ApplicationInstaller QML Type

The package installation/removal/update part of the application-manager. More...

Import Statement: import QtApplicationManager.SystemUI 2.0

Signals

Methods

Detailed Description

The ApplicationInstaller 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: The ApplicationInstaller singleton and its corresponding DBus API are only available if you specify a base directory for installed application manifests. See Configuration for details.

The following table describes all possible states that a background task could be in:

Task StateDescription
QueuedThe task was created and is now queued up for execution.
ExecutingThe task is being executed.
FinishedThe task was executed successfully.
FailedThe task failed to execute successfully.
AwaitingAcknowledgeInstallation tasks only! The task is currently halted, waiting for either acknowledgePackageInstallation() or cancelTask() to continue. See startPackageInstallation() for more information on the installation workflow.
InstallingInstallation tasks only! The installation was acknowledged via acknowledgePackageInstallation() and the final installation phase is now running.
CleaningUpInstallation tasks only! The installation has finished, and previous installations as well as temporary files are being cleaned up.

The normal workflow for tasks is: QueuedExecutingFinished. 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: QueuedExecutingAwaitingAcknowledge (this state may be skipped if acknowledgePackageInstallation() was called already) → InstallingCleanupFinished. Again, the task can fail at any point.

Signal Documentation

taskBlockingUntilInstallationAcknowledge(taskId)

This signal is emitted when the installation task identified by taskId cannot continue due to a missing acknowledgePackageInstallation() call for the task.

See also taskStateChanged() and acknowledgePackageInstallation().


taskFailed(taskId)

This signal is emitted when the task identified by taskId enters the Failed state.

See also taskStateChanged().


taskFinished(taskId)

This signal is emitted when the task identified by taskId enters the Finished state.

See also taskStateChanged().


taskProgressChanged(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.

See also taskStateChanged().


taskRequestingInstallationAcknowledge(taskId, object application, 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.

The contents of the package's manifest file are supplied via application as a JavaScript object. Please see the role names for the expected object fields.

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 ApplicationInstaller 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().

See also taskStateChanged() and startPackageInstallation().


taskStarted(taskId)

This signal is emitted when the task identified by taskId enters the Executing state.

See also taskStateChanged().


taskStateChanged(taskId, string newState)

This signal is emitted when the state of the task identified by taskId changes. The new state is supplied in the parameter newState.

See also taskState().


Method Documentation

void acknowledgePackageInstallation(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().


list<string> activeTaskIds()

Retuns a list of all currently active (as in not yet finished or failed) installation task ids.


bool cancelTask(taskId)

Tries to cancel the installation task identified by taskId.

Returns true if the task was canceled, false otherwise.


int compareVersions(version1, string version2)

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 getInstallationLocation(installationLocationId)

Returns an object describing the installation location identified by installationLocationId in detail.

The returned object has the following members:

NameTypeDescription
idstringThe installation location id that is used as the handle for all other ApplicationInstaller function calls. The id consists of the type and index field, concatenated by a single dash (for example, internal-0).
typestringThe type of device this installation location is connected to. Valid values are internal (for any kind of built-in storage, e.g. flash), removable (for any kind of storage that is removable by the user, e.g. an SD card) and invalid.
indexintIn case there is more than one installation location for the same type of device, this zero-based index is used for disambiguation. For example, two SD card slots will result in the ids removable-0 and removable-1. Otherwise, the index is always 0.
isDefaultboolExactly one installation location is the default location which must be mounted and accessible at all times. This can be used by an UI application to get a sensible default for the installation location that it needs to pass to startPackageInstallation().
isRemovableboolIndicates whether this installation location is on a removable media (for example, an SD card).
isMountedboolThe current mount status of this installation location: should always be true for non-removable media.
installationPathstringThe absolute file-system path to the base directory under which applications are installed.
installationDeviceSizeintThe size of the device holding installationPath in bytes. This field is only present if isMounted is true.
installationDeviceFreeintThe amount of bytes available on the device holding installationPath. This field is only present if isMounted is true.
documentPathstringThe absolute file-system path to the base directory under which per-user document directories are created.
documentDeviceSizeintThe size of the device holding documentPath in bytes. This field is only present if isMounted is true.
documentDeviceFreeintThe amount of bytes available on the device holding documentPath. This field is only present if isMounted is true.

Returns an empty object in case the installationLocationId is not valid.


string installationLocationIdFromApplication(id)

Returns the installation location id for the application identified by id. Returns an empty string in case the application is not installed.

See also installationLocationIds().


list<string> installationLocationIds()

Retuns a list of all known installation location ids. Calling getInstallationLocation() on one of the returned identifiers will yield specific information about the individual installation locations.


var installedApplicationExtraMetaData(id)

Returns a map of all extra metadata in the package header of the application identified by id.

Returns an empty map in case the application id is not valid, or the application is not installed.


var installedApplicationExtraSignedMetaData(id)

Returns a map of all signed extra metadata in the package header of the application identified by id.

Returns an empty map in case the application id is not valid, or the application is not installed.


int installedApplicationSize(id)

Returns the size in bytes that the application identified by id is occupying on the storage device.

Returns -1 in case the application id is not valid, or the application is not installed.


string removePackage(id, bool keepDocuments, bool force)

Uninstalls the application identified by id. Normally, the documents directory of the application is deleted on removal, but this can be prevented by setting keepDocuments to true.

The actual removal will happen asynchronously in the background. The ApplicationInstaller 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 if an SD card got lost 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).


string startPackageInstallation(installationLocationId, string sourceUrl)

Downloads an application package from sourceUrl and installs it to the installation location described by installationLocationId.

The actual download and installation will happen asynchronously in the background. The ApplicationInstaller 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 application 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).


string taskApplicationId(taskId)

Returns the application id associated with the task identified by taskId. The task may not have a valid application 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(taskId)

Returns the current state of the installation task identified by taskId. See here for a list of valid task states.

Returns ApplicationInstaller.Invalid if the taskId is invalid.


int validateDnsName(name, int minimalPartCount)

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.


© 2019 Luxoft Sweden AB. 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.