CHttpClient::SubmitRequest Method  
 
INT SubmitRequest(
  DWORD dwRequestType,  
  LPCTSTR lpszResource,  
  LPHTTPCONNECTION lpConnection,  
  LPCVOID lpvRequest,  
  DWORD dwRequestLength,  
  LPVOID lpvResponse,  
  LPDWORD lpdwResponseLength  
);

The SubmitRequest method provides a high-level interface for submitting requests to a web service.

Parameters

dwRequestType
An unsigned integer which specifies the type of request being submitted to the server. It may be one of the following values:
Value Description
HTTP_METHOD_DEFAULT Perform a default request action based on the value of parameters passed to this method. If there is no request payload, the action will default to HTTP_METHOD_GET, otherwise it will default to HTTP_METHOD_POST. It is generally recommended that you explicitly specify the request method; however, this default value can be useful if your application does not know if a payload will be included with the request at the time the method is called.
HTTP_METHOD_GET Use the GET method when submitting the request to the server. If this action is used, the lpvRequest and dwRequestLength parameters will be ignored. The buffer specified by the lpvResponse parameter will contain the server's response to the request.
HTTP_METHOD_POST Use the POST method when submitting the request to the server. The payload specified by the lpvRequest parameter will be included with the request and the buffer specified by the lpvResponse parameter will contain the server's response to the request.
HTTP_METHOD_PUT Use the PUT method when submitting the request to the server. The payload specified by the lpvRequest parameter will be included with the request. This method is typically used with persistent storage on the server, such as uploading the contents of a file. If the lpvResponse parameter is not NULL, it will contain any response from the server after the operation has completed.
lpszResource
A pointer to a null-terminated string which specifies the complete URL for the resource. Both standard and secure connections are supported, and query parameters may be included with the URL. This parameter cannot be NULL and must specify an absolute (fully qualified) URI which begins with either http:// or https://.
lpConnection
A pointer to a HTTPCONNECTION structure which contains additional information about the client connection. This structure is required if your application must connect through a proxy server or when authentication is required to access a resource. This parameter can be NULL, in which case default values will be used when establishing the connection.
lpvRequest
A pointer to a buffer which contains the payload data submitted to the server as part of the request. This parameter may point to a byte buffer or a null-terminated string. If there is no payload required for the request this parameter may be NULL. If the Unicode version of this method is called and the request buffer contains text, it will be automatically converted to UTF-8 prior to submitting the data to the server. If the dwRequestLength parameter is -1, the payload will always be processed as a null-terminated string and the method will fail if the buffer does not contain text characters.
dwRequestLength
An unsigned integer which specifies the size of the request payload. If the payload contains text, this should specify the number of characters in the buffer. If the payload contains binary data, this value should specify the number of bytes in the buffer. If the lpvRequest parameter points to a null-terminated string, this value can be -1 and the length of the payload will be determined automatically. If the Unicode version of this method is called and the length is -1, the request payload will be UTF-8 encoded prior to being submitted to the server.
lpvResponse
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. This parameter may be NULL if the response data is not required. If this parameter is NULL, the lpdwResponseLength parameter must also be NULL. If a response buffer is provided, the data will always be returned as a byte stream, even when the Unicode version of this method is called. If the server returns a text payload, it will typically be UTF-8 encoded and the application can convert the text to Unicode using the MultiByteToWideChar method.
lpdwResponseLength
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 lpvResponse parameter. If the lpvResponse 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 actual number of bytes of data that was returned. If the lpvResponse parameter is not NULL, this parameter cannot be NULL.

Return Value

If the method succeeds, the return value is the server status code. If the method fails, the return value is HTTP_ERROR. To get extended error information, call the GetLastError method. The application should always check the return value to determine if the request was successful. If the server returns a 4xx or 5xx status code, this indicates the request was not accepted and the response buffer will typically contain information about the cause of the failure.

Remarks

The SubmitRequest method provides a single high-level interface for submitting requests to a web server and returning the server's response. This method is entirely self-contained and does not require a client session handle. The current thread will block until the method returns and will not generate event notifications. If you need to download a large file from a web server and want progress updates, it is recommended you use the DownloadFile method.

If the service you are using requires authentication, you will need to allocate a HTTPCONNECTION structure and set the appropriate member values to specify the authentication method and user credentials. This structure also allows you to provide additional information, such as additional request header values, a custom timeout period and additional connection options.

When the lpvRequest parameter is not NULL, the contents of the buffer will be examined to determine if it contains text or binary data. If the dwRequestLength parameter is -1, the lpvRequest parameter is always considered to be a pointer a null-terminated string, with the length calculated by counting the number of characters up to the terminating null character. If the request payload is text, the method will also attempt to determine if the payload looks like XML or JSON and will automatically set the appropriate content type. The application can explicitly provide a MIME content type by setting the lpszContentType member of the HTTPCONNECTION structure.

Example

// Submit an XML payload to the server and return the response in a global
// memory buffer allocated by the method
LPCTSTR lpszResource = _T("https://www.example.com/postxml"); 
LPCTSTR lpszRequest = _T("<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n") \
                      _T("<test>\r\n") \
                      _T("  <data param=\"A\">Value1</data>\r\n") \
                      _T("  <data param=\"B\">Value2</data>\r\n") \
                      _T("</test>\r\n");

// Provide additional connection information which includes user credentials
// and a custom header which includes an API token for the service; note that
// we need to initialize the dwSize member of the structure
HTTPCONNECTION httpConnection = { 0, };
httpConnection.dwSize = sizeof(httpConnection);
httpConnection.nAuthType = HTTP_AUTH_BASIC;
httpConnection.lpszUserName = _T("userid");
httpConnection.lpszPassword = _T("secret");
httpConnection.lpszContentType = _T("application/xml");
httpConnection.lpszHeaders = _T("X-API-Token: 99d2fe39-0246-4efa-98e0-4d775579fa5d");

// Declare the global memory handle which will contain the server response
// and initialize the length to 0, which tells the API that a HGLOBAL handle
// is being used rather than a pointer to a pre-allocated buffer
CHttpClient httpClient;
HGLOBAL hgblResponse = NULL;
DWORD dwLength = 0;

INT nResult = httpClient.SubmitRequest(
    HTTP_METHOD_POST,
    lpszResource,
    &httpConnection,
    lpszRequest,
    (DWORD)-1,
    &hgblResponse,
    &dwLength);

if (nResult != HTTP_ERROR && hgblResponse != NULL)
{
    LPBYTE lpBuffer = (LPBYTE)GlobalLock(hgblResponse);

    // The lpBuffer variable points to the data returned by the server and
    // the application is responsible for freeing the global memory handle

    GlobalUnlock(hgblResponse);
    GlobalFree(hgblResponse);
}

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

DownloadFile, GetData, PostData, PostJson, PostXml, UploadFile, HTTPCONNECTION

 
 

Copyright © 2025 Catalyst Development Corporation. All rights reserved.