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

包含標頭名稱的字串指標。如果 dwInfoLevel 中的旗標未 WINHTTP_QUERY_CUSTOM，請將此參數設定為 WINHTTP_HEADER_NAME_BY_INDEX。

[out] lpBuffer

接收信息的緩衝區指標。將此參數設定為 WINHTTP_NO_OUTPUT_BUFFER會導致此函式傳回 FALSE。呼叫 GetLastError 然後傳回ERROR_INSUFFICIENT_BUFFER，lpdwBufferLength 包含保存要求資訊所需的位元元數目。

[in, out] lpdwBufferLength

DWORD 類型的值指標，指定數據緩衝區的長度，以位元組為單位。當函式傳回時，此參數會包含值指標，指定寫入緩衝區的信息長度。當函式傳回字串時，會套用下列規則。

如果函式成功， lpdwBufferLength 會指定終止 Null 的字串長度，以位元組為單位，減 2。
如果函式失敗並傳回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
程式庫	Winhttp.lib
Dll	Winhttp.dll
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。