CHttpClient::PostData Method  
 
INT PostData(
  LPCTSTR lpszResource,  
  LPBYTE lpBuffer,  
  DWORD cbBuffer,  
  LPBYTE lpResult,  
  LPDWORD lpcbResult,  
  DWORD dwOptions  
);
INT PostData(
  LPCTSTR lpszResource,  
  LPBYTE lpBuffer,  
  DWORD cbBuffer,  
  HGLOBAL *lpResult,  
  LPDWORD lpcbResult,  
  DWORD dwOptions  
);
INT PostData(
  LPCTSTR lpszResource,  
  LPCTSTR lpszBuffer,  
  CString& strResult,  
  DWORD dwOptions  
);

The PostData method submits the contents of the specified buffer to a script on the server and returns the result in a buffer provided by the caller.

Parameters

lpszResource
A pointer to a string that specifies the resource that the data will be posted to on the server. Typically this is the name of an executable script. This string may specify a valid URL for the current server that the client is connected to.
lpBuffer
A pointer to the data that will be provided to the script. This parameter may be NULL if the script does not require any additional data from the client. In an alternate form of the method, this may point to a string which contains the data to be posted.
cbBuffer
The number of bytes to copy from the buffer. If the lpBuffer parameter is NULL, this value should be zero.
lpResult
A pointer to a byte buffer which will contain the data returned by the server, or a pointer to a global memory handle which will reference the data when the method returns. An alternate version of this method accepts a CString object which will contain the server response.
lpcbResult
A pointer to an unsigned integer which should be initialized to the maximum number of bytes that can be copied to the buffer specified by the lpvBuffer parameter. If the lpvResult parameter points to a global memory handle, the length value should be initialized to zero. When the method returns, this value will be updated with the number of bytes of data returned by the server.
dwOptions
An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:
Value Description
HTTP_POST_DEFAULT The default post mode. The contents of the buffer are encoded and sent as standard form data. The data returned by the server is copied to the result buffer exactly as it is returned from the server.
HTTP_POST_CONVERT If the data being returned from the server is textual, it is automatically converted so that the end of line character sequence is compatible with the Windows platform. Individual carriage return or linefeed characters are converted to carriage return/linefeed character sequences. Note that this option does not have any effect on the form data being submitted to the server, only on the data returned by the server.
HTTP_POST_MULTIPART The contents of the buffer being sent to the server consists of multipart form data and will be sent as-is without any encoding.
HTTP_POST_ERRORDATA This option causes the client to accept error data from the server if the request fails. If this option is specified, an error response from the server will not cause the method to fail. Instead, the response is returned to the client and the method will succeed.

Return Value

If the method succeeds, the return value is the server result code. If the method fails, the return value is HTTP_ERROR. To get extended error information, call GetLastError.

Remarks

The PostData method 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 formatted data to the server, it is recommended that you use the PostXml method to ensure that the correct content type and encoding is automatically selected.

The method 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 method 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 method 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 method may have a value of zero when the method returns, indicating no data has been returned to the caller.

When encountering a server error during a request, the PostData method 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 PostData 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 GetResultCode 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 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 EnableEvents, or by registering a callback function using the RegisterEvent method.

To determine the current status of a file transfer while it is in progress, use the GetTransferStatus method.

Example

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 = lpClient->PostData(lpszResource,
                             lpParameters,
                             cbParameters,
                             &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);
}

Requirements

Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cshtpv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

GetData, GetTransferStatus, PostJson, PostXml, PutData, SubmitRequest

 
 

Copyright © 2025 Catalyst Development Corporation. All rights reserved.