Debian Codegraph @

docs/api/spec/pk-concepts.xml

raw
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
3
4 <chapter id="concepts">
5 <title>Important Concepts</title>
6 <para>
7 The following sections explain key concepts used internally in PackageKit.
8 </para>
9 <sect1 id="introduction-ideas-packageid">
10 <title>Package ID</title>
11 <para>
12 One important idea is the <literal>package_id</literal>.
13 This is the <literal>name;version;arch;data</literal> in
14 a single string and is meant to represent a single package.
15 This is important when multiple versions of a package are installed and
16 only the correct one is removed.
17 </para>
18 <para>
19 The <literal>package_id</literal> is parsed and checked carefully in
20 the helper code.
21 The package arch and data are optional, but 3 <literal>;</literal>'s must
22 be present.
23 For instance, <literal>gnome-keyring-manager;2.18.0;;</literal> is
24 valid but <literal>gnome-keyring-manager;2.18.0</literal> is not.
25 The data field is used for the repository name and/or installation state.
26 It should ideally not be parsed by frontends to extract state data, instead the
27 <code>PkInfoEnum</code> that is often provided alongside a <literal>package_id</literal>
28 will provide more accurate state information.
29 </para>
30 <para>
31 The data field for an installed package can either be
32 <literal>installed</literal> for installed packages, <literal>auto</literal>
33 for automatically installed packages or <literal>manual</literal> for manually
34 installed packages. If the package has a repository origin, the installation state may be
35 prefixed to the origin, divided by a colon, e.g. <literal>auto:fedora-devel</literal>.
36 If a package is not installed, the data field is equal to the package origin.
37 </para>
38 <para>
39 The data field for an non-installed local package must be
40 <literal>local</literal> as this signifies a repository name is not available
41 and that package resides locally on the client system.
42 </para>
43 <para>
44 For example:
45 </para>
46 <itemizedlist>
47 <listitem>
48 <para>
49 <literal>csup;20060318-5;x86_64;local</literal>: for locally available package file.
50 </para>
51 </listitem>
52 <listitem>
53 <para>
54 <literal>csup;20060318-5;x86_64;fedora-devel</literal>: for package that is not installed
55 and can be downladed from the Fedora development repostory.
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 <literal>csup;20060318-5;x86_64;installed:fedora-devel</literal>: for locally installed package
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 <literal>csup;20060318-5;x86_64;installed</literal>: for locally installed package without repository information
66 </para>
67 </listitem>
68 </itemizedlist>
69 <informaltable>
70 <tgroup cols="3">
71 <thead>
72 <row>
73 <entry>Situation</entry>
74 <entry>Value</entry>
75 <entry>Description</entry>
76 </row>
77 </thead>
78 <tbody>
79 <row>
80 <entry>Searching</entry>
81 <entry><literal>installed</literal></entry>
82 <entry>If installed</entry>
83 </row>
84 <row>
85 <entry></entry>
86 <entry><literal>available</literal></entry>
87 <entry>If available to install</entry>
88 </row>
89 <row>
90 <entry>Getting Updates</entry>
91 <entry><literal>low</literal></entry>
92 <entry>If update is of low severity</entry>
93 </row>
94 <row>
95 <entry></entry>
96 <entry><literal>normal</literal></entry>
97 <entry>If update is of normal severity</entry>
98 </row>
99 <row>
100 <entry></entry>
101 <entry><literal>important</literal></entry>
102 <entry>If update is very important</entry>
103 </row>
104 <row>
105 <entry></entry>
106 <entry><literal>security</literal></entry>
107 <entry>If the update is security sensitive</entry>
108 </row>
109 <row>
110 <entry>Installing/Updating/Removing</entry>
111 <entry><literal>downloading</literal></entry>
112 <entry>If we are downloading this package</entry>
113 </row>
114 <row>
115 <entry></entry>
116 <entry><literal>updating</literal></entry>
117 <entry>If we are updating this package</entry>
118 </row>
119 <row>
120 <entry></entry>
121 <entry><literal>installing</literal></entry>
122 <entry>If we are installing this package</entry>
123 </row>
124 <row>
125 <entry></entry>
126 <entry><literal>removing</literal></entry>
127 <entry>If we are removing this package</entry>
128 </row>
129 <row>
130 <entry>Otherwise</entry>
131 <entry><literal>unknown</literal></entry>
132 <entry>If we cannot use any other option</entry>
133 </row>
134 </tbody>
135 </tgroup>
136 </informaltable>
137 <para>
138 The backend must ensure that the package_id only matches on one
139 single package.
140 A single package_id must be enough to uniquely identify a single object
141 in any repository used on the system.
142 </para>
143 </sect1>
144
145 <sect1 id="introduction-ideas-filters">
146 <title>Filters</title>
147 <para>
148 Search filtering on the name is done in the backend for efficiency reasons.
149 This can be added into the compiled backend if this is not possible
150 in any new backend design.
151 </para>
152 <para>
153 Filter options are:
154 </para>
155 <informaltable>
156 <tgroup cols="2">
157 <thead>
158 <row>
159 <entry>Option</entry>
160 <entry>Description</entry>
161 </row>
162 </thead>
163 <tbody>
164 <row>
165 <entry><literal>installed</literal> or <literal>~installed</literal></entry>
166 <entry>
167 If the package is currently installed.
168 Packages returned with the <literal>~installed</literal> filter set
169 are available in remote software sources.
170 </entry>
171 </row>
172 <row>
173 <entry><literal>devel</literal> or <literal>~devel</literal></entry>
174 <entry>
175 Development packages are typically not required for normal operation
176 and typically have the suffixes -devel, -dgb and -static.
177 </entry>
178 </row>
179 <row>
180 <entry><literal>gui</literal> or <literal>~gui</literal></entry>
181 <entry>
182 GUI programs typically depend on gtk, libkde or libxfce.
183 </entry>
184 </row>
185 <row>
186 <entry><literal>application</literal> or <literal>~application</literal></entry>
187 <entry>
188 Packages that provide desktop files and are probably applications.
189 </entry>
190 </row>
191 <row>
192 <entry><literal>free</literal> or <literal>~free</literal></entry>
193 <entry>
194 Free software. The package contains only software and
195 other content that is available under a free license.
196 See the <ulink url="http://fedoraproject.org/wiki/Licensing">Fedora wiki</ulink>
197 for a list of licenses that are considered free.
198 If a license cannot be determined from the package metadata, or the
199 status of the license is not known, the package will be marked as 'non-free'.
200 </entry>
201 </row>
202 <row>
203 <entry><literal>visible</literal> or <literal>~visible</literal></entry>
204 <entry>
205 Repositories may want to specify if a package should be visible
206 in an application chooser.
207 This is only really useful for embedded environments where the
208 package list is manually chosen.
209 </entry>
210 </row>
211 <row>
212 <entry><literal>supported</literal> or <literal>~supported</literal></entry>
213 <entry>
214 If the package is supported by the distribution or retailer or is a
215 unsupported third party package.
216 </entry>
217 </row>
218 <row>
219 <entry><literal>basename</literal> or <literal>~basename</literal></entry>
220 <entry>
221 The basename filter will only return results according to the
222 package basename.
223 This is useful if you are searching for pm-utils and you only
224 want to show the main pm-utils package, not any of the
225 <literal>-devel</literal> or <literal>-debuginfo</literal> or
226 <literal>-common</literal> suffixes in the UI.
227 The basename is normally the original name of the source package.
228 </entry>
229 </row>
230 <row>
231 <entry><literal>newest</literal> or <literal>~newest</literal></entry>
232 <entry>
233 <para>
234 The newest filter will only return the newest package available.
235 This is useful if you are searching for <literal>gimp</literal>
236 and only <literal>gimp-2.4.5-1.fc9.i386</literal> would be returned,
237 not <literal>gimp-2.4.5-1.fc9.i386</literal>,
238 <literal>gimp-2.4.4-1.fc9.i386</literal> and
239 <literal>gimp-2.4.3-1.fc9.i386</literal>.
240 </para>
241 <para>
242 <emphasis>NOTE:</emphasis>
243 The <literal>newest</literal> filter processes installed and available
244 package lists separately and so the <literal>installed</literal> or
245 <literal>~installed</literal> filter also has to be specified if only one type of
246 results are required.
247 There is no way to do a <literal>newest</literal> filter across both
248 installed and available packages.
249 </para>
250 </entry>
251 </row>
252 <row>
253 <entry><literal>arch</literal> or <literal>~arch</literal></entry>
254 <entry>
255 The arch filter will only return the packages that match the exact architecture
256 of the system, for instance only showing x86_64 packages on a AMD Turion 64.
257 This would mean that x86_64 packages could be filtered from non-native 32-bit
258 packages.
259 This allows the used to choose non-native packages if a multi-lib policy is allowed.
260 </entry>
261 </row>
262 <row>
263 <entry><literal>source</literal> or <literal>~source</literal></entry>
264 <entry>
265 The source filter will only return source packages.
266 These are typically useful when rebuilding other packages.
267 </entry>
268 </row>
269 </tbody>
270 </tgroup>
271 </informaltable>
272
273 <para>
274 So valid options would be:
275 </para>
276 <informaltable>
277 <tgroup cols="2">
278 <thead>
279 <row>
280 <entry>Option</entry>
281 <entry>Description</entry>
282 </row>
283 </thead>
284 <tbody>
285 <row>
286 <entry><literal>none</literal></entry>
287 <entry>All packages installed or available with no filtering</entry>
288 </row>
289 <row>
290 <entry><literal>devel;~installed</literal></entry>
291 <entry>All non-installed development packages</entry>
292 </row>
293 <row>
294 <entry><literal>installed;~devel</literal></entry>
295 <entry>All installed non-development packages</entry>
296 </row>
297 <row>
298 <entry><literal>gui;~installed;~devel</literal></entry>
299 <entry>All non-installed, non-devel gui programs</entry>
300 </row>
301 </tbody>
302 </tgroup>
303 </informaltable>
304
305 <sect2 id="introduction-ideas-filters-removeinstalled">
306 <title>Removing installed versions in search results</title>
307 <para>
308 When outputting a list of packages, it's important to remove the <emphasis>available</emphasis>
309 package if the <emphasis>same</emphasis> version is installed.
310 This is required, as the user may do <literal>SearchName("kernel",filter="none")</literal>
311 and only want to return results that can be operated on.
312 For instance, suppose we have installed:
313 </para>
314 <simplelist type="horiz" columns="1">
315 <member><literal>kernel-2.6.29.4-167 (installed)</literal></member>
316 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
317 </simplelist>
318 <para>
319 And in the remote software sources we have:
320 </para>
321 <simplelist type="horiz" columns="1">
322 <member><literal>kernel-2.6.29.4-167 (fedora)</literal></member>
323 <member><literal>kernel-2.6.29.5-191 (fedora-updates)</literal></member>
324 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
325 </simplelist>
326 <para>
327 If we do <literal>Resolve("kernel",filter="none")</literal> we should expect:
328 </para>
329 <simplelist type="horiz" columns="1">
330 <member><literal>kernel-2.6.29.4-167 (installed)</literal></member>
331 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
332 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
333 </simplelist>
334 <para>
335 If the <literal>kernel-2.6.29.4-167 (fedora)</literal> result was returned,
336 this will be in the list of results, and is a valid install target.
337 The user will get very confused why <literal>2.6.29.4-167</literal> is both
338 installed and not installed.
339 </para>
340 </sect2>
341
342 <sect2 id="introduction-ideas-filters-examples">
343 <title>Filter examples</title>
344 <para>
345 Suppose we have installed:
346 </para>
347 <simplelist type="horiz" columns="1">
348 <member><literal>kernel-2.6.29.4-167 (installed)</literal></member>
349 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
350 </simplelist>
351 <para>
352 In the remote software sources we have:
353 </para>
354 <simplelist type="horiz" columns="1">
355 <member><literal>kernel-2.6.29.4-167 (fedora)</literal></member>
356 <member><literal>kernel-2.6.29.5-191 (fedora-updates)</literal></member>
357 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
358 </simplelist>
359 <para>
360 If we do <literal>Resolve("kernel",filter="none")</literal> we should expect:
361 </para>
362 <simplelist type="horiz" columns="1">
363 <member><literal>kernel-2.6.29.4-167 (installed)</literal></member>
364 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
365 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
366 </simplelist>
367 <para>
368 If we do <literal>Resolve("kernel",filter="installed")</literal> we should expect:
369 </para>
370 <simplelist type="horiz" columns="1">
371 <member><literal>kernel-2.6.29.4-167 (installed)</literal></member>
372 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
373 </simplelist>
374 <para>
375 If we do <literal>Resolve("kernel",filter="~installed")</literal> we should expect:
376 </para>
377 <simplelist type="horiz" columns="1">
378 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
379 </simplelist>
380 <para>
381 If we do <literal>Resolve("kernel",filter="newest;installed")</literal> we should expect:
382 </para>
383 <simplelist type="horiz" columns="1">
384 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
385 </simplelist>
386 <para>
387 If we do <literal>Resolve("kernel",filter="newest")</literal> we should expect:
388 </para>
389 <simplelist type="horiz" columns="1">
390 <member><literal>kernel-2.6.29.5-191 (installed)</literal></member>
391 <member><literal>kernel-2.6.30.1-203 (fedora-updates)</literal></member>
392 </simplelist>
393 </sect2>
394
395 </sect1>
396
397 <sect1 id="introduction-errors">
398 <title>Error Enums</title>
399 <para>
400 If you have to handle an error, try to use <literal>internal-error</literal>
401 as little as possible.
402 Just ask on the mailing list, and we can add some more error enums to
403 cover the type of error in an abstract way as possible.
404 </para>
405 <para>
406 Every error should have an enumerated type
407 (e.g. <literal>out-of-memory</literal>) and also an error description.
408 The error description is not translated and not converted into the users
409 locale.
410 The error description should be descriptive, as it's for power users
411 and people trying to debug the problem.
412 For instance, "Out of memory" is not helpful as an error description
413 that is reported in a bugzilla, but "Could not create database index" is.
414 For the description use <literal>;</literal> to separate the lines if
415 required.
416 </para>
417 <para>
418 The following error enumerated types are available for use in all
419 backends:
420 </para>
421 <informaltable>
422 <tgroup cols="2">
423 <thead>
424 <row>
425 <entry>Error</entry>
426 <entry>Description</entry>
427 </row>
428 </thead>
429 <tbody>
430 <row>
431 <entry><literal>out-of-memory</literal></entry>
432 <entry>There is an out of memory condition</entry>
433 </row>
434 <row>
435 <entry><literal>no-network</literal></entry>
436 <entry>There is no network connection that can be used</entry>
437 </row>
438 <row>
439 <entry><literal>not-supported</literal></entry>
440 <entry>
441 Not supported by the backend.
442 NOTE: You shouldn't be setting non-NULL in the compiled
443 backend symbol table if you find yourself using this.
444 </entry>
445 </row>
446 <row>
447 <entry><literal>internal-error</literal></entry>
448 <entry>
449 There was an unspecified internal error.
450 NOTE: Please try and be more specific.
451 If you are using this then we should probably add a new type.
452 </entry>
453 </row>
454 <row>
455 <entry><literal>no-cache</literal></entry>
456 <entry>
457 The operation is trying to read from the cache, but the cache
458 is not present or invalid
459 </entry>
460 </row>
461 <row>
462 <entry><literal>gpg-failure</literal></entry>
463 <entry>There was a GPG failure in the transaction</entry>
464 </row>
465 <row>
466 <entry><literal>package-id-invalid</literal></entry>
467 <entry>The package ID is not valid for this transaction</entry>
468 </row>
469 <row>
470 <entry><literal>package-not-installed</literal></entry>
471 <entry>
472 The package that is trying to be removed or updated is not
473 installed
474 </entry>
475 </row>
476 <row>
477 <entry><literal>package-not-found</literal></entry>
478 <entry>
479 The package that is trying to be removed or updated is not
480 installed
481 </entry>
482 </row>
483 <row>
484 <entry><literal>package-already-installed</literal></entry>
485 <entry>
486 The (single) package that is trying to be installed or updated is already
487 installed
488 </entry>
489 </row>
490 <row>
491 <entry><literal>all-packages-already-installed</literal></entry>
492 <entry>
493 Multiple package installs were attempted, but all of
494 them were already installed. The backend should
495 generate package-already-installed messages (not errors)
496 for each package.
497 </entry>
498 </row>
499 <row>
500 <entry><literal>package-download-failed</literal></entry>
501 <entry>A package failed to download correctly</entry>
502 </row>
503 <row>
504 <entry><literal>invalid-package-file</literal></entry>
505 <entry>
506 The file that is supposed to contain a package to
507 install is corrupt, or is not a valid package file
508 </entry>
509 </row>
510 <row>
511 <entry><literal>package-install-blocked</literal></entry>
512 <entry>
513 The backend's configuration or policy prevents the
514 install or updating of a package
515 </entry>
516 </row>
517 <row>
518 <entry><literal>dep-resolution-failed</literal></entry>
519 <entry>Dependency resolution failed</entry>
520 </row>
521 <row>
522 <entry><literal>filter-invalid</literal></entry>
523 <entry>
524 The filter was invalid.
525 NOTE: syntax checking is done in the backend loader, so you
526 should only use this if the filter is not supported by the
527 backend.
528 </entry>
529 </row>
530 <row>
531 <entry><literal>group-not-found</literal></entry>
532 <entry>
533 The specified software group was not found.
534 </entry>
535 </row>
536 <row>
537 <entry><literal>create-thread-failed</literal></entry>
538 <entry>Failed to create a thread</entry>
539 </row>
540 <row>
541 <entry><literal>transaction-error</literal></entry>
542 <entry>
543 There was a generic transaction error, but please give more
544 details in the description
545 </entry>
546 </row>
547 <row>
548 <entry><literal>transaction-cancelled</literal></entry>
549 <entry>
550 The transaction was cancelled as the result of a call
551 to Cancel()
552 </entry>
553 </row>
554 <row>
555 <entry><literal>repo-not-found</literal></entry>
556 <entry>The repository name could not be found</entry>
557 </row>
558 <row>
559 <entry><literal>repo-configuration-error</literal></entry>
560 <entry>One of the enabled repositories has invalid configuration</entry>
561 </row>
562 <row>
563 <entry><literal>repo-not-available</literal></entry>
564 <entry>
565 There was a (possibly transient) problem connecting to a
566 repository
567 </entry>
568 </row>
569 <row>
570 <entry><literal>cannot-remove-system-package</literal></entry>
571 <entry>
572 Could not remove a protected system package that is needed for
573 stable operation of the system
574 </entry>
575 </row>
576 <row>
577 <entry><literal>process-quit</literal></entry>
578 <entry>
579 The process was asked to quit, probably because it was cancelled
580 </entry>
581 </row>
582 <row>
583 <entry><literal>process-kill</literal></entry>
584 <entry>
585 The process was forcibly killed, probably because ignored the
586 quit request. This is probably due to it being cancelled
587 </entry>
588 </row>
589 <row>
590 <entry><literal>failed-config-parsing</literal></entry>
591 <entry>
592 Configuration files could not be read or parsed.
593 </entry>
594 </row>
595 <row>
596 <entry><literal>cannot-cancel</literal></entry>
597 <entry>
598 The Cancel() method was called, but it is too late to
599 cancel the current transaction.
600 </entry>
601 </row>
602 <row>
603 <entry><literal>cannot-get-lock</literal></entry>
604 <entry>
605 The backend could not acquire a lock on the underlying
606 package management system.
607 </entry>
608 </row>
609 <row>
610 <entry><literal>no-packages-to-update</literal></entry>
611 <entry>
612 UpdatePackages() was called, but there are no packages to update.
613 </entry>
614 </row>
615 <row>
616 <entry><literal>cannot-write-repo-config</literal></entry>
617 <entry>
618 RepoEnable() or RepoSetData() was called, but the
619 repository configuration file could not be written to.
620 </entry>
621 </row>
622 <row>
623 <entry><literal>local-install-failed</literal></entry>
624 <entry>
625 A local file could not be installed. The file might not
626 be readable, or it might not contain a valid package.
627 </entry>
628 </row>
629 <row>
630 <entry><literal>bad-gpg-signature</literal></entry>
631 <entry>
632 The package is signed with a GPG signature, but that
633 signature is not valid in some way.
634 </entry>
635 </row>
636 <row>
637 <entry><literal>package-corrupt</literal></entry>
638 <entry>
639 The downloaded package is corrupt.
640 </entry>
641 </row>
642 <row>
643 <entry><literal>file-not-found</literal></entry>
644 <entry>
645 The file could not be found on the system.
646 </entry>
647 </row>
648 </tbody>
649 </tgroup>
650 </informaltable>
651 </sect1>
652
653 <sect1 id="introduction-group-type">
654 <title>Group type</title>
655 <para>
656 Groups are enumerated for localisation.
657 Backends should try to put packages in different groups if possible,
658 else just don't advertise SearchGroup and the options should not be
659 shown in the UI.
660 </para>
661 <para>
662 The following group enumerated types are available, but please check
663 <literal>libpackagekit/pk-enum.h</literal> for the latest list.
664 </para>
665 <informaltable>
666 <tgroup cols="2">
667 <thead>
668 <row>
669 <entry>Group</entry>
670 <entry>Description</entry>
671 </row>
672 </thead>
673 <tbody>
674 <row>
675 <entry><literal>accessibility</literal></entry>
676 <entry>Accessibility</entry>
677 </row>
678 <row>
679 <entry><literal>accessories</literal></entry>
680 <entry>Accessories</entry>
681 </row>
682 <row>
683 <entry><literal>admin-tools</literal></entry>
684 <entry>Admin tools</entry>
685 </row>
686 <row>
687 <entry><literal>communication</literal></entry>
688 <entry>Communication</entry>
689 </row>
690 <row>
691 <entry><literal>desktop-gnome</literal></entry>
692 <entry>Gnome</entry>
693 </row>
694 <row>
695 <entry><literal>desktop-kde</literal></entry>
696 <entry>KDE</entry>
697 </row>
698 <row>
699 <entry><literal>desktop-dde</literal></entry>
700 <entry>DDE</entry>
701 </row>
702 <row>
703 <entry><literal>desktop-other</literal></entry>
704 <entry>Other desktops</entry>
705 </row>
706 <row>
707 <entry><literal>desktop-xfce</literal></entry>
708 <entry>Xfce</entry>
709 </row>
710 <row>
711 <entry><literal>education</literal></entry>
712 <entry>Education</entry>
713 </row>
714 <row>
715 <entry><literal>fonts</literal></entry>
716 <entry>Fonts</entry>
717 </row>
718 <row>
719 <entry><literal>games</literal></entry>
720 <entry>Games</entry>
721 </row>
722 <row>
723 <entry><literal>graphics</literal></entry>
724 <entry>Graphics</entry>
725 </row>
726 <row>
727 <entry><literal>internet</literal></entry>
728 <entry>Internet</entry>
729 </row>
730 <row>
731 <entry><literal>legacy</literal></entry>
732 <entry>Legacy</entry>
733 </row>
734 <row>
735 <entry><literal>localization</literal></entry>
736 <entry>Localization</entry>
737 </row>
738 <row>
739 <entry><literal>maps</literal></entry>
740 <entry>Maps</entry>
741 </row>
742 <row>
743 <entry><literal>network</literal></entry>
744 <entry>Network</entry>
745 </row>
746 <row>
747 <entry><literal>office</literal></entry>
748 <entry>Office</entry>
749 </row>
750 <row>
751 <entry><literal>other</literal></entry>
752 <entry>Other</entry>
753 </row>
754 <row>
755 <entry><literal>power-management</literal></entry>
756 <entry>Power management</entry>
757 </row>
758 <row>
759 <entry><literal>programming</literal></entry>
760 <entry>Programming</entry>
761 </row>
762 <row>
763 <entry><literal>publishing</literal></entry>
764 <entry>Publishing</entry>
765 </row>
766 <row>
767 <entry><literal>multimedia</literal></entry>
768 <entry>Multimedia</entry>
769 </row>
770 <row>
771 <entry><literal>security</literal></entry>
772 <entry>Security</entry>
773 </row>
774 <row>
775 <entry><literal>servers</literal></entry>
776 <entry>Servers</entry>
777 </row>
778 <row>
779 <entry><literal>system</literal></entry>
780 <entry>System</entry>
781 </row>
782 <row>
783 <entry><literal>virtualization</literal></entry>
784 <entry>Virtualization</entry>
785 </row>
786 <row>
787 <entry><literal>science</literal></entry>
788 <entry>Science</entry>
789 </row>
790 <row>
791 <entry><literal>documentation</literal></entry>
792 <entry>Documentation</entry>
793 </row>
794 <row>
795 <entry><literal>electronics</literal></entry>
796 <entry>Electronics</entry>
797 </row>
798 <row>
799 <entry><literal>vendor</literal></entry>
800 <entry>Vendor</entry>
801 </row>
802 </tbody>
803 </tgroup>
804 </informaltable>
805 </sect1>
806
807 <sect1 id="introduction-cancellation">
808 <title>Cancellation</title>
809 <para>
810 If you have a multipart transaction that can be aborted in one phase but
811 not another then the AllowCancel signal can be sent.
812 This allows for example the hif download to be cancelled, but not the
813 install transaction.
814 By cancelling a job all subtransactions are killed.
815 </para>
816 <para>
817 By default actions cannot be cancelled unless enabled in the backend.
818 Use <literal>AllowCancel(true)</literal> to enable cancellation
819 and <literal>AllowCancel(false)</literal> to disable it.
820 This can be done for any job type.
821 </para>
822 <para>
823 For compiled backends that are threaded, the
824 <literal>cancel()</literal> method can be used to terminate
825 the thread.
826 </para>
827 <para>
828 For spawned backends, there are two staggered signals send to allow
829 locks to be released or for the backend to clean up after itself:
830 </para>
831 <itemizedlist>
832 <listitem>
833 <para>Send the process <literal>SIGQUIT</literal>.</para>
834 </listitem>
835 <listitem>
836 <para>Wait 500ms</para>
837 </listitem>
838 <listitem>
839 <para>
840 If the process has not already quit, send the process
841 <literal>SIGKILL</literal> to terminate it.
842 </para>
843 </listitem>
844 </itemizedlist>
845 </sect1>
846
847 <sect1 id="introduction-ideas-transactions">
848 <title>Transactions</title>
849 <para>
850 PackageKit does not ask the user questions when the transaction is running.
851 It also supports a fire-and-forget method invocation, which means that transactions will
852 have one calling method, and have many signals going back to the caller.
853 </para>
854 <para>
855 Each transaction is a new path on the <literal>org.freedesktop.PackageKit</literal>
856 service, and to create a path you have to call <literal>CreateTransaction</literal> on the base
857 interface which creates the new D-Bus path, and returns the new path for you to connect to.
858 In the libpackagekit binding, <literal>PkControl</literal> handles the base interface,
859 whilst <literal>PkClient</literal> handles all the transaction interface stuff.
860 The <literal>org.freedesktop.PackageKit.Transaction</literal> interface can be used
861 on the newly created path, but only used once.
862 New methods require a new transaction path (i.e. another call to <literal>CreateTransaction</literal>)
863 which is synchronous and thus very fast.
864 </para>
865
866 <sect2 id="introduction-ideas-transactions-success">
867 <title>Transaction example: Success</title>
868 <mediaobject id="pk-transactions-success">
869 <imageobject>
870 <imagedata format="PNG" fileref="pk-transactions-success.png" align="center"/>
871 </imageobject>
872 </mediaobject>
873 <para>
874 A typical successful transaction would emit many signals such as
875 <literal>::Progress()</literal>, <literal>::Package()</literal> and
876 <literal>::StatusChanged()</literal>.
877 These are used to inform the client application of the current state,
878 so widgets such as icons or description text can be updated.
879 </para>
880 <para>
881 These different signals are needed for a few different reasons:
882 </para>
883
884 <itemizedlist>
885 <listitem>
886 <para>
887 <literal>::StatusChanged()</literal>: The global state of the
888 transaction, which will be useful for some GUIs.
889 Examples include downloading or installing, and this is designed
890 to be a 40,000ft view of what is happening.
891 </para>
892 </listitem>
893 <listitem>
894 <para>
895 <literal>::Package()</literal>: Used to either return a result
896 (e.g. returning results of the <literal>SearchName()</literal> method)
897 or to return progress about a _specific_ package.
898 For instance, when doing <literal>UpdatePackages()</literal>, sending
899 <literal>::Package(downloading)</literal> and then
900 <literal>::Package(installing)</literal> for each package as processed
901 in the transaction allows a GUI to position the cursor on the worked
902 on package and show the correct icon for that package.
903 </para>
904 </listitem>
905 <listitem>
906 <para>
907 <literal>::ErrorCode()</literal>: to show an error to the user about
908 the transaction, which can be cleaned up before sending
909 <literal>::Finished()</literal>.
910 </para>
911 </listitem>
912 <listitem>
913 <para>
914 <literal>::Finished()</literal>: to show the transaction has
915 finished, and others can be scheduled.
916 </para>
917 </listitem>
918 </itemizedlist>
919 </sect2>
920
921 <sect2 id="introduction-ideas-transactions-failure">
922 <title>Transaction example: Failure</title>
923 <mediaobject id="pk-transactions-failure">
924 <imageobject>
925 <imagedata format="PNG" fileref="pk-transactions-failure.png" align="center"/>
926 </imageobject>
927 </mediaobject>
928 <para>
929 This is the typical transaction failure case when there is no network available.
930 The user is not given the chance to requeue the transaction as it is a fatal error.
931 </para>
932 </sect2>
933
934 <sect2 id="introduction-ideas-transactions-trusted">
935 <title>Transaction example: Trusted</title>
936 <mediaobject id="pk-transactions-trusted">
937 <imageobject>
938 <imagedata format="PNG" fileref="pk-transactions-trusted.png" align="center"/>
939 </imageobject>
940 </mediaobject>
941 <para>
942 In this non-trivial example, a local file install is being attempted.
943 First the <literal>InstallFile</literal> is called with the <literal>only_trusted</literal>
944 flag set.
945 This will fail if the package does not have a valid GPG key, and ordinarily the transaction
946 would fail. What the client can do, e.g. using <literal>libpackagekit</literal>, is
947 to re-request the <literal>InstallFile</literal> with <literal>non-trusted</literal>.
948 This will use a different PolicyKit authentication, and allow the file to succeed.
949 </para>
950 <para>
951 So why do we bother calling <literal>only_trusted</literal> in the first place?
952 Well, the only_trusted PolicyKit role can be saved in the gnome-keyring, or could be
953 set to the users password as the GPG key is already only_trusted by the user.
954 The <literal>non-trusted</literal> action would likely ask for the administrator password,
955 and not allowed to be saved. This gives the user the benifit of installing only_trusted local
956 files without a password (common case) but requiring something stronger for untrusted or
957 unsigned files.
958 </para>
959 </sect2>
960
961 <sect2 id="introduction-ideas-transactions-auto-untrusted">
962 <title>Transaction example: Auto Untrusted</title>
963 <mediaobject id="pk-transactions-auto-untrusted">
964 <imageobject>
965 <imagedata format="PNG" fileref="pk-transactions-auto-untrusted.png" align="center"/>
966 </imageobject>
967 </mediaobject>
968 <para>
969 If <literal>SimulateInstallPackage</literal> or
970 <literal>SimulateInstallFile</literal> is used then the client
971 may receive a <literal>INFO_UNTRUSTED</literal> package.
972 </para>
973 <para>
974 This is used to inform the client that the action would require
975 the untrusted authentication type, which means the client does
976 not attempt to do <literal>SimulateInstallPackage(only_trusted=TRUE)</literal>
977 and only does <literal>SimulateInstallPackage(only_trusted=FALSE)</literal>.
978 This ensures the user has to only authenticate once for the
979 transaction as the <literal>only_trusted=TRUE</literal> action
980 may also require a password.
981 </para>
982 </sect2>
983
984 <sect2 id="introduction-ideas-transactions-sig-install">
985 <title>Transaction example: Package signature install</title>
986 <mediaobject id="pk-transactions-sig-install">
987 <imageobject>
988 <imagedata format="PNG" fileref="pk-transactions-sig-install.png" align="center"/>
989 </imageobject>
990 </mediaobject>
991 <para>
992 If the package is signed, and a valid GPG signature is available, then we need to ask the
993 user to import the key, and re-run the transaction.
994 This is done as three transactions, as other transactions may be queued and have a higher
995 priority, and to make sure that the transaction object is not reused.
996 </para>
997 <para>
998 Keep in mind that PackageKit can only be running one transaction at any
999 one time.
1000 If we had designed the PackageKit API to block and wait for user input,
1001 then no other transactions could be run whilst we are waiting for the user.
1002 </para>
1003 <para>
1004 This is best explained using an example:
1005 </para>
1006 <itemizedlist>
1007 <listitem>
1008 <para>User clicks "install vmware" followed by "confirm".</para>
1009 </listitem>
1010 <listitem>
1011 <para>User walks away from the computer and takes a nap</para>
1012 </listitem>
1013 <listitem>
1014 <para>System upgrade is scheduled (300Mb of updates)</para>
1015 </listitem>
1016 </itemizedlist>
1017 <para>
1018 The vmware package is downloaded, but cannot be installed until a EULA
1019 is agreed to.
1020 If we pause the transaction then we never apply the updates automatically
1021 and the computer is not kept up to date.
1022 The user would have to wait a substantial amount of time waiting for
1023 the updates to download when returning from his nap after clicking "I agree"
1024 to the vmware EULA.
1025 </para>
1026 <para>
1027 In the current system where transactions cannot block, the first
1028 transaction downloads vmware, and then it finishes, and puts up a UI
1029 for the user to click.
1030 In the meantime the second transaction (the update) is scheduled,
1031 downloaded and installed, and then finishes.
1032 The user returns, clicks "okay" and a third transaction is created that
1033 accepts the eula, and a forth that actually installs vmware.
1034 </para>
1035 <para>
1036 It seems complicated, but it's essential to make sure none of the
1037 callbacks block and stop other transactions from happening.
1038 </para>
1039 </sect2>
1040
1041 <sect2 id="introduction-ideas-transactions-download">
1042 <title>Transaction example: Download</title>
1043 <mediaobject id="pk-transactions-download">
1044 <imageobject>
1045 <imagedata format="PNG" fileref="pk-transactions-download.png" align="center"/>
1046 </imageobject>
1047 </mediaobject>
1048 <para>
1049 When the <literal>DownloadPackages()</literal> method is called on a number
1050 of packages, then these are downloaded by the daemon into a temporary
1051 directory.
1052 This directory can only be written by the <literal>packagekitd</literal>
1053 user (usually root) but can be read by all users.
1054 The files are not downloaded into any specific directory, instead a
1055 random one is created in <literal>/var/cache/PackageKit/downloads</literal>.
1056 The reason for this intermediate step is that the
1057 <literal>DownloadPackages()</literal> method does not take a destination
1058 directory as the dameon is running as a different user to the user,
1059 and in a different SELinux context.
1060 </para>
1061 <para>
1062 To preserve the SELinux attributes and the correct user and group ownership
1063 of the newly created files, the client (running in the user session) has
1064 to copy the files from the temporary directory into the chosen destination
1065 directory.
1066 NOTE: this copy step is optional but recommended, as the files will remain in
1067 the temporary directory until the daemon is times out and is restarted.
1068 As the client does not know (intentionally) the temporary directory or the
1069 filenames of the packages that are created, the <literal>::Files()</literal>
1070 signal is emitted with the full path of the downloaded files.
1071 It is expected the <literal>package_id</literal> parameter of
1072 <literal>::Files()</literal> will be blank, although this is not mandated.
1073 </para>
1074 <para>
1075 Multiple <literal>::Files()</literal> signals can be sent by the dameon,
1076 as the download operation may be pipelined, and the client should honour
1077 every signal by copying each file.
1078 </para>
1079 </sect2>
1080
1081 <sect2 id="introduction-ideas-transactions-set-locale">
1082 <title>Transaction example: Setting the locale</title>
1083 <mediaobject id="pk-transactions-set-locale">
1084 <imageobject>
1085 <imagedata format="PNG" fileref="pk-transactions-set-locale.png" align="center"/>
1086 </imageobject>
1087 </mediaobject>
1088 <para>
1089 The PackageKit backend may support native localisation, which we should support if the
1090 translations exist.
1091 In the prior examples the <literal>SetLocale()</literal> method has been left out for brevity.
1092 If you are using the raw D-Bus methods to access PackageKit, you will also need to make
1093 a call to <literal>SetLocale()</literal> so the daemon knows what locale to assign the
1094 transaction.
1095 If you are using libpackagekit to schedule transactions, then the locale will be set
1096 automatically in the <literal>PkControl</literal> GObject, and you do not need to call
1097 <literal>pk_client_set_locale()</literal> manually.
1098 </para>
1099 </sect2>
1100
1101 <sect2 id="introduction-ideas-transactions-repair">
1102 <title>Transaction example: Repair</title>
1103 <mediaobject id="pk-transactions-repair">
1104 <imageobject>
1105 <imagedata format="PNG" fileref="pk-transactions-repair-required.png" align="center"/>
1106 </imageobject>
1107 </mediaobject>
1108 <para>
1109 If the package management system is damaged, a repair may be required.
1110 This is not automatically done befor each transaction as the user
1111 may have to verify destructive package actions or make manual changes to
1112 configuration files.
1113 </para>
1114 <para>
1115 This transaction sequence is not common and is not supported on
1116 many backends.
1117 It may be completely implemented in the frontend or not at all.
1118 </para>
1119 </sect2>
1120
1121 </sect1>
1122
1123 <sect1 id="introduction-ideas-transactionid">
1124 <title>Transaction IDs</title>
1125 <para>
1126 A <literal>transaction_id</literal> is a unique identifier that
1127 identifies the present or past transaction.
1128 A transaction is made up of one or more sub-transactions.
1129 A transaction has one <literal>role</literal> for the entire lifetime,
1130 but the transaction can different values of <literal>status</literal>
1131 as the transaction is processed.
1132 </para>
1133 <para>
1134 For example, if the user "Installed OpenOffice" and the backend has to:
1135 </para>
1136 <itemizedlist>
1137 <listitem>
1138 <para>
1139 update libxml2 as a dependency
1140 </para>
1141 </listitem>
1142 <listitem>
1143 <para>
1144 install java as dependency
1145 </para>
1146 </listitem>
1147 <listitem>
1148 <para>
1149 install openoffice-bin
1150 </para>
1151 </listitem>
1152 <listitem>
1153 <para>
1154 install openoffice-clipart
1155 </para>
1156 </listitem>
1157 </itemizedlist>
1158 <para>
1159 This is one single transaction with the role <literal>install</literal>,
1160 with 4 different sub-transactions.
1161 </para>
1162 <para>
1163 The <literal>transaction_id</literal> must be of the format
1164 <literal>/job_identifier_data</literal> where the daemon controls
1165 all parameters.
1166 <literal>job</literal> is a monotonically updating number and is
1167 retained over reboots.
1168 <literal>identifier</literal> is random data used by the daemon to
1169 ensure jobs started in parallel cannot race, and also to make a
1170 malicious client program harder to write.
1171 <literal>data</literal> can be used for ref-counting in the backend or
1172 for any other purpose.
1173 It is designed to make the life of a backend writer a little bit easier.
1174 An example <literal>transaction_id</literal> would be
1175 <literal>/45_dafeca_checkpoint32</literal>
1176 </para>
1177 </sect1>
1178
1179 <sect1 id="introduction-ideas-status">
1180 <title>Status Values</title>
1181 <para>
1182 A transaction will have different status values as it it queued, prepared
1183 and executed.
1184 The <literal>::StatusChanged</literal> signal from PkClient allow you
1185 to design user interfaces that tell the user what is happening with the
1186 transaction.
1187 </para>
1188 <para>
1189 A typical transaction will have the following states:
1190 </para>
1191 <itemizedlist>
1192 <listitem>
1193 <para>
1194 Queued in the active queue (<literal>PK_STATUS_ENUM_WAIT</literal>)
1195 </para>
1196 </listitem>
1197 <listitem>
1198 <para>
1199 Transaction started, and is being prepared (<literal>PK_STATUS_ENUM_SETUP</literal>)
1200 </para>
1201 </listitem>
1202 <listitem>
1203 <para>
1204 The transaction is running (<literal>PK_STATUS_ENUM_RUNNING</literal>)
1205 </para>
1206 </listitem>
1207 <listitem>
1208 <para>
1209 (optional) Data is downloading (<literal>PK_STATUS_ENUM_DOWNLOADING</literal>)
1210 </para>
1211 </listitem>
1212 <listitem>
1213 <para>
1214 (optional) Data is installing (<literal>PK_STATUS_ENUM_INSTALLING</literal>)
1215 </para>
1216 </listitem>
1217 <listitem>
1218 <para>
1219 The transaction is finished (<literal>PK_STATUS_ENUM_FINISHED</literal>)
1220 </para>
1221 </listitem>
1222 </itemizedlist>
1223 <para>
1224 If the transaction is waiting for other jobs to finish (in the active queue)
1225 then the status will be stuck at <literal>PK_STATUS_ENUM_WAIT</literal>
1226 and the UI should show a message to this effect.
1227 </para>
1228 <para>
1229 If the transaction is waiting for a package lock (when a legacy tool like
1230 <literal>pirut</literal> is loaded and has the <literal>hif</literal> lock)
1231 then the transaction will be stuck at <literal>PK_STATUS_ENUM_WAITING_FOR_LOCK</literal>.
1232 </para>
1233 <para>
1234 As a backend writer, you do not have to set <literal>PK_STATUS_ENUM_RUNNING</literal>
1235 manually, as this will be set for you if you set any other value such as
1236 <literal>PK_STATUS_ENUM_DOWNLOADING</literal> or <literal>PK_STATUS_ENUM_INFO</literal>.
1237 However, you will need to avoid setting any status values until a package
1238 lock is available and the transaction has started.
1239 </para>
1240 </sect1>
1241
1242 </chapter>
1243