Fonction WinHttpCloseHandle (winhttp.h)

Article
08/27/2023

La fonction WinHttpCloseHandle ferme un seul handle HINTERNET (voir Handles HINTERNET dans WinHTTP).

Syntaxe

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Paramètres

[in] hInternet

Un handle HINTERNET valide (voir Handles HINTERNET dans WinHTTP) à fermer.

Valeur retournée

TRUE si le handle est correctement fermé, sinon FALSE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.

Codes d’erreur	Description
ERROR_WINHTTP_SHUTDOWN	La prise en charge de la fonction WinHTTP est en cours d’arrêt ou de déchargement.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows)

Remarques

Même lorsque WinHTTP est utilisé en mode asynchrone (c’est-à-dire, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de manière synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

S’il existe un rappel status inscrit pour le handle en cours de fermeture et que le handle a été créé avec une valeur de contexte non NULL, un rappel WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING est effectué. Il s’agit du dernier rappel effectué à partir du handle et indique que le handle est en cours de destruction.

Une application peut mettre fin à une requête asynchrone en cours en fermant le handle de requête HINTERNET à l’aide de WinHttpCloseHandle. Gardez à l’esprit les points suivants :

Une fois qu’une application appelle WinHttpCloseHandle sur un handle WinHTTP, elle ne peut pas appeler d’autres fonctions d’API WinHTTP à l’aide de ce handle à partir d’un thread quelconque.
Même après le retour d’un appel à WinHttpCloseHandle , l’application doit toujours être prête à recevoir des rappels pour le handle fermé, car WinHTTP peut détruire le handle de manière asynchrone. Si la demande asynchrone n’a pas pu se terminer correctement, le rappel reçoit une notification WINHTTP_CALLBACK_STATUS_REQUEST_ERROR.
Si une application associe une structure ou un objet de données de contexte au handle, elle doit conserver cette liaison jusqu’à ce que la fonction de rappel reçoive une notification WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Il s’agit de la dernière notification de rappel envoyée par WinHTTP avant la suppression d’un objet handle de la mémoire. Pour recevoir la notification de rappel WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , l’application doit activer l’indicateur WINHTTP_CALLBACK_FLAG_HANDLES dans l’appel WinHttpSetStatusCallback .
Avant d’appeler WinHttpCloseHandle, une application peut appeler WinHttpSetStatusCallback pour indiquer qu’aucun rappel supplémentaire ne doit être effectué :
WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

Il peut sembler que la structure de données de contexte peut alors être libérée immédiatement au lieu d’attendre une notification WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , mais ce n’est pas le cas : WinHTTP ne synchronise pas WinHttpSetStatusCallback avec les rappels provenant de threads de travail. Par conséquent, un rappel peut déjà être en cours à partir d’un autre thread et l’application peut recevoir une notification de rappel même après avoir supprimé null le pointeur de la fonction de rappel et supprimé la structure de données de contexte du handle. En raison de cette condition de race potentielle, soyez prudent dans la libération de la structure de contexte jusqu’à ce qu’après avoir reçu la notification WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING .

Une application ne doit jamais appeler WinHttpCloseHandle sur une demande synchrone. Cela peut créer une condition de race. Pour plus d’informations, consultez Handles HINTERNET dans WinHTTP .

Note Pour Windows XP et Windows 2000, consultez la section Conditions d’exécution de la page de démarrage WinHttp.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll
Composant redistribuable	WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000.