HINTERNET-Handles in WinHTTP
Microsoft Windows HTTP Services (WinHTTP) verwendet Handles, um einstellungen und Informationen zu verfolgen, die bei Verwendung des HTTP-Protokolls erforderlich sind. Jedes Handle verwaltet Informationen, die für eine HTTP-Sitzung, eine Verbindung mit einem HTTP-Server oder eine bestimmte Ressource relevant sind. In diesem Thema werden die verschiedenen Arten von Handles, die Benennungskonventionen für diese Handles und ihre hierarchische Struktur beschrieben.
- Informationen zu HINTERNET-Handles
- Namenshandles
- Hierarchie- behandeln
- Erläuterung der Handlehierarchie
Informationen zu HINTERNET-Handles
Die von WinHTTP erstellten und verwendeten Handles werden HINTERNET- Handles aufgerufen. Die WinHTTP-Funktionen geben HINTERNET Handles zurück, die nicht mit anderen Handles austauschbar sind, sodass sie nicht mit Funktionen wie ReadFile- oder CloseHandle-verwendet werden können. Ebenso können andere Handles nicht mit WinHTTP-Funktionen verwendet werden. Ein von CreateFile- zurückgegebenes Handle kann beispielsweise nicht an WinHttpReadData-übergeben werden. Diese HINTERNET- Handles können nicht geschlossen werden, während ein API-Aufruf mit dem Handle ausgeführt wird. Um eine Racebedingung zu vermeiden, sollten Anwendungen den Handle schützen und verhindern, dass sie geschlossen werden, solange der API-Aufruf ausgeführt wird.
Microsoft Win32 Internet(WinInet)-Funktionen verwenden auch HINTERNET- Handles. Die in WinInet-Funktionen verwendeten Handles können jedoch nicht mit den in WinHTTP-Funktionen verwendeten Handles ausgetauscht werden. Weitere Informationen zu WinInet finden Sie unter Über WinINet-.
Die WinHttpCloseHandle--Funktion schließt WinHTTP HINTERNET- Handles.
Benennungshandles
In der WinHTTP-Dokumentation zeigen Beschreibungen von Funktionen in der Anwendungsprogrammierschnittstelle (API) und Beispielcode die Erstellung und Verwendung verschiedener Arten von HINTERNET- Handles. Um die verschiedenen Arten von Handles nachzuverfolgen, ist die Benennung dieser Handles konsistent. In der folgenden Tabelle sind die in der Dokumentation verwendeten Bezeichner aufgeführt.
| Handle-Typ | Funktionserstellungshandle | Bezeichner |
|---|---|---|
| Generisches Handle | WinHttpOpen, WinHttpConnectoder WinHttpOpenRequest | hInternet |
| Sitzungshandle | WinHttpOpen | hSession |
| Verbindungsziehpunkt | WinHttpConnect- | hConnect |
| Anforderungshandle | WinHttpOpenRequest | hRequest |
| Web Sockethandle | WinHttpWebSocketCompleteUpgrade- | hWebSocket |
Behandeln der Hierarchie
Die HINTERNET- Handles werden in einer Hierarchie verwaltet. Das von WinHttpOpen zurückgegebene Handle ist die Sitzung HINTERNET- Handle. Das Aufrufen WinHttpOpen initialisiert die WinHTTP-Funktionen und beginnt einen Sitzungskontext, der Benutzerinformationen und -einstellungen während der gesamten Lebensdauer des Sitzungshandle verwaltet. WinHttpConnect- gibt einen ZIEL-HTTP- oder HTTPS-Server an und erstellt eine Verbindung HINTERNET- Handle. Standardmäßig erbt das Verbindungshandle die Einstellungen für das Sitzungshandle. Jeder Ressource, die mit einem Aufruf von WinHttpOpenRequest- angegeben wird, wird eine Anforderung HINTERNET Handle zugewiesen.
Das folgende Diagramm veranschaulicht die Hierarchie von HINTERNET- Handles. Jedes Feld im Diagramm stellt eine WinHTTP-Funktion dar, die ein HINTERNET- Handle zurückgibt.
Nach dem Schließen eines Handles muss die Anwendung bereit sein, Rückrufbenachrichtigungen für das Handle zu empfangen, bis der letzte WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED Wert zurückgegeben wird, um anzugeben, dass das Handle vollständig geschlossen ist (oder bis die Anwendung eine eigene entsprechende Synchronisierung ausführt, z. B. das Nachverfolgen und Warten auf Rückrufe von ausstehenden asynchronen Vorgängen und sicherstellen, dass keine weiteren Vorgänge mit diesem Handle versucht werden).
Ein Sitzungshandle wird als übergeordnetes Element eines Verbindungshandle bezeichnet, das zum Erstellen verwendet wird; Ebenso werden sowohl das Verbindungshandle als auch das übergeordnete Sitzungshandle als übergeordnetes Element eines Anforderungshandle bezeichnet, das zum Erstellen des Verbindungshandles verwendet wird.
Wenn ein übergeordnetes Handle geschlossen wird, werden alle untergeordneten Elemente indirekt ungültig, auch wenn sie nicht selbst geschlossen werden, und nachfolgende Anforderungen, die sie verwenden, schlagen mit dem Fehler ERROR_INVALID_HANDLEfehl. Ausstehende asynchrone Anforderungen können nicht ordnungsgemäß ausgeführt werden.
Das folgende Diagramm zeigt die Funktionen, die das HINTERNET- Handle verwenden, das von WinHttpOpenRequesterstellt wurde. Die schattierten Felder stellen WinHTTP-Funktionen dar, die Handles erstellen, und in den einfachen Feldern werden die Funktionen angezeigt, die diese HINTERNET- Handles verwenden. Das Diagramm ist auch so organisiert, dass die Reihenfolge angezeigt wird, in der WinHTTP-Funktionen normalerweise aufgerufen werden.
Erläuterung der Handlehierarchie
Zunächst wird ein Sitzungshandle mit WinHttpOpenerstellt. WinHttpConnect- erfordert das Sitzungshandle als ersten Parameter und gibt ein Verbindungshandle für einen angegebenen Server zurück. Ein Anforderungshandle wird von WinHttpOpenRequesterstellt, das das von WinHttpConnecterstellte Verbindungshandle verwendet. Wenn die Anwendung der Anforderung zusätzliche Header hinzufügt oder wenn die Anwendung Anmeldeinformationen für die Authentifizierung festlegen muss, WinHttpAddRequestHeaders und WinHttpSetCredentials- mithilfe dieses Anforderungshandle aufgerufen werden können. Die Anforderung wird von WinHttpSendRequestgesendet, das das Anforderungshandle verwendet. Nach dem Senden der Anforderung können zusätzliche Daten mithilfe WinHttpWriteData-an den Server gesendet werden, oder die Anwendung kann direkt zu WinHttpReceiveResponse, um anzugeben, dass keine weiteren Informationen an den Server gesendet werden. Abhängig vom Zweck der Anwendung kann das Anforderungshandle verwendet werden, um WinHttpQueryHeaders, WinHttpQueryAuthSchemesaufzurufen oder eine Ressource mit WinHttpQueryDataAvailable und WinHttpReadDataabzurufen.
Websockets in der Handlehierarchie
Ein Websockethandle erbt von den Verbindungs- und Sitzungshandles und nimmt eine ähnliche Position in der Handlehierarchie ein wie ein Anforderungshandle. Um ein Websockethandle zu erstellen, muss ein Anforderungshandle vorhanden sein; sobald das Websockethandle erstellt wurde, kann die Anforderung geschlossen werden, und der Websockethandle funktioniert weiterhin.