XLaunchUri

Article
2025-04-28

The Microsoft Game Development Kit (GDK) Launcher API provides a mechanism that enables games to launch an experience by invoking a URI.

Syntax

HRESULT XLaunchUri(  
         XUserHandle requestingUser,  
         const char* uri  
)

Parameters

requestingUser _In_opt_
Type: XUserHandle

Defines a handle identifying the user that makes the request.

uri _In_z_
Type: char*

String that indicates the URI to launch.

Return value

Type: HRESULT

HRESULT success or error code.

Returns S_OK if successful; otherwise it returns an error code. For a list of error codes, see Error Codes.

Return Code	Description
S_OK	The operation succeeded.
E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER	The URI passed in to this function attempted to launch an app to the background, but no suitable app could be found. It may not be installed.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

This launches another app via URI. It also accepts an optional user context and a required URI.

If successful, the destination URI is launched. Otherwise, an error is returned. This method is not considered time critical, and blocks until the underlying async system operation is completed, and either the destination URI has been launched, or an error has occurred.

If no app exists to handle the given URI's protocol scheme, the system displays a prompt to the user asking if they would like to search the Windows Store for an application that handles that scheme.

Launching into the Background

On console, Universal Windows Apps that have the backgroundMediaPlayback capability in their appxmanifest file can be launched into the background instead of the foreground. To do this, prepend your URI with the string "ms-bgm-". For example, if your background media application responds to the protocol "companion-music-app://", then you could launch it into the background with the uri "ms-bgm-companion-music-app://". When the app receives the activation, the URI obtained from the ProtocolActivatedEventArgs will not include the "ms-bgm-" prefix.

When called in this way, XLaunchUri does not show the user a prompt when no suitable app is installed. Instead, if your game is using the April 2025 version of the GDK or later, it returns E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER. Your code can check for this return value and use it to display remediation UI to the user, as appropriate.

On PC, when XLaunchUri is called in this way it simply removes "ms-bgm-" from the beginning of the URI before launching it normally. It has no other effect on the system behavior on PC.

Here's an example of calling XLaunchUri to launch a companion music application:

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

Requirements

Header: XLauncher.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via