> ## 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.

# XPackageRegisterInstallationProgressChanged

> XPackageRegisterInstallationProgressChanged

# XPackageRegisterInstallationProgressChanged

注册一个回调，在安装进度发生变化时调用。

## 语法

```cpp theme={null}
HRESULT XPackageRegisterInstallationProgressChanged(  
         XPackageInstallationMonitorHandle installationMonitor,  
         void* context,  
         XPackageInstallationProgressCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### 参数

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

要注册回调的安装监视器的句柄。

*context*   \_In\_opt\_\
类型：void\*

要传递给回调的上下文。

*callback*   \_In\_\
类型：XPackageInstallationProgressCallback\*

安装进度发生变化时调用的用户定义回调。

*token*   \_Out\_\
类型：[XTaskQueueRegistrationToken\*](/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

用于标识回调的令牌，稍后可通过 [XPackageUnregisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged) 使用此令牌注销回调。

### 返回值

类型：HRESULT

HRESULT 成功或错误代码。

## 备注

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

```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);
```

所有已安装的内容都将具有唯一的标识符。如果你知道包的标识符并有权访问该内容，则可以监视任何包的安装。正在运行的进程可以获取自己的包标识符。有关包标识符的详细信息，请参阅[管理和授权可下载内容 (DLC)](https://learn.microsoft.com/gaming/gdk/docs/store/commerce/fundamentals/xstore-manage-and-license-optional-packages)。

```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 毫秒），指示安装监视器最快多久更新一次其进度快照。如果一段时间内没有进展，它可能会更慢。

```cpp theme={null}
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/intelligentdelivery-language)
* [流式安装：状态](/build/core-features/common/packaging/packaging-installstatus)

## 另请参阅

[XPackage](/reference/system/xpackage/xpackage_members)\
[流式安装和智能交付](/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)\
[XPackageGetInstallationProgress](/reference/system/xpackage/functions/xpackagegetinstallationprogress)\
[XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)


## Related topics

- [XPackageInstallationProgressCallback](/zh-CN/reference/system/xpackage/functions/xpackageinstallationprogresscallback.md)
- [XPackageUnregisterInstallationProgressChanged](/zh-CN/reference/system/xpackage/functions/xpackageunregisterinstallationprogresschanged.md)
- [流式安装:状态](/zh-CN/build/core-features/common/packaging/packaging-installstatus.md)
- [XPackage](/zh-CN/reference/system/xpackage/xpackage_members.md)
- [XTaskQueueRegistrationToken](/zh-CN/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken.md)