## 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:
  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
    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)

See also HttpOpenRequest

### 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

© 1996 Microsoft Corporation