Asynchrones Modell

Die meisten Vorgänge in Windows Webdienst-API können synchron oder asynchron ausgeführt werden. Um eine Funktion synchron aufzurufen, übergeben Sie einen NULL-Wert für die WS _ ASYNC _ CONTEXT-Struktur. Um anzugeben, dass eine Funktion asynchron ausgeführt werden kann, übergeben Sie einen WS _ ASYNC _ CONTEXT ungleich NULL an die Funktion.

Wenn eine Funktion asynchron aufgerufen wird, kann sie trotzdem synchron oder asynchron abgeschlossen werden. Wenn die Funktion synchron abgeschlossen wird, gibt sie einen Wert zurück, der den endgültigen Erfolg oder Fehler angibt, und dieser Wert ist immer etwas anderes als WS _ S _ ASYNC (siehe Windows Webdienstrückgabewerte). Der Rückgabewert WS _ S _ ASYNC gibt jedoch an, dass die Funktion asynchron abgeschlossen wird. Wenn die Funktion asynchron abgeschlossen wird, wird ein Rückruf aufgerufen, um den Abschluss des Vorgangs zu signalisieren. Dieser Rückruf gibt den endgültigen Erfolg oder Fehlerwert an. Der Rückruf wird nicht aufgerufen, wenn der Vorgang synchron abgeschlossen wird.

Initialisieren Sie zum Erstellen eines asynchronen Kontexts die Felder callback und callbackState der WS _ ASYNC _ CONTEXT-Struktur. Das CallbackState-Feld wird verwendet, um einen Zeiger auf benutzerdefinierte Daten anzugeben, die an die WS _ ASYNC _ CALLBACK-Funktion übergeben werden.

Das folgende Beispiel zeigt, wie eine Funktion asynchron aufgerufen wird, indem ein Zeiger auf eine WS _ ASYNC _ CONTEXT-Struktur übergeben wird, die den Rückruf und einen Zeiger auf die Zustandsdaten enthält.

HRESULT ExampleAsyncFunction(WS_ASYNC_CONTEXT* asyncContext);
void ExampleAsyncFunction()
{
    // Set up the WS_ASYNC_CONTEXT structure.
    MyState* myState = ...;  \\ Declare a pointer to user-defined data.
    WS_ASYNC_CONTEXT asyncContext;
    asyncContext.callback = MyCallback;  \\ Set the callback.
    asyncContext.callbackState = myState; \\ Set the pointer to the user-defined data.

    // Start the asynchronous operation
    HRESULT hr = SomeFunction(&asyncContext);

    if (hr == WS_S_ASYNC)
    {
        // The operation is completing asynchronously.  The callback is called 
        // when the operation is complete.
    }
    else
    {
        // The operation completed synchronously.  The callback is not called.
    }
}
void CALLBACK MyCallback(HRESULT hr, WS_CALLBACK_MODEL callbackModel, void* callbackState)
{
    MyState* myState = (MyState*)callbackState;

    // The operation completed asynchronously.
}

Die WS _ ASYNC _ CONTEXT-Struktur wird von der asynchronen Funktion nur für die Dauer des Funktionsaufrufs (nicht für die Dauer des asynchronen Vorgangs) verwendet, sodass Sie sie sicher im Stapel deklarieren können.

Wenn andere Parameter außer der _ WS-ASYNC _ CONTEXT-Struktur als Zeiger an eine asynchrone Funktion übergeben werden und die Funktion asynchron abgeschlossen wird, liegt es in der Verantwortung des Aufrufers, die Werte, auf die von diesen Parametern verwiesen wird, aktiv zu halten (nicht freigegeben), bis der asynchrone Rückruf aufgerufen wird.

Es gibt Einschränkungen hinsichtlich der Vorgänge, die ein Rückruf ausführen kann. Weitere Informationen zu möglichen Vorgängen finden Sie unter WS _ CALLBACK _ MODEL.

Wenn Sie eine asynchrone Funktion implementieren, rufen Sie den Rückruf nicht für denselben Thread auf, der die asynchrone Funktion aufgerufen hat, bevor die asynchrone Funktion an den Aufrufer zurückgegeben wurde, da dies das asynchrone Modell unterbricht.

Wenn Sie eine Funktion implementieren, die eine Reihe asynchroner Vorgänge ausführen muss, sollten Sie die Hilfsfunktion WsAsyncExecute verwenden.

Das Beispiel für asynchrone Funktionen zeigt, wie Funktionen implementiert und verwendet werden, die dem asynchronen Modell folgen.

Beim Starten eines asynchronen E/A-Vorgangs werden Systemressourcen verbraucht. Wenn genügend E/A-Vorgänge gestartet werden, kann das System nicht mehr reagieren. Um dies zu verhindern, muss eine Anwendung die Anzahl der asynchronen Vorgänge begrenzen, die sie startet.

Das asynchrone Modell verwendet die folgenden API-Elemente.

Rückruf BESCHREIBUNG
_WS-ASYNCHRONER _ RÜCKRUF Der Rückruffunktionsparameter, der mit dem asynchronen Modell verwendet wird.
_WS-ASYNCHRONE _ FUNKTION Wird mit WsAsyncExecute verwendet, um die nächste Funktion anzugeben, die in einer Reihe asynchroner Vorgänge aufgerufen werden soll.
Enumeration Beschreibung
_WS-RÜCKRUFMODELL _ Gibt das Threadingverhalten eines Rückrufs an (z. B. ein WS _ ASYNC _ CALLBACK).
Funktion BESCHREIBUNG
WsAsyncExecute Ruft einen benutzerdefinierten Rückruf auf, der einen asynchronen Vorgang initiieren und eine Funktion angeben kann, die aufgerufen werden soll, wenn der asynchrone Vorgang abgeschlossen wurde.
Struktur BESCHREIBUNG
_WS-ASYNCHRONER _ KONTEXT Gibt den asynchronen Rückruf und einen Zeiger auf benutzerdefinierte Daten an, die an den asynchronen Rückruf übergeben werden.
_WS-ASYNCHRONER _ VORGANG Wird mit WsAsyncExecute verwendet, um die nächste Funktion anzugeben, die in einer Reihe asynchroner Vorgänge aufgerufen werden soll.
WS _ ASYNC _ STATE Wird von WsAsyncExecute zum Verwalten des Zustands eines asynchronen Vorgangs verwendet.

Beispiel für asynchrone Funktion

_WS-ASYNCHRONER _ RÜCKRUF

_WS-ASYNCHRONER _ KONTEXT

_WS-RÜCKRUFMODELL _

WsAsyncExecute