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 错误代码。

返回代码	说明
WS_E_INVALID_OPERATION	通道未处于WS_CHANNEL_STATE_OPEN或WS_CHANNEL_STATE_FAULTED状态。 (有关通道状态，请参阅 WS_CHANNEL_STATE enumeration.)
E_INVALIDARG	指定的消息当前未在指定通道上读取或写入。

注解

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 enumeration.)

指定的消息必须是正在读取的当前消息或为指定通道写入的当前消息。

如果调用正确，则此函数不会 (失败，例如，由于缺少系统资源) 。

要求

要求	值
最低受支持的客户端	Windows 7 [桌面应用 |UWP 应用]
最低受支持的服务器	Windows Server 2008 R2 [桌面应用 |UWP 应用]
目标平台	Windows
标头	webservices.h
Library	WebServices.lib
DLL	WebServices.dll