WinHttpQueryHeaders

Description

The WinHttpQueryHeaders function retrieves header information associated with an HTTP request.

C/C++ Syntax

PowerBASIC Syntax

Parameters

hRequest

[in] HINTERNET request handle returned by WinHttpOpenRequest. WinHttpReceiveResponse must have been called for this handle and have completed before WinHttpQueryHeaders is called.

dwInfoLevel

[in] Value of type DWORD that specifies a combination of attribute and modifier flags listed on the Query Info Flags page. These attribute and modifier flags indicate that the information is being requested and how it is to be formatted.

pwszName

[in, optional] Pointer to a null-terminated Unicode string that contains the header name. If the flag in dwInfoLevel is not WINHTTP_QUERY_CUSTOM, set this parameter to WINHTTP_HEADER_NAME_BY_INDEX.

lpBuffer

[out] Pointer to the buffer that receives the information. Setting this parameter to WINHTTP_NO_OUTPUT_BUFFER causes this function to return FALSE. Calling GetLastError then returns ERROR_INSUFFICIENT_BUFFER and lpdwBufferLength contains the number of bytes required to hold the requested information.

lpdwBufferLength

[in, out] Pointer to a value of type DWORD that specifies the length of the data buffer, in bytes. When the function returns, this parameter contains the pointer to a value that specifies the length of the information written to the buffer. When the function returns strings, the following rules apply.

lpdwIndex

[in, out] Pointer to 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_WINHTTP_HEADER_NOT_FOUND is returned. Set this parameter to WINHTTP_NO_HEADER_INDEX to specify that only the first occurrence of a header should be returned.

Return Value

Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError. Among the error codes returned are:

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.

By default WinHttpQueryHeaders returns a string. However, you can request data in the form of a SYSTEMTIME structure or DWORD by including the appropriate modifier flag in dwInfoLevel. The following table shows the possible data types that WinHttpQueryHeaders can return along with the modifier flag that you use to select that data type.

Example Code [PowerBASIC]

The following example shows how to obtain an HINTERNET handle, open an HTTP session, create and send a request header, and examine the returned response header.

#COMPILE EXE

#DIM ALL

#INCLUDE "WIN32API.INC"

#INCLUDE "WINHTTP.INC"

FUNCTION PBMAIN () AS LONG

 LOCAL dwSize AS DWORD

 LOCAL dwStatusCode AS DWORD

 LOCAL bResults AS LONG

 LOCAL hSession AS DWORD

 LOCAL hConnect AS DWORD

 LOCAL hRequest AS DWORD

 LOCAL strUserAgent AS STRING

 LOCAL strServerName AS STRING

 LOCAL strVerb AS STRING

 LOCAL strOutBuffer AS STRING

 dwSize = 4  ' size of a DWORD

 ' Use WinHttpOpen to obtain a session handle.

 strUserAgent = UCODE$("A WinHTTP Example Program/1.0" & $NUL)

 hSession = WinHttpOpen(STRPTR(strUserAgent), _

                        %WINHTTP_ACCESS_TYPE_DEFAULT_PROXY, _

                        %WINHTTP_NO_PROXY_NAME, _

                        %WINHTTP_NO_PROXY_BYPASS, _

                        0)

 ' Specify an HTTP server.

 IF hSession THEN

    strServerName = UCODE$("www.microsoft.com" & $NUL)

    hConnect = WinHttpConnect(hSession, _

                              STRPTR(strServerName), _

                              %INTERNET_DEFAULT_HTTP_PORT, _

                              0)

 END IF

 ' Create an HTTP Request handle.

 IF hConnect THEN

    strVerb = UCODE$("GET" & $NUL)

    hRequest = WinHttpOpenRequest(hConnect, _

                                  STRPTR(strVerb), _

                                  %NULL,  _

                                  %NULL, _

                                  %WINHTTP_NO_REFERER, _

                                  BYVAL %WINHTTP_DEFAULT_ACCEPT_TYPES, _

                                  0)

 END IF

 ' Send a Request.

 IF hRequest THEN

    bResults = WinHttpSendRequest(hRequest, _

                                  %WINHTTP_NO_ADDITIONAL_HEADERS, _

                                  0, _

                                  %WINHTTP_NO_REQUEST_DATA, _

                                  0, _

                                  0, _

                                  0)

 END IF

 ' End the request.

 IF bResults THEN

    bResults = WinHttpReceiveResponse(hRequest, %NULL)

 END IF

 ' First, use WinHttpQueryHeaders to obtain the size of the buffer.

 IF bResults THEN

    WinHttpQueryHeaders(hRequest, %WINHTTP_QUERY_RAW_HEADERS_CRLF, _

                        %WINHTTP_HEADER_NAME_BY_INDEX, %NULL, _

                        dwSize, BYVAL %WINHTTP_NO_HEADER_INDEX)

 END IF

 ' Allocate memory for the buffer.

 IF GetLastError = %ERROR_INSUFFICIENT_BUFFER THEN

    strOutBuffer = SPACE$(dwSize)

    '  Now, use WinHttpQueryHeaders to retrieve the header.

     bResults = WinHttpQueryHeaders(hRequest, _

                                    %WINHTTP_QUERY_RAW_HEADERS_CRLF, _

                                    %WINHTTP_HEADER_NAME_BY_INDEX, _

                                    STRPTR(strOutBuffer), dwSize, _

                                    BYVAL %WINHTTP_NO_HEADER_INDEX)

 END IF

 ' Print the header contents.

 IF bResults THEN

    STDOUT "Header contents: "

    STDOUT ACODE$(strOutBuffer)

 END IF

 ' Report any errors.

 IF ISFALSE bResults THEN

    PRINT "Error " GetLastError " has occurred."

 END IF

 ' Close open handles.

 IF hRequest THEN WinHttpCloseHandle(hRequest)

 IF hConnect THEN WinHttpCloseHandle(hConnect)

 IF hSession THEN WinHttpCloseHandle(hSession)

 WAITKEY$

END FUNCTION

Example Code [C++]

DWORD dwSize = 0;

LPVOID lpOutBuffer = NULL;

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.microsoft.com",

                             INTERNET_DEFAULT_HTTP_PORT, 0);

// Create an HTTP request handle.

if (hConnect)

  hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,

                                 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);

// End the request.

if (bResults)

  bResults = WinHttpReceiveResponse( hRequest, NULL);

// First, use WinHttpQueryHeaders to obtain the size of the buffer.

if (bResults)

{

  WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,

                       WINHTTP_HEADER_NAME_BY_INDEX, NULL,

                       &dwSize, WINHTTP_NO_HEADER_INDEX);

  // Allocate memory for the buffer.

  if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )

  {

      lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

      // Now, use WinHttpQueryHeaders to retrieve the header.

      bResults = WinHttpQueryHeaders( hRequest,

                                 WINHTTP_QUERY_RAW_HEADERS_CRLF,

                                 WINHTTP_HEADER_NAME_BY_INDEX,

                                 lpOutBuffer, &dwSize,

                                 WINHTTP_NO_HEADER_INDEX);

  }

}

// Print the header contents.

if (bResults)

  printf("Header contents: \n%S",lpOutBuffer);

// Free the allocated memory.

delete [] lpOutBuffer;

// 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);