A typical successful transaction would emit many signals such as ::Progress(), ::Package() and ::StatusChanged(). These are used to inform the client application of the current state, so widgets such as icons or description text can be updated.

These different signals are needed for a few different reasons:

This is the typical transaction failure case when there is no network available. The user is not given the chance to requeue the transaction as it is a fatal error.

In this non-trivial example, a local file install is being attempted. First the InstallFile is called with the only_trusted flag set. This will fail if the package does not have a valid GPG key, and ordinarily the transaction would fail. What the client can do, e.g. using libpackagekit, is to re-request the InstallFile with non-trusted. This will use a different PolicyKit authentication, and allow the file to succeed.

So why do we bother calling only_trusted in the first place? Well, the only_trusted PolicyKit role can be saved in the gnome-keyring, or could be set to the users password as the GPG key is already only_trusted by the user. The non-trusted action would likely ask for the administrator password, and not allowed to be saved. This gives the user the benifit of installing only_trusted local files without a password (common case) but requiring something stronger for untrusted or unsigned files.

If SimulateInstallPackage or SimulateInstallFile is used then the client may receive a INFO_UNTRUSTED package.

This is used to inform the client that the action would require the untrusted authentication type, which means the client does not attempt to do SimulateInstallPackage(only_trusted=TRUE) and only does SimulateInstallPackage(only_trusted=FALSE). This ensures the user has to only authenticate once for the transaction as the only_trusted=TRUE action may also require a password.

If the package is signed, and a valid GPG signature is available, then we need to ask the user to import the key, and re-run the transaction. This is done as three transactions, as other transactions may be queued and have a higher priority, and to make sure that the transaction object is not reused.

Keep in mind that PackageKit can only be running one transaction at any one time. If we had designed the PackageKit API to block and wait for user input, then no other transactions could be run whilst we are waiting for the user.

This is best explained using an example:

The vmware package is downloaded, but cannot be installed until a EULA is agreed to. If we pause the transaction then we never apply the updates automatically and the computer is not kept up to date. The user would have to wait a substantial amount of time waiting for the updates to download when returning from his nap after clicking "I agree" to the vmware EULA.

In the current system where transactions cannot block, the first transaction downloads vmware, and then it finishes, and puts up a UI for the user to click. In the meantime the second transaction (the update) is scheduled, downloaded and installed, and then finishes. The user returns, clicks "okay" and a third transaction is created that accepts the eula, and a forth that actually installs vmware.

It seems complicated, but it's essential to make sure none of the callbacks block and stop other transactions from happening.

When the DownloadPackages() method is called on a number of packages, then these are downloaded by the daemon into a temporary directory. This directory can only be written by the packagekitd user (usually root) but can be read by all users. The files are not downloaded into any specific directory, instead a random one is created in /var/cache/PackageKit. The reason for this intermediate step is that the DownloadPackages() method does not take a destination directory as the dameon is running as a different user to the user, and in a different SELinux context.

To preserve the SELinux attributes and the correct user and group ownership of the newly created files, the client (running in the user session) has to copy the files from the temporary directory into the chosen destination directory. NOTE: this copy step is optional but recommended, as the files will remain in the temporary directory until the daemon is times out and is restarted. As the client does not know (intentionally) the temporary directory or the filenames of the packages that are created, the ::Files() signal is emitted with the full path of the downloaded files. It is expected the package_id parameter of ::Files() will be blank, although this is not mandated.

Multiple ::Files() signals can be sent by the dameon, as the download operation may be pipelined, and the client should honour every signal by copying each file.

The PackageKit backend may support native localisation, which we should support if the translations exist. In the prior examples the SetLocale() method has been left out for brevity. If you are using the raw DBUS methods to access PackageKit, you will also need to make a call to SetLocale() so the daemon knows what locale to assign the transaction. If you are using libpackagekit to schedule transactions, then the locale will be set automatically in the PkControl GObject, and you do not need to call pk_client_set_locale() manually.