Asynkron modell

De flesta åtgärder i Windows Web Services API kan utföras synkront eller asynkront. Om du vill anropa en funktion synkront skickar du ett null-värde för den WS_ASYNC_CONTEXT strukturen. Om du vill ange att en funktion kan utföras asynkront skickar du en icke-null-WS_ASYNC_CONTEXT till funktionen.

När den anropas asynkront kan en funktion ändå slutföras synkront eller asynkront. Om funktionen slutförs synkront returneras ett värde som anger det slutliga resultatet eller felet, och det här värdet är alltid något annat än WS_S_ASYNC (se Return Values för Windows Web Services). Ett returvärde för WS_S_ASYNCanger dock att funktionen kommer att slutföras asynkront. När funktionen slutförs asynkront anropas en återanrop för att signalera att åtgärden har slutförts. Det här återanropet anger det slutliga framgångs- eller felvärdet. Återanropet anropas inte om åtgärden slutförs synkront.

Om du vill skapa en asynkron kontext initierar du återanrop och callbackState fält i WS_ASYNC_CONTEXT-strukturen. Fältet callbackState används för att ange en pekare till användardefinierade data som skickas till funktionen WS_ASYNC_CALLBACK.

I följande exempel visas hur du anropar en funktion asynkront genom att skicka en pekare till en WS_ASYNC_CONTEXT struktur som innehåller motringningen och en pekare till tillståndsdata.

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

Den WS_ASYNC_CONTEXT strukturen används endast av den asynkrona funktionen under funktionsanropets varaktighet (inte under den asynkrona åtgärdens varaktighet), så du kan deklarera den på ett säkert sätt i stacken.

Om andra parametrar, förutom den WS_ASYNC_CONTEXT strukturen, skickas till en asynkron funktion som pekare och funktionen slutförs asynkront, är det anroparens ansvar att hålla värdena som pekas på av dessa parametrar levande (inte frigjorda) tills den asynkrona återanropet anropas.

Det finns begränsningar för vilka åtgärder som en återanrop kan utföra. Mer information om möjliga åtgärder finns i WS_CALLBACK_MODEL.

När du implementerar en asynkron funktion ska du inte anropa återanropet på samma tråd som anropade den asynkrona funktionen innan den asynkrona funktionen har återvänt till anroparen, eftersom detta stör den asynkrona modellen.

När du implementerar en funktion som behöver köra en serie asynkrona åtgärder bör du överväga att använda hjälpfunktionen WsAsyncExecute.

Asynkront funktionsexempel visar hur du implementerar och använder funktioner som följer den asynkrona modellen.

Om du startar en asynkron I/O-åtgärd används systemresurser. Om tillräckligt många I/O-åtgärder startas kan systemet inte svara. För att förhindra detta måste ett program begränsa antalet asynkrona åtgärder som startas.

Den asynkrona modellen använder följande API-element.

Relaterade ämnen

asynkront funktionsexempel

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute