Descripteurs 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 descripteur conserve les 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 descripteurs, les conventions d’affectation de noms pour ces handles et leur structure hiérarchique.

À propos des handles HINTERNET

Les handles qui sont 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, donc ils ne peuvent pas être utilisés avec des fonctions telles que ReadFile ou CloseHandle. De même, les 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 lorsqu’un appel d’API utilisant le descripteur est en cours. Pour éviter une condition de concurrence, les applications doivent protéger le descripteur et l’empêcher d’être fermé tant que l’appel d’API est en cours.

Les fonctions Microsoft Win32 Internet (WinInet) utilisent également des handles HINTERNET . Toutefois, les handles utilisés dans les fonctions WinInet ne peuvent pas être modifié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 de nommage

Dans la documentation WinHTTP, les descriptions des fonctions dans l’interface de programmation d’applications (API) et l’exemple de code illustrent la création et l’utilisation de différents types de descripteurs HINTERNET . Pour assurer le suivi des différents types de handles disponibles, le nom de ces descripteurs 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, WinHttpConnectou WinHttpOpenRequest hInternet
Handle de session WinHttpOpen hSession
Handle de connexion WinHttpConnect hConnect
Handle de demande WinHttpOpenRequest hRequest

Hiérarchie des handles

Les handles HINTERNET sont conservés dans une hiérarchie. Le handle retourné par WinHttpOpen est le descripteur de HINTERNET de session. L’appel de WinHttpOpen initialise les fonctions WinHTTP et commence un contexte de session qui gère les informations et paramètres utilisateur pendant toute la durée de vie du handle de session. WinHttpConnect spécifie un serveur HTTP ou https cible et crée un handle de HINTERNET de connexion. Par défaut, le handle de connexion hérite des paramètres pour le handle de session. Chaque ressource spécifiée avec un appel à WinHttpOpenRequest est affectée à un descripteur de 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 .

fonctions qui créent des handles

Après avoir fermé un handle, l’application doit être préparée à recevoir des notifications de rappel sur le descripteur jusqu’à ce que la valeur finale du _ handle d’état de rappel _ _ _ WinHTTP soit retournée pour indiquer que le handle est complètement fermé.

Un descripteur de session est appelé le parent d’un handle de connexion qu’il a utilisé pour créer ; de même, le descripteur de connexion et son descripteur de session parent sont les parents de tous les descripteurs de demande que le handle de connexion est utilisé pour créer.

Lorsqu’un descripteur parent est fermé, les enfants qu’il a sont invalidés indirectement, même s’ils ne se ferment pas eux-mêmes, et les demandes ultérieures qui les utilisent échouent avec l’erreur erreur _ _ handle non valide. Les demandes asynchrones en attente ne peuvent pas être exécutées correctement.

Le diagramme suivant montre les fonctions qui utilisent le handle HINTERNET créé par WinHttpOpenRequest. Les zones ombrées représentent des 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 indiquer l’ordre dans lequel les fonctions WinHTTP sont normalement appelées.

fonctions qui créent des handles

Explication de la hiérarchie des handles

Tout d’abord, un descripteur de session est créé avec WinHttpOpen. WinHttpConnect requiert le descripteur de session comme premier paramètre et retourne un handle de connexion pour un serveur spécifié. Un handle de demande 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 si elle est nécessaire pour que l’application définisse des informations d’identification pour l’authentification, WinHttpAddRequestHeaders et WinHttpSetCredentials peuvent être appelés à l’aide de ce handle de demande. La demande est envoyée par WinHttpSendRequest, qui utilise le handle de demande. 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 indiquer qu’aucune information supplémentaire n’est envoyée au serveur. À ce stade, en fonction de l’objectif de l’application, le descripteur de demande peut être utilisé pour appeler WinHttpQueryHeaders, WinHttpQueryAuthSchemesou récupérer une ressource avec WinHttpQueryDataAvailable et WinHttpReadData.