Funzione WinHttpSetStatusCallback (winhttp.h)

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.

[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.

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.

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

Vedi anche

Informazioni su Microsoft Windows HTTP Services (WinHTTP)

WINHTTP_STATUS_CALLBACK

Versioni WinHTTP

WinHttpConnect

WinHttpOpen