> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XPackageCreateInstallationMonitor

> XPackageCreateInstallationMonitor

# XPackageCreateInstallationMonitor

创建安装状态的监视器。

## 语法

```cpp theme={null}
HRESULT XPackageCreateInstallationMonitor(  
         const char* packageIdentifier,  
         uint32_t selectorCount,  
         XPackageChunkSelector* selectors,  
         uint32_t minimumUpdateIntervalMs,  
         XTaskQueueHandle queue,  
         XPackageInstallationMonitorHandle* installationMonitor  
)  
```

### 参数

*packageIdentifier*   \_In\_z\_\
类型：char\*

唯一标识磁盘上已安装程序包的字符串。有关程序包标识符的详细信息，请参阅[管理和许可可下载内容 (DLC)](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-manage-and-license-optional-packages)。

*selectorCount*   \_In\_\
类型：uint32\_t

*selectors* 参数中的选择器数。

*selectors*   \_In\_reads\_opt\_(selectorCount)\
类型：[XPackageChunkSelector\*](/reference/system/xpackage/structs/xpackagechunkselector)

指定要监视的区块的选择器数组。

*minimumUpdateIntervalMs*   \_In\_\
类型：uint32\_t

监视器的分辨率（以毫秒为单位）。

*queue*   \_In\_opt\_\
类型：XTaskQueueHandle

执行更新的队列。

*installationMonitor*   \_Out\_\
类型：XPackageInstallationMonitorHandle\*

返回时，指向创建的安装监视器。

### 返回值

类型：HRESULT

HRESULT 成功或错误代码。

## 备注

<Note>此函数在时间敏感线程上调用不安全。有关详细信息，请参阅[时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

**XPackageCreateInstallationMonitor** 创建一个跟踪安装状态的监视器。该监视器按指定更新间隔控制的固定节奏更新并刷新自身。更新在指定的任务队列上进行调度。零间隔指定从不执行更新，并创建一个一次性快照的安装监视器。如果传递了零间隔，队列参数可以为 null。

若要获取安装的当前进度，请调用 [XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress)；若要在安装过程中获得变化通知，请注册回调。可以为整个程序包或特定子集创建此安装监视器。

一款游戏实现了启动标记，因此它可以在完全安装之前运行。该游戏需要知道哪些部分已安装，哪些部分尚未安装。在此示例中，游戏需要知道与具有指定跑道名称的赛道关联的区块何时安装完成：

```cpp theme={null}
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 调用：

```cpp theme={null}
XPackageGetCurrentProcessPackageIdentifier(_countof(id), id); 
```

所有已安装的内容都有唯一标识符。只要你知道任何程序包的标识符并可以访问该内容，就可以监视其安装。运行中的进程可以获取自己的程序包标识符。

```cpp theme={null}
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](/reference/system/xpackage/functions/xpackagegetinstallationprogress)；若要在安装过程中获得变化通知，请注册回调。

你可以为整个程序包或特定子集创建安装监视器。在此，你已定义了一个“选择器”，用于表示你想了解某个赛道名称的安装进度。你可以指定频率（在此为 1000 ms），指示安装监视器更新其进度快照的频率上限。如果没有及时的进度发生，可能会更慢。

```cpp theme={null}
hr = XPackageRegisterInstallationProgressChanged(
    monitor,
    nullptr,
    ProgressChangedCallback,
    &token);
```

你想知道赛道何时加载完毕，因此在监视器上注册了一个进度变更事件。此回调将通过创建监视器时提供的任务队列调用，大致按照 [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor) 中指定的节奏。在回调内部，你可以呈现游戏内进度或通知游戏赛道已准备就绪。

在此示例中，你关闭了安装监视器但没有取消注册通知。安装监视器通知的生存期与安装监视器绑定；因此，关闭该监视器会取消对其注册的所有通知。

## 要求

**头文件：** XPackage.h

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 概念性文档

* [流式安装：状态](/build/core-features/common/packaging/packaging-installstatus)
* [时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)
* [检查更新](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-checking-for-updates)

## 另请参阅

[XPackage](/reference/system/xpackage/xpackage_members)


## Related topics

- [XPackageInstallationProgressCallback](/zh-CN/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageRegisterInstallationProgressChanged](/zh-CN/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [流式安装:状态](/zh-CN/build/core-features/common/packaging/packaging-installstatus.md)
- [检查更新](/zh-CN/publishing/xstore-commerce/xstore-checking-updates.md)
- [XPackageCloseInstallationMonitorHandle](/zh-CN/reference/system/xpackage/functions/xpackagecloseinstallationmonitorhandle.md)