WinHttpQueryHeaders 関数 (winhttp.h)

[アーティクル]
08/27/2023

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

同じ名前の複数のヘッダーを列挙するために使用される 0 から始まるヘッダーインデックスへのポインター。関数を呼び出すとき、このパラメーターは、返される指定されたヘッダーのインデックスです。関数が戻るときに、このパラメーターは次のヘッダーのインデックスです。次のインデックスが見つからない場合は、 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 およびインターネットエクスプローラー 5.01 以降がインストールされています。