HttpReceiveHttpRequest function (http.h)
The HttpReceiveHttpRequest function retrieves the next available HTTP request from the specified request queue either synchronously or asynchronously.
Syntax
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
A handle to the request queue from which to retrieve the next available request. A request queue is created and its handle returned by a call to the HttpCreateRequestQueue function.
Windows Server 2003 with SP1 and Windows XP with SP2: The handle to the request queue is created by the HttpCreateHttpHandle function.
[in] RequestId
On the first call to retrieve a request, this parameter should be HTTP_NULL_ID. Then, if more than one call is required to retrieve the entire request, HttpReceiveHttpRequest or HttpReceiveRequestEntityBody can be called with RequestID set to the value returned in the RequestId member of the HTTP_REQUEST structure pointed to by pRequestBuffer.
[in] Flags
A parameter that can be one of the following values.
| Value | Meaning |
|---|---|
|
Only the request headers are retrieved; the entity body is not copied. |
|
The available entity body is copied along with the request headers. The pEntityChunks member of the HTTP_REQUEST structure points to the entity body. |
|
All of the entity bodies are copied along with the request headers. The pEntityChunks member of the HTTP_REQUEST structure points to the entity body. |
[out] RequestBuffer
A pointer to a buffer into which the function copies an HTTP_REQUEST structure and entity body for the HTTP request. HTTP_REQUEST.RequestId contains the identifier for this HTTP request, which the application can use in subsequent calls HttpReceiveRequestEntityBody, HttpSendHttpResponse, or HttpSendResponseEntityBody.
[in] RequestBufferLength
Size, in bytes, of the pRequestBuffer buffer.
[out, optional] BytesReturned
Optional. A pointer to a variable that receives the size, in bytes, of the entity body, or of the remaining part of the entity body.
When making an asynchronous call using pOverlapped, set pBytesReceived to NULL. Otherwise, when pOverlapped is set to NULL, pBytesReceived must contain a valid memory address, and not be set to NULL.
[in, optional] Overlapped
For asynchronous calls, set pOverlapped to point to an OVERLAPPED structure; for synchronous calls, set it to NULL.
A synchronous call blocks until a request has arrived in the specified queue and some or all of it has been retrieved, whereas an asynchronous call immediately returns ERROR_IO_PENDING and the calling application then uses
GetOverlappedResult or I/O completion ports to determine when the operation is completed. For more information about using
OVERLAPPED structures for synchronization, see
Synchronization and Overlapped Input and Output.
Return value
If the function succeeds, the return value is NO_ERROR.
If the function is being used asynchronously, a return value of ERROR_IO_PENDING indicates that the next request is not yet ready and will be retrieved later through normal overlapped I/O completion mechanisms.
If the function fails, the return value is one of the following error codes.
| Value | Meaning |
|---|---|
|
One or more of the supplied parameters is in an unusable form. |
|
One or more of the supplied parameters points to an invalid or unaligned memory buffer. The pRequestBuffer parameter must point to a valid memory buffer with a memory alignment equal or greater to the memory alignment requirement for an HTTP_REQUEST structure. |
|
The value of RequestBufferLength is greater than or equal to the size of the request header received, but is not as large as the combined size of the request structure and entity body. The buffer size required to read the remaining part of the entity body is returned in the pBytesReceived parameter if this is non-NULL and if the call is synchronous. Call the function again with a large enough buffer to retrieve all data. |
|
The specified request has already been completely retrieved; in this case, the value pointed to by pBytesReceived is not meaningful, and pRequestBuffer should not be examined. |
|
A system error code defined in WinError.h. |
Remarks
More than one call can be required to retrieve a given request. When the Flags parameter is set to zero, for example, HttpReceiveHttpRequest only copies the request header structure into the buffer, and does not attempt to copy any of the entity body. In this case, the HttpReceiveRequestEntityBody function can be used to retrieve the entity body, or a second call can be made to HttpReceiveHttpRequest.
Alternatively, the buffer provided by the application may be insufficiently large to receive all or part of the request. To be sure of receiving at least part of the request, it is recommended that an application provide at least a buffer of 4 KB, which accommodates most HTTP requests. Alternately, authentication headers, parsed as unknown headers, can add up to 12 KB to that, so if authentication/authorization is used, a buffer size of at least 16 KB is recommended.
If HttpReceiveHttpRequest returns ERROR_MORE_DATA, the application continues to make additional calls, identifying the request in each additional call by passing in the HTTP_REQUEST.RequestId value returned by the first call until ERROR_HANDLE_EOF is returned.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista, Windows XP with SP2 [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | http.h |
| Library | Httpapi.lib |
| DLL | Httpapi.dll |