WinHttpSetStatusCallback-Funktion (winhttp.h)

Die WinHttpSetStatusCallback-Funktion richtet eine Rückruffunktion ein, die WinHTTP aufrufen kann, wenn während eines Vorgangs Fortschritt gemacht wird.

Syntax

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

Parameter

[in] hInternet

HINTERNET-Handle , für das der Rückruf festgelegt werden soll.

[in] lpfnInternetCallback

Zeiger auf die Rückruffunktion, die aufgerufen werden soll, wenn der Fortschritt gemacht wird. Legen Sie dies auf NULL fest, um die vorhandene Rückruffunktion zu entfernen. Weitere Informationen zur Rückruffunktion finden Sie unter WINHTTP_STATUS_CALLBACK.

[in] dwNotificationFlags

Unsigned long integer value that specifies flags to indicate which events activate the callback function.

Die folgenden Werte sind möglich:

[in] dwReserved

Dieser Parameter ist reserviert und muss NULL sein.

Rückgabewert

Bei erfolgreicher Ausführung wird ein Zeiger auf die zuvor definierte status Rückruffunktion oder NULL zurückgegeben, wenn zuvor keine status Rückruffunktion definiert wurde. Gibt WINHTTP_INVALID_STATUS_CALLBACK zurück, wenn die Rückruffunktion nicht installiert werden konnte. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Hinweise

Wenn Sie den Rückruf für das Sitzungshandle festlegen, bevor Sie das Anforderungshandle erstellen, erbt das Anforderungshandle den Rückruffunktionszeiger von seiner übergeordneten Sitzung.

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.

Sowohl synchrone als auch asynchrone Funktionen verwenden die Rückruffunktion, um den Fortschritt der Anforderung anzugeben, z. B. auflösen eines Namens, Herstellen einer Verbindung mit einem Server usw. Die Rückruffunktion ist für einen asynchronen Vorgang erforderlich.

Eine Rückruffunktion kann für jedes Handle festgelegt werden und wird von abgeleiteten Handles geerbt. Eine Rückruffunktion kann mithilfe von WinHttpSetStatusCallback geändert werden, sofern keine ausstehenden Anforderungen vorhanden sind, die den vorherigen Rückrufwert verwenden müssen. Das Ändern der Rückruffunktion für ein Handle ändert jedoch nicht die Rückrufe für abgeleitete Handles, z. B. die von WinHttpConnect zurückgegebenen. Sie müssen die Rückruffunktion auf jeder Ebene ändern.

Viele WinHTTP-Funktionen führen mehrere Vorgänge im Netzwerk aus. Jeder Vorgang kann einige Zeit in Anspruch nehmen, und jeder Vorgang kann fehlschlagen.

Nach dem Initiieren der WinHttpSetStatusCallback-Funktion kann von WinHTTP aus auf die Rückruffunktion zugegriffen werden, um zeitintensive Netzwerkvorgänge zu überwachen.

Am Ende der asynchronen Verarbeitung kann die Anwendung die Rückruffunktion auf NULL festlegen. Dadurch wird verhindert, dass die Clientanwendung zusätzliche Benachrichtigungen empfängt.

Der folgende Codeausschnitt zeigt die empfohlene Methode zum Festlegen der Rückruffunktion auf NULL.

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

Beachten Sie jedoch, dass WinHTTP WinHttpSetStatusCallback nicht mit Workerthreads synchronisiert. Wenn ein Rückruf aus einem anderen Thread ausgeführt wird, wenn eine Anwendung WinHttpSetStatusCallback aufruft, empfängt die Anwendung weiterhin eine Rückrufbenachrichtigung, auch nachdem WinHttpSetStatusCallback die Rückruffunktion erfolgreich auf NULL festgelegt und zurückgegeben hat.

Beispiele

Das folgende Beispiel zeigt, wie Sie eine Rückruffunktion für asynchrone WinHTTP-Funktionen installieren. Im Beispiel wird davon ausgegangen, dass eine WINHTTP_STATUS_CALLBACK-Funktion namens "AsyncCallback( )" bereits implementiert wurde:

    // 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());
    }

Anforderungen

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP-Versionen

WinHttpConnect

WinHttpOpen