Opérations de service côté client

Article
06/13/2023

Voici la disposition d’une opération de service côté client :

WS_SERVICE_PROXY* serviceProxy : proxy de service pour l’appel.
tas WS_HEAP* : segment requis utilisé pour la sérialisation et la désérialisation du corps du WS_MESSAGE.
Paramètres des opérations de service : paramètres relatifs à l’opération de service.
Propriétés d’appel et leur nombre : tableau de propriétés d’appel.
Nombre de propriétés d’appel : nombre de propriétés d’appel.
WS_ASYNC_CONTEXT asyncContext : contexte asynchrone pour l’exécution asynchrone de l’appel.
WS_ERROR erreur : objet d’erreur enrichi.

Signature pour les opérations de service côté client

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

Considérations relatives à la mémoire pour les opérations de service côté client

L’appel à l’opération de service prend une WS_HEAP* comme paramètre. Il s’agit d’un paramètre obligatoire utilisé pour la sérialisation/désérialisation des corps de message en paramètres.

L’application doit appeler WsResetHeap , que l’appel ait réussi ou non. Si l’appel a réussi et qu’il a des paramètres sortants, l’application doit appeler WsResetHeap immédiatement après avoir terminé avec les paramètres sortants.

L’application doit allouer de la mémoire pour les paramètres entrants et sortants avec WsAlloc. Le proxy de service peut avoir besoin de les réallouer afin que les pointeurs fournis soient remplacés. Une tentative de libération de cette mémoire entraîne le blocage de l’application.

Opération et WS_HEAP de service côté client

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;

Paramètre d’erreur

L’application doit toujours passer le paramètre d’erreur à :

Obtenez des informations d’erreur enrichies si un échec se produit pendant l’appel de l’opération de service.
Obtenez l’objet d’erreur si le service a retourné une erreur. L’erreur est contenue dans l’objet error. Dans ce cas, la valeur HRESULT retournée par l’opération de service est WS_E_ENDPOINT_FAULT_RECEIVED (voir Valeurs de retour des services Web Windows).

Propriétés d’appel pour les opérations de service côté client

Les propriétés d’appel permettent à une application de spécifier des paramètres personnalisés pour un appel donné. Actuellement, une seule propriété d’appel est disponible avec le modèle de service , 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);

Abandon d’un appel

Il est souvent souhaitable d’abandonner les résultats d’un appel afin de remettre le contrôle à l’application, de sorte que l’achèvement réel de l’appel soit géré par l’infrastructure. Le proxy de service fournit cette fonctionnalité via WsAbandonCall.

Notez que le contrôle de l’appelant peut ne pas être remis immédiatement. La seule garantie que le runtime du proxy de service offre est qu’il n’attend pas la fin d’une opération liée aux E/S avant de redonner le contrôle à l’appelant.

Les appels sur une opération de service côté client peuvent être abandonnés au moyen d’un appel à WsAbandonCall. Il prend un proxy de service et un ID d’appel. Un ID d’appel est fourni dans le cadre des propriétés d’un appel sur une opération de service.

Si l’ID d’appel est 0, le proxy de service abandonne tous les appels en attente à ce instance.

Délais d’expiration des appels

Par défaut, un proxy de service a un délai d’expiration de 30 secondes pour chaque appel. Le délai d’expiration d’un appel peut être modifié par WS_PROXY_PROPERTY_CALL_TIMEOUT propriété de proxy de service lors de la création d’un proxy de service via WsCreateServiceProxy.

Une fois le délai d’expiration atteint, l’appel est abandonné.

Valeurs de retour

Toutes les valeurs HRESULT de réussite doivent être traitées comme réussite, et toutes les valeurs d’échec doivent être traitées comme des échecs. Voici quelques-unes des valeurs HRESULT auxquelles une application peut s’attendre :

WS_S_ASYNC : l’appel est effectué de manière asynchrone.
NOERROR : Appel terminé avec succès.
WS_E_OPERATION_ABANDONED : L’appel a été abandonné. L’objet error contient la raison de l’abandon.
WS_E_INVALID_OPERATION : le proxy de service n’est pas dans un état approprié pour effectuer un appel, case activée l’état du proxy de service pour déterminer l’état du proxy de service.

Pour obtenir la liste complète des valeurs de retour, consultez Valeurs de retour des services Web Windows.

Exemples de code

Pour obtenir des exemples de code, consultez les rubriques suivantes :

Partager via