Exemplo de configuração de provedor personalizado

Este tópico fornece um exemplo de como configurar um provedor assíncrono personalizado. Ao escrever um provedor assíncrono personalizado, os métodos assíncronos são iniciados por uma chamada a XAsyncBegin. Essa função tem um parâmetro de retorno de chamada que implementa, por exemplo, o tratamento de alterações de estado, o enfileiramento de retornos de chamada e o disparo da conclusão.

struct Context
{
    uint64_t result;
};

Context* context = new Context{ 0 };
// Assume that the async block is already filled out with the completion callback and task queue.
HRESULT hr = XAsyncBegin(async, context, ProviderFuncIdentity, __FUNCTION__,
    [](XAsyncOp op, const XAsyncProviderData* providerData)
    {
        Context* context =
        reinterpret_cast<Context*>(providerData->context);
        switch (op)
        {
            case XAsyncOp::Begin:
                return XAsyncSchedule(providerData->async, 0);

            case XAsyncOp::Cleanup:
                delete context;
                break;

            case XAsyncOp::GetResult:
                memcpy(providerData->buffer, &context->result, sizeof(uint64_t));
                break;

            case XAsyncOp::DoWork:
                context->result = 12345678;
                XAsyncComplete(providerData->async, S_OK, sizeof(uint64_t));
                break;

            case XAsyncOp::Cancel:
                // This call can't be canceled.
                break;
        }

    return S_OK;
});

Há muito a ser explicado aqui, mas a ideia básica é simples: chame XAsyncBegin e forneça a ele um retorno de chamada de provedor para tratar as diferentes alterações de estado. Lembre-se de que o bloco assíncrono contém a fila de tarefas a ser usada e uma implementação opcional de um retorno de chamada de conclusão. O retorno de chamada deve então tratar os cinco casos diferentes do tempo de execução da tarefa assíncrona, conforme mostrado na tabela a seguir.

Caso do provedor	Responsabilidade
`Begin`	Chamado imediatamente pela chamada a `XAsyncBegin`. Esse caso é responsável por agendar o retorno de chamada de trabalho assíncrono na fila de tarefas. Isso é feito por uma chamada a XAsyncSchedule. Ela enfileira esse retorno de chamada para ser executado novamente com o caso `DoWork` por meio da porta de trabalho da fila de tarefas.
`Cleanup`	Chamado quando a tarefa assíncrona está sendo concluída e quaisquer dados internos criados para acompanhamento podem ser excluídos. No código de exemplo anterior, esse caso limpa a estrutura `Context`, que foi alocada para acompanhar os dados de resultado.
`GetResult`	Chamado quando o usuário chama XAsyncGetResult. O caso deve então gravar no buffer de saída passado a ele. Portanto, o resultado assíncrono original deve ter sido salvo em algum lugar. O código de exemplo anterior o salva na estrutura `Context`. As funções de API assíncronas do Microsoft Game Development Kit (GDK) que retornam dados de uma tarefa assíncrona chamam `XAsyncGetResult` internamente e convertem esses dados para a forma adequada ao chamador. Recomendamos essa abordagem para trabalhar com resultados.
`DoWork`	Chamado por meio da fila de tarefas que tem sua porta de trabalho despachada. Isso significa que o quadro de pilha desse retorno de chamada está sendo executado no thread pretendido, de acordo com a forma como a fila de tarefas foi configurada. Todo o trabalho deve ser realizado aqui. Na implementação interna do provedor assíncrono de XAsyncRun, é aqui que o retorno de chamada de trabalho passado é executado. Para provedores personalizados, o trabalho pode ser feito diretamente no retorno de chamada ou com algum método personalizado que encapsule a funcionalidade. Quando o trabalho for concluído, XAsyncComplete deverá ser chamada. Essa função executa duas tarefas. Primeiro, ela especifica se algum dado de saída é necessário, fornecendo um tamanho de dados. Se um valor maior que zero for fornecido, um buffer interno será alocado para que o caso `GetResult` grave nele. Segundo, ela enfileira uma chamada ao retorno de chamada de conclusão para ser executada na porta de conclusão da fila de tarefas. O código de status de conclusão passado a `XAsyncComplete` torna-se o código retornado por uma chamada a XAsyncGetStatus.
`Cancel`	Disparado por uma chamada externa a XAsyncCancel. Se esse caso não for implementado, nada acontecerá. Para permitir o cancelamento, o provedor deve ser capaz de sinalizar a qualquer trabalho em execução que ele pare. O caso `DoWork` deve então chamar `XAsyncComplete` com o status `E_ABORT`.

Documentação de referência da API

XAsyncProvider (conteúdo da API)
- Funções
xasync (conteúdo da API)
- Funções

Consulte também

Visão geral da biblioteca XAsyncProvider Configurar métodos de invocação (exemplo) Configurar dados de retorno (exemplo) Configurar cancelabilidade (exemplo) XAsyncProvider

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Build and Develop

Documentação de referência da API

Consulte também

​Documentação de referência da API

​Consulte também

Documentação de referência da API

Consulte também