Asynchrones Modell

Die meisten Vorgänge in der 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 eine nicht null WS_ASYNC_CONTEXT an die Funktion.

Wenn eine Funktion asynchron aufgerufen wird, kann eine Funktion trotzdem synchron oder asynchron ausgeführt werden. Wenn die Funktion synchron abgeschlossen wird, wird ein Wert zurückgegeben, der den endgültigen Erfolg oder Fehler angibt, und dieser Wert ist immer etwas anderes als WS_S_ASYNC (Siehe Windows Web Services Rückgabewerte). Ein Rückgabewert von WS_S_ASYNCgibt 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 Erfolgs- oder Fehlerwert an. Der Rückruf wird nicht aufgerufen, wenn der Vorgang synchron abgeschlossen wird.

Um einen asynchronen Kontext zu erstellen, initialisieren Sie die Rückruf- und callbackState- Felder 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 an eine WS_ASYNC_CONTEXT Struktur übergeben wird, die den Rückruf und einen Zeiger auf die Statusdaten 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 nur für die Dauer des Funktionsaufrufs (nicht für die Dauer des asynchronen Vorgangs) von der asynchronen Funktion verwendet, sodass Sie sie sicher im Stapel deklarieren können.

Wenn neben der WS_ASYNC_CONTEXT-Struktur andere Parameter als Zeiger an eine asynchrone Funktion übergeben werden und die Funktion asynchron abgeschlossen wird, liegt es in der Verantwortung des Aufrufers, die Werte beizubehalten, auf die diese Parameter verweisen (nicht freigegeben), bis der asynchrone Rückruf aufgerufen wird.

Es gibt Einschränkungen für Vorgänge, die ein Rückruf ausführen kann. Weitere Informationen zu möglichen Vorgängen finden Sie im WS_CALLBACK_MODEL.

Wenn Sie eine asynchrone Funktion implementieren, rufen Sie nicht den Rückruf im selben Thread auf, der die asynchrone Funktion aufgerufen hat, bevor die asynchrone Funktion an den Aufrufer zurückgegeben wurde, da dadurch das asynchrone Modell unterbrochen wird.

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

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

Das Starten eines asynchronen E/A-Vorgangs verbraucht Systemressourcen. 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 einschränken, die sie startet.

Das asynchrone Modell verwendet die folgenden API-Elemente.

Verwandte Themen

Beispiel für asynchrone Funktion

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute-