The HttpPostJson function is used to submit JSON 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
JSON data to a server, however it does not parse the JSON data itself
to ensure that it is well-formed. Your application is responsible for
ensuring that the JSON data that is being submitted to the server is
formatted correctly.
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.
If the content type for the request has not been explicitly
specified, it will be automatically updated by this function to use
the "application/json" content type. You can override the
default content type for the request by calling the
HttpSetRequestHeader function prior to calling this
function. Most servers require you to explicitly specify what type of
data is being submitted by the client and will reject requests which
do not correctly identify the content type.
It is common for servers to return additional information about a
failed request in their response to the client. If you need to process
this information, use the HTTP_POST_ERRORDATA option which causes the
error message to be returned in the lpvResult 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 must be enabled, either by calling
HttpEnableEvents, or 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;
// Store the script output into block of global memory allocated by
// the GlobalAlloc function; the handle to this memory will be
// returned in the hgblBuffer parameter. Since the output from the
// script is textual, the HTTP_POST_CONVERT option is used
nResult = HttpPostJson(hClient,
lpszResource,
lpszJsonData,
&hgblBuffer,
&cbBuffer,
HTTP_POST_CONVERT);
if (nResult != HTTP_ERROR)
{
// Lock the global memory handle, returning a pointer to the
// output data from the script
lpBuffer = (LPBYTE)GlobalLock(hgblBuffer);
// After the data has been used, the handle must be unlocked
// and freed, otherwise a memory leak will occur
GlobalUnlock(hgblBuffer);
GlobalFree(hgblBuffer);
}