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:

Wert Bedeutung
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS
Wird bei jeder Vervollständigungsbenachrichtigung aktiviert. Dieses Flag gibt an, dass alle Benachrichtigungen verwendet werden, die für Lese- oder Schreibvorgänge erforderlich sind. Eine Liste der Vervollständigungen finden Sie unter WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS
Wird bei jeder status Änderungsbenachrichtigung aktiviert, einschließlich Vervollständigungen. Eine Liste der Benachrichtigungen finden Sie unter WINHTTP_STATUS_CALLBACK .
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME
Wird beim Starten und Abschließen der Namensauflösung aktiviert.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER
Wird beim Starten und Abschließen der Verbindung mit dem Server aktiviert.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY
Wird aktiviert, wenn der Proxyserver erkannt wird.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE
Wird aktiviert, wenn eine Abfrage für Daten abgeschlossen wird.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE
Wird aktiviert, wenn die Antwortheader zum Abrufen verfügbar sind.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE
Wird nach Abschluss eines Datenlesevorgangs aktiviert.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR
Wird aktiviert, wenn ein asynchroner Fehler auftritt.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST
Aktiviert beim Starten und Abschließen des Sendens eines Anforderungsheaders mit WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE
Wird aktiviert, wenn ein Anforderungsheader mit WinHttpSendRequest gesendet wurde.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE
Wird nach Abschluss eines Daten-Post-Vorgangs aktiviert.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE
Wird beim Starten und Abschließen des Empfangs einer Ressource vom HTTP-Server aktiviert.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION
Wird beim Starten und Abschließen des Schließens einer HTTP-Verbindung aktiviert.
WINHTTP_CALLBACK_FLAG_HANDLES
Wird aktiviert, wenn ein HINTERNET-Handle erstellt oder geschlossen wird.
WINHTTP_CALLBACK_FLAG_REDIRECT
Wird aktiviert, wenn die Anforderung umgeleitet wird.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE
Wird aktiviert, wenn eine zwischengeschaltete Codenachricht (Ebene 100) status vom Server empfangen wird.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE
Wird bei einem Fehler der sicheren Verbindung aktiviert.

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

Fehlercode BESCHREIBUNG
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INTERNAL_ERROR
Ein interner Fehler ist aufgetreten.
ERROR_NOT_ENOUGH_MEMORY
Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

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.

Hinweis Informationen zu Windows XP und Windows 2000 finden Sie im Abschnitt Laufzeitanforderungen der WinHttp-Startseite .
 

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

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winhttp.h
Bibliothek Winhttp.lib
DLL Winhttp.dll
Verteilbare Komponente WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.

Weitere Informationen

Informationen zu Microsoft Windows HTTP-Diensten (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP-Versionen

WinHttpConnect

WinHttpOpen