Funzione WinHttpSetStatusCallback (winhttp.h)

Articolo
03/15/2023

La funzione WinHttpSetStatusCallback configura una funzione di callback che WinHTTP può chiamare durante un'operazione.

Sintassi

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

Parametri

[in] hInternet

Handle DI ISTRUZIONENET per il quale deve essere impostato il callback.

[in] lpfnInternetCallback

Puntatore alla funzione di callback da chiamare quando viene eseguito lo stato di avanzamento. Impostare questa proprietà su NULL per rimuovere la funzione di callback esistente. Per altre informazioni sulla funzione di callback, vedere WINHTTP_STATUS_CALLBACK.

[in] dwNotificationFlags

Valore intero long senza segno che specifica i flag per indicare quali eventi attivano la funzione di callback.

I valori possibili sono i seguenti.

Valore	Significato
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	Viene attivato dopo qualsiasi notifica di completamento. Questo flag specifica che vengono usate tutte le notifiche necessarie per le operazioni di lettura o scrittura. Per un elenco dei completamenti, vedere WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	Viene attivato dopo qualsiasi notifica di modifica dello stato, inclusi i completamenti. Per un elenco di notifiche, vedere WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	Viene attivato all'inizio e al completamento della risoluzione dei nomi.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	Viene attivato all'inizio e al completamento della connessione al server.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	Viene attivato durante il rilevamento del server proxy.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	Viene attivato quando si completa una query per i dati.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	Attiva quando le intestazioni di risposta sono disponibili per il recupero.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	Attiva al completamento di un'operazione di lettura dei dati.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	Attiva quando si verifica un errore asincrono.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Attiva all'inizio e completa l'invio di un'intestazione di richiesta con WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	Attiva quando un'intestazione di richiesta è stata inviata con WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	Attiva al termine di un'operazione di post-data.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	Attiva all'inizio e completa la ricezione di una risorsa dal server HTTP.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	Viene attivato all'inizio e al completamento della chiusura di una connessione HTTP.
WINHTTP_CALLBACK_FLAG_HANDLES	Viene attivato quando viene creato o chiuso un handle DELLANET .
WINHTTP_CALLBACK_FLAG_REDIRECT	Viene attivato quando la richiesta viene reindirizzata.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	Viene attivato quando si riceve un messaggio di codice di stato intermedio (livello 100) dal server.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	Si attiva in caso di errore di connessione sicura.

[in] dwReserved

Questo parametro è riservato e deve essere NULL.

Valore restituito

Se ha esito positivo, restituisce un puntatore alla funzione di callback di stato definita in precedenza o NULL se non è stata definita alcuna funzione di callback di stato definita in precedenza. Restituisce WINHTTP_INVALID_STATUS_CALLBACK se non è stato possibile installare la funzione di callback. Per informazioni sugli errori estesi, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codice di errore	Descrizione
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Il tipo di handle fornito non è corretto per questa operazione.
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

Se si imposta il callback nell'handle di sessione prima di creare l'handle di richiesta, l'handle di richiesta eredita il puntatore alla funzione di callback dalla sessione padre.

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.

Entrambe le funzioni sincrone e asincrone usano la funzione di callback per indicare lo stato di avanzamento della richiesta, ad esempio la risoluzione di un nome, la connessione a un server e così via. La funzione di callback è necessaria per un'operazione asincrona.

Una funzione di callback può essere impostata su qualsiasi handle e viene ereditata dagli handle derivati. È possibile modificare una funzione di callback usando WinHttpSetStatusCallback, purché non siano presenti richieste in sospeso che devono usare il valore di callback precedente. Tuttavia, la modifica della funzione di callback in un handle non modifica i callback negli handle derivati, ad esempio quelli restituiti da WinHttpConnect. È necessario modificare la funzione di callback a ogni livello.

Molte funzioni WinHTTP eseguono diverse operazioni sulla rete. Il completamento di ogni operazione può richiedere tempo e ogni operazione può avere esito negativo.

Dopo aver avviato la funzione WinHttpSetStatusCallback , è possibile accedere alla funzione di callback dall'interno di WinHTTP per il monitoraggio delle operazioni di rete a elevato utilizzo di tempo.

Al termine dell'elaborazione asincrona, l'applicazione può impostare la funzione di callback su NULL. Ciò impedisce all'applicazione client di ricevere notifiche aggiuntive.

Il frammento di codice seguente mostra il metodo consigliato per impostare la funzione di callback su NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

Si noti, tuttavia, che WinHTTP non sincronizza WinHttpSetStatusCallback con i thread di lavoro. Se un callback originato in un altro thread è in corso quando un'applicazione chiama WinHttpSetStatusCallback, l'applicazione riceve comunque una notifica di callback anche dopo che WinHttpSetStatusCallback imposta correttamente la funzione di callback su NULL e restituisce.

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

Esempio

L'esempio seguente illustra come installare una funzione di callback per le funzioni WinHTTP asincrone. L'esempio presuppone che sia stata implementata in precedenza una funzione WINHTTP_STATUS_CALLBACK denominata "AsyncCallback( )":

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

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.