Asynchroon model

De meeste bewerkingen in de Windows Web Services-API kunnen synchroon of asynchroon worden uitgevoerd. Als u een functie synchroon wilt aanroepen, geeft u een null-waarde door voor de WS_ASYNC_CONTEXT structuur. Als u wilt opgeven dat een functie asynchroon kan worden uitgevoerd, geeft u een niet-null-WS_ASYNC_CONTEXT door aan de functie.

Wanneer een functie asynchroon wordt aangeroepen, kan een functie niettemin synchroon of asynchroon worden voltooid. Als de functie synchroon wordt voltooid, retourneert deze een waarde die aangeeft dat de uiteindelijke geslaagde of fout is geslaagd en deze waarde altijd iets anders is dan WS_S_ASYNC (Zie Windows Web Services Retourwaarden). Een retourwaarde van WS_S_ASYNCgeeft echter aan dat de functie asynchroon wordt voltooid. Wanneer de functie asynchroon wordt voltooid, wordt een callback aangeroepen om de voltooiing van de bewerking aan te geven. Deze callback geeft de uiteindelijke succes- of foutwaarde aan. De callback wordt niet aangeroepen als de bewerking synchroon wordt voltooid.

Als u een asynchrone context wilt maken, initialiseert u de callback- en callbackState velden van de WS_ASYNC_CONTEXT-structuur. Het veld callbackState wordt gebruikt om een aanwijzer op te geven voor door de gebruiker gedefinieerde gegevens die worden doorgegeven aan de WS_ASYNC_CALLBACK-functie.

In het volgende voorbeeld ziet u hoe u een functie asynchroon aanroept door een aanwijzer door te geven aan een WS_ASYNC_CONTEXT structuur die de callback en een aanwijzer naar de statusgegevens bevat.

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.
}

De WS_ASYNC_CONTEXT structuur wordt alleen gebruikt door de asynchrone functie voor de duur van de functieaanroep (niet voor de duur van de asynchrone bewerking), zodat u deze veilig op de stack kunt declareren.

Als andere parameters, naast de WS_ASYNC_CONTEXT structuur, worden doorgegeven aan een asynchrone functie als aanwijzers en de functie asynchroon wordt voltooid, is het de verantwoordelijkheid van de aanroeper om de waarden die door deze parameters worden verwezen (niet vrij) te houden totdat de asynchrone callback wordt aangeroepen.

Er gelden beperkingen voor de bewerkingen die een callback kan uitvoeren. Zie de WS_CALLBACK_MODELvoor meer informatie over mogelijke bewerkingen.

Wanneer u een asynchrone functie implementeert, roept u de callback niet aan op dezelfde thread die de asynchrone functie heeft aangeroepen voordat de asynchrone functie naar de aanroeper is geretourneerd, omdat dit het asynchrone model verstoort.

Bij het implementeren van een functie die een reeks asynchrone bewerkingen moet uitvoeren, kunt u overwegen de WsAsyncExecute helperfunctie te gebruiken.

Het Asynchrone functievoorbeeld laat zien hoe u functies implementeert en gebruikt die het asynchrone model volgen.

Bij het starten van een asynchrone IO-bewerking worden systeembronnen verbruikt. Als er voldoende IO-bewerkingen worden gestart, kan het systeem niet meer reageren. Om dit te voorkomen, moet een toepassing het aantal asynchrone bewerkingen beperken dat wordt gestart.

Het asynchrone model maakt gebruik van de volgende API-elementen.

Verwante onderwerpen

asynchrone functievoorbeeld

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute-