XPackageGetInstallationProgress

インストールの現在の進行状況を返します。

構文

void XPackageGetInstallationProgress(  
         XPackageInstallationMonitorHandle installationMonitor,  
         XPackageInstallationProgress* progress  
)  

パラメーター

installationMonitor_In_
型: XPackageInstallationMonitorHandle

インストール モニターのハンドル。

progress _Out_
型: XPackageInstallationProgress*

戻ったとき、インストールの現在の進行状況が格納されています。

戻り値

型: void

解説

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

新しいコンテンツの新規インストール中は、インストールが完全に開始されていないため、ランタイムはパッケージの合計サイズを計算できません。 この場合、ランタイムは totalBytes の値として UINT64_MAX を返し、その他のすべてのフィールドについては 0 または false を返します。

以下に例を示します。

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

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

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

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

要件

ヘッダー: XPackage.h

ライブラリ: xgameruntime.lib

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

関連項目

XPackage