WinHttpOpenRequest

 

Description

 

The WinHttpOpenRequest function creates an HTTP request handle.

 

C/C++ Syntax

 

HINTERNET WinHttpOpenRequest(

HINTERNET hConnect,

LPCWSTR pwszVerb,

LPCWSTR pwszObjectName,

LPCWSTR pwszVersion,

LPCWSTR pwszReferrer,

LPCWSTR* ppwszAcceptTypes,

DWORD dwFlags

);

 

PowerBASIC Syntax

 

FUNCTION WinHttpOpenRequest ( _

BYVAL hConnect AS DWORD, _

BYVAL pwszVerb AS DWORD, _

BYVAL pwszObjectName AS DWORD, _

BYVAL pwszVersion AS DWORD, _

BYVAL pwszReferrer AS DWORD, _

BYREF ppwszAcceptTypes AS DWORD, _

BYVAL dwFlags AS DWORD _

) AS DWORD

 

Parameters

 

hConnect

 

[in] HINTERNET connection handle to an HTTP session returned by WinHttpConnect.

 

pwszVerb

 

[in] Pointer to a null-terminated Unicode string that contains the HTTP verb to use in the request. If this parameter is NULL, the function uses GET as the HTTP verb.

 

Important This string should be all uppercase. Many servers treat HTTP verbs as case-sensitive, and the Internet Engineering Task Force (IETF) Requests for Comments (RFCs) spell these verbs using uppercase characters only.

 

pwszObjectName

 

[in] Pointer to a null-terminated Unicode string that contains the name of the target resource of the specified HTTP verb. This is generally a file name, an executable module, or a search specifier.

 

pwszVersion

 

[in] Pointer to a null-terminated Unicode string that contains the HTTP version. If this parameter is NULL, the function uses HTTP/1.1.

 

pwszReferrer

 

[in] Pointer to a null-terminated Unicode string that specifies the URL of the document from which the URL in the request pwszObjectName was obtained. If this parameter is set to WINHTTP_NO_REFERER, no referring document is specified.

 

pwszAcceptTypes

 

[in] Pointer to a null-terminated array of string pointers that specifies media types accepted by the client. If this parameter is set to WINHTTP_DEFAULT_ACCEPT_TYPES, no types are accepted by the client. Typically, servers handle a lack of accepted types as indication that the client accepts only documents of type "text/*"; that is, only text documents—no pictures or other binary files. For a list of valid media types, see Media Types.

 

dwFlags

 

[in] Unsigned long integer value that contains the Internet flag values. This can be one or more of the following values:

 

WINHTTP_FLAG_BYPASS_PROXY_CACHE

 

This flag provides the same behavior as WINHTTP_FLAG_REFRESH.

 

WINHTTP_FLAG_ESCAPE_DISABLE

 

Unsafe characters in the URL passed in for pwszObjectName are not converted to escape sequences.

 

WINHTTP_FLAG_ESCAPE_DISABLE_QUERY

 

Unsafe characters in the query component of the URL passed in for pwszObjectName are not converted to escape sequences.

 

WINHTTP_FLAG_ESCAPE_PERCENT

 

The string passed in for pwszObjectName is converted from an LPCWSTR (null-terminated Unicode string) to an LPSTR (null-terminated ANSI string). All unsafe characters are converted to an escape sequence including the percent symbol. By default, all unsafe characters except the percent symbol are converted to an escape sequence.

 

WINHTTP_FLAG_NULL_CODEPAGE

 

The string passed in for pwszObjectName is assumed to consist of valid ANSI characters represented by wide characters. No check are done for unsafe characters.

 

WINHTTP_FLAG_REFRESH

 

Indicates that the request should be forwarded to the originating server rather than sending a cached version of a resource from a proxy server. When this flag is used, a "Pragma: no-cache" header is added to the request handle. When creating an HTTP/1.1 request header, a "Cache-Control: no-cache" is also added.

 

WINHTTP_FLAG_SECURE

 

Uses secure transaction semantics. This translates to using Secure Sockets Layer (SSL)/Transport Layer Security (TLS).

 

Return Value

 

Returns a valid session handle if successful, or NULL otherwise. To retrieve extended error information, call GetLastError. Among the error codes returned are:

 

Error Codes

Description

ERROR_WINHTTP_INCORRECT_HANDLE_TYPE

The type of handle supplied is incorrect for this operation.

ERROR_WINHTTP_INTERNAL_ERROR

An internal error has occurred.

ERROR_WINHTTP_INVALID_URL

The URL is invalid.

ERROR_WINHTTP_OPERATION_CANCELLED

The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed.

ERROR_WINHTTP_UNRECOGNIZED_SCHEME

The URL specified a scheme other than "http:" or "https:".

ERROR_NOT_ENOUGH_MEMORY

Not enough memory was available to complete the requested operation. (Windows error code)

 

Remarks

 

Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates synchronously. The return value indicates success or failure. To get extended error information, call GetLastError.

 

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

 

If pwszVerb is set to "HEAD", the Content-Length header is ignored.

 

If a status callback function has been installed with WinHttpSetStatusCallback, then a WINHTTP_CALLBACK_STATUS_HANDLE_CREATED notification indicates that WinHttpOpenRequest has created a request handle.

 

After the calling application finishes using the HINTERNET handle returned by WinHttpOpenRequest, it must be closed using the WinHttpCloseHandle function.

 

Example Code [C++]

 

This example shows how to obtain an HINTERNET handle, open an HTTP session, create a request header, and send that header to the server.

 

BOOL  bResults = FALSE;

HINTERNET hSession = NULL,

        hConnect = NULL,

        hRequest = NULL;

 

// Use WinHttpOpen to obtain a session handle.

hSession = WinHttpOpen(  L"A WinHTTP Example Program/1.0",

                       WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,

                       WINHTTP_NO_PROXY_NAME,

                       WINHTTP_NO_PROXY_BYPASS, 0);

 

// Specify an HTTP server.

if (hSession)

  hConnect = WinHttpConnect( hSession, L"www.wingtiptoys.com",

                             INTERNET_DEFAULT_HTTP_PORT, 0);

 

// Create an HTTP Request handle.

if (hConnect)

  hRequest = WinHttpOpenRequest( hConnect, L"PUT",

                                 L"/writetst.txt",

                                 NULL, WINHTTP_NO_REFERER,

                                 WINHTTP_DEFAULT_ACCEPT_TYPES,

                                 0);

 

// Send a Request.

if (hRequest)

  bResults = WinHttpSendRequest( hRequest,

                                 WINHTTP_NO_ADDITIONAL_HEADERS,

                                 0, WINHTTP_NO_REQUEST_DATA, 0,

                                 0, 0);

 

// PLACE ADDITIONAL CODE HERE.

 

// Report any errors.

if (!bResults)

  printf("Error %d has occurred.\n",GetLastError());

 

// Close any open handles.

if (hRequest) WinHttpCloseHandle(hRequest);

if (hConnect) WinHttpCloseHandle(hConnect);

if (hSession) WinHttpCloseHandle(hSession);

 

Valid XHTML 1.0 Transitional