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
不帶正負號的長整數值，其中包含用來修改此函式語意的旗標。 可以是下列一或多個旗標。
傳回值
如果成功，則傳回 TRUE ，否則傳回 FALSE 。 如需擴充的錯誤資訊，請呼叫 GetLastError。 傳回的錯誤碼如下。
| 錯誤碼 | 描述 |
|---|---|
|
無法執行要求的作業，因為提供的控制碼不是處於正確的狀態。 |
|
此作業所提供的控制碼類型不正確。 |
|
發生內部錯誤。 |
|
記憶體不足，無法完成要求的作業。 |
備註
標頭會跨重新導向傳輸。 這可以是安全性問題。 為了避免在重新導向發生時傳送標頭，請使用 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 或更新版本。 |