WINHTTP_STATUS_CALLBACK Rückruffunktion (winhttp.h)
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.
[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.
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. |