WinHttpAddRequestHeaders 函数 (winhttp.h)

项目
08/27/2023

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、Windows 2000 Server SP3 [仅限桌面应用]
目标平台	Windows
标头	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
可再发行组件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpOpenRequest

WinHttpSendRequest

WinHttpAddRequestHeaders 函数 (winhttp.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

反馈

其他资源