
The HTTP functions described in this section control the transmission and content of HTTP requests.
BOOL HttpAddRequestHeaders(
IN HINTERNET hHttpRequest,
IN LPCSTR 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 the following values:
- HTTP_ADDREQ_FLAG_ADD
- Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.
- HTTP_ADDREQ_FLAG_ADD_IF_NEW
- Adds the header only if it does not already exist; otherwise, an error is returned.
- HTTP_ADDREQ_FLAG_COALESCE
- Coalesces headers of the same name.
- 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
- Coalesces headers of the same name using a semicolon.
- 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.
HttpAddRequestHeaders 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 HttpSendRequest
HttpEndRequest(
IN HINTERNET hRequest,
OUT LPINTERNET_BUFFERS lpBuffersOut,
IN DWORD dwFlags,
IN DWORD dwContext
);
Ends an HTTP request.
- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
- hRequest
- HINTERNET handle returned by HttpOpenRequest and sent by HttpSendRequestEx.
- lpBuffersOut
- Address of an INTERNET_BUFFERS structure.
- dwFlags
- Can be one of the following values:
- dwContext
- Double-word variable that contains the context value to use in asynchronous operations.
HINTERNET HttpOpenRequest(
IN HINTERNET hHttpSession,
IN LPCSTR lpszVerb,
IN LPCSTR lpszObjectName,
IN LPCSTR lpszVersion,
IN LPCSTR lpszReferer,
IN LPCSTR FAR * lpszAcceptTypes,
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 LPCSTR 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. Can be any of the following values:
- INTERNET_FLAG_CACHE_IF_NET_FAIL
- Return the resource from the cache if the network request for the resource fails due to an ERROR_INTERNET_CONNECTION_RESET or ERROR_INTERNET_CANNOT_CONNECT.
- INTERNET_FLAG_DONT_CACHE
- Does not add the returned entity to the cache. Identical to the preferred value, INTERNET_FLAG_NO_CACHE_WRITE.
- INTERNET_FLAG_HYPERLINK
- Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network.
- INTERNET_FLAG_IGNORE_CERT_CN_INVALID
- Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules.
- INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
- Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates.
- INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
- Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs.
- INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
- Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs.
- INTERNET_FLAG_KEEP_CONNECTION
- Uses keep-alive semantics, if available, for the connection. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication.
- INTERNET_FLAG_MAKE_PERSISTENT
- No longer supported.
- INTERNET_FLAG_MUST_CACHE_REQUEST
- Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value, INTERNET_FLAG_NEED_FILE.
- INTERNET_FLAG_NEED_FILE
- Causes a temporary file to be created if the file cannot be cached.
- INTERNET_FLAG_NO_AUTH
- Does not attempt authentication automatically.
- INTERNET_FLAG_NO_AUTO_REDIRECT
- Does not automatically handle redirection in HttpSendRequest.
- INTERNET_FLAG_NO_CACHE_WRITE
- Does not add the returned entity to the cache.
- INTERNET_FLAG_NO_COOKIES
- Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database.
- INTERNET_FLAG_NO_UI
- Disables the cookie dialog box.
- INTERNET_FLAG_PRAGMA_NOCACHE
- Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
- INTERNET_FLAG_READ_PREFETCH
- This flag is currently disabled.
- INTERNET_FLAG_RELOAD
- Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
- INTERNET_FLAG_RESYNCHRONIZE
- Reloads HTTP resources if the resource has been modified since the last time it was downloaded.
- INTERNET_FLAG_SECURE
- Uses SSL/PCT transaction semantics.
- dwContext
- Application-defined value that associates this operation with any application data.
HttpOpenRequest 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, InternetReadFile
BOOL HttpQueryInfo(
IN HINTERNET hHttpRequest,
IN DWORD dwInfoLevel,
IN LPVOID lpvBuffer,
IN LPDWORD lpdwBufferLength,
IN OUT LPDWORD lpdwIndex,
);
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 or InternetOpenUrl.
- dwInfoLevel
- Combination of the attribute to query and the flags that modify the request. The attributes can be any of the following values:
- HTTP_QUERY_ACCEPT
- Retrieves the acceptable media types for the response.
- HTTP_QUERY_ACCEPT_CHARSET
- Retrieves the acceptable character sets for the response.
- HTTP_QUERY_ACCEPT_ENCODING
- Retrieves the acceptable content-coding values for the response.
- HTTP_QUERY_ACCEPT_LANGUAGE
- Retrieves the acceptable natural languages for the response.
- HTTP_QUERY_ACCEPT_RANGES
- Retrieves the types of range requests that are accepted for a resource.
- HTTP_QUERY_AGE
- Retrieves the Age response-header field, which contains the sender's estimate of the amount of time since the response was generated at the origin server.
- HTTP_QUERY_ALLOW
- Receives the methods supported by the server.
- HTTP_QUERY_AUTHORIZATION
- Retrieves the authorization credentials used for a request.
- HTTP_QUERY_CACHE_CONTROL
- Retrieves the cache control directives.
- HTTP_QUERY_CONNECTION
- Retrieves any options that are specified for a particular connection and must not be communicated by proxies over further connections.
- HTTP_QUERY_COOKIE
- Retrieves any cookies associated with the request.
- HTTP_QUERY_CONTENT_BASE
- Retrieves the base URI for resolving relative URLs within the entity.
- HTTP_QUERY_CONTENT_DESCRIPTION
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_CONTENT_DISPOSITION
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_CONTENT_ENCODING
- Receives any additional content codings that have been applied to the entire resource.
- HTTP_QUERY_CONTENT_ID
- Receives the content identification.
- HTTP_QUERY_CONTENT_LANGUAGE
- Receives the language that the content is in.
- HTTP_QUERY_CONTENT_LENGTH
- Receives the size of the resource, in bytes.
- HTTP_QUERY_CONTENT_LOCATION
- Retrieves the resource location for the entity enclosed in the message.
- HTTP_QUERY_CONTENT_MD5
- Retrieves a MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) for the entity-body. For more information, see RFC1864, The Content-MD5 Header Field, at http://ds.internic.net/rfc/rfc1864.txt
for more information.
- HTTP_QUERY_CONTENT_RANGE
- Retrieves the location in the full entity-body where the partial entity-body should be inserted and the total size of the full entity-body.
- HTTP_QUERY_CONTENT_TRANSFER_ENCODING
- Receives the additional content coding that has been applied to the resource.
- HTTP_QUERY_CONTENT_TYPE
- Receives the content type of the resource (such as text/html).
- HTTP_QUERY_COST
- No longer implemented.
- HTTP_QUERY_DATE
- Receives the date and time at which the message was originated.
- HTTP_QUERY_DERIVED_FROM
- No longer supported.
- HTTP_QUERY_ETAG
- Retrieves the entity tag for the associated entity.
- HTTP_QUERY_EXPIRES
- Receives the date and time after which the resource should be considered outdated.
- HTTP_QUERY_FORWARDED
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_FROM
- Retrieves the e-mail address for the human user who controls the requesting user agent if the From header is given.
- HTTP_QUERY_HOST
- Retrieves the Internet host and port number of the resource being requested.
- HTTP_QUERY_IF_MATCH
- Retrieves the contents of the If-Match request-header field.
- HTTP_QUERY_IF_MODIFIED_SINCE
- Retrieves the contents of the If-Modified-Since header.
- HTTP_QUERY_IF_NONE_MATCH
- Retrieves the contents of the If-None-Match request-header field.
- HTTP_QUERY_IF_RANGE
- Retrieves the contents of the If-Range request-header field. This header allows the client application to check if the entity related to a partial copy of the entity in the client application's cache has not been updated. If the entity has not been updated, send the parts that the client application is missing. If the entity has been updated, send the entire updated entity.
- HTTP_QUERY_IF_UNMODIFIED_SINCE
- Retrieves the contents of the If-Unmodified-Since request-header field.
- HTTP_QUERY_LINK
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_LAST_MODIFIED
- Receives the date and time at which the server believes the resource was last modified.
- HTTP_QUERY_LOCATION
- Retrieves the absolute URI used in a Location response-header.
- HTTP_QUERY_MAX
- Retrieves the maximum value of an HTTP_QUERY_* value.
- HTTP_QUERY_MAX_FORWARDS
- Retrieves the number of proxies or gateways that can forward the request to the next inbound server.
- HTTP_QUERY_MESSAGE_ID
- No longer implemented.
- HTTP_QUERY_MIME_VERSION
- Receives the version of the MIME protocol that was used to construct the message.
- HTTP_QUERY_ORIG_URI
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_PRAGMA
- Receives the implementation-specific directives that may apply to any recipient along the request/response chain.
- HTTP_QUERY_PROXY_AUTHENTICATE
- Retrieves the authentication scheme and realm returned by the proxy.
- HTTP_QUERY_PROXY_AUTHORIZATION
- Retrieves the header that is used to identify the user to a proxy that requires authentication.
- HTTP_QUERY_PUBLIC
- Receives methods available at this server.
- HTTP_QUERY_RANGE
- Retrieves the byte range of an entity.
- HTTP_QUERY_RAW_HEADERS
- Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.
- HTTP_QUERY_RAW_HEADERS_CRLF
- Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.
- HTTP_QUERY_REFERER
- Receives the URI of the resource where the requested URI was obtained.
- HTTP_QUERY_REFRESH
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_REQUEST_METHOD
- Receives the verb that is being used in the request, typically GET or POST.
- HTTP_QUERY_RETRY_AFTER
- Retrieves the amount of time the service is expected to be unavailable.
- HTTP_QUERY_SERVER
- Retrieves information about the software used by the origin server to handle the request.
- HTTP_QUERY_SET_COOKIE
- Receives the value of the cookie set for the request.
- HTTP_QUERY_STATUS_CODE
- Receives the status code returned by the server. For a list of possible values, see HTTP Status Codes.
- HTTP_QUERY_STATUS_TEXT
- Receives any additional text returned by the server on the response line.
- HTTP_QUERY_TITLE
- Obsolete. Maintained for legacy application compatibility only.
- HTTP_QUERY_TRANSFER_ENCODING
- Retrieves the type of transformation that has been applied to the message body so it can be safely transferred between the sender and recipient.
- HTTP_QUERY_UPGRADE
- Retrieves the additional communication protocols that are supported by the server.
- HTTP_QUERY_URI
- Receives some or all of the Uniform Resource Identifiers (URIs) by which the Request-URI resource can be identified.
- HTTP_QUERY_USER_AGENT
- Retrieves information about the user agent that made the request.
- HTTP_QUERY_VARY
- Retrieves the header that indicates that the entity was selected from a number of available representations of the response using server-driven negotiation.
- HTTP_QUERY_VERSION
- Receives the last response code returned by the server.
- HTTP_QUERY_VIA
- Retrieves the intermediate protocols and recipients between the user agent and the server on requests, and between the origin server and the client on responses.
- HTTP_QUERY_WARNING
- Retrieves additional information about the status of a response that may not be reflected by the response status code.
- HTTP_QUERY_WWW_AUTHENTICATE
- Retrieves the authentication scheme and realm returned by the server.
The following modifiers can be used with the information values:
- HTTP_QUERY_CUSTOM
- Causes HttpQueryInfo to search for the header name specified in lpvBuffer and store the header information in lpvBuffer.
- HTTP_QUERY_FLAG_COALESCE
- Combines the values from headers with the same name into the output buffer.
- HTTP_QUERY_FLAG_NUMBER
- Returns the data as a 32-bit number for headers whose value is a number, such as the status code.
- HTTP_QUERY_FLAG_REQUEST_HEADERS
- Queries request headers only.
- HTTP_QUERY_FLAG_SYSTEMTIME
- Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".
- 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 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.
HttpQueryInfo 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
BOOL HttpSendRequest(
IN HINTERNET hHttpRequest,
IN LPCSTR lpszHeaders,
IN DWORD dwHeadersLength,
IN LPVOID lpOptional,
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 parameter is generally used for POST and PUT operations. The optional data can be the resource or information being posted to the server. 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.
HttpSendRequest sends the specified request to the HTTP server and allows the client to specify additional 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 InternetReadFile
BOOL HttpSendRequestEx(
IN HINTERNET hRequest,
IN LPINTERNET_BUFFERS lpBuffersIn,
OUT LPINTERNET_BUFFERS lpBuffersOut,
IN DWORD dwFlags,
IN DWORD dwContext
);
Sends the specified request to the HTTP server.
- Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError.
- hRequest
- HINTERNET handle returned by HttpOpenRequest.
- lpBuffersIn
- Optional. Address of an INTERNET_BUFFERS structure.
- lpBuffersOut
- Optional. Address of an INTERNET_BUFFERS structure.
- dwFlags
- Can be one of the following values:
- dwContext
- DWORD variable that contains the context value to use in asynchronous operations.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.