XPackageCreateInstallationMonitor

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

インストールの状態のモニターを作成します。

構文

HRESULT XPackageCreateInstallationMonitor(  
         const char* packageIdentifier,  
         uint32_t selectorCount,  
         XPackageChunkSelector* selectors,  
         uint32_t minimumUpdateIntervalMs,  
         XTaskQueueHandle queue,  
         XPackageInstallationMonitorHandle* installationMonitor  
)

パラメーター

packageIdentifier _In_z_
型: char*

ディスクにインストールされているパッケージを一意に識別する文字列。パッケージ識別子の詳細については、「ダウンロード可能なコンテンツ (DLC) の管理とライセンス」を参照してください。

selectorCount _In_
型: uint32_t

selectors パラメーター内のセレクターの数。

selectors _In_reads_opt_(selectorCount)
型: XPackageChunkSelector*

監視するチャンクを指定するセレクターの配列。

minimumUpdateIntervalMs _In_
型: uint32_t

モニターの解像度 (ミリ秒単位)。

queue _In_opt_
型: XTaskQueueHandle

更新が実行されるキュー。

installationMonitor _Out_
型: XPackageInstallationMonitorHandle*

戻ったとき、作成されたインストールモニターを指しています。

戻り値

型: HRESULT

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

解説

注意

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

XPackageCreateInstallationMonitor により、インストールの状態を追跡するモニターが作成されます。モニターは、指定した更新間隔で定期的に更新およびリフレッシュされます。更新は、指定したタスクキューでスケジュールされます。間隔を 0 にすると、更新はまったく実行されず、インストールの 1 回限りのスナップショットであるインストールモニターが作成されます。間隔として 0 を渡すと、キューパラメーターは null になる場合があります。

現在のインストールの進行状況を取得するには、XPackageGetInstallationProgress を呼び出します。インストールの進行状況が変化したときに通知を受け取るには、コールバックを登録します。このインストールモニターは、パッケージ全体または特定のサブセットに対して作成することができます。

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

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 を取得できます。

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 ミリ秒) を指定できます。時間内に進行していない場合は、それ以下になる場合があります。

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

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

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

要件

ヘッダー: XPackage.h

ライブラリ: xgameruntime.lib

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

次の方法で共有

XPackageCreateInstallationMonitor

構文

パラメーター

戻り値

解説

要件

関連項目

その他のリソース