The HttpPostData function is used to submit data to a
script that executes on the server and then copy the output from that
script into a local buffer. If you are submitting XML or JSON formatted data
to the server, it is recommended that you use the HttpPostXml
or HttpPostJson
functions instead to ensure that the correct content type and encoding
is automatically selected.
The function may be used in one of two ways, depending on the
needs of the application. The first method is to pre-allocate a
buffer large enough to store the resulting output of the script. In
this case, the lpvResult parameter will point to the buffer
that was allocated by the client and the value that the
lpcbResult parameter points to should be initialized to the
size of that buffer.
The second method that can be used is have the lpvResult
parameter point to a global memory handle which will contain the data
when the function returns. In this case, the value that the
lpcbResult parameter points to must be initialized to zero. It
is important to note that the memory handle returned by the function
must be freed by the application, otherwise a memory leak will occur.
See the example code below.
It is important for your application to initialize the value of the
lpcbResult parameter correctly. This parameter must be passed
by reference and if it is not initialized properly it can cause
unexpected behavior or corrupt the process heap. If an error occurs
when issuing the POST request to the server, the variable passed to
this function may have a value of zero when the function returns,
indicating no data has been returned to the caller.
When encountering a server error during a request, the
HttpPostData function normally returns HTTP_ERROR, and no data is
copied into the caller-provided buffer. The last error code for the
current thread is updated to reflect 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
HTTP_POST_ERRORDATA option. When this option is enabled, the
behavior of HttpPostData changes; it does not return HTTP_ERROR
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 call HttpGetResultCode to obtain the HTTP status code
returned by the server. This will enable you to determine if the
operation was successful.
This function will cause the current thread to block until the
post completes, a timeout occurs or the operation is canceled. During
the transfer, the HTTP_EVENT_PROGRESS event will be periodically
fired, enabling the application to update any user interface
controls. Event notification can be enabled by registering a callback
function using the HttpRegisterEvent function.
To determine the current status of the transaction while it is in
progress, use the HttpGetTransferStatus function.
HGLOBAL hgblBuffer = (HGLOBAL)NULL;
LPBYTE lpBuffer = (LPBYTE)NULL;
DWORD cbBuffer = 0;
nResult = HttpPostData(hClient,
lpszResource,
lpParameters,
cbParameters,
&hgblBuffer,
&cbBuffer,
HTTP_POST_CONVERT);
if (nResult != HTTP_ERROR)
{
lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
GlobalUnlock(hgblBuffer);
GlobalFree(hgblBuffer);
}