Fonction HttpSendResponseEntityBody (http.h)

Article
02/28/2024

La fonction HttpSendResponseEntityBody envoie des données de corps d’entité associées à une réponse HTTP.

Syntaxe

HTTPAPI_LINKAGE ULONG HttpSendResponseEntityBody(
  [in]           HANDLE           RequestQueueHandle,
  [in]           HTTP_REQUEST_ID  RequestId,
  [in]           ULONG            Flags,
  [in]           USHORT           EntityChunkCount,
  [in]           PHTTP_DATA_CHUNK EntityChunks,
  [out]          PULONG           BytesSent,
  [in]           PVOID            Reserved1,
  [in]           ULONG            Reserved2,
  [in]           LPOVERLAPPED     Overlapped,
  [in, optional] PHTTP_LOG_DATA   LogData
);

Paramètres

[in] RequestQueueHandle

Handle de la file d’attente des requêtes à partir de laquelle la requête spécifiée a été récupérée. 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

Identificateur de la requête HTTP à laquelle cette réponse correspond. Cette valeur est retournée dans le membre RequestId de la structure HTTP_REQUEST par un appel à la fonction HttpReceiveHttpRequest . Il ne peut pas être HTTP_NULL_ID.

[in] Flags

Paramètre qui peut inclure l’une des valeurs d’indicateur mutuellement exclusives suivantes.

Indicateurs	Signification
HTTP_SEND_RESPONSE_FLAG_DISCONNECT	La connexion réseau doit être déconnectée après l’envoi de cette réponse, en remplaçant toutes les fonctionnalités de connexion persistantes associées à la version de HTTP en cours d’utilisation. Les applications doivent utiliser cet indicateur pour indiquer la fin de l’entité dans les cas où ni la longueur du contenu ni l’encodage segmenté ne sont utilisés.
HTTP_SEND_RESPONSE_FLAG_MORE_DATA	Les données de corps d’entité supplémentaires pour cette réponse sont envoyées par l’application via un ou plusieurs appels ultérieurs à HttpSendResponseEntityBody. Le dernier appel définit ensuite cet indicateur sur zéro.
HTTP_SEND_RESPONSE_FLAG_BUFFER_DATA	Cet indicateur permet la mise en mémoire tampon des données dans le noyau par réponse. Il doit être utilisé par une application effectuant des E/S synchrones, ou par une application effectuant des E/S asynchrones sans qu’un envoi soit en attente à la fois. Les applications utilisant des E/S asynchrones qui peuvent avoir plusieurs envois en attente à la fois ne doivent pas utiliser cet indicateur. Lorsque cet indicateur est défini, il doit également être utilisé de manière cohérente dans les appels à la fonction HttpSendHttpResponse . Windows Server 2003 : Cet indicateur n’est pas pris en charge. Cet indicateur est nouveau pour Windows Server 2003 avec SP1.
HTTP_SEND_RESPONSE_FLAG_ENABLE_NAGLING	Active l’algorithme de nagling TCP pour cet envoi uniquement. Windows Vista et versions ultérieures : Cet indicateur n’est pas pris en charge.
HTTP_SEND_RESPONSE_FLAG_PROCESS_RANGES	Spécifie que pour une demande de plage, le contenu de la réponse complète est passé et que l’appelant souhaite que l’API HTTP traite les plages de manière appropriée. Note Cet indicateur est uniquement pris en charge pour les réponses aux requêtes HTTP GET et offre un sous-ensemble limité de fonctionnalités. Les applications qui nécessitent un traitement complet doivent l’exécuter en mode utilisateur et ne pas s’appuyer sur HTTP.sys. Son utilisation est déconseillée. Windows Server 2008 R2 et Windows 7 ou version ultérieure. Note Cet indicateur est pris en charge.
HTTP_SEND_RESPONSE_FLAG_OPAQUE	Spécifie que la requête/réponse n’est pas conforme à HTTP et que tous les octets suivants doivent être traités en tant que corps d’entité. Les applications spécifient cet indicateur lorsqu’elles acceptent une demande de mise à niveau web socket et informent HTTP.sys de traiter les données de connexion comme des données opaques. Cet indicateur n’est autorisé que lorsque le membre StatusCode de pHttpResponse est 101 et change de protocole. HttpSendResponseEntityBody retourne ERROR_INVALID_PARAMETER pour tous les autres types de réponse HTTP si cet indicateur est utilisé. Windows 8 et versions ultérieures : cet indicateur est pris en charge.

Attention La combinaison des deux indicateurs dans un seul appel à la fonction HttpSendHttpResponse produit des résultats non définis.

[in] EntityChunkCount

Un certain nombre de structures dans le tableau pointées par pEntityChunks. Ce nombre ne peut pas dépasser 9999.

[in] EntityChunks

Pointeur vers un tableau de structures HTTP_DATA_CHUNK à envoyer en tant que données de corps d’entité.

[out] BytesSent

facultatif. Pointeur vers une variable qui reçoit le nombre, en octets, envoyé si la fonction fonctionne de manière synchrone.

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

[in] Reserved1

Ce paramètre est réservé et doit être NULL.

[in] Reserved2

Ce paramètre est réservé et doit être égal à zéro.

[in] 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 que toutes les données de réponse spécifiées dans le paramètre pEntityChunks soient envoyées , tandis qu’un appel asynchrone retourne immédiatement ERROR_IO_PENDING et que 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 superposées.

[in, optional] LogData

Pointeur vers la structure HTTP_LOG_DATA utilisée pour journaliser la réponse. Passez un pointeur à la structure HTTP_LOG_FIELDS_DATA et convertissez-le en PHTTP_LOG_DATA.

N’oubliez pas que même lorsque la journalisation est activée sur un groupe d’URL ou une session serveur, la réponse n’est pas journalisée, sauf si l’application fournit la structure des données des champs de journal.

Windows Server 2003 et Windows XP avec SP2 : Ce paramètre est réservé et doit être NULL.

Windows Vista et Windows Server 2008 : Ce paramètre est nouveau pour Windows Vista et Windows Server 2008

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 qu’elle est récupérée ultérieurement par le biais de 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_BAD_COMMAND	Un appel est en attente vers HttpSendHttpResponse ou HttpSendResponseEntityBody ayant le même RequestId.
Autres	Code d’erreur système défini dans WinError.h.

Remarques

Si ni un en-tête de longueur de contenu ni un en-tête d’encodage de transfert ne sont inclus dans les en-têtes de réponse, l’application doit indiquer la fin de la réponse en fermant explicitement la connexion à l’aide de l’indicateur HTTP_SEND_RESPONSE_DISCONNECT .

RemarqueHttpSendResponseEntityBody (ou HttpSendHttpResponse) et HttpSendResponseEntityBody ne doivent pas être appelés simultanément à partir de threads différents sur le même RequestId.

Configuration requise

Condition requise	Valeur
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