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

# WdLaunchRemoteGame

> WdLaunchRemoteGame

# WdLaunchRemoteGame

Inicia um jogo em um dispositivo remoto.

## Sintaxe

```cpp theme={null}
HRESULT WdLaunchRemoteGame(  
         _In_z_ const char* remoteDevice,  
         _In_z_ const char* remotePath,  
         _In_opt_z_ const char* args,  
         _In_opt_ const WdLaunchOptions* launchOptions,  
         _Out_opt_ uint32_t* processId,  
         _Out_opt_ uint32_t* threadId  
);  
```

### Parâmetros

`_In_z_ remoteDevice`\
Tipo: **const char\***

O nome do host ou o endereço IP do dispositivo remoto (por exemplo, `"192.168.1.100"` ou `"MyDevKit"`).

`_In_z_ remotePath`\
Tipo: **const char\***

O caminho para o executável do jogo no dispositivo remoto. Pode ser um caminho absoluto (por exemplo, `"D:\\Games\\MyGame\\game.exe"`) ou um caminho relativo resolvido em relação à raiz comum (por exemplo, `"MyGame\\game.exe"`).

`_In_opt_z_ args`\
Tipo: **const char\***

Opcional. Argumentos de linha de comando a serem passados para o executável do jogo (por exemplo, `"-windowed -debug"`). Passe `nullptr` se nenhum argumento for necessário.

`_In_opt_ launchOptions`\
Tipo: **[WdLaunchOptions](/pt-BR/reference/remoting/structs/wdlaunchoptions)\***

Opcional. Especifica o modo de inicialização e o alias da raiz comum. Passe `nullptr` para usar as configurações padrão (inicialização `Immediate`, raiz comum padrão).

`_Out_opt_ processId`\
Tipo: **uint32\_t\***

Opcional. Recebe a ID do processo do jogo iniciado. Passe `nullptr` se a ID do processo não for necessária.

`_Out_opt_ threadId`\
Tipo: **uint32\_t\***

Opcional. Recebe a ID do thread principal do jogo iniciado. Passe `nullptr` se a ID do thread não for necessária.

### Valor retornado

Tipo: **HRESULT**

Retorna `S_OK` se for bem-sucedido; caso contrário, retorna um código de erro.

#### Códigos de erro

| Código | Valor | Descrição | Causa raiz | Solução de problemas |
| - | - | - | - | - |
| E\_GAMEFILEPATHNOTEXIST | 0x8C114010 | O caminho do arquivo do jogo não existe. | O caminho do executável ou do pacote do jogo fornecido é inválido ou está inacessível na máquina remota. | Verifique se o caminho existe no dispositivo remoto; Confirme se a operação de cópia foi bem-sucedida |
| E\_CONNECTIONERROR | 0x8C114014 | Erro de conexão. | Falha genérica ao estabelecer a conexão de rede (falha no nível de transporte), não relacionada à validade do endereço IP nem à resolução do nome da máquina remota | Verifique a conectividade de rede, as regras de firewall e a disponibilidade do serviço na máquina remota; Verifique a visibilidade entre os dispositivos, que devem conseguir executar ping um no outro; Tente a conexão novamente com o registro em log habilitado. |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | Não foi possível resolver o nome da máquina remota. | O nome do host não pode ser resolvido via DNS ou resolução de nomes local. | Verifique a ortografia do nome do host, a configuração de DNS e a conectividade de rede.; Use o endereço IP para isolar problemas de resolução de nomes. |
| E\_INVALIDADDRESS | 0x8C114013 | Endereço inválido. | Foi fornecido um endereço de rede incorreto, malformado ou sem suporte (por exemplo, formato de IP inválido, IP errado ou protocolo sem suporte). | Confirme se o endereço IP está correto; Corrija o formato do endereço e verifique se ele usa o protocolo IPv4 |
| E\_CLIENTNOTAUTHORIZED | 0x8C114008 | O dispositivo rejeitou o cliente. | O cliente não está na lista de clientes confiáveis do dispositivo. A tentativa de conexão foi iniciada antes da conclusão do processo de emparelhamento | Conclua o processo de emparelhamento por PIN com êxito; Execute a solicitação de conexão novamente |
| E\_SERVERNOTAUTHORIZED | 0x8C114009 | O cliente rejeitou o dispositivo. | O dispositivo de destino não está na lista de pontos de extremidade confiáveis do cliente. A tentativa de conexão foi iniciada antes da conclusão do processo de emparelhamento | Conclua o processo de emparelhamento por PIN com êxito; Execute a solicitação de conexão novamente |
| E\_SERVERTOOOLD | 0x8C114011 | A versão do servidor é muito antiga para este cliente. | A versão da API no lado do cliente é mais recente que a versão do ponto de extremidade no dispositivo remoto | Atualize o wdEndpoint na máquina remota para uma versão compatível |
| E\_ADMIN\_REQUIRED | 0x8C114016 | Privilégios de administrador necessários. | O ponto de extremidade não está em execução com privilégios elevados e a operação exige permissões de nível de Administrador | Execute o ponto de extremidade novamente como Administrador |

## Comentários

Somente um processo de jogo pode estar em execução no dispositivo remoto por vez. Se um jogo já estiver em execução, essa função o encerrará automaticamente e o iniciará novamente. O jogo existente pode ser encerrado usando [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame) antes de iniciar um novo.

Quando iniciado com [WdLaunchMode::Suspended](/pt-BR/reference/remoting/enums/wdlaunchmode), o processo do jogo começa em estado suspenso. Use [WdResumeRemoteGame](/pt-BR/reference/remoting/functions/wdresumeremotegame) para retomar a execução. Isso é útil para anexar um depurador antes que o jogo comece a ser executado.

## Exemplos

### Exemplo 1: Iniciar um jogo em um dispositivo remoto

Inicia um executável de jogo copiado anteriormente usando as configurações padrão (execução imediata, raiz comum padrão).

```cpp theme={null}
// LaunchGame.cpp
// Launches a game executable on a remote device.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    // TODO: Replace with your remote device IP address or hostname
    const char* remoteDevice = "192.168.1.100";

    // TODO: Replace with the path to your game executable on the remote device.
    // Relative paths resolve against the default common root.
    const char* remotePath = "MyGame\\Binaries\\MyGame.exe";

    uint32_t processId = 0;
    uint32_t threadId  = 0;

    HRESULT hr = WdLaunchRemoteGame(
        remoteDevice,
        remotePath,
        nullptr,       // args — no command-line arguments
        nullptr,       // launchOptions — defaults to Immediate mode, default common root
        &processId,
        &threadId);

    if (SUCCEEDED(hr))
    {
        printf("Game launched — PID: %u, TID: %u\n", processId, threadId);
    }
    else
    {
        printf("Launch failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

### Exemplo 2: Iniciar no modo suspenso para depuração

Inicia o jogo em estado suspenso para que um depurador possa ser anexado antes do início da execução. Depois que o depurador estiver conectado, o usuário pressiona Enter para retomar o processo.

```cpp theme={null}
// LaunchSuspended.cpp
// Launches a game in suspended mode, waits for debugger attach, then resumes.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    const char* remoteDevice = "192.168.1.100";
    const char* remotePath   = "MyGame\\Binaries\\MyGame.exe";

    WdLaunchOptions launchOptions = {};
    launchOptions.launchMode     = WdLaunchMode::Suspended;
    launchOptions.commonRootAlias = nullptr;  // Use default common root

    uint32_t processId = 0;
    uint32_t threadId  = 0;

    HRESULT hr = WdLaunchRemoteGame(
        remoteDevice,
        remotePath,
        "-debug -log",    // Command-line arguments passed to the executable
        &launchOptions,
        &processId,
        &threadId);

    if (FAILED(hr))
    {
        printf("Launch failed: HRESULT 0x%08X\n", hr);
        return hr;
    }

    printf("Game suspended — PID: %u\n", processId);
    printf("Attach your debugger to the remote process, then press Enter to resume...\n");
    getchar();

    hr = WdResumeRemoteGame(remoteDevice);
    if (SUCCEEDED(hr))
    {
        printf("Game resumed.\n");
    }
    else
    {
        printf("Resume failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

### Exemplo 3: Fluxo de trabalho de cópia e inicialização

Demonstra o ciclo de iteração típico: copiar os arquivos do jogo para o dispositivo remoto e, em seguida, iniciar o executável. Esse é o fluxo de trabalho de ponta a ponta mais comum da XBOX PC Remote Iteration API.

```cpp theme={null}
// CopyAndLaunch.cpp
// Copies game files to a remote device, then launches the game.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    // TODO: Replace these values with your own
    const char* remoteDevice   = "192.168.1.100";
    const char* localBuildPath = "C:\\builds\\MyGame";
    const char* gameFolderName = "MyGame";
    const char* gameExePath    = "MyGame\\Binaries\\MyGame.exe";

    // Step 1: Copy game files to the remote device
    printf("Copying files...\n");
    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        localBuildPath,
        gameFolderName,
        nullptr, nullptr, nullptr, nullptr);

    if (FAILED(hr))
    {
        printf("Copy failed: HRESULT 0x%08X\n", hr);
        return hr;
    }

    // Step 2: Launch the game
    printf("Launching game...\n");
    hr = WdLaunchRemoteGame(
        remoteDevice,
        gameExePath,
        nullptr, nullptr, nullptr, nullptr);

    if (FAILED(hr))
    {
        printf("Launch failed: HRESULT 0x%08X\n", hr);
        return hr;
    }

    printf("Game files copied and launched successfully.\n");
    return 0;
}
```

## Requisitos

| Requisito | Valor |
| - | - |
| **Cabeçalho** | WdRemoteIteration.h |
| **Biblioteca** | wdremoteapi.lib |
| **SO com suporte** | Windows 11 e posterior |
| **Arquiteturas com suporte** | x64, ARM64 |

## Confira também

* [WdResumeRemoteGame](/pt-BR/reference/remoting/functions/wdresumeremotegame)
* [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame)
* [WdLaunchOptions](/pt-BR/reference/remoting/structs/wdlaunchoptions)
* [WdLaunchMode](/pt-BR/reference/remoting/enums/wdlaunchmode)
* [Códigos de erro da XBOX PC Remote Iteration API](/pt-BR/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/pt-BR/reference/remoting/remoteiteration_members)


## Related topics

- [WdLaunchMode](/pt-BR/reference/remoting/enums/wdlaunchmode.md)
- [WdLaunchOptions](/pt-BR/reference/remoting/structs/wdlaunchoptions.md)
- [WdResumeRemoteGame](/pt-BR/reference/remoting/functions/wdresumeremotegame.md)
- [WdTerminateRemoteGame](/pt-BR/reference/remoting/functions/wdterminateremotegame.md)
- [WdRegisterRemoteXboxGame](/pt-BR/reference/remoting/functions/wdregisterremotexboxgame.md)