Routines d’achèvement HTTP

Les applications ont plusieurs options pour recevoir des indications d’achèvement et fournir une certaine flexibilité aux développeurs. Les options doivent être bloquées en attendant qu’un appel d’API se termine ou utilise des routines d’achèvement pour les opérations asynchrones. L’avantage de l’utilisation d’opérations asynchrones est une augmentation de la réactivité de l’application.

E/S bloquées

Les applications peuvent bloquer en attendant que l’appel d’API se termine en définissant la structure deSE CHEVAUCHER sur NULL. Cela bloque vraiment toutes les opérations sur le thread. Par exemple, dans les appels à HttpWaitForDisconnect, les appels se bloquent jusqu’à ce que la connexion soit interrompue.

E/S asynchrones

Les applications qui préfèrent ne pas bloquer peuvent utiliser la structure SE CHEVAUCHER pour obtenir les résultats d’achèvement. L’application fournit un pointeur vers une structure de QUI SE CHEVAUCHE, qui est utilisée avec un objet événement ou un port d’achèvement. Avec un port d’achèvement d’E/S, un handle HTTP est utilisé comme handle de fichier dans une opération d’E/S de fichier asynchrone. Le tableau suivant récapitule les options d’achèvement disponibles pour les applications.

Structure superposée	Objet Event	Port d’achèvement	Achèvement
NULL	Sans objet	Ignoré	L’opération se termine de façon synchrone.
NULL non	NULL non	NULL	L’opération se termine de manière asynchrone. Une notification superposée est effectuée en signalant un objet d’événement.
NULL non	Ignoré	NULL non	L’opération se termine de manière asynchrone. Une notification superposée est effectuée en planifiant une routine d’achèvement.

 

Renvoi du nombre d’octets en lecture

Certaines des fonctions qui utilisent la structure deSE CHEVAUCHER pour la saisie semi-automatique asynchrone retournent un paramètre pBytesReceived (ou pBytesSent ou pBytesRead) qui indique le nombre d’octets transférés de manière synchrone. Pour les appels asynchrones, ce paramètre doit être défini sur NULL. Pour les appels synchrones, le paramètre pBytesReceived est facultatif et peut être NULL ou nonNULL.

Si l’objet d’événement est utilisé pour l’achèvement asynchrone, la fonction GetOverlappedResult est appelée pour déterminer le nombre d’octets lus. Si le port d’achèvement est utilisé (le paramètre hFile est associé à un port d’achèvement d’E/S), l’application appelle la fonction GetQueuedCompletionStatus pour déterminer le nombre d’octets lus. Si les opérations asynchrones n’ont pas été effectuées, les applications peuvent appeler la fonction GetLastError pour obtenir des informations d’erreur étendues.

Le tableau suivant résume le comportement d’achèvement pour l’achèvement synchrone et asynchrone dans les fonctions telles que HttpReceiveHttpRequest qui utilisent le paramètre pBytesReceived.

pBytesReceived*	pOverlapped	Description
NULL	NULL	L’application ne reçoit pas d’informations sur le nombre d’octets retournés.
NULL	NULL non	L’opération asynchrone, pBytesReceived est sans signification.
NULL non	NULL	Opération synchrone, nombre d’octets retournés dans pBytesReceived.
NULL non	NULL non	L’opération asynchrone, pBytesReceived est ignorée même si elle n’est pas NULL.**

 

Note

*Ce paramètre peut également être pBytesSent ou pBytesRead.

 

Note

**Il est recommandé que les applications passent une NULL dans pBytesReceived pour les opérations asynchrones et obtiennent le nombre d’octets reçus de GetOverlappedResult ou GetQueuedCompletionStatus.

 

Codes de retour

L’API serveur HTTP retourne trois classes de codes pour les appels de fonction asynchrones.

• NO_ERROR
• ERROR_IO_PENDING
• Tout autre code d’erreur système .

Lorsque ERROR_IO_PENDING ou NO_ERROR sont retournés à partir de l’appel de fonction asynchrone, les utilisateurs doivent s’attendre à ce que la routine d’événement ou d’achèvement soit signalée. L’appel de la fonction GetOverlappedResult pour l’événement ou la fonction GetQueuedCompletionStatus pour le port d’achèvement retourne l’état d’achèvement. En outre, si NO_ERROR est retournée, les applications peuvent effectuer un post-traitement sur le même thread que celui qui a effectué l’appel d’API.

Si l’API serveur HTTP retourne autre chose que ERROR_IO_PENDING ou NO_ERROR, à partir de l’appel de fonction asynchrone, la routine d’achèvement n’est pas signalée et l’erreur est directement retournée par l’API.