> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Exemplo de configuração de provedor personalizado > 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](/pt-BR/reference/system/xasyncprovider/functions/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. ```c++ theme={null} 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(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](/pt-BR/reference/system/xasyncprovider/functions/xasyncprovider) 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](/pt-BR/reference/system/xasyncprovider/enums/xasyncop) 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](/pt-BR/reference/system/xasyncprovider/functions/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](/pt-BR/reference/system/xasyncprovider/functions/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](/pt-BR/reference/system/xasync/functions/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](/pt-BR/reference/system/xasyncprovider/functions/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](/pt-BR/reference/system/xasync/functions/xasyncgetstatus). | | `Cancel` | Disparado por uma chamada externa a [XAsyncCancel](/pt-BR/reference/system/xasync/functions/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)](/pt-BR/reference/system/xasyncprovider/xasyncprovider_members) * Funções * [XAsyncBegin](/pt-BR/reference/system/xasyncprovider/functions/xasyncbegin) * [xasyncprovider](/pt-BR/reference/system/xasyncprovider/functions/xasyncprovider) * [XAsyncSchedule](/pt-BR/reference/system/xasyncprovider/functions/xasyncschedule) * [XAsyncGetResult](/pt-BR/reference/system/xasyncprovider/functions/xasyncgetresult) * [XAsyncComplete](/pt-BR/reference/system/xasyncprovider/functions/xasynccomplete) * [xasync (conteúdo da API)](/pt-BR/reference/system/xasync/xasync_members) * Funções * [XAsyncRun](/pt-BR/reference/system/xasync/functions/xasyncrun) * [XAsyncGetStatus](/pt-BR/reference/system/xasync/functions/xasyncgetstatus) * [XAsyncCancel](/pt-BR/reference/system/xasync/functions/xasynccancel) ## Consulte também [Visão geral da biblioteca XAsyncProvider](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider) [Configurar métodos de invocação (exemplo)](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-invocation-methods) [Configurar dados de retorno (exemplo)](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-return-data) [Configurar cancelabilidade (exemplo)](/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-cancelability) [XAsyncProvider](/pt-BR/reference/system/xasyncprovider/xasyncprovider_members) ## Related topics - [Visão geral de Godot e engines da comunidade](/pt-BR/paths/community-engines/overview.md) - [Requisitos XBOX testados na certificação para jogos de console XBOX](/pt-BR/publishing/certification/console-cert-tested-requirements.md) - [Desenvolva um novo título GDK](/pt-BR/home/build-first-title/developing-new-titles.md) - [XR-015 Gerenciamento das comunicações do jogador](/pt-BR/publishing/certification/xr/xr-015.md) - [XR-045 Rede XBOX e privilégios de conta](/pt-BR/publishing/certification/xr/xr-045.md)