客户端服务操作

项目
06/13/2023

下面是客户端服务操作的布局：

WS_SERVICE_PROXY* serviceProxy：调用的服务代理。
WS_HEAP* 堆：用于 WS_MESSAGE的正文序列化和反序列化所需的堆。
服务操作参数：与服务操作相关的参数。
调用属性及其计数：一个调用属性数组。
调用属性计数：调用属性的计数。
WS_ASYNC_CONTEXT asyncContext：异步执行调用的异步上下文。
WS_ERROR 错误：Rich 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 参数分配内存。服务代理可能需要重新分配它们，以便覆盖提供的指针。尝试释放此类内存将导致应用程序崩溃。

客户端服务操作和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 Services 返回值) 。

客户端服务操作的调用属性

调用属性允许应用程序为给定调用指定自定义设置。目前，服务模型只有一个调用属性可用， 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：已放弃调用。 error 对象包含放弃的原因。
WS_E_INVALID_OPERATION：服务代理未处于调用的适当状态，检查服务代理状态来确定服务代理的状态。

有关返回值的完整列表，请参阅 Windows Web Services 返回值。

代码示例

有关代码示例，请参阅以下内容：

通过