## org.freedesktop.PackageKit.Transaction

org.freedesktop.PackageKit.Transaction — Transaction interface

## Methods

    SetHints           (in  'as' hints)
    AcceptEula         (in  's'  eula_id)
    Cancel             ()
    DownloadPackages   (in  'b'  store_in_cache,
                        in  'as' package_ids)
    GetCategories      ()
    DependsOn          (in  't'  filter,
                        in  'as' package_ids,
                        in  'b'  recursive)
    GetDetails         (in  'as' package_ids)
    GetDetailsLocal    (in  'as' files)
    GetFilesLocal      (in  'as' files)
    GetFiles           (in  'as' package_ids)
    GetOldTransactions (in  'u'  number)
    GetPackages        (in  't'  filter)
    GetRepoList        (in  't'  filter)
    RequiredBy         (in  't'  filter,
                        in  'as' package_ids,
                        in  'b'  recursive)
    GetUpdateDetail    (in  'as' package_ids)
    GetUpdates         (in  't'  filter)
    GetDistroUpgrades  ()
    InstallFiles       (in  't'  transaction_flags,
                        in  'as' full_paths)
    InstallPackages    (in  't'  transaction_flags,
                        in  'as' package_ids)
    InstallSignature   (in  'u'  sig_type,
                        in  's'  key_id,
                        in  's'  package_id)
    RefreshCache       (in  'b'  force)
    RemovePackages     (in  't'  transaction_flags,
                        in  'as' package_ids,
                        in  'b'  allow_deps,
                        in  'b'  autoremove)
    RepoEnable         (in  's'  repo_id,
                        in  'b'  enabled)
    RepoSetData        (in  's'  repo_id,
                        in  's'  parameter,
                        in  's'  value)
    RepoRemove         (in  't'  transaction_flags,
                        in  's'  repo_id,
                        in  'b'  autoremove)
    Resolve            (in  't'  filter,
                        in  'as' packages)
    SearchDetails      (in  't'  filter,
                        in  'as' values)
    SearchFiles        (in  't'  filter,
                        in  'as' values)
    SearchGroups       (in  't'  filter,
                        in  'as' values)
    SearchNames        (in  't'  filter,
                        in  'as' values)
    UpdatePackages     (in  't'  transaction_flags,
                        in  'as' package_ids)
    WhatProvides       (in  't'  filter,
                        in  'as' values)
    UpgradeSystem      (in  't'  transaction_flags,
                        in  's'  distro_id,
                        in  'u'  upgrade_kind)
    RepairSystem       (in  't'  transaction_flags)

## Signals

    Category              ('s'                    parent_id,
                           's'                    cat_id,
                           's'                    name,
                           's'                    summary,
                           's'                    icon)
    Details               ('a{sv}'                data)
    ErrorCode             ('u'                    code,
                           's'                    details)
    Files                 ('s'                    package_id,
                           'as'                   file_list)
    Finished              ('u'                    exit,
                           'u'                    runtime)
    Package               ('u'                    info,
                           's'                    package_id,
                           's'                    summary)
    Packages              ('a(uss)'               packages)
    RepoDetail            ('s'                    repo_id,
                           's'                    description,
                           'b'                    enabled)
    RepoSignatureRequired ('s'                    package_id,
                           's'                    repository_name,
                           's'                    key_url,
                           's'                    key_userid,
                           's'                    key_id,
                           's'                    key_fingerprint,
                           's'                    key_timestamp,
                           'u'                    type)
    EulaRequired          ('s'                    eula_id,
                           's'                    package_id,
                           's'                    vendor_name,
                           's'                    license_agreement)
    MediaChangeRequired   ('u'                    media_type,
                           's'                    media_id,
                           's'                    media_text)
    RequireRestart        ('u'                    type,
                           's'                    package_id)
    Transaction           ('o'                    object_path,
                           's'                    timespec,
                           'b'                    succeeded,
                           'u'                    role,
                           'u'                    duration,
                           's'                    data,
                           'u'                    uid,
                           's'                    cmdline)
    UpdateDetail          ('s'                    package_id,
                           'as'                   updates,
                           'as'                   obsoletes,
                           'as'                   vendor_urls,
                           'as'                   bugzilla_urls,
                           'as'                   cve_urls,
                           'u'                    restart,
                           's'                    update_text,
                           's'                    changelog,
                           'u'                    state,
                           's'                    issued,
                           's'                    updated)
    UpdateDetails         ('a(sasasasasasussuss)' details)
    DistroUpgrade         ('u'                    type,
                           's'                    name,
                           's'                    summary)
    ItemProgress          ('s'                    id,
                           'u'                    status,
                           'u'                    percentage)
    Destroy               ()

## Implemented Interfaces

org.freedesktop.PackageKit.Transaction implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Properties

    'Role'                  read      'u'
    'Status'                read      'u'
    'LastPackage'           read      's'
    'Uid'                   read      'u'
    'Sender'                read      's'
    'Percentage'            read      'u'
    'AllowCancel'           read      'b'
    'CallerActive'          read      'b'
    'ElapsedTime'           read      'u'
    'RemainingTime'         read      'u'
    'Speed'                 read      'u'
    'DownloadSizeRemaining' read      't'
    'TransactionFlags'      read      't'

## Description

The transaction interface is used for interacting with individual transactions.

## Details

### SetHints ()

    SetHints (in  'as' hints)

This method allows the calling session to set transaction hints for the package manager which can change as the transaction runs.

This method can be sent before the transaction has been run or whilst it is running. There is no limit to the number of times this method can be sent, although some backends may only use the values that were set before the transaction was started.

Each parameter value is optional.

`hints`:

The values as an array of strings, for example ['locale=en_GB.utf8','idle=true','interactive=false','cache-age=3600']. The following parameter values are understood: locale The locale code, for example en_GB. background If the method should be executed as a background task, valid values are true and false, and other values will result in an error. Background tasks are normally treated with a low priority than regular tasks, and normally only use idle CPU and network. interactive If the method can ask interactive questions whilst running, valid values are true and false, and other values will result in an error. cache-age This allows the frontend to set how fresh it needs the metadata used in the transaction. This allows fine control of the age of the returned results, but means the frontend probably has to query the updates check value and pass it this value for GetUpdates, and choose something sane otherwise. Most interactive clients will set this to intmax which means "never download new metadata, unless required to return results". Most transactions will not have this value set. supports-plural-signals This allows the frontend to tell the daemon that it supports the new Packages signal for receiving information about multiple packages at once, rather than just the original Package signal. If this is set, and the daemon supports the signal, it will be used. If present, this must always be set to true. Other values will cause a verbose warning in the daemon, but will not cause the method to fail. This will preserve forward and backwards compatibility for future API versions.

### AcceptEula ()

    AcceptEula (in  's' eula_id)

This method allows the user to accept a end user licence agreement.

`eula_id`: | A valid EULA ID

Callers need the org.freedesktop.packagekit.accept-eula

### Cancel ()

    Cancel ()

This method cancels a transaction that is already running

### DownloadPackages ()

    DownloadPackages (in  'b'  store_in_cache,
                      in  'as' package_ids)

This method downloads packages into a temporary directory.

This method should emit one Files signal for each package that is downloaded, with the file list set as the name of the complete downloaded file and directory, so for example:

DownloadPackages('hal;0.1.2;i386;fedora','hal-info;2009-09-07;no-arch;updates') should send two signals, e.g. Files('hal;0.1.2;i386;fedora', '/tmp/hal-0.1.2.i386.rpm') and Files('hal-info;2009-09-07;no-arch;updates', '/tmp/hal-info-2009-09-07.noarch.rpm').

`store_in_cache`: | If the downloaded files should be stored in the system package cache rather than copied into a newly created directory. See the developer docs for more details on how this is supposed to work.
`package_ids`: | An array of package IDs.

### GetCategories ()

    GetCategories ()

This method return the collection categories

### DependsOn ()

    DependsOn (in  't'  filter,
               in  'as' package_ids,
               in  'b'  recursive)

This method returns packages that this package depends on.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel
`package_ids`: | An array of package IDs.
`recursive`: | Either true or false. If yes then the requirements should be returned for all packages returned. This means if gnome-power-manager depends on NetworkManager and NetworkManager depends on HAL, then DependsOn on gnome-power-manager should return both HAL and NetworkManager.

### GetDetails ()

    GetDetails (in  'as' package_ids)

This method should return all the details about a specific package_id.

This method typically emits Progress, Status and Error and Details.

`package_ids`: | An array of package IDs.

### GetDetailsLocal ()

    GetDetailsLocal (in  'as' files)

This method should return all the details about a specific local file.

This method typically emits Progress, Status and Error and Details.

`files`: | An array of filenames.

### GetFilesLocal ()

    GetFilesLocal (in  'as' files)

This method should return all the file lists for a specific local file.

This method typically emits Progress, Status and Error and Details.

`files`: | An array of filenames.

### GetFiles ()

    GetFiles (in  'as' package_ids)

This method should return the file list of the package_id.

This method typically emits Progress, Status and Error and Files.

`package_ids`: | An array of package IDs.

### GetOldTransactions ()

    GetOldTransactions (in  'u' number)

This method allows a client to view details for old transactions.

`number`: | The number of past transactions, or 0 for all known transactions.

### GetPackages ()

    GetPackages (in  't' filter)

This method returns all the packages without a search term.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

### GetRepoList ()

    GetRepoList (in  't' filter)

This method returns the list of repositories used in the system.

This method should emit RepoDetail.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

### RequiredBy ()

    RequiredBy (in  't'  filter,
                in  'as' package_ids,
                in  'b'  recursive)

This method returns packages that depend on this package. This is useful to know, as if package_id is being removed, we can warn the user what else would be removed.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel
`package_ids`: | An array of package IDs.
`recursive`: | Either true or false. If yes then the requirements should be returned for all packages returned. This means if gnome-power-manager depends on NetworkManager and NetworkManager depends on HAL, then GetRequires on HAL should return both gnome-power-manager and NetworkManager.

### GetUpdateDetail ()

    GetUpdateDetail (in  'as' package_ids)

This method returns details about a specific update.

This method typically emits UpdateDetail and Error

`package_ids`: | An array of package IDs.

### GetUpdates ()

    GetUpdates (in  't' filter)

This method should return a list of packages that are installed and are upgradable. It should only return the newest update for each installed package.

This method typically emits Progress, Error and Package.

Package enumerated types should be blocked, low, normal, important or security.

The status blocked signifies the package cannot be updated, probably due to other dependencies not being met. This type allows the GUI tools to show to the user that an update exists, but cannot be installed. The reason for it not being installed should be put into the update description when doing GetUpdateDetail.

A filter such as basename or gui is also useful if you want to do filtering on the method to only show the main packages rather than the complete list. The complete list is available but specifying none as the filter. Using no filter which may be useful in advanced tools or when using libpackagekit and searching for an update of a specific name. Other filter types may be present, but can be safely ignored of the backend does not support them.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

### GetDistroUpgrades ()

    GetDistroUpgrades ()

This method should return a list of distribution upgrades that are available. It should not return updates, only major upgrades.

This method typically emits DistroUpgrade, Error and

### InstallFiles ()

    InstallFiles (in  't'  transaction_flags,
                  in  'as' full_paths)

This method installs local package files onto the local system.

The installer should always install extra dependant packages automatically.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

`transaction_flags`: | If the transaction is only allowed to install trusted files. Unsigned files should not be installed if this parameter is TRUE. If this method is can only install trusted files, and the files are unsigned, then the backend will send a ErrorCode(missing-gpg-signature).
`full_paths`: | An array of full path and filenames to packages.

Callers need the org.freedesktop.packagekit.localinstall-untrusted

### InstallPackages ()

    InstallPackages (in  't'  transaction_flags,
                     in  'as' package_ids)

This method installs new packages on the local system.

The installer should always install extra packages automatically as the use could call DependsOn prior to the install if a confirmation is required in the UI.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

`transaction_flags`: | If the transaction is only allowed to install trusted packages. Unsigned packages should not be installed if this transaction_flags has ONLY_TRUSTED. If this method is can only install trusted packages, and the packages are unsigned, then the backend will send a ErrorCode(missing-gpg-signature).
`package_ids`: | An array of package IDs.

Callers need the org.freedesktop.packagekit.install-untrusted

### InstallSignature ()

    InstallSignature (in  'u' sig_type,
                      in  's' key_id,
                      in  's' package_id)

This method allows us to install new security keys.

`sig_type`: | A key type enum, e.g. gpg
`key_id`: | A key ID, e.g. BB7576AC
`package_id`: | A PackageID for the package that the user is trying to install

Callers need the org.freedesktop.packagekit.install-signature

### RefreshCache ()

    RefreshCache (in  'b' force)

This method should fetch updated meta-data for all enabled repositories. This operation should be only scheduled when the computer is idle as the network connection will be very active, and will the computer will have have non-trivial levels of hard disk and processor activity. For these reasons, it should not be done automatically when on battery power.

When fetching each software repository, ensure to emit RepoDetail for the current repository to give the user interface some extra details. Be sure to have the "enabled" field set to true, otherwise you wouldn't be fetching that repository.

This method typically emits Progress, Error and RepoDetail.

`force`: | If the caches should be cleaned and reloaded even if there is valid, up to date data.

Callers need the org.freedesktop.packagekit.refresh-cache

### RemovePackages ()

    RemovePackages (in  't'  transaction_flags,
                    in  'as' package_ids,
                    in  'b'  allow_deps,
                    in  'b'  autoremove)

This method removes packages from the local system.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be downloading, updating, installing or removing.

`transaction_flags`: | If the transaction should be simulated or prepared.
`package_ids`: | An array of package IDs.
`allow_deps`: | Either true or false. If true allow other packages to be removed with the package, but false should cause the script to abort if other packages are dependant on the package.

`autoremove`:

Either true or false. This option is only really interesting on embedded devices with a limited amount of flash storage. It suggests to the packagekit backend that dependencies installed at the same time as the package should also be removed if they are not required by anything else. For instance, if you install OpenOffice, it might download libneon as a dependency. When auto_remove is set to true, and you remove OpenOffice then libneon will also get removed automatically.

Callers need the org.freedesktop.packagekit.remove

### RepoEnable ()

    RepoEnable (in  's' repo_id,
                in  'b' enabled)

This method enables the repository specified.

`repo_id`: | A repository identifier, e.g. fedora-development-debuginfo
`enabled`: | true if enabled, false if disabled.

Callers need the org.freedesktop.packagekit.repo-change

### RepoSetData ()

    RepoSetData (in  's' repo_id,
                 in  's' parameter,
                 in  's' value)

This method allows arbitary data to be passed to the repository handler.

`repo_id`: | A repository identifier, e.g. fedora-development-debuginfo
`parameter`: | The backend specific value, e.g. set-download-url.
`value`: | The backend specific value, e.g. http://foo.bar.org/baz.

Callers need the org.freedesktop.packagekit.repo-change

### RepoRemove ()

    RepoRemove (in  't' transaction_flags,
                in  's' repo_id,
                in  'b' autoremove)

This method removes the repo and optionally removes all the packages installed from the repo.

`transaction_flags`: | If the transaction should be simulated.
`repo_id`: | A repository identifier, e.g. updates-testing
`autoremove`: | Packages installed from the repo are automatically removed.

Callers need org.freedesktop.packagekit.repo-change

### Resolve ()

    Resolve (in  't'  filter,
             in  'as' packages)

This method turns a single package name into a package_id suitable for the other methods.

If the package is a fully formed package_id, then this should be treated as an exact package match. This is useful to find the summary or installed status of a package_id returned from other methods.

This method typically emits Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

`packages`:

An array of package names, e.g. scribus-clipart. The package names are case sensitive, so for instance: Resolve('Packagekit') would not match PackageKit. As a special case, if Resolve() is called with a name prefixed with @ then this should be treated as a category, for example: @web-development. In this instance, a meta-package should be emitted, for example: web-development;;;meta with the correct installed status and summary for the category.

### SearchDetails ()

    SearchDetails (in  't'  filter,
                   in  'as' values)

This method allows deeper searching than SearchName().

Do not refresh the package cache. This should be fast. This is very similar to search-name. This should search as much data as possible, including, if possible repo names, package summaries, descriptions, licenses and URLs.

Try to emit installed before available packages first, as it allows the client program to perform the GUI filtering and matching whilst the daemon is running the transaction.

If the backend includes installed and available versions of the same package when searching then the available version will have to be filtered in the backend.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel
`values`: | A single word search term with no wildcard chars. The search can contain many words separated by spaces. In this case, the search operator is AND and the words can be found in any details section/field. For example, search of GPL games should returns every games with a GPL license. The search should not be treated as case sensitive.

### SearchFiles ()

    SearchFiles (in  't'  filter,
                 in  'as' values)

This method searches for files on the local system and files in available packages.

This should search for files. This should allow an application to find out what package owns a file on the system.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

`values`:

A filename or fully qualified path and filename on the system. If the search term begins with a / it will be assumed the entire path has been given and only packages that contain this exact path and filename will be returned. If the search term does not start with / then it should be treated as a single filename, which can be in any directory. The search is case sensitive, and should not be escaped or surrounded in quotes.

### SearchGroups ()

    SearchGroups (in  't'  filter,
                  in  'as' values)

This method returns packages from a given group enumerated type.

Do not refresh the package cache. This should be fast.

Try to emit installed before available packages first, as it allows the client program to perform the GUI filtering and matching whilst the daemon is running the transaction.

If the backend includes installed and available versions of the same package when searching then the available version will have to be filtered in the backend.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel

`values`:

An enumerated group type, or unknown. The search cannot contain spaces. The following recommendations are made below: If the values strings are prefixed with category: then the request is treated as a 'category search', for example: category:web-development. If the values strings are prefixed with repo: then the request is treated as a 'repository search', for example: repo:fedora-debuginfo. In this instance all packages that were either installed from, or can be installed from the fedora-debuginfo repository would be returned.

### SearchNames ()

    SearchNames (in  't'  filter,
                 in  'as' values)

This method searches the package database by package name.

Do not refresh the package cache. This should be fast.

Try to emit installed before available packages first, as it allows the client program to perform the GUI filtering and matching whilst the daemon is running the transaction.

If the backend includes installed and available versions of the same package when searching then the available version will have to be filtered in the backend.

The search methods should return all results in all repositories. This may mean that multiple versions of package are returned. If this is not what is wanted by the client program, then the newest filter should be used.

This method typically emits Progress, Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel
`values`: | A single word search term with no wildcard chars. The search term can contain many words separated by spaces. In this case, the search operator is AND. For example, search of gnome power should returns gnome-power-manager but not gnomesword or powertop. The search should not be treated as case sensitive.

### UpdatePackages ()

    UpdatePackages (in  't'  transaction_flags,
                    in  'as' package_ids)

This method updates existing packages on the local system.

The installer should always update extra packages automatically to fulfil dependencies.

This should allow an application to find out what package owns a file on the system.

This method typically emits Progress, Status and Error and Package.

`transaction_flags`: | If the transaction is only allowed to update to trusted packages. Unsigned packages should not be installed if this transaction_flags has ONLY_TRUSTED. If this method is can only update trusted packages, and the packages are unsigned, then the backend will send a ErrorCode(missing-gpg-signature).
`package_ids`: | An array of package IDs.

Callers need the org.freedesktop.packagekit.update-package

### WhatProvides ()

    WhatProvides (in  't'  filter,
                  in  'as' values)

This method returns packages that provide the supplied attributes. This method is useful for finding out what package(s) provide a modalias or GStreamer codec string.

This method typically emits Progress, Status and Error and Package.

Package enumerated types should be available or installed.

`filter`: | A correct filter bitfield, e.g. none or installed;~devel
`values`: | The data to send to the backend to get the packages. Note: This is backend specific.

### UpgradeSystem ()

    UpgradeSystem (in  't' transaction_flags,
                   in  's' distro_id,
                   in  'u' upgrade_kind)

This method perfoms a distribution upgrade to the specified version.

This method typically emits Progress, Status and Error and Package.

`transaction_flags`: | If this method is can only install trusted files, and the files are unsigned, then the backend will send a ErrorCode(missing-gpg-signature).
`distro_id`: | The distribution ID to upgrade to, e.g. fedora-14.
`upgrade_kind`: | The type of upgrade, e.g. minimal, default or complete. Minimal upgrades will download the smallest amount of data before launching a installer. The default is to download enough data to launch a full graphical installer, but a complete upgrade will be required if there is no internet access during install time.

### RepairSystem ()

    RepairSystem (in  't' transaction_flags)

This method recovers the package management system from e.g. unsatisfied dependencies of installed packages.

This method typically emits Progress, Status and Error and Package.

`transaction_flags`: | If the transaction is only allowed to install trusted packages. Unsigned packages should not be installed if this transaction_flags has ONLY_TRUSTED. If this method is can only install trusted packages, and the packages are unsigned, then the backend will send a ErrorCode(missing-gpg-signature).

## Signal Details

### The Category signal

    Category ('s' parent_id,
              's' cat_id,
              's' name,
              's' summary,
              's' icon)

This signal send information about a collection category

`parent_id`: | The parent identifier, e.g. applications. If the category is a root entry, use a blank parent.

`cat_id`:

The category identifier, e.g. applications;system-tools. The identifier does not have to be related to the parent_id in any way. A menu tree is made from multiple Category signals. The tree does not have any depth or bredth limits, although it should be kept to less than about 100 entries as this will be shown to the user in a menu. The cat_id will be sent as a parameter to SearchGroup so you may have to prefix or otherwise identify the ID to not confuse the search method.

`name`: | The localised name of the category, e.g. System Tools.
`summary`: | The localised category summary, e.g. Tools for mangaing system state. This is not normally shown in the menus, but may be shown in helper popups.
`icon`: | The icon name for the category, e.g. server-cfg. If the icon is not known, then it should be set to image-missing.

### The Details signal

    Details ('a{sv}' data)

This signal allows the backend to convey more details about the package.

`data`:

The details about a specific package. The available keys are here: package_id The package ID [s] license The license string, e.g. GPLv2+ [s] group The enumerated package group description [u] detail The multi-line package description in markdown syntax.[s] url The upstream project homepage [s] size The size of the package in bytes [t] summary The one line package summary, e.g. Clipart for OpenOffice [s]

### The ErrorCode signal

    ErrorCode ('u' code,
               's' details)

This signal is used to report errors back to the session program.

Errors should only be send on fatal abort.

`code`: | Enumerated type, e.g. no-network.
`details`: | Long description or error, e.g. failed to connect to mytry.xml

### The Files signal

    Files ('s'  package_id,
           'as' file_list)

This signal is used to push file lists from the backend to the session.

`package_id`: | The Package ID that called the method.
`file_list`: | The file list as an array.

### The Finished signal

    Finished ('u' exit,
              'u' runtime)

This signal is used to signal that the transaction has finished.

`exit`: | The PkExitEnum describing the exit status of the transaction.
`runtime`: | The amount of time in milliseconds that the transaction ran for.

### The Package signal

    Package ('u' info,
             's' package_id,
             's' summary)

This signal allows the backend to communicate packages to the session.

If updating, as packages are updated then emit them to the screen. This allows a summary to be presented after the transaction.

When returning results from a search always return installed before available for the same package name.

`info`: | A valid info enumerated type

`package_id`:

This identifier is of the form name;version;arch;data in a single string and is meant to represent a single package unique across all local and remote data stores. For a remote, not-installed package the data field should be set as the repository identifier or repository name. The data field for an installed package must be prefixed with installed as this is used to identify which packages are installable or installed in the client tools. As a special extension, if the package manager is able to track which repository a package was originally installed from, then the data field can be set to installed:REPO-NAME which allows the frontend client to advise the user of the package origin. The data field for a non-installed local package must be local as this signifies a repository name is not available and that package resides locally on the client system rather than in any specific repository.

`summary`: | The one line package summary, e.g. Clipart for OpenOffice

### The Packages signal

    Packages ('a(uss)' packages)

This signal allows the backend to communicate multiple packages to the session.

If updating, as packages are updated then emit them to the screen. This allows a summary to be presented after the transaction.

When returning results from a search always return installed before available for the same package name.

This signal was added to the API in PackageKit 1.2.6. It will only be emitted by the daemon if the client sets the supports-plural-signals=true hint on the transaction using SetHints().

Even if this signal is used by the transaction, it may also still emit Package signals at other times. The content of one signal will never duplicate the content of another. Clients must be prepared to handle both signals within the same transaction.

`packages`: | An array of package details. Each array element is one package, as documented for the Package signal.

### The RepoDetail signal

    RepoDetail ('s' repo_id,
                's' description,
                'b' enabled)

This signal describes a repository on the system.

`repo_id`: | The repository ID.
`description`: | A description of the repository.
`enabled`: | If the repository is enabled and in use.

### The RepoSignatureRequired signal

    RepoSignatureRequired ('s' package_id,
                           's' repository_name,
                           's' key_url,
                           's' key_userid,
                           's' key_id,
                           's' key_fingerprint,
                           's' key_timestamp,
                           'u' type)

This signal is emitted when a transaction is not possible due to a missing security certificate.

Some backends support repositories which use a cryptographic signature, such as GPG. If a package cannot be installed because it is signed with a key that has not been verified, this signal is generated so the user can choose to accept or decline the key.

This signal includes information that can be used to verify that the key should be trusted, such as a URL for the company or person who owns the key, the key's ID, the userid of the key creator, and the date the key was generated.

`package_id`: | A package ID for the package that is trying to be installed
`repository_name`: | The name of the repository associated with the provided key.
`key_url`: | The URL provided with the key.
`key_userid`: | The user id associated with the key.
`key_id`: | A unique identifier for the key.
`key_fingerprint`: | The hashed fingerprint of the key.
`key_timestamp`: | The date the key was created.
`type`: | The type of signature used. gpg, for example.

### The EulaRequired signal

    EulaRequired ('s' eula_id,
                  's' package_id,
                  's' vendor_name,
                  's' license_agreement)

This signal is emitted when a transaction is not possible due to a EULA that needs to be agreed to at install time.

Some backends support EULAs, which have to be agreed to before the install can proceed.

`eula_id`: | The eula_id which identifies the EULA - this is provided so that if a specific EULA has previously agreed to a EULA from Acme Corp it is not asked again. An example eula_id's is vmware5_single_user.
`package_id`: | A package ID for the package that is trying to be installed.
`vendor_name`: | The vendor that is providing the EULA.
`license_agreement`: | The full text EULA.

### The MediaChangeRequired signal

    MediaChangeRequired ('u' media_type,
                         's' media_id,
                         's' media_text)

This signal is emitted when a transaction needsneeds a different media to grab the packages.

Some backends support Media changing, which will fail the transaction each time it needs a new media.

`media_type`: | Enumerated type, e.g. dvd.
`media_id`: | The media_id which identifies the Media - this is provided so that if DeviceKit or another program is able to identify the right media before continuing, note however that it's not the DeviceKit oblication to check the media when the transaction is re-scheduled this is the backend task. An example media_id's is Debian testing amd64 Bin-1.
`media_text`: | Might be used for the disk label too, something like Fedora Disk 1

### The RequireRestart signal

    RequireRestart ('u' type,
                    's' package_id)

This signal is sent when the session program should notify the user that a restart is required.

This is optional, but highly recommended.

This can be sent as many times as needed by the backend script. PackageKit will always choose the 'worst' method in the UI notification.

`type`: | One of system, application or session.
`package_id`: | The package ID that caused the restart notifier.

### The Transaction signal

    Transaction ('o' object_path,
                 's' timespec,
                 'b' succeeded,
                 'u' role,
                 'u' duration,
                 's' data,
                 'u' uid,
                 's' cmdline)

This signal is sent when more details are required about a specific transaction.

`object_path`: | The transaction ID of the old transaction.
`timespec`: | The timespec of the old transaction in ISO8601 format.
`succeeded`: | If the transaction succeeded.
`role`: | The role enumerated type.
`duration`: | The duration of the transaction in milliseconds.
`data`: | Any data associated with the transaction.
`uid`: | The user ID of the user that scheduled the action.
`cmdline`: | The command line of the tool that scheduled the action, e.g. /usr/bin/gpk-application.

### The UpdateDetail signal

    UpdateDetail ('s'  package_id,
                  'as' updates,
                  'as' obsoletes,
                  'as' vendor_urls,
                  'as' bugzilla_urls,
                  'as' cve_urls,
                  'u'  restart,
                  's'  update_text,
                  's'  changelog,
                  'u'  state,
                  's'  issued,
                  's'  updated)

This signal is sent when more details are required about a specific update.

`package_id`: | The package ID
`updates`: | A list of package_id's that are to be updated.
`obsoletes`: | A list of package_id's that are to be obsoleted.
`vendor_urls`: | A list of URLs with more details on the update, e.g. a page with more information on the update.
`bugzilla_urls`: | A list of bugzilla URL with more details on the update. If no URLs are available then this field should be left empty.
`cve_urls`: | A list of CVE URLs with more details on the security advisory.
`restart`: | A valid restart type, e.g. system.
`update_text`: | The update text describing the update. If formatting is required, then markdown syntax should be used, e.g. This is **critically** important
`changelog`: | The ChangeLog text describing the changes since the last version.
`state`: | The state of the update, e.g. stable or testing.
`issued`: | The ISO8601 encoded date that the update was issued.
`updated`: | The ISO8601 encoded date that the update was updated.

### The UpdateDetails signal

    UpdateDetails ('a(sasasasasasussuss)' details)

This signal allows the backend to communicate specific details for multiple updates to the session. It is equivalent to the sequential emission of N UpdateDetail signals.

This signal was added to the API in PackageKit 1.2.6. It will only be emitted by the daemon if the client sets the supports-plural-signals=true hint on the transaction using SetHints().

Even if this signal is used by the transaction, it may also still emit UpdateDetail signals at other times. The content of one signal will never duplicate the content of another. Clients must be prepared to handle both signals within the same transaction.

`details`: | An array of update details. Each array element is one update, as documented for the UpdateDetail signal.

### The DistroUpgrade signal

    DistroUpgrade ('u' type,
                   's' name,
                   's' summary)

This signal allows the backend to communicate distribution upgrades to the session.

`type`: | A valid upgrade enumerated type, e.g. stable or unstable
`name`: | The short name of the distribution, e.g. Fedora Core 10 RC1
`summary`: | The multi-line description of the release.

### The ItemProgress signal

    ItemProgress ('s' id,
                  'u' status,
                  'u' percentage)

This signal allows the backend to send infomation about package or repository progress when using Simultanous mode.

`id`: | A valid package_id, e.g. hal;0.1.0;i386;fedora or a repo_id. A repo_id may only be used when running RefreshCache.
`status`: | The status enumerated value that is being completed.
`percentage`: | The percentage of this package action is completed.

### The Destroy signal

    Destroy ()

This signal is sent when the transaction has been destroyed and is no longer available for use.

## Property Details

### The "Role" property

    'Role'  read      'u'

The transaction role enum, e.g. update-system.

### The "Status" property

    'Status'  read      'u'

The transaction status enum, e.g. downloading.

### The "LastPackage" property

    'LastPackage'  read      's'

The last package_id that was processed, e.g. hal;0.1.2;i386;fedora.

### The "Uid" property

    'Uid'  read      'u'

The uid of the user that started the transaction.

### The "Sender" property

    'Sender'  read      's'

The D-Bus name of the process that started the transaction.

### The "Percentage" property

    'Percentage'  read      'u'

The percentage complete of the transaction.

Backends should set this value to 101 if the amount complete cannot be calculated.

### The "AllowCancel" property

    'AllowCancel'  read      'b'

If the transaction can be cancelled.

### The "CallerActive" property

    'CallerActive'  read      'b'

If the original caller of the method is still connected to the system bus. This is usually an indication that the client can handle it's own error handling and EULA callbacks rather than another program taking over.

### The "ElapsedTime" property

    'ElapsedTime'  read      'u'

The amount of time elapsed during the transaction in seconds.

### The "RemainingTime" property

    'RemainingTime'  read      'u'

The estimated time remaining of the transaction in seconds, or 0 if not known.

### The "Speed" property

    'Speed'  read      'u'

The estimated speed of the transaction (copying, downloading, etc.) in bits per second, or 0 if not known.

### The "DownloadSizeRemaining" property

    'DownloadSizeRemaining'  read      't'

The number of bytes remaining to download, 0 if nothing is left to download.

### The "TransactionFlags" property

    'TransactionFlags'  read      't'

The flags set for this transaction, e.g. SIMULATE or ONLY_DOWNLOAD.