The PatchData method is used to submit XML or JSON formatted
patch data to a service, and then returns a copy of the response from
the server into a local string buffer. This method will not perform any
encoding and will not automatically define the type of patch data being
submitted. Your application is responsible for specifying the content
type for the patch data, and ensuring that the XML or JSON data that is
being submitted to the server is formatted correctly.
This method sends a PATCH command to the server, which is similar
to a POST or PUT request. It is used to make partial updates to a
resource, rather than creating or replacing it entirely. The format of
the patch data is specific to the service being used. If the resource
being patched does not exist, the behavior is defined by the server.
If enough information is provided, it may choose to create the
resource just as if a PUT command was used, or it may return an error.
Your application should use the SetHeader method to
define the Content-Type header prior to calling the PatchData
method. One of the most common formats used is the JSON Merge Patch
which is defined in RFC 7396. The value for the Content-Type header
for this patch format is "application/merge-patch+json". Refer to your
service API documentation to determine what patch formats are
acceptable, along with any additional header values that must be
defined.
When encountering a server error during a request, the PatchData
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 PATCH 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
httpPatchErrorData option. When this option is enabled, the
behavior of PatchData 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.