WINHTTP_STATUS_CALLBACK Rückruffunktion (winhttp.h)

  • Artikel

Der typ WINHTTP_STATUS_CALLBACK stellt eine anwendungsdefinierte Statusrückruffunktion dar.

Syntax

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

Parameter

[in] hInternet

Das Handle, für das die Rückruffunktion aufgerufen wird.

[in] dwContext

Ein Zeiger auf ein DWORD , der den anwendungsdefinierten Kontextwert angibt, der dem Handle im hInternet-Parameter zugeordnet ist.

Ein Kontextwert kann einem Sitzungs-, Verbindungs- oder Anforderungshandle zugewiesen werden, indem WinHttpSetOption mit der Option WINHTTP_OPTION_CONTEXT_VALUE aufgerufen wird. Alternativ kann WinHttpSendRequest verwendet werden, um einem Anforderungshandle einen Kontextwert zuzuordnen.

[in] dwInternetStatus

Verweist auf ein DWORD , das den Statuscode angibt, der angibt, warum die Rückruffunktion aufgerufen wird. Mögliche Werte:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Schließen der Verbindung mit dem Server. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

Erfolgreich eine Verbindung mit dem Server hergestellt. Der lpvStatusInformation-Parameter enthält einen Zeiger auf einen LPWSTR,der die IP-Adresse des Servers in gepunkteter Notation angibt.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

Herstellen einer Verbindung mit dem Server. Der lpvStatusInformation-Parameter enthält einen Zeiger auf einen LPWSTR,der die IP-Adresse des Servers in gepunkteter Notation angibt.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Die Verbindung mit dem Server wurde erfolgreich geschlossen. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Daten können mit WinHttpReadData abgerufen werden. Der Parameter lpvStatusInformation verweist auf ein DWORD , das die Anzahl der verfügbaren Daten in Bytes enthält. Der dwStatusInformationLength-Parameter selbst ist 4 (die Größe eines DWORD-Werts).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

Ein HINTERNET-Handle wurde erstellt. Der lpvStatusInformation-Parameter enthält einen Zeiger auf das HINTERNET-Handle .

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

Dieser Handle-Wert wurde beendet. Der lpvStatusInformation-Parameter enthält einen Zeiger auf das HINTERNET-Handle . Für dieses Handle werden keine Rückrufe mehr ausgeführt.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

Der Antwortheader wurde empfangen und ist mit WinHttpQueryHeaders verfügbar. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

Eine zwischengeschaltete Statuscodemeldung (100-Ebene) wurde vom Server empfangen. Der Parameter lpvStatusInformation enthält einen Zeiger auf ein DWORD , das den Statuscode angibt.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

Die IP-Adresse des Servers wurde erfolgreich gefunden. Der lpvStatusInformation-Parameter enthält einen Zeiger auf einen LPWSTR , der den aufgelösten Namen angibt.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Daten wurden erfolgreich vom Server gelesen. Der Parameter lpvStatusInformation enthält einen Zeiger auf den Puffer, der im Aufruf von WinHttpReadData angegeben ist. Der dwStatusInformationLength-Parameter enthält die Anzahl der gelesenen Bytes.

Bei Verwendung von WinHttpWebSocketReceive enthält der lpvStatusInformation-Parameter einen Zeiger auf eine WINHTTP_WEB_SOCKET_STATUS-Struktur , und der dwStatusInformationLength-Parameter gibt die Größe von lpvStatusInformation an.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

Warten, bis der Server auf eine Anforderung antwortet. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_REDIRECT

Eine HTTP-Anforderung wird die Anforderung automatisch umgeleitet. Der Parameter lpvStatusInformation enthält einen Zeiger auf einen LPWSTR,der die neue URL angibt. An diesem Punkt kann die Anwendung alle vom Server zurückgegebenen Daten mit der Umleitungsantwort lesen und die Antwortheader abfragen. Der Vorgang kann auch abgebrochen werden, indem das Handle geschlossen wird.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

Fehler beim Senden einer HTTP-Anforderung. Der lpvStatusInformation-Parameter enthält einen Zeiger auf eine WINHTTP_ASYNC_RESULT-Struktur . Das dwResult-Element gibt die ID der aufgerufenen Funktion und dwError den Rückgabewert an.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Die Informationsanforderung wurde erfolgreich an den Server gesendet. Der lpvStatusInformation-Parameter enthält einen Zeiger auf ein DWORD, der die Anzahl der gesendeten Bytes angibt.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Nachschlagen der IP-Adresse eines Servernamens. Der Parameter lpvStatusInformation enthält einen Zeiger auf den servernamen, der aufgelöst wird.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Eine Antwort vom Server wurde erfolgreich empfangen. Der Parameter lpvStatusInformation enthält einen Zeiger auf ein DWORD, der die Anzahl der empfangenen Bytes angibt.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

Beim Herstellen einer sicheren (HTTPS)-Verbindung mit dem Server ist mindestens ein Fehler aufgetreten. Der Parameter lpvStatusInformation enthält einen Zeiger auf ein DWORD , bei dem es sich um eine bitweise OR-Kombination von Fehlerwerten handelt. Weitere Informationen finden Sie in der Beschreibung für lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Senden der Informationsanforderung an den Server. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

Die Anforderung wurde erfolgreich abgeschlossen. Der Parameter lpvStatusInformation ist der lpOptional-Wert, der an WinHttpSendRequest (den ursprünglichen Anforderungstext ) übergeben wird, und der parameter dwStatusInformationLength gibt die Anzahl der erfolgreich geschriebenen Anfangstextbytes an (der an WinHttpSendRequest übergebene dwOptionalLength-Wert).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Daten wurden erfolgreich auf den Server geschrieben. Der Parameter lpvStatusInformation enthält einen Zeiger auf ein DWORD , der die Anzahl der geschriebenen Bytes angibt.

Bei Verwendung von WinHttpWebSocketSend enthält der lpvStatusInformation-Parameter einen Zeiger auf eine WINHTTP_WEB_SOCKET_STATUS-Struktur , und der dwStatusInformationLength-Parameter gibt die Größe von lpvStatusInformation an.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

Der vorgang, der durch einen Aufruf von WinHttpGetProxyForUrlEx initiiert wurde, ist abgeschlossen. Daten können mit WinHttpReadData abgerufen werden.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

Die Verbindung wurde über einen Aufruf von WinHttpWebSocketClose erfolgreich geschlossen. Der lpvStatusInformation-Parameter ist NULL.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

Die Verbindung wurde über einen Aufruf von WinHttpWebSocketShutdown erfolgreich beendet. Der lpvStatusInformation-Parameter ist NULL.

[in] lpvStatusInformation

Ein Zeiger auf einen Puffer, der Informationen angibt, die für diesen Aufruf der Rückruffunktion relevant sind. Das Format dieser Daten hängt vom Wert des dwInternetStatus-Arguments ab. Weitere Informationen finden Sie unter dwInternetStatus.

Wenn das Argument dwInternetStatus WINHTTP_CALLBACK_STATUS_SECURE_FAILURE ist, verweist lpvStatusInformation auf ein DWORD, bei dem es sich um eine bitweise OR-Kombination aus einem oder mehreren der folgenden Werte handelt.

Wert Bedeutung
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED
 Die Überprüfung der Zertifizierungssperrung wurde aktiviert, aber die Sperrprüfung konnte nicht überprüfen, ob ein Zertifikat widerrufen wurde. Der Server, der zum Überprüfen der Sperrung verwendet wird, ist möglicherweise nicht erreichbar.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT
 DAS SSL-Zertifikat ist ungültig.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED
 Das SSL-Zertifikat wurde widerrufen.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA
 Die Funktion ist nicht mit der Zertifizierungsstelle vertraut, die das Zertifikat des Servers generiert hat.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID
 Der allgemeine Ssl-Zertifikatname (Hostnamenfeld) ist beispielsweise falsch, wenn Sie www.microsoft.com eingegeben haben und der allgemeine Name im Zertifikat www.msn.com.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID
 Das SSL-Zertifikatdatum, das vom Server empfangen wurde, ist ungültig. Das Zertifikat ist abgelaufen.
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR
 Bei der Anwendung ist ein interner Fehler beim Laden der SSL-Bibliotheken aufgetreten.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT Statusrückrufe stellen einen dwStatusInformationLength-Wert bereit, der der Zeichenanzahl des LPWSTR entspricht, auf den lpvStatusInformation verweist.

Rückgabewert

Keine

Bemerkungen

Die Rückruffunktion muss threadsicher und reentrant sein, da sie in einem anderen Thread für eine separate Anforderung aufgerufen und für denselben Thread für die aktuelle Anforderung erneut aufgerufen werden kann. Es muss daher codiert sein, um die Wiedereintrierung während der Verarbeitung sicher zu behandeln. Wenn der dwInternetStatus-Parametergleich WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING ist, muss der Rückruf nicht in der Lage sein, die Wiederholung für dieselbe Anforderung zu verarbeiten, da dieser Rückruf garantiert der letzte ist und nicht auftritt, wenn andere Nachrichten für diese Anforderung verarbeitet werden.

Die Statusrückruffunktion empfängt Updates zum Status asynchroner Vorgänge über Benachrichtigungsflags. Benachrichtigungen, die darauf hinweisen, dass ein bestimmter Vorgang abgeschlossen ist, werden als Vervollständigungsbenachrichtigungen oder einfach als Vervollständigungen bezeichnet. In der folgenden Tabelle sind die sechs Vervollständigungsflags und die entsprechende Funktion aufgeführt, die abgeschlossen ist, wenn dieses Flag empfangen wird.

Vervollständigungsflag Funktion
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Eine der oben genannten Funktionen, wenn ein Fehler auftritt.
 

Da Rückrufe während der Verarbeitung der Anforderung erfolgen, sollte die Anwendung so wenig Zeit wie möglich in der Rückruffunktion verbringen, um eine Beeinträchtigung des Datendurchsatzes im Netzwerk zu vermeiden. Beispielsweise kann das Anzeigen eines Dialogfelds in einer Rückruffunktion so langwierig sein, dass der Server die Anforderung beendet.

Die Rückruffunktion kann in einem Threadkontext aufgerufen werden, der sich von dem Thread unterscheidet, der die Anforderung initiiert hat.

Ebenso gibt es keine Rückrufthreadaffinität, wenn Sie WinHttp asynchron aufrufen: Ein Aufruf kann von einem Thread aus gestartet werden, aber jeder andere Thread kann den Rückruf empfangen.

Hinweis Weitere Informationen zur Implementierung in Windows XP und Windows 2000 finden Sie unter Laufzeitanforderungen.
 

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
Verteilbare Komponente WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.

Weitere Informationen

WinHTTP-Versionen

WinHttpSetStatusCallback