Operações de serviço do lado do cliente

Artigo
06/13/2023

Veja a seguir o layout de uma operação de serviço do lado do cliente:

WS_SERVICE_PROXY* serviceProxy: o proxy de serviço para a chamada.
heap WS_HEAP*: um heap necessário usado para serialização do corpo e desserialização do WS_MESSAGE.
Parâmetros de operações de serviço: parâmetros relativos à operação de serviço.
Propriedades de chamada e sua contagem: uma matriz de propriedades de chamada.
Contagem de propriedades de chamada: a contagem de propriedades de chamada.
WS_ASYNC_CONTEXT asyncContext: contexto assíncrono para executar a chamada de forma assíncrona.
WS_ERROR erro: objeto rich error.

Assinatura para operações de serviço do lado do cliente

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);

Considerações de memória para operações de serviço do lado do cliente

A chamada para a operação de serviço usa um WS_HEAP* como parâmetro. Esse é um parâmetro necessário usado para serialização/desserialização de corpos de mensagens para parâmetros.

O aplicativo deve chamar WsResetHeap se a chamada foi bem-sucedida ou não. Se a chamada tiver êxito e tiver parâmetros de saída, o aplicativo deverá chamar WsResetHeap imediatamente após a conclusão com os parâmetros de saída.

O aplicativo deve alocar memória para parâmetros de entrada e saída com WsAlloc. O proxy de serviço pode precisar realocá-los para que os ponteiros fornecidos sejam substituídos. Uma tentativa de liberar essa memória fará com que o aplicativo falhe.

Operação de serviço e WS_HEAP do lado do cliente

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;

Parâmetro de erro

O aplicativo sempre deve passar o parâmetro de erro para:

Obtenha informações de erro avançadas se ocorrer uma falha durante a chamada de operação de serviço.
Obtenha o objeto de falha se o serviço retornou uma falha. A falha está contida no objeto de erro. Nesse caso, o valor HRESULT retornado da operação de serviço é WS_E_ENDPOINT_FAULT_RECEIVED (consulte Valores retornados dos Serviços Web do Windows).

Propriedades de chamada para operações de serviço do lado do cliente

As propriedades de chamada permitem que um aplicativo especifique configurações personalizadas para uma determinada chamada. Atualmente, apenas uma propriedade de chamada está disponível com o modelo de serviço , 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);

Abandonando uma chamada

Geralmente, é desejável abandonar os resultados de uma chamada para abrir mão do controle de volta para o aplicativo, de modo que a conclusão real da chamada seja tratada pela infraestrutura. O proxy de serviço fornece essa instalação por meio de WsAbandonCall.

Observe que o controle para o chamador pode não ser retornado imediatamente, a única garantia que o runtime de proxy de serviço fornece é que ele não esperaria que qualquer operação associada de E/S fosse concluída antes de devolver o controle ao chamador.

As chamadas em uma operação de serviço do lado do cliente podem ser abandonadas por meio de uma chamada para WsAbandonCall. Ele usa um proxy de serviço e uma ID de chamada. Uma ID de chamada é fornecida como parte de uma propriedade de chamada em uma operação de serviço.

Se a ID da chamada for 0, o proxy de serviço abandonará todas as chamadas pendentes nessa instância.

Tempos limite de chamada

Por padrão, um proxy de serviço tem um tempo limite de 30 segundos para cada chamada. O tempo limite em uma chamada pode ser alterado por WS_PROXY_PROPERTY_CALL_TIMEOUT propriedade de proxy de serviço ao criar um proxy de serviço por meio de WsCreateServiceProxy.

Depois que um tempo limite é atingido, a chamada é abandonada.

Valores de retorno

Todos os valores HRESULT de êxito devem ser tratados como êxito e todos os valores de falha devem ser tratados como falhas. Veja a seguir alguns dos valores HRESULT que um aplicativo pode esperar:

WS_S_ASYNC: a chamada será concluída de forma assíncrona.
NOERROR: chamada concluída com êxito.
WS_E_OPERATION_ABANDONED: a chamada foi abandonada. O objeto de erro contém o motivo do abandono.
WS_E_INVALID_OPERATION: o proxy de serviço não está em um estado apropriado para fazer uma chamada, marcar o estado do proxy de serviço para descobrir o estado do proxy de serviço.

Para obter uma lista completa de valores retornados, consulte Valores retornados dos Serviços Web do Windows.

Exemplos de código

Para obter exemplos de código, consulte o seguinte:

Compartilhar via