httpSendHttpResponse 函数 (http.h)

  • 项目

HttpSendHttpResponse 函数向指定的 HTTP 请求发送 HTTP 响应。

语法

HTTPAPI_LINKAGE ULONG HttpSendHttpResponse(
  [in]           HANDLE             RequestQueueHandle,
  [in]           HTTP_REQUEST_ID    RequestId,
  [in]           ULONG              Flags,
  [in]           PHTTP_RESPONSE     HttpResponse,
  [in, optional] PHTTP_CACHE_POLICY CachePolicy,
  [out]          PULONG             BytesSent,
  [in]           PVOID              Reserved1,
  [in]           ULONG              Reserved2,
  [in]           LPOVERLAPPED       Overlapped,
  [in, optional] PHTTP_LOG_DATA     LogData
);

parameters

[in] RequestQueueHandle

从中检索指定请求的请求队列的句柄。 创建请求队列，并通过调用 HttpCreateRequestQueue 函数返回其句柄。

Windows Server 2003 SP1 和 Windows XP SP2： 请求队列的句柄由 HttpCreateHttpHandle 函数创建。

[in] RequestId

此响应所对应的 HTTP 请求的标识符。 通过调用 HttpReceiveHttpRequest 函数，在 HTTP_REQUEST 结构的 RequestId 成员中返回此值。 不能 HTTP_NULL_ID此值。

[in] Flags

此参数可以是以下一些标志值的组合。 相互排斥的项会相应地进行标记。

Flags 含义
HTTP_SEND_RESPONSE_FLAG_DISCONNECT
 发送此响应后，网络连接应断开，并重写与正在使用的 HTTP 版本关联的任何持久性连接功能。
谨慎在对 HttpSendHttpResponse 函数的单个调用中组合HTTP_SEND_RESPONSE_FLAG_DISCONNECT和HTTP_SEND_RESPONSE_FLAG_MORE_DATA会产生未定义的结果。
 
HTTP_SEND_RESPONSE_FLAG_MORE_DATA
 应用程序通过对 HttpSendResponseEntityBody 的一个或多个后续调用发送此响应的其他实体正文数据。 然后，发送实体主体数据的最后一次调用将此标志设置为零。
谨慎在对 HttpSendHttpResponse 函数的单个调用中组合HTTP_SEND_RESPONSE_FLAG_DISCONNECT和HTTP_SEND_RESPONSE_FLAG_MORE_DATA会产生未定义的结果。
 
HTTP_SEND_RESPONSE_FLAG_BUFFER_DATA
 此标志允许基于每个响应缓冲内核中的数据。

它应由执行同步 I/O 的应用程序使用，或者由执行异步 I/O 且一次发送不超过一次的应用程序使用。

使用异步 I/O 且一次可能有多个未完成发送的应用程序不应使用此标志。

设置此标志后，还应在调用 HttpSendResponseEntityBody 函数时一致地使用它。

Windows Server 2003： 不支持此标志。 此标志是 Windows Server 2003 SP1 的新增标志。
HTTP_SEND_RESPONSE_FLAG_ENABLE_NAGLING
 仅为此发送启用 TCP 导航算法。

Windows Server 2003 SP1 和 Windows XP SP2： 不支持此标志。
HTTP_SEND_RESPONSE_FLAG_PROCESS_RANGES
 指定对于范围请求，将传递完整的响应内容，并且调用方希望 HTTP API 正确处理范围。
注意 此标志仅支持对 HTTP GET 请求的响应，并提供有限的功能子集。 需要全范围处理的应用程序应在用户模式下执行，而不是依赖于 HTTP.sys。 不建议使用它。
 
Windows Server 2008 R2 和 Windows 7 或更高版本。

注意 支持此标志。
HTTP_SEND_RESPONSE_FLAG_OPAQUE
 指定请求/响应不符合 HTTP，并且所有后续字节应被视为实体正文。 应用程序在接受 Web 套接字升级请求并通知 HTTP.sys 将连接数据视为不透明数据时指定此标志。

仅当 pHttpResponse 的 StatusCode 成员为 101，切换协议时，才允许使用此标志。 如果使用此标志，HttpSendHttpResponse 将返回所有其他 HTTP 响应类型的ERROR_INVALID_PARAMETER。

Windows 8 及更高版本： 支持此标志。

[in] HttpResponse

指向定义 HTTP 响应 的HTTP_RESPONSE 结构的指针。

[in, optional] CachePolicy

指向用于缓存响应 的 HTTP_CACHE_POLICY 结构的指针。

Windows Server 2003 SP1 和 Windows XP SP2： 此参数是保留的，必须为 NULL。

[out] BytesSent

可选。 指向变量的指针，该变量接收在函数同步运行时发送的数字（以字节为单位）。

使用 pOverlapped 进行异步调用时，将 pBytesSent 设置为 NULL。 否则，当 pOverlapped 设置为 NULL 时， pBytesSent 必须包含有效的内存地址，并且不能设置为 NULL。

[in] Reserved1

此参数是保留的，必须为 NULL。

[in] Reserved2

此参数是保留的，必须为零。

[in] Overlapped

对于异步调用，请将 pOverlapped 设置为指向 OVERLAPPED 结构;对于同步调用，请设置为 NULL。

同步调用会阻止，直到发送 pHttpResponse 参数中指定的所有响应数据，而异步调用会立即返回 ERROR_IO_PENDING ，然后调用应用程序使用 GetOverlappedResult 或 I/O 完成端口来确定操作何时完成。 有关使用 OVERLAPPED 结构进行同步的详细信息，请参阅 同步和重叠输入和输出。

[in, optional] LogData

指向用于记录响应 的 HTTP_LOG_DATA 结构的指针。 传递指向 HTTP_LOG_FIELDS_DATA 结构的指针，并将其强制转换为 PHTTP_LOG_DATA。

请注意，即使对 URL 组或服务器会话启用了日志记录，也不会记录响应，除非应用程序提供日志字段数据结构。

Windows Server 2003 和 Windows XP SP2： 此参数是保留的，必须为 NULL。

Windows Vista 和 Windows Server 2008： 此参数是 Windows Vista 和 Windows Server 2008 的新增功能

返回值

如果函数成功，该函数将返回 NO_ERROR。

如果异步使用函数，则返回值 ERROR_IO_PENDING 指示下一个请求尚未就绪，稍后会通过正常的重叠 I/O 完成机制进行检索。

如果该函数失败，它将返回以下错误代码之一。

值 含义
ERROR_INVALID_PARAMETER
 提供的一个或多个参数以不可用的形式提供。
其他
 WinError.h 中定义的 系统错误代码 。

注解

HttpSendHttpResponse 函数用于创建和发送响应标头，HttpSendResponseEntityBody 函数可用于根据需要发送实体正文数据。

如果响应中不包含 content-length 标头和传输编码标头，则应用程序必须通过使用 HTTP_SEND_RESPONSE_DISCONNECT 标志显式关闭连接来指示 响应 结束。

如果应用程序使用 HTTP_KNOWN_HEADER 结构中的 HttpHeaderServer 标识符在响应中指定了“Server：”标头，则指定的值将作为标头的第一部分放置，后跟空格，然后是“Microsoft-HTTPAPI/1.0”。 如果未指定服务器标头， HttpSendHttpResponse 将提供“Microsoft-HTTPAPI/1.0”作为服务器标头。

注意不能从同一 RequestId 上的不同线程同时调用 HttpSendHttpResponse 和 HttpSendResponseEntityBody 函数。
 

要求

   
最低受支持的客户端 Windows Vista、Windows XP SP2 [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 http.h
Library Httpapi.lib
DLL Httpapi.dll

另请参阅

HTTP 服务器 API 版本 1.0 函数

HTTP_RESPONSE

HttpReceiveHttpRequest

HttpReceiveRequestEntityBody

HttpSendResponseEntityBody