WinHttpCloseHandle-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpCloseHandle-Funktion schließt ein einzelnes HINTERNET-Handle (siehe HINTERNET-Handles in WinHTTP).

Syntax

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Parameter

[in] hInternet

Ein gültiges HINTERNET-Handle (siehe HINTERNET-Handles in WinHTTP), das geschlossen werden soll.

Rückgabewert

TRUE , wenn das Handle erfolgreich geschlossen wurde, andernfalls FALSE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercodes	BESCHREIBUNG
ERROR_WINHTTP_SHUTDOWN	Die WinHTTP-Funktionsunterstützung wird heruntergefahren oder entladen.
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

Hinweise

Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), wird diese Funktion synchron ausgeführt. Der Rückgabewert gibt Erfolg oder Fehler an. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn ein status Rückruf für das zu schließende Handle registriert ist und das Handle mit einem Nicht-NULL-Kontextwert erstellt wurde, wird ein WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING Rückruf durchgeführt. Dies ist der letzte Rückruf aus dem Handle und gibt an, dass das Handle zerstört wird.

Eine Anwendung kann eine in Bearbeitung befindliche asynchrone Anforderung beenden, indem sie das HINTERNET-Anforderungshandle mit WinHttpCloseHandle schließt. Beachten Sie folgende Punkte:

Nachdem eine Anwendung WinHttpCloseHandle für ein WinHTTP-Handle aufgerufen hat, kann sie keine anderen WinHTTP-API-Funktionen aufrufen, die dieses Handle von einem Thread verwenden.
Auch nachdem ein Aufruf von WinHttpCloseHandle zurückgegeben wurde, muss die Anwendung weiterhin darauf vorbereitet sein, Rückrufe für das geschlossene Handle zu empfangen, da WinHTTP das Handle asynchron löschen kann. Wenn die asynchrone Anforderung nicht erfolgreich abgeschlossen werden konnte, erhält der Rückruf eine WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Benachrichtigung.
Wenn eine Anwendung dem Handle eine Kontextdatenstruktur oder ein Objekt zuordnet, sollte diese Bindung beibehalten werden, bis die Rückruffunktion eine WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING Benachrichtigung empfängt. Dies ist die letzte Rückrufbenachrichtigung, die WinHTTP vor dem Löschen eines Handle-Objekts aus dem Arbeitsspeicher sendet. Um die WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING Rückrufbenachrichtigung zu erhalten, muss die Anwendung das flag WINHTTP_CALLBACK_FLAG_HANDLES im WinHttpSetStatusCallback-Aufruf aktivieren.
Vor dem Aufrufen von WinHttpCloseHandle kann eine Anwendung WinHttpSetStatusCallback aufrufen, um anzugeben, dass keine Rückrufe mehr ausgeführt werden sollen:
WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

Es scheint, dass die Kontextdatenstruktur dann sofort freigegeben werden könnte, anstatt auf eine WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING-Benachrichtigung warten zu müssen, aber dies ist nicht der Fall: WinHTTP synchronisiert WinHttpSetStatusCallback nicht mit Rückrufen, die aus Workerthreads stammen. Daher kann bereits ein Rückruf von einem anderen Thread ausgeführt werden, und die Anwendung kann eine Rückrufbenachrichtigung erhalten, auch wenn der Zeiger der Rückruffunktion durch NULL entfernt und die Kontextdatenstruktur des Handles gelöscht wurde. Aufgrund dieser potenziellen Racebedingung, seien Sie vorsichtig bei der Freigabe der Kontextstruktur, bis sie die WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING Benachrichtigung erhalten haben.

Eine Anwendung sollte niemals WinHttpCloseHandle für eine synchrone Anforderung aufrufen. Dadurch kann eine Racebedingung erstellt werden. Weitere Informationen finden Sie unter HINTERNET Handles in WinHTTP .

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHttp-Startseite .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll
Verteilbare Komponente	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)