PackageManager QML 类型

应用程序管理器中负责软件包安装/删除/更新的部分。更多信息...

导入声明	import QtApplicationManager.SystemUI 2.0

所有成员的列表，包括继承成员

属性

documentLocation : 对象
installationLocation : 对象
ready : 布尔值

信号

taskBlockingUntilInstallationAcknowledge(string taskId)
taskFailed(string taskId)
taskFinished(string taskId)
taskProgressChanged(string taskId, qreal progress)
taskRequestingInstallationAcknowledge(string taskId, PackageObject package, object packageExtraMetaData, object packageExtraSignedMetaData)
taskStarted(string taskId)
taskStateChanged(string taskId, string newState)

方法

void acknowledgePackageInstallation(string taskId)
list<string> activeTaskIds()
bool cancelTask(string taskId)
int compareVersions(string version1, string version2)
object get(string packageId)
object get(int index)
int indexOfPackage(string id)
var installedPackageExtraMetaData(string packageId)
var installedPackageExtraSignedMetaData(string packageId)
int installedPackageSize(string packageId)
PackageObject package(string id)
PackageObject package(int index)
list<string> packageIds()
string removePackage(string packageId, bool keepDocuments, bool force)
string startPackageInstallation(string sourceUrl)
string taskPackageId(string taskId)
enumeration taskState(string taskId)
int validateDnsName(string name, int minimalPartCount)

详细描述

PackageManager 单例类型处理应用管理器的包安装部分。它为所有功能提供 DBus 和 QML API。

注意：与已弃用的 ApplicationInstaller 类不同，PackageManager 单例及其对应的 DBus API 总是可用。通过应用管理器的配置禁用安装器功能将直接导致包的（解）安装失败。

请注意，设置 applications/installationDirMountPoint 配置选项可能会延迟包数据库的初始化。在这种情况下，在与 PackageManager 交互之前，请确保 ready 属性为 true。

该类型继承自 QAbstractListModel，因此可以直接用作 QML 中的模型。

该模型中以下角色可用

角色名称	类型	描述
`packageId`	字符串	包的唯一 ID，表示为字符串（例如 `Browser` 或 `com.pelagicore.music`）
`name`	字符串	包的名称。如果可能，已翻译为当前区域设置。
`icon`	字符串	包图标 URL。
`isBlocked`	布尔值	当应用管理器需要阻止此包中的任何应用程序运行时，将设置该布尔值：通常只在应用更新时发生。
`isUpdating`	布尔值	表示包是否正在安装或更新的布尔值。如果为 `true`，则可以使用 `updateProgress` 跟踪实际进度。
`isRemovable`	布尔值	表示此包是否可由用户删除的布尔值；所有动态安装的第三方包为 `true`，所有系统包为 `false`。
`updateProgress`	实数	当 `isUpdating` 为 `true` 时，查询此角色将返回 `0.0` 到 `1.0` 范围内的实际进度作为浮点值。
`categories`	list<string>	通过其元数据文件注册此包的类别。
`version`	字符串	此包的当前安装版本。
`package`	Package	用于快速访问模型代表之外属性的底层包对象。

下表描述了后台任务可能处于的所有可能状态

任务状态	描述
`Queued`	任务已创建并正在排队执行。
`Executing`	任务正在执行。
`Finished`	任务已成功执行。
`Failed`	任务未能成功执行。
`AwaitingAcknowledge`	仅安装任务！任务目前正在暂停，等待 acknowledgePackageInstallation() 或 cancelTask() 继续执行。有关安装工作流程的更多信息，请参阅 startPackageInstallation()。
`Installing`	仅安装任务！通过 acknowledgePackageInstallation() 承认安装，现在正在运行最终安装阶段。
`CleaningUp`	仅安装任务！安装已完成，并且之前的安装以及临时文件正在清理。

任务的正常工作流程为：Queued → Executing → Finished。任务可以在任何点进入 Failed 状态 - 或者通过 cancelTask() 取消，或者简单地因为错误而失败。

由于必须经过以下确认阶段，安装任务会稍微复杂一些：排队 → 执行中 → 等待确认（如果已经调用了 acknowledgePackageInstallation()，则可能跳过此状态）→ 安装中 → 清理 → 完成。同样，任务可能在任何时刻失败。

属性文档

documentLocation : 对象

返回一个对象，详细描述了用户文档目录在哪个位置创建。

返回的对象有与PackageManager::installationLocation中描述的相同成员。

installationLocation : 对象

返回一个对象，详细描述了在哪个位置安装软件包。

返回的对象有以下成员

`名称`	`类型`	描述
`路径`	`字符串`	基础目录的绝对文件系统路径。
`设备大小`	`int`	包含路径的设备的字节大小。
`设备空闲空间`	`int`	包含路径的设备上的空闲字节数。

如果安装组件被禁用，返回空对象。

ready : 布尔

如果启动时设置了配置选项 applications/installationDirMountPoint，则加载数据库可能被延迟。

如果您的系统依赖于此行为，您应该始终在访问有关已安装软件包的信息之前检查 ready 属性是否为 true。

注意：当 ready 仍为 false 时，调用 startPackageInstallation() 和 removePackage() 将排队并等待包数据库完全加载后执行。

信号文档

taskBlockingUntilInstallationAcknowledge(字符串 taskId)

当安装任务因缺少对任务调用 acknowledgePackageInstallation() 而无法继续时，将发出此信号。

注意：对应的手动是 onTaskBlockingUntilInstallationAcknowledge。

另请参阅：taskStateChanged() 和 acknowledgePackageInstallation()。

taskFailed(字符串 taskId)

当任务标识为 taskId 的任务进入 Failed 状态时，将发出此信号。

注意：对应的手动是 onTaskFailed。

另请参阅：taskStateChanged()。

taskFinished(字符串 taskId)

当任务标识为 taskId 的任务进入 Finished 状态时，将发出此信号。

注意：对应的手动是 onTaskFinished。

另请参阅：taskStateChanged()。

taskProgressChanged(字符串 taskId, qreal progress)

每当由taskId标识的任务接近完成时，都会发出此信号。进度通过一个浮点数报告，范围从0.0到1.0。

注意： 相应的处理程序是onTaskProgressChanged。

另请参阅：taskStateChanged()。

taskRequestingInstallationAcknowledge(string taskId, PackageObject package, object packageExtraMetaData, object packageExtraSignedMetaData)

当由taskId标识的安装任务接收到足够的元数据并能够发出此信号时，此信号会被发出。任务可能处于Executing或AwaitingAcknowledge状态。

通过package通过一个临时的PackageObject提供。请注意，在此信号发出时，此对象只是临时构建的，不是PackageManager模型的一部分。信号回调返回后，包对象将被销毁。稍后，在安装过程中将构建另一个也是模型一部分的永久PackageObject。

此外，通过packageExtraMetaData和packageExtraSignedMetaData分别以JavaScript对象的形式提供了包的额外元数据（签名和非签名）。这两个对象都是可选的，需要在应用打包步骤中显式填充或由中间应用商店服务器添加。默认情况下，两者都将为空。

在此信号之后，必须调用cancelTask()或acknowledgePackageInstallation()，以分别取消此taskId的安装或尝试完成它。

PackageManager有两个便利函数来帮助System UI验证元数据：compareVersions()和，如果您使用反向DNS表示法表示应用程序ID，则validateDnsName()。

注意： 相应的处理程序是onTaskRequestingInstallationAcknowledge。

另见 taskStateChanged()和startPackageInstallation()。

taskStarted(string taskId)

当由taskId标识的任务进入Executing状态时，此信号会被发出。

注意： 相应的处理程序是onTaskStarted。

另请参阅：taskStateChanged()。

taskStateChanged(string taskId, string newState)

当由taskId标识的任务的状态发生变化时，会发出此信号。新状态由参数newState提供。

注意： 相应的处理程序是onTaskStateChanged。

另见 taskState()。

方法说明

void acknowledgePackageInstallation(string taskId)

调用此函数可以启用安装程序来完成由taskId标识的安装任务。通常，在接收到taskRequestingInstallationAcknowledge()信号之后，调用此函数，并且用户和/或程序逻辑决定继续安装。

另见 startPackageInstallation()。

列表<字符串> activeTaskIds()

返回所有当前活动中（尚未完成或失败）的安装任务ID列表。

布尔值 cancelTask(字符串 taskId)

尝试取消由 taskId 标识的安装任务。

如果任务被取消，则返回 true，否则为 false。

整数 compareVersions(字符串 version1, 字符串 version2)

为应用商店实现或 taskRequestingInstallationAcknowledge() 回调提供一个方便的方法来比较版本号，因为实际的版本比较算法并不简单。

如果 version1 小于、等于或大于 version2，则返回 -1、0 或 1（类似于 strcmp() 的工作方式）。

对象 get(字符串 packageId)

以JavaScript对象的形式检索由 packageId 标识的包的数据模型。请参阅角色名称以了解预期的对象字段。

如果指定的 packageId 无效，则返回空对象。

对象 get(整数 index)

以JavaScript对象的形式检索位于 index 的模型数据。请参阅角色名称以了解预期的对象字段。

如果指定的 index 无效，则返回空对象。

注意：如果你只想从QML访问单个属性，那么这非常低效；请改用 package() 来直接访问 PackageObject 的属性。

整数 indexOfPackage(字符串 id)

将包 id 映射到模型中的位置。

如果指定的 id 无效，则返回 -1。

变量 installedPackageExtraMetaData(字符串 packageId)

返回由 packageId 标识的包头中所有额外元数据的映射。

如果包 packageId 无效或未安装，则返回空映射。

变量 installedPackageExtraSignedMetaData(字符串 packageId)

返回由 packageId 标识的包头中所有已签名的额外元数据的映射。

如果包 packageId 无效或未安装，则返回空映射。

int installedPackageSize(string packageId)

返回由 packageId 指定的包在存储设备上占用的字节数。

如果 packageId 无效或包未安装，则返回 -1。

PackageObject package(string id)

返回与给定 id 对应的 PackageObject，或如果 id 不存在则返回 null。

注意：返回的 PackageObject 的所有权属于应用程序管理器。如果您想存储此指针，可以使用 PackageManager 的 QAbstractListModel 信号或 packageAboutToBeRemoved 信号来通知对象在 C++ 端即将被删除。

PackageObject package(int index)

返回与给定 index 在模型中对应的 PackageObject，或如果索引无效则返回 null。

list<string> packageIds()

返回所有可用包 id 的列表。这可以用于通过 get() 进一步查询特定信息。

string removePackage(string packageId, bool keepDocuments, bool force)

卸载由 packageId 指定的包。通常，在删除时删除包的文档目录，但可以将 keepDocuments 设置为 true 以阻止此操作。

实际删除将在后台异步发生。当适用时，PackageManager 将发射信号 taskStarted、taskProgressChanged、taskFinished、taskFailed 和 taskStateChanged 来通知返回的 taskId。

通常情况下，只有当 removePackage() 之前的调用失败时，才应将 force 设置为 true。这可能是在安装过程被中断或存在文件系统问题时所需的。

返回唯一的 taskId。这也可以是一个空字符串，如果任务无法创建（在这种情况下，不会发出信号）。

string startPackageInstallation(string sourceUrl)

从 sourceUrl 下载应用程序包并安装它。

实际下载和安装将在后台异步进行。当适用时，PackageManager 将发射信号 taskStarted、taskProgressChanged、taskRequestingInstallationAcknowledge、taskFinished、taskFailed 和 taskStateChanged，以返回 taskId。

注意：仅调用此函数不足以完成软件包安装：需要将 taskRequestingInstallationAcknowledge() 信号连接到槽，在槽中对提供的软件包元数据进行验证（程序化或询问用户）。如果验证成功，可以通过调用 acknowledgePackageInstallation() 来完成安装；如果验证失败，应通过调用 cancelTask() 来取消安装。不完成任一步骤将留下未完成的“僵尸”安装。

返回唯一的 taskId。这也可以是一个空字符串，如果任务无法创建（在这种情况下，不会发出信号）。

字符串 taskPackageId(字符串 taskId)

返回与由 taskId 标识的任务相关联的软件包 id。尽管任务可能根本不具有有效的软件包 id，但在这种情况下该函数将返回空字符串（如果还没有发射 taskRequestingInstallationAcknowledge 信号，将出现这种情况）。

如果 taskId 无效，则返回空字符串。

枚举 taskState(字符串 taskId)

返回由 taskId 标识的安装任务的当前状态。请参阅此处了解有效任务状态的列表。

如果 taskId 无效，则返回 PackageManager.Invalid。

整数 validateDnsName(字符串 name, 整数 minimalPartCount)

为应用商店实现或 taskRequestingInstallationAcknowledge() 回调提供便利方法，用于检查给定的 name 是否是有效的 DNS（或反向-DNS）名，符合 RFC 1035/1123。如果指定了可选参数 minimalPartCount，则此函数还会检查 name 是否包含至少这么多部分/子域。

如果名字是有效的 DNS 名称，则返回 true；否则返回 false。