> ## 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；否则返回错误代码。有关错误代码列表，请参阅[错误代码](/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](/reference/system/xlauncher/xlauncher_members)


## Related topics

- [XLaunchNewGame](/zh-CN/reference/system/xgame/functions/xlaunchnewgame.md)
- [XLauncher](/zh-CN/reference/system/xlauncher/xlauncher_members.md)
- [XR-109 应用之间的链接](/zh-CN/publishing/certification/xr/xr-109.md)
- [GameClipUriType 枚举](/zh-CN/reference/live/rest/enums/gvr-enum-gameclipuritype.md)
- [WdLaunchOptions](/zh-CN/reference/remoting/structs/wdlaunchoptions.md)