Função HttpReceiveHttpRequest (http.h)

Artigo
08/24/2023

A função HttpReceiveHttpRequest recupera a próxima solicitação HTTP disponível da fila de solicitação especificada de forma síncrona ou assíncrona.

Sintaxe

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

Parâmetros

[in] RequestQueueHandle

Um identificador para a fila de solicitação da qual recuperar a próxima solicitação disponível. 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

Na primeira chamada para recuperar uma solicitação, esse parâmetro deve ser HTTP_NULL_ID. Em seguida, se mais de uma chamada for necessária para recuperar toda a solicitação, HttpReceiveHttpRequest ou HttpReceiveRequestEntityBody poderão ser chamados com RequestID definido como o valor retornado no membro RequestId da estrutura HTTP_REQUEST apontada por pRequestBuffer.

[in] Flags

Um parâmetro que pode ser um dos valores a seguir.

Valor	Significado
0 (zero)	Somente os cabeçalhos de solicitação são recuperados; o corpo da entidade não é copiado.
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY	O corpo da entidade disponível é copiado junto com os cabeçalhos de solicitação. O membro pEntityChunks da estrutura HTTP_REQUEST aponta para o corpo da entidade.
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY	Todos os corpos da entidade são copiados junto com os cabeçalhos de solicitação. O membro pEntityChunks da estrutura HTTP_REQUEST aponta para o corpo da entidade.

[out] RequestBuffer

Um ponteiro para um buffer no qual a função copia uma estrutura HTTP_REQUEST e o corpo da entidade para a solicitação HTTP. HTTP_REQUEST. RequestId contém o identificador dessa solicitação HTTP, que o aplicativo pode usar nas chamadas subsequentes HttpReceiveRequestEntityBody, HttpSendHttpResponse ou HttpSendResponseEntityBody.

[in] RequestBufferLength

Tamanho, em bytes, do buffer pRequestBuffer .

[out, optional] BytesReturned

Opcional. Um ponteiro para uma variável que recebe o tamanho, em bytes, do corpo da entidade ou da parte restante do corpo da entidade.

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 uma solicitação chegue à fila especificada e algumas ou todas elas sejam recuperadas, enquanto uma chamada assíncrona retorna imediatamente ERROR_IO_PENDING e o aplicativo de chamada usa as portas de conclusão GetOverlappedResult ou 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.

Valor retornado

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

Se a função estiver sendo 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_NOACCESS	Um ou mais dos parâmetros fornecidos apontam para um buffer de memória inválido ou não assinado. O parâmetro pRequestBuffer deve apontar para um buffer de memória válido com um alinhamento de memória igual ou maior ao requisito de alinhamento de memória para uma estrutura de HTTP_REQUEST .
ERROR_MORE_DATA	O valor de RequestBufferLength é maior ou igual ao tamanho do cabeçalho de solicitação recebido, mas não é tão grande quanto o tamanho combinado da estrutura de solicitação e do corpo da entidade. O tamanho do buffer necessário para ler a parte restante do corpo da entidade será retornado no parâmetro pBytesReceived se isso não for NULL e se a chamada for síncrona. Chame a função novamente com um buffer grande o suficiente para recuperar todos os dados.
ERROR_HANDLE_EOF	A solicitação especificada já foi completamente recuperada; nesse caso, o valor apontado por pBytesReceived não é significativo e pRequestBuffer não deve ser examinado.
Outros	Um código de erro do sistema definido em WinError.h.

Comentários

Mais de uma chamada pode ser necessária para recuperar uma determinada solicitação. Quando o parâmetro Flags é definido como zero, por exemplo, HttpReceiveHttpRequest copia apenas a estrutura de cabeçalho da solicitação para o buffer e não tenta copiar nenhum corpo da entidade. Nesse caso, a função HttpReceiveRequestEntityBody pode ser usada para recuperar o corpo da entidade ou uma segunda chamada pode ser feita para HttpReceiveHttpRequest.

Como alternativa, o buffer fornecido pelo aplicativo pode ser insuficientemente grande para receber toda ou parte da solicitação. Para ter certeza de receber pelo menos parte da solicitação, é recomendável que um aplicativo forneça pelo menos um buffer de 4 KB, que acomoda a maioria das solicitações HTTP. Como alternativa, cabeçalhos de autenticação, analisados como cabeçalhos desconhecidos, podem adicionar até 12 KB a isso, portanto, se a autenticação/autorização for usada, um tamanho de buffer de pelo menos 16 KB será recomendado.

Se HttpReceiveHttpRequest retornar ERROR_MORE_DATA, o aplicativo continuará fazendo chamadas adicionais, identificando a solicitação em cada chamada adicional passando o HTTP_REQUEST. Valor RequestId retornado pela primeira chamada até que ERROR_HANDLE_EOF seja retornado.

Nota O aplicativo deve examinar todos os cabeçalhos de solicitação relevantes, incluindo cabeçalhos de negociação de conteúdo, se usados, e falhar na solicitação conforme apropriado com base no conteúdo do cabeçalho. HttpReceiveHttpRequest garante apenas que a linha de cabeçalho seja terminada corretamente e não contenha caracteres ilegais.

Requisitos


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