XLaunchUri

Microsoft GameCore Launcher API では、ゲームが URI を呼び出すことでエクスペリエンスを起動できるメカニズムが提供されます。

構文

HRESULT XLaunchUri(  
         XUserHandle requestingUser,  
         const char* uri  
)  

パラメーター

requestingUser _In_opt_
型: XUserHandle

要求を行うユーザーを示すハンドルを定義します。

uri _In_z_
型: char*

起動する URI を示す文字列。

戻り値

型: HRESULT

HRESULT 成功またはエラー コード。

正常に実行された場合は S_OK を返し、失敗した場合はエラー コードを返します。 エラー コードの一覧については、「エラー コード」を参照してください。

リターン コード	説明
S_OK	操作に成功しました。
E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER	この関数に渡された URI は、アプリをバックグラウンドで起動しようとしましたが、適切なアプリが見つかりませんでした。 インストールされていない可能性があります。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。 詳細については、「時間依存のスレッド」を参照してください。

これにより、URI を介して別のアプリが起動します。 また、オプションのユーザー コンテキストと必要な URI も受け取ります。

成功した場合は、対象の URI が起動されます。 それ以外の場合は、エラーが返されます。 このメソッドは、タイム クリティカルとは見なされず、基になる非同期システムの操作が完了し、対象の URI が起動されるか、またはエラーが発生するまで、ブロックされます。

指定された URI のプロトコル スキームを処理するアプリが存在しない場合、システムは、そのスキームを処理するアプリケーションを Microsoft Store で検索するかどうかをたずねるプロンプトを、ユーザーに表示します。

バックグラウンドでの起動

コンソールでは、appxmanifest ファイルに backgroundMediaPlayback 機能を持つユニバーサル Windows App アプリを、フォアグラウンドではなくバックグラウンドで起動できます。 これを行うには、URI の先頭に文字列 "ms-bgm-" を追加します。 たとえば、バックグラウンド メディア アプリケーションがプロトコル "companion-music-app://" に応答する場合は、URI "ms-bgm-companion-music-app://" を使用してバックグラウンドで起動できます。 アプリがライセンス認証を受け取ると、ProtocolActivatedEventArgs から取得した URI に "ms-bgm-" プレフィックスは含まれません。

この方法で呼び出された場合、適切なアプリがインストールされていないと、XLaunchUri はユーザーにプロンプトを表示しません。 代わりに、ゲームが April 2025 バージョンの GDK 以降を使用している場合は、E_GAMEPACKAGE_NO_PACKAGE_IDENTIFIER が返されます。 コードは、この戻り値を確認することができ、必要に応じて修復 UI をユーザーに表示するために使用します。

PC では、この方法で XLaunchUri が呼び出されると、通常どおり起動する前に URI の先頭から "ms-bgm-" が削除されます。 PC のシステム動作に他の影響はありません。

XLaunchUri を呼び出してコンパニオン ミュージック アプリケーションを起動する例を次に示します。

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 本体

関連項目

XLauncher