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

# Controle de versão da API do GameInput

> Controle de versão da API do GameInput

<a id="introductionSection" />

<Note>Se você estiver desenvolvendo para XBOX, a versão v.0 é a versão padrão disponível no GDK a partir do GDK 2510. Os títulos que utilizam as APIs v1.0+ podem fazer isso tanto para PC (v1.0+) quanto para console (v2.2+) integrando o pacote NuGet [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput). O GDK 2510 ou mais recente é necessário para usar esse pacote NuGet com console. Os aplicativos para PC exigem que o redistribuível mais recente do GameInput, incluído no pacote NuGet, esteja instalado no computador de destino. Os aplicativos para console devem ser compilados e vinculados com o cabeçalho e a biblioteca mais recentes do GameInput no pacote NuGet, mas não exigem o redistribuível, pois o runtime mais recente do GameInput está incluído na imagem do GDK no XBOX.</Note>

O GameInput é uma API viva que continua evoluindo ao longo do tempo à medida que novos recursos são adicionados e recursos desnecessários ou desatualizados são removidos. Você pode encontrar a versão mais recente do GameInput no [pacote NuGet](/pt-BR/build/core-features/common/input/overviews/input-nuget) oficial. Esse pacote também inclui o [Histórico de versões](https://www.nuget.org/packages/Microsoft.GameInput) mais recente e atualizado. O pacote sempre contém o cabeçalho, os binários e o redistribuível mais recentes do GameInput para incluir com seu título.

A atualização para uma versão mais recente do GameInput é rápida e simples. Além disso, independentemente da API descrita no cabeçalho mais recente do GameInput, a compatibilidade binária e funcional é mantida para aplicativos compilados com versões anteriores do GameInput. Nesse modelo, os jogos lançados podem aproveitar as melhorias no GameInput e podem ser migrados para a versão mais recente do GameInput, se necessário, para aproveitar novos recursos.

## Atualização do runtime e da versão da API

<a id="upgradingRuntimeAndApiVersionSection" />

Diferentes versões do GameInput têm nomes e métodos de aparência semelhante, mas são versionadas de forma distinta, com UUIDs diferentes. A partir da API GameInput v.1, cada versão é definida em um namespace exclusivo (por exemplo, `GameInput::v1`). Os mesmos objetos subjacentes do GameInput implementam essas interfaces. Você pode usar [QueryInterface](https://learn.microsoft.com/cpp/atl/queryinterface) para alternar entre versões, o que significa que você pode misturar o uso da API no seu jogo, se quiser.

Se você estiver atualizando do GameInput v.0, em que a API era definida no namespace global, talvez perceba que adicionar uma instrução `using namespace GameInput::v1` ajuda a reduzir o número de locais de chamada do GameInput que você precisa atualizar para adotar a v.1 e as revisões subsequentes da API.

Além das verificações de versão em runtime, você pode usar a compilação condicional verificando a definição de processador `GAMEINPUT_API_VERSION`. Essa definição corresponde à versão da API do GameInput atualmente em uso, bem como à versão principal do GameInput. A API v.0 não apresentava essa definição; portanto, se você quiser testar condicionalmente essa versão, poderá adicionar o seguinte trecho após a inclusão do cabeçalho do GameInput.

```cpp theme={null}
#ifndef GAMEINPUT_API_VERSION
#define GAMEINPUT_API_VERSION 0
#endif
```

## Atualização somente do runtime

<a id="upgradingRuntimeSection" />

O GameInput permite que você obtenha as correções de bugs mais recentes sem forçá-lo a atualizar o uso da API. Para obter essas correções de bugs, instale o redistribuível do GameInput incluído no pacote NuGet [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) mais recente. Como o GameInput permanece compatível em nível binário com versões mais antigas da API, você pode continuar usando seu cabeçalho existente com o novo runtime. Lembre-se de redistribuir os binários mais recentes do GameInput com seus títulos para garantir que a funcionalidade no seu ambiente de teste seja consistente com a de produção.

## Alterações do GameInput v.1

Se você estiver usando uma versão anterior do GameInput, observe que muitas funções não implementadas
e as enumerações e constantes correspondentes foram removidas da API a partir da v.1.
Além disso, a API foi colocada no namespace `GameInput::v1`
para facilitar o controle de versão. Devido a essas alterações, você poderá encontrar
erros de compilação ao compilar esse código usando esta versão (e versões
futuras). As alterações notáveis incluem:

1. `IGameInputDevice::GetDeviceInfo` anteriormente retornava a struct
   `IGameInputDeviceInfo` resultante como valor de retorno da função. Essa
   struct agora é retornada como um parâmetro de saída da função, e o
   valor de retorno da função agora é um `HRESULT`.

2. `IGameInput::UnregisterCallback` anteriormente recebia um valor de tempo limite como
   segundo parâmetro, mas esse parâmetro foi removido.

3. `IGameInputReading::GetSequenceNumber` foi removido. Use
   `IGameInputReading::GetTimestamp` no lugar.

## Dicas de controle de versão

* A mudança na superfície de API utilizável entre a v.0 e a v.1 é mínima, com a remoção de funcionalidades que nunca foram implementadas, além das alterações de assinatura de função descritas anteriormente.
* A API v.0 original do cabeçalho `GameInput.h` original ainda é suportada, mas essa API permanece estática. Nesse caso, você continuaria a usar o cabeçalho como está, do GDK, de um pacote NuGet mais antigo ou do SDK do Windows.
* Independentemente da versão da API que você usar, você deve instalar o redistribuível mais recente do [pacote NuGet](/pt-BR/build/core-features/common/input/overviews/input-nuget) durante o desenvolvimento e incluir esse redistribuível (ou um mais recente) como parte do processo de instalação do seu jogo para os usuários finais. É nesse redistribuível que está a implementação mais recente do runtime do GameInput, e ela aprimora todas as versões da API com itens como suporte expandido a controles, suporte a trackpad, suporte a área de trabalho remota e várias outras correções de bugs.

## Confira também

<a id="seeAlsoSection" />

[Pacote NuGet do GameInput](/pt-BR/build/core-features/common/input/overviews/input-nuget)


## Related topics

- [Notas de versão do PlayFab Party](/pt-BR/services/playfab/multiplayer/networking/release-notes.md)
- [XR-112 Estabelecimento de um usuário e um controle durante a ativação inicial e a retomada](/pt-BR/publishing/certification/xr/xr-112.md)
- [Guia de BVT de console da certificação](/pt-BR/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md)
- [Requisitos do XBOX para jogos do XBOX](/pt-BR/publishing/certification/xbox-requirements.md)
- [XR-115 Adição e remoção de usuários ou controles durante a jogabilidade](/pt-BR/publishing/certification/xr/xr-115.md)