Funzione WinHttpCloseHandle (winhttp.h)

Articolo
03/13/2024

La funzione WinHttpCloseHandle chiude un singolo handle DELL'INTERFACCIA UTENTE (vedere HANDLE DI RETE IN WINHTTP).

Sintassi

WINHTTPAPI BOOL WinHttpCloseHandle(
  [in] HINTERNET hInternet
);

Parametri

[in] hInternet

Un handle DELL'OGGETTO WEB VALIDO (vedere Handle DI RETE DELL'AMBIENTE IN WINHTTP) da chiudere.

Valore restituito

TRUE se l'handle viene chiuso correttamente; in caso contrario , FALSE. Per informazioni dettagliate sull'errore, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codici errore	Descrizione
ERROR_WINHTTP_SHUTDOWN	Il supporto della funzione WinHTTP viene arrestato o scaricato.
ERROR_WINHTTP_INTERNAL_ERROR	Si è verificato un errore interno.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Commenti

Anche quando WinHTTP viene usato in modalità asincrona , ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione funziona in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se è presente un callback di stato registrato per l'handle da chiudere e l'handle è stato creato con un valore di contesto non NULL , viene eseguito un callback WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Si tratta dell'ultimo callback eseguito dall'handle e indica che l'handle viene eliminato definitivamente.

Un'applicazione può terminare una richiesta asincrona in corso chiudendo l'handle di richiesta DELL'interfaccia UTENTE con WinHttpCloseHandle. Tieni presenti i punti seguenti:

Dopo che un'applicazione chiama WinHttpCloseHandle in un handle WinHTTP, non può chiamare altre funzioni API WinHTTP usando tale handle da qualsiasi thread.
Anche dopo la restituzione di una chiamata a WinHttpCloseHandle , l'applicazione deve comunque essere pronta a ricevere i callback per l'handle chiuso, perché WinHTTP può rimuovere l'handle in modo asincrono. Se la richiesta asincrona non è stata completata correttamente, il callback riceve una notifica di WINHTTP_CALLBACK_STATUS_REQUEST_ERROR.
Se un'applicazione associa una struttura o un oggetto di dati di contesto all'handle, deve mantenere tale associazione fino a quando la funzione di callback non riceve una notifica di WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING . Si tratta dell'ultima notifica di callback inviata da WinHTTP prima di eliminare un oggetto handle dalla memoria. Per ricevere la notifica di callback WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, l'applicazione deve abilitare il flag WINHTTP_CALLBACK_FLAG_HANDLES nella chiamata WinHttpSetStatusCallback .
Prima di chiamare WinHttpCloseHandle, un'applicazione può chiamare WinHttpSetStatusCallback per indicare che non devono essere eseguiti altri callback:
WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );

Potrebbe sembrare che la struttura dei dati di contesto possa essere liberata immediatamente anziché dover attendere una notifica di WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING , ma questo non è il caso: WinHTTP non sincronizza WinHttpSetStatusCallback con i callback originati nei thread di lavoro. Di conseguenza, un callback potrebbe essere già in corso da un altro thread e l'applicazione potrebbe ricevere una notifica di callback anche dopo avere edout NULL il puntatore alla funzione di callback ed eliminato la struttura dei dati di contesto dell'handle. A causa di questa potenziale race condition, essere conservativi nel liberare la struttura del contesto fino a quando non dopo aver ricevuto la notifica di WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING .

Un'applicazione non deve mai chiamare WinHttpCloseHandle in una richiesta sincrona. Ciò può creare una race condition. Per altre informazioni , vedere HANDLE DI RETE IN WINHTTP .

Nota Per Windows XP e Windows 2000, vedere la sezione Requisiti di runtime della pagina iniziale di WinHttp.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP, Windows 2000 Professional con SP3 [solo app desktop]
Server minimo supportato	Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winhttp.h
Libreria	Winhttp.lib
DLL	Winhttp.dll
Componente ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.