Attachment 131047 Details for Bug 100795 – document all driver calls in the same section

[patch] document all driver calls in the same section

0001-docs-document-all-of-the-org.freedesktop.DBus-method.patch (text/plain), 113.39 KB, created by Tom Gundersen on 2017-04-26 09:49:08 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Tom Gundersen

Created: 2017-04-26 09:49:08 UTC

Size: 113.39 KB

patch

obsolete

>From 3492c747246efda1ca719422b3e681bdb3810c07 Mon Sep 17 00:00:00 2001
>From: Tom Gundersen <teg@jklm.no>
>Date: Fri, 21 Apr 2017 11:54:03 +0200
>Subject: [PATCH 1/3] docs: document all of the org.freedesktop.DBus methods
> together
>
>This patch simply moves RequestName, ReleaseName and ListNameOwners
>to the "Message Bus Messages" section. This keeps the documentation
>of the org.freedesktop.DBus interface in one place for easier reading.
>
>Only very minor rewording was done, but no substantive changes.
>
>Signed-off-by: Tom Gundersen <teg@jklm.no>
>---
> doc/dbus-specification.xml | 2257 ++++++++++++++++++++++----------------------
> 1 file changed, 1125 insertions(+), 1132 deletions(-)
>
>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index 0f0ca5ae..7759de36 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -4253,1036 +4253,645 @@
>         name. These names can be released again using the
>         <literal>org.freedesktop.DBus.ReleaseName</literal> message.
>       </para>
>+    </sect2>
> 
>-      <sect3 id="bus-messages-request-name">
>-        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
>+    <sect2 id="message-bus-routing">
>+      <title>Message Bus Message Routing</title>
>+
>+      <para>
>+        Messages may have a <literal>DESTINATION</literal> field (see <xref
>+          linkend="message-protocol-header-fields"/>), resulting in a
>+        <firstterm>unicast message</firstterm>.  If the
>+        <literal>DESTINATION</literal> field is present, it specifies a message
>+        recipient by name. Method calls and replies normally specify this field.
>+        The message bus must send messages (of any type) with the
>+        <literal>DESTINATION</literal> field set to the specified recipient,
>+        regardless of whether the recipient has set up a match rule matching
>+        the message.
>+      </para>
>+
>+      <para>
>+        When the message bus receives a signal, if the
>+        <literal>DESTINATION</literal> field is absent, it is considered to
>+        be a <firstterm>broadcast signal</firstterm>, and is sent to all
>+        applications with <firstterm>message matching rules</firstterm> that
>+        match the message. Most signal messages are broadcasts, and
>+        no other message types currently defined in this specification
>+        may be broadcast.
>+      </para>
>+
>+      <para>
>+        Unicast signal messages (those with a <literal>DESTINATION</literal>
>+        field) are not commonly used, but they are treated like any unicast
>+        message: they are delivered to the specified receipient,
>+        regardless of its match rules.  One use for unicast signals is to
>+        avoid a race condition in which a signal is emitted before the intended
>+        recipient can call <xref linkend="bus-messages-add-match"/> to
>+        receive that signal: if the signal is sent directly to that recipient
>+        using a unicast message, it does not need to add a match rule at all,
>+        and there is no race condition.  Another use for unicast signals,
>+        on message buses whose security policy prevents eavesdropping, is to
>+        send sensitive information which should only be visible to one
>+        recipient.
>+      </para>
>+
>+      <para>
>+        When the message bus receives a method call, if the
>+        <literal>DESTINATION</literal> field is absent, the call is taken to be
>+        a standard one-to-one message and interpreted by the message bus
>+        itself. For example, sending an
>+        <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
>+        <literal>DESTINATION</literal> will cause the message bus itself to
>+        reply to the ping immediately; the message bus will not make this
>+        message visible to other applications.
>+      </para>
>+
>+      <para>
>+        Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
>+        the ping message were sent with a <literal>DESTINATION</literal> name of
>+        <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
>+        forwarded, and the Yoyodyne Corporation screensaver application would be
>+        expected to reply to the ping.
>+      </para>
>+
>+      <para>
>+        Message bus implementations may impose a security policy which
>+        prevents certain messages from being sent or received.
>+        When a method call message cannot be sent or received due to a security
>+        policy, the message bus should send an error reply, unless the
>+        original message had the <literal>NO_REPLY</literal> flag.
>+      </para>
>+
>+      <sect3 id="message-bus-routing-eavesdropping">
>+        <title>Eavesdropping</title>
>         <para>
>-          As a method:
>-          <programlisting>
>-            UINT32 RequestName (in STRING name, in UINT32 flags)
>-          </programlisting>
>-          Message arguments:
>+          Receiving a unicast message whose <literal>DESTINATION</literal>
>+          indicates a different recipient is called
>+          <firstterm>eavesdropping</firstterm>. On a message bus which acts as
>+          a security boundary (like the standard system bus), the security
>+          policy should usually prevent eavesdropping, since unicast messages
>+          are normally kept private and may contain security-sensitive
>+          information.
>+        </para>
>+
>+        <para>
>+          Eavesdropping is mainly useful for debugging tools, such as
>+          the <literal>dbus-monitor</literal> tool in the reference
>+          implementation of D-Bus. Tools which eavesdrop on the message bus
>+          should be careful to avoid sending a reply or error in response to
>+          messages intended for a different client.
>+        </para>
>+
>+        <para>
>+          Clients may attempt to eavesdrop by adding match rules
>+          (see <xref linkend="message-bus-routing-match-rules"/>) containing
>+          the <literal>eavesdrop='true'</literal> match. If the message bus'
>+          security policy does not allow eavesdropping, the match rule can
>+          still be added, but will not have any practical effect. For
>+          compatibility with older message bus implementations, if adding such
>+          a match rule results in an error reply, the client may fall back to
>+          adding the same rule with the <literal>eavesdrop</literal> match
>+          omitted.
>+        </para>
>+
>+        <para>
>+          Eavesdropping interacts poorly with buses with non-trivial
>+          access control restrictions. The
>+          <xref linkend="bus-messages-become-monitor"/> method provides
>+          an alternative way to monitor buses.
>+        </para>
>+      </sect3>
>+
>+      <sect3 id="message-bus-routing-match-rules">
>+        <title>Match Rules</title>
>+        <para>
>+          An important part of the message bus routing protocol is match
>+          rules. Match rules describe the messages that should be sent to a
>+          client, based on the contents of the message.  Broadcast signals
>+          are only sent to clients which have a suitable match rule: this
>+          avoids waking up client processes to deal with signals that are
>+          not relevant to that client.
>+        </para>
>+        <para>
>+          Messages that list a client as their <literal>DESTINATION</literal>
>+          do not need to match the client's match rules, and are sent to that
>+          client regardless. As a result, match rules are mainly used to
>+          receive a subset of broadcast signals.
>+        </para>
>+        <para>
>+          Match rules can also be used for eavesdropping
>+          (see <xref linkend="message-bus-routing-eavesdropping"/>),
>+          if the security policy of the message bus allows it.
>+        </para>
>+        <para>
>+          Match rules are added using the AddMatch bus method
>+          (see <xref linkend="bus-messages-add-match"/>).  Rules are
>+          specified as a string of comma separated key/value pairs.
>+          Excluding a key from the rule indicates a wildcard match.
>+          For instance excluding the the member from a match rule but
>+          adding a sender would let all messages from that sender through.
>+          An example of a complete rule would be
>+          "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
>+        </para>
>+        <para>
>+          Within single quotes (ASCII apostrophe, U+0027), a backslash
>+          (U+005C) represents itself, and an apostrophe ends the quoted
>+          section. Outside single quotes, \' (backslash, apostrophe)
>+          represents an apostrophe, and any backslash not followed by
>+          an apostrophe represents itself. For instance, the match rules
>+          <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
>+          <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
>+          both match messages where the arguments are a 1-character string
>+          containing an apostrophe, a 1-character string containing a
>+          backslash, a 1-character string containing a comma, and a
>+          2-character string containing two backslashes<footnote>
>+            <para>
>+              This idiosyncratic quoting style is based on the rules for
>+              escaping items to appear inside single-quoted strings
>+              in POSIX <literal>/bin/sh</literal>, but please
>+              note that backslashes that are not inside single quotes have
>+              different behaviour. This syntax does not offer any way to
>+              represent an apostrophe inside single quotes (it is necessary
>+              to leave the single-quoted section, backslash-escape the
>+              apostrophe and re-enter single quotes), or to represent a
>+              comma outside single quotes (it is necessary to wrap it in
>+              a single-quoted section).
>+            </para>
>+          </footnote>.
>+        </para>
>+        <para>
>+          The following table describes the keys that can be used to create
>+          a match rule.
>           <informaltable>
>             <tgroup cols="3">
>               <thead>
>                 <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>+                  <entry>Key</entry>
>+                  <entry>Possible Values</entry>
>                   <entry>Description</entry>
>                 </row>
>               </thead>
>               <tbody>
>                 <row>
>-                  <entry>0</entry>
>-                  <entry>STRING</entry>
>-                  <entry>Name to request</entry>
>+                  <entry><literal>type</literal></entry>
>+                  <entry>'signal', 'method_call', 'method_return', 'error'</entry>
>+                  <entry>Match on the message type.  An example of a type match is type='signal'</entry>
>                 </row>
>                 <row>
>-                  <entry>1</entry>
>-                  <entry>UINT32</entry>
>-                  <entry>Flags</entry>
>+                  <entry><literal>sender</literal></entry>
>+                  <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
>+                  and <xref linkend="term-unique-name"/> respectively)
>+                  </entry>
>+                  <entry>Match messages sent by a particular sender.  An example of a sender match
>+                  is sender='org.freedesktop.Hal'</entry>
>                 </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-          Reply arguments:
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>                 <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>-                  <entry>Description</entry>
>+                  <entry><literal>interface</literal></entry>
>+                  <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
>+                  <entry>Match messages sent over or to a particular interface.  An example of an
>+                  interface match is interface='org.freedesktop.Hal.Manager'.
>+                  If a message omits the interface header, it must not match any rule
>+                  that specifies this key.</entry>
>                 </row>
>-              </thead>
>-              <tbody>
>                 <row>
>-                  <entry>0</entry>
>-                  <entry>UINT32</entry>
>-                  <entry>Return value</entry>
>+                  <entry><literal>member</literal></entry>
>+                  <entry>Any valid method or signal name</entry>
>+                  <entry>Matches messages which have the give method or signal name. An example of
>+                  a member match is member='NameOwnerChanged'</entry>
>                 </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-        <para>
>-          This method call should be sent to
>-          <literal>org.freedesktop.DBus</literal> and asks the message bus to
>-          assign the given name to the method caller. Each name maintains a
>-          queue of possible owners, where the head of the queue is the primary
>-          or current owner of the name. Each potential owner in the queue
>-          maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
>-          DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
>-          call.  When RequestName is invoked the following occurs:
>-          <itemizedlist>
>-            <listitem>
>-              <para>
>-                If the method caller is currently the primary owner of the name,
>-                the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
>-                values are updated with the values from the new RequestName call,
>-                and nothing further happens.
>-              </para>
>-            </listitem>
>+                <row>
>+                  <entry><literal>path</literal></entry>
>+                  <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
>+                  <entry>Matches messages which are sent from or to the given object. An example of a
>+                  path match is path='/org/freedesktop/Hal/Manager'</entry>
>+                </row>
>+                <row>
>+                  <entry><literal>path_namespace</literal></entry>
>+                  <entry>An object path</entry>
>+                  <entry>
>+                    <para>
>+                      Matches messages which are sent from or to an
>+                      object for which the object path is either the
>+                      given value, or that value followed by one or
>+                      more path components.
>+                    </para>
> 
>-            <listitem>
>-              <para>
>-                If the current primary owner (head of the queue) has
>-                DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
>-                invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
>-                the caller of RequestName replaces the current primary owner at
>-                the head of the queue and the current primary owner moves to the
>-                second position in the queue. If the caller of RequestName was
>-                in the queue previously its flags are updated with the values from
>-                the new RequestName in addition to moving it to the head of the queue.
>-              </para>
>-            </listitem>
>-
>-            <listitem>
>-              <para>
>-                If replacement is not possible, and the method caller is
>-                currently in the queue but not the primary owner, its flags are
>-                updated with the values from the new RequestName call.
>-              </para>
>-            </listitem>
>-
>-            <listitem>
>-              <para>
>-                If replacement is not possible, and the method caller is
>-                currently not in the queue, the method caller is appended to the
>-                queue.
>-              </para>
>-            </listitem>
>+                    <para>
>+                      For example,
>+                      <literal>path_namespace='/com/example/foo'</literal>
>+                      would match signals sent by
>+                      <literal>/com/example/foo</literal>
>+                      or by
>+                      <literal>/com/example/foo/bar</literal>,
>+                      but not by
>+                      <literal>/com/example/foobar</literal>.
>+                    </para>
> 
>-            <listitem>
>-              <para>
>-                If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
>-                set and is not the primary owner, it is removed from the
>-                queue. This can apply to the previous primary owner (if it
>-                was replaced) or the method caller (if it updated the
>-                DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
>-                queue, or if it was just added to the queue with that flag set).
>-              </para>
>-            </listitem>
>-          </itemizedlist>
>-        </para>
>-        <para>
>-          Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
>-          queue," even if another application already in the queue had specified
>-          DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
>-          that does not allow replacement goes away, and the next primary owner
>-          does allow replacement. In this case, queued items that specified
>-          DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
>-          automatically replace the new primary owner. In other words,
>-          DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
>-          time RequestName is called. This is deliberate to avoid an infinite loop
>-          anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
>-          and DBUS_NAME_FLAG_REPLACE_EXISTING.
>-        </para>
>-        <para>
>-          The flags argument contains any of the following values logically ORed
>-          together:
>+                    <para>
>+                      Using both <literal>path</literal> and
>+                      <literal>path_namespace</literal> in the same match
>+                      rule is not allowed.
>+                    </para>
> 
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>+                    <para>
>+                      <emphasis>
>+                        This match key was added in version 0.16 of the
>+                        D-Bus specification and implemented by the bus
>+                        daemon in dbus 1.5.0 and later.
>+                      </emphasis>
>+                    </para>
>+                </entry>
>+                </row>
>                 <row>
>-                  <entry>Conventional Name</entry>
>-                  <entry>Value</entry>
>-                  <entry>Description</entry>
>+                  <entry><literal>destination</literal></entry>
>+                  <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
>+                  <entry>Matches messages which are being sent to the given unique name. An
>+                  example of a destination match is destination=':1.0'</entry>
>                 </row>
>-              </thead>
>-              <tbody>
>                 <row>
>-                  <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
>-                  <entry>0x1</entry>
>+                  <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
>+                  <entry>Any string</entry>
>+                  <entry>Arg matches are special and are used for further restricting the
>+                  match based on the arguments in the body of a message. Only arguments of type
>+                  STRING can be matched in this way. An example of an argument match
>+                  would be arg3='Foo'. Only argument indexes from 0 to 63 should be
>+                  accepted.</entry>
>+                </row>
>+                <row>
>+                  <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
>+                  <entry>Any string</entry>
>                   <entry>
>+                    <para>Argument path matches provide a specialised form of wildcard matching for
>+                      path-like namespaces. They can match arguments whose type is either STRING or
>+                      OBJECT_PATH. As with normal argument matches,
>+                      if the argument is exactly equal to the string given in the match
>+                      rule then the rule is satisfied. Additionally, there is also a
>+                      match when either the string given in the match rule or the
>+                      appropriate message argument ends with '/' and is a prefix of the
>+                      other. An example argument path match is arg0path='/aa/bb/'. This
>+                      would match messages with first arguments of '/', '/aa/',
>+                      '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
>+                      messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
> 
>-                    If an application A specifies this flag and succeeds in
>-                    becoming the owner of the name, and another application B
>-                    later calls RequestName with the
>-                    DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
>-                    will lose ownership and receive a
>-                    <literal>org.freedesktop.DBus.NameLost</literal> signal, and
>-                    application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
>-                    is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
>-                    is not specified by application B, then application B will not replace
>-                    application A as the owner.
>-
>+                    <para>This is intended for monitoring âdirectoriesâ in file system-like
>+                      hierarchies, as used in the <citetitle>dconf</citetitle> configuration
>+                      system. An application interested in all nodes in a particular hierarchy would
>+                      monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
>+                      emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
>+                      represent a modification to the âbarâ property, or a signal with zeroth
>+                      argument <literal>"/ca/example/"</literal> to represent atomic modification of
>+                      many properties within that directory, and the interested application would be
>+                      notified in both cases.</para>
>+                    <para>
>+                      <emphasis>
>+                        This match key was added in version 0.12 of the
>+                        D-Bus specification, implemented for STRING
>+                        arguments by the bus daemon in dbus 1.2.0 and later,
>+                        and implemented for OBJECT_PATH arguments in dbus 1.5.0
>+                        and later.
>+                      </emphasis>
>+                    </para>
>                   </entry>
>                 </row>
>                 <row>
>-                  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
>-                  <entry>0x2</entry>
>+                  <entry><literal>arg0namespace</literal></entry>
>+                  <entry>Like a bus name, except that the string is not
>+                    required to contain a '.' (period)</entry>
>                   <entry>
>+                    <para>Match messages whose first argument is of type STRING, and is a bus name
>+                      or interface name within the specified namespace. This is primarily intended
>+                      for watching name owner changes for a group of related bus names, rather than
>+                      for a single name or all name changes.</para>
> 
>-                    Try to replace the current owner if there is one. If this
>-                    flag is not set the application will only become the owner of
>-                    the name if there is no current owner. If this flag is set,
>-                    the application will replace the current owner if
>-                    the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
>+                    <para>Because every valid interface name is also a valid
>+                      bus name, this can also be used for messages whose
>+                      first argument is an interface name.</para>
>+
>+                    <para>For example, the match rule
>+                      <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
>+                      matches name owner changes for bus names such as
>+                      <literal>com.example.backend1.foo</literal>,
>+                      <literal>com.example.backend1.foo.bar</literal>, and
>+                      <literal>com.example.backend1</literal> itself.</para>
> 
>+                    <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
>+                    <para>
>+                      <emphasis>
>+                        This match key was added in version 0.16 of the
>+                        D-Bus specification and implemented by the bus
>+                        daemon in dbus 1.5.0 and later.
>+                      </emphasis>
>+                    </para>
>                   </entry>
>                 </row>
>                 <row>
>-                  <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
>-                  <entry>0x4</entry>
>-                  <entry>
>-
>-                    Without this flag, if an application requests a name that is
>-                    already owned, the application will be placed in a queue to
>-                    own the name when the current owner gives it up. If this
>-                    flag is given, the application will not be placed in the
>-                    queue, the request for the name will simply fail.  This flag
>-                    also affects behavior when an application is replaced as
>-                    name owner; by default the application moves back into the
>-                    waiting queue, unless this flag was provided when the application
>-                    became the name owner.
>-
>+                  <entry><literal>eavesdrop</literal></entry>
>+                  <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
>+                  <entry>Since D-Bus 1.5.6, match rules do not
>+                    match messages which have a <literal>DESTINATION</literal>
>+                    field unless the match rule specifically
>+                    requests this
>+                    (see <xref linkend="message-bus-routing-eavesdropping"/>)
>+                    by specifying <literal>eavesdrop='true'</literal>
>+                    in the match rule.  <literal>eavesdrop='false'</literal>
>+                    restores the default behaviour. Messages are
>+                    delivered to their <literal>DESTINATION</literal>
>+                    regardless of match rules, so this match does not
>+                    affect normal delivery of unicast messages.
>+                    If the message bus has a security policy which forbids
>+                    eavesdropping, this match may still be used without error,
>+                    but will not have any practical effect.
>+                    In older versions of D-Bus, this match was not allowed
>+                    in match rules, and all match rules behaved as if
>+                    <literal>eavesdrop='true'</literal> had been used.
>                   </entry>
>                 </row>
>               </tbody>
>             </tgroup>
>           </informaltable>
>+        </para>
>+      </sect3>
>+    </sect2>
>+    <sect2 id="message-bus-starting-services">
>+      <title>Message Bus Starting Services (Activation)</title>
>+      <para>
>+        The message bus can start applications on behalf of other applications.
>+        This is referred to as <firstterm>service activation</firstterm> or
>+        <firstterm>activation</firstterm>.
>+        An application that can be started in this way is called a
>+        <firstterm>service</firstterm> or an
>+        <firstterm>activatable service</firstterm>.
>+      </para>
> 
>-          The return code can be one of the following values:
>+      <para>
>+        <firstterm>Starting a service</firstterm> should be read as synonymous
>+        with service activation.
>+      </para>
> 
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Conventional Name</entry>
>-                  <entry>Value</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
>-                  <entry>1</entry> <entry>The caller is now the primary owner of
>-                  the name, replacing any previous owner. Either the name had no
>-                  owner before, or the caller specified
>-                  DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
>-                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
>-                </row>
>-                <row>
>-                  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
>-                  <entry>2</entry>
>-
>-                  <entry>The name already had an owner,
>-                    DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
>-                    the current owner did not specify
>-                    DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
>-                    application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
>-                    </entry>
>-                </row>
>-                <row>
>-                  <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
>-                  <entry>The name already has an owner,
>-                  DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
>-                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
>-                  current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
>-                  specified by the requesting application.</entry>
>-                </row>
>-                <row>
>-                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
>-                  <entry>4</entry>
>-                  <entry>The application trying to request ownership of a name is already the owner of it.</entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-       </sect3>
>-
>-       <sect3 id="bus-messages-release-name">
>-        <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
>-        <para>
>-          As a method:
>-          <programlisting>
>-            UINT32 ReleaseName (in STRING name)
>-          </programlisting>
>-          Message arguments:
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>0</entry>
>-                  <entry>STRING</entry>
>-                  <entry>Name to release</entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-          Reply arguments:
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>0</entry>
>-                  <entry>UINT32</entry>
>-                  <entry>Return value</entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-        <para>
>-          This method call should be sent to
>-          <literal>org.freedesktop.DBus</literal> and asks the message bus to
>-          release the method caller's claim to the given name. If the caller is
>-          the primary owner, a new primary owner will be selected from the
>-          queue if any other owners are waiting. If the caller is waiting in
>-          the queue for the name, the caller will removed from the queue and
>-          will not be made an owner of the name if it later becomes available.
>-          If there are no other owners in the queue for the name, it will be
>-          removed from the bus entirely.
>-
>-          The return code can be one of the following values:
>-
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Conventional Name</entry>
>-                  <entry>Value</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
>-                  <entry>1</entry> <entry>The caller has released his claim on
>-                  the given name. Either the caller was the primary owner of
>-                  the name, and the name is now unused or taken by somebody
>-                  waiting in the queue for the name, or the caller was waiting
>-                  in the queue for the name and has now been removed from the
>-                  queue.</entry>
>-                </row>
>-                <row>
>-                  <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
>-                  <entry>2</entry>
>-                  <entry>The given name does not exist on this bus.</entry>
>-                </row>
>-                <row>
>-                  <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
>-                  <entry>3</entry>
>-                  <entry>The caller was not the primary owner of this name,
>-                  and was also not waiting in the queue to own this name.</entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-       </sect3>
>-
>-       <sect3 id="bus-messages-list-queued-owners">
>-        <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
>-        <para>
>-          As a method:
>-          <programlisting>
>-            ARRAY of STRING ListQueuedOwners (in STRING name)
>-          </programlisting>
>-          Message arguments:
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>0</entry>
>-                  <entry>STRING</entry>
>-                  <entry>The well-known bus name to query, such as
>-                    <literal>com.example.cappuccino</literal></entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-          Reply arguments:
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Argument</entry>
>-                  <entry>Type</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry>0</entry>
>-                  <entry>ARRAY of STRING</entry>
>-                  <entry>The unique bus names of connections currently queued
>-                    for the name</entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-        <para>
>-          This method call should be sent to
>-          <literal>org.freedesktop.DBus</literal> and lists the connections
>-          currently queued for a bus name (see
>-          <xref linkend="term-queued-owner"/>).
>-        </para>
>-       </sect3>
>-    </sect2>
>-
>-    <sect2 id="message-bus-routing">
>-      <title>Message Bus Message Routing</title>
>+      <para>
>+        In D-Bus, service activation is normally done by
>+        <firstterm>auto-starting</firstterm>.
>+        In auto-starting, applications send a
>+        message to a particular well-known name, such as
>+        <literal>com.example.TextEditor1</literal>, without specifying the
>+        <literal>NO_AUTO_START</literal> flag in the message header.
>+        If no application on the bus owns the requested name, but the bus
>+        daemon does know how to start an activatable service for that name,
>+        then the bus daemon will start that service, wait for it to request
>+        that name, and deliver the message to it.
>+      </para>
> 
>       <para>
>-        Messages may have a <literal>DESTINATION</literal> field (see <xref
>-          linkend="message-protocol-header-fields"/>), resulting in a
>-        <firstterm>unicast message</firstterm>.  If the
>-        <literal>DESTINATION</literal> field is present, it specifies a message
>-        recipient by name. Method calls and replies normally specify this field.
>-        The message bus must send messages (of any type) with the
>-        <literal>DESTINATION</literal> field set to the specified recipient,
>-        regardless of whether the recipient has set up a match rule matching
>-        the message.
>+        It is also possible for applications to send an explicit request to
>+        start a service: this is another form of activation, distinct from
>+        auto-starting. See
>+        <xref linkend="bus-messages-start-service-by-name"/> for details.
>       </para>
> 
>       <para>
>-        When the message bus receives a signal, if the
>-        <literal>DESTINATION</literal> field is absent, it is considered to
>-        be a <firstterm>broadcast signal</firstterm>, and is sent to all
>-        applications with <firstterm>message matching rules</firstterm> that
>-        match the message. Most signal messages are broadcasts, and
>-        no other message types currently defined in this specification
>-        may be broadcast.
>+        In either case, this implies a contract documented along with the name
>+        <literal>com.example.TextEditor1</literal> for which object
>+        the owner of that name will provide, and what interfaces those
>+        objects will have.
>       </para>
> 
>       <para>
>-        Unicast signal messages (those with a <literal>DESTINATION</literal>
>-        field) are not commonly used, but they are treated like any unicast
>-        message: they are delivered to the specified receipient,
>-        regardless of its match rules.  One use for unicast signals is to
>-        avoid a race condition in which a signal is emitted before the intended
>-        recipient can call <xref linkend="bus-messages-add-match"/> to
>-        receive that signal: if the signal is sent directly to that recipient
>-        using a unicast message, it does not need to add a match rule at all,
>-        and there is no race condition.  Another use for unicast signals,
>-        on message buses whose security policy prevents eavesdropping, is to
>-        send sensitive information which should only be visible to one
>-        recipient.
>+        To find an executable corresponding to a particular name, the bus daemon
>+        looks for <firstterm>service description files</firstterm>.  Service
>+        description files define a mapping from names to executables. Different
>+        kinds of message bus will look for these files in different places, see
>+        <xref linkend="message-bus-types"/>.
>       </para>
>-
>       <para>
>-        When the message bus receives a method call, if the
>-        <literal>DESTINATION</literal> field is absent, the call is taken to be
>-        a standard one-to-one message and interpreted by the message bus
>-        itself. For example, sending an
>-        <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
>-        <literal>DESTINATION</literal> will cause the message bus itself to
>-        reply to the ping immediately; the message bus will not make this
>-        message visible to other applications.
>+        Service description files have the ".service" file
>+        extension. The message bus will only load service description files
>+        ending with .service; all other files will be ignored.  The file format
>+        is similar to that of <ulink
>+        url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
>+        entries</ulink>. All service description files must be in UTF-8
>+        encoding. To ensure that there will be no name collisions, service files
>+        must be namespaced using the same mechanism as messages and service
>+        names.
>       </para>
> 
>       <para>
>-        Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
>-        the ping message were sent with a <literal>DESTINATION</literal> name of
>-        <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
>-        forwarded, and the Yoyodyne Corporation screensaver application would be
>-        expected to reply to the ping.
>+        On the well-known system bus, the name of a service description file
>+        must be its well-known name plus <literal>.service</literal>,
>+        for instance
>+        <literal>com.example.ConfigurationDatabase1.service</literal>.
>       </para>
> 
>       <para>
>-        Message bus implementations may impose a security policy which
>-        prevents certain messages from being sent or received.
>-        When a method call message cannot be sent or received due to a security
>-        policy, the message bus should send an error reply, unless the
>-        original message had the <literal>NO_REPLY</literal> flag.
>+        On the well-known session bus, services should follow the same
>+        service description file naming convention as on the system bus,
>+        but for backwards compatibility they are not required to do so.
>       </para>
> 
>-      <sect3 id="message-bus-routing-eavesdropping">
>-        <title>Eavesdropping</title>
>-        <para>
>-          Receiving a unicast message whose <literal>DESTINATION</literal>
>-          indicates a different recipient is called
>-          <firstterm>eavesdropping</firstterm>. On a message bus which acts as
>-          a security boundary (like the standard system bus), the security
>-          policy should usually prevent eavesdropping, since unicast messages
>-          are normally kept private and may contain security-sensitive
>-          information.
>-        </para>
>-
>-        <para>
>-          Eavesdropping is mainly useful for debugging tools, such as
>-          the <literal>dbus-monitor</literal> tool in the reference
>-          implementation of D-Bus. Tools which eavesdrop on the message bus
>-          should be careful to avoid sending a reply or error in response to
>-          messages intended for a different client.
>+      <para>
>+        [FIXME the file format should be much better specified than "similar to
>+        .desktop entries" esp. since desktop entries are already
>+        badly-specified. ;-)]
>+        These sections from the specification apply to service files as well:
>+
>+        <itemizedlist>
>+          <listitem><para>General syntax</para></listitem>
>+          <listitem><para>Comment format</para></listitem>
>+        </itemizedlist>
>+
>+        Service description files must contain a
>+        <literal>D-BUS Service</literal> group with at least the keys
>+        <literal>Name</literal> (the well-known name of the service)
>+        and <literal>Exec</literal> (the command to be executed).
>+
>+        <figure>
>+          <title>Example service description file</title>
>+          <programlisting>
>+            # Sample service description file
>+            [D-BUS Service]
>+            Name=com.example.ConfigurationDatabase1
>+            Exec=/usr/bin/sample-configd
>+          </programlisting>
>+        </figure>
>+      </para>
>+
>+      <para>
>+        Additionally, service description files for the well-known system
>+        bus on Unix must contain a <literal>User</literal> key, whose value
>+        is the name of a user account (e.g. <literal>root</literal>).
>+        The system service will be run as that user.
>+      </para>
>+
>+      <para>
>+        When an application asks to start a service by name, the bus daemon tries to
>+        find a service that will own that name. It then tries to spawn the
>+        executable associated with it. If this fails, it will report an
>+        error.
>+      </para>
>+
>+      <para>
>+        On the well-known system bus, it is not possible for two .service files
>+        in the same directory to offer the same service, because they are
>+        constrained to have names that match the service name.
>+      </para>
>+
>+      <para>
>+        On the well-known session bus, if two .service files in the same
>+        directory offer the same service name, the result is undefined.
>+        Distributors should avoid this situation, for instance by naming
>+        session services' .service files according to their service name.
>+      </para>
>+
>+      <para>
>+        If two .service files in different directories offer the same
>+        service name, the one in the higher-priority directory is used:
>+        for instance, on the system bus, .service files in
>+        /usr/local/share/dbus-1/system-services take precedence over those
>+        in /usr/share/dbus-1/system-services.
>+      </para>
>+      <para>
>+        The executable launched will have the environment variable
>+        <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
>+        message bus so it can connect and request the appropriate names.
>+      </para>
>+      <para>
>+        The executable being launched may want to know whether the message bus
>+        starting it is one of the well-known message buses (see <xref
>+        linkend="message-bus-types"/>). To facilitate this, the bus must also set
>+        the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
>+        of the well-known buses. The currently-defined values for this variable
>+        are <literal>system</literal> for the systemwide message bus,
>+        and <literal>session</literal> for the per-login-session message
>+        bus. The new executable must still connect to the address given
>+        in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
>+        resulting connection is to the well-known bus.
>+      </para>
>+      <para>
>+        [FIXME there should be a timeout somewhere, either specified
>+        in the .service file, by the client, or just a global value
>+        and if the client being activated fails to connect within that
>+        timeout, an error should be sent back.]
>+      </para>
>+
>+      <sect3 id="message-bus-starting-services-scope">
>+        <title>Message Bus Service Scope</title>
>+        <para>
>+          The "scope" of a service is its "per-", such as per-session,
>+          per-machine, per-home-directory, or per-display. The reference
>+          implementation doesn't yet support starting services in a different
>+          scope from the message bus itself. So e.g. if you start a service
>+          on the session bus its scope is per-session.
>+        </para>
>+        <para>
>+          We could add an optional scope to a bus name. For example, for
>+          per-(display,session pair), we could have a unique ID for each display
>+          generated automatically at login and set on screen 0 by executing a
>+          special "set display ID" binary. The ID would be stored in a
>+          <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
>+          random bytes. This ID would then be used to scope names.
>+          Starting/locating a service could be done by ID-name pair rather than
>+          only by name.
>+        </para>
>+        <para>
>+          Contrast this with a per-display scope. To achieve that, we would
>+          want a single bus spanning all sessions using a given display.
>+          So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
>+          property on screen 0 of the display, pointing to this bus.
>         </para>
>+      </sect3>
>+
>+      <sect3 id="message-bus-starting-services-systemd">
>+        <title>systemd Activation</title>
> 
>         <para>
>-          Clients may attempt to eavesdrop by adding match rules
>-          (see <xref linkend="message-bus-routing-match-rules"/>) containing
>-          the <literal>eavesdrop='true'</literal> match. If the message bus'
>-          security policy does not allow eavesdropping, the match rule can
>-          still be added, but will not have any practical effect. For
>-          compatibility with older message bus implementations, if adding such
>-          a match rule results in an error reply, the client may fall back to
>-          adding the same rule with the <literal>eavesdrop</literal> match
>-          omitted.
>+          Service description files may contain a
>+          <literal>SystemdService</literal> key. Its value is the name of a
>+          <ulink
>+            url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
>+          service, for example
>+          <literal>dbus-com.example.MyDaemon.service</literal>.
>         </para>
> 
>         <para>
>-          Eavesdropping interacts poorly with buses with non-trivial
>-          access control restrictions. The
>-          <xref linkend="bus-messages-become-monitor"/> method provides
>-          an alternative way to monitor buses.
>+          If this key is present, the bus daemon may carry out activation for
>+          this D-Bus service by sending a request to systemd asking it to
>+          start the systemd service whose name is the value of
>+          <literal>SystemdService</literal>. For example, the reference
>+          <literal>dbus-daemon</literal> has a
>+          <literal>--systemd-activation</literal> option that enables this
>+          feature, and that option is given when it is started by systemd.
>+        </para>
>+
>+        <para>
>+          On the well-known system bus, it is a common practice to set
>+          <literal>SystemdService</literal> to <literal>dbus-</literal>,
>+          followed by the well-known bus name, followed by
>+          <literal>.service</literal>, then register that name as an alias
>+          for the real systemd service. This allows D-Bus activation of a
>+          service to be enabled or disabled independently of whether the
>+          service is started by systemd during boot.
>         </para>
>       </sect3>
> 
>-      <sect3 id="message-bus-routing-match-rules">
>-        <title>Match Rules</title>
>+      <sect3 id="message-bus-starting-services-apparmor">
>+        <title>Mediating Activation with AppArmor</title>
>+
>         <para>
>-          An important part of the message bus routing protocol is match
>-          rules. Match rules describe the messages that should be sent to a
>-          client, based on the contents of the message.  Broadcast signals
>-          are only sent to clients which have a suitable match rule: this
>-          avoids waking up client processes to deal with signals that are
>-          not relevant to that client.
>+          Please refer to
>+          <ulink url="http://wiki.apparmor.net/index.php/Documentation">AppArmor documentation</ulink>
>+          for general information on AppArmor, and how it mediates D-Bus
>+          messages when used in conjunction with a kernel and
>+          <literal>dbus-daemon</literal> that support this.
>         </para>
>+
>         <para>
>-          Messages that list a client as their <literal>DESTINATION</literal>
>-          do not need to match the client's match rules, and are sent to that
>-          client regardless. As a result, match rules are mainly used to
>-          receive a subset of broadcast signals.
>+          In recent versions of the reference <literal>dbus-daemon</literal>,
>+          AppArmor policy rules of type <literal>dbus send</literal>
>+          are also used to control auto-starting: if a message is sent to
>+          the well-known name of an activatable service, the
>+          <literal>dbus-daemon</literal> will attempt to determine whether
>+          it would deliver the message to that service
>+          <emphasis>before</emphasis>auto-starting it, by making some
>+          assumptions about the resulting process's credentials.
>         </para>
>+
>         <para>
>-          Match rules can also be used for eavesdropping
>-          (see <xref linkend="message-bus-routing-eavesdropping"/>),
>-          if the security policy of the message bus allows it.
>+          If it does proceed with auto-starting, when the service appears, the
>+          <literal>dbus-daemon</literal> repeats the policy check (with
>+          the service's true credentials, which might not be identical)
>+          before delivering the message. In practice, this second check will
>+          usually be more strict than the first; the first check would only
>+          be more strict if there are "blacklist"-style rules like
>+          <literal>deny dbus send peer=(label=/usr/bin/protected)</literal>
>+          that match on the peer's specific credentials, but AppArmor is
>+          normally used in a "whitelist" style where this does not apply.
>         </para>
>+
>         <para>
>-          Match rules are added using the AddMatch bus method
>-          (see <xref linkend="bus-messages-add-match"/>).  Rules are
>-          specified as a string of comma separated key/value pairs.
>-          Excluding a key from the rule indicates a wildcard match.
>-          For instance excluding the the member from a match rule but
>-          adding a sender would let all messages from that sender through.
>-          An example of a complete rule would be
>-          "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
>+          To support this process, service description files may contain a
>+          <literal>AssumedAppArmorLabel</literal> key. Its value is the name
>+          of an AppArmor label, for example
>+          <literal>/usr/sbin/mydaemon</literal>.
>+          If present, AppArmor mediation of messages that auto-start a
>+          service will decide whether to allow auto-starting to occur based
>+          on the assumption that the activated service will be confined
>+          under the specified label; in particular, rules of the form
>+          <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
>+          <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
>+          will match it, allowing or denying as appropriate
>+          (even if there is in fact no profile of that name loaded).
>         </para>
>+
>         <para>
>-          Within single quotes (ASCII apostrophe, U+0027), a backslash
>-          (U+005C) represents itself, and an apostrophe ends the quoted
>-          section. Outside single quotes, \' (backslash, apostrophe)
>-          represents an apostrophe, and any backslash not followed by
>-          an apostrophe represents itself. For instance, the match rules
>-          <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
>-          <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
>-          both match messages where the arguments are a 1-character string
>-          containing an apostrophe, a 1-character string containing a
>-          backslash, a 1-character string containing a comma, and a
>-          2-character string containing two backslashes<footnote>
>-            <para>
>-              This idiosyncratic quoting style is based on the rules for
>-              escaping items to appear inside single-quoted strings
>-              in POSIX <literal>/bin/sh</literal>, but please
>-              note that backslashes that are not inside single quotes have
>-              different behaviour. This syntax does not offer any way to
>-              represent an apostrophe inside single quotes (it is necessary
>-              to leave the single-quoted section, backslash-escape the
>-              apostrophe and re-enter single quotes), or to represent a
>-              comma outside single quotes (it is necessary to wrap it in
>-              a single-quoted section).
>-            </para>
>-          </footnote>.
>+          Otherwise, AppArmor mediation of messages that auto-start a
>+          service will decide whether to allow auto-starting to occur
>+          without specifying any particular label. In particular, any rule of
>+          the form <literal>dbus send peer=(label=X)</literal> or
>+          <literal>deny dbus send peer=(label=X)</literal>
>+          (for any value of X, including the special label
>+          <literal>unconfined</literal>) will not influence whether the
>+          auto-start is allowed.
>         </para>
>-        <para>
>-          The following table describes the keys that can be used to create
>-          a match rule.
>-          <informaltable>
>-            <tgroup cols="3">
>-              <thead>
>-                <row>
>-                  <entry>Key</entry>
>-                  <entry>Possible Values</entry>
>-                  <entry>Description</entry>
>-                </row>
>-              </thead>
>-              <tbody>
>-                <row>
>-                  <entry><literal>type</literal></entry>
>-                  <entry>'signal', 'method_call', 'method_return', 'error'</entry>
>-                  <entry>Match on the message type.  An example of a type match is type='signal'</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>sender</literal></entry>
>-                  <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
>-                  and <xref linkend="term-unique-name"/> respectively)
>-                  </entry>
>-                  <entry>Match messages sent by a particular sender.  An example of a sender match
>-                  is sender='org.freedesktop.Hal'</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>interface</literal></entry>
>-                  <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
>-                  <entry>Match messages sent over or to a particular interface.  An example of an
>-                  interface match is interface='org.freedesktop.Hal.Manager'.
>-                  If a message omits the interface header, it must not match any rule
>-                  that specifies this key.</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>member</literal></entry>
>-                  <entry>Any valid method or signal name</entry>
>-                  <entry>Matches messages which have the give method or signal name. An example of
>-                  a member match is member='NameOwnerChanged'</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>path</literal></entry>
>-                  <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
>-                  <entry>Matches messages which are sent from or to the given object. An example of a
>-                  path match is path='/org/freedesktop/Hal/Manager'</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>path_namespace</literal></entry>
>-                  <entry>An object path</entry>
>-                  <entry>
>-                    <para>
>-                      Matches messages which are sent from or to an
>-                      object for which the object path is either the
>-                      given value, or that value followed by one or
>-                      more path components.
>-                    </para>
>-
>-                    <para>
>-                      For example,
>-                      <literal>path_namespace='/com/example/foo'</literal>
>-                      would match signals sent by
>-                      <literal>/com/example/foo</literal>
>-                      or by
>-                      <literal>/com/example/foo/bar</literal>,
>-                      but not by
>-                      <literal>/com/example/foobar</literal>.
>-                    </para>
>-
>-                    <para>
>-                      Using both <literal>path</literal> and
>-                      <literal>path_namespace</literal> in the same match
>-                      rule is not allowed.
>-                    </para>
>-
>-                    <para>
>-                      <emphasis>
>-                        This match key was added in version 0.16 of the
>-                        D-Bus specification and implemented by the bus
>-                        daemon in dbus 1.5.0 and later.
>-                      </emphasis>
>-                    </para>
>-                </entry>
>-                </row>
>-                <row>
>-                  <entry><literal>destination</literal></entry>
>-                  <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
>-                  <entry>Matches messages which are being sent to the given unique name. An
>-                  example of a destination match is destination=':1.0'</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
>-                  <entry>Any string</entry>
>-                  <entry>Arg matches are special and are used for further restricting the
>-                  match based on the arguments in the body of a message. Only arguments of type
>-                  STRING can be matched in this way. An example of an argument match
>-                  would be arg3='Foo'. Only argument indexes from 0 to 63 should be
>-                  accepted.</entry>
>-                </row>
>-                <row>
>-                  <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
>-                  <entry>Any string</entry>
>-                  <entry>
>-                    <para>Argument path matches provide a specialised form of wildcard matching for
>-                      path-like namespaces. They can match arguments whose type is either STRING or
>-                      OBJECT_PATH. As with normal argument matches,
>-                      if the argument is exactly equal to the string given in the match
>-                      rule then the rule is satisfied. Additionally, there is also a
>-                      match when either the string given in the match rule or the
>-                      appropriate message argument ends with '/' and is a prefix of the
>-                      other. An example argument path match is arg0path='/aa/bb/'. This
>-                      would match messages with first arguments of '/', '/aa/',
>-                      '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
>-                      messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
>-
>-                    <para>This is intended for monitoring âdirectoriesâ in file system-like
>-                      hierarchies, as used in the <citetitle>dconf</citetitle> configuration
>-                      system. An application interested in all nodes in a particular hierarchy would
>-                      monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
>-                      emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
>-                      represent a modification to the âbarâ property, or a signal with zeroth
>-                      argument <literal>"/ca/example/"</literal> to represent atomic modification of
>-                      many properties within that directory, and the interested application would be
>-                      notified in both cases.</para>
>-                    <para>
>-                      <emphasis>
>-                        This match key was added in version 0.12 of the
>-                        D-Bus specification, implemented for STRING
>-                        arguments by the bus daemon in dbus 1.2.0 and later,
>-                        and implemented for OBJECT_PATH arguments in dbus 1.5.0
>-                        and later.
>-                      </emphasis>
>-                    </para>
>-                  </entry>
>-                </row>
>-                <row>
>-                  <entry><literal>arg0namespace</literal></entry>
>-                  <entry>Like a bus name, except that the string is not
>-                    required to contain a '.' (period)</entry>
>-                  <entry>
>-                    <para>Match messages whose first argument is of type STRING, and is a bus name
>-                      or interface name within the specified namespace. This is primarily intended
>-                      for watching name owner changes for a group of related bus names, rather than
>-                      for a single name or all name changes.</para>
>-
>-                    <para>Because every valid interface name is also a valid
>-                      bus name, this can also be used for messages whose
>-                      first argument is an interface name.</para>
>-
>-                    <para>For example, the match rule
>-                      <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
>-                      matches name owner changes for bus names such as
>-                      <literal>com.example.backend1.foo</literal>,
>-                      <literal>com.example.backend1.foo.bar</literal>, and
>-                      <literal>com.example.backend1</literal> itself.</para>
>-
>-                    <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
>-                    <para>
>-                      <emphasis>
>-                        This match key was added in version 0.16 of the
>-                        D-Bus specification and implemented by the bus
>-                        daemon in dbus 1.5.0 and later.
>-                      </emphasis>
>-                    </para>
>-                  </entry>
>-                </row>
>-                <row>
>-                  <entry><literal>eavesdrop</literal></entry>
>-                  <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
>-                  <entry>Since D-Bus 1.5.6, match rules do not
>-                    match messages which have a <literal>DESTINATION</literal>
>-                    field unless the match rule specifically
>-                    requests this
>-                    (see <xref linkend="message-bus-routing-eavesdropping"/>)
>-                    by specifying <literal>eavesdrop='true'</literal>
>-                    in the match rule.  <literal>eavesdrop='false'</literal>
>-                    restores the default behaviour. Messages are
>-                    delivered to their <literal>DESTINATION</literal>
>-                    regardless of match rules, so this match does not
>-                    affect normal delivery of unicast messages.
>-                    If the message bus has a security policy which forbids
>-                    eavesdropping, this match may still be used without error,
>-                    but will not have any practical effect.
>-                    In older versions of D-Bus, this match was not allowed
>-                    in match rules, and all match rules behaved as if
>-                    <literal>eavesdrop='true'</literal> had been used.
>-                  </entry>
>-                </row>
>-              </tbody>
>-            </tgroup>
>-          </informaltable>
>-        </para>
>-      </sect3>
>-    </sect2>
>-    <sect2 id="message-bus-starting-services">
>-      <title>Message Bus Starting Services (Activation)</title>
>-      <para>
>-        The message bus can start applications on behalf of other applications.
>-        This is referred to as <firstterm>service activation</firstterm> or
>-        <firstterm>activation</firstterm>.
>-        An application that can be started in this way is called a
>-        <firstterm>service</firstterm> or an
>-        <firstterm>activatable service</firstterm>.
>-      </para>
>-
>-      <para>
>-        <firstterm>Starting a service</firstterm> should be read as synonymous
>-        with service activation.
>-      </para>
>-
>-      <para>
>-        In D-Bus, service activation is normally done by
>-        <firstterm>auto-starting</firstterm>.
>-        In auto-starting, applications send a
>-        message to a particular well-known name, such as
>-        <literal>com.example.TextEditor1</literal>, without specifying the
>-        <literal>NO_AUTO_START</literal> flag in the message header.
>-        If no application on the bus owns the requested name, but the bus
>-        daemon does know how to start an activatable service for that name,
>-        then the bus daemon will start that service, wait for it to request
>-        that name, and deliver the message to it.
>-      </para>
>-
>-      <para>
>-        It is also possible for applications to send an explicit request to
>-        start a service: this is another form of activation, distinct from
>-        auto-starting. See
>-        <xref linkend="bus-messages-start-service-by-name"/> for details.
>-      </para>
>-
>-      <para>
>-        In either case, this implies a contract documented along with the name
>-        <literal>com.example.TextEditor1</literal> for which object
>-        the owner of that name will provide, and what interfaces those
>-        objects will have.
>-      </para>
>-
>-      <para>
>-        To find an executable corresponding to a particular name, the bus daemon
>-        looks for <firstterm>service description files</firstterm>.  Service
>-        description files define a mapping from names to executables. Different
>-        kinds of message bus will look for these files in different places, see
>-        <xref linkend="message-bus-types"/>.
>-      </para>
>-      <para>
>-        Service description files have the ".service" file
>-        extension. The message bus will only load service description files
>-        ending with .service; all other files will be ignored.  The file format
>-        is similar to that of <ulink
>-        url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
>-        entries</ulink>. All service description files must be in UTF-8
>-        encoding. To ensure that there will be no name collisions, service files
>-        must be namespaced using the same mechanism as messages and service
>-        names.
>-      </para>
>-
>-      <para>
>-        On the well-known system bus, the name of a service description file
>-        must be its well-known name plus <literal>.service</literal>,
>-        for instance
>-        <literal>com.example.ConfigurationDatabase1.service</literal>.
>-      </para>
>-
>-      <para>
>-        On the well-known session bus, services should follow the same
>-        service description file naming convention as on the system bus,
>-        but for backwards compatibility they are not required to do so.
>-      </para>
>-
>-      <para>
>-        [FIXME the file format should be much better specified than "similar to
>-        .desktop entries" esp. since desktop entries are already
>-        badly-specified. ;-)]
>-        These sections from the specification apply to service files as well:
>-
>-        <itemizedlist>
>-          <listitem><para>General syntax</para></listitem>
>-          <listitem><para>Comment format</para></listitem>
>-        </itemizedlist>
>-
>-        Service description files must contain a
>-        <literal>D-BUS Service</literal> group with at least the keys
>-        <literal>Name</literal> (the well-known name of the service)
>-        and <literal>Exec</literal> (the command to be executed).
>-
>-        <figure>
>-          <title>Example service description file</title>
>-          <programlisting>
>-            # Sample service description file
>-            [D-BUS Service]
>-            Name=com.example.ConfigurationDatabase1
>-            Exec=/usr/bin/sample-configd
>-          </programlisting>
>-        </figure>
>-      </para>
>-
>-      <para>
>-        Additionally, service description files for the well-known system
>-        bus on Unix must contain a <literal>User</literal> key, whose value
>-        is the name of a user account (e.g. <literal>root</literal>).
>-        The system service will be run as that user.
>-      </para>
>-
>-      <para>
>-        When an application asks to start a service by name, the bus daemon tries to
>-        find a service that will own that name. It then tries to spawn the
>-        executable associated with it. If this fails, it will report an
>-        error.
>-      </para>
>-
>-      <para>
>-        On the well-known system bus, it is not possible for two .service files
>-        in the same directory to offer the same service, because they are
>-        constrained to have names that match the service name.
>-      </para>
>-
>-      <para>
>-        On the well-known session bus, if two .service files in the same
>-        directory offer the same service name, the result is undefined.
>-        Distributors should avoid this situation, for instance by naming
>-        session services' .service files according to their service name.
>-      </para>
>-
>-      <para>
>-        If two .service files in different directories offer the same
>-        service name, the one in the higher-priority directory is used:
>-        for instance, on the system bus, .service files in
>-        /usr/local/share/dbus-1/system-services take precedence over those
>-        in /usr/share/dbus-1/system-services.
>-      </para>
>-      <para>
>-        The executable launched will have the environment variable
>-        <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
>-        message bus so it can connect and request the appropriate names.
>-      </para>
>-      <para>
>-        The executable being launched may want to know whether the message bus
>-        starting it is one of the well-known message buses (see <xref
>-        linkend="message-bus-types"/>). To facilitate this, the bus must also set
>-        the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
>-        of the well-known buses. The currently-defined values for this variable
>-        are <literal>system</literal> for the systemwide message bus,
>-        and <literal>session</literal> for the per-login-session message
>-        bus. The new executable must still connect to the address given
>-        in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
>-        resulting connection is to the well-known bus.
>-      </para>
>-      <para>
>-        [FIXME there should be a timeout somewhere, either specified
>-        in the .service file, by the client, or just a global value
>-        and if the client being activated fails to connect within that
>-        timeout, an error should be sent back.]
>-      </para>
>-
>-      <sect3 id="message-bus-starting-services-scope">
>-        <title>Message Bus Service Scope</title>
>-        <para>
>-          The "scope" of a service is its "per-", such as per-session,
>-          per-machine, per-home-directory, or per-display. The reference
>-          implementation doesn't yet support starting services in a different
>-          scope from the message bus itself. So e.g. if you start a service
>-          on the session bus its scope is per-session.
>-        </para>
>-        <para>
>-          We could add an optional scope to a bus name. For example, for
>-          per-(display,session pair), we could have a unique ID for each display
>-          generated automatically at login and set on screen 0 by executing a
>-          special "set display ID" binary. The ID would be stored in a
>-          <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
>-          random bytes. This ID would then be used to scope names.
>-          Starting/locating a service could be done by ID-name pair rather than
>-          only by name.
>-        </para>
>-        <para>
>-          Contrast this with a per-display scope. To achieve that, we would
>-          want a single bus spanning all sessions using a given display.
>-          So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
>-          property on screen 0 of the display, pointing to this bus.
>-        </para>
>-      </sect3>
>-
>-      <sect3 id="message-bus-starting-services-systemd">
>-        <title>systemd Activation</title>
>-
>-        <para>
>-          Service description files may contain a
>-          <literal>SystemdService</literal> key. Its value is the name of a
>-          <ulink
>-            url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
>-          service, for example
>-          <literal>dbus-com.example.MyDaemon.service</literal>.
>-        </para>
>-
>-        <para>
>-          If this key is present, the bus daemon may carry out activation for
>-          this D-Bus service by sending a request to systemd asking it to
>-          start the systemd service whose name is the value of
>-          <literal>SystemdService</literal>. For example, the reference
>-          <literal>dbus-daemon</literal> has a
>-          <literal>--systemd-activation</literal> option that enables this
>-          feature, and that option is given when it is started by systemd.
>-        </para>
>-
>-        <para>
>-          On the well-known system bus, it is a common practice to set
>-          <literal>SystemdService</literal> to <literal>dbus-</literal>,
>-          followed by the well-known bus name, followed by
>-          <literal>.service</literal>, then register that name as an alias
>-          for the real systemd service. This allows D-Bus activation of a
>-          service to be enabled or disabled independently of whether the
>-          service is started by systemd during boot.
>-        </para>
>-      </sect3>
>-
>-      <sect3 id="message-bus-starting-services-apparmor">
>-        <title>Mediating Activation with AppArmor</title>
>-
>-        <para>
>-          Please refer to
>-          <ulink url="http://wiki.apparmor.net/index.php/Documentation">AppArmor documentation</ulink>
>-          for general information on AppArmor, and how it mediates D-Bus
>-          messages when used in conjunction with a kernel and
>-          <literal>dbus-daemon</literal> that support this.
>-        </para>
>-
>-        <para>
>-          In recent versions of the reference <literal>dbus-daemon</literal>,
>-          AppArmor policy rules of type <literal>dbus send</literal>
>-          are also used to control auto-starting: if a message is sent to
>-          the well-known name of an activatable service, the
>-          <literal>dbus-daemon</literal> will attempt to determine whether
>-          it would deliver the message to that service
>-          <emphasis>before</emphasis>auto-starting it, by making some
>-          assumptions about the resulting process's credentials.
>-        </para>
>-
>-        <para>
>-          If it does proceed with auto-starting, when the service appears, the
>-          <literal>dbus-daemon</literal> repeats the policy check (with
>-          the service's true credentials, which might not be identical)
>-          before delivering the message. In practice, this second check will
>-          usually be more strict than the first; the first check would only
>-          be more strict if there are "blacklist"-style rules like
>-          <literal>deny dbus send peer=(label=/usr/bin/protected)</literal>
>-          that match on the peer's specific credentials, but AppArmor is
>-          normally used in a "whitelist" style where this does not apply.
>-        </para>
>-
>-        <para>
>-          To support this process, service description files may contain a
>-          <literal>AssumedAppArmorLabel</literal> key. Its value is the name
>-          of an AppArmor label, for example
>-          <literal>/usr/sbin/mydaemon</literal>.
>-          If present, AppArmor mediation of messages that auto-start a
>-          service will decide whether to allow auto-starting to occur based
>-          on the assumption that the activated service will be confined
>-          under the specified label; in particular, rules of the form
>-          <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
>-          <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
>-          will match it, allowing or denying as appropriate
>-          (even if there is in fact no profile of that name loaded).
>-        </para>
>-
>-        <para>
>-          Otherwise, AppArmor mediation of messages that auto-start a
>-          service will decide whether to allow auto-starting to occur
>-          without specifying any particular label. In particular, any rule of
>-          the form <literal>dbus send peer=(label=X)</literal> or
>-          <literal>deny dbus send peer=(label=X)</literal>
>-          (for any value of X, including the special label
>-          <literal>unconfined</literal>) will not influence whether the
>-          auto-start is allowed.
>-        </para>
>-
>+
>         <para>
>           Rules of type <literal>dbus receive</literal> are not checked
>           when deciding whether to allow auto-starting; they are only checked
>@@ -5429,197 +5038,570 @@
>                 <para>the machine's ID</para>
>               </listitem>
> 
>-              <listitem>
>-                <para>the literal character '-' (dash)</para>
>-              </listitem>
>+              <listitem>
>+                <para>the literal character '-' (dash)</para>
>+              </listitem>
>+
>+              <listitem>
>+                <para>the X display without the screen number, with the
>+                following prefixes removed, if present: ":", "localhost:"
>+                ."localhost.localdomain:". That is, a display of
>+                "localhost:10.0" produces just the number "10"</para>
>+              </listitem>
>+            </itemizedlist>
>+          </para>
>+
>+          <para>
>+            The contents of this file NAME=value assignment pairs and
>+            lines starting with # are comments (no comments are allowed
>+            otherwise). The following variable names are defined:
>+            <informaltable
>+              frame="all">
>+              <tgroup cols="2">
>+                <tbody>
>+                  <row>
>+                    <entry>
>+                      <para>Variable</para>
>+                    </entry>
>+
>+                    <entry>
>+                      <para>meaning</para>
>+                    </entry>
>+                  </row>
>+
>+                  <row>
>+                    <entry>
>+                      <para>DBUS_SESSION_BUS_ADDRESS</para>
>+                    </entry>
>+
>+                    <entry>
>+                      <para>the actual address of the server socket</para>
>+                    </entry>
>+                  </row>
>+
>+                  <row>
>+                    <entry>
>+                      <para>DBUS_SESSION_BUS_PID</para>
>+                    </entry>
>+
>+                    <entry>
>+                      <para>the PID of the server process</para>
>+                    </entry>
>+                  </row>
>+
>+                  <row>
>+                    <entry>
>+                      <para>DBUS_SESSION_BUS_WINDOWID</para>
>+                    </entry>
>+
>+                    <entry>
>+                      <para>the window ID</para>
>+                    </entry>
>+                  </row>
>+                </tbody>
>+              </tgroup>
>+            </informaltable>
>+          </para>
>+
>+          <para>
>+            At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
>+            in this file.
>+          </para>
>+
>+          <para>
>+            Failure to open this file MUST be interpreted as absence of a
>+            running server. Therefore, the implementation MUST proceed to
>+            attempting to launch a new bus server if the file cannot be
>+            opened.
>+          </para>
>+
>+          <para>
>+            However, success in opening this file MUST NOT lead to the
>+            conclusion that the server is running. Thus, a failure to connect to
>+            the bus address obtained by the alternative method MUST NOT be
>+            considered a fatal error. If the connection cannot be established,
>+            the implementation MUST proceed to check the X selection settings or
>+            to start the server on its own.
>+          </para>
>+
>+          <para>
>+            If the implementation concludes that the D-Bus server is not
>+            running it MUST attempt to start a new server and it MUST also
>+            ensure that the daemon started as an effect of the "autolaunch"
>+            mechanism provides the lookup mechanisms described above, so
>+            subsequent calls can locate the newly started server. The
>+            implementation MUST also ensure that if two or more concurrent
>+            initiations happen, only one server remains running and all other
>+            initiations are able to obtain the address of this server and
>+            connect to it. In other words, the implementation MUST ensure that
>+            the X selection is not present when it attempts to set it, without
>+            allowing another process to set the selection between the
>+            verification and the setting (e.g., by using XGrabServer /
>+            XungrabServer).
>+          </para>
>+        </sect4>
>+        <sect4>
>+          <title>Finding session services</title>
>+          <para>
>+            On Unix systems, the session bus should search for .service files
>+            in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
>+            by the
>+            <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
>+            Implementations may also search additional locations,
>+            with a higher or lower priority than the XDG directories.
>+          </para>
>+          <para>
>+            As described in the XDG Base Directory Specification, software
>+            packages should install their session .service files to their
>+            configured <literal>${datadir}/dbus-1/services</literal>,
>+            where <literal>${datadir}</literal> is as defined by the GNU
>+            coding standards. System administrators or users can arrange
>+            for these service files to be read by setting XDG_DATA_DIRS or by
>+            symlinking them into the default locations.
>+          </para>
>+        </sect4>
>+      </sect3>
>+      <sect3 id="message-bus-types-system">
>+        <title>System message bus</title>
>+        <para>
>+          A computer may have a <firstterm>system message bus</firstterm>,
>+          accessible to all applications on the system. This message bus may be
>+          used to broadcast system events, such as adding new hardware devices,
>+          changes in the printer queue, and so forth.
>+        </para>
>+        <para>
>+          The address of the system message bus is given
>+          in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
>+          variable. If that variable is not set, applications should try
>+          to connect to the well-known address
>+          <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
>+          <footnote>
>+            <para>
>+              The D-Bus reference implementation actually honors the
>+              <literal>$(localstatedir)</literal> configure option
>+              for this address, on both client and server side.
>+            </para>
>+          </footnote>
>+        </para>
>+        <para>
>+          On Unix systems, the system bus should default to searching
>+          for .service files in
>+          <literal>/usr/local/share/dbus-1/system-services</literal>,
>+          <literal>/usr/share/dbus-1/system-services</literal> and
>+          <literal>/lib/dbus-1/system-services</literal>, with that order
>+          of precedence. It may also search other implementation-specific
>+          locations, but should not vary these locations based on environment
>+          variables.
>+          <footnote>
>+            <para>
>+              The system bus is security-sensitive and is typically executed
>+              by an init system with a clean environment. Its launch helper
>+              process is particularly security-sensitive, and specifically
>+              clears its own environment.
>+            </para>
>+          </footnote>
>+        </para>
>+        <para>
>+          Software packages should install their system .service
>+          files to their configured
>+          <literal>${datadir}/dbus-1/system-services</literal>,
>+          where <literal>${datadir}</literal> is as defined by the GNU
>+          coding standards. System administrators can arrange
>+          for these service files to be read by editing the system bus'
>+          configuration file or by symlinking them into the default
>+          locations.
>+        </para>
>+      </sect3>
>+    </sect2>
>+
>+    <sect2 id="message-bus-messages">
>+      <title>Message Bus Messages</title>
>+      <para>
>+        The special message bus name <literal>org.freedesktop.DBus</literal>
>+        responds to a number of additional messages.
>+      </para>
>+
>+      <sect3 id="bus-messages-hello">
>+        <title><literal>org.freedesktop.DBus.Hello</literal></title>
>+        <para>
>+          As a method:
>+          <programlisting>
>+            STRING Hello ()
>+          </programlisting>
>+          Reply arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>STRING</entry>
>+                  <entry>Unique name assigned to the connection</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+        </para>
>+        <para>
>+          Before an application is able to send messages to other applications
>+          it must send the <literal>org.freedesktop.DBus.Hello</literal> message
>+          to the message bus to obtain a unique name. If an application without
>+          a unique name tries to send a message to another application, or a
>+          message to the message bus itself that isn't the
>+          <literal>org.freedesktop.DBus.Hello</literal> message, it will be
>+          disconnected from the bus.
>+        </para>
>+        <para>
>+          There is no corresponding "disconnect" request; if a client wishes to
>+          disconnect from the bus, it simply closes the socket (or other
>+          communication channel).
>+        </para>
>+      </sect3>
>+      <sect3 id="bus-messages-request-name">
>+        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
>+        <para>
>+          As a method:
>+          <programlisting>
>+            UINT32 RequestName (in STRING name, in UINT32 flags)
>+          </programlisting>
>+          Message arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>STRING</entry>
>+                  <entry>Name to request</entry>
>+                </row>
>+                <row>
>+                  <entry>1</entry>
>+                  <entry>UINT32</entry>
>+                  <entry>Flags</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+          Reply arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>UINT32</entry>
>+                  <entry>Return value</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+        </para>
>+        <para>
>+          Ask the message bus to assign the given name to the method caller. Each
>+          name maintains a queue of possible owners, where the head of the queue is
>+          the primary or current owner of the name. Each potential owner in the
>+          queue maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
>+          DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName call.
>+          When RequestName is invoked the following occurs:
>+          <itemizedlist>
>+            <listitem>
>+              <para>
>+                If the method caller is currently the primary owner of the name,
>+                the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
>+                values are updated with the values from the new RequestName call,
>+                and nothing further happens.
>+              </para>
>+            </listitem>
>+
>+            <listitem>
>+              <para>
>+                If the current primary owner (head of the queue) has
>+                DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
>+                invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
>+                the caller of RequestName replaces the current primary owner at
>+                the head of the queue and the current primary owner moves to the
>+                second position in the queue. If the caller of RequestName was
>+                in the queue previously its flags are updated with the values from
>+                the new RequestName in addition to moving it to the head of the queue.
>+              </para>
>+            </listitem>
> 
>-              <listitem>
>-                <para>the X display without the screen number, with the
>-                following prefixes removed, if present: ":", "localhost:"
>-                ."localhost.localdomain:". That is, a display of
>-                "localhost:10.0" produces just the number "10"</para>
>-              </listitem>
>-            </itemizedlist>
>-          </para>
>+            <listitem>
>+              <para>
>+                If replacement is not possible, and the method caller is
>+                currently in the queue but not the primary owner, its flags are
>+                updated with the values from the new RequestName call.
>+              </para>
>+            </listitem>
> 
>-          <para>
>-            The contents of this file NAME=value assignment pairs and
>-            lines starting with # are comments (no comments are allowed
>-            otherwise). The following variable names are defined:
>-            <informaltable
>-              frame="all">
>-              <tgroup cols="2">
>-                <tbody>
>-                  <row>
>-                    <entry>
>-                      <para>Variable</para>
>-                    </entry>
>+            <listitem>
>+              <para>
>+                If replacement is not possible, and the method caller is
>+                currently not in the queue, the method caller is appended to the
>+                queue.
>+              </para>
>+            </listitem>
> 
>-                    <entry>
>-                      <para>meaning</para>
>-                    </entry>
>-                  </row>
>+            <listitem>
>+              <para>
>+                If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
>+                set and is not the primary owner, it is removed from the
>+                queue. This can apply to the previous primary owner (if it
>+                was replaced) or the method caller (if it updated the
>+                DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
>+                queue, or if it was just added to the queue with that flag set).
>+              </para>
>+            </listitem>
>+          </itemizedlist>
>+        </para>
>+        <para>
>+          Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
>+          queue," even if another application already in the queue had specified
>+          DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
>+          that does not allow replacement goes away, and the next primary owner
>+          does allow replacement. In this case, queued items that specified
>+          DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
>+          automatically replace the new primary owner. In other words,
>+          DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
>+          time RequestName is called. This is deliberate to avoid an infinite loop
>+          anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
>+          and DBUS_NAME_FLAG_REPLACE_EXISTING.
>+        </para>
>+        <para>
>+          The flags argument contains any of the following values logically ORed
>+          together:
> 
>-                  <row>
>-                    <entry>
>-                      <para>DBUS_SESSION_BUS_ADDRESS</para>
>-                    </entry>
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Conventional Name</entry>
>+                  <entry>Value</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
>+                  <entry>0x1</entry>
>+                  <entry>
> 
>-                    <entry>
>-                      <para>the actual address of the server socket</para>
>-                    </entry>
>-                  </row>
>+                    If an application A specifies this flag and succeeds in
>+                    becoming the owner of the name, and another application B
>+                    later calls RequestName with the
>+                    DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
>+                    will lose ownership and receive a
>+                    <literal>org.freedesktop.DBus.NameLost</literal> signal, and
>+                    application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
>+                    is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
>+                    is not specified by application B, then application B will not replace
>+                    application A as the owner.
> 
>-                  <row>
>-                    <entry>
>-                      <para>DBUS_SESSION_BUS_PID</para>
>-                    </entry>
>+                  </entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
>+                  <entry>0x2</entry>
>+                  <entry>
> 
>-                    <entry>
>-                      <para>the PID of the server process</para>
>-                    </entry>
>-                  </row>
>+                    Try to replace the current owner if there is one. If this
>+                    flag is not set the application will only become the owner of
>+                    the name if there is no current owner. If this flag is set,
>+                    the application will replace the current owner if
>+                    the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
> 
>-                  <row>
>-                    <entry>
>-                      <para>DBUS_SESSION_BUS_WINDOWID</para>
>-                    </entry>
>+                  </entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
>+                  <entry>0x4</entry>
>+                  <entry>
> 
>-                    <entry>
>-                      <para>the window ID</para>
>-                    </entry>
>-                  </row>
>-                </tbody>
>-              </tgroup>
>-            </informaltable>
>-          </para>
>+                    Without this flag, if an application requests a name that is
>+                    already owned, the application will be placed in a queue to
>+                    own the name when the current owner gives it up. If this
>+                    flag is given, the application will not be placed in the
>+                    queue, the request for the name will simply fail.  This flag
>+                    also affects behavior when an application is replaced as
>+                    name owner; by default the application moves back into the
>+                    waiting queue, unless this flag was provided when the application
>+                    became the name owner.
> 
>-          <para>
>-            At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
>-            in this file.
>-          </para>
>+                  </entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
> 
>-          <para>
>-            Failure to open this file MUST be interpreted as absence of a
>-            running server. Therefore, the implementation MUST proceed to
>-            attempting to launch a new bus server if the file cannot be
>-            opened.
>-          </para>
>+          The return code can be one of the following values:
> 
>-          <para>
>-            However, success in opening this file MUST NOT lead to the
>-            conclusion that the server is running. Thus, a failure to connect to
>-            the bus address obtained by the alternative method MUST NOT be
>-            considered a fatal error. If the connection cannot be established,
>-            the implementation MUST proceed to check the X selection settings or
>-            to start the server on its own.
>-          </para>
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Conventional Name</entry>
>+                  <entry>Value</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
>+                  <entry>1</entry> <entry>The caller is now the primary owner of
>+                  the name, replacing any previous owner. Either the name had no
>+                  owner before, or the caller specified
>+                  DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
>+                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
>+                  <entry>2</entry>
> 
>-          <para>
>-            If the implementation concludes that the D-Bus server is not
>-            running it MUST attempt to start a new server and it MUST also
>-            ensure that the daemon started as an effect of the "autolaunch"
>-            mechanism provides the lookup mechanisms described above, so
>-            subsequent calls can locate the newly started server. The
>-            implementation MUST also ensure that if two or more concurrent
>-            initiations happen, only one server remains running and all other
>-            initiations are able to obtain the address of this server and
>-            connect to it. In other words, the implementation MUST ensure that
>-            the X selection is not present when it attempts to set it, without
>-            allowing another process to set the selection between the
>-            verification and the setting (e.g., by using XGrabServer /
>-            XungrabServer).
>-          </para>
>-        </sect4>
>-        <sect4>
>-          <title>Finding session services</title>
>-          <para>
>-            On Unix systems, the session bus should search for .service files
>-            in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
>-            by the
>-            <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
>-            Implementations may also search additional locations,
>-            with a higher or lower priority than the XDG directories.
>-          </para>
>-          <para>
>-            As described in the XDG Base Directory Specification, software
>-            packages should install their session .service files to their
>-            configured <literal>${datadir}/dbus-1/services</literal>,
>-            where <literal>${datadir}</literal> is as defined by the GNU
>-            coding standards. System administrators or users can arrange
>-            for these service files to be read by setting XDG_DATA_DIRS or by
>-            symlinking them into the default locations.
>-          </para>
>-        </sect4>
>-      </sect3>
>-      <sect3 id="message-bus-types-system">
>-        <title>System message bus</title>
>-        <para>
>-          A computer may have a <firstterm>system message bus</firstterm>,
>-          accessible to all applications on the system. This message bus may be
>-          used to broadcast system events, such as adding new hardware devices,
>-          changes in the printer queue, and so forth.
>-        </para>
>-        <para>
>-          The address of the system message bus is given
>-          in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
>-          variable. If that variable is not set, applications should try
>-          to connect to the well-known address
>-          <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
>-          <footnote>
>-            <para>
>-              The D-Bus reference implementation actually honors the
>-              <literal>$(localstatedir)</literal> configure option
>-              for this address, on both client and server side.
>-            </para>
>-          </footnote>
>+                  <entry>The name already had an owner,
>+                    DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
>+                    the current owner did not specify
>+                    DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
>+                    application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
>+                    </entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
>+                  <entry>The name already has an owner,
>+                  DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
>+                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
>+                  current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
>+                  specified by the requesting application.</entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
>+                  <entry>4</entry>
>+                  <entry>The application trying to request ownership of a name is already the owner of it.</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>         </para>
>+       </sect3>
>+
>+       <sect3 id="bus-messages-release-name">
>+        <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
>         <para>
>-          On Unix systems, the system bus should default to searching
>-          for .service files in
>-          <literal>/usr/local/share/dbus-1/system-services</literal>,
>-          <literal>/usr/share/dbus-1/system-services</literal> and
>-          <literal>/lib/dbus-1/system-services</literal>, with that order
>-          of precedence. It may also search other implementation-specific
>-          locations, but should not vary these locations based on environment
>-          variables.
>-          <footnote>
>-            <para>
>-              The system bus is security-sensitive and is typically executed
>-              by an init system with a clean environment. Its launch helper
>-              process is particularly security-sensitive, and specifically
>-              clears its own environment.
>-            </para>
>-          </footnote>
>+          As a method:
>+          <programlisting>
>+            UINT32 ReleaseName (in STRING name)
>+          </programlisting>
>+          Message arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>STRING</entry>
>+                  <entry>Name to release</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+          Reply arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>UINT32</entry>
>+                  <entry>Return value</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>         </para>
>         <para>
>-          Software packages should install their system .service
>-          files to their configured
>-          <literal>${datadir}/dbus-1/system-services</literal>,
>-          where <literal>${datadir}</literal> is as defined by the GNU
>-          coding standards. System administrators can arrange
>-          for these service files to be read by editing the system bus'
>-          configuration file or by symlinking them into the default
>-          locations.
>-        </para>
>-      </sect3>
>-    </sect2>
>+          Ask the message bus to release the method caller's claim to the given
>+          name. If the caller is the primary owner, a new primary owner will be
>+          selected from the queue if any other owners are waiting. If the
>+          caller is waiting in the queue for the name, the caller will removed
>+          from the queue and will not be made an owner of the name if it later
>+          becomes available. If there are no other owners in the queue for the
>+          name, it will be removed from the bus entirely.
> 
>-    <sect2 id="message-bus-messages">
>-      <title>Message Bus Messages</title>
>-      <para>
>-        The special message bus name <literal>org.freedesktop.DBus</literal>
>-        responds to a number of additional messages.
>-      </para>
>+          The return code can be one of the following values:
> 
>-      <sect3 id="bus-messages-hello">
>-        <title><literal>org.freedesktop.DBus.Hello</literal></title>
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Conventional Name</entry>
>+                  <entry>Value</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
>+                  <entry>1</entry> <entry>The caller has released his claim on
>+                  the given name. Either the caller was the primary owner of
>+                  the name, and the name is now unused or taken by somebody
>+                  waiting in the queue for the name, or the caller was waiting
>+                  in the queue for the name and has now been removed from the
>+                  queue.</entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
>+                  <entry>2</entry>
>+                  <entry>The given name does not exist on this bus.</entry>
>+                </row>
>+                <row>
>+                  <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
>+                  <entry>3</entry>
>+                  <entry>The caller was not the primary owner of this name,
>+                  and was also not waiting in the queue to own this name.</entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+        </para>
>+       </sect3>
>+
>+       <sect3 id="bus-messages-list-queued-owners">
>+        <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
>         <para>
>           As a method:
>           <programlisting>
>-            STRING Hello ()
>+            ARRAY of STRING ListQueuedOwners (in STRING name)
>           </programlisting>
>-          Reply arguments:
>+          Message arguments:
>           <informaltable>
>             <tgroup cols="3">
>               <thead>
>@@ -5633,25 +5615,36 @@
>                 <row>
>                   <entry>0</entry>
>                   <entry>STRING</entry>
>-                  <entry>Unique name assigned to the connection</entry>
>+                  <entry>The well-known bus name to query, such as
>+                    <literal>com.example.cappuccino</literal></entry>
>+                </row>
>+              </tbody>
>+            </tgroup>
>+          </informaltable>
>+          Reply arguments:
>+          <informaltable>
>+            <tgroup cols="3">
>+              <thead>
>+                <row>
>+                  <entry>Argument</entry>
>+                  <entry>Type</entry>
>+                  <entry>Description</entry>
>+                </row>
>+              </thead>
>+              <tbody>
>+                <row>
>+                  <entry>0</entry>
>+                  <entry>ARRAY of STRING</entry>
>+                  <entry>The unique bus names of connections currently queued
>+                    for the name</entry>
>                 </row>
>               </tbody>
>             </tgroup>
>           </informaltable>
>         </para>
>         <para>
>-          Before an application is able to send messages to other applications
>-          it must send the <literal>org.freedesktop.DBus.Hello</literal> message
>-          to the message bus to obtain a unique name. If an application without
>-          a unique name tries to send a message to another application, or a
>-          message to the message bus itself that isn't the
>-          <literal>org.freedesktop.DBus.Hello</literal> message, it will be
>-          disconnected from the bus.
>-        </para>
>-        <para>
>-          There is no corresponding "disconnect" request; if a client wishes to
>-          disconnect from the bus, it simply closes the socket (or other
>-          communication channel).
>+          List the connections currently queued for a bus name (see
>+          <xref linkend="term-queued-owner"/>).
>         </para>
>       </sect3>
>       <sect3 id="bus-messages-list-names">
>-- 
>2.12.2
>

Actions: View | Splinter Review

Attachments on bug 100795: 131047 | 131048 | 131049 | 131166 | 131167

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.