Handles HINTERNET dans WinHTTP

Microsoft Windows HTTP Services (WinHTTP) utilise des handles pour effectuer le suivi des paramètres et des informations nécessaires lors de l’utilisation du protocole HTTP. Chaque handle conserve des informations pertinentes pour une session HTTP, une connexion avec un serveur HTTP ou une ressource spécifique. Cette rubrique décrit les différents types de handles, les conventions d’affectation de noms pour ces handles et leur structure hiérarchique.

• À propos des handles HINTERNET
• Descripteurs d’affectation de noms
• Gérer la hiérarchie
• Explication de la hiérarchie de handles

À propos des handles HINTERNET

Les handles créés et utilisés par WinHTTP sont appelés handles HINTERNET . Les fonctions WinHTTP retournent des handles HINTERNET qui ne sont pas interchangeables avec d’autres handles, de sorte qu’ils ne peuvent pas être utilisés avec des fonctions telles que ReadFile ou CloseHandle. De même, d’autres handles ne peuvent pas être utilisés avec les fonctions WinHTTP. Par exemple, un handle retourné par CreateFile ne peut pas être passé à WinHttpReadData. Ces handles HINTERNET ne peuvent pas être fermés pendant qu’un appel d’API utilisant le handle est en cours. Pour éviter une condition de concurrence, les applications doivent protéger le handle et empêcher sa fermeture tant que l’appel d’API est en cours.

Les fonctions Microsoft Win32 Internet (WinInet) utilisent également des descripteurs HINTERNET . Toutefois, les handles utilisés dans les fonctions WinInet ne peuvent pas être échangés avec les handles utilisés dans les fonctions WinHTTP. Pour plus d’informations sur WinInet, consultez À propos de WinINet.

La fonction WinHttpCloseHandle ferme les handles WinHTTP HINTERNET .

Descripteurs d’affectation de noms

Dans la documentation WinHTTP, les descriptions des fonctions dans l’interface de programmation d’application (API) et l’exemple de code montrent la création et l’utilisation de différents types de handles HINTERNET . Pour effectuer le suivi des différents types de handles disponibles, le nommage de ces handles est cohérent. Le tableau suivant présente les identificateurs utilisés par convention dans la documentation.

Type de handle	Handle de création de fonction	Identificateur
Handle générique	WinHttpOpen, WinHttpConnect ou WinHttpOpenRequest	hInternet
Handle de session	WinHttpOpen	hSession
Handle de connexion	WinHttpConnect	hConnect
Handle de requête	WinHttpOpenRequest	hRequest
Handle Web Socket	WinHttpWebSocketCompleteUpgrade	hWebSocket

Gérer la hiérarchie

Les handles HINTERNET sont conservés dans une hiérarchie. Le handle retourné par WinHttpOpen est le handle HINTERNET de session. L’appel de WinHttpOpen initialise les fonctions WinHTTP et commence un contexte de session qui conserve les informations et les paramètres utilisateur tout au long de la durée de vie du handle de session. WinHttpConnect spécifie un serveur HTTP ou HTTPS cible et crée un handle HINTERNET de connexion. Par défaut, le handle de connexion hérite des paramètres du handle de session. Chaque ressource spécifiée avec un appel à WinHttpOpenRequest se voit attribuer un handle HINTERNET de requête.

Le diagramme suivant illustre la hiérarchie des handles HINTERNET . Chaque zone du diagramme représente une fonction WinHTTP qui retourne un handle HINTERNET .

Après la fermeture d’un handle, l’application doit être prête à recevoir des notifications de rappel sur le handle jusqu’à ce que la valeur WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED finale soit retournée pour indiquer que le handle est complètement fermé (ou jusqu’à ce que l’application effectue sa propre synchronisation équivalente, comme le suivi et l’attente de rappels d’opérations asynchrones en attente et s’assurer qu’aucune autre opération n’est tentée à l’aide de ce handle).

Un handle de session est appelé parent de tout handle de connexion qu’il a utilisé pour créer ; De même, le handle de connexion et son handle de session parent sont appelés parents de tout handle de requête que le handle de connexion est utilisé pour créer.

Lorsqu’un handle parent est fermé, tous les enfants qu’il a sont indirectement invalidés, même s’ils ne sont pas fermés eux-mêmes, et les demandes suivantes qui les utilisent échouent avec l’erreur ERROR_INVALID_HANDLE. Les demandes asynchrones en attente ne peuvent pas être utilisées pour se terminer correctement.

Le diagramme suivant montre les fonctions qui utilisent le handle HINTERNET créé par WinHttpOpenRequest. Les zones ombrées représentent les fonctions WinHTTP qui créent des handles, et les zones simples affichent les fonctions qui utilisent ces handles HINTERNET . Le diagramme est également organisé pour afficher l’ordre dans lequel les fonctions WinHTTP sont normalement appelées.

Explication de la hiérarchie de handles

Tout d’abord, un handle de session est créé avec WinHttpOpen. WinHttpConnect nécessite le handle de session comme premier paramètre et retourne un handle de connexion pour un serveur spécifié. Un handle de requête est créé par WinHttpOpenRequest, qui utilise le handle de connexion créé par WinHttpConnect. Si l’application choisit d’ajouter des en-têtes supplémentaires à la demande, ou s’il est nécessaire pour l’application de définir des informations d’identification pour l’authentification, WinHttpAddRequestHeaders et WinHttpSetCredentials peuvent être appelés à l’aide de ce handle de requête. La requête est envoyée par WinHttpSendRequest, qui utilise le handle de requête. Après l’envoi de la demande, des données supplémentaires peuvent être envoyées au serveur à l’aide de WinHttpWriteData, ou l’application peut passer directement à WinHttpReceiveResponse pour spécifier qu’aucune information supplémentaire n’est envoyée au serveur. À ce stade, selon l’objectif de l’application, le handle de requête peut être utilisé pour appeler WinHttpQueryHeaders, WinHttpQueryAuthSchemes ou récupérer une ressource avec WinHttpQueryDataAvailable et WinHttpReadData.

Sockets web dans la hiérarchie des handles

Un handle de socket web hérite des handles de connexion et de session et occupe une position similaire dans la hiérarchie des handles comme un handle de requête. Pour créer un handle de socket web, un handle de demande doit exister ; mais une fois le handle de socket web créé, la requête peut être fermée et le handle de socket web continue de fonctionner.