packagekit/docs/backends.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="backends">
  <title>Backends</title>

  <sect1 id="backends-spawn-introduction">
    <title>Spawn Introduction</title>
    <para>
      Backends are typically open-programmable, which means we can define a
      standard for what goes on stdin, stdout and stderr to try and maximise
      the common code between the backends.
      The following section will explain the convention used on
      <literal>backends/conary</literal> and <literal>backends/yum</literal>.
    </para>
    <para>
      If you are unable to write scripts that conform to these specifications
      then just launch a PkSpawn object in the compiled helper with stdout and
      stderr callbacks and then try to do screenscraping in the backend.
      This screenscraping is least popular for obvious reasons.
    </para>
    <para>
      Backends scripts are run with arguments and data is sent to standard out
      and standard error asyncronously so that PackageKit can proxy this to DBUS.
      A method has command line arguments seporated with tabs, and data is also
      seporated with tabs.
    </para>
  </sect1>

  <sect1 id="backends-spawn-methods">
    <title>Methods</title>
    <para>
      The following methods are mapped from the helper to comand line programs
      in the compile helper.
    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Method</entry>
            <entry>File</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Search Name</entry>
            <entry><literal>search-name.*</literal></entry>
          </row>
          <row>
            <entry>Search Group</entry>
            <entry><literal>search-group.*</literal></entry>
          </row>
          <row>
            <entry>Search Details</entry>
            <entry><literal>search-details.*</literal></entry>
          </row>
          <row>
            <entry>Search File</entry>
            <entry><literal>search-file.*</literal></entry>
          </row>
          <row>
            <entry>Install Package</entry>
            <entry><literal>install.*</literal></entry>
          </row>
          <row>
            <entry>Install File</entry>
            <entry><literal>install-file.*</literal></entry>
          </row>
          <row>
            <entry>Remove Package</entry>
            <entry><literal>remove.*</literal></entry>
          </row>
          <row>
            <entry>Get Depends</entry>
            <entry><literal>get-depends.*</literal></entry>
          </row>
          <row>
            <entry>Resolve</entry>
            <entry><literal>resolve.*</literal></entry>
          </row>
          <row>
            <entry>Get Requires</entry>
            <entry><literal>get-requires.*</literal></entry>
          </row>
          <row>
            <entry>Get Update Detail</entry>
            <entry><literal>get-update-detail.*</literal></entry>
          </row>
          <row>
            <entry>Get Description</entry>
            <entry><literal>get-description.*</literal></entry>
          </row>
          <row>
            <entry>Update Package</entry>
            <entry><literal>update.*</literal></entry>
          </row>
          <row>
            <entry>Update System</entry>
            <entry><literal>update-system.*</literal></entry>
          </row>
          <row>
            <entry>Get Updates</entry>
            <entry><literal>get-updates.*</literal></entry>
          </row>
          <row>
            <entry>Refresh Cache</entry>
            <entry><literal>refresh-cache.*</literal></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

  </sect1>

  <sect1 id="backends-spawn-common">
    <title>Common function outputs</title>
    <para>
      The following commands echoed to standard error will
      automatically make the backend-launcher do the correct action in the
      compiled helper.
    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Method</entry>
            <entry>Data</entry>
            <entry>File</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>Percentage</entry>
            <entry><literal>percentage[tab]value</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>Subpercentage</entry>
            <entry><literal>subpercentage[tab]value</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>NoPercentageUpdates</entry>
            <entry><literal>no-percentage-updates</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>Error</entry>
            <entry><literal>error[tab]enum[tab]description</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>Status</entry>
            <entry><literal>status[tab]state</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>RequireRestart</entry>
            <entry><literal>requirerestart[tab]type[tab]details</literal></entry>
            <entry><literal>stderr</literal></entry>
          </row>
          <row>
            <entry>Package</entry>
            <entry><literal>package_id[tab]status[tab]package_id[tab]summary</literal></entry>
            <entry><literal>stdout</literal></entry>
          </row>
          <row>
            <entry>Description</entry>
            <entry><literal>description[tab]package_id[tab]group[tab]detail[tab]url[tab]size_in_bytes[tab]file_list</literal></entry>
            <entry><literal>stdout</literal></entry>
          </row>
          <row>
            <entry>UpdateDetail</entry>
            <entry><literal>package_id[tab]updates[tab]obsoletes[tab]url[tab]restart[tab]update_text</literal></entry>
            <entry><literal>stdout</literal></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>


</chapter>