Asynchronní model

Většinu operací v rozhraní API webových služeb systému Windows je možné provádět synchronně nebo asynchronně. Pokud chcete volat funkci synchronně, předejte hodnotu null pro WS_ASYNC_CONTEXT strukturu. Pokud chcete určit, že se funkce může provádět asynchronně, předejte funkci WS_ASYNC_CONTEXT, která není null.

Když se volá asynchronně, funkce se přesto může dokončit synchronně nebo asynchronně. Pokud se funkce dokončí synchronně, vrátí hodnotu, která označuje konečný úspěch nebo chybu a tato hodnota je vždy jiná než WS_S_ASYNC (viz návratové hodnoty webových služeb systému Windows). Návratová hodnota WS_S_ASYNCvšak označuje, že funkce se dokončí asynchronně. Po dokončení funkce asynchronně se vyvolá zpětné volání, které signalizují dokončení operace. Toto zpětné volání označuje konečnou úspěšnou nebo chybovou hodnotu. Zpětné volání se nevolá, pokud se operace dokončí synchronně.

Chcete-li vytvořit asynchronní kontext, inicializovat zpětné volání a callbackState pole struktury WS_ASYNC_CONTEXT. Pole callbackState slouží k určení ukazatele na uživatelsky definovaná data, která se předávají funkci WS_ASYNC_CALLBACK.

Následující příklad ukazuje asynchronní volání funkce předáním ukazatele do WS_ASYNC_CONTEXT struktury, která obsahuje zpětné volání a ukazatel na stavová data.

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

Struktura WS_ASYNC_CONTEXT je používána asynchronní funkcí pouze po dobu trvání volání funkce (ne po dobu trvání asynchronní operace), takže ji můžete bezpečně deklarovat v zásobníku.

Pokud jsou některé další parametry kromě struktury WS_ASYNC_CONTEXT předány asynchronní funkci jako ukazatele a funkce se dokončí asynchronně, je zodpovědností volajícího zachovat hodnoty, na které tyto parametry odkazují (nejsou uvolněny), dokud se nevyvolá asynchronní zpětné volání.

Existují omezení operací, které může zpětné volání provádět. Další informace o možnýchoperacích WS_CALLBACK_MODELch

Při implementaci asynchronní funkce nevyvolejte zpětné volání ve stejném vlákně, které volala asynchronní funkce před tím, než se asynchronní funkce vrátila volajícímu, protože to naruší asynchronní model.

Při implementaci funkce, která potřebuje provést řadu asynchronních operací, zvažte použití WsAsyncExecute pomocné funkce.

Příklad asynchronní funkce ukazuje, jak implementovat a využívat funkce, které následují podle asynchronního modelu.

Spuštění asynchronní vstupně-výstupní operace spotřebovává systémové prostředky. Pokud je spuštěno dostatek vstupně-výstupních operací, systém přestane reagovat. Aby tomu zabránila, musí aplikace omezit počet asynchronních operací, které spouští.

Asynchronní model používá následující prvky rozhraní API.

Související témata

Příklad asynchronní funkce

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

wsAsyncExecute