用戶端服務作業

發行項
06/13/2023

以下是用戶端服務作業的配置：

WS_SERVICE_PROXY* serviceProxy：呼叫的服務 Proxy 。
WS_HEAP* 堆積：用於主體序列化和還原序列化 WS_MESSAGE的必要堆積。
服務作業參數：與服務作業相關的參數。
呼叫屬性及其計數：呼叫屬性的陣列。
呼叫屬性計數：呼叫屬性的計數。
WS_ASYNC_CONTEXT asyncCoNtext：非同步執行呼叫的非同步內容。
WS_ERROR 錯誤：豐富的錯誤物件。

用戶端服務作業的簽章

typedef HRESULT(CALLBACK *ICalculator_Add)(WS_SERVICE_PROXY* serviceProxy, 
                                           WS_HEAP* heap, 
                                           ULONG a, ULONG b, ULONG* result, 
                                           const WS_CALL_PROPERTY* callProperties, 
                                           const ULONG callPropertyCount, 
                                           const WS_ASYNC_CONTEXT* asyncContext, 
                                           WS_ERROR* error);

用戶端服務作業的記憶體考慮

對服務作業的呼叫會採用 WS_HEAP* 作為參數。這是將訊息本文序列化/還原序列化為參數的必要參數。

無論呼叫是否成功，應用程式都必須呼叫 WsResetHeap 。如果呼叫成功且具有傳出參數，應用程式應該在傳出參數完成之後立即呼叫 WsResetHeap 。

應用程式應該使用 WsAlloc為 in 和 out 參數配置記憶體。服務 Proxy 可能需要重新配置它們，因此會覆寫提供的指標。嘗試釋放這類記憶體會導致應用程式當機。

用戶端服務作業和WS_HEAP

HRESULT hr = IProcessOrder_ProcessOrder(serviceProxy, heap, orderNumber, &orderReceipt, NULL, 0, NULL, error);
if(FAILED(hr))
    goto error;
hr = ProcessReceipt(orderReceipt);
WsResetHeap(heap);
if(FAILED(hr))
    goto error;
hr = IProcessOrder_CompleteOrder(serviceProxy, heap, orderNumber, &orderMemo, NULL, 0, NULL, error);
if(FAILED(hr))
    goto error;
hr = ProcessMemo(orderMemo);
WsResetHeap(heap);
if(FAILED(hr))
    goto error;

錯誤參數

應用程式應該一律將錯誤參數傳遞至：

如果在服務作業呼叫期間發生失敗，請取得豐富的錯誤資訊。
如果服務傳回錯誤，請取得錯誤物件。錯誤包含在錯誤物件中。在此情況下，從服務作業傳回的 HRESULT 值 WS_E_ENDPOINT_FAULT_RECEIVED ( 請參閱 Windows Web 服務傳回值) 。

呼叫用戶端服務作業的屬性

呼叫屬性可讓應用程式指定指定呼叫的自訂設定。目前，服務模型只能使用一個呼叫屬性， WS_CALL_PROPERTY_CALL_ID。

WS_CALL_PROPERTY callProperties[1] = {0};
callProperties[0].id = WS_CALL_PROPERTY_CALL_ID;
callProperties[0].value = 5;

HRESULT hr = IProcessOrder_ProcessOrder(serviceProxy, heap, orderNumber, &orderReceipt,  callProperties, WsCountOf(callProperties), NULL, error);
if(FAILED(hr))
    goto error;
//:
//:
hr = IProcessOrder_CompleteOrder(serviceProxy, heap, orderNumber, &orderReceipt, callProperties, WsCountOf(callProperties), NULL, error);
if(FAILED(hr))
    goto error;

//:
//:
//:
// On a separate thread 
// In this case both the calls belong to call group 5, and will abandon as a result of the call to WsAbandonCall. 
hr = WsAbandonCall(serviceProxy, 5, error);

放棄通話

通常想要放棄呼叫的結果，以便將控制項捨棄回應用程式，如此基礎結構就會處理實際的呼叫完成。服務 Proxy 透過 WsAbandonCall提供這項設施。

請注意，呼叫端的控制項可能不會立即傳回，唯一保證服務 Proxy 執行時間會提供，在於它不會等待任何 I/O 系結作業完成，再將控制權傳回給呼叫端。

用戶端服務作業上的呼叫可以藉由呼叫 WsAbandonCall來放棄。它會採用服務 Proxy 和呼叫識別碼。呼叫識別碼是服務作業上呼叫屬性的一部分。

如果呼叫識別碼為 0，則服務 Proxy 將會放棄該實例上的所有擱置呼叫。

呼叫逾時

根據預設，每個呼叫的服務 Proxy 都有 30 秒的逾時。透過WsCreateServiceProxy建立服務 Proxy 時，WS_PROXY_PROPERTY_CALL_TIMEOUT服務 Proxy 屬性可以變更呼叫逾時。

到達逾時之後，就會放棄呼叫。

傳回值

所有成功 HRESULT 值都必須視為成功，而且所有失敗值都必須視為失敗。以下是應用程式可以預期的一些 HRESULT 值：

WS_S_ASYNC：將會以非同步方式完成呼叫。
NOERROR：呼叫成功完成。
WS_E_OPERATION_ABANDONED：已放棄呼叫。 error 物件包含放棄的原因。
WS_E_INVALID_OPERATION：服務 Proxy 不是進行呼叫的適當狀態，請檢查服務 Proxy 狀態以找出服務 Proxy 的狀態。

如需傳回值的完整清單，請參閱 Windows Web 服務傳回值。

程式碼範例

如需程式碼範例，請參閱下列各項：

共用方式為