通过

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_S_ASYNC
 异步操作仍处于挂起状态。
WS_S_END
 指定 了接收选项WS_RECEIVE_OPTIONAL_MESSAGE ，并且没有更多可用于通道的消息。
WS_E_ENDPOINT_FAULT_RECEIVED
 收到的消息包含错误。 可以使用 WsGetErrorProperty 从WS_ERROR中提取错误。
WS_E_OPERATION_ABORTED
 操作已中止。
WS_E_INVALID_OPERATION
 由于对象的当前状态，不允许该操作。
WS_E_ENDPOINT_NOT_FOUND
 远程终结点不存在或找不到。
WS_E_ENDPOINT_ACCESS_DENIED
 远程终结点拒绝了访问。
WS_E_ENDPOINT_DISCONNECTED
 与远程终结点的连接已终止。
WS_E_ENDPOINT_FAILURE
 远程终结点无法处理请求。
WS_E_ENDPOINT_NOT_AVAILABLE
 远程终结点当前未在此位置使用。
WS_E_ENDPOINT_TOO_BUSY
 由于重载，远程终结点无法处理请求。
WS_E_ENDPOINT_UNREACHABLE
 无法访问远程终结点。
WS_E_INVALID_ENDPOINT_URL
 终结点地址 URL 无效。
WS_E_INVALID_FORMAT
 输入数据未采用预期格式或没有预期值。
WS_E_OPERATION_TIMED_OUT
 操作未在分配的时间内完成。
WS_E_PROXY_ACCESS_DENIED
 HTTP 代理服务器拒绝了访问。
WS_E_PROXY_FAILURE
 HTTP 代理服务器无法处理请求。
WS_E_QUOTA_EXCEEDED
 超出配额。
WS_E_SECURITY_VERIFICATION_FAILURE
 收到的数据的安全验证未成功。
WS_E_SECURITY_SYSTEM_FAILURE
 Windows Web Services 框架中的安全操作失败。
WS_E_SECURITY_TOKEN_EXPIRED
 服务器拒绝了安全令牌，因为它已过期。
WS_E_PROXY_REQUIRES_BASIC_AUTH
 HTTP 代理服务器需要 HTTP 身份验证方案“basic”。
WS_E_PROXY_REQUIRES_DIGEST_AUTH
 HTTP 代理服务器需要 HTTP 身份验证方案“digest”。
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
 HTTP 代理服务器需要 HTTP 身份验证方案“协商”。
WS_E_PROXY_REQUIRES_NTLM_AUTH
 HTTP 代理服务器需要 HTTP 身份验证方案“NTLM”。
WS_E_SERVER_REQUIRES_BASIC_AUTH
 远程终结点需要 HTTP 身份验证方案“basic”。
WS_E_SERVER_REQUIRES_DIGEST_AUTH
 远程终结点需要 HTTP 身份验证方案“digest”。
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
 远程终结点需要 HTTP 身份验证方案“协商”。
WS_E_SERVER_REQUIRES_NTLM_AUTH
 远程终结点需要 HTTP 身份验证方案“NTLM”。
CERT_E_EXPIRED
 根据当前系统时钟或已签名文件中的时间戳进行验证时，所需证书不在有效期内。
CERT_E_CN_NO_MATCH
 证书 CN 名称与传递的值不匹配。
CERT_E_UNTRUSTEDROOT
 证书链已处理，但在信任提供程序不信任的根证书中终止。
CERT_E_WRONG_USAGE
 该证书对于请求的用法无效。
CRYPT_E_REVOCATION_OFFLINE
 吊销功能无法检查吊销，因为吊销服务器已脱机。
E_OUTOFMEMORY
 内存不足。
E_INVALIDARG
 一个或多个参数无效。
其他错误
此函数可能会返回上面未列出的其他错误。

注解

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

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

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

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

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

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

要求

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