HTTP Functions

The HTTP functions control the transmission and content of HTTP requests.

HttpAddRequestHeaders

BOOL HttpAddRequestHeaders(
    IN HINTERNET hHttpRequest,
    IN LPCTSTR lpszHeaders,
    IN DWORD dwHeadersLength,
    IN DWORD dwModifiers
);

Adds one or more HTTP request headers to the HTTP request handle.

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hHttpRequest

Open HTTP request handle returned by HttpOpenRequest.

lpszHeaders

Headers to append to the request. Each header must be terminated by a CR/LF (carriage return/line feed) pair.

dwHeadersLength

Length, in characters, of lpszHeaders. If this parameter is -1L, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is computed.

dwModifiers

Values used to modify the semantics of this function. Can be a combination of these values:

Modifier: Meaning
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA: Coalesces headers of the same name. For example, adding "Accept: text/*" followed by "Accept: audio/*" with this flag results in the formation of the single header "Accept: text/*, audio/*". This causes the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON: Coaleses headers of the same name using a semicolon.
HTTP_ADDREQ_FLAG_COALESCE: Coaleses headers of the same name.
HTTP_ADDREQ_FLAG_REPLACE: Replaces or removes a header. If the header value is empty and the header is found, it is removed. If not empty, the header value is replaced.
HTTP_ADDREQ_FLAG_ADD: Adds the header if it does not exist. Used with REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW: Adds the header only if it does not already exist; otherwise, an error is returned.

This function appends additional, free-format headers to the HTTP request handle and is intended for use by sophisticated clients that need detailed control over the exact request sent to the HTTP server.

Note that for basic HttpAddRequestHeaders, the application can pass in multiple headers in a single buffer. If the application is trying to remove or replace a header, only one header can be supplied in lpszHeaders.

HttpOpenRequest

HINTERNET HttpOpenRequest(
    IN HINTERNET hHttpSession,
    IN LPCTSTR lpszVerb,
    IN LPCTSTR lpszObjectName,
    IN LPCTSTR lpszVersion,
    IN LPCTSTR lpszReferer OPTIONAL,
    IN LPCTSTR FAR * lpszAcceptTypes OPTIONAL,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Opens an HTTP request handle.

Returns a valid (non-NULL) HTTP request handle if successful, or NULL otherwise. To get extended error information, call GetLastError.

hHttpSession: Handle to an HTTP session returned by InternetConnect.
lpszVerb: Address of a string that contains the verb to use in the request. If this parameter is NULL, the function uses "GET" as the verb.
lpszObjectName: Address of a string that contains the name of the target object of the specified verb. This is generally a file name, an executable module, or a search specifier.
lpszVersion: Address of a string that contains the HTTP version. If this parameter is NULL, the function uses "HTTP/1.0" as the version.
lpszReferer: Address of a string that specifies the address (URL) of the document from which the URL in the request (lpszObjectName) was obtained. If this parameter is NULL, no "referrer" is specified.
lpszAcceptTypes: Address of a null-terminated array of LPCTSTR pointers indicating content types accepted by the client. If this parameter is NULL, no types are accepted by the client. Servers interpret a lack of accept types to indicate that the client accepts only documents of type "text/*" (that is, only text documents and not pictures or other binary files).
dwFlags: Internet flag values. For a list of valid flag values, see InternetOpenUrl.
dwContext: An application-defined value that associates this operation with any application data.

This function creates a new HTTP request handle and stores the specified parameters in that handle. An HTTP request handle holds a request to be sent to an HTTP server and contains all RFC822/MIME/HTTP headers to be sent as part of the request.

Use the InternetCloseHandle function to close the handle returned by HttpOpenRequest. InternetCloseHandle cancels all outstanding I/O on the handle.

The lpszReferer parameter to InternetOpen is used as the referrer for the HTTP request.

HttpQueryInfo

BOOL HttpQueryInfo(
    IN HINTERNET hHttpRequest,
    IN DWORD dwInfoLevel,
    IN LPVOID lpvBuffer OPTIONAL,
    IN LPDWORD lpdwBufferLength,
    IN OUT LPDWORD lpdwIndex OPTIONAL,
);

Queries for information about an HTTP request.

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hHttpRequest

Open HTTP request handle returned by HttpOpenRequest.

dwInfoLevel

Combination of the attribute to query and the flags that modify the request. The following flags can be used to modify a request:

HTTP_QUERY_INFO_NUMBER: This flag is required to set the type of the data returned by HttpQueryInfo to a DWORD.
HTTP_QUERY_CUSTOM: If this query level is specified, lpvBuffer contains an ASCIIZ header name. This header name is searched for and its value returned in lpvBuffer on output.
HTTP_QUERY_FLAG_COALESCE: Combine the values from several headers of the same name into the output buffer.
HTTP_QUERY_FLAG_REQUEST_HEADERS: Typically, response headers are queried, but an application can also query request headers by using this flag.
HTTP_QUERY_FLAG_SYSTEMTIME: For those headers whose value is a date/time string, such as "Last-Modified-Time", specifying this flag returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data.
HTTP_QUERY_FLAG_NUMBER: For those headers whose value is a number, such as the status code, specifying this flag returns the data as a 32-bit number.

lpvBuffer

Address of the buffer that receives the information.

lpdwBufferLength

Address of a value that contains the length of the data buffer. When the function returns, this parameter contains the address of a value specifying the length of the information written to the buffer. When the function returns strings, the following rules apply:

If the function succeeds, lpdwBufferLength specifies the length of the string, in characters, minus 1 for the terminating null.
If the function fails and ERROR_INSUFFICIENT_BUFFER is returned, lpdwBufferLength specifies the number of bytes that the application must allocate in order to receive the string.

lpdwIndex

Address of a zero-based header index used to enumerate multiple headers with the same name. When calling the function, this parameter is the index of the specified header to return. When the function returns, this parameter is the index of the next header. If the next index cannot be found, ERROR_HTTP_HEADER_NOT_FOUND is returned.

The possible values for the dwInfoLevel parameter include:

HTTP_QUERY_MIME_VERSION
HTTP_QUERY_CONTENT_TYPE
HTTP_QUERY_CONTENT_TRANSFER_ENCODING
HTTP_QUERY_CONTENT_ID
HTTP_QUERY_CONTENT_DESCRIPTION
HTTP_QUERY_CONTENT_LENGTH
HTTP_QUERY_ALLOW
HTTP_QUERY_PUBLIC
HTTP_QUERY_DATE
HTTP_QUERY_EXPIRES
HTTP_QUERY_LAST_MODIFIED
HTTP_QUERY_MESSAGE_ID
HTTP_QUERY_URI
HTTP_QUERY_DERIVED_FROM
HTTP_QUERY_LANGUAGE
HTTP_QUERY_COST
HTTP_QUERY_WWW_LINK
HTTP_QUERY_PRAGMA
HTTP_QUERY_VERSION
HTTP_QUERY_STATUS_CODE
HTTP_QUERY_STATUS_TEXT
HTTP_QUERY_RAW_HEADERS
HTTP_QUERY_RAW_HEADERS_CRLF
HTTP_QUERY_REQUEST_METHOD

In HTTP_QUERY_REQUEST_METHOD, the lpvBuffer parameter receives the verb that is being used in the request, typically "GET" or "POST".

This function is used to return response or request headers from an HTTP request. You can retrieve different types of data from HttpQueryInfo:

strings (default)
SYSTEMTIME (for Data: Expires:, headers)
DWORD (for STATUS_CODE, CONTENT_LENGTH, and so on if HTTP_QUERY_INFO_NUMBER has been used.)

HttpSendRequest

BOOL HttpSendRequest(
    IN HINTERNET hHttpRequest,
    IN LPCTSTR lpszHeaders OPTIONAL,
    IN DWORD dwHeadersLength,
    IN LPVOID lpOptional OPTIONAL,
    DWORD dwOptionalLength
);

Sends the specified request to the HTTP server.

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.

hHttpRequest: Open HTTP request handle returned by HttpOpenRequest.
lpszHeaders: Additional headers to be appended to the request. This parameter can be NULL if there are no additional headers to append.
dwHeadersLength: Length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, the function assumes that lpszHeaders is zero-terminated (ASCIIZ), and the length is calculated.
lpOptional: Address of any optional data to send immediately after the request headers. This is generally used for POST and PUT operations. This parameter can be NULL if there is no optional data to send.
dwOptionalLength: Length, in bytes, of the optional data. This parameter can be zero if there is no optional data to send.

This function sends the specified request to the HTTP server and allows the client to specify additional RFC822/MIME/HTTP headers to send along with the request.

The function also lets the client specify optional data to send to the HTTP server immediately following the request headers. This feature is generally used for "write" operations such as PUT and POST.

After the request is sent, the status code and response headers from the HTTP server are read. These headers are maintained internally and are available to client applications through the HttpQueryInfo function.

An application can use the same HTTP request handle in multiple calls to HttpSendRequest, but the application must read all data returned from the previous call before calling the function again.