Handle HINTERNET in WinHTTP

Microsoft Windows HTTP Services (WinHTTP) usa handle per tenere traccia delle impostazioni e delle informazioni necessarie quando si usa il protocollo HTTP. Ogni handle gestisce informazioni pertinenti a una sessione HTTP, una connessione con un server HTTP o una risorsa specifica. Questo argomento descrive i vari tipi di handle, le convenzioni di denominazione per questi handle e la relativa struttura gerarchica.

• Informazioni sugli handle DI HINTERNET
• Handle di denominazione
• Gestire la gerarchia
• Spiegazione della gerarchia di handle

Informazioni sugli handle DI HINTERNET

Gli handle creati e usati da WinHTTP sono denominati handle HINTERNET . Le funzioni WinHTTP restituiscono handle HINTERNET che non sono intercambiabili con altri handle, in modo che non possano essere usati con funzioni come ReadFile o CloseHandle. Analogamente, altri handle non possono essere usati con funzioni WinHTTP. Ad esempio, un handle restituito da CreateFile non può essere passato a WinHttpReadData. Questi handle HINTERNET non possono essere chiusi mentre una chiamata API usando l'handle è in corso. Per evitare una condizione di gara, le applicazioni devono proteggere l'handle e impedirne la chiusura fino a quando la chiamata API è in corso.

Le funzioni Microsoft Win32 Internet (WinInet) usano anche handle KPINET . Tuttavia, gli handle usati nelle funzioni WinInet non possono essere interscambiati con gli handle usati nelle funzioni WinHTTP. Per altre informazioni su WinInet, vedere Informazioni su WinINet.

La funzione WinHttpCloseHandle chiude gli handle WINHTTP HINTERNET .

Handle di denominazione

In tutta la documentazione di WinHTTP, le descrizioni delle funzioni nell'interfaccia di programmazione dell'applicazione (API) e il codice di esempio mostrano la creazione e l'uso di vari tipi di handle SHADOWNET . Per tenere traccia dei diversi tipi di handle disponibili, la denominazione di questi handle è coerente. Nella tabella seguente vengono illustrati gli identificatori usati dalla convenzione nella documentazione.

Tipo di handle	Handle di creazione di funzioni	Identificatore
Handle generico	WinHttpOpen, WinHttpConnect o WinHttpOpenRequest	hInternet
Handle sessione	WinHttpOpen	hSession
Handle di connessione	WinHttpConnect	hConnect
Handle di richiesta	WinHttpOpenRequest	hRequest
Handle Web Socket	WinHttpWebSocketCompleteUpgrade	hWebSocket

Gestire la gerarchia

Gli handle HINTERNET vengono mantenuti in una gerarchia. L'handle restituito da WinHttpOpen è l'handle SESSION HINTERNET . La chiamata a WinHttpOpen inizializza le funzioni WinHTTP e inizia un contesto di sessione che gestisce le informazioni utente e le impostazioni durante la vita dell'handle di sessione. WinHttpConnect specifica un server HTTP o HTTPS di destinazione e crea un handle DI CONNESSIONE HINTERNET . Per impostazione predefinita, l'handle di connessione eredita le impostazioni per l'handle di sessione. Ogni risorsa specificata con una chiamata a WinHttpOpenRequest viene assegnata a un handle DI RICHIESTA HINTERNET .

Il diagramma seguente illustra la gerarchia degli handle DI HINTERNET . Ogni casella nel diagramma rappresenta una funzione WinHTTP che restituisce un handle HINTERNET .

Dopo aver chiuso un handle, l'applicazione deve essere preparata per ricevere notifiche di callback nell'handle fino a quando il valore di WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED finale non viene restituito per indicare che l'handle è completamente chiuso (o finché l'applicazione esegue la propria sincronizzazione equivalente, ad esempio il rilevamento e l'attesa di eventuali callback dalle operazioni asincrone in sospeso e garantire che non vengano tentate ulteriori operazioni tramite tale handle).

Un handle di sessione viene definito padre di qualsiasi handle di connessione usato per creare; analogamente, sia l'handle di connessione che il relativo handle di sessione padre sono i genitori di qualsiasi handle di richiesta usato per creare l'handle di connessione.

Quando un handle padre è chiuso, tutti gli elementi figlio che ha indirettamente invalidato anche se non sono chiuse e le richieste successive che li usano non riescono con l'errore ERROR_INVALID_HANDLE. Le richieste asincrone in sospeso non possono essere eseguite correttamente.

Il diagramma seguente illustra le funzioni che usano l'handle HINTERNET creato da WinHttpOpenRequest. Le caselle ombreggiate rappresentano le funzioni WinHTTP che creano handle e le caselle di tipo normale mostrano le funzioni che usano tali handle HINTERNET . Il diagramma è organizzato anche per mostrare l'ordine in cui vengono normalmente chiamate le funzioni WinHTTP.

Spiegazione della gerarchia di handle

Prima di tutto, viene creato un handle di sessione con WinHttpOpen. WinHttpConnect richiede l'handle di sessione come primo parametro e restituisce un handle di connessione per un server specificato. Un handle di richiesta viene creato da WinHttpOpenRequest, che usa l'handle di connessione creato da WinHttpConnect. Se l'applicazione sceglie di aggiungere intestazioni aggiuntive alla richiesta oppure se è necessario che l'applicazione imposta le credenziali per l'autenticazione, WinHttpAddRequestHeaders e WinHttpSetCredentials può essere chiamato usando questo handle di richiesta. La richiesta viene inviata da WinHttpSendRequest, che usa l'handle della richiesta. Dopo l'invio della richiesta, è possibile inviare dati aggiuntivi al server usando WinHttpWriteData oppure l'applicazione può passare direttamente a WinHttpReceiveResponse per specificare che non vengono inviate altre informazioni al server. A questo punto, a seconda dello scopo dell'applicazione, l'handle di richiesta può essere usato per chiamare WinHttpQueryHeaders, WinHttpQueryAuthSchemes o recuperare una risorsa con WinHttpQueryDataAvailable e WinHttpReadData.

Socket Web nella gerarchia di handle

Un handle del socket Web eredita dagli handle di connessione e sessione e occupa una posizione simile nella gerarchia di handle come handle di richiesta. Per creare un handle del socket Web, è necessario che esista un handle di richiesta; ma una volta creato l'handle del socket Web, la richiesta potrebbe essere chiusa e l'handle del socket Web continuerà a funzionare.