訊息 (Windows Web 服務)

訊息是封裝傳輸或接收之資料的物件。 訊息的結構是由 SOAP 所定義,並包含一組標頭和本文。 標頭一律會緩衝處理于記憶體中,但本文是以串流 API 讀取和寫入。

Diagram showing a message with the header being buffered and the body being streamed.

訊息有一組屬性,可用來指定可控制訊息行為的選擇性設定,並提供方法來擷取所接收訊息的其他資訊(例如安全性資訊)。 如需訊息屬性的完整清單,請參閱 WS_MESSAGE_PROPERTY_ID

訊息會定址至特定的 端點位址

WS_FAULT 是一種特殊的訊息內容,用來代表從遠端端點傳回的失敗。

訊息會進行編碼,在傳輸之前,將 XML 轉換成線性線格式。

如需訊息的詳細資訊,請參閱 通道層概觀 主題。

下列範例說明如何在 WWSAPI 中使用訊息。

範例 描述
CustomHeaderExample 說明如何使用自訂訊息標頭。
MessageEncodingExample 說明編碼和解碼訊息。
ForwardMessageExample 說明轉送訊息。

 

下列 API 元素會與訊息搭配使用。

回撥 描述
WS_MESSAGE_DONE_CALLBACK 通知呼叫端訊息已完成使用提供給 WsReadEnvelopeStart 函式的WS_XML_READER結構,或提供給 WsWriteEnvelopeStart 函式的WS_XML_WRITER結構。

 

列舉型別 描述
WS_ADDRESSING_VERSION 用於定址標頭的規格版本。
WS_ENVELOPE_VERSION 用於信封結構的規格版本。
WS_HEADER_ATTRIBUTES 一組旗標,表示標頭的 SOAP mustUnderstand 和轉送屬性。
WS_HEADER_TYPE 標頭的類型。
WS_MESSAGE_INITIALIZATION 指定 WsInitializeMessage 應該新增至訊息的標頭
WS_MESSAGE_PROPERTY_ID 每個訊息屬性的識別碼。
WS_MESSAGE_STATE 訊息的狀態。

 

函式 描述
WsAddressMessage 將目的地位址指派給訊息。
WsCheckMustUnderstandHeaders 確認接收者已適當瞭解指定的標頭。
WsCreateMessage 建立WS_MESSAGE 物件的實例
WsCreateMessageForChannel 建立適合與特定通道搭配使用的訊息。
WsFillBody 確保訊息中有足夠的位元組可供讀取。
WsFlushBody 排清所有已寫入的累積訊息本文資料。
WsFreeMessage 釋放與訊息相關聯的記憶體資源。
WsGetCustomHeader 尋找訊息的應用程式定義標頭,並將其還原序列化。
WsGetHeader 在訊息中尋找特定的標準標頭,並將其還原序列化。
WsGetHeaderAttributes 使用讀取器所在的標頭專案WS_HEADER_ATTRIBUTES 填入 ULONG 參數
WsGetMessageProperty 擷取指定的 Message 物件屬性。
WsInitializeMessage 初始化訊息的標頭,以準備處理。
WsMarkHeaderAsUnderstood 將標頭標示為應用程式所瞭解。
WsReadBody 從訊息的 XML 讀取器還原序列化值。
WsReadEnvelopeEnd 讀取訊息的結尾專案。
WsReadEnvelopeStart 讀取訊息的標頭,並準備讀取本文專案。
WsRemoveCustomHeader 從訊息中移除自訂標頭。
WsRemoveHeader 從訊息中移除標準 WS_HEADER_TYPE 物件。
WsResetMessage 將訊息狀態設定回 WS_MESSAGE_STATE_EMPTY
WsSetHeader 在訊息中加入或取代指定的標準標頭。
WsWriteBody 在訊息本文中寫入值。
WsWriteEnvelopeEnd 寫入訊息的結尾專案。
WsWriteEnvelopeStart 寫入訊息的開頭,包括訊息的目前標頭集,並準備寫入本文專案。

 

Handle 描述
WS_MESSAGE 用來參考訊息物件的不透明型別。

 

結構 描述
WS_FAULT 訊息本文中攜帶的錯誤值,表示處理失敗。
WS_FAULT_CODE 表示錯誤碼。
WS_FAULT_REASON 包含錯誤的說明。
WS_MESSAGE_PROPERTIES 指定一組 WS_MESSAGE_PROPERTY 結構。
WS_MESSAGE_PROPERTY 指定訊息特定設定。