The PostXml method is used to submit XML formatted data to
a script that executes on the server and then copy the output from
that script into a local buffer. This function automatically sets the
correct content type and encoding required for submitting XML data to
a server, however it does not parse the XML data itself to ensure
that it is well-formed. Your application is responsible for ensuring
that the XML data that is being submitted to the server is formatted
correctly.
When encountering a server error during a request, the PostXml
method normally returns an error code, and no data is copied into
the caller-provided buffer. The error code reflects the general cause
of the failure, allowing the application to handle this error condition
appropriately. If the POST request fails, servers may also provide
further details about the failure, such as XML or JSON formatted data
containing specific error codes or diagnostic messages.
To capture this error information, you can utilize the
httpPostErrorData option. When this option is enabled, the
behavior of PostXml changes; it does not return an error code
for server error statuses. Instead, any error data provided in the
server's response, regardless of its format, is copied into the result
buffer provided by the caller. If this option is used, your application
should check the value of the ResultCode property to obtain
the HTTP status code returned by the server. This will enable you
to determine if the operation was successful.
This method will cause the current thread to block until the
operation completes, a timeout occurs or the post is canceled. During
the operation, the OnProgress event will fire periodically,
enabling the application to update any user interface objects such as
a progress bar.