共用方式為


WinHttpAddRequestHeaders 函式 (winHTTP.h)

WinHttpAddRequestHeaders 函式會將一或多個 HTTP 要求標頭新增至 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的長度,以字元為單位。 如果此參數為 -1L,函式會假設 pwszHeaders 是以零終止 (ASCIIZ) ,而且會計算長度。

[in] dwModifiers

不帶正負號的長整數值,其中包含用來修改此函式語意的旗標。 可以是下列一或多個旗標。

意義
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/*」。 這會導致找到的第一個標頭合併。 呼叫端應用程式必須確定與合併和分隔標頭相關的一致配置。
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 用於非同步模式 (亦即,在WinHttpOpen) 中設定WINHTTP_FLAG_ASYNC時,此函式仍會同步運作。 傳回值表示成功或失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

WinHttpAddRequestHeaders函式會將額外的自由格式標頭附加至 HTTP 要求控制碼,並供需要詳細控制傳送至 HTTP 伺服器之確切要求的複雜用戶端使用。

會驗證使用此函式新增之要求標頭的名稱和值。 標頭的格式必須正確。 如需有效 HTTP 標頭的詳細資訊,請參閱 RFC 2616。 如果使用不正確標頭,此函式會失敗,而且 GetLastError傳回ERROR_INVALID_PARAMETER。 未新增不正確標頭。

如果您要傳送 Date: 要求標頭,您可以使用 WinHttpTimeFromSystemTime 函式來建立標頭的結構。

針對基本 WinHttpAddRequestHeaders,應用程式可以在單一緩衝區中傳入多個標頭。

應用程式也可以使用 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、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winHTTP.h
程式庫 WinHTTP.lib
Dll Winhttp.dll
可轉散發套件 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。

另請參閱

關於 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpOpenRequest

WinHttpSendRequest