WsAbandonMessage 函式 (webservices.h)
略過指定通道上指定 訊息 的其餘部分。
語法
HRESULT WsAbandonMessage(
[in] WS_CHANNEL *channel,
[in] WS_MESSAGE *message,
[in, optional] WS_ERROR *error
);
參數
[in] channel
WS_CHANNEL 結構的指標,代表正在讀取或寫入訊息的通道。
[in] message
表示要放棄之訊息 之WS_MESSAGE 結構的指標。 這應該是傳遞至 WsWriteMessageStart 或 WsReadMessageStart 函式的相同訊息。
[in, optional] error
WS_ERROR 結構的指標,如果函式失敗,則會接收其他錯誤資訊。
傳回值
如果函式成功,它會傳回NO_ERROR;否則,它會傳回 HRESULT 錯誤碼。
傳回碼 | Description |
---|---|
|
通道不是處於WS_CHANNEL_STATE_OPEN或WS_CHANNEL_STATE_FAULTED狀態。 (針對通道狀態,請參閱 WS_CHANNEL_STATE enumeration.) |
|
指定的訊息目前不是在指定的通道上讀取或寫入。 |
備註
WsAbandonMessage 可用來略過讀取或寫入訊息的其餘內容,允許讀取或寫入通道的下一個訊息。 在此方面,它是 WsReadMessageEnd 或 WsWriteMessageEnd 函式的替代方案,如下列狀態圖所示:
對於讀取作業,應用程式通常會在應用程式不需要時呼叫 WsAbandonMessage ,以繼續讀取訊息數據,例如,如果訊息不符合應用程式的需求。 如果訊息包含格式不正確的 XML,或 XML 讀取器 在讀取訊息時產生錯誤,也可以使用此函式。
如果通道串流處理 (看到 WS_TRANSFER_MODE 列舉) 的WS_STREAMED_INPUT_TRANSFER_MODE值,則會讀取串流訊息數據的其餘部分,並在通道的下一次呼叫 WsReadMessageStart 或 WsCloseChannel 時自動捨棄。 如果未串流通道,則只會捨棄未讀取的緩衝訊息數據。
針對寫入作業,當應用程式無法繼續寫入訊息時,應用程式通常會呼叫 WsAbandonMessage ,因為發生某些錯誤,例如 XML 寫入器所傳回的訊息,或必須基於其他原因停止產生訊息。
如果通道串流處理 (看到WS_TRANSFER_MODE列舉) 的 WS_STREAMED_INPUT_TRANSFER_MODE 值,訊息數據將會遭到截斷,而且在遠端合作物件讀取時可能會導致錯誤。 如果未串流通道,訊息的緩衝數據只會捨棄 (,因為從未傳輸) 。
此函式可讓使用者讓通道保持開啟,並傳送或接收其他訊息 (,例如傳送錯誤) ,即使發生錯誤也一樣。 相反地, WsAbortChannel 會導致通道發生錯誤。 典型的使用方式是先嘗試放棄訊息並傳送錯誤。 如果失敗,則可以中止通道。
此函式不會執行任何封鎖 I/O。
只有當通道處於WS_CHANNEL_STATE_OPEN或WS_CHANNEL_STATE_FAULTED狀態時,此函式才有效。 (針對通道狀態,請參閱 WS_CHANNEL_STATE enumeration.)
指定的訊息必須是正在讀取的目前訊息,或為指定的通道寫入目前的訊息。
如果呼叫正確,則此函式不會失敗 (例如,因為缺少系統資源) 。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 7 [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows Server 2008 R2 [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | webservices.h |
程式庫 | WebServices.lib |
Dll | WebServices.dll |