WsAbandonMessage function (webservices.h)

Skips the remainder of a specified message on a specified channel.

Syntax

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

Parameters

[in] channel

Pointer to a WS_CHANNEL structure representing the channel on which the message is being read or written.

[in] message

Pointer to a WS_MESSAGE structure representing the message to abandon. This should be the same message that was passed to the WsWriteMessageStart or WsReadMessageStart function.

[in, optional] error

Pointer to a WS_ERROR structure that receives additional error information if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.

Remarks

WsAbandonMessage is used to skip reading or writing the remaining contents of a message, allowing the next message for the channel to be read or written. In this respect, it is an alternative to the WsReadMessageEnd or WsWriteMessageEnd functions, as shown in the following state diagram:

For read operations, an application typically calls WsAbandonMessage when it is unnecessary for the application to continue reading the message data, for example, if the message does not meet the application's requirements. This function can also be used if the message contains malformed XML or if the XML reader has generated an error while reading the message.

If the channel is streamed (see the WS_STREAMED_INPUT_TRANSFER_MODE value of the WS_TRANSFER_MODE enumeration), the remainder of the streamed message data is read and automatically discarded with the next call to WsReadMessageStart or WsCloseChannel for the channel. If the channel is not streamed, the unread buffered message data is simply discarded.

For write operations, an application typically calls WsAbandonMessage when the application cannot continue writing the message because it has encountered some error, such as one returned by the XML writer, or must stop generating the message for some other reason.

If the channel is streamed (see the WS_STREAMED_INPUT_TRANSFER_MODE value of the WS_TRANSFER_MODE enumeration), the message data will be truncated and may result in errors when read by the remote party. If the channel is not streamed, the buffered data for the message is simply discarded (since it was never transmitted).

This function allows the user of the channel to keep the channel open and send or receive additional messages (such as sending a fault), even though an error occurred. In contrast, WsAbortChannel will causes the channel to fault. A typical usage is first to try to abandon the message and send a fault. If that fails, the channel can be aborted.

This function does not perform any blocking I/O.

This function is only valid when the channel is in the WS_CHANNEL_STATE_OPEN or WS_CHANNEL_STATE_FAULTED states. (For channel states, see the WS_CHANNEL_STATE enumeration.)

The message specified must be the current message being read or the current message being written for the specified channel.

If called correctly, this function will not fail (for example, due to lack of system resources).

Requirements