クライアント側のサービス操作

[アーティクル]
03/11/2025

クライアント側サービス操作のレイアウトを次に示します。

WS_SERVICE_PROXY* serviceProxy: 呼び出しのサービスプロキシ。
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を使用してインパラメーターとアウトパラメーターにメモリを割り当てる必要があります。サービスプロキシは、指定されたポインターが上書きされるように、それらを再割り当てする必要がある場合があります。このようなメモリを解放しようとすると、アプリケーションがクラッシュします。

クライアント側のサービス操作と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;

Error パラメーター

アプリケーションは常にエラーパラメーターを渡して次のコードを実行する必要があります。

サービス操作の呼び出し中にエラーが発生した場合は、豊富なエラー情報を取得します。
サービスがエラーを返した場合は、障害オブジェクトを取得します。エラーはエラーオブジェクトに含まれています。この場合、サービス操作から返される HRESULT 値は WS_E_ENDPOINT_FAULT_RECEIVED されます (Windows Web サービスの戻り値参照)。

クライアント側サービス操作の呼び出しプロパティ

呼び出しプロパティを使用すると、アプリケーションは特定の呼び出しのカスタム設定を指定できます。現在、サービスモデルで使用できる呼び出しプロパティは 1 つだけ 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);

通話の破棄

多くの場合、実際の呼び出しの完了がインフラストラクチャによって処理されるように、アプリケーションに制御を放棄するために、呼び出しの結果を破棄することが望ましいです。サービスプロキシは、WsAbandonCallを介してこの機能を提供します。

呼び出し元に制御をすぐに返さない場合があることに注意してください。サービスプロキシランタイムが提供する唯一の保証は、I/O バインド操作が完了するのを待たないと呼び出し元に制御を返さないことを保証することです。

クライアント側のサービス操作での呼び出しは、WsAbandonCall呼び出しによって破棄できます。サービスプロキシと呼び出し ID を受け取ります。呼び出し ID は、サービス操作の呼び出しプロパティの一部として指定されます。

呼び出し ID が 0 の場合、サービスプロキシはそのインスタンスで保留中のすべての呼び出しを破棄します。

通話タイムアウト

既定では、サービスプロキシは呼び出しごとに 30 秒のタイムアウトになります。 WsCreateServiceProxyを使用してサービスプロキシ作成するときに、サービスプロキシプロパティ WS_PROXY_PROPERTY_CALL_TIMEOUT することで、呼び出しのタイムアウトを変更できます。

タイムアウトに達すると、呼び出しは破棄されます。

戻り値

HRESULT 値成功はすべて成功として扱う必要があり、すべての失敗値は失敗として扱う必要があります。アプリケーションで期待できる HRESULT 値の一部を次に示します。

WS_S_ASYNC: 呼び出しは非同期的に完了します。
NOERROR: 呼び出しが正常に完了しました。
WS_E_OPERATION_ABANDONED: 呼び出しは破棄されました。エラーオブジェクトには、破棄の理由が含まれています。
WS_E_INVALID_OPERATION: サービスプロキシが呼び出しを行う適切な状態ではありません。サービスプロキシの状態を確認して、サービスプロキシの状態を確認します。

戻り値の完全な一覧については、「Windows Web サービスの戻り値を参照してください。

コード例

コード例については、次を参照してください。

CallAbandonExample の
WsAbandonCallの

次の方法で共有