WsReceiveMessage-Funktion (webservices.h)

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.

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