Operacje usługi po stronie klienta

Poniżej przedstawiono układ operacji usługi po stronie klienta:

• WS_SERVICE_PROXY* serviceProxy: serwer proxy usługi dla wywołania.
• WS_HEAP* sterta: wymagana sterta używana do serializacji ciała i deserializacji WS_MESSAGE.
• Parametry operacji usługi: parametry dotyczące operacji usługi.
• właściwości wywołania i ich liczba: tablica właściwości wywołań.
• liczba właściwości wywołania: liczba właściwości wywołań.
• WS_ASYNC_CONTEXT asyncContext: kontekst asynchroniczny do wykonywania wywołania asynchronicznie.
• błąd WS_ERROR: obiekt błędu wzbogaconego.

Podpis operacji usługi po stronie klienta

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

Zagadnienia dotyczące pamięci dla operacji usługi po stronie klienta

Wywołanie operacji usługi przyjmuje WS_HEAP* jako parametr. Jest to wymagany parametr używany do serializacji/deserializacji treści komunikatów do parametrów.

Aplikacja musi wywołać WsResetHeap, czy wywołanie powiodło się, czy nie. Jeśli wywołanie powiodło się i ma parametry wychodzące, aplikacja powinna wywołać WsResetHeap natychmiast po zakończeniu z parametrami wychodzącymi.

Aplikacja powinna przydzielić pamięć dla parametrów w parametrach in i out z WsAlloc. Serwer proxy usługi może wymagać reallokowania ich, więc podane wskaźniki zostaną zastąpione. Próba zwolnienia takiej pamięci spowoduje awarię aplikacji.

Operacja usługi po stronie klienta i 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;

Parametr błędu

Aplikacja powinna zawsze przekazywać parametr error do:

• Uzyskaj zaawansowane informacje o błędach, jeśli wystąpi błąd podczas wywołania operacji usługi.
• Pobierz obiekt błędu, jeśli usługa zwróciła błąd. Błąd jest zawarty w obiekcie error. W tym przypadku wartość HRESULT zwrócona z operacji usługi jest WS_E_ENDPOINT_FAULT_RECEIVED (zobacz Wartości zwracane usług sieci Web systemu Windows).

Właściwości wywołania operacji usługi po stronie klienta

Właściwości wywołania umożliwiają aplikacji określanie ustawień niestandardowych dla danego wywołania. Obecnie tylko jedna właściwość wywołania jest dostępna w modelu usługi, 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);

Porzucenie połączenia

Często pożądane jest porzucenie wyników wywołania, aby zrezygnować z kontrolki z powrotem do aplikacji, tak aby rzeczywiste ukończenie wywołań było obsługiwane przez infrastrukturę. Serwer proxy usługi udostępnia tę funkcję za pośrednictwem WsAbandonCall.

Należy pamiętać, że kontrolka obiektu wywołującego może nie zostać natychmiast przekazana, jedyną gwarancją, że środowisko uruchomieniowe serwera proxy usługi daje, jest to, że nie będzie czekać na ukończenie żadnej operacji powiązanej we/wy, zanim da kontrolę z powrotem do obiektu wywołującego.

Wywołania operacji usługi po stronie klienta można porzucić za pomocą wywołania polecenia WsAbandonCall. Pobiera serwer proxy usługi i identyfikator wywołania. Identyfikator wywołania jest podawany jako część właściwości wywołania operacji usługi.

Jeśli identyfikator wywołania to 0, serwer proxy usługi porzuci wszystkie oczekujące wywołania w tym wystąpieniu.

Limity czasu wywołań

Domyślnie serwer proxy usługi ma limit czasu 30 sekund dla każdego wywołania. Limit czasu wywołania można zmienić przez właściwość serwera proxy usługi WS_PROXY_PROPERTY_CALL_TIMEOUT podczas tworzenia serwera proxy usługi za pomocą WsCreateServiceProxy.

Po osiągnięciu limitu czasu połączenie zostanie porzucone.

Zwracane wartości

Wszystkie wartości sukcesu HRESULT muszą być traktowane jako powodzenie, a wszystkie wartości niepowodzeń muszą być traktowane jako błędy. Poniżej przedstawiono niektóre wartości HRESULT, których aplikacja może oczekiwać:

• WS_S_ASYNC: wywołanie zostanie ukończone asynchronicznie.
• NOERROR: Połączenie zostało ukończone pomyślnie.
• WS_E_OPERATION_ABANDONED: Połączenie zostało porzucone. Obiekt błędu zawiera przyczynę porzucenia.
• WS_E_INVALID_OPERATION: serwer proxy usługi nie jest w odpowiednim stanie, aby wykonać wywołanie, sprawdź stan serwera proxy usługi, aby ustalić stan serwera proxy usługi.

Aby uzyskać pełną listę wartości zwracanych, zobacz Wartości zwracane usług sieci Web systemu Windows.

Przykłady kodu

Przykłady kodu można znaleźć w następujących tematach:

• CallAbandonExample
• WsAbandonCall