PackageManager QML Type
The package installation/removal/update part of the application manager. More...
| Import Statement: | import QtApplicationManager.SystemUI 2.0 |
Properties
- documentLocation : object
- installationLocation : object
Signals
- 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)
Methods
- 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)
Detailed Description
The PackageManager singleton type handles the package installation part of the application manager. It provides both a DBus and QML APIs for all of its functionality.
Note: Unlike the deprecated ApplicationInstaller class, the PackageManager singleton and its corresponding DBus API are always available. Disabling the installer functionality via the application manager's Configuration will just lead to package (de-) installations failing instantly.
The type is derived from QAbstractListModel, so it can be used directly as a model from QML.
The following roles are available in this model:
| Role name | Type | Description |
|---|---|---|
packageId | string | The unique ID of a package, represented as a string (e.g. Browser or com.pelagicore.music) |
name | string | The name of the package. If possible, already translated to the current locale. |
icon | string | The URL of the package's icon. |
isBlocked | bool | A boolean value that gets set when the application manager needs to block any application within this package from running: this is normally only the case while an update is being applied. |
isUpdating | bool | A boolean value indicating whether the package is currently being installed or updated. If true, the updateProgress can be used to track the actual progress. |
isRemovable | bool | A boolean value indicating whether this package is user-removable; true for all dynamically installed third party packages and false for all system packages. |
updateProgress | real | While isUpdating is true, querying this role returns the actual progress as a floating-point value in the 0.0 to 1.0 range. |
categories | list<string> | The categories this package is registered for via its meta-data file. |
version | string | The currently installed version of this package. |
package | Package | The underlying package object for quick access to the properties outside of a model delegate. |
The following table describes all possible states that a background task could be in:
| Task State | Description |
|---|---|
Queued | The task was created and is now queued up for execution. |
Executing | The task is being executed. |
Finished | The task was executed successfully. |
Failed | The task failed to execute successfully. |
AwaitingAcknowledge | Installation tasks only! The task is currently halted, waiting for either acknowledgePackageInstallation() or cancelTask() to continue. See startPackageInstallation() for more information on the installation workflow. |
Installing | Installation tasks only! The installation was acknowledged via acknowledgePackageInstallation() and the final installation phase is now running. |
CleaningUp | Installation tasks only! The installation has finished, and previous installations as well as temporary files are being cleaned up. |
The normal workflow for tasks is: Queued → Executing → Finished. The task can enter the Failed state at any point though - either by being canceled via cancelTask() or simply by failing due to an error.
Installation tasks are a bit more complex due to the acknowledgment: Queued → Executing → AwaitingAcknowledge (this state may be skipped if acknowledgePackageInstallation() was called already) → Installing → Cleanup → Finished. Again, the task can fail at any point.
Property Documentation
documentLocation : object |
Returns an object describing the location under which per-user document directories are created in detail.
The returned object has the same members as described in PackageManager::installationLocation.
installationLocation : object |
Returns an object describing the location under which packages are installed in detail.
The returned object has the following members:
Name | Type | Description |
|---|---|---|
path | string | The absolute file-system path to the base directory. |
deviceSize | int | The size of the device holding path in bytes. |
deviceFree | int | The amount of bytes available on the device holding path. |
Returns an empty object in case the installer component is disabled.
Signal Documentation
taskBlockingUntilInstallationAcknowledge(string taskId) |
This signal is emitted when the installation task identified by taskId cannot continue due to a missing acknowledgePackageInstallation() call for the task.
Note: The corresponding handler is onTaskBlockingUntilInstallationAcknowledge.
See also taskStateChanged() and acknowledgePackageInstallation().
taskFailed(string taskId) |
This signal is emitted when the task identified by taskId enters the Failed state.
Note: The corresponding handler is onTaskFailed.
See also taskStateChanged().
taskFinished(string taskId) |
This signal is emitted when the task identified by taskId enters the Finished state.
Note: The corresponding handler is onTaskFinished.
See also taskStateChanged().
taskProgressChanged(string taskId, qreal progress) |
This signal is emitted whenever the task identified by taskId makes progress towards its completion. The progress is reported as a floating-point number ranging from 0.0 to 1.0.
Note: The corresponding handler is onTaskProgressChanged.
See also taskStateChanged().
taskRequestingInstallationAcknowledge(string taskId, PackageObject package, object packageExtraMetaData, object packageExtraSignedMetaData) |
This signal is emitted when the installation task identified by taskId has received enough meta-data to be able to emit this signal. The task may be in either Executing or AwaitingAcknowledge state.
A temporary PackageObject is supplied via package. Please note, that this object is just constructed on the fly for this signal emission and is not part of the PackageManager model. The package object is destroyed again after the signal callback returns. Another permanent PackageObject that is also part of the model will be constructed later in the installation process.
In addition, the package's extra meta-data (signed and unsinged) is also supplied via packageExtraMetaData and packageExtraSignedMetaData respectively as JavaScript objects. Both these objects are optional and need to be explicitly either populated during an application's packaging step or added by an intermediary app-store server. By default, both will just be empty.
Following this signal, either cancelTask() or acknowledgePackageInstallation() has to be called for this taskId, to either cancel the installation or try to complete it.
The PackageManager has two convenience functions to help the System UI with verifying the meta-data: compareVersions() and, in case you are using reverse-DNS notation for application-ids, validateDnsName().
Note: The corresponding handler is onTaskRequestingInstallationAcknowledge.
See also taskStateChanged() and startPackageInstallation().
taskStarted(string taskId) |
This signal is emitted when the task identified by taskId enters the Executing state.
Note: The corresponding handler is onTaskStarted.
See also taskStateChanged().
This signal is emitted when the state of the task identified by taskId changes. The new state is supplied in the parameter newState.
Note: The corresponding handler is onTaskStateChanged.
See also taskState().
Method Documentation
void acknowledgePackageInstallation(string taskId) |
Calling this function enables the installer to complete the installation task identified by taskId. Normally, this function is called after receiving the taskRequestingInstallationAcknowledge() signal, and the user and/or the program logic decided to proceed with the installation.
See also startPackageInstallation().
Retuns a list of all currently active (as in not yet finished or failed) installation task ids.
Tries to cancel the installation task identified by taskId.
Returns true if the task was canceled, false otherwise.
Convenience method for app-store implementations or taskRequestingInstallationAcknowledge() callbacks for comparing version numbers, as the actual version comparison algorithm is not trivial.
Returns -1, 0 or 1 if version1 is smaller than, equal to, or greater than version2 (similar to how strcmp() works).
object get(string packageId) |
Retrieves the model data for the package identified by packageId as a JavaScript object. See the role names for the expected object fields.
Returns an empty object if the specified packageId is invalid.
object get(int index) |
Retrieves the model data at index as a JavaScript object. See the role names for the expected object fields.
Returns an empty object if the specified index is invalid.
Note: This is very inefficient if you only want to access a single property from QML; use package() instead to access the PackageObject's properties directly.
Maps the package id to its position within the model.
Returns -1 if the specified id is invalid.
Returns a map of all extra metadata in the package header of the package identified by packageId.
Returns an empty map in case the package packageId is not valid, or the package is not installed.
Returns a map of all signed extra metadata in the package header of the package identified by packageId.
Returns an empty map in case the package packageId is not valid, or the package is not installed.
Returns the size in bytes that the package identified by packageId is occupying on the storage device.
Returns -1 in case the package packageId is not valid, or the package is not installed.
PackageObject package(string id) |
Returns the PackageObject corresponding to the given package id, or null if the id does not exist.
Note: The object ownership of the returned PackageObject stays with the application manager. If you want to store this pointer, you can use the PackageManager's QAbstractListModel signals or the packageAboutToBeRemoved signal to get notified if the object is about to be deleted on the C++ side.
PackageObject package(int index) |
Returns the PackageObject corresponding to the given index in the model, or null if the index is invalid.
Note: The object ownership of the returned PackageObject stays with the application manager. If you want to store this pointer, you can use the PackageManager's QAbstractListModel signals or the packageAboutToBeRemoved signal to get notified if the object is about to be deleted on the C++ side.
Returns a list of all available package ids. This can be used to further query for specific information via get().
Uninstalls the package identified by packageId. Normally, the documents directory of the package is deleted on removal, but this can be prevented by setting keepDocuments to true.
The actual removal will happen asynchronously in the background. The PackageManager will emit the signals taskStarted, taskProgressChanged, taskFinished, taskFailed and taskStateChanged for the returned taskId when applicable.
Normally, force should only be set to true if a previous call to removePackage() failed. This may be necessary if the installation process was interrupted, or or has file-system issues.
Returns a unique taskId. This can also be an empty string, if the task could not be created (in this case, no signals will be emitted).
Downloads an application package from sourceUrl and installs it.
The actual download and installation will happen asynchronously in the background. The PackageManager emits the signals taskStarted, taskProgressChanged, taskRequestingInstallationAcknowledge, taskFinished, taskFailed, and taskStateChanged for the returned taskId when applicable.
Note: Simply calling this function is not enough to complete a package installation: The taskRequestingInstallationAcknowledge() signal needs to be connected to a slot where the supplied package meta-data can be validated (either programmatically or by asking the user). If the validation is successful, the installation can be completed by calling acknowledgePackageInstallation() or, if the validation was unsuccessful, the installation should be canceled by calling cancelTask(). Failing to do one or the other will leave an unfinished "zombie" installation.
Returns a unique taskId. This can also be an empty string, if the task could not be created (in this case, no signals will be emitted).
Returns the package id associated with the task identified by taskId. The task may not have a valid package id at all times though and in this case the function will return an empty string (this will be the case for installations before the taskRequestingInstallationAcknowledge signal has been emitted).
Returns an empty string if the taskId is invalid.
enumeration taskState(string taskId) |
Returns the current state of the installation task identified by taskId. See here for a list of valid task states.
Returns PackageManager.Invalid if the taskId is invalid.
Convenience method for app-store implementations or taskRequestingInstallationAcknowledge() callbacks for checking if the given name is a valid DNS (or reverse-DNS) name according to RFC 1035/1123. If the optional parameter minimalPartCount is specified, this function will also check if name contains at least this amount of parts/sub-domains.
Returns true if the name is a valid DNS name or false otherwise.
© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.