Fonction HttpReceiveHttpRequest (http.h)
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 |
|---|---|
|
Seuls les en-têtes de requête sont récupérés ; le corps de l’entité n’est pas copié. |
|
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é. |
|
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 |
|---|---|
|
Un ou plusieurs des paramètres fournis sont sous une forme inutilisable. |
|
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 . |
|
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. |
|
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é. |
|
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é.
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 |