XPackageRegisterInstallationProgressChanged
注册在安装进度发生变化时要调用的回调。
语法
HRESULT XPackageRegisterInstallationProgressChanged(
XPackageInstallationMonitorHandle installationMonitor,
void* context,
XPackageInstallationProgressCallback* callback,
XTaskQueueRegistrationToken* token
)
参数
installationMonitor _In_
类型:XPackageInstallationMonitorHandle
指向要向其注册回调的安装监视器的句柄。
context _In_opt_
类型:void*
要传递给回调的上下文。
callback _In_
类型:XPackageInstallationProgressCallback*
在安装进度发生变化时要调用的用户定义的回调。
token _Out_
类型:XTaskQueueRegistrationToken*
一个令牌,它标识以后可用于使用 XPackageUnregisterInstallationProgressChanged 取消注册回调的回调。
返回值
类型:HRESULT
HRESULT 成功或错误代码。
备注
游戏已实现启动标记,因此它可以在完全安装之前运行。 游戏将需要了解安装哪些部分以及不安装哪些部分。 在此示例中,游戏需要知道何时安装与具有指定赛道名称的赛道关联的区块:
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);
所有安装的内容都将具有唯一标识符。 如果您知道程序包标识符并且您有权访问该内容,则可以监视任何程序包的安装。 一个正在运行的进程可以获取其自己的包标识符。 有关包标识符的详细信息,请参阅管理和许可可下载内容 (DLC)。
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 毫秒),以指示安装监视器将更新其进度快照的频率(最高为此速度)。 如果未及时取得进度,可能会降低速度。
XPackageRegisterInstallationProgressChanged(
monitor,
nullptr,
ProgressChangedCallback,
&token);
您想要知道赛道何时完成加载,以便在监视器上注册进度更改事件。 此回调将通过创建监视器时提供的任务队列来调用,大致采用在 XPackageCreateInstallationMonitor 中指定的节奏。 在回调内,您可以呈现游戏内进度,或通知游戏赛道已准备就绪。
在此示例中,您关闭安装监视器,但不取消注册通知。 安装监视器通知的生命周期与安装监视器关联;因此,关闭监视器会向其取消注册所有通知。
要求
头文件:XPackage.h
库:xgameruntime.lib
支持平台:Windows、Xbox One 系列主机和 Xbox Series 主机
另请参阅
XPackage
流式安装和智能交付
XPackageGetInstallationProgress
XPackageCreateInstallationMonitor