httpReceiveHttpRequest 函数 (http.h)

  • 项目

HttpReceiveHttpRequest 函数以同步或异步方式从指定的请求队列中检索下一个可用的 HTTP 请求。

语法

HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
  [in]            HANDLE          RequestQueueHandle,
  [in]            HTTP_REQUEST_ID RequestId,
  [in]            ULONG           Flags,
  [out]           PHTTP_REQUEST   RequestBuffer,
  [in]            ULONG           RequestBufferLength,
  [out, optional] PULONG          BytesReturned,
  [in, optional]  LPOVERLAPPED    Overlapped
);

parameters

[in] RequestQueueHandle

要从中检索下一个可用请求的请求队列的句柄。 创建请求队列，并通过调用 HttpCreateRequestQueue 函数返回其句柄。

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

[in] RequestId

第一次调用检索请求时，应 HTTP_NULL_ID此参数。 然后，如果需要多个调用来检索整个请求，则可以调用 HttpReceiveHttpRequest 或 HttpReceiveRequestEntityBody，并将 RequestID 设置为 pRequestBuffer 指向的 HTTP_REQUEST 结构的 RequestId 成员中返回的值。

[in] Flags

可以是下列值之一的参数。

值 含义
0（零）
 仅检索请求标头;不会复制实体正文。
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY
 可用实体正文与请求标头一起复制。 HTTP_REQUEST 结构的 pEntityChunks 成员指向实体主体。
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY
 所有实体正文与请求标头一起复制。 HTTP_REQUEST 结构的 pEntityChunks 成员指向实体主体。

[out] RequestBuffer

指向缓冲区的指针，函数在其中复制 HTTP 请求 的HTTP_REQUEST 结构和实体正文。 HTTP_REQUEST。RequestId 包含此 HTTP 请求的标识符，应用程序可以在后续调用 HttpReceiveRequestEntityBody、 HttpSendHttpResponse 或 HttpSendResponseEntityBody 中使用该标识符。

[in] RequestBufferLength

pRequestBuffer 缓冲区的大小（以字节为单位）。

[out, optional] BytesReturned

可选。 指向变量的指针，该变量接收实体正文或实体正文剩余部分的大小（以字节为单位）。

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

[in, optional] Overlapped

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

同步调用会阻塞，直到请求到达指定队列并检索到部分或全部队列，而异步调用会立即返回 ERROR_IO_PENDING 调用应用程序随后使用 GetOverlappedResult 或 I/O 完成端口来确定操作何时完成。 有关使用 OVERLAPPED 结构进行同步的详细信息，请参阅
同步以及重叠的输入和输出。

返回值

如果函数成功，则返回值 NO_ERROR。

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

如果函数失败，则返回值为以下错误代码之一。

值 含义
ERROR_INVALID_PARAMETER
 提供的一个或多个参数以不可用的形式提供。
ERROR_NOACCESS
 提供的一个或多个参数指向无效或未对齐的内存缓冲区。 pRequestBuffer 参数必须指向有效的内存缓冲区，其内存对齐方式等于或大于HTTP_REQUEST结构的内存对齐要求。
ERROR_MORE_DATA
 RequestBufferLength 的值大于或等于接收的请求标头的大小，但不如请求结构和实体正文的组合大小大。 如果这是非 NULL 且调用是同步的，则读取实体正文的剩余部分所需的缓冲区大小将在 pBytesReceived 参数中返回。 使用足够大的缓冲区再次调用 函数，以检索所有数据。
ERROR_HANDLE_EOF
 指定的请求已完全检索;在这种情况下， pBytesReceived 指向的值没有意义，不应检查 pRequestBuffer 。
其他
 WinError.h 中定义的 系统错误代码 。

注解

检索给定请求可能需要多个调用。 例如，当 Flags 参数设置为零时， HttpReceiveHttpRequest 仅将请求标头结构复制到缓冲区中，而不尝试复制任何实体正文。 在这种情况下， HttpReceiveRequestEntityBody 函数可用于检索实体正文，也可以对 HttpReceiveHttpRequest 进行第二次调用。

或者，应用程序提供的缓冲区可能不够大，无法接收全部或部分请求。 为了确保至少接收部分请求，建议应用程序提供至少 4 KB 的缓冲区，该缓冲区可容纳大多数 HTTP 请求。 或者，解析为未知标头的身份验证标头最多可添加 12 KB，因此，如果使用身份验证/授权，则建议缓冲区大小至少为 16 KB。

如果 HttpReceiveHttpRequest 返回 ERROR_MORE_DATA，则应用程序将继续进行其他调用，通过传入HTTP_REQUEST来标识每个附加调用中的请求 。 在返回 ERROR_HANDLE_EOF 之前，第一次调用返回的 RequestId 值。

注意 应用程序必须检查所有相关的请求标头，包括内容协商标头（如果使用），并根据标头内容根据需要使请求失败。 HttpReceiveHttpRequest 仅确保标头行正确终止，并且不包含非法字符。
 

要求

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

另请参阅

HTTP 服务器 API 版本 1.0 函数

HTTP_REQUEST

HttpReceiveRequestEntityBody

HttpSendHttpResponse

HttpSendResponseEntityBody