XPackageCreateInstallationMonitor

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

Syntax

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

Parameters

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* 戻り時、作成されたインストールモニターを指します。

Return value

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

Remarks

この関数はタイムセンシティブスレッドで呼び出すのは安全ではありません。詳細については、タイムセンシティブスレッドを参照してください。

XPackageCreateInstallationMonitor は、インストールの状態を追跡するモニターを作成します。モニターは、指定された更新間隔によって管理される定期的なペースで自身を更新およびリフレッシュします。更新は指定されたタスクキュー上でスケジュールされます。間隔がゼロの場合、更新は決して実行されず、インストールの一度限りのスナップショットとなるインストールモニターが作成されます。間隔がゼロで渡された場合、queue パラメーターは 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);

インストールされたすべてのコンテンツには一意の識別子があります。パッケージの識別子を知っており、そのコンテンツにアクセス権があれば、任意のパッケージのインストールを監視できます。実行中のプロセスは自身のパッケージ識別子を取得できます。

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 ms)。この速度が上限です。時間内に進行がなかった場合は、より遅くなる可能性があります。

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

トラックがいつロードを完了したかを知りたいので、モニターに進捗変更イベントを登録します。このコールバックは、モニターが作成されたときに提供されたタスクキューを通じて、XPackageCreateInstallationMonitor で指定されたおおよそのペースで呼び出されます。コールバック内で、ゲーム内の進捗を描画したり、トラックの準備が整ったことをゲームに通知したりできます。この例では、インストールモニターを閉じますが、通知の登録は解除しません。インストールモニター通知のライフタイムはインストールモニターに結び付けられているため、モニターを閉じることで、それに関連するすべての通知が登録解除されます。

Requirements

ヘッダー: XPackage.h ライブラリ: xgameruntime.lib サポートされているプラットフォーム: Windows、XBOX One ファミリー本体および XBOX Series 本体

(all) API references

Error codes

Audio API reference

Chat API reference

Developer kit only API reference

Graphics API reference

Input API reference

Lighting API reference

Networking API reference

XBOX PC remote iteration API reference

System API reference

Tools API reference

Windows device portal REST API reference

XBOX services API reference

MicrosoftGame.config reference

XPackageCreateInstallationMonitor

XPackageCreateInstallationMonitor

Syntax

Parameters

Return value

Remarks

Requirements

Conceptual documentation

See also

​XPackageCreateInstallationMonitor

​Syntax

​Parameters

​Return value

​Remarks

​Requirements

​Conceptual documentation

​See also

XPackageCreateInstallationMonitor

Syntax

Parameters

Return value

Remarks

Requirements

Conceptual documentation

See also