共用方式為


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 結構的指標。 這應該是傳遞至 WsWriteMessageStartWsReadMessageStart 函式的相同訊息。

[in, optional] error

WS_ERROR 結構的指標,如果函式失敗,則會接收其他錯誤資訊。

傳回值

如果函式成功,它會傳回NO_ERROR;否則,它會傳回 HRESULT 錯誤碼。

傳回碼 Description
WS_E_INVALID_OPERATION
通道不是處於WS_CHANNEL_STATE_OPEN或WS_CHANNEL_STATE_FAULTED狀態。 (針對通道狀態,請參閱 WS_CHANNEL_STATE enumeration.)
E_INVALIDARG
指定的訊息目前不是在指定的通道上讀取或寫入。

備註

WsAbandonMessage 可用來略過讀取或寫入訊息的其餘內容,允許讀取或寫入通道的下一個訊息。 在此方面,它是 WsReadMessageEndWsWriteMessageEnd 函式的替代方案,如下列狀態圖所示:

此圖顯示 WsAbandonMessage 函式所造成的狀態轉換與 WSReadMessageEnd 和 WsWriteMessageEnd 函式有何不同。

對於讀取作業,應用程式通常會在應用程式不需要時呼叫 WsAbandonMessage ,以繼續讀取訊息數據,例如,如果訊息不符合應用程式的需求。 如果訊息包含格式不正確的 XML,或 XML 讀取器 在讀取訊息時產生錯誤,也可以使用此函式。

如果通道串流處理 (看到 WS_TRANSFER_MODE 列舉) 的WS_STREAMED_INPUT_TRANSFER_MODE值,則會讀取串流訊息數據的其餘部分,並在通道的下一次呼叫 WsReadMessageStartWsCloseChannel 時自動捨棄。 如果未串流通道,則只會捨棄未讀取的緩衝訊息數據。

針對寫入作業,當應用程式無法繼續寫入訊息時,應用程式通常會呼叫 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