WsReceiveMessage-Funktion (webservices.h)

Artikel
08/27/2023

Empfangen Sie eine Nachricht, und deserialisieren Sie den Text der Nachricht als Wert.

Syntax

HRESULT WsReceiveMessage(
  [in]           WS_CHANNEL                   *channel,
  [in]           WS_MESSAGE                   *message,
                 const WS_MESSAGE_DESCRIPTION **messageDescriptions,
  [in]           ULONG                        messageDescriptionCount,
  [in]           WS_RECEIVE_OPTION            receiveOption,
  [in]           WS_READ_OPTION               readBodyOption,
  [in, optional] WS_HEAP                      *heap,
                 void                         *value,
  [in]           ULONG                        valueSize,
                 ULONG                        *index,
  [in, optional] const WS_ASYNC_CONTEXT       *asyncContext,
  [in, optional] WS_ERROR                     *error
);

Parameter

[in] channel

Der Kanal, von dem empfangen werden soll.

[in] message

Das Nachrichtenobjekt, das zum Empfangen verwendet wird.

Die Nachricht sollte sich in WS_MESSAGE_STATE_EMPTY Zustand befinden.

messageDescriptions

Ein Array von Zeigern auf Nachrichtenbeschreibungen, das die Metadaten für die erwarteten Nachrichtentypen angibt.

[in] messageDescriptionCount

Die Anzahl der Elemente im MessageDescriptions-Array.

[in] receiveOption

Gibt an, ob die Nachricht erforderlich ist. Weitere Informationen finden Sie unter WS_RECEIVE_OPTION .

[in] readBodyOption

Gibt an, ob das body-Element erforderlich ist und wie der Wert zugeordnet werden soll.
Weitere Informationen finden Sie unter WS_READ_OPTION .

[in, optional] heap

Der Heap, in dem die deserialisierten Werte gespeichert werden sollen. Wenn der Heap für den angegebenen Typ nicht erforderlich ist, kann dieser Parameter NULL sein.

value

Die Interpretation dieses Parameters hängt vom WS_READ_OPTION ab.

Wenn WS_RECEIVE_OPTIONAL_MESSAGE für den receiveOption-Parameter angegeben ist und keine weiteren Nachrichten auf dem Kanal verfügbar sind, wird dieser Parameter nicht berührt. In diesem Fall gibt die Funktion WS_S_END zurück. (Siehe Rückgabewerte für Windows-Webdienste.)

Wenn die bodyElementDescription des übereinstimmenden WS_MESSAGE_DESCRIPTIONNULL ist, wird dieser Parameter nicht berührt. In diesem Fall muss der Parameter nicht angegeben werden.

[in] valueSize

Die Interpretation dieses Parameters hängt vom WS_READ_OPTION ab.

index

Wenn WS_RECEIVE_OPTIONAL_MESSAGE für den receiveOption-Parameter angegeben ist und keine weiteren Nachrichten im Kanal verfügbar sind, bleibt dieser Parameter unberührt. In diesem Fall gibt die Funktion WS_S_END zurück.

Andernfalls enthält die Funktion, wenn die Funktion erfolgreich ist, den nullbasierten Index in das Array der Nachrichtenbeschreibungen, die angibt, welche zugeordnet ist.

Dieser Parameter kann NULL sein, wenn der Aufrufer nicht an dem Wert interessiert ist (z. B. wenn nur eine Nachrichtenbeschreibung vorhanden ist).

[in, optional] asyncContext

Informationen zum asynchronen Aufrufen der Funktion oder NULL beim synchronen Aufrufen.

[in, optional] error

Gibt an, wo zusätzliche Fehlerinformationen gespeichert werden sollen, wenn die Funktion fehlschlägt.

Rückgabewert

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	Beschreibung
WS_S_ASYNC	Der asynchrone Vorgang steht noch aus.
WS_S_END	Die Empfangsoption WS_RECEIVE_OPTIONAL_MESSAGE wurde angegeben, und es sind keine weiteren Nachrichten für den Kanal verfügbar.
WS_E_ENDPOINT_FAULT_RECEIVED	Die empfangene Nachricht enthielt einen Fehler. Der Fehler kann mithilfe von WsGetErrorProperty aus dem WS_ERROR extrahiert werden.
WS_E_OPERATION_ABORTED	Der Vorgang wurde abgebrochen.
WS_E_INVALID_OPERATION	Der Vorgang ist aufgrund des aktuellen Zustands des Objekts nicht zulässig.
WS_E_ENDPOINT_NOT_FOUND	Der Remoteendpunkt ist nicht vorhanden oder konnte nicht gefunden werden.
WS_E_ENDPOINT_ACCESS_DENIED	Der Zugriff wurde vom Remoteendpunkt verweigert.
WS_E_ENDPOINT_DISCONNECTED	Die Verbindung mit dem Remoteendpunkt wurde beendet.
WS_E_ENDPOINT_FAILURE	Der Remoteendpunkt konnte die Anforderung nicht verarbeiten.
WS_E_ENDPOINT_NOT_AVAILABLE	Der Remoteendpunkt ist an diesem Standort derzeit nicht im Dienst.
WS_E_ENDPOINT_TOO_BUSY	Der Remoteendpunkt kann die Anforderung aufgrund einer Überlastung nicht verarbeiten.
WS_E_ENDPOINT_UNREACHABLE	Der Remoteendpunkt war nicht erreichbar.
WS_E_INVALID_ENDPOINT_URL	Die Endpunktadressen-URL ist ungültig.
WS_E_INVALID_FORMAT	Die Eingabedaten waren nicht im erwarteten Format oder hatten nicht den erwarteten Wert.
WS_E_OPERATION_TIMED_OUT	Der Vorgang wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen.
WS_E_PROXY_ACCESS_DENIED	Der Zugriff wurde vom HTTP-Proxyserver verweigert.
WS_E_PROXY_FAILURE	Der HTTP-Proxyserver konnte die Anforderung nicht verarbeiten.
WS_E_QUOTA_EXCEEDED	Ein Kontingent wurde überschritten.
WS_E_SECURITY_VERIFICATION_FAILURE	Die Sicherheitsüberprüfung war für die empfangenen Daten nicht erfolgreich.
WS_E_SECURITY_SYSTEM_FAILURE	Fehler bei einem Sicherheitsvorgang im Windows-Webdienstframework.
WS_E_SECURITY_TOKEN_EXPIRED	Ein Sicherheitstoken wurde vom Server abgelehnt, da es abgelaufen ist.
WS_E_PROXY_REQUIRES_BASIC_AUTH	Der HTTP-Proxyserver erfordert das HTTP-Authentifizierungsschema "basic".
WS_E_PROXY_REQUIRES_DIGEST_AUTH	Der HTTP-Proxyserver erfordert das HTTP-Authentifizierungsschema "digest".
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH	Für den HTTP-Proxyserver ist das HTTP-Authentifizierungsschema "negotiate" erforderlich.
WS_E_PROXY_REQUIRES_NTLM_AUTH	Der HTTP-Proxyserver erfordert das HTTP-Authentifizierungsschema "NTLM".
WS_E_SERVER_REQUIRES_BASIC_AUTH	Für den Remoteendpunkt ist das HTTP-Authentifizierungsschema "basic" erforderlich.
WS_E_SERVER_REQUIRES_DIGEST_AUTH	Für den Remoteendpunkt ist das HTTP-Authentifizierungsschema "digest" erforderlich.
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH	Für den Remoteendpunkt ist das HTTP-Authentifizierungsschema "negotiate" erforderlich.
WS_E_SERVER_REQUIRES_NTLM_AUTH	Für den Remoteendpunkt ist das HTTP-Authentifizierungsschema "NTLM" erforderlich.
CERT_E_EXPIRED	Ein erforderliches Zertifikat liegt nicht innerhalb seines Gültigkeitszeitraums, wenn es mit der aktuellen Systemuhr oder dem Zeitstempel in der signierten Datei überprüft wird.
CERT_E_CN_NO_MATCH	Der Zertifikat-CN-Name stimmt nicht mit dem übergebenen Wert überein.
CERT_E_UNTRUSTEDROOT	Eine Zertifikatkette, die verarbeitet, aber in einem Stammzertifikat beendet wird, das vom Vertrauensanbieter nicht vertrauenswürdig ist.
CERT_E_WRONG_USAGE	Das Zertifikat ist für die angeforderte Verwendung nicht zulässig.
CRYPT_E_REVOCATION_OFFLINE	Die Sperrfunktion konnte die Sperrung nicht überprüfen, da der Sperrserver offline war.
E_OUTOFMEMORY	Der Arbeitsspeicher ist nicht mehr vorhanden.
E_INVALIDARG	Mindestens ein Argument ist ungültig.
Andere Fehler	Diese Funktion gibt möglicherweise andere Fehler zurück, die oben nicht aufgeführt sind.

Hinweise

Diese Funktion verwendet Metadaten zu den erwarteten Nachrichtentypen, um den Text zu deserialisieren.
Die Metadaten sind ein Array von Zeigern auf WS_MESSAGE_DESCRIPTIONs. Jede Nachrichtenbeschreibung enthält einen Aktionswert, der verwendet wird, um mit der Aktion der Nachricht abzugleichen, und eine WS_ELEMENT_DESCRIPTION , die die Metadaten für das Body-Element bereitstellt.

Wenn die Nachrichtenheader empfangen wurden, scannt die Funktion das Array, um eine Übereinstimmung mit der Aktion zu finden. Die erste Übereinstimmende Nachrichtenbeschreibung wird verwendet, um den Text zu deserialisieren, und der nullbasierte Index dieser Nachrichtenbeschreibung im Array wird im Index out-Parameter zurückgegeben. Wenn die Funktion erfolgreich ist, wird der Index out-Parameter immer so festgelegt, dass er angibt, welche Nachrichtenbeschreibung verwendet wurde.

Damit eine Nachrichtenbeschreibung übereinstimmt, muss der Aktionswert genau mit dem wert der Nachricht übereinstimmen. Wenn die Aktion im WS_MESSAGE_DESCRIPTIONNULL ist, stimmt die Aktion immer überein. Dies kann verwendet werden, wenn in der empfangenen Nachricht kein Aktionsheader vorhanden ist oder wenn der Text immer gleich ist, unabhängig davon, was die Aktion ist.

Wenn erwartet wird, dass der Text leer ist, kann das bodyElementDescription-Feld des WS_MESSAGE_DESCRIPTIONNULL sein.

Wenn bodyElementDescription nicht NULL ist, deserialisiert diese Funktion den Text wie in WsReadBody beschrieben.

Nachdem eine Nachricht empfangen wurde, können ihre Header mit WsGetHeader oder WsGetCustomHeader überprüft werden.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	webservices.h
Bibliothek	WebServices.lib
DLL	WebServices.dll

Freigeben über