Função HttpReceiveRequestEntityBody (http.h)

Artigo
08/24/2023

A função HttpReceiveRequestEntityBody recebe dados adicionais do corpo da entidade para uma solicitação HTTP especificada.

Sintaxe

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
);

Parâmetros

[in] RequestQueueHandle

O identificador para a fila de solicitação da qual recuperar os dados do corpo da entidade especificados. Uma fila de solicitação é criada e seu identificador retornado por uma chamada para a função HttpCreateRequestQueue .

Windows Server 2003 com SP1 e Windows XP com SP2: O identificador para a fila de solicitação é criado pela função HttpCreateHttpHandle .

[in] RequestId

O identificador da solicitação HTTP que contém o corpo da entidade recuperada. Esse valor é retornado no membro RequestId da estrutura HTTP_REQUEST por uma chamada para a função HttpReceiveHttpRequest . Esse valor não pode ser HTTP_NULL_ID.

[in] Flags

Esse parâmetro pode ser o valor do sinalizador a seguir.

Windows Server 2003 com SP1 e Windows XP com SP2: Esse parâmetro é reservado e deve ser zero.

Valor	Significado
HTTP_RECEIVE_REQUEST_ENTITY_BODY_FLAG_FILL_BUFFER	Especifica que o buffer será preenchido com um ou mais corpos de entidade, a menos que não haja corpos de entidade restantes a serem copiados.

[out] EntityBuffer

Um ponteiro para um buffer que recebe dados do corpo da entidade.

[in] EntityBufferLength

O tamanho, em bytes, do buffer apontado pelo parâmetro pBuffer .

[out, optional] BytesReturned

Opcional. Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados do corpo da entidade retornados no buffer pBuffer .

Ao fazer uma chamada assíncrona usando pOverlapped, defina pBytesReceived como NULL. Caso contrário, quando pOverlapped é definido como NULL, pBytesReceived deve conter um endereço de memória válido e não ser definido como NULL.

[in, optional] Overlapped

Para chamadas assíncronas, defina pOverlapped para apontar para uma estrutura OVERLAPPED ; para chamadas síncronas, defina-a como NULL.

Uma chamada síncrona bloqueia até que os dados do corpo da entidade sejam recuperados, enquanto uma chamada assíncrona retorna imediatamente ERROR_IO_PENDING e o aplicativo de chamada usa as portas de conclusão GetOverlappedResult ou de E/S para determinar quando a operação é concluída. Para obter mais informações sobre como usar estruturas OVERLAPPED para sincronização, consulte Sincronização e entrada e saída sobrepostas.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função for usada de forma assíncrona, um valor retornado de ERROR_IO_PENDING indicará que a próxima solicitação ainda não está pronta e será recuperada posteriormente por meio de mecanismos normais de conclusão de E/S sobrepostos.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Valor	Significado
ERROR_INVALID_PARAMETER	Um ou mais dos parâmetros fornecidos estão em uma forma inutilizável.
ERROR_HANDLE_EOF	O corpo da entidade especificado já foi completamente recuperado; nesse caso, o valor apontado por pBytesReceived não é significativo e pBuffer não deve ser examinado.
ERROR_DLL_INIT_FAILED	O aplicativo de chamada não chamou HttpInitialize antes de chamar essa função.
Outros	Um código de erro do sistema definido em WinError.h.

Comentários

Para recuperar um corpo de entidade inteiro, espera-se que um aplicativo chame HttpReceiveRequestEntityBody, passando novos buffers até que a função retorne ERROR_HANDLE_EOF. Desde que um buffer cheio de dados do corpo da entidade seja copiado com êxito e ainda haja mais dados do corpo da entidade aguardando para serem recuperados, a função retornará NO_ERROR.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista, Windows XP com SP2 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	http.h
Biblioteca	Httpapi.lib
DLL	Httpapi.dll