XPackageCreateInstallationMonitor

创建安装状态的监视器。

语法

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 创建一个对安装状态保持跟踪的监视器。 监视器将以由指定的更新间隔控制的定期节奏自行进行更新和刷新。 更新是在指定的任务队列上计划的。 间隔为零指定从不执行更新，并创建安装监视器（这是安装的一次性快照）。 如果传递零间隔，则队列参数可以为 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 毫秒），以指示安装监视器将更新其进度快照的频率（最高为此速度）。 如果未及时取得进度，可能会降低速度。

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

您想要知道赛道何时完成加载，以便在监视器上注册进度更改事件。 此回调将通过创建监视器时提供的任务队列来调用，大致采用在 XPackageCreateInstallationMonitor 中指定的节奏。 在回调内，您可以呈现游戏内进度，或通知游戏赛道已准备就绪。

在此示例中，您关闭安装监视器，但不取消注册通知。 安装监视器通知的生命周期与安装监视器关联；因此，关闭监视器会向其取消注册所有通知。

要求

头文件：XPackage.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XPackage