HttpReceiveRequestEntityBody function (http.h)

Article
10/13/2021

The HttpReceiveRequestEntityBody function receives additional entity body data for a specified HTTP request.

Syntax

HTTPAPI_LINKAGE ULONG HttpReceiveRequestEntityBody(
  [in]            HANDLE          RequestQueueHandle,
  [in]            HTTP_REQUEST_ID RequestId,
  [in]            ULONG           Flags,
  [out]           PVOID           EntityBuffer,
  [in]            ULONG           EntityBufferLength,
  [out, optional] PULONG          BytesReturned,
  [in, optional]  LPOVERLAPPED    Overlapped
);

Parameters

[in] RequestQueueHandle

The handle to the request queue from which to retrieve the specified entity body data. 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

The identifier of the HTTP request that contains the retrieved entity body. This value is returned in the RequestId member of the HTTP_REQUEST structure by a call to the HttpReceiveHttpRequest function. This value cannot be HTTP_NULL_ID.

[in] Flags

This parameter can be the following flag value.

Windows Server 2003 with SP1 and Windows XP with SP2: This parameter is reserved and must be zero.

Value	Meaning
HTTP_RECEIVE_REQUEST_ENTITY_BODY_FLAG_FILL_BUFFER	Specifies that the buffer will be filled with one or more entity bodies, unless there are no remaining entity bodies to copy.

[out] EntityBuffer

A pointer to a buffer that receives entity-body data.

[in] EntityBufferLength

The size, in bytes, of the buffer pointed to by the pBuffer parameter.

[out, optional] BytesReturned

Optional. A pointer to a variables that receives the size, in bytes, of the entity body data returned in the pBuffer buffer.

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 the entity-body data 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 used asynchronously, a return value of ERROR_IO_PENDING indicates that the next request is not yet ready and is 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
ERROR_INVALID_PARAMETER	One or more of the supplied parameters are in an unusable form.
ERROR_HANDLE_EOF	The specified entity body has already been completely retrieved; in this case, the value pointed to by pBytesReceived is not meaningful, and pBuffer should not be examined.
ERROR_DLL_INIT_FAILED	The calling application did not call HttpInitialize before calling this function.
Other	A system error code defined in WinError.h.

Remarks

To retrieve an entire entity body, an application is expected to call HttpReceiveRequestEntityBody, passing in new buffers, until the function returns ERROR_HANDLE_EOF. As long as a buffer full of entity-body data is copied successfully and there is still more entity-body data waiting to be retrieved, the function returns NO_ERROR.

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