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

# XLaunchUri

> XLaunchUri

# XLaunchUri

Microsoft Game Development Kit (GDK) 啟動器 API 提供一種機制，讓遊戲能夠透過叫用 URI 來啟動體驗。

## 語法

```cpp theme={null}
HRESULT XLaunchUri(  
         XUserHandle requestingUser,  
         const char* uri  
)  
```

### 參數

*requestingUser*   \_In\_opt\_\
類型：XUserHandle

定義識別發出要求之使用者的控制代碼。

*uri*   \_In\_z\_\
類型：char\*

指出要啟動之 URI 的字串。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。

如果成功，則傳回 S\_OK；否則傳回錯誤碼。如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

| 傳回碼 | 描述 |
| - | - |
| S\_OK | 作業成功。 |
| E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER | 傳入此函式的 URI 嘗試在背景啟動應用程式，但找不到適合的應用程式。該應用程式可能尚未安裝。 |

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

這會透過 URI 啟動另一個應用程式。它也接受選擇性的使用者內容和必要的 URI。

如果成功，就會啟動目的地 URI。否則會傳回錯誤。此方法不被視為時間關鍵，並且會封鎖直到基礎非同步系統作業完成，也就是目的地 URI 已啟動或發生錯誤為止。

如果沒有應用程式可以處理指定 URI 的通訊協定配置，系統會顯示提示，詢問使用者是否要在 Windows 市集中搜尋處理該配置的應用程式。

### 在背景中啟動

在主機上，於其 appxmanifest 檔案中具有 [backgroundMediaPlayback](https://learn.microsoft.com/windows/uwp/audio-video-camera/background-audio) 功能的通用 Windows 應用程式，可以在背景而非前景中啟動。若要這麼做，請在您的 URI 前面加上字串 "ms-bgm-"。例如，如果您的背景媒體應用程式回應通訊協定 "companion-music-app\://"，則可以使用 URI "ms-bgm-companion-music-app\://" 在背景中啟動它。當應用程式收到啟用時，從 [ProtocolActivatedEventArgs](https://learn.microsoft.com/uwp/api/windows.applicationmodel.activation.protocolactivatedeventargs) 取得的 URI 不會包含 "ms-bgm-" 前置詞。

以這種方式呼叫時，若未安裝適合的應用程式，XLaunchUri 不會向使用者顯示提示。相反地，如果您的遊戲使用 2025 年 4 月版或更新版本的 GDK，它會傳回 E\_GAMEPACKAGE\_NO\_PACKAGE\_IDENTIFIER。您的程式碼可以檢查此傳回值，並視情況使用它向使用者顯示補救 UI。

在 PC 上，以這種方式呼叫 XLaunchUri 時，它只會先從 URI 開頭移除 "ms-bgm-"，然後再以一般方式啟動。這對 PC 上的系統行為沒有其他影響。

以下是呼叫 XLaunchUri 來啟動隨附音樂應用程式的範例：

```cpp theme={null}
HRESULT BeginPlayingMusic(XUserHandle user)
{
    // Launch a well-known companion music application.
    // The game and app both need to agree on the URI scheme.
    HRESULT hr = XLaunchUri(user, "ms-bgm-companion-music-app://launch?play=true");
    if (hr == E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER)
    {
        // If the music app isn't installed, launch the store page so the user can download it.
        return XLaunchUri(user, "ms-windows-store://pdp/?ProductId=9FAKESTOREID");
    }

    return hr;
}
```

## 需求

**標頭：** XLauncher.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XLauncher](/zh-TW/reference/system/xlauncher/xlauncher_members)


## Related topics

- [XLaunchUri](/reference/system/xlauncher/functions/xlaunchuri.md)
- [XLaunchNewGame](/reference/system/xgame/functions/xlaunchnewgame.md)