Fonction HttpReceiveHttpRequest (http.h)

Article
08/24/2023

La fonction HttpReceiveHttpRequest récupère la requête HTTP disponible suivante à partir de la file d’attente de requêtes spécifiée de manière synchrone ou asynchrone.

Syntaxe

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

Paramètres

[in] RequestQueueHandle

Handle de la file d’attente des requêtes à partir de laquelle récupérer la requête disponible suivante. Une file d’attente de requêtes est créée et son handle est retourné par un appel à la fonction HttpCreateRequestQueue .

Windows Server 2003 avec SP1 et Windows XP avec SP2 : Le handle de la file d’attente des requêtes est créé par la fonction HttpCreateHttpHandle .

[in] RequestId

Lors du premier appel pour récupérer une demande, ce paramètre doit être HTTP_NULL_ID. Ensuite, si plusieurs appels sont nécessaires pour récupérer l’intégralité de la requête, HttpReceiveHttpRequest ou HttpReceiveRequestEntityBody peuvent être appelés avec RequestID défini sur la valeur retournée dans le membre RequestId de la structure HTTP_REQUEST pointée par pRequestBuffer.

[in] Flags

Paramètre qui peut être l’une des valeurs suivantes.

Valeur	Signification
0 (zéro)	Seuls les en-têtes de requête sont récupérés ; le corps de l’entité n’est pas copié.
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY	Le corps de l’entité disponible est copié avec les en-têtes de requête. Le membre pEntityChunks de la structure HTTP_REQUEST pointe vers le corps de l’entité.
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY	Tous les corps d’entité sont copiés avec les en-têtes de requête. Le membre pEntityChunks de la structure HTTP_REQUEST pointe vers le corps de l’entité.

[out] RequestBuffer

Pointeur vers une mémoire tampon dans laquelle la fonction copie une structure HTTP_REQUEST et un corps d’entité pour la requête HTTP. HTTP_REQUEST. RequestId contient l’identificateur de cette requête HTTP, que l’application peut utiliser dans les appels suivants HttpReceiveRequestEntityBody, HttpSendHttpResponse ou HttpSendResponseEntityBody.

[in] RequestBufferLength

Taille, en octets, de la mémoire tampon pRequestBuffer .

[out, optional] BytesReturned

Optionnel. Pointeur vers une variable qui reçoit la taille, en octets, du corps de l’entité ou de la partie restante du corps de l’entité.

Lorsque vous effectuez un appel asynchrone à l’aide de pOverlapped, définissez pBytesReceived sur NULL. Sinon, lorsque pOverlapped a la valeur NULL, pBytesReceived doit contenir une adresse mémoire valide et ne doit pas avoir la valeur NULL.

[in, optional] Overlapped

Pour les appels asynchrones, définissez pOverlapped pour qu’il pointe vers une structure CHEVAUCHEMENT . pour les appels synchrones, définissez-le sur NULL.

Un appel synchrone se bloque jusqu’à ce qu’une demande soit arrivée dans la file d’attente spécifiée et qu’une partie ou la totalité de celle-ci ait été récupérée, tandis qu’un appel asynchrone retourne immédiatement ERROR_IO_PENDING et l’application appelante utilise ensuite les ports d’achèvement GetOverlappedResult ou d’E/S pour déterminer quand l’opération est terminée. Pour plus d’informations sur l’utilisation des structures OVERLAPPED pour la synchronisation, consultez
Synchronisation et entrée et sortie qui se chevauchent.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction est utilisée de manière asynchrone, une valeur de retour de ERROR_IO_PENDING indique que la requête suivante n’est pas encore prête et sera récupérée ultérieurement via des mécanismes d’achèvement d’E/S qui se chevauchent normalement.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Valeur	Signification
ERROR_INVALID_PARAMETER	Un ou plusieurs des paramètres fournis sont sous une forme inutilisable.
ERROR_NOACCESS	Un ou plusieurs des paramètres fournis pointent vers une mémoire tampon non valide ou non alignée. Le paramètre pRequestBuffer doit pointer vers une mémoire tampon valide avec un alignement de mémoire égal ou supérieur à l’exigence d’alignement de la mémoire pour une structure de HTTP_REQUEST .
ERROR_MORE_DATA	La valeur de RequestBufferLength est supérieure ou égale à la taille de l’en-tête de requête reçu, mais n’est pas aussi grande que la taille combinée de la structure de la requête et du corps de l’entité. La taille de la mémoire tampon requise pour lire la partie restante du corps de l’entité est retournée dans le paramètre pBytesReceived si ce n’est pas NULL et si l’appel est synchrone. Appelez à nouveau la fonction avec une mémoire tampon suffisamment grande pour récupérer toutes les données.
ERROR_HANDLE_EOF	La requête spécifiée a déjà été entièrement récupérée ; dans ce cas, la valeur pointée par pBytesReceived n’est pas significative et pRequestBuffer ne doit pas être examiné.
Autres	Code d’erreur système défini dans WinError.h.

Notes

Plusieurs appels peuvent être nécessaires pour récupérer une demande donnée. Lorsque le paramètre Flags est défini sur zéro, par exemple, HttpReceiveHttpRequest copie uniquement la structure d’en-tête de requête dans la mémoire tampon et ne tente pas de copier le corps de l’entité. Dans ce cas, la fonction HttpReceiveRequestEntityBody peut être utilisée pour récupérer le corps de l’entité, ou un deuxième appel peut être effectué à HttpReceiveHttpRequest.

Sinon, la mémoire tampon fournie par l’application peut être insuffisante pour recevoir tout ou partie de la demande. Pour être sûr de recevoir au moins une partie de la demande, il est recommandé qu’une application fournisse au moins une mémoire tampon de 4 Ko, qui prend en charge la plupart des requêtes HTTP. Les en-têtes d’authentification, analysés en tant qu’en-têtes inconnus, peuvent également ajouter jusqu’à 12 Ko. Par conséquent, si l’authentification/autorisation est utilisée, une taille de mémoire tampon d’au moins 16 Ko est recommandée.

Si HttpReceiveHttpRequest retourne ERROR_MORE_DATA, l’application continue d’effectuer des appels supplémentaires, en identifiant la demande dans chaque appel supplémentaire en passant le HTTP_REQUEST. Valeur RequestId retournée par le premier appel jusqu’à ce que ERROR_HANDLE_EOF soit retourné.

Note L’application doit examiner tous les en-têtes de requête pertinents, y compris les en-têtes de négociation de contenu s’ils sont utilisés, et faire échouer la demande en fonction du contenu de l’en-tête. HttpReceiveHttpRequest garantit uniquement que la ligne d’en-tête est correctement terminée et ne contient pas de caractères non conformes.

Configuration requise


Client minimal pris en charge	Windows Vista, Windows XP avec SP2 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	http.h
Bibliothèque	Httpapi.lib
DLL	Httpapi.dll