Operazioni sul servizio sul lato client

Articolo
03/11/2025

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

WS_SERVICE_PROXY* serviceProxy: proxy del servizio per la chiamata.
WS_HEAP* heap: heap necessario usato per la serializzazione del corpo e la deserializzazione del WS_MESSAGE.
Parametri delle operazioni del servizio: parametri relativi all'operazione del servizio.
Proprietà chiamata 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 della chiamata in modo asincrono.
WS_ERROR errore: oggetto errore rtf.

Firma per le operazioni del servizio sul 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 del servizio sul lato client

La chiamata all'operazione del servizio accetta un WS_HEAP* come parametro. Si tratta di 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 negativo. Se la chiamata ha esito positivo e ha parametri in uscita, l'applicazione deve chiamare WsResetHeap immediatamente dopo il completamento dei parametri in uscita.

L'applicazione deve allocare memoria per i 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 e WS_HEAP del servizio sul lato 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;

Parametro error

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

Ottenere informazioni dettagliate sull'errore 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 del servizio è WS_E_ENDPOINT_FAULT_RECEIVED (vedere Valori restituiti di Servizi Web Windows).

Chiamare le proprietà per le operazioni del servizio sul lato client

Le proprietà delle chiamate consentono a un'applicazione di specificare impostazioni personalizzate per una determinata chiamata. 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 rinunciare al controllo all'applicazione, in modo che il completamento effettivo della chiamata venga gestito dall'infrastruttura. Il proxy di servizio fornisce questa funzionalità tramite WsAbandonCall.

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

Le chiamate su un'operazione del servizio 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 una chiamata proprietà su un'operazione del 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 il raggiungimento di un timeout, la chiamata viene abbandonata.

Valori restituiti

Tutti i valori di HRESULT devono essere considerati come riusciti 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: la chiamata è stata 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 determinare lo stato del proxy del servizio.

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

Esempi di codice

Per esempi di codice, vedere quanto segue:

Condividi tramite