1812 lines
58 KiB
XML
1812 lines
58 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
|
|
<chapter id="introduction">
|
|
<title>PackageKit Introduction</title>
|
|
|
|
<sect1 id="introduction-description">
|
|
<title>Overall Description</title>
|
|
|
|
<para>
|
|
PackageKit is a small open source systems abstracts out common package
|
|
management tasks such as:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Checking for updates and installing in the background.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Automatically installing new or add-on software.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
PackageKit is a modular design with an asynchronous API for client programs,
|
|
a flexible queuing module, and run-time selectable backends.
|
|
</para>
|
|
|
|
<mediaobject id="pk-structure">
|
|
<imageobject>
|
|
<imagedata format="PNG" fileref="pk-structure.png" align="center"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</sect1>
|
|
|
|
<sect1 id="introduction-backends">
|
|
<title>Backends</title>
|
|
<para>
|
|
The following sections explain what a backend is, and how it is implemented.
|
|
</para>
|
|
<sect2 id="introduction-backends-overview">
|
|
<title>Overview</title>
|
|
<para>
|
|
A backend is just a compiled <literal>.so</literal> object that is
|
|
loaded at run-time and provides an interface to the underlying package
|
|
commands.
|
|
A backend converts an async request into either a new thread which
|
|
in the same process, or using external "glue" files that can be written
|
|
in any language.
|
|
</para>
|
|
<para>
|
|
Please see the <literal>html/pk-faq.html</literal> file for the current
|
|
status of the existing backends.
|
|
Backend maintainers, please keep this file updated.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-backends-compiled-backends">
|
|
<title>Compiled backends</title>
|
|
<para>
|
|
If you have got a C or C++ binding for your package system then you can
|
|
use a compiled backend, which is more efficient than using helpers as
|
|
described below.
|
|
You can include the headers in the backend (with extra libraries) and
|
|
then just write the simple code to interface with the set methods of
|
|
PackageKit.
|
|
A C example can be found in <literal>backends/box</literal> and a
|
|
C++ example in <literal>backends/apt</literal>.
|
|
</para>
|
|
<para>
|
|
You will have to use threading if your backend does not support async
|
|
operation as requests have to return immediately.
|
|
This is very important. Do any significant processing in a thread, and
|
|
certainly don't return package results without creating a thread.
|
|
By keeping the backends async we can make sure that there is no blocking
|
|
which means the command line and UI do not freeze.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-backends-helpers">
|
|
<title>Backends with helpers</title>
|
|
<para>
|
|
If you do not have a C or C++ language binding PackageKit executes
|
|
helper scripts written in pretty much any language.
|
|
It then watches the standard out and standard error and parses the
|
|
output into compiled backend commands.
|
|
This means a python library can be interfaced easily with a C backend.
|
|
</para>
|
|
<para>
|
|
Even when using helpers, a compiled backend stub is still used for
|
|
two reasons:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It is still needed for the dlopen internally in PackageKit.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
You can add cleverness in the C backend that you might not want to
|
|
do in the scripted backend, for example using a hashtable in C
|
|
rather than checking all the names in awk.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Boilerplate code for common backends can be found in
|
|
<literal>src/pk-backend-language.[c|h]</literal> which eliminates copy
|
|
and paste in the compiled part of the backend.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="introduction-ideas">
|
|
<title>Important Ideas</title>
|
|
<para>
|
|
The following sections explain key concepts used internally in PackageKit.
|
|
</para>
|
|
<sect2 id="introduction-ideas-packageid">
|
|
<title>Package ID</title>
|
|
<para>
|
|
One important idea is the <literal>package_id</literal>.
|
|
This is the <literal>name;version;arch;data</literal> 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.
|
|
</para>
|
|
<para>
|
|
The <literal>package_id</literal> is parsed and checked carefully in
|
|
the helper code.
|
|
The package arch and data is optional, but 3 <literal>;</literal>'s must
|
|
be present.
|
|
For instance, <literal>gnome-keyring-manager;2.18.0;;</literal> is
|
|
valid but <literal>gnome-keyring-manager;2.18.0</literal> 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.
|
|
</para>
|
|
<para>
|
|
The data field for an installed package must be
|
|
<literal>installed</literal> as this is used to identify which packages
|
|
are installable or installed in the client tools.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-ideas-filters">
|
|
<title>Filters</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Filter options are:
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>installed</literal> or <literal>~installed</literal></entry>
|
|
<entry>If the package is installed on the system</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>devel</literal> or <literal>~devel</literal></entry>
|
|
<entry>Development packages typically end -devel, -dgb and -static.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>gui</literal> or <literal>~gui</literal></entry>
|
|
<entry>GUI programs typically depend on gtk, libkde or libxfce.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>free</literal> or <literal>~free</literal></entry>
|
|
|
|
<entry>
|
|
Free software, where the definition of free is given
|
|
by the Free Software Foundation. See
|
|
http://www.fsf.org/licensing/licenses/ for a list of
|
|
free licenses. 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'.
|
|
</entry>
|
|
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
So valid options would be:
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>none</literal></entry>
|
|
<entry>All packages installed or available with no filtering</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>devel;~installed</literal></entry>
|
|
<entry>All non-installed development packages</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>installed;~devel</literal></entry>
|
|
<entry>All installed non-development packages</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>gui;~installed;~devel</literal></entry>
|
|
<entry>All non-installed, non-devel gui programs</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-errors">
|
|
<title>Error Enums</title>
|
|
<para>
|
|
If you have to handle an error, try to use <literal>internal-error</literal>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Every error should have an enumerated type
|
|
(e.g. <literal>out-of-memory</literal>) 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 <literal>;</literal> to separate the lines if
|
|
required.
|
|
</para>
|
|
<para>
|
|
The following error enumerated types are available for use in all
|
|
backends:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Error</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>out-of-memory</literal></entry>
|
|
<entry>There is an out of memory condition</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>no-network</literal></entry>
|
|
<entry>There is no network connection that can be used</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>not-supported</literal></entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>internal-error</literal></entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>gpg-failure</literal></entry>
|
|
<entry>There was a GPG failure in the transaction</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package-id-invalid</literal></entry>
|
|
<entry>The package ID is not valid for this transaction</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package-not-installed</literal></entry>
|
|
<entry>
|
|
The package that is trying to be removed or updated is not
|
|
installed
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>no-cache</literal></entry>
|
|
<entry>
|
|
The operation is trying to read from the cache, but the cache
|
|
is not present or invalid
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package-already-installed</literal></entry>
|
|
<entry>
|
|
The package that is trying to be installed or updated is already
|
|
installed
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package-download-failed</literal></entry>
|
|
<entry>A package failed to download correctly</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>dep-resolution-failed</literal></entry>
|
|
<entry>Dependency resolution failed</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>filter-invalid</literal></entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>create-thread-failed</literal></entry>
|
|
<entry>Failed to create a thread</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>transaction-error</literal></entry>
|
|
<entry>
|
|
There was a generic transaction error, but please give more
|
|
details in the description
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>repo-not-found</literal></entry>
|
|
<entry>The repository name could not be found</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>cannot-remove-system-package</literal></entry>
|
|
<entry>
|
|
Could not remove a protected system package that is needed for
|
|
stable operation of the system
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>process-quit</literal></entry>
|
|
<entry>
|
|
The process was asked to quit, probably because it was cancelled
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>process-kill</literal></entry>
|
|
<entry>
|
|
The process was forcibly killed, probably because ignored the
|
|
quit request. This is probably due to it being cancelled
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-group-type">
|
|
<title>Group type</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The following group enumerated types are available, but please check
|
|
<literal>libpackagekit/pk-enum.h</literal> for the latest list.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Group</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>accessibility</literal></entry>
|
|
<entry>Accessibility</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>accessories</literal></entry>
|
|
<entry>Accessories</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>education</literal></entry>
|
|
<entry>Education</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>games</literal></entry>
|
|
<entry>Games</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>graphics</literal></entry>
|
|
<entry>Graphics</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>internet</literal></entry>
|
|
<entry>Internet</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>office</literal></entry>
|
|
<entry>Office</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>other</literal></entry>
|
|
<entry>Other</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>programming</literal></entry>
|
|
<entry>Programming</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>multimedia</literal></entry>
|
|
<entry>Multimedia</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>system</literal></entry>
|
|
<entry>System</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-cancellation">
|
|
<title>Cancellation</title>
|
|
<para>
|
|
If you have a multipart transaction that can be aborted in one phase but
|
|
not another then the AllowInterrupt 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.
|
|
</para>
|
|
<para>
|
|
By default actions cannot be cancelled unless enabled in the backend.
|
|
Use <literal>AllowInterrupt(true)</literal> to enable cancellation
|
|
and <literal>AllowInterrupt(false)</literal> to disable it.
|
|
This can be done for any job type.
|
|
</para>
|
|
<para>
|
|
For compiled backends that are threaded, the
|
|
<literal>cancel()</literal> method can be used to terminate
|
|
the thread.
|
|
</para>
|
|
<para>
|
|
For spawned backends, there are two staggered signals send to allow
|
|
locks to be released or for the backend to clean up after itself:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Send the process <literal>SIGQUIT</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Wait 500ms</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the process has not already quit, send the process
|
|
<literal>SIGKILL</literal> to terminate it.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="introduction-ideas-transactionid">
|
|
<title>Transaction ID</title>
|
|
<para>
|
|
A <literal>transaction_id</literal> 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 <literal>role</literal> for the entire lifetime,
|
|
but the transaction can different values of <literal>status</literal>
|
|
as the transaction is processed.
|
|
</para>
|
|
<para>
|
|
For example, if the user "Installed OpenOffice" and the backend has to:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
update libxml2 as a dependency
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
install java as dependency
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
install openoffice-bin
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
install openoffice-clipart
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This is one single transaction with the role <literal>install</literal>,
|
|
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.
|
|
</para>
|
|
<para>
|
|
The <literal>transaction_id</literal> must be of the format
|
|
<literal>job;identifier;data</literal> where the daemon controls
|
|
all parameters.
|
|
<literal>job</literal> is a monotonically updating number and is
|
|
retained over reboots.
|
|
<literal>identifier</literal> 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.
|
|
<literal>data</literal> 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 <literal>transaction_id</literal> would be
|
|
<literal>45;dafeca;checkpoint32</literal>
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="config-main">
|
|
<title>Daemon Config Options</title>
|
|
<para>
|
|
The config file <literal>/etc/PackageKit.conf</literal> allows to the
|
|
administrator to change system daemon options.
|
|
In normal use this file does not have to be changed, but it may be
|
|
useful to people debugging the daemon or developing backends.
|
|
</para>
|
|
<para>
|
|
The options are:
|
|
</para>
|
|
<sect3 id="config-main-logging">
|
|
<title>TransactionLogging</title>
|
|
<para>
|
|
This logs all transactions to a database so old transactions can be
|
|
viewed, and rollbacks can be done.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="config-main-timeout">
|
|
<title>ShutdownTimeout</title>
|
|
<para>
|
|
This is the time that the daemon waits when idle before shutting down.
|
|
A smaller number will result in slower response times when running
|
|
many transactions in a small amount of time.
|
|
A longer timeout will lock the underlying packaging backend for longer,
|
|
although the daemon will start and stop less often.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="config-main-default">
|
|
<title>DefaultBackend</title>
|
|
<para>
|
|
The default backend that the daemon should use.
|
|
The default is set at compile time to the
|
|
<literal>--default-backend=</literal> configure setting.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="api-method-reference">
|
|
<title>API Method Reference</title>
|
|
<para>
|
|
Methods used by the backends are as follows:
|
|
</para>
|
|
<sect2 id="api-search-name">
|
|
<title>Search Name</title>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>filter</literal></entry>
|
|
<entry>
|
|
A correct filter, e.g. <literal>none</literal> or
|
|
<literal>installed;~devel</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>search_term</literal></entry>
|
|
<entry>A single word search term with no wildcard chars.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
Do not refresh the package cache. This should be fast.
|
|
</para>
|
|
<para>
|
|
Always emit <literal>installed</literal> before
|
|
<literal>available</literal> packages first, as it allows the client
|
|
program to perform the GUI filtering and matching whilst the daemon is
|
|
running the transaction.
|
|
</para>
|
|
<para>
|
|
The search query in the backend should not be case sensitive, and
|
|
should not be sensitive to <literal>_</literal> or <literal>-</literal>.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-search-group">
|
|
<title>Search Group</title>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>filter</literal></entry>
|
|
<entry>
|
|
A correct filter, e.g. <literal>none</literal> or
|
|
<literal>installed;~devel</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>group_type</literal></entry>
|
|
<entry>An enumerated group_type, or <literal>unknown</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
Do not refresh the package cache. This should be fast.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-search-details">
|
|
<title>Search Details</title>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>filter</literal></entry>
|
|
<entry>
|
|
A correct filter, e.g. <literal>none</literal> or
|
|
<literal>installed;~devel</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>search_term</literal></entry>
|
|
<entry>A single word search term with no wildcard chars.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
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 and URLs.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-search-file">
|
|
<title>Search File</title>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>filter</literal></entry>
|
|
<entry>
|
|
A correct filter, e.g. <literal>none</literal> or
|
|
<literal>installed;~devel</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>search_term</literal></entry>
|
|
<entry>A single word search term with no wildcard chars.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This should search for files.
|
|
This should allow an application to find out what package owns
|
|
a file on the system.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-install-package">
|
|
<title>Install Package</title>
|
|
<para>
|
|
The installer should always install extra packages automatically
|
|
as the use could call GetDepends prior to the install if a confirmation
|
|
is required in the UI.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This should search for files.
|
|
This should allow an application to find out what package owns
|
|
a file on the system.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>downloading</literal>,
|
|
<literal>updating</literal>,
|
|
<literal>installing</literal> or
|
|
<literal>removing</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-install-file">
|
|
<title>Install File</title>
|
|
<para>
|
|
The installer should always install extra packages automatically
|
|
as the use could call GetDepends prior to the install if a confirmation
|
|
is required in the UI.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>full_path</literal></entry>
|
|
<entry>A full path and filename to a single package.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>downloading</literal>,
|
|
<literal>updating</literal>,
|
|
<literal>installing</literal> or
|
|
<literal>removing</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-remove">
|
|
<title>Remove Package</title>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>allow_deps</literal></entry>
|
|
<entry>
|
|
Either "yes" or "no". If yes allow other packages to be
|
|
removed with the package, but "no" should cause the script
|
|
to abort if other packages are dependant on the package.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>downloading</literal>,
|
|
<literal>updating</literal>,
|
|
<literal>installing</literal> or
|
|
<literal>removing</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-depends">
|
|
<title>Get Depends</title>
|
|
<para>
|
|
GetDepends should return packages that this package depends on.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>recursive</literal></entry>
|
|
<entry>
|
|
Either "yes" or "no". 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 GetDepends on
|
|
gnome-power-manager should return both HAL and NetworkManager.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-resolve">
|
|
<title>Resolve</title>
|
|
<para>
|
|
Resolve turns a single package name into a package_id suitable for the
|
|
other methods.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>filter</literal></entry>
|
|
<entry>
|
|
A correct filter, e.g. <literal>none</literal> or
|
|
<literal>installed;~devel</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package</literal></entry>
|
|
<entry>A single package name, e.g. <literal>art-clipart</literal>.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-update-detail">
|
|
<title>Get Update Detail</title>
|
|
<para>
|
|
GetUpdateDetail should return details about the update.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>UpdateDetail</literal> and
|
|
<literal>Error</literal>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-requires">
|
|
<title>Get Requires</title>
|
|
<para>
|
|
GetRequires should return packages that depend on this package.
|
|
This is useful to know, as if <literal>package_id</literal> is being
|
|
removed, we can warn the user what else would be removed.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>recursive</literal></entry>
|
|
<entry>
|
|
Either "yes" or "no". 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.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>available</literal> or <literal>installed</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-description">
|
|
<title>Get Description</title>
|
|
<para>
|
|
GetDescription should return the description of that
|
|
<literal>package_id</literal>.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Description</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-files">
|
|
<title>Get Files</title>
|
|
<para>
|
|
GetFiles should return the file list of that
|
|
<literal>package_id</literal>.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Files</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-update">
|
|
<title>Update Package</title>
|
|
<para>
|
|
The installer should always update extra packages automatically.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A single, valid, package ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
This should search for files.
|
|
This should allow an application to find out what package owns
|
|
a file on the system.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Status</literal> and
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-update-system">
|
|
<title>Update System</title>
|
|
<para>
|
|
There are no arguments.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>RequireRestart</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>downloading</literal>,
|
|
<literal>updating</literal>,
|
|
<literal>installing</literal> or
|
|
<literal>removing</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-updates">
|
|
<title>Get Updates</title>
|
|
<para>
|
|
There are no arguments.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
<para>
|
|
<literal>Package</literal> enumerated types should be
|
|
<literal>blocked</literal>,
|
|
<literal>low</literal>,
|
|
<literal>normal</literal>,
|
|
<literal>important</literal> or
|
|
<literal>security</literal>.
|
|
</para>
|
|
<para>
|
|
The status <literal>blocked</literal> 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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-refresh-cache">
|
|
<title>Refresh Cache</title>
|
|
<para>
|
|
There are no arguments.
|
|
</para>
|
|
<para>
|
|
This 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.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>Progress</literal>,
|
|
<literal>Error</literal> and
|
|
<literal>Package</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-get-repo-list">
|
|
<title>Get Repo List</title>
|
|
<para>
|
|
Return the list of repositories used in the system.
|
|
</para>
|
|
<para>
|
|
There are no arguments.
|
|
</para>
|
|
<para>
|
|
This method typically emits
|
|
<literal>RepoDetail</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="api-repo-enable">
|
|
<title>Repo Enable</title>
|
|
<para>
|
|
This enables the repository specified.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>repo_id</literal></entry>
|
|
<entry>
|
|
A repository identifier, e.g.
|
|
<literal>fedora-development-debuginfo</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>enabled</literal></entry>
|
|
<entry>
|
|
<literal>true</literal> if enabled,
|
|
<literal>false</literal> if disabled.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="api-repo-set-data">
|
|
<title>Repo Set Data</title>
|
|
<para>
|
|
This sets a parameter for the repository specified.
|
|
</para>
|
|
<para>
|
|
The arguments are:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>repo_id</literal></entry>
|
|
<entry>
|
|
A repository identifier, e.g.
|
|
<literal>fedora-development-debuginfo</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>parameter</literal></entry>
|
|
<entry>
|
|
The backend specific value, e.g.
|
|
<literal>set-download-url</literal>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>value</literal></entry>
|
|
<entry>
|
|
The backend specific value, e.g.
|
|
<literal>http://foo.bar.org/baz</literal>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="api-signal-reference">
|
|
<title>API Signal Reference</title>
|
|
<para>
|
|
Signals used by the backends are as follows:
|
|
</para>
|
|
<sect2 id="api-percentage">
|
|
<title>Progress</title>
|
|
<para>
|
|
This is optional.
|
|
Backends should send the percentage fields to 101 if the amount complete
|
|
cannot be calculated.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>percentage</literal></entry>
|
|
<entry>The percentage complete of the entire transaction</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>subpercentage</literal></entry>
|
|
<entry>The subpercentage complete of the sub-transaction</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>elapsed</literal></entry>
|
|
<entry>
|
|
The amount of time in seconds this transaction has been in the
|
|
running state
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>remaining</literal></entry>
|
|
<entry>
|
|
The amount of time in seconds this transaction will take to
|
|
complete. Zero is sent for unknown.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="api-error">
|
|
<title>Error</title>
|
|
<para>
|
|
Errors should only be send on fatal abortion.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>enum</literal></entry>
|
|
<entry>Enumerated type, e.g. <literal>no-network</literal>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>description</literal></entry>
|
|
<entry>
|
|
Long description or error, e.g.
|
|
<literal>failed to connect to mytry.xml</literal>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="api-status">
|
|
<title>Status</title>
|
|
<para>
|
|
This is optional, but highly recommended.
|
|
It gives the GUI tools a chance to show a different icon to show what
|
|
stage the transaction is in, for instance, a downloading icon can be
|
|
shown whilst in the <literal>download</literal> state.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>status</literal></entry>
|
|
<entry>
|
|
One of "<literal>download</literal>",
|
|
"<literal>install</literal>",
|
|
"<literal>update</literal>",
|
|
"<literal>remove</literal>".
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="api-requirerestart">
|
|
<title>RequireRestart</title>
|
|
<para>
|
|
This is optional, but highly recommended.
|
|
</para>
|
|
<para>
|
|
This can be sent as many times as needed by the backend script.
|
|
PackageKit will always choose the 'worst' method in the UI notification.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>type</literal></entry>
|
|
<entry>
|
|
One of "<literal>system</literal>",
|
|
"<literal>application</literal>",
|
|
"<literal>session</literal>".
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>detail</literal></entry>
|
|
<entry>Optional details about the restart</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="api-message">
|
|
<title>Message</title>
|
|
<para>
|
|
This allows the backend to queue up a message to be shown after the
|
|
transaction has completed.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>type</literal></entry>
|
|
<entry>
|
|
One of "<literal>warning</literal>",
|
|
"<literal>notice</literal>",
|
|
"<literal>daemon</literal>".
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>detail</literal></entry>
|
|
<entry>Required details about the message, non localised</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="backends-spawn-package">
|
|
<title>Package</title>
|
|
<para>
|
|
If updating, as packages are updated then emit them to the screen.
|
|
This allows a summary to be presented after the transaction.
|
|
</para>
|
|
<para>
|
|
When returning results from a search always return
|
|
<literal>installed</literal> before <literal>available</literal> for
|
|
the same package name.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>info</literal></entry>
|
|
<entry>A valid <literal>info</literal> string enumerated type</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>A valid package ID string with as much data as known</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>summary</literal></entry>
|
|
<entry>
|
|
The one line package summary, e.g. "Clipart for OpenOffice"
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
The <literal>info</literal> enumerated type
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Situation</entry>
|
|
<entry>Value</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>Searching</entry>
|
|
<entry><literal>installed</literal></entry>
|
|
<entry>If installed</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>available</literal></entry>
|
|
<entry>If available to install</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Getting Updates</entry>
|
|
<entry><literal>low</literal></entry>
|
|
<entry>If update is of low severity</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>normal</literal></entry>
|
|
<entry>If update is of normal severity</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>important</literal></entry>
|
|
<entry>If update is very important</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>security</literal></entry>
|
|
<entry>If the update is security sensitive</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Installing/Updating/Removing</entry>
|
|
<entry><literal>downloading</literal></entry>
|
|
<entry>If we are downloading this package</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>updating</literal></entry>
|
|
<entry>If we are updating this package</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>installing</literal></entry>
|
|
<entry>If we are installing this package</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry><literal>removing</literal></entry>
|
|
<entry>If we are removing this package</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Otherwise</entry>
|
|
<entry><literal>unknown</literal></entry>
|
|
<entry>If we cannot use any other option</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="backends-spawn-description">
|
|
<title>Description</title>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>The package ID</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>license</literal></entry>
|
|
<entry>
|
|
The license, e.g. "GPLv2+" or "proprietary".
|
|
If you need to add a EULA then do it like this:
|
|
"proprietary;By installing this software\nyou may kill a kitten."
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>group</literal></entry>
|
|
<entry>The enumerated package group description</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>detail</literal></entry>
|
|
<entry>
|
|
The multi-line package description.
|
|
NOTE: Tabs may have to be stripped from the description to
|
|
avoid being split.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>url</literal></entry>
|
|
<entry>The upstream project homepage</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>size</literal></entry>
|
|
<entry>
|
|
The size of the package in bytes. This should be the
|
|
size of the entire package file, not the size of the
|
|
files installed on the system.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>file_list</literal></entry>
|
|
<entry>
|
|
A list of all files and directories created by the package
|
|
at install time.
|
|
The list is separated by the <literal>;</literal> character.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="backends-spawn-update-detail">
|
|
<title>UpdateDetail</title>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>package_id</literal></entry>
|
|
<entry>The package ID</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>updates</literal></entry>
|
|
<entry>A list of package_id's that are to be updated</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>obsoletes</literal></entry>
|
|
<entry>A list of package_id's that are to be obsoletes</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>url</literal></entry>
|
|
<entry>
|
|
A URL with more details on the update, e.g. a security advisory
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>restart_enum</literal></entry>
|
|
<entry>A valid restart type, e.g. "system"</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>update_text</literal></entry>
|
|
<entry>
|
|
The update text describing the update in a non-localised way.
|
|
Newlines should be converted to ";" before printed.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
|
|
<sect2 id="backends-spawn-repo-signature-required">
|
|
<title>RepoSignatureRequired</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Option</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>repository_name</literal></entry>
|
|
<entry>
|
|
The name of the repository associated with the provided key
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>key_url</literal></entry>
|
|
<entry>The URL provided with the key.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>key_userid</literal></entry>
|
|
<entry>The user id associated with the key</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>key_id</literal></entry>
|
|
<entry>A unique identifier for the key</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>key_fingerprint</literal></entry>
|
|
<entry>The hashed fingerprint of the key</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>key_timestamp</literal></entry>
|
|
<entry>The date the key was created</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>type</literal></entry>
|
|
<entry>The type of signature used. 'GPG', for example.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</chapter>
|