WsReceiveMessage 函数 (webservices.h)

接收消息并将消息正文反序列化为值。

语法

HRESULT WsReceiveMessage(
  [in]           WS_CHANNEL                   *channel,
  [in]           WS_MESSAGE                   *message,
                 const WS_MESSAGE_DESCRIPTION **messageDescriptions,
  [in]           ULONG                        messageDescriptionCount,
  [in]           WS_RECEIVE_OPTION            receiveOption,
  [in]           WS_READ_OPTION               readBodyOption,
  [in, optional] WS_HEAP                      *heap,
                 void                         *value,
  [in]           ULONG                        valueSize,
                 ULONG                        *index,
  [in, optional] const WS_ASYNC_CONTEXT       *asyncContext,
  [in, optional] WS_ERROR                     *error
);

参数

[in] channel

要从其接收的通道。

[in] message

用于接收的消息对象。

消息应处于 WS_MESSAGE_STATE_EMPTY 状态。

messageDescriptions

指向消息说明的指针数组，指定预期消息类型的元数据。

[in] messageDescriptionCount

messageDescriptions 数组中的项数。

[in] receiveOption

消息是否是必需的。 有关详细信息 ，请参阅WS_RECEIVE_OPTION 。

[in] readBodyOption

正文元素是否是必需的，以及如何分配值。
有关详细信息 ，请参阅WS_READ_OPTION 。

[in, optional] heap

要存储反序列化值的堆。 如果给定类型不需要堆，则此参数可以为 NULL。

value

此参数的解释取决于 WS_READ_OPTION。

如果为 receiveOption 参数指定 了 WS_RECEIVE_OPTIONAL_MESSAGE ，并且通道上没有更多消息可用，则不会触及此参数。 在这种情况下，函数返回 WS_S_END。 (请参阅 Windows Web Services 返回值。)

如果匹配 的WS_MESSAGE_DESCRIPTION 的 bodyElementDescription 为 NULL，则不会触及此参数。 在这种情况下，不需要指定 参数。

[in] valueSize

此参数的解释取决于 WS_READ_OPTION。

index

如果为 receiveOption 参数指定 了WS_RECEIVE_OPTIONAL_MESSAGE ，并且通道上没有更多消息可用，则此参数保持不变。 在这种情况下，函数将返回 WS_S_END。

否则，如果函数成功，则会将从零开始的索引包含在消息说明数组中，指示匹配的索引。

如果调用方对值 (不感兴趣，则此参数可能为 NULL ，例如，如果) 只有一条消息说明。

[in, optional] asyncContext

有关如何异步调用函数的信息;如果以同步方式调用，则为 NULL 。

[in, optional] error

指定函数失败时应存储其他错误信息的位置。

返回值

此函数可以返回其中一个值。

注解

此函数使用有关预期消息类型的元数据来反序列化正文。
元数据是指向 WS_MESSAGE_DESCRIPTION的指针数组。 每个消息说明都包含一个操作值（用于与消息的操作匹配）和一个 WS_ELEMENT_DESCRIPTION （提供正文元素的元数据）。

收到消息标头后，函数将扫描数组以查找与操作匹配项。 匹配的第一个消息说明用于反序列化正文，数组中此消息说明的从零开始的索引在 index out 参数中返回。 如果函数成功，则始终将 index out 参数设置为指示使用了哪个消息说明。

为了使消息说明匹配，操作值必须完全匹配消息的值。 如果 WS_MESSAGE_DESCRIPTION 中的操作为 NULL，则该操作始终匹配。 在接收的消息中没有操作标头的情况下，或者无论操作是什么，正文始终相同时，都可以使用此方法。

如果正文预期为空，则 WS_MESSAGE_DESCRIPTION 的 bodyElementDescription 字段可能为 NULL。

如果 bodyElementDescription 为非 NULL，则此函数将反序列化正文，如 WsReadBody 中所述。

收到消息后，可以使用 WsGetHeader 或 WsGetCustomHeader 检查其标头。

要求