Partilhar via

Modelo assíncrono

  • Artigo

A maioria das operações na API de Serviços Web do Windows pode ser executada de forma síncrona ou assíncrona. Para chamar uma função de forma síncrona, passe um valor nulo para a estrutura WS_ASYNC_CONTEXT. Para especificar que uma função pode ser executada de forma assíncrona, passe um WS_ASYNC_CONTEXT não nulo para a função.

Quando chamada de forma assíncrona, uma função pode, no entanto, ser concluída de forma síncrona ou assíncrona. Se a função for concluída de forma síncrona, ela retornará um valor que indica o êxito ou erro final, e esse valor será sempre algo diferente de WS_S_ASYNC (Consulte Valores de retorno do Windows Web Services). Um valor de retorno de WS_S_ASYNC, no entanto, indica que a função será concluída de forma assíncrona. Quando a função é concluída de forma assíncrona, um retorno de chamada é invocado para sinalizar a conclusão da operação. Este retorno de chamada indica o valor final de sucesso ou erro. O retorno de chamada não será chamado se a operação for concluída de forma síncrona.

Para criar um contexto assíncrono, inicialize o de retorno de chamada e campos de callbackState da estrutura WS_ASYNC_CONTEXT. O campo callbackState é usado para especificar um ponteiro para dados definidos pelo usuário que são passados para a função WS_ASYNC_CALLBACK.

O exemplo a seguir mostra a chamada assíncrona de uma função passando um ponteiro para uma estrutura WS_ASYNC_CONTEXT que contém o retorno de chamada e um ponteiro para os dados de estado.

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

A estrutura WS_ASYNC_CONTEXT é usada pela função assíncrona apenas durante a chamada de função (não durante a operação assíncrona), para que você possa declará-la com segurança na pilha.

Se quaisquer outros parâmetros, além da estrutura WS_ASYNC_CONTEXT, forem passados para uma função assíncrona como ponteiros e a função for concluída de forma assíncrona, é responsabilidade do chamador manter os valores apontados por esses parâmetros vivos (não liberados) até que o retorno de chamada assíncrono seja invocado.

Há limitações sobre as operações que um retorno de chamada pode executar. Para obter mais informações sobre possíveis operações, consulte o WS_CALLBACK_MODEL.

Ao implementar uma função assíncrona, não invoque o retorno de chamada no mesmo thread que chamou a função assíncrona antes que a função assíncrona retorne ao chamador, pois isso interrompe o modelo assíncrono.

Ao implementar uma função que precisa executar uma série de operações assíncronas, considere usar o WsAsyncExecute função auxiliar.

O Exemplo de Função Assíncrona mostra como implementar e consumir funções que seguem o modelo assíncrono.

Iniciar uma operação de E/S assíncrona consome recursos do sistema. Se operações de E/S suficientes forem iniciadas, o sistema pode deixar de responder. Para evitar isso, um aplicativo precisa limitar o número de operações assíncronas iniciadas.

O modelo assíncrono usa os seguintes elementos de API.

Retorno de chamada Descrição
WS_ASYNC_CALLBACK O parâmetro da função de retorno de chamada usado com o modelo assíncrono.
WS_ASYNC_FUNCTION Usado com o WsAsyncExecute para especificar a próxima função a ser invocada em uma série de operações assíncronas.

 

Enumeração Descrição
WS_CALLBACK_MODEL Especifica o comportamento de threading de um retorno de chamada (por exemplo, um WS_ASYNC_CALLBACK).

 

Função Descrição
WsAsyncExecute Invoca um retorno de chamada definido pelo usuário que pode iniciar uma operação assíncrona e indicar uma função que deve ser chamada quando a operação assíncrona for concluída.

 

Estrutura Descrição
WS_ASYNC_CONTEXT Especifica o retorno de chamada assíncrono e um ponteiro para dados definidos pelo usuário, que serão passados para o retorno de chamada assíncrono.
WS_ASYNC_OPERATION Usado com o WsAsyncExecute para especificar a próxima função a ser invocada em uma série de operações assíncronas.
WS_ASYNC_STATE Usado por WsAsyncExecute para gerenciar o estado de uma operação assíncrona.

 

Exemplo de função assíncrona

WS_ASYNC_CALLBACK

WS_ASYNC_CONTEXT

WS_CALLBACK_MODEL

WsAsyncExecute