Opérations de service côté client

Article
03/11/2025

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

WS_SERVICE_PROXY* serviceProxy : proxy de service pour l’appel.
WS_HEAP* tas : tas requis utilisé pour la sérialisation du corps et la désérialisation 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 un WS_HEAP* en tant que paramètre. Il s’agit d’un paramètre obligatoire utilisé pour la sérialisation/désérialisation des corps de messages aux paramètres.

L’application doit appeler WsResetHeap si l’appel a 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 sa fin 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 de service côté client et 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;

Paramètre d’erreur

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

Obtenez des informations d’erreur enrichies si une défaillance se produit pendant l’appel d’opération de service.
Récupérez l’objet d’erreur si le service a retourné une erreur. L’erreur est contenue dans l’objet d’erreur. 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 pour abandonner le contrôle à l’application, de sorte que l’achèvement des appels réels soit géré par l’infrastructure. Le proxy de service fournit cette fonctionnalité via WsAbandonCall.

Notez que le contrôle à l’appelant ne peut pas être remis immédiatement, la seule garantie que le runtime du proxy de service donne est qu’il n’attend pas que l’opération liée aux E/S se termine avant de remettre le contrôle à l’appelant.

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

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

Délais d’attente 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é proxy de service lors de la création d’un proxy de service via WsCreateServiceProxy.

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

Valeurs de retour

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

WS_S_ASYNC: l’appel est terminé de façon asynchrone.
NOERROR : Appel terminé avec succès.
WS_E_OPERATION_ABANDONED: l’appel a été abandonné. L’objet d’erreur 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, vérifiez 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