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

是否需要 body 元素，以及如何配置值。
如需詳細資訊 ，請參閱WS_READ_OPTION 。

[in, optional] heap

要儲存還原串行化值的堆積。 如果指定類型不需要堆積，則此參數可以是 NULL。

value

此參數的解譯取決於 WS_READ_OPTION。

如果已為 receiveOption 參數指定 WS_RECEIVE_OPTIONAL_MESSAGE ，而且通道上沒有其他可用的訊息，則不會觸碰此參數。 在此情況下，函式會 傳回WS_S_END。 (請參閱 Windows Web 服務傳回值。)

如果相符 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

指定函式失敗時應儲存其他錯誤資訊的位置。

傳回值

此函式可以傳回下列其中一個值。

傳回碼 Description
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 Proxy 伺服器拒絕存取。
WS_E_PROXY_FAILURE
 HTTP Proxy 伺服器無法處理要求。
WS_E_QUOTA_EXCEEDED
 超過配額。
WS_E_SECURITY_VERIFICATION_FAILURE
 已接收數據的安全性驗證未成功。
WS_E_SECURITY_SYSTEM_FAILURE
 Windows Web 服務架構中的安全性作業失敗。
WS_E_SECURITY_TOKEN_EXPIRED
 伺服器因為安全性令牌已過期而遭到拒絕。
WS_E_PROXY_REQUIRES_BASIC_AUTH
 HTTP Proxy 伺服器需要 HTTP 驗證配置 'basic'。
WS_E_PROXY_REQUIRES_DIGEST_AUTH
 HTTP Proxy 伺服器需要 HTTP 驗證配置 'digest'。
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
 HTTP Proxy 伺服器需要 HTTP 驗證配置 'negotiate'。
WS_E_PROXY_REQUIRES_NTLM_AUTH
 HTTP Proxy 伺服器需要 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 驗證配置 'negotiate'。
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
程式庫 WebServices.lib
Dll WebServices.dll