HINTERNET-Handles in WinHTTP

  • Artikel

Microsoft Windows HTTP Services (WinHTTP) verwendet Handles, um Einstellungen und Informationen nachzuverfolgen, 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 Typen von Handles, die Benennungskonventionen für diese Handles und ihre hierarchische Struktur beschrieben.

Informationen zu HINTERNET-Handles

Die von WinHTTP erstellten und verwendeten Handles werden als HINTERNET-Handles bezeichnet. 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 das Handle schützen und verhindern, dass es geschlossen wird, solange der API-Aufruf ausgeführt wird.

Microsoft Win32 Internet-Funktionen (WinInet) 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 Informationen zu WinINet.

Die WinHttpCloseHandle-Funktion schließt WinHTTP HINTERNET-Handles .

Benennungshandles

In der gesamten WinHTTP-Dokumentation zeigen Beschreibungen der Funktionen in der Anwendungsprogrammierschnittstelle (API) und Beispielcode die Erstellung und Verwendung verschiedener Typen von HINTERNET-Handles . Um die verschiedenen verfügbaren Typen von Handles nachzuverfolgen, ist die Benennung dieser Handles konsistent. Die folgende Tabelle zeigt die von der Konvention verwendeten Bezeichner in der Dokumentation.

Handle-Typ Funktionserstellungshandle Bezeichner
Generisches Handle WinHttpOpen, WinHttpConnect oder WinHttpOpenRequest hInternet
Sitzungshandle WinHttpOpen hSession
Verbindungshandle WinHttpConnect hConnect
Anforderungshandle WinHttpOpenRequest hRequest
Websockethandle WinHttpWebSocketCompleteUpgrade hWebSocket

Behandeln der Hierarchie

Die HINTERNET-Handles werden in einer Hierarchie verwaltet. Das von WinHttpOpen zurückgegebene Handle ist das HINTERNET-Sitzungshandle. Beim Aufrufen von WinHttpOpen werden die WinHTTP-Funktionen initialisiert und ein Sitzungskontext gestartet, der Benutzerinformationen und -einstellungen während der gesamten Lebensdauer des Sitzungshandles verwaltet. WinHttpConnect gibt einen HTTP- oder HTTPS-Zielserver an und erstellt ein HINTERNET-Verbindungshandle . Standardmäßig erbt das Verbindungshandle die Einstellungen für das Sitzungshandle. Jeder Ressource, die mit einem Aufruf von WinHttpOpenRequest angegeben wird, wird ein HINTERNET-Anforderungshandle zugewiesen.

Das folgende Diagramm veranschaulicht die Hierarchie der HINTERNET-Handles . Jedes Feld im Diagramm stellt eine WinHTTP-Funktion dar, die ein HINTERNET-Handle zurückgibt.

Funktionen, die Handles erstellen

Nach dem Schließen eines Handles muss die Anwendung darauf vorbereitet sein, Rückrufbenachrichtigungen für das Handle zu empfangen, bis der endgültige WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED-Wert zurückgegeben wird, um anzugeben, dass das Handle vollständig geschlossen ist (oder bis die Anwendung eine eigene gleichwertige Synchronisierung durchführt, z. B. das Nachverfolgen und Warten auf Rückrufe aus ausstehenden asynchronen Vorgängen und sicherstellen, dass mit diesem Handle keine weiteren Vorgänge versucht werden).

Ein Sitzungshandle wird als übergeordnetes Element jedes Verbindungshandles bezeichnet, das zum Erstellen verwendet wird. Ebenso werden sowohl das Verbindungshandle als auch sein übergeordnetes Sitzungshandle als übergeordnetes Element jedes Anforderungshandles bezeichnet, für das das Verbindungshandle erstellt wird.

Wenn ein übergeordnetes Handle geschlossen wird, werden alle untergeordneten Elemente, über die es verfügt, indirekt ungültig, auch wenn sie nicht selbst geschlossen werden, und nachfolgende Anforderungen, die sie verwenden, schlagen mit dem Fehler ERROR_INVALID_HANDLE fehl. Ausstehende asynchrone Anforderungen können nicht ordnungsgemäß ausgeführt werden.

Das folgende Diagramm zeigt die Funktionen, die das von WinHttpOpenRequest erstellte HINTERNET-Handle verwenden. Die schattierten Felder stellen WinHTTP-Funktionen dar, die Handles erstellen, und die einfachen Felder zeigen die Funktionen an, die diese HINTERNET-Handles verwenden. Das Diagramm ist auch so organisiert, dass die Reihenfolge angezeigt wird, in der WinHTTP-Funktionen normalerweise aufgerufen werden.

Funktionen, die Handles erstellen

Erläuterung der Handlehierarchie

Zunächst wird mit WinHttpOpen ein Sitzungshandle erstellt. WinHttpConnect erfordert das Sitzungshandle als ersten Parameter und gibt ein Verbindungshandle für einen angegebenen Server zurück. Ein Anforderungshandle wird von WinHttpOpenRequest erstellt, das das von WinHttpConnect erstellte Verbindungshandle verwendet. Wenn die Anwendung der Anforderung zusätzliche Header hinzufügt oder wenn die Anwendung Anmeldeinformationen für die Authentifizierung festlegen muss, können WinHttpAddRequestHeaders und WinHttpSetCredentials mithilfe dieses Anforderungshandles aufgerufen werden. Die Anforderung wird von WinHttpSendRequest gesendet, das das Anforderungshandle verwendet. Nach dem Senden der Anforderung können zusätzliche Daten mithilfe von WinHttpWriteData an den Server gesendet werden, oder die Anwendung kann direkt zu WinHttpReceiveResponse überspringen, um anzugeben, dass keine weiteren Informationen an den Server gesendet werden. An diesem Punkt kann das Anforderungshandle je nach Zweck der Anwendung verwendet werden, um WinHttpQueryHeaders, WinHttpQueryAuthSchemes oder eine Ressource mit WinHttpQueryDataAvailable und WinHttpReadData abzurufen.

Websockets in der Handlehierarchie

Ein Websockethandle erbt von den Verbindungs- und Sitzungshandles und nimmt eine ähnliche Position in der Handlehierarchie ein wie ein Anforderungshandle. Zum Erstellen eines Websocketshandles muss ein Anforderungshandle vorhanden sein. Nach dem Erstellen des Websocketshandles wird die Anforderung möglicherweise geschlossen, und das Websockethandle funktioniert weiterhin.