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_E_INVALID_OPERATION
 通道不是處於WS_CHANNEL_STATE_OPEN或WS_CHANNEL_STATE_FAULTED狀態。 (針對通道狀態，請參閱 WS_CHANNEL_STATE enumeration.)
E_INVALIDARG
 指定的訊息目前不是在指定的通道上讀取或寫入。

備註

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

此圖顯示 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