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
可以是下列值之一的参数。
| 值 | 含义 |
|---|---|
|
仅检索请求标头;不会复制实体正文。 |
|
可用实体正文与请求标头一起复制。 HTTP_REQUEST 结构的 pEntityChunks 成员指向实体主体。 |
|
所有实体正文与请求标头一起复制。 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 完成机制进行检索。
如果函数失败，则返回值为以下错误代码之一。
| 值 | 含义 |
|---|---|
|
提供的一个或多个参数以不可用的形式提供。 |
|
提供的一个或多个参数指向无效或未对齐的内存缓冲区。 pRequestBuffer 参数必须指向有效的内存缓冲区，其内存对齐方式等于或大于HTTP_REQUEST结构的内存对齐要求。 |
|
RequestBufferLength 的值大于或等于接收的请求标头的大小，但不如请求结构和实体正文的组合大小大。 如果这是非 NULL 且调用是同步的，则读取实体正文的剩余部分所需的缓冲区大小将在 pBytesReceived 参数中返回。 使用足够大的缓冲区再次调用 函数，以检索所有数据。 |
|
指定的请求已完全检索;在这种情况下， 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 值。
要求
| 最低受支持的客户端 | Windows Vista、Windows XP SP2 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | http.h |
| Library | Httpapi.lib |
| DLL | Httpapi.dll |