The following sections explain key concepts used internally in PackageKit. One important idea is the package_id. This is the name;version;arch;data in a single string and is meant to represent a single package. This is important when multiple versions of a package are installed and only the correct one is removed. The package_id is parsed and checked carefully in the helper code. The package arch and data is optional, but 3 ;'s must be present. For instance, gnome-keyring-manager;2.18.0;; is valid but gnome-keyring-manager;2.18.0 is not. The data field can be used for the repository name or any other purpose. It is designed to make the life of a backend writer a little bit easier. The data field for an installed package must be installed as this is used to identify which packages are installable or installed in the client tools. The backend must ensure that the package_id only matches on one single package. A single package_id must be enough to uniquely identify a single object in any repository used on the system. Search filtering on the name is done in the backend for efficiency reasons. This can be added into the compiled backend if this is not possible in any new backend design. Filter options are: Option Description installed or ~installed If the package is installed on the system devel or ~devel Development packages typically end -devel, -dgb and -static. gui or ~gui GUI programs typically depend on gtk, libkde or libxfce. free or ~free Free software. The package contains only software and other content that is available under a free license. See http://fedoraproject.org/wiki/Licensing for a list of licenses that are considered free. If a license cannot be determined from the package metadata, or the status of the license is not known, the package will be marked as 'non-free'. visible or ~visible Repositories may want to specify if a package should be visible in an application chooser. supported or ~supported If the package is supported or is a third party addon. basename or ~basename The basename filter will only return results according to the package basename. This is useful if you are searching for pm-utils and you only want to show the main pm-utils package, not any of the -devel or -debuginfo or -common suffixes in the UI. The basename is normally the original name of the source package. So valid options would be: Option Description none All packages installed or available with no filtering devel;~installed All non-installed development packages installed;~devel All installed non-development packages gui;~installed;~devel All non-installed, non-devel gui programs If you have to handle an error, try to use internal-error as little as possible. Just ask on the mailing list, and we can add some more error enums to cover the type of error in an abstract way as possible. Every error should have an enumerated type (e.g. out-of-memory) and also an error description. The error description is not translated and not converted into the users locale. The error description should be descriptive, as it's for power users and people trying to debug the problem. For instance, "Out of memory" is not helpful as an error description that is reported in a bugzilla, but "Could not create database index" is. For the description use ; to separate the lines if required. The following error enumerated types are available for use in all backends: Error Description out-of-memory There is an out of memory condition no-network There is no network connection that can be used not-supported Not supported by the backend. NOTE: You shouldn't be setting non-NULL in the compiled backend symbol table if you find yourself using this. internal-error There was an unspecified internal error. NOTE: Please try and be more specific. If you are using this then we should probably add a new type. gpg-failure There was a GPG failure in the transaction package-id-invalid The package ID is not valid for this transaction package-not-installed The package that is trying to be removed or updated is not installed no-cache The operation is trying to read from the cache, but the cache is not present or invalid package-already-installed The package that is trying to be installed or updated is already installed package-download-failed A package failed to download correctly dep-resolution-failed Dependency resolution failed filter-invalid The filter was invalid. NOTE: syntax checking is done in the backend loader, so you should only use this if the filter is not supported by the backend. create-thread-failed Failed to create a thread transaction-error There was a generic transaction error, but please give more details in the description repo-not-found The repository name could not be found cannot-remove-system-package Could not remove a protected system package that is needed for stable operation of the system process-quit The process was asked to quit, probably because it was cancelled process-kill The process was forcibly killed, probably because ignored the quit request. This is probably due to it being cancelled Groups are enumerated for localisation. Backends should try to put packages in different groups if possible, else just don't advertise SearchGroup and the options should not be shown in the UI. The following group enumerated types are available, but please check libpackagekit/pk-enum.h for the latest list. Group Description accessibility Accessibility accessories Accessories education Education games Games graphics Graphics internet Internet office Office other Other programming Programming multimedia Multimedia system System If you have a multipart transaction that can be aborted in one phase but not another then the AllowCancel signal can be sent. This allows for example the yum download to be cancelled, but not the install transaction. By cancelling a job all subtransactions are killed. By default actions cannot be cancelled unless enabled in the backend. Use AllowCancel(true) to enable cancellation and AllowCancel(false) to disable it. This can be done for any job type. For compiled backends that are threaded, the cancel() method can be used to terminate the thread. For spawned backends, there are two staggered signals send to allow locks to be released or for the backend to clean up after itself: Send the process SIGQUIT. Wait 500ms If the process has not already quit, send the process SIGKILL to terminate it. A transaction_id is a unique identifier that identifies the present or past transaction. A transaction is made up of one or more sub-transactions. A transaction has one role for the entire lifetime, but the transaction can different values of status as the transaction is processed. For example, if the user "Installed OpenOffice" and the backend has to: update libxml2 as a dependency install java as dependency install openoffice-bin install openoffice-clipart This is one single transaction with the role install, with 4 different sub-transactions. This allows the user to rollback transactions with selected backends, rather than select sub-transactions which may need complex conflict resolution. The transaction_id must be of the format job;identifier;data where the daemon controls all parameters. job is a monotonically updating number and is retained over reboots. identifier is random data used by the daemon to ensure jobs started in parallel cannot race, and also to make a malicious client program harder to write. data can be used for ref-counting in the backend or for any other purpose. It is designed to make the life of a backend writer a little bit easier. An example transaction_id would be 45;dafeca;checkpoint32