WsAbandonMessage-Funktion (webservices.h)

Überspringt den Rest einer angegebenen Nachricht auf einem angegebenen Kanal.

Syntax

HRESULT WsAbandonMessage(
  [in]           WS_CHANNEL *channel,
  [in]           WS_MESSAGE *message,
  [in, optional] WS_ERROR   *error
);

Parameter

[in] channel

Zeiger auf eine WS_CHANNEL-Struktur , die den Kanal darstellt, in dem die Nachricht gelesen oder geschrieben wird.

[in] message

Zeiger auf eine WS_MESSAGE-Struktur , die die abzubrechende Nachricht darstellt. Dies sollte dieselbe Nachricht sein, die an die Funktion WsWriteMessageStart oder WsReadMessageStart übergeben wurde.

[in, optional] error

Zeiger auf eine WS_ERROR-Struktur , die zusätzliche Fehlerinformationen empfängt, wenn die Funktion fehlschlägt.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie NO_ERROR zurück. Andernfalls wird ein HRESULT-Fehlercode zurückgegeben.

Hinweise

WsAbandonMessage wird verwendet, um das Lesen oder Schreiben des verbleibenden Inhalts einer Nachricht zu überspringen, sodass die nächste Nachricht für den Kanal gelesen oder geschrieben werden kann. In dieser Hinsicht ist es eine Alternative zu den Funktionen WsReadMessageEnd oder WsWriteMessageEnd , wie im folgenden Zustandsdiagramm gezeigt:

Bei Lesevorgängen ruft eine Anwendung in der Regel WsAbandonMessage auf, wenn es nicht erforderlich ist, dass die Anwendung die Nachrichtendaten weiter liest, z. B. wenn die Nachricht die Anforderungen der Anwendung nicht erfüllt. Diese Funktion kann auch verwendet werden, wenn die Nachricht einen fehlerhaften XML-Code enthält oder wenn der XML-Reader beim Lesen der Nachricht einen Fehler generiert hat.

Wenn der Kanal gestreamt wird (siehe WS_STREAMED_INPUT_TRANSFER_MODE Wert der WS_TRANSFER_MODE-Enumeration ), werden die restlichen Daten der gestreamten Nachrichten gelesen und automatisch verworfen, wenn der nächste Aufruf von WsReadMessageStart oder WsCloseChannel für den Kanal erfolgt. Wenn der Kanal nicht gestreamt wird, werden die ungelesenen gepufferten Nachrichtendaten einfach verworfen.

Bei Schreibvorgängen ruft eine Anwendung in der Regel WsAbandonMessage auf, wenn die Anwendung das Schreiben der Nachricht nicht fortsetzen kann, weil ein Fehler aufgetreten ist, z. B. ein vom XML-Writer zurückgegebener Fehler, oder die Generierung der Nachricht aus einem anderen Grund beenden muss.

Wenn der Kanal gestreamt wird (siehe WS_STREAMED_INPUT_TRANSFER_MODE Wert der WS_TRANSFER_MODE-Enumeration ), werden die Nachrichtendaten abgeschnitten und können zu Fehlern führen, wenn sie von der Remotepartei gelesen werden. Wenn der Kanal nicht gestreamt wird, werden die gepufferten Daten für die Nachricht einfach verworfen (da sie nie übertragen wurden).

Diese Funktion ermöglicht es dem Benutzer des Kanals, den Kanal geöffnet zu halten und zusätzliche Nachrichten (z. B. das Senden eines Fehlers) zu senden oder zu empfangen, obwohl ein Fehler aufgetreten ist. Im Gegensatz dazu verursacht WsAbortChannel einen Fehler beim Kanal. Eine typische Verwendung besteht darin, zuerst zu versuchen, die Nachricht abzubrechen und einen Fehler zu senden. Wenn dies fehlschlägt, kann der Kanal abgebrochen werden.

Diese Funktion führt keine blockierenden E/A-Vorgänge aus.

Diese Funktion ist nur gültig, wenn sich der Kanal im WS_CHANNEL_STATE_OPEN- oder WS_CHANNEL_STATE_FAULTED-Status befindet. (Kanalzustände finden Sie in der WS_CHANNEL_STATE-Enumeration .)

Die angegebene Nachricht muss die aktuelle Nachricht sein, die gelesen wird, oder die aktuelle Nachricht, die für den angegebenen Kanal geschrieben wird.

Wenn diese Funktion richtig aufgerufen wird, schlägt diese Funktion nicht fehl (z. B. aufgrund eines Mangels an Systemressourcen).

Anforderungen