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 |
|---|---|
|
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 . |
|
Wird bei jeder status Änderungsbenachrichtigung aktiviert, einschließlich Vervollständigungen. Eine Liste der Benachrichtigungen finden Sie unter WINHTTP_STATUS_CALLBACK . |
|
Wird beim Starten und Abschließen der Namensauflösung aktiviert. |
|
Wird beim Starten und Abschließen der Verbindung mit dem Server aktiviert. |
|
Wird aktiviert, wenn der Proxyserver erkannt wird. |
|
Wird aktiviert, wenn eine Abfrage für Daten abgeschlossen wird. |
|
Wird aktiviert, wenn die Antwortheader zum Abrufen verfügbar sind. |
|
Wird nach Abschluss eines Datenlesevorgangs aktiviert. |
|
Wird aktiviert, wenn ein asynchroner Fehler auftritt. |
|
Aktiviert beim Starten und Abschließen des Sendens eines Anforderungsheaders mit WinHttpSendRequest. |
|
Wird aktiviert, wenn ein Anforderungsheader mit WinHttpSendRequest gesendet wurde. |
|
Wird nach Abschluss eines Daten-Post-Vorgangs aktiviert. |
|
Wird beim Starten und Abschließen des Empfangs einer Ressource vom HTTP-Server aktiviert. |
|
Wird beim Starten und Abschließen des Schließens einer HTTP-Verbindung aktiviert. |
|
Wird aktiviert, wenn ein HINTERNET-Handle erstellt oder geschlossen wird. |
|
Wird aktiviert, wenn die Anforderung umgeleitet wird. |
|
Wird aktiviert, wenn eine zwischengeschaltete Codenachricht (Ebene 100) status vom Server empfangen wird. |
|
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 |
|---|---|
|
Der Typ des angegebenen Handles ist für diesen Vorgang falsch. |
|
Ein interner Fehler ist aufgetreten. |
|
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.
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. |