> ## 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](/zh-TW/reference/remoting/structs/wdlaunchoptions)\***

選用。指定啟動模式與通用根目錄別名。傳遞 `nullptr` 以使用預設設定 (`Immediate` 啟動、預設通用根目錄)。

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

選用。接收所啟動遊戲的處理程序識別碼。如果不需要處理程序識別碼，請傳遞 `nullptr`。

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

選用。接收所啟動遊戲主執行緒的執行緒識別碼。如果不需要執行緒識別碼，請傳遞 `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](/zh-TW/reference/remoting/functions/wdterminateremotegame) 終止現有的遊戲。

以 [WdLaunchMode::Suspended](/zh-TW/reference/remoting/enums/wdlaunchmode) 啟動時，遊戲處理程序會以暫停狀態啟動。請使用 [WdResumeRemoteGame](/zh-TW/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 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;
}
```

## 需求

| 需求 | 值 |
| - | - |
| **標頭** | WdRemoteIteration.h |
| **程式庫** | wdremoteapi.lib |
| **支援的作業系統** | Windows 11 及更新版本 |
| **支援的架構** | x64, ARM64 |

## 另請參閱

* [WdResumeRemoteGame](/zh-TW/reference/remoting/functions/wdresumeremotegame)
* [WdTerminateRemoteGame](/zh-TW/reference/remoting/functions/wdterminateremotegame)
* [WdLaunchOptions](/zh-TW/reference/remoting/structs/wdlaunchoptions)
* [WdLaunchMode](/zh-TW/reference/remoting/enums/wdlaunchmode)
* [XBOX PC Remote Iteration API 錯誤碼](/zh-TW/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/zh-TW/reference/remoting/remoteiteration_members)


## Related topics

- [WdLaunchRemoteGame](/ko/reference/remoting/functions/wdlaunchremotegame.md)
- [WdLaunchMode](/ko/reference/remoting/enums/wdlaunchmode.md)