TP 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:

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.

See also HttpOpenRequest, HttpSendRequest

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.

See also HttpAddRequestHeaders, HttpQueryInfo, HttpSendRequest, InternetCloseHandle, InternetConnect, InternetOpen, InternetReadFile

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

HTTP_QUERY_CUSTOM

HTTP_QUERY_FLAG_COALESCE

This flag is required to set the type of the data returned by HttpQueryInfo to a DWORD.

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.

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

HTTP_QUERY_FLAG_SYSTEMTIME

HTTP_QUERY_FLAG_NUMBER

lpvBuffer

also query request headers by using this flag.

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.

For those headers whose value is a number, such as the status code, specifying this flag returns the data as a 32-bit number.

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_ENCODI NG

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.

See also HttpOpenRequest, HttpQueryInfo, InternetReadFile