> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exemplo de configuração de provedor personalizado

> Escreva um provedor assíncrono personalizado com XAsyncBegin e um retorno de chamada de provedor que trate os casos Begin, Cleanup, GetResult, DoWork e Cancel de uma tarefa.

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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncbegin.md). 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<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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncprovider.md)
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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/enums/xasyncop.md) 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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncschedule.md). 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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncgetresult.md). 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](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasyncrun.md), é 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](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasynccomplete.md) 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](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasyncgetstatus.md). |
| `Cancel` | Disparado por uma chamada externa a [XAsyncCancel](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasynccancel.md). 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)](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/xasyncprovider_members.md)
  * Funções
    * [XAsyncBegin](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncbegin.md)
    * [xasyncprovider](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncprovider.md)
    * [XAsyncSchedule](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncschedule.md)
    * [XAsyncGetResult](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasyncgetresult.md)
    * [XAsyncComplete](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/functions/xasynccomplete.md)
* [xasync (conteúdo da API)](https://docs.xbox.com/pt-BR/reference/system/xasync/xasync_members.md)
  * Funções
    * [XAsyncRun](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasyncrun.md)
    * [XAsyncGetStatus](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasyncgetstatus.md)
    * [XAsyncCancel](https://docs.xbox.com/pt-BR/reference/system/xasync/functions/xasynccancel.md)

## Consulte também

[Visão geral da biblioteca XAsyncProvider](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider.md)

[Configurar métodos de invocação (exemplo)](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-invocation-methods.md)

[Configurar dados de retorno (exemplo)](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-return-data.md)

[Configurar cancelabilidade (exemplo)](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-cancelability.md)

[XAsyncProvider](https://docs.xbox.com/pt-BR/reference/system/xasyncprovider/xasyncprovider_members.md)


## Related topics

- [Bibliotecas XAsync para programação de tarefas assíncronas](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/index.md)
- [Exemplo de configuração de métodos de invocação](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-invocation-methods.md)
- [Exemplo de configuração de dados de retorno](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-return-data.md)
- [Exemplo de configuração de cancelabilidade](https://docs.xbox.com/pt-BR/build/core-features/common/async/async-libraries/async-library-xasyncprovider-example-setup-cancelability.md)
- [Configuração de serviços personalizados](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/custom-service-config/index.md)