PackageManager QML类型

应用程序管理器中的包安装/卸载/更新的部分。更多信息...

导入声明	import QtApplicationManager.SystemUI 2.0

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

属性

allowInstallationOfUnsignedPackages : string
architecture : string
developmentMode : bool
documentLocation : object
hardwareId : string
installationLocation : object
ready : bool

信号

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(int index)
object get(string packageId)
int indexOfPackage(string id)
var installedPackageExtraMetaData(string packageId)
var installedPackageExtraSignedMetaData(string packageId)
int installedPackageSize(string packageId)
PackageObject package(int index)
包装对象 package(string id)
list packageIds()
string removePackage(string packageId, bool keepDocuments, bool force)
string startPackageInstallation(string sourceUrl)
string taskPackageId(string taskId)
枚举 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`	string	软件包的唯一ID，表示为字符串（例如`Browser`或`com.pelagicore.music`）
`name`	string	软件包的名称。如果可能，已翻译为当前区域设置。
`icon`	string	软件包图标的URL。
`isBlocked`	bool	当应用程序管理器需要阻止此软件包中的任何应用程序运行时，设置此布尔值：这通常仅适用于更新应用期间。
`isUpdating`	bool	一个布尔值，指示该软件包是否目前正在安装或更新。如果为`true`，可以使用`updateProgress`来跟踪实际进度。
`isRemovable`	bool	一个布尔值，指示此软件包是否可由用户移除；对于所有动态安装的第三方软件包为`true`，而对于所有系统软件包为`false`。
`updateProgress`	real	当`isUpdating`为`true`时，查询此角色会返回一个在`0.0`到`1.0`范围内的浮点值，表示实际进度。
`categories`	list	通过其元数据文件登记的软件包分类。
`version`	string	该软件包的当前安装版本。
`package`	PackageObject	用于快速访问模型代理之外属性的底层PackageObject。注意：在严格模式下，`package`是一个保留的JavaScript关键字，因此在严格模式下定义`required property PackageObject package`时，必须使用`packageObject`角色。
`packageObject`	PackageObject	与`package`完全相同，但同时也适用于JavaScript的严格模式。此角色自Qt 6.6版本引入。

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

任务状态	描述
`已排队`	任务已创建，现在正在排队等待执行。
`正在执行`	任务正在执行。
`已完成`	任务已成功执行。
`失败`	任务未能成功执行。
`等待确认`	仅安装任务！任务当前暂停，正在等待acknowledgePackageInstallation()或cancelTask()以继续。有关安装工作流程的更多信息，请参阅startPackageInstallation()。
`正在安装`	仅安装任务！通过acknowledgePackageInstallation()确认了安装，现在正在进行最终安装阶段。
`清理中`	仅安装任务！安装已完成，以前的安装以及临时文件正在被清理。

任务的一般工作流程是：已排队 → 正在执行 → 已完成。然而，任务在任何时候都可以进入失败状态 - 要么是通过cancelTask()取消，要么是简单地由于错误而失败。

由于需要确认，安装任务更为复杂：已排队 → 正在执行 → 等待确认（如果已调用acknowledgePackageInstallation()，则此状态可能被跳过）→ 正在安装 → 清理 → 已完成。再次强调，任务可能在任何时刻失败。

属性文档

allowInstallationOfUnsignedPackages : string [只读]

此只读属性反映了配置文件中的allowUnsignedPackages设置。

architecture : string [只读]

一个唯一的字符串，用于标识当前系统的架构。

软件包仓库（如示例中的appman-package-server）可以使用这些标识符来支持同一软件包的多个架构特定构建。

developmentMode : bool [只读]

此只读属性反映了配置文件中的developmentMode设置。

documentLocation : object

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

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

hardwareId : string [只读]

此属性将返回当前系统的硬件标识符。

软件包仓库（如示例中的appman-package-server）可以使用这些硬件标识符通过数字签名将软件包的分发限制在特定设备上。

installationLocation : object

返回一个详细描述所安装包位置的物体。

返回的物体有以下成员

`名称`	`类型`	描述
`路径`	`string`	基础目录的绝对文件系统路径。
`设备大小`	`int`	以字节为单位包含 `path` 的设备的大小。
`设备可用空间`	`int`	在包含 `path` 的设备上的可用字节数。

如果安装组件被禁用，将返回空物体。

ready : bool

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

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

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

信号文档

taskBlockingUntilInstallationAcknowledge(string taskId)

当通过 taskId 识别的安装任务由于缺少对 acknowledgePackageInstallation() 调用而无法继续时，会触发此信号。

注意：相应处理程序为 onTaskBlockingUntilInstallationAcknowledge。

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

taskFailed(string taskId)

当通过 taskId 识别的任务进入 Failed 状态时，会触发此信号。

注意：相应处理程序为 onTaskFailed。

另请参阅：taskStateChanged()。

taskFinished(string taskId)

当通过 taskId 识别的任务进入 Finished 状态时，会触发此信号。

注意：相应处理程序为 onTaskFinished。

另请参阅：taskStateChanged()。

taskProgressChanged(string taskId, qreal progress)

只要通过 taskId 识别的任务在其完成过程中取得进展，就会发射此信号。进度以从 0.0 到 1.0 的浮点数报告。

注意：相应处理程序为 onTaskProgressChanged。

另请参阅：taskStateChanged()。

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

当通过 taskId 识别的安装任务接收到足够元数据以能够发射此信号时，会触发此信号。任务可能处于 Executing 或 AwaitingAcknowledge 状态。

通过包提供临时PackageObject。请注意，此对象仅为此信号发射而即时构建，不属于PackageManager模型。在信号回调返回后，包对象将被销毁。在安装过程中稍后，还将构建另一个永久性的PackageObject，该对象也是模型的一部分。

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

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

PackageManager有两个便利函数，用于帮助系统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（）。

list<string> activeTaskIds()

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

bool cancelTask(string taskId)

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

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

int compareVersions(string version1, string version2)

方便的应用商店实现方法或者 taskRequestingInstallationAcknowledge() 回调，用于比较版本号，因为实际的版本比较算法并不是简单的。

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

object get(int index)

以 JavaScript 对象形式检索 index 处的模型数据。查看角色名称以获取预期对象字段。

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

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

object get(string packageId)

以 JavaScript 对象形式检索由 packageId 标识的包的模型数据。查看角色名称以获取预期对象字段。

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

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

int indexOfPackage(string id)

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

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

var installedPackageExtraMetaData(string packageId)

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

如果包 packageId 无效，或者包没有安装，则返回一个空映射。

var installedPackageExtraSignedMetaData(string packageId)

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

如果包 packageId 无效，或者包没有安装，则返回一个空映射。

int installedPackageSize(string packageId)

返回由 packageId 标识的包在存储设备上占用的大小（字节）。

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

PackageObject package(int index)

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

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

PackageObject package(string id)

根据给定的包id返回对应的PackageObject，如果id不存在，则返回null。

列表<字符串> packageIds()

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

字符串 removePackage(字符串 packageId, 布尔 keepDocuments, 布尔 force)

卸载由packageId标识的包。通常，包的文档目录在移除时被删除，但可以设置keepDocuments为true来防止这种情况。

实际的移除将在后台异步发生。当适用时，PackageManager将发出taskStarted、taskProgressChanged、taskFinished、taskFailed和taskStateChanged信号。

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

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

字符串 startPackageInstallation(字符串 sourceUrl)

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

实际的下载和安装将在后台异步发生。当适用时，PackageManager发出taskStarted、taskProgressChanged、taskRequestingInstallationAcknowledge、taskFinished、taskFailed和taskStateChanged信号。

注意：仅调用此函数不足以完成包安装：需要将taskRequestingInstallationAcknowledge()信号连接到槽，在该槽中可以验证提供的包元数据（无论是程序化验证还是提示用户）。如果验证成功，可以通过调用acknowledgePackageInstallation()完成安装，如果验证失败，应该通过调用cancelTask()取消安装。未能完成其中之一将留下未完成的“僵尸”安装。

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

字符串 taskPackageId(字符串 taskId)

返回由 taskId 标识的任务关联的包标识符。尽管任务可能并非始终具有有效的包标识符，此函数将返回一个空字符串（在taskRequestingInstallationAcknowledge 信号已发出之前，这是这种情况）。

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

枚举 taskState(字符串 taskId)

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

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

int validateDnsName(字符串 name, int minimalPartCount)

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

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