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
收到的消息包含错误。 可以使用 WsGetErrorPropertyWS_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 中所述。

收到消息后,可以使用 WsGetHeaderWsGetCustomHeader 检查其标头。

要求

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