次の方法で共有


WinHttpAddRequestHeaders 関数 (winhttp.h)

WinHttpAddRequestHeaders 関数は、HTTP 要求ハンドルに 1 つ以上の HTTP 要求ヘッダーを追加します。

構文

WINHTTPAPI BOOL WinHttpAddRequestHeaders(
  [in] HINTERNET hRequest,
  [in] LPCWSTR   lpszHeaders,
  [in] DWORD     dwHeadersLength,
  [in] DWORD     dwModifiers
);

パラメーター

[in] hRequest

WinHttpOpenRequest 関数の呼び出しによって返される HINTERNET ハンドル。

[in] lpszHeaders

要求に追加するヘッダーを含む文字列変数へのポインター。 最後を除く各ヘッダーは、キャリッジ リターン/ライン フィード (CR/LF) で終了する必要があります。

[in] dwHeadersLength

pwszHeaders の長さを文字数で表す符号なし long 整数値。 このパラメーターが -1L の場合、関数は pwszHeaders が 0 で終わる (ASCIIZ) と見なされ、長さが計算されます。

[in] dwModifiers

この関数のセマンティクスを変更するために使用されるフラグを含む符号なし long 整数値。 次のフラグの 1 つ以上を指定できます。

説明
WINHTTP_ADDREQ_FLAG_ADD
存在しない場合は、ヘッダーを追加します。 WINHTTP_ADDREQ_FLAG_REPLACEで使用されます。
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW
ヘッダーがまだ存在しない場合にのみ、ヘッダーを追加します。それ以外の場合は、エラーが返されます。
WINHTTP_ADDREQ_FLAG_COALESCE
同じ名前のヘッダーをマージします。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA
コンマを使用して、同じ名前のヘッダーをマージします。 たとえば、このフラグで "Accept: text/*" の後に "Accept: audio/*" を追加すると、"Accept: text/*, audio/*" というヘッダーが 1 つになります。 これにより、最初に見つかったヘッダーがマージされます。 呼び出し元のアプリケーションは、マージされたヘッダーと個別のヘッダーに関するまとまりのあるスキームを確保する必要があります。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON
セミコロンを使用して、同じ名前のヘッダーをマージします。
WINHTTP_ADDREQ_FLAG_REPLACE
ヘッダーを置換または削除します。 ヘッダー値が空で、ヘッダーが見つかった場合は削除されます。 値が空でない場合は、置き換えられます。

戻り値

成功した場合は TRUE 、それ以外の場合 は FALSE を 返します。 拡張エラー情報については、 GetLastError を呼び出します。 返されるエラー コードは次のとおりです。

エラー コード 説明
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
指定されたハンドルが正しい状態でないため、要求された操作を実行できません。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
指定されたハンドルの種類が、この操作に対して正しくありません。
ERROR_WINHTTP_INTERNAL_ERROR
内部エラーが発生しました。
ERROR_NOT_ENOUGH_MEMORY
要求された操作を完了するのに十分なメモリが使用できませんでした。

解説

ヘッダーはリダイレクト間で転送されます。 これはセキュリティの問題である可能性があります。 リダイレクトが発生したときにヘッダーが転送されないようにするには、 WINHTTP_STATUS_CALLBACK コールバックを使用して、リダイレクトが発生したときに特定のヘッダーを修正します。

WinHTTP が非同期モードで使用されている場合 (つまり、WinHttpOpenWINHTTP_FLAG_ASYNCが設定されている場合) でも、この関数は同期的に動作します。 戻り値は成功または失敗を示します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

WinHttpAddRequestHeaders 関数は、HTTP 要求ハンドルに追加のフリーフォーマット ヘッダーを追加し、HTTP サーバーに送信される正確な要求を詳細に制御する必要がある高度なクライアントで使用することを目的としています。

この関数で追加された要求ヘッダーの名前と値が検証されます。 ヘッダーは整形式である必要があります。 有効な HTTP ヘッダーの詳細については、「 RFC 2616」を参照してください。 無効なヘッダーが使用されている場合、この関数は失敗し、GetLastError はERROR_INVALID_PARAMETERを返します。 無効なヘッダーは追加されません。

Date: 要求ヘッダーを送信する場合は、 WinHttpTimeFromSystemTime 関数を使用してヘッダーの構造体を作成できます。

基本的な WinHttpAddRequestHeaders の場合、アプリケーションは 1 つのバッファーに複数のヘッダーを渡すことができます。

アプリケーションでは、 WinHttpSendRequest を使用して、要求を送信する前に HTTP 要求ハンドルにヘッダーを追加することもできます。

メモ 詳細については、「 ランタイム要件」を参照してください。
 

次のコード例には、要求に If-Modified-Since ヘッダーが含まれています。 応答ヘッダーは、ターゲット ドキュメントが更新されたかどうかを判断するために解釈されます。


  DWORD dwSize = sizeof(DWORD);
  DWORD dwStatusCode = 0;
  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 );

  // Add a request header.
  if( hRequest )
    bResults = WinHttpAddRequestHeaders( hRequest, 
                 L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
                                         (ULONG)-1L,
                                         WINHTTP_ADDREQ_FLAG_ADD );

  // Send a Request.
  if( bResults ) 
    bResults = WinHttpSendRequest( hRequest, 
                                   WINHTTP_NO_ADDITIONAL_HEADERS,
                                   0,
                                   WINHTTP_NO_REQUEST_DATA,
                                   0, 
                                   0,
                                   0 );

  // End the request.
  if( bResults )
    bResults = WinHttpReceiveResponse( hRequest, NULL);

  // Use WinHttpQueryHeaders to obtain the header buffer.
  if( bResults )
    bResults = WinHttpQueryHeaders( hRequest, 
                WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
                                    NULL, 
                                    &dwStatusCode,
                                    &dwSize,
                                    WINHTTP_NO_HEADER_INDEX );

  // Based on the status code, determine whether 
  // the document was recently updated.
  if( bResults )
  {
    if( dwStatusCode == 304 ) 
      printf( "Document has not been updated.\n" );
    else if( dwStatusCode == 200 ) 
      printf( "Document has been updated.\n" );
    else 
      printf( "Status code = %u.\n",dwStatusCode );
  }

  // Report any errors.
  if( !bResults )
    printf( "Error %d has occurred.\n", GetLastError( ) );

  // Close 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 以降がインストールされています。

関連項目

Microsoft Windows HTTP Services (WinHTTP) について

WinHTTP バージョン

WinHttpOpenRequest

WinHttpSendRequest