> ## 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. # XBOX PC Remote Iteration API > Referência da XBOX PC Remote Iteration API: funções para copiar arquivos e para iniciar, retomar e encerrar jogos em dispositivos de desenvolvimento remotos baseados no Windows. # XBOX PC Remote Iteration API Fornece funções para copiar e excluir arquivos e para iniciar, retomar e encerrar jogos em dispositivos remotos baseados no Windows. ## Visão geral A XBOX PC Remote Iteration API habilita fluxos de trabalho de desenvolvimento baseados em PC voltados para dispositivos Windows remotos. Ela fornece um conjunto de funções C para transferir arquivos de jogo entre um PC local e um dispositivo remoto, além de iniciar e gerenciar processos de jogo no dispositivo remoto. A API foi projetada para ciclos de iteração rápidos durante o desenvolvimento de jogos, permitindo que os desenvolvedores criem builds localmente e implantem e testem em hardware remoto sem gerenciamento manual de arquivos. ## Disponibilidade da API Esta referência descreve a API mais recente. A menos que uma versão posterior seja especificada, as declarações públicas da API estão disponíveis no [RIT 0.0.8-Preview](/pt-BR/reference/remoting/release-versions#release-versions), a versão inicial da API pública. **Introduzida em** identifica quando uma declaração foi adicionada. **Suporte a partir de** identifica quando uma opção declarada passou a funcionar. A introdução de uma declaração não implica que retornos de chamada ou configurações atualmente não usados estejam implementados. As seções **Histórico de alterações** descrevem alterações nas declarações ou no comportamento da API, não correções na documentação. Os rótulos de versão usam a versão do WinGet. A [tabela de versões de lançamento](/pt-BR/reference/remoting/release-versions#release-versions) mapeia cada rótulo para o pacote NuGet da API e para as versões da ferramenta de linha de comando. ## Quando usar * Implantar builds de jogos de um PC local para um dispositivo Windows remoto durante o desenvolvimento. * Copiar arquivos atualizados (cópia delta) para um dispositivo remoto para minimizar os tempos de transferência durante builds iterativos. * Remover a saída de build obsoleta de um dispositivo remoto antes de implantar um novo build. * Iniciar, suspender, retomar e encerrar processos de jogo em um dispositivo remoto a partir do seu PC de desenvolvimento. * Automatizar fluxos de trabalho de build-implantação-teste em pipelines de integração contínua voltados para dispositivos Windows remotos. * Criar ou integrar ferramentas personalizadas do estúdio para implantação em dispositivos Windows remotos, localmente ou em laboratórios de teste. ## Quando NÃO usar * Não use esta API para implantação de varejo ou de produção de jogos em consoles de usuários finais. * Não use esta API para transferir arquivos entre dois dispositivos remotos; uma das extremidades deve ser o PC local. * Não use esta API se o dispositivo remoto não tiver sido emparelhado e configurado para desenvolvimento remoto. ## Pré-requisitos * **Pacote NuGet:** [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) versão 0.1.0-preview\.26.3.6001 ou posterior para a API base. APIs e opções posteriores exigem as versões identificadas em suas páginas de referência. * **Emparelhamento de dispositivos:** o PC local e o dispositivo remoto devem estar emparelhados e confiar mutuamente um no outro, usando o aplicativo [XBOX PC Toolbox](/pt-BR/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) para provisioná-los. * **wdEndpoint:** o `wdEndpoint` deve estar instalado e em execução no dispositivo remoto. A configuração do [XBOX PC Toolbox](/pt-BR/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) instala e configura o `wdEndpoint` por padrão. * **Cabeçalho e biblioteca:** inclua `WdRemoteIteration.h` e vincule a `wdremoteapi.lib`. ## Exemplo O [Remote Iteration Tools Sample](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Tools/RemoteIterationToolsSample) é um aplicativo WPF em C# que demonstra como implantar, iniciar, retomar e encerrar jogos em um dispositivo remoto e cancelar uma implantação em andamento. ## Funções | Função | Descrição | | - | - | | [WdRemoteCopy](/pt-BR/reference/remoting/functions/wdremotecopy) | Copia arquivos entre um PC local e um dispositivo remoto. | | [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) | Cancela uma operação de cópia em andamento. | | [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle) | Cria um identificador de cancelamento para cancelar uma operação de cópia ou exclusão. | | [WdCloseCancellationHandle](/pt-BR/reference/remoting/functions/wdclosecancellationhandle) | Fecha um identificador de cancelamento. | | [WdDuplicateCancellationHandle](/pt-BR/reference/remoting/functions/wdduplicatecancellationhandle) | Duplica um identificador de cancelamento existente. | | [WdLaunchRemoteGame](/pt-BR/reference/remoting/functions/wdlaunchremotegame) | Inicia um jogo em um dispositivo remoto. | | [WdResumeRemoteGame](/pt-BR/reference/remoting/functions/wdresumeremotegame) | Retoma o último jogo iniciado no modo suspenso em um dispositivo remoto. | | [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame) | Encerra o último jogo iniciado em um dispositivo remoto. | | [WdRegisterRemoteXboxGame](/pt-BR/reference/remoting/functions/wdregisterremotexboxgame) | Resolve e valida um caminho de pasta remota; não executa o registro do jogo na plataforma. | | [WdDeleteRemoteFiles](/pt-BR/reference/remoting/functions/wddeleteremotefiles) | Executa a exclusão de arquivos e diretórios em um dispositivo remoto, na base do melhor esforço. | | [WdCancelRemoteDelete](/pt-BR/reference/remoting/functions/wdcancelremotedelete) | Sinaliza o cancelamento da espera do cliente por uma operação de exclusão. | ## Estruturas | Estrutura | Descrição | | - | - | | [WdCopyFileProgressInfo](/pt-BR/reference/remoting/structs/wdcopyfileprogressinfo) | Contém informações de progresso de um arquivo individual durante uma operação de cópia. | | [WdCopyOperationSummary](/pt-BR/reference/remoting/structs/wdcopyoperationsummary) | Contém informações resumidas de progresso da operação de cópia como um todo. | | [WdCopyOptions](/pt-BR/reference/remoting/structs/wdcopyoptions) | Especifica a direção e o alias da raiz comum de uma operação de cópia. | | [WdCopyStatusCallbacks](/pt-BR/reference/remoting/structs/wdcopystatuscallbacks) | Contém ponteiros de função de retorno de chamada e configurações para receber atualizações de status da cópia. | | [WdCopySearchOptions](/pt-BR/reference/remoting/structs/wdcopysearchoptions) | Especifica padrões de filtro de arquivos e diretórios para uma operação de cópia. | | [WdCancellationHandle](/pt-BR/reference/remoting/structs/wdcancellationhandle) | Um identificador opaco usado para cancelar uma operação de cópia ou exclusão em andamento. | | [WdLaunchOptions](/pt-BR/reference/remoting/structs/wdlaunchoptions) | Especifica opções para iniciar um jogo em um dispositivo remoto. | | [WdDeleteFileProgressInfo](/pt-BR/reference/remoting/structs/wddeletefileprogressinfo) | Não usada no momento; nenhum dado de progresso de exclusão por item é produzido. | | [WdDeleteOperationSummary](/pt-BR/reference/remoting/structs/wddeleteoperationsummary) | Não usada no momento; nenhum resumo de progresso de exclusão é produzido. | | [WdDeleteOptions](/pt-BR/reference/remoting/structs/wddeleteoptions) | Especifica opções para uma operação de exclusão em um dispositivo remoto. | | [WdDeleteStatusCallbacks](/pt-BR/reference/remoting/structs/wddeletestatuscallbacks) | Contém ponteiros de função de retorno de chamada e configurações que são ignorados no momento. | | [WdDeleteSearchOptions](/pt-BR/reference/remoting/structs/wddeletesearchoptions) | Especifica padrões de filtro de arquivos e diretórios para uma operação de exclusão. | ## Enumerações | Enumeração | Descrição | | - | - | | [WdCopyDirection](/pt-BR/reference/remoting/enums/wdcopydirection) | Especifica a direção de uma operação de cópia. | | [WdLaunchMode](/pt-BR/reference/remoting/enums/wdlaunchmode) | Especifica o modo de inicialização de um jogo remoto. | | [WdCopyErrorSeverity](/pt-BR/reference/remoting/enums/wdcopyerrorseverity) | Especifica a gravidade de uma mensagem de erro ou aviso de cópia. | ## Retornos de chamada | Retorno de chamada | Descrição | | - | - | | [WdCopyFilesStatusCallback](/pt-BR/reference/remoting/callbacks/wdcopyfilesstatuscallback) | Chamado para relatar o progresso da cópia de arquivos durante uma operação de cópia. | | [WdCopyErrorCallback](/pt-BR/reference/remoting/callbacks/wdcopyerrorcallback) | Chamado para relatar mensagens de erro e aviso durante uma operação de cópia. | | [WdDeleteProgressCallback](/pt-BR/reference/remoting/callbacks/wddeleteprogresscallback) | Não usado no momento; nunca é invocado por `WdDeleteRemoteFiles`. | | [WdDeleteErrorCallback](/pt-BR/reference/remoting/callbacks/wddeleteerrorcallback) | Não usado no momento; nunca é invocado por `WdDeleteRemoteFiles`. | ## Modelo de threading A XBOX PC Remote Iteration API foi projetada para operações de cópia de thread único. As seguintes regras se aplicam: * **Uma cópia por vez.** Somente uma chamada de [WdRemoteCopy](/pt-BR/reference/remoting/functions/wdremotecopy) pode estar ativa a qualquer momento, independentemente do dispositivo de destino ou do caminho de destino. Chamar `WdRemoteCopy` enquanto outra cópia já estiver em andamento resulta em **comportamento indefinido**. * **Outras funções são seguras durante uma cópia.** Funções como [WdLaunchRemoteGame](/pt-BR/reference/remoting/functions/wdlaunchremotegame), [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame), [WdResumeRemoteGame](/pt-BR/reference/remoting/functions/wdresumeremotegame) e [WdRegisterRemoteXboxGame](/pt-BR/reference/remoting/functions/wdregisterremotexboxgame) podem ser chamadas a partir de threads separados enquanto uma cópia está em andamento. * **As operações remotas são de bloqueio.** Funções como `WdRemoteCopy` e `WdDeleteRemoteFiles` ficam bloqueadas aguardando o resultado da operação, um erro ou um cancelamento observado. `WdCancelRemoteCopy` e `WdCancelRemoteDelete` não são de bloqueio. * **O cancelamento é thread-safe.** [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) e [WdCancelRemoteDelete](/pt-BR/reference/remoting/functions/wdcancelremotedelete) podem ser chamadas a partir de outro thread para sinalizar o cancelamento. * **Nenhum estado de conexão entre operações remotas.** Cada chamada de operação remota estabelece sua própria conexão com o dispositivo remoto. Não há sessão persistente; por exemplo, se a conexão cair após a conclusão de [WdLaunchRemoteGame](/pt-BR/reference/remoting/functions/wdlaunchremotegame), você ainda poderá chamar [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame) assim que a conectividade for restaurada. ## Comportamento de repetição A XBOX PC Remote Iteration API **não** repete automaticamente operações com falha no nível da API. Se uma operação falhar devido a uma interrupção de rede ou outro erro transitório, o chamador será responsável por tentar novamente. * **Nenhuma repetição automática.** Se uma operação de cópia falhar (por exemplo, devido à perda de conectividade de rede), `WdRemoteCopy` retornará um erro. O chamador deverá invocar a função novamente para tentar outra vez. * **Nenhum tempo limite configurável.** `WdRemoteCopy` não impõe um tempo limite à operação de cópia. Ela continua transferindo até a conclusão, até ocorrer um erro ou até ser cancelada por meio de [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy). Em condições de rede degradadas, as transferências podem prosseguir muito lentamente em vez de falhar. * **O progresso é preservado em caso de falha.** Os arquivos copiados com êxito antes de uma falha permanecem no destino. Quando o chamador tenta a cópia novamente, o comportamento de cópia delta garante que somente arquivos incompletos ou ausentes sejam transferidos; os arquivos copiados anteriormente não são transferidos novamente. * **Erros de espaço em disco são relatados.** Se o dispositivo de destino ficar sem espaço em disco durante uma cópia, a operação falhará com um erro em vez de travar. * **Resiliência no nível de transporte.** A camada de transporte subjacente lida com a retransmissão de pacotes de baixo nível de forma transparente. Pequenas falhas de rede (como a perda de um único pacote) não fazem a operação falhar. No entanto, uma perda prolongada de conectividade acabará causando um erro. * **Padrão de repetição recomendado.** Após uma falha de `WdRemoteCopy`, basta chamar `WdRemoteCopy` novamente com os mesmos parâmetros. O comportamento de cópia delta minimiza o trabalho redundante transferindo apenas os arquivos ausentes ou incompletos no destino. ## Cancelamento A XBOX PC Remote Iteration API fornece um modelo de cancelamento baseado em identificador para operações de cópia e exclusão de longa duração. O mesmo tipo [WdCancellationHandle](/pt-BR/reference/remoting/structs/wdcancellationhandle) é usado para ambas. O chamador é responsável pelo ciclo de vida do identificador: 1. Crie um identificador chamando [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle). 2. Passe o identificador para [WdRemoteCopy](/pt-BR/reference/remoting/functions/wdremotecopy) por meio do parâmetro `cancellationHandle`. 3. A partir de um thread separado, chame [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) com o identificador para cancelar a cópia em andamento. `WdCancelRemoteCopy` não é de bloqueio. Depois que o cancelamento for sinalizado, `WdRemoteCopy` poderá retornar `S_OK` ou uma falha. 4. Depois que `WdRemoteCopy` retornar, feche o identificador chamando [WdCloseCancellationHandle](/pt-BR/reference/remoting/functions/wdclosecancellationhandle). Se vários componentes precisarem referenciar o mesmo identificador de cancelamento, use [WdDuplicateCancellationHandle](/pt-BR/reference/remoting/functions/wdduplicatecancellationhandle) para duplicá-lo. Cada cópia deve ser fechada de forma independente. [WdDeleteRemoteFiles](/pt-BR/reference/remoting/functions/wddeleteremotefiles) segue o mesmo modelo baseado em identificador, usando [WdCancelRemoteDelete](/pt-BR/reference/remoting/functions/wdcancelremotedelete) para sinalizar o cancelamento. O cancelamento observado interrompe a espera do cliente e retorna `S_OK` sem confirmar a conclusão no ponto de extremidade. A exclusão já iniciada no ponto de extremidade continua de forma independente; o cancelamento não restaura os itens excluídos. ## Raízes comuns Raízes comuns são locais conhecidos pré-configurados no dispositivo remoto para os quais os jogos normalmente são copiados ou a partir dos quais são iniciados. Em vez de especificar um caminho absoluto completo, os chamadores podem se referir a esses locais por alias usando o campo `commonRootAlias` em [WdCopyOptions](/pt-BR/reference/remoting/structs/wdcopyoptions) ou [WdLaunchOptions](/pt-BR/reference/remoting/structs/wdlaunchoptions). Para operações de cópia, o caminho remoto é `destinationPath` para `CopyTo` e `sourcePath` para `CopyFrom`. Se esse caminho for absoluto, o `commonRootAlias` será ignorado. Quando for relativo, ele será resolvido em relação à raiz comum identificada pelo alias. Se nenhum alias for especificado, o local padrão da raiz comum será usado. ## Códigos de erro Para obter uma lista completa dos códigos de erro específicos da API, incluindo descrições, causas raiz e orientações de solução de problemas, confira [Códigos de erro da XBOX PC Remote Iteration API](/pt-BR/reference/remoting/error-codes). ## Controle de versão, manutenção e distribuição Para obter os números de versão do NuGet da API, do WinGet e dos executáveis, confira [Versões de lançamento do XBOX PC Remote Iteration](/pt-BR/reference/remoting/release-versions). A API do Remote Iteration Tools (RIT) segue o **Versionamento Semântico 2.0.0** (`MAJOR.MINOR.PATCH`) para fornecer expectativas claras sobre compatibilidade, atualizações e suporte de longo prazo. Todas as bibliotecas públicas da API do RIT são distribuídas via **NuGet**, permitindo o gerenciamento de dependências e fluxos de trabalho de atualização padrão. ### Modelo de controle de versão As expectativas de compatibilidade abaixo se aplicam a versões que não são de visualização. Para pacotes de visualização, consulte o histórico de alterações específico da API para verificar alterações de declaração, layout e comportamento antes de atualizar. #### Versões PATCH As atualizações `PATCH` fornecem correções de bugs e melhorias de confiabilidade. Essas atualizações **não** alteram os contratos da API nem o comportamento em tempo de execução e são atualizações seguras de substituição direta. Atualizar para uma versão `PATCH` mais recente não requer alterações de código. #### Versões MINOR As atualizações `MINOR` introduzem novas APIs ou evoluem a funcionalidade existente de forma compatível com versões anteriores. Quando houver planos de alterar ou remover APIs no futuro, elas serão claramente marcadas como preteridas, dando aos desenvolvedores tempo para migrar. As atualizações de dependências são revisadas para garantir a compatibilidade dentro da mesma versão `MAJOR`. #### Versões MAJOR As atualizações `MAJOR` representam alterações interruptivas intencionais. Essas versões podem exigir alterações de código ou atualizações de dependências e são acompanhadas de orientações claras de migração. A atualização para uma nova versão `MAJOR` é tratada como uma decisão explícita e opcional, alinhada aos ciclos normais de validação e lançamento. ### Modelo de manutenção e suporte Depois que uma versão `MAJOR` ou `MINOR` da API do RIT é lançada publicamente, ela entra em um período de manutenção ativa com uma janela de suporte prevista de aproximadamente **18 meses**. Durante esse período: * Versões `PATCH` são aprovadas para corrigir bugs e melhorar a confiabilidade das versões com suporte. * À medida que novas versões são lançadas e patches e pequenas alterações melhoram as versões existentes e corrigem bugs, várias versões `MAJOR` e `MINOR` podem receber manutenção simultaneamente. * Versões `PATCH` **não** estendem o tempo de manutenção de uma versão `MAJOR` ou `MINOR`. * Novos recursos são introduzidos somente em versões `MINOR` ou `MAJOR` mais recentes e não são portados para versões anteriores. Após o término da janela de manutenção, a versão é desativada e espera-se que os desenvolvedores migrem para uma versão `MAJOR` ou `MINOR` mais recente com suporte. ### Expectativas de atualização Recomenda-se que os desenvolvedores se mantenham atualizados dentro de uma versão `MAJOR`, adotando as atualizações `PATCH` e `MINOR`. As atualizações de versão `MAJOR` devem ser planejadas e validadas explicitamente para garantir a compatibilidade com os fluxos de trabalho de produção. ### Compatibilidade de versões entre a API e o wdEndpoint A biblioteca de cliente da API do RIT e o `wdEndpoint` em execução no dispositivo remoto devem sempre ser mantidos em versões compatíveis. Usar uma versão mais recente da API com um `wdEndpoint` mais antigo pode resultar em erros `E_SERVERTOOOLD` ou em comportamento inesperado. Para garantir o comportamento correto, a compatibilidade total com versões anteriores e o suporte aos recursos mais recentes da API, é recomendável atualizar o `wdEndpoint` em todos os dispositivos remotos sempre que a biblioteca de cliente da API for atualizada. Consulte as notas de versão do pacote NuGet para conhecer os requisitos mínimos de versão do `wdEndpoint`. ## Requisitos | Requisito | Valor | | - | - | | **Cabeçalho** | WdRemoteIteration.h | | **Biblioteca** | wdremoteapi.lib | | **Pacote NuGet** | [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) | | **SO com suporte** | Windows 11 e posterior | | **Arquiteturas com suporte** | x64, ARM64 | ## Documentação conceitual * [Notas de versão - XBOX PC Remote Tools (março de 2026)](/pt-BR/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603) ## Confira também * [WdRemoteCopy](/pt-BR/reference/remoting/functions/wdremotecopy) * [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) * [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle) * [WdLaunchRemoteGame](/pt-BR/reference/remoting/functions/wdlaunchremotegame) * [WdRegisterRemoteXboxGame](/pt-BR/reference/remoting/functions/wdregisterremotexboxgame) ## Related topics - [XBOX PC Remote Iteration API](/reference/remoting/remoteiteration_members.md) - [API XBOX PC Remote Iteration](/es/reference/remoting/remoteiteration_members.md)