WinHttpQueryHeaders 函数 (winhttp.h)

项目
03/13/2024

WinHttpQueryHeaders 函数检索与 HTTP 请求关联的标头信息。

另请参阅 WinHttpQueryHeadersEx，它提供了一种检索已分析标头名称和值字符串的方法。

语法

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

参数

[in] hRequest

WinHttpOpenRequest 返回的 HINTERNET 请求句柄。 WinHttpReceiveResponse 必须已为此句柄调用，并在调用 WinHttpQueryHeaders 之前完成。

[in] dwInfoLevel

类型为 DWORD 的值，该值指定“查询信息标志”页上列出的属性标志和修饰符标志的组合。这些属性和修饰符标志指示正在请求信息以及设置其格式的方式。

[in, optional] pwszName

指向包含标头名称的字符串的指针。如果未WINHTTP_QUERY_CUSTOMdwInfoLevel 中的标志，请将此参数设置为 WINHTTP_HEADER_NAME_BY_INDEX。

[out] lpBuffer

指向接收信息的缓冲区的指针。将此参数设置为 WINHTTP_NO_OUTPUT_BUFFER 会导致此函数返回 FALSE。然后调用 GetLastError 将返回ERROR_INSUFFICIENT_BUFFER，lpdwBufferLength 包含保存所请求信息所需的字节数。

[in, out] lpdwBufferLength

指向 DWORD 类型的值的指针，该值指定数据缓冲区的长度（以字节为单位）。函数返回时，此参数包含指向值的指针，该值指定写入缓冲区的信息的长度。当函数返回字符串时，以下规则适用。

如果函数成功， 则 lpdwBufferLength 指定字符串的长度（以字节为单位），以减 2 表示终止 null。
如果函数失败并返回 ERROR_INSUFFICIENT_BUFFER ， 则 lpdwBufferLength 指定应用程序必须分配才能接收字符串的字节数。

[in, out] lpdwIndex

指向从零开始的标头索引的指针，用于枚举具有相同名称的多个标头。调用函数时，此参数是要返回的指定标头的索引。当函数返回时，此参数是下一个标头的索引。如果找不到下一个索引，则返回 ERROR_WINHTTP_HEADER_NOT_FOUND 。将此参数设置为 WINHTTP_NO_HEADER_INDEX 以指定只返回标头的第一个匹配项。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。要获得更多的错误信息，请调用 GetLastError。返回的错误代码如下。

错误代码	说明
ERROR_WINHTTP_HEADER_NOT_FOUND	无法找到请求的标头。
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	无法执行请求的操作，因为提供的句柄未处于正确的状态。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	为此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。返回值指示成功或失败。要获得更多的错误信息，请调用 GetLastError。

默认情况下 ，WinHttpQueryHeaders 返回一个字符串。但是，可以通过在 dwInfoLevel 中包含相应的修饰符标志，以 SYSTEMTIME 结构或 DWORD 的形式请求数据。下表显示了 WinHttpQueryHeaders 可以返回的可能数据类型，以及用于选择该数据类型的修饰符标志。

数据类型	修饰符标志
LPCWSTR	默认。无需修饰符标志。
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

示例

以下示例演示如何获取 HINTERNET 句柄、打开 HTTP 会话、创建和发送请求标头，以及检查返回的响应标头。

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

要求

要求	值
最低受支持的客户端	Windows XP、Windows 2000 Professional 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。