WsAbandonMessage 関数 (webservices.h)

指定したチャネルで、指定した メッセージ の残りの部分をスキップします。

構文

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

パラメーター

[in] channel

メッセージの読み取 り または書き込み中のチャネルを表すWS_CHANNEL構造体へのポインター。

[in] message

破棄するメッセージを表す WS_MESSAGE 構造体へのポインター。 これは、WsWriteMessageStart 関数または WsReadMessageStart 関数に渡されたメッセージと同じである必要があります。

[in, optional] error

関数が失敗した場合に追加のエラー情報を受け取る WS_ERROR 構造体へのポインター。

戻り値

関数が成功した場合は、NO_ERRORを返します。それ以外の場合は、HRESULT エラー コードを返します。

注釈

WsAbandonMessage は、メッセージの残りの内容の読み取りまたは書き込みをスキップするために使用され、チャネルの次のメッセージの読み取りまたは書き込みを許可します。 この点では、次の状態図に示すように、 WsReadMessageEnd 関数または WsWriteMessageEnd 関数の代わりに使用します。

読み取り操作の場合、アプリケーションは通常、アプリケーションがメッセージ データの読み取りを続行する必要がない場合 (たとえば、メッセージがアプリケーションの要件を満たしていない場合) に WsAbandonMessage を呼び出します。 この関数は、メッセージに不適切な形式の XML が含まれている場合、または XML リーダー がメッセージの読み取り中にエラーを生成した場合にも使用できます。

チャネルがストリーミングされる場合 ( WS_TRANSFER_MODE 列挙のWS_STREAMED_INPUT_TRANSFER_MODE値を参照)、ストリームされたメッセージ データの残りの部分が読み取られ、次にチャネルの WsReadMessageStart または WsCloseChannel が呼び出されると自動的に破棄されます。 チャネルがストリーミングされていない場合、未読のバッファーメッセージデータは単に破棄されます。

書き込み操作の場合、アプリケーションがメッセージの書き込みを続行できない場合 (XML ライターから返されたエラーなど)、または何らかの理由でメッセージの生成を停止する必要があるために、アプリケーションは通常 WsAbandonMessage を呼び出します。

チャネルがストリーミングされている場合 ( WS_TRANSFER_MODE 列挙のWS_STREAMED_INPUT_TRANSFER_MODE値を参照)、メッセージ データは切り捨てられ、リモート パーティが読み取るときにエラーが発生する可能性があります。 チャネルがストリーミングされていない場合、メッセージのバッファーされたデータは単に破棄されます (送信されていないため)。

この関数を使用すると、エラーが発生した場合でも、チャネルのユーザーはチャネルを開いたままにし、追加のメッセージ (エラーの送信など) を送受信できます。 これに対し、 WsAbortChannel によってチャネルがエラーになります。 一般的な使用方法は、最初にメッセージを破棄してエラーを送信することです。 失敗した場合は、チャネルを中止できます。

この関数は、ブロッキング I/O を実行しません。

この関数は、チャネルがWS_CHANNEL_STATE_OPENまたはWS_CHANNEL_STATE_FAULTED状態にある場合にのみ有効です。 (チャネルの状態については、 WS_CHANNEL_STATE 列挙を参照してください)。

指定するメッセージは、読み取り中の現在のメッセージか、指定されたチャネルに対して書き込まれる現在のメッセージである必要があります。

正しく呼び出された場合、この関数は失敗しません (たとえば、システム リソースがないため)。

要件