Operazioni sul servizio lato client

Articolo
06/13/2023

Di seguito è riportato il layout di un'operazione sul lato client:

WS_SERVICE_PROXY* serviceProxy: proxy del servizio per la chiamata.
WS_HEAP* heap: heap richiesto usato per la serializzazione del corpo e la deserializzazione del WS_MESSAGE.
Parametri delle operazioni del servizio: parametri relativi all'operazione del servizio.
Chiamare Proprietà e il relativo conteggio: matrice di proprietà della chiamata.
Numero di proprietà call: conteggio delle proprietà della chiamata.
WS_ASYNC_CONTEXT asyncContext: contesto asincrono per l'esecuzione asincrona della chiamata.
WS_ERROR errore: oggetto errore avanzato.

Firma per operazioni sul servizio lato 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);

Considerazioni sulla memoria per le operazioni sul servizio lato client

La chiamata all'operazione di servizio accetta un WS_HEAP* come parametro. Questo è un parametro obbligatorio usato per la serializzazione/deserializzazione dei corpi dei messaggi ai parametri.

L'applicazione deve chiamare WsResetHeap se la chiamata ha avuto esito positivo o meno. Se la chiamata ha esito positivo e ha parametri in uscita, l'applicazione deve chiamare WsResetHeap immediatamente dopo aver completato i parametri in uscita.

L'applicazione deve allocare memoria per parametri in e out con WsAlloc. Il proxy del servizio potrebbe dover riallocarli in modo che i puntatori forniti vengano sovrascritti. Un tentativo di liberare tale memoria causerà l'arresto anomalo dell'applicazione.

Operazione del servizio sul lato client e 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;

Parametro di errore

L'applicazione deve sempre passare il parametro di errore a:

Ottenere informazioni di errore avanzate se si verifica un errore durante la chiamata all'operazione del servizio.
Ottenere l'oggetto di errore se il servizio ha restituito un errore. L'errore è contenuto nell'oggetto error. In questo caso, il valore HRESULT restituito dall'operazione di servizio è WS_E_ENDPOINT_FAULT_RECEIVED (vedere Valori restituiti di Servizi Web Windows).

Chiamare le proprietà per le operazioni sul servizio lato client

Le proprietà della chiamata consentono a un'applicazione di specificare impostazioni personalizzate per una chiamata specificata. Attualmente, è disponibile una sola proprietà di chiamata con il modello di servizio, 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);

Abbandono di una chiamata

Spesso è consigliabile abbandonare i risultati di una chiamata per rimettere il controllo all'applicazione, in modo che il completamento effettivo della chiamata venga gestito dall'infrastruttura. Il proxy di servizio fornisce questa struttura tramite WsAbandonCall.

Si noti che il controllo al chiamante potrebbe non essere restituito immediatamente, l'unica garanzia che il runtime del proxy del servizio fornisce è che non attendere il completamento di un'operazione associata di I/O prima che restituisca il controllo al chiamante.

Le chiamate su un'operazione sul lato client possono essere abbandonate tramite una chiamata a WsAbandonCall. Accetta un proxy di servizio e un ID chiamata. Un ID chiamata viene assegnato come parte di proprietà di una chiamata in un'operazione di servizio.

Se l'ID chiamata è 0, il proxy del servizio abbandonerà tutte le chiamate in sospeso in tale istanza.

Timeout delle chiamate

Per impostazione predefinita, un proxy di servizio ha un timeout di 30 secondi per ogni chiamata. Il timeout in una chiamata può essere modificato WS_PROXY_PROPERTY_CALL_TIMEOUT proprietà proxy del servizio durante la creazione di un proxy di servizio tramite WsCreateServiceProxy.

Dopo aver raggiunto un timeout, la chiamata viene abbandonata.

Valori restituiti

Tutti i valori HRESULT riusciti devono essere considerati correttamente e tutti i valori di errore devono essere considerati errori. Di seguito sono riportati alcuni dei valori HRESULT previsti da un'applicazione:

WS_S_ASYNC: la chiamata verrà completata in modo asincrono.
NOERROR: chiamata completata correttamente.
WS_E_OPERATION_ABANDONED: la chiamata è stata abbandonata. L'oggetto error contiene il motivo dell'abbandono.
WS_E_INVALID_OPERATION: il proxy del servizio non è in uno stato appropriato per effettuare una chiamata, controllare lo stato del proxy del servizio per capire lo stato del proxy del servizio.

Per un elenco completo dei valori restituiti, vedere Valori restituiti di Servizi Web Windows.

Esempi di codice

Per esempi di codice, vedere quanto segue:

Condividi tramite