Clientseitige Dienstvorgänge

Artikel
06/13/2023

Im Folgenden wird das Layout eines clientseitigen Dienstvorgangs dargestellt:

WS_SERVICE_PROXY* serviceProxy: Der Dienstproxy für den Aufruf.
WS_HEAP*-Heap: Ein erforderlicher Heap, der für die Serialisierung und Deserialisierung des WS_MESSAGE verwendet wird.
Dienstbetriebsparameter: Parameter, die sich auf den Dienstvorgang beziehen.
Aufrufeigenschaften und deren Anzahl: Ein Array von Aufrufeigenschaften.
Anzahl der Aufrufeigenschaften : Die Anzahl der Aufrufeigenschaften.
WS_ASYNC_CONTEXT asyncContext: Asynchroner Kontext zum asynchronen Ausführen des Aufrufs.
WS_ERROR Fehler: Rich error object.

Signatur für clientseitige Dienstvorgänge

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

Überlegungen zum Arbeitsspeicher für clientseitige Dienstvorgänge

Der Aufruf des Dienstvorgangs verwendet einen WS_HEAP* als Parameter. Dies ist ein erforderlicher Parameter, der für die Serialisierung/Deserialisierung von Nachrichtentexten zu Parametern verwendet wird.

Die Anwendung muss WsResetHeap aufrufen, unabhängig davon, ob der Aufruf erfolgreich war oder nicht. Wenn der Aufruf erfolgreich war und über ausgehende Parameter verfügt, sollte die Anwendung WsResetHeap sofort aufrufen, nachdem sie mit den ausgehenden Parametern abgeschlossen wurde.

Die Anwendung sollte Arbeitsspeicher für In- und Out-Parameter mit WsAlloc zuordnen. Der Dienstproxy muss sie möglicherweise neu zuordnen, damit bereitgestellte Zeiger überschrieben werden. Ein Versuch, diesen Arbeitsspeicher freizugeben, führt dazu, dass die Anwendung abstürzt.

Clientseitiger Dienstvorgang und 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;

Fehlerparameter

Die Anwendung sollte den Fehlerparameter immer an Folgendes übergeben:

Rufen Sie umfassende Fehlerinformationen ab, wenn während des Dienstvorgangsaufrufs ein Fehler auftritt.
Ruft das Fehlerobjekt ab, wenn der Dienst einen Fehler zurückgegeben hat. Der Fehler ist im Fehlerobjekt enthalten. In diesem Fall wird der vom Dienstvorgang zurückgegebene HRESULT-WertWS_E_ENDPOINT_FAULT_RECEIVED (siehe Rückgabewerte für Windows-Webdienste).

Aufrufeigenschaften für clientseitige Dienstvorgänge

Aufrufeigenschaften ermöglichen es einer Anwendung, benutzerdefinierte Einstellungen für einen bestimmten Aufruf anzugeben. Derzeit ist nur eine Aufrufeigenschaft mit dem Dienstmodell verfügbar, 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);

Abbrechen eines Anrufs

Es ist häufig wünschenswert, die Ergebnisse eines Aufrufs aufzugeben, um das Steuerelement an die Anwendung zurückzugeben, sodass der eigentliche Aufrufabschluss von der Infrastruktur verarbeitet wird. Der Dienstproxy stellt diese Funktion über WsAbandonCall bereit.

Beachten Sie, dass das Steuerelement an den Aufrufer möglicherweise nicht sofort zurückerhalten wird. Die einzige Garantie, die die Dienstproxylaufzeit gibt, besteht darin, dass sie nicht auf den Abschluss eines E/A-gebundenen Vorgangs wartet, bevor sie dem Aufrufer die Kontrolle zurückgibt.

Aufrufe eines clientseitigen Dienstvorgangs können über einen Aufruf von WsAbandonCall abgebrochen werden. Sie benötigt einen Dienstproxy und eine Aufruf-ID. Eine Aufruf-ID wird als Teil einer Aufrufeigenschaften für einen Dienstvorgang angegeben.

Wenn die Aufruf-ID 0 ist, gibt der Dienstproxy alle ausstehenden Aufrufe an diesem instance ab.

Aufruftimeouts

Standardmäßig weist ein Dienstproxy für jeden Aufruf ein Timeout von 30 Sekunden auf. Das Timeout für einen Aufruf kann durch WS_PROXY_PROPERTY_CALL_TIMEOUT Dienstproxyeigenschaft geändert werden, wenn ein Dienstproxy über WsCreateServiceProxy erstellt wird.

Nachdem ein Timeout erreicht wurde, wird der Anruf abgebrochen.

Rückgabewerte

Alle Erfolgs-HRESULT-Werte müssen als Erfolg behandelt werden, und alle Fehlerwerte müssen als Fehler behandelt werden. Im Folgenden finden Sie einige der HRESULT-Werte , die eine Anwendung erwarten kann:

WS_S_ASYNC: Der Aufruf wird asynchron abgeschlossen.
NOERROR: Der Aufruf wurde erfolgreich abgeschlossen.
WS_E_OPERATION_ABANDONED: Der Aufruf wurde abgebrochen. Das Fehlerobjekt enthält den Grund für den Abbruch.
WS_E_INVALID_OPERATION: Der Dienstproxy befindet sich nicht in einem geeigneten Zustand, um einen Aufruf zu tätigen. Überprüfen Sie den Dienstproxystatus, um den Status des Dienstproxys zu ermitteln.

Eine vollständige Liste der Rückgabewerte finden Sie unter Rückgabewerte für Windows-Webdienste.

Codebeispiele

Codebeispiele finden Sie in den folgenden Artikeln:

Freigeben über