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

# 流式安装:状态

> 流式安装:状态

在安装进行时,如果玩家正在游玩,游戏必须跟踪支持游玩所需的内容,并检查所需内容是否已安装。游戏可以使用系统 API 查询硬盘上区块的状态以及正在下载内容的进度。

如果玩家试图进入需要尚未安装内容的游戏部分,游戏应通过显示对话框或进度条告知玩家,并传达安装进度。同时,游戏应始终为玩家提供离开进度界面的选项 —— 理想情况下,让玩家在内容安装期间也能体验其他内容。以下是一个示例。

在玩一款射击游戏的单人战役时,玩家到达了下一战役区域所需内容尚未安装的地方。良好的用户体验是显示一个显示内容获取状态的进度条,并提供加入多人游戏的选项。此选项可通过将一部分多人内容作为启动游戏所需的数据来启用。

游戏可以监控和验证安装,并在安装完成时收到通知。你可以监控整个包的安装,或包中一部分区块的安装。要创建安装监视器,请使用 [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)。将监视器指定为以下之一:

* 通过将 selector 作为参数指定一组特定的区块
* 通过指定零个 selector 来表示整个包

创建安装监视器后,注册以下事件之一的处理程序:

* 使用 [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged) 注册 *安装进度变化* 事件
* 使用 [XPackageRegisterPackageInstalled](/reference/system/xpackage/functions/xpackageregisterpackageinstalled) 注册 *包已安装* 事件

*包已安装* 事件表示整个包已完成安装。*进度变化* 事件让你可以监控安装进度。请注意,*进度变化* 事件也会指示安装已完成,因此如果你已经注册了 *进度变化* 处理程序,就不需要再注册 *包已安装* 处理程序。以下是一个示例。

某游戏已实现启动标记(launch marker),因此可以在完全安装前运行。游戏需要知道哪些部分已安装,哪些没有。为向玩家展示可用的赛道,游戏需要知道与某个特定名称赛道相关的区块何时安装完成。

```cpp theme={null}
class GameTrackMonitor 
{ 
public: 
 
    HRESULT StartMonitoring(XTaskQueueHandle queue, const char* trackName) 
    { 
        char id[PACKAGE_IDENTIFIER_MAX_LENGTH]; 
 
        XPackageChunkSelector selector; 
        selector.type = XPackageChunkSelectorType::Tag; 
        selector.tag = trackName; 
 
        RETURN_IF_FAILED(XPackageGetCurrentProcessPackageIdentifier(_countof(id), id)); 
 
        XPackageInstallationMonitorHandle monitor; 
 
        RETURN_IF_FAILED(XPackageCreateInstallationMonitor( 
            id,         // Identity to monitor. 
            1,          // Number of selectors. 
            &selector,  // Selectors. 
            1000,       // Resolution of monitor in ms. 
            queue,      // Queue where updates are performed. 
            &monitor)); 
 
        XTaskQueueRegistrationToken token; 
 
        HRESULT hr = XPackageRegisterInstallationProgressChanged( 
            monitor, 
            this, 
            [](void *context, XPackageInstallationMonitorHandle monitor) 
        { 
            GameTrackMonitor* pthis = static_cast<GameTrackMonitor*>(context); 
            XPackageInstallationProgress progress; 
 
            XPackageGetInstallationProgress(monitor, &progress); 
            pthis->DrawProgress(progress); 
            if (progress.completed) 
            { 
                pthis->TrackReady(); 
                XPackageCloseInstallationMonitorHandle(monitor); 
            } 
        }, &token); 
 
        if (FAILED(hr)) 
        { 
            XPackageCloseInstallationMonitorHandle(monitor); 
        } 
 
        return hr; 
    } 
 
private: 
 
    void DrawProgress(const XPackageInstallationProgress& progress) 
    { 
        // ... 
    } 
 
    void TrackReady() 
    { 
        // ... 
    } 
};
```

## 参考 API 文档

* [XPackage(API 内容)](/reference/system/xpackage/xpackage_members)
  * Functions
    * [XPackageCreateInstallationMonitor](/reference/system/xpackage/functions/xpackagecreateinstallationmonitor)
    * [XPackageRegisterInstallationProgressChanged](/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged)
    * [XPackageRegisterPackageInstalled](/reference/system/xpackage/functions/xpackageregisterpackageinstalled)


## Related topics

- [游戏打包、更新与流式安装测试](/zh-CN/build/core-features/common/packaging/title-packaging-streaming-install-testing.md)
- [流式安装与智能交付概述](/zh-CN/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery.md)
- [XPackageRegisterPackageInstalled](/zh-CN/reference/system/xpackage/functions/xpackageregisterpackageinstalled.md)
- [XPackageRegisterInstallationProgressChanged](/zh-CN/reference/system/xpackage/functions/xpackageregisterinstallationprogresschanged.md)
- [XPackageCreateInstallationMonitor](/zh-CN/reference/system/xpackage/functions/xpackagecreateinstallationmonitor.md)