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

在远程设备上启动游戏。

## 语法

```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  
);  
```

### 参数

`_In_z_ remoteDevice`\
类型：**const char\***

远程设备的主机名或 IP 地址（例如 `"192.168.1.100"` 或 `"MyDevKit"`）。

`_In_z_ remotePath`\
类型：**const char\***

远程设备上游戏可执行文件的路径。可以是绝对路径（例如 `"D:\\Games\\MyGame\\game.exe"`），或相对于公共根解析的相对路径（例如 `"MyGame\\game.exe"`）。

`_In_opt_z_ args`\
类型：**const char\***

可选。要传递给游戏可执行文件的命令行参数（例如 `"-windowed -debug"`）。如果不需要参数，则传入 `nullptr`。

`_In_opt_ launchOptions`\
类型：**[WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions)\***

可选。指定启动模式和公共根别名。传入 `nullptr` 以使用默认设置（`Immediate` 启动、默认公共根）。

`_Out_opt_ processId`\
类型：**uint32\_t\***

可选。接收已启动游戏的进程 ID。如果不需要进程 ID，则传入 `nullptr`。

`_Out_opt_ threadId`\
类型：**uint32\_t\***

可选。接收已启动游戏主线程的线程 ID。如果不需要线程 ID，则传入 `nullptr`。

### 返回值

类型：**HRESULT**

如果成功，则返回 `S_OK`；否则，返回错误代码。

#### 错误代码

| 代码                      | 值          | 说明                | 根本原因                                              | 故障排除                                                             |
| ----------------------- | ---------- | ----------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| E\_GAMEFILEPATHNOTEXIST | 0x8C114010 | 游戏文件路径不存在。        | 提供的游戏可执行文件或包路径在远程计算机上无效或无法访问。                     | 验证该路径在远程设备上存在；确认复制操作已成功                                          |
| E\_CONNECTIONERROR      | 0x8C114014 | 连接错误。             | 建立网络连接时的通用故障（传输层故障），与 IP 地址有效性或远程计算机名称解析无关        | 检查远程计算机上的网络连接、防火墙规则和服务可用性；检查设备之间的可见性，两者应能够互相 ping 通；启用日志记录后重试连接。 |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | 无法解析远程计算机名称。      | 无法通过 DNS 或本地名称解析来解析主机名。                           | 验证主机名拼写、DNS 配置和网络连接。；使用 IP 地址以隔离名称解析问题。                          |
| E\_INVALIDADDRESS       | 0x8C114013 | 无效地址。             | 提供的网络地址不正确、格式错误或不受支持（例如 IP 格式错误、错误的 IP 或不受支持的协议）。 | 确认正确的 IP 地址；更正地址格式并确保使用 IPv4 协议                                  |
| E\_CLIENTNOTAUTHORIZED  | 0x8C114008 | 设备拒绝了客户端。         | 客户端不在该设备的受信任客户端列表中。在完成配对流程之前就尝试了连接                | 成功完成 PIN 码配对流程；重新执行连接请求                                          |
| E\_SERVERNOTAUTHORIZED  | 0x8C114009 | 客户端拒绝了设备。         | 目标设备不在该客户端的受信任端点列表中。在完成配对流程之前就尝试了连接               | 成功完成 PIN 码配对流程；重新执行连接请求                                          |
| E\_SERVERTOOOLD         | 0x8C114011 | 该服务器的版本对此客户端而言过旧。 | 客户端的 API 版本比远程设备上的端点版本更新                          | 将远程计算机上的 wdEndpoint 更新到兼容版本                                      |
| E\_ADMIN\_REQUIRED      | 0x8C114016 | 需要管理员权限。          | 端点未以提升的权限运行，而该操作需要管理员级别的权限                        | 以管理员身份重新运行该端点                                                    |

## 备注

同一时间在远程设备上只能有一个游戏进程运行。如果游戏已在运行，此函数将自动终止它并重新启动。可以在启动新游戏之前使用 [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame) 终止现有游戏。

当使用 [WdLaunchMode::Suspended](/reference/remoting/enums/wdlaunchmode) 启动时，游戏进程会以挂起状态启动。使用 [WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame) 恢复执行。这在游戏开始执行之前附加调试器时非常有用。

## 示例

### 示例 1：在远程设备上启动游戏

使用默认设置（立即执行、默认公共根）启动先前已复制的游戏可执行文件。

```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;
}
```

### 示例 2：以挂起模式启动以进行调试

以挂起状态启动游戏，以便在开始执行之前附加调试器。附加调试器后，用户按 Enter 恢复进程。

```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;
}
```

### 示例 3：复制并启动工作流

演示典型的迭代循环：将游戏文件复制到远程设备，然后启动可执行文件。这是 XBOX PC 远程迭代 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;
}
```

## 要求

| 要求          | 值                   |
| ----------- | ------------------- |
| **头文件**     | WdRemoteIteration.h |
| **库**       | wdremoteapi.lib     |
| **支持的操作系统** | Windows 11 及更高版本    |
| **支持的体系结构** | x64、ARM64           |

## 另请参阅

* [WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame)
* [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)
* [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions)
* [WdLaunchMode](/reference/remoting/enums/wdlaunchmode)
* [XBOX PC 远程迭代 API 错误代码](/reference/remoting/error-codes)
* [XBOX PC 远程迭代 API](/reference/remoting/remoteiteration_members)


## Related topics

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