Expand Minimize

WsAbandonMessage function

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

Syntax


HRESULT WINAPI  WsAbandonMessage(
  _In_      WS_CHANNEL* channel,
  _In_      WS_MESSAGE* message,
  _In_opt_  WS_ERROR* error
);

Parameters

channel [in]

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

message [in]

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.

error [in, optional]

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.

Return codeDescription
WS_E_INVALID_OPERATION

The channel is not in the WS_CHANNEL_STATE_OPEN or WS_CHANNEL_STATE_FAULTED state. (For channel states, see the WS_CHANNEL_STATE enumeration.)

E_INVALIDARG

The specified message is not currently being read or written on the specified channel.

 

Security

Messages have a single-threaded contract (see the Thread Safety topic). It is therefore not valid to call this function while the message is being used for another operation. Calling this function while a message is being used as part of another operation will result in undefined behavior.

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:

Dd430473.AbandonMessage(en-us,VS.85).png

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

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

WebServices.h

Library

WebServices.lib

DLL

WebServices.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft