Skip to main content

XLaunchUri

Microsoft Game Development Kit (GDK) 启动器 API 提供了一种机制,使游戏能够通过调用 URI 来启动一项体验。

语法

参数

requestingUser   _In_opt_
类型:XUserHandle
定义标识发出请求的用户的句柄。 uri   _In_z_
类型:char*
指示要启动的 URI 的字符串。

返回值

类型:HRESULT HRESULT 成功或错误代码。 如果成功,则返回 S_OK;否则返回错误代码。有关错误代码列表,请参阅错误代码

备注

此函数在时间敏感线程上调用是不安全的。有关更多信息,请参阅时间敏感线程
此函数通过 URI 启动另一个应用。它还接受一个可选的用户上下文和一个必需的 URI。 如果成功,将启动目标 URI;否则返回错误。此方法不被视为时间关键,将会阻塞,直到底层异步系统操作完成,并且目标 URI 已启动或发生错误。 如果不存在可处理给定 URI 协议方案的应用,系统将向用户显示提示,询问他们是否要在 Windows 应用商店中搜索处理该方案的应用程序。

启动到后台

在主机上,appxmanifest 文件中具有 backgroundMediaPlayback 功能的通用 Windows 应用可以启动到后台而非前台。为此,请在 URI 前添加字符串 “ms-bgm-”。例如,如果你的后台媒体应用程序响应协议 “companion-music-app://”,那么你可以使用 URI “ms-bgm-companion-music-app://” 将其启动到后台。当应用收到激活时,从 ProtocolActivatedEventArgs 获取的 URI 将不包含 “ms-bgm-” 前缀。 以此方式调用时,若未安装合适的应用,XLaunchUri 不会向用户显示提示。相反,如果你的游戏使用 2025 年 4 月版或更高版本的 GDK,则会返回 E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER。你的代码可以检查此返回值,并根据需要将其用于向用户显示补救 UI。 在 PC 上,以此方式调用 XLaunchUri 时,只会在正常启动之前从 URI 开头删除 “ms-bgm-”。在 PC 上,这对系统行为没有其他影响。 以下是调用 XLaunchUri 启动配套音乐应用程序的示例:

要求

标头: XLauncher.h 库: xgameruntime.lib 支持的平台: Windows、XBOX One 系列主机和 XBOX Series 主机

概念文档

请参阅

XLauncher
最后修改于 2026年8月24日