XPackageRegisterInstallationProgressChanged

[アーティクル]
05/10/2023

インストールの進行状況が変化したときに呼び出されるコールバックを登録します。

構文

HRESULT XPackageRegisterInstallationProgressChanged(  
         XPackageInstallationMonitorHandle installationMonitor,  
         void* context,  
         XPackageInstallationProgressCallback* callback,  
         XTaskQueueRegistrationToken* token  
)

パラメーター

installationMonitor _In_
型: XPackageInstallationMonitorHandle

コールバックが登録されるインストールモニターのハンドル。

context _In_opt_
型: void*

コールバックに渡すコンテキスト。

callback _In_
型: XPackageInstallationProgressCallback*

インストールの進行状況が変化したときに呼び出されるユーザー定義のコールバック。

token _Out_
型: XTaskQueueRegistrationToken*

後で XPackageUnregisterInstallationProgressChanged を使用してコールバックを登録解除するために使用できる、コールバックを識別するトークン。

戻り値

型: HRESULT

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

解説

ゲームは起動マーカーを実装しているため、完全にインストールされる前に実行できます。ゲームは、インストールされているパーツと、インストールされていないパーツを知る必要があります。この例では、指定されたトラック名を持つトラックに関連付けられたチャンクがインストールされるタイミングを、ゲームが知る必要があります。

void CALLBACK ProgressChangedCallback(
    void* /* context*/,
    XPackageInstallationMonitorHandle monitor)
{
    XPackageInstallationProgress progress;
    XPackageGetInstallationProgress(monitor, &progress);

    if (progress.completed)
    {
        printf("Track ready\n");
        XPackageCloseInstallationMonitorHandle(monitor);
    }
}

HRESULT StartMonitoring(XTaskQueueHandle queue, char* trackName)
{
    char id[XPACKAGE_IDENTIFIER_MAX_LENGTH];

    HRESULT hr = XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);
    if (FAILED(hr)) return hr;

    XPackageChunkSelector selector;
    selector.type = XPackageChunkSelectorType::Tag;
    selector.tag = trackName;

    XPackageInstallationMonitorHandle monitor;
    hr = XPackageCreateInstallationMonitor(
        id,         // Identity to be monitored
        1,          // Number of selectors
        &selector,  // Selectors
        1000,       // Resolution of the monitor, in milliseconds
        queue,      // Queue where updates are performed
        &monitor);
    if (FAILED(hr)) return hr;

    XTaskQueueRegistrationToken token;
    hr = XPackageRegisterInstallationProgressChanged(
        monitor,
        nullptr,
        ProgressChangedCallback,
        &token);

    if (FAILED(hr))
    {
        XPackageCloseInstallationMonitorHandle(monitor);
    }

    return hr;
}

上に示したコードで、各 API の呼び出しを見ていきましょう。

XPackageGetCurrentProcessPackageIdentifier(_countof(id), id);

インストールされたすべてのコンテンツには、一意の識別子があります。パッケージ ID がわかっていて、そのコンテンツにアクセスできる場合は、パッケージのインストールを監視できます。実行中のプロセスは、独自のパッケージ ID を取得できます。パッケージ識別子の詳細については、「ダウンロード可能なコンテンツ (DLC) の管理とライセンス」を参照してください。

XPackageCreateInstallationMonitor(
    id,         // Identity to be monitored
    1,          // Number of selectors
    &selector,  // Selectors
    1000,       // Resolution of the monitor, in milliseconds
    queue,      // Queue where updates are performed
    &monitor);

これにより、インストールの状態を追跡するモニターが作成されます。このインストールモニターは、一定の間隔で自動的に更新されます。現在のインストールの進行状況を取得するには、XPackageGetInstallationProgress を呼び出します。インストールの進行状況が変化したときに通知を受け取るには、コールバックを登録します。

パッケージ全体または特定のサブセットに対して、インストールモニターを作成できます。このようにして、トラック名に応じたインストールの進行状況を取得できる「セレクター」が定義されます。インストールモニターが進行状況のスナップショットを更新する頻度 (最高値、この場合は 1000 ミリ秒) を指定できます。時間内に進行していない場合は、それ以下になる場合があります。

XPackageRegisterInstallationProgressChanged(
    monitor,
    nullptr,
    ProgressChangedCallback,
    &token);

トラックの読み込みが完了したことを確認する場合は、モニターに進行状況変更イベントを登録します。このコールバックは、モニターの作成時に提供されたタスクキューを通じて呼び出されます。それはほぼ XPackageCreateInstallationMonitor で指定された間隔で行われます。コールバック内で、ゲーム内の進行状況をレンダリングしたり、トラックの準備ができたことをゲームに通知したりできます。

この例では、インストールモニターを閉じますが、通知の登録解除は行いません。インストールモニターの通知の有効期間は、インストールモニターに関連付けられています。したがって、モニターを閉じると、モニターへのすべての通知が登録解除されます。

要件

ヘッダー: XPackage.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

次の方法で共有

XPackageRegisterInstallationProgressChanged

構文

パラメーター

戻り値

解説

要件

関連項目

その他のリソース