Merge "Optional autogen.sh flag --enable-kdbus-transport added allowing to compile...

[platform/upstream/dbus.git] / doc / dbus-specification.xml
diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml

index dd4aa6a..673383a 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1,13 +1,13 @@
  <?xml version="1.0" standalone="no" ?>
  <?xml version="1.0" standalone="no" ?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
  [
  ]>
  <article id="index">
    <articleinfo>
      <title>D-Bus Specification</title>
  [
  ]>
  <article id="index">
    <articleinfo>
      <title>D-Bus Specification</title>
-    <releaseinfo>Version 0.15</releaseinfo>
-    <date>3 November 2010</date>
+    <releaseinfo>Version 0.22</releaseinfo>
+    <date>(not yet released)</date>
      <authorgroup>
        <author>
         <firstname>Havoc</firstname>
      <authorgroup>
        <author>
         <firstname>Havoc</firstname>
@@ -39,15 +39,89 @@
            </address>
         </affiliation>
        </author>
            </address>
         </affiliation>
        </author>
+      <author>
+       <firstname>Sven</firstname>
+       <surname>Herzberg</surname>
+       <affiliation>
+         <orgname>Imendio AB</orgname>
+         <address>
+            <email>sven@imendio.com</email>
+          </address>
+       </affiliation>
+      </author>
+      <author>
+        <firstname>Simon</firstname>
+        <surname>McVittie</surname>
+        <affiliation>
+          <orgname>Collabora Ltd.</orgname>
+          <address>
+            <email>simon.mcvittie@collabora.co.uk</email>
+          </address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>David</firstname>
+        <surname>Zeuthen</surname>
+        <affiliation>
+          <orgname>Red Hat, Inc.</orgname>
+          <address>
+            <email>davidz@redhat.com</email>
+          </address>
+        </affiliation>
+      </author>
      </authorgroup>
     <revhistory>
       <revision>
      </authorgroup>
     <revhistory>
       <revision>
-       <revnumber>current</revnumber>
-       <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
+       <revnumber>0.22</revnumber>
+       <date>not yet released (<ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink>)</date>
         <authorinitials></authorinitials>
         <revremark></revremark>
       </revision>
       <revision>
         <authorinitials></authorinitials>
         <revremark></revremark>
       </revision>
       <revision>
+       <revnumber>0.21</revnumber>
+       <date>2013-04-25</date>
+       <authorinitials>smcv</authorinitials>
+       <revremark>allow Unicode noncharacters in UTF-8 (Unicode
+         Corrigendum #9)</revremark>
+     </revision>
+     <revision>
+       <revnumber>0.20</revnumber>
+       <date>22 February 2013</date>
+       <authorinitials>smcv, walters</authorinitials>
+       <revremark>reorganise for clarity, remove false claims about
+         basic types, mention /o/fd/DBus</revremark>
+     </revision>
+     <revision>
+       <revnumber>0.19</revnumber>
+       <date>20 February 2012</date>
+       <authorinitials>smcv/lp</authorinitials>
+       <revremark>formally define unique connection names and well-known
+        bus names; document best practices for interface, bus, member and
+        error names, and object paths; document the search path for session
+        and system services on Unix; document the systemd transport</revremark>
+     </revision>
+     <revision>
+       <revnumber>0.18</revnumber>
+       <date>29 July 2011</date>
+       <authorinitials>smcv</authorinitials>
+       <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
+         match keyword; promote type system to a top-level section</revremark>
+     </revision>
+     <revision>
+       <revnumber>0.17</revnumber>
+       <date>1 June 2011</date>
+       <authorinitials>smcv/davidz</authorinitials>
+       <revremark>define ObjectManager; reserve extra pseudo-type-codes used
+         by GVariant</revremark>
+     </revision>
+     <revision>
+       <revnumber>0.16</revnumber>
+       <date>11 April 2011</date>
+       <authorinitials></authorinitials>
+       <revremark>add path_namespace, arg0namespace; argNpath matches object
+        paths</revremark>
+     </revision>
+     <revision>
         <revnumber>0.15</revnumber>
         <date>3 November 2010</date>
         <authorinitials></authorinitials>
         <revnumber>0.15</revnumber>
         <date>3 November 2010</date>
         <authorinitials></authorinitials>
@@ -220,43 +294,80 @@
      
    </sect1>
  
      
    </sect1>
  
-  <sect1 id="message-protocol">
-    <title>Message Protocol</title>
+  <sect1 id="type-system">
+    <title>Type System</title>
  
      <para>
  
      <para>
-      A <firstterm>message</firstterm> consists of a
-      <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
-      think of a message as a package, the header is the address, and the body
-      contains the package contents. The message delivery system uses the header
-      information to figure out where to send the message and how to interpret
-      it; the recipient interprets the body of the message.
+      D-Bus has a type system, in which values of various types can be
+      serialized into a sequence of bytes referred to as the
+      <firstterm>wire format</firstterm> in a standard way.
+      Converting a value from some other representation into the wire
+      format is called <firstterm>marshaling</firstterm> and converting
+      it back from the wire format is <firstterm>unmarshaling</firstterm>.
      </para>
      </para>
-    
+
      <para>
      <para>
-      The body of the message is made up of zero or more
-      <firstterm>arguments</firstterm>, which are typed values, such as an
-      integer or a byte array.
+      The D-Bus protocol does not include type tags in the marshaled data; a
+      block of marshaled values must have a known <firstterm>type
+        signature</firstterm>. The type signature is made up of zero or more
+      <firstterm id="term-single-complete-type">single complete
+        types</firstterm>, each made up of one or more
+      <firstterm>type codes</firstterm>.
      </para>
  
      <para>
      </para>
  
      <para>
-      Both header and body use the same type system and format for 
-      serializing data. Each type of value has a wire format. 
-      Converting a value from some other representation into the wire
-      format is called <firstterm>marshaling</firstterm> and converting
-      it back from the wire format is <firstterm>unmarshaling</firstterm>.
+      A type code is an ASCII character representing the
+      type of a value. Because ASCII characters are used, the type signature
+      will always form a valid ASCII string. A simple string compare
+      determines whether two type signatures are equivalent.
+    </para>
+
+    <para>
+      A single complete type is a sequence of type codes that fully describes
+      one type: either a basic type, or a single fully-described container type.
+      A single complete type is a basic type code, a variant type code,
+      an array with its element type, or a struct with its fields (all of which
+      are defined below). So the following signatures are not single complete
+      types:
+      <programlisting>
+        "aa"
+      </programlisting>
+      <programlisting>
+        "(ii"
+      </programlisting>
+      <programlisting>
+        "ii)"
+      </programlisting>
+      And the following signatures contain multiple complete types:
+      <programlisting>
+        "ii"
+      </programlisting>
+      <programlisting>
+        "aiai"
+      </programlisting>
+      <programlisting>
+        "(ii)(ii)"
+      </programlisting>
+      Note however that a single complete type may <emphasis>contain</emphasis>
+      multiple other single complete types, by containing a struct or dict
+      entry.
      </para>
  
      </para>
  
-    <sect2 id="message-protocol-signatures">
-      <title>Type Signatures</title>
+    <sect2 id="basic-types">
+      <title>Basic types</title>
+
+      <para>
+        The simplest type codes are the <firstterm id="term-basic-type">basic
+          types</firstterm>, which are the types whose structure is entirely
+        defined by their 1-character type code. Basic types consist of
+        fixed types and string-like types.
+      </para>
  
        <para>
  
        <para>
-        The D-Bus protocol does not include type tags in the marshaled data; a
-        block of marshaled values must have a known <firstterm>type
-        signature</firstterm>.  The type signature is made up of <firstterm>type
-        codes</firstterm>. A type code is an ASCII character representing the
-        type of a value. Because ASCII characters are used, the type signature
-        will always form a valid ASCII string. A simple string compare 
-        determines whether two type signatures are equivalent.
+        The <firstterm id="term-fixed-type">fixed types</firstterm>
+        are basic types whose values have a fixed length, namely BYTE,
+        BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
+        16, 32 or 64 bits.
        </para>
  
        <para>
        </para>
  
        <para>
@@ -273,10 +384,267 @@
        </para>
  
        <para>
        </para>
  
        <para>
-        All <firstterm>basic</firstterm> types work like 
-        <literal>INT32</literal> in this example. To marshal and unmarshal 
-        basic types, you simply read one value from the data
-        block corresponding to each type code in the signature.
+        The characteristics of the fixed types are listed in this table.
+
+        <informaltable>
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry>Conventional name</entry>
+                <entry>ASCII type-code</entry>
+                <entry>Encoding</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><literal>BYTE</literal></entry>
+                <entry><literal>y</literal> (121)</entry>
+                <entry>Unsigned 8-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>BOOLEAN</literal></entry>
+                <entry><literal>b</literal> (98)</entry>
+                <entry>Boolean value: 0 is false, 1 is true, any other value
+                  allowed by the marshalling format is invalid</entry>
+              </row>
+              <row>
+                <entry><literal>INT16</literal></entry>
+                <entry><literal>n</literal> (110)</entry>
+                <entry>Signed (two's complement) 16-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>UINT16</literal></entry>
+                <entry><literal>q</literal> (113)</entry>
+                <entry>Unsigned 16-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>INT32</literal></entry>
+                <entry><literal>i</literal> (105)</entry>
+                <entry>Signed (two's complement) 32-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>UINT32</literal></entry>
+                <entry><literal>u</literal> (117)</entry>
+                <entry>Unsigned 32-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>INT64</literal></entry>
+                <entry><literal>x</literal> (120)</entry>
+                <entry>Signed (two's complement) 64-bit integer
+                  (mnemonic: x and t are the first characters in "sixty" not
+                  already used for something more common)</entry>
+              </row>
+              <row>
+                <entry><literal>UINT64</literal></entry>
+                <entry><literal>t</literal> (116)</entry>
+                <entry>Unsigned 64-bit integer</entry>
+              </row>
+              <row>
+                <entry><literal>DOUBLE</literal></entry>
+                <entry><literal>d</literal> (100)</entry>
+                <entry>IEEE 754 double-precision floating point</entry>
+              </row>
+              <row>
+                <entry><literal>UNIX_FD</literal></entry>
+                <entry><literal>h</literal> (104)</entry>
+                <entry>Unsigned 32-bit integer representing an index into an
+                  out-of-band array of file descriptors, transferred via some
+                  platform-specific mechanism (mnemonic: h for handle)</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+
+      <para>
+        The <firstterm id="term-string-like-type">string-like types</firstterm>
+        are basic types with a variable length. The value of any string-like
+        type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
+        none of which may be U+0000. The UTF-8 text must be validated
+        strictly: in particular, it must not contain overlong sequences
+        or codepoints above U+10FFFF.
+      </para>
+
+      <para>
+        Since D-Bus Specification version 0.21, in accordance with Unicode
+        Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and
+        U+nFFFF are allowed in UTF-8 strings (but note that older versions of
+        D-Bus rejected these noncharacters).
+      </para>
+
+      <para>
+        The marshalling formats for the string-like types all end with a
+        single zero (NUL) byte, but that byte is not considered to be part of
+        the text.
+      </para>
+
+      <para>
+        The characteristics of the string-like types are listed in this table.
+
+        <informaltable>
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry>Conventional name</entry>
+                <entry>ASCII type-code</entry>
+                <entry>Validity constraints</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><literal>STRING</literal></entry>
+                <entry><literal>s</literal> (115)</entry>
+                <entry>No extra constraints</entry>
+              </row>
+              <row>
+                <entry><literal>OBJECT_PATH</literal></entry>
+                <entry><literal>o</literal> (111)</entry>
+                <entry>Must be
+                  <link linkend="message-protocol-marshaling-object-path">a
+                    syntactically valid object path</link></entry>
+              </row>
+              <row>
+                <entry><literal>SIGNATURE</literal></entry>
+                <entry><literal>g</literal> (103)</entry>
+                <entry>Zero or more
+                  <firstterm linkend="term-single-complete-type">single
+                    complete types</firstterm></entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+
+      <sect3 id="message-protocol-marshaling-object-path">
+        <title>Valid Object Paths</title>
+
+        <para>
+          An object path is a name used to refer to an object instance.
+          Conceptually, each participant in a D-Bus message exchange may have
+          any number of object instances (think of C++ or Java objects) and each
+          such instance will have a path. Like a filesystem, the object
+          instances in an application form a hierarchical tree.
+        </para>
+
+        <para>
+          Object paths are often namespaced by starting with a reversed
+          domain name and containing an interface version number, in the
+          same way as
+          <link linkend="message-protocol-names-interface">interface
+            names</link> and
+          <link linkend="message-protocol-names-bus">well-known
+            bus names</link>.
+          This makes it possible to implement more than one service, or
+          more than one version of a service, in the same process,
+          even if the services share a connection but cannot otherwise
+          co-operate (for instance, if they are implemented by different
+          plugins).
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might use the
+          hierarchy of object paths that start with
+          <literal>/com/example/MusicPlayer1</literal> for its objects.
+        </para>
+
+        <para>
+          The following rules define a valid object path. Implementations must
+          not send or accept messages with invalid object paths.
+          <itemizedlist>
+            <listitem>
+              <para>
+                The path may be of any length.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The path must begin with an ASCII '/' (integer 47) character,
+                and must consist of elements separated by slash characters.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                Each element must only contain the ASCII characters
+                "[A-Z][a-z][0-9]_"
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                No element may be the empty string.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                Multiple '/' characters cannot occur in sequence.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                A trailing '/' character is not allowed unless the
+                path is the root path (a single '/' character).
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+
+      </sect3>
+
+      <sect3 id="message-protocol-marshaling-signature">
+        <title>Valid Signatures</title>
+        <para>
+          An implementation must not send or accept invalid signatures.
+          Valid signatures will conform to the following rules:
+          <itemizedlist>
+            <listitem>
+              <para>
+                The signature is a list of single complete types.
+                Arrays must have element types, and structs must
+                have both open and close parentheses.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                Only type codes, open and close parentheses, and open and
+                close curly brackets are allowed in the signature. The
+                <literal>STRUCT</literal> type code
+                is not allowed in signatures, because parentheses
+                are used instead. Similarly, the
+                <literal>DICT_ENTRY</literal> type code is not allowed in
+                signatures, because curly brackets are used instead.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The maximum depth of container type nesting is 32 array type
+                codes and 32 open parentheses. This implies that the maximum
+                total depth of recursion is 64, for an "array of array of array
+                of ... struct of struct of struct of ..."  where there are 32
+                array and 32 struct.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The maximum length of a signature is 255.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+
+        <para>
+          When signatures appear in messages, the marshalling format
+          guarantees that they will be followed by a nul byte (which can
+          be interpreted as either C-style string termination or the INVALID
+          type-code), but this is not conceptually part of the signature.
+        </para>
+      </sect3>
+
+    </sect2>
+
+    <sect2 id="container-types">
+      <title>Container types</title>
+
+      <para>
          In addition to basic types, there are four <firstterm>container</firstterm> 
          types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>, 
          and <literal>DICT_ENTRY</literal>.
          In addition to basic types, there are four <firstterm>container</firstterm> 
          types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>, 
          and <literal>DICT_ENTRY</literal>.
@@ -332,34 +700,6 @@
        </para>
  
        <para>
        </para>
  
        <para>
-        The phrase <firstterm>single complete type</firstterm> deserves some 
-        definition. A single complete type is a basic type code, a variant type code, 
-        an array with its element type, or a struct with its fields. 
-        So the following signatures are not single complete types:
-        <programlisting>
-          "aa"
-        </programlisting>
-        <programlisting>
-          "(ii"
-        </programlisting>
-        <programlisting>
-          "ii)"
-        </programlisting>
-        And the following signatures contain multiple complete types:
-        <programlisting>
-          "ii"
-        </programlisting>
-        <programlisting>
-          "aiai"
-        </programlisting>
-        <programlisting>
-          "(ii)(ii)"
-        </programlisting>
-        Note however that a single complete type may <emphasis>contain</emphasis>
-        multiple other single complete types.
-      </para>
-
-      <para>
          <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
          type <literal>VARIANT</literal> will have the signature of a single complete type as part
          of the <emphasis>value</emphasis>.  This signature will be followed by a
          <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
          type <literal>VARIANT</literal> will have the signature of a single complete type as part
          of the <emphasis>value</emphasis>.  This signature will be followed by a
@@ -367,6 +707,14 @@
        </para>
  
        <para>
        </para>
  
        <para>
+        Unlike a message signature, the variant signature can
+        contain only a single complete type.  So "i", "ai"
+        or "(ii)" is OK, but "ii" is not.  Use of variants may not
+        cause a total message depth to be larger than 64, including
+        other container types such as structures.
+      </para>
+
+      <para>
          A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
          than parentheses it uses curly braces, and it has more restrictions.
          The restrictions are: it occurs only as an array element type; it has
          A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
          than parentheses it uses curly braces, and it has more restrictions.
          The restrictions are: it occurs only as an array element type; it has
@@ -389,6 +737,10 @@
          In most languages, an array of dict entry would be represented as a 
          map, hash table, or dict object.
        </para>
          In most languages, an array of dict entry would be represented as a 
          map, hash table, or dict object.
        </para>
+    </sect2>
+
+    <sect2>
+      <title>Summary of types</title>
  
        <para>
          The following table summarizes the D-Bus types.
  
        <para>
          The following table summarizes the D-Bus types.
@@ -461,7 +813,10 @@
                </row><row>
                  <entry><literal>STRUCT</literal></entry>
                  <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
                </row><row>
                  <entry><literal>STRUCT</literal></entry>
                  <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
-                <entry>Struct</entry>
+                <entry>Struct; type code 114 'r' is reserved for use in
+                  bindings and implementations to represent the general
+                  concept of a struct, and must not appear in signatures
+                  used on D-Bus.</entry>
                </row><row>
                  <entry><literal>VARIANT</literal></entry>
                  <entry>118 (ASCII 'v') </entry>
                </row><row>
                  <entry><literal>VARIANT</literal></entry>
                  <entry>118 (ASCII 'v') </entry>
@@ -469,21 +824,69 @@
                </row><row>
                  <entry><literal>DICT_ENTRY</literal></entry>
                  <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
                </row><row>
                  <entry><literal>DICT_ENTRY</literal></entry>
                  <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
-                <entry>Entry in a dict or map (array of key-value pairs)</entry>
+                <entry>Entry in a dict or map (array of key-value pairs).
+                  Type code 101 'e' is reserved for use in bindings and
+                  implementations to represent the general concept of a
+                  dict or dict-entry, and must not appear in signatures
+                  used on D-Bus.</entry>
                </row><row>
                  <entry><literal>UNIX_FD</literal></entry>
                  <entry>104 (ASCII 'h')</entry>
                  <entry>Unix file descriptor</entry>
                </row>
                </row><row>
                  <entry><literal>UNIX_FD</literal></entry>
                  <entry>104 (ASCII 'h')</entry>
                  <entry>Unix file descriptor</entry>
                </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>109 (ASCII 'm')</entry>
+                <entry>Reserved for <ulink
+                    url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
+                  'maybe' type compatible with the one in GVariant</ulink>,
+                  and must not appear in signatures used on D-Bus until
+                  specified here</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>42 (ASCII '*')</entry>
+                <entry>Reserved for use in bindings/implementations to
+                  represent any <firstterm>single complete type</firstterm>,
+                  and must not appear in signatures used on D-Bus.</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>63 (ASCII '?')</entry>
+                <entry>Reserved for use in bindings/implementations to
+                  represent any <firstterm>basic type</firstterm>, and must
+                  not appear in signatures used on D-Bus.</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>64 (ASCII '@'), 38 (ASCII '&amp;'),
+                  94 (ASCII '^')</entry>
+                <entry>Reserved for internal use by bindings/implementations,
+                  and must not appear in signatures used on D-Bus.
+                  GVariant uses these type-codes to encode calling
+                  conventions.</entry>
+              </row>
              </tbody>
            </tgroup>
          </informaltable>
        </para>
  
      </sect2>
              </tbody>
            </tgroup>
          </informaltable>
        </para>
  
      </sect2>
+  </sect1>
+
+  <sect1 id="message-protocol-marshaling">
+    <title>Marshaling (Wire Format)</title>
+
+    <para>
+      D-Bus defines a marshalling format for its type system, which is
+      used in D-Bus messages. This is not the only possible marshalling
+      format for the type system: for instance, GVariant (part of GLib)
+      re-uses the D-Bus type system but implements an alternative marshalling
+      format.
+    </para>
  
  
-    <sect2 id="message-protocol-marshaling">
-      <title>Marshaling (Wire Format)</title>
+    <sect2>
+      <title>Byte order and alignment</title>
  
        <para>
          Given a type signature, a block of bytes can be converted into typed
  
        <para>
          Given a type signature, a block of bytes can be converted into typed
@@ -492,11 +895,11 @@
        </para>
  
        <para>
        </para>
  
        <para>
-        A block of bytes has an associated byte order. The byte order 
-        has to be discovered in some way; for D-Bus messages, the 
-        byte order is part of the message header as described in 
-        <xref linkend="message-protocol-messages"/>. For now, assume 
-        that the byte order is known to be either little endian or big 
+        A block of bytes has an associated byte order. The byte order
+        has to be discovered in some way; for D-Bus messages, the
+        byte order is part of the message header as described in
+        <xref linkend="message-protocol-messages"/>. For now, assume
+        that the byte order is known to be either little endian or big
            endian.
        </para>
  
            endian.
        </para>
  
@@ -512,6 +915,95 @@
        </para>
  
        <para>
        </para>
  
        <para>
+        As an exception to natural alignment, <literal>STRUCT</literal> and
+        <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
+        boundary, regardless of the alignments of their contents.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Marshalling basic types</title>
+
+      <para>
+        To marshal and unmarshal fixed types, you simply read one value
+        from the data block corresponding to each type code in the signature.
+        All signed integer values are encoded in two's complement, DOUBLE
+        values are IEEE 754 double-precision floating-point, and BOOLEAN
+        values are encoded in 32 bits (of which only the least significant
+        bit is used).
+      </para>
+
+      <para>
+        The string-like types are all marshalled as a
+        fixed-length unsigned integer <varname>n</varname> giving the
+        length of the variable part, followed by <varname>n</varname>
+        nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
+        which is not considered to be part of the text. The alignment
+        of the string-like type is the same as the alignment of
+        <varname>n</varname>.
+      </para>
+
+      <para>
+        For the STRING and OBJECT_PATH types, <varname>n</varname> is
+        encoded in 4 bytes, leading to 4-byte alignment.
+        For the SIGNATURE type, <varname>n</varname> is encoded as a single
+        byte. As a result, alignment padding is never required before a
+        SIGNATURE.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Marshalling containers</title>
+
+      <para>
+        Arrays are marshalled as a <literal>UINT32</literal>
+        <varname>n</varname> giving the length of the array data in bytes,
+        followed by alignment padding to the alignment boundary of the array
+        element type, followed by the <varname>n</varname> bytes of the
+        array elements marshalled in sequence. <varname>n</varname> does not
+        include the padding after the length, or any padding after the
+        last element.
+      </para>
+
+      <para>
+        For instance, if the current position in the message is a multiple
+        of 8 bytes and the byte-order is big-endian, an array containing only
+        the 64-bit integer 5 would be marshalled as:
+
+        <screen>
+00 00 00 08               <lineannotation>8 bytes of data</lineannotation>
+00 00 00 00               <lineannotation>padding to 8-byte boundary</lineannotation>
+00 00 00 00  00 00 00 05  <lineannotation>first element = 5</lineannotation>
+        </screen>
+      </para>
+
+      <para>
+        Arrays have a maximum length defined to be 2 to the 26th power or
+        67108864. Implementations must not send or accept arrays exceeding this
+        length.
+      </para>
+
+      <para>
+        Structs and dict entries are marshalled in the same way as their
+        contents, but their alignment is always to an 8-byte boundary,
+        even if their contents would normally be less strictly aligned.
+      </para>
+
+      <para>
+        Variants are marshalled as the <literal>SIGNATURE</literal> of
+        the contents (which must be a single complete type), followed by a
+        marshalled value with the type given by that signature. The
+        variant has the same 1-byte alignment as the signature, which means
+        that alignment padding before a variant is never needed.
+        Use of variants may not cause a total message depth to be larger
+        than 64, including other container types such as structures.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Summary of D-Bus marshalling</title>
+
+      <para>
          Given all this, the types are marshaled on the wire as follows:
          <informaltable>
            <tgroup cols="3">
          Given all this, the types are marshaled on the wire as follows:
          <informaltable>
            <tgroup cols="3">
@@ -576,7 +1068,7 @@
                </row><row>
                  <entry><literal>OBJECT_PATH</literal></entry>
                  <entry>Exactly the same as <literal>STRING</literal> except the 
                </row><row>
                  <entry><literal>OBJECT_PATH</literal></entry>
                  <entry>Exactly the same as <literal>STRING</literal> except the 
-                  content must be a valid object path (see below).
+                  content must be a valid object path (see above).
                  </entry>
                  <entry>
                    4 (for the length)
                  </entry>
                  <entry>
                    4 (for the length)
@@ -585,7 +1077,7 @@
                  <entry><literal>SIGNATURE</literal></entry>
                  <entry>The same as <literal>STRING</literal> except the length is a single 
                    byte (thus signatures have a maximum length of 255)
                  <entry><literal>SIGNATURE</literal></entry>
                  <entry>The same as <literal>STRING</literal> except the length is a single 
                    byte (thus signatures have a maximum length of 255)
-                  and the content must be a valid signature (see below).
+                  and the content must be a valid signature (see above).
                  </entry>
                  <entry>
                    1
                  </entry>
                  <entry>
                    1
@@ -594,14 +1086,8 @@
                  <entry><literal>ARRAY</literal></entry>
                  <entry>
                    A <literal>UINT32</literal> giving the length of the array data in bytes, followed by 
                  <entry><literal>ARRAY</literal></entry>
                  <entry>
                    A <literal>UINT32</literal> giving the length of the array data in bytes, followed by 
-                  alignment padding to the alignment boundary of the array element type, 
-                  followed by each array element. The array length is from the 
-                  end of the alignment padding to the end of the last element,
-                  i.e. it does not include the padding after the length,
-                  or any padding after the last element.
-                  Arrays have a maximum length defined to be 2 to the 26th power or
-                  67108864. Implementations must not send or accept arrays exceeding this
-                  length.
+                  alignment padding to the alignment boundary of the array element type,
+                  followed by each array element.
                  </entry>
                  <entry>
                    4 (for the length)
                  </entry>
                  <entry>
                    4 (for the length)
@@ -620,12 +1106,9 @@
               </row><row>
                  <entry><literal>VARIANT</literal></entry>
                  <entry>
               </row><row>
                  <entry><literal>VARIANT</literal></entry>
                  <entry>
-                  A variant type has a marshaled <literal>SIGNATURE</literal>
-                  followed by a marshaled value with the type
+                  The marshaled <literal>SIGNATURE</literal> of a single
+                  complete type, followed by a marshaled value with the type
                    given in the signature.
                    given in the signature.
-                  Unlike a message signature, the variant signature 
-                  can contain only a single complete type.
-                  So "i", "ai" or "(ii)" is OK, but "ii" is not.
                  </entry>
                  <entry>
                    1 (alignment of the signature)
                  </entry>
                  <entry>
                    1 (alignment of the signature)
@@ -652,111 +1135,33 @@
            </tgroup>
          </informaltable>
        </para>
            </tgroup>
          </informaltable>
        </para>
-      
-      <sect3 id="message-protocol-marshaling-object-path">
-        <title>Valid Object Paths</title>
-        
-        <para>
-          An object path is a name used to refer to an object instance.
-          Conceptually, each participant in a D-Bus message exchange may have
-          any number of object instances (think of C++ or Java objects) and each
-          such instance will have a path. Like a filesystem, the object
-          instances in an application form a hierarchical tree.
-        </para>
-        
-        <para>
-          The following rules define a valid object path. Implementations must 
-          not send or accept messages with invalid object paths.
-          <itemizedlist>
-            <listitem>
-              <para>
-                The path may be of any length.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                The path must begin with an ASCII '/' (integer 47) character, 
-                and must consist of elements separated by slash characters.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                Each element must only contain the ASCII characters 
-                "[A-Z][a-z][0-9]_"
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                No element may be the empty string.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                Multiple '/' characters cannot occur in sequence.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                A trailing '/' character is not allowed unless the 
-                path is the root path (a single '/' character).
-              </para>
-            </listitem>
-          </itemizedlist>
-        </para>
  
  
-      </sect3>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="message-protocol">
+    <title>Message Protocol</title>
+
+    <para>
+      A <firstterm>message</firstterm> consists of a
+      <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
+      think of a message as a package, the header is the address, and the body
+      contains the package contents. The message delivery system uses the header
+      information to figure out where to send the message and how to interpret
+      it; the recipient interprets the body of the message.
+    </para>
+    
+    <para>
+      The body of the message is made up of zero or more
+      <firstterm>arguments</firstterm>, which are typed values, such as an
+      integer or a byte array.
+    </para>
  
  
-      
-      <sect3 id="message-protocol-marshaling-signature">
-        <title>Valid Signatures</title>
-        <para>
-          An implementation must not send or accept invalid signatures.
-          Valid signatures will conform to the following rules:
-          <itemizedlist>
-            <listitem>
-              <para>
-                The signature ends with a nul byte.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                The signature is a list of single complete types. 
-                Arrays must have element types, and structs must 
-                have both open and close parentheses.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                Only type codes and open and close parentheses are 
-                allowed in the signature. The <literal>STRUCT</literal> type code
-                is not allowed in signatures, because parentheses
-                are used instead.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                The maximum depth of container type nesting is 32 array type
-                codes and 32 open parentheses. This implies that the maximum
-                total depth of recursion is 64, for an "array of array of array
-                of ... struct of struct of struct of ..."  where there are 32
-                array and 32 struct.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                The maximum length of a signature is 255.
-              </para>
-            </listitem>
-            <listitem>
-              <para>
-                Signatures must be nul-terminated.
-              </para>
-            </listitem>
-          </itemizedlist>
-        </para>
-      </sect3>
-      
-    </sect2>
+    <para>
+      Both header and body use the D-Bus <link linkend="type-system">type
+        system</link> and format for serializing data.
+    </para>
  
      <sect2 id="message-protocol-messages">
        <title>Message Format</title>
  
      <sect2 id="message-protocol-messages">
        <title>Message Format</title>
@@ -1125,21 +1530,48 @@
             <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
            </itemizedlist>
          </para>
             <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
            </itemizedlist>
          </para>
+
+        <para>
+          Interface names should start with the reversed DNS domain name of
+          the author of the interface (in lower-case), like interface names
+          in Java. It is conventional for the rest of the interface name
+          to consist of words run together, with initial capital letters
+          on all words ("CamelCase"). Several levels of hierarchy can be used.
+          It is also a good idea to include the major version of the interface
+          in the name, and increment it if incompatible changes are made;
+          this way, a single object can implement several versions of an
+          interface in parallel, if necessary.
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might define
+          interfaces called <literal>com.example.MusicPlayer1</literal>,
+          <literal>com.example.MusicPlayer1.Track</literal> and
+          <literal>com.example.MusicPlayer1.Seekable</literal>.
+        </para>
+
+        <para>
+          D-Bus does not distinguish between the concepts that would be
+          called classes and interfaces in Java: either can be identified on
+          D-Bus by an interface name.
+        </para>
        </sect3>
        <sect3 id="message-protocol-names-bus">
          <title>Bus names</title>
          <para>
            Connections have one or more bus names associated with them.
        </sect3>
        <sect3 id="message-protocol-names-bus">
          <title>Bus names</title>
          <para>
            Connections have one or more bus names associated with them.
-          A connection has exactly one bus name that is a unique connection
-          name. The unique connection name remains with the connection for
-          its entire lifetime.
+          A connection has exactly one bus name that is a <firstterm>unique
+            connection name</firstterm>. The unique connection name remains
+          with the connection for its entire lifetime.
            A bus name is of type <literal>STRING</literal>,
            meaning that it must be valid UTF-8. However, there are also
            some additional restrictions that apply to bus names 
            specifically:
            <itemizedlist>
              <listitem><para>Bus names that start with a colon (':')
            A bus name is of type <literal>STRING</literal>,
            meaning that it must be valid UTF-8. However, there are also
            some additional restrictions that apply to bus names 
            specifically:
            <itemizedlist>
              <listitem><para>Bus names that start with a colon (':')
-                character are unique connection names.
+                character are unique connection names. Other bus names
+                are called <firstterm>well-known bus names</firstterm>.
                  </para>
              </listitem>
              <listitem><para>Bus names are composed of 1 or more elements separated by
                  </para>
              </listitem>
              <listitem><para>Bus names are composed of 1 or more elements separated by
@@ -1166,6 +1598,31 @@
            Note that the hyphen ('-') character is allowed in bus names but
            not in interface names.
          </para>
            Note that the hyphen ('-') character is allowed in bus names but
            not in interface names.
          </para>
+
+        <para>
+          Like <link linkend="message-protocol-names-interface">interface
+            names</link>, well-known bus names should start with the
+          reversed DNS domain name of the author of the interface (in
+          lower-case), and it is conventional for the rest of the well-known
+          bus name to consist of words run together, with initial
+          capital letters. As with interface names, including a version
+          number in well-known bus names is a good idea; it's possible to
+          have the well-known bus name for more than one version
+          simultaneously if backwards compatibility is required.
+        </para>
+
+        <para>
+          If a well-known bus name implies the presence of a "main" interface,
+          that "main" interface is often given the same name as
+          the well-known bus name, and situated at the corresponding object
+          path. For instance, if the owner of <literal>example.com</literal>
+          is developing a D-Bus API for a music player, they might define
+          that any application that takes the well-known name
+          <literal>com.example.MusicPlayer1</literal> should have an object
+          at the object path <literal>/com/example/MusicPlayer1</literal>
+          which implements the interface
+          <literal>com.example.MusicPlayer1</literal>.
+        </para>
        </sect3>
        <sect3 id="message-protocol-names-member">
          <title>Member names</title>
        </sect3>
        <sect3 id="message-protocol-names-member">
          <title>Member names</title>
@@ -1180,12 +1637,31 @@
             <listitem><para>Must be at least 1 byte in length.</para></listitem>
            </itemizedlist>
          </para>
             <listitem><para>Must be at least 1 byte in length.</para></listitem>
            </itemizedlist>
          </para>
+
+        <para>
+          It is conventional for member names on D-Bus to consist of
+          capitalized words with no punctuation ("camel-case").
+          Method names should usually be verbs, such as
+          <literal>GetItems</literal>, and signal names should usually be
+          a description of an event, such as <literal>ItemsChanged</literal>.
+        </para>
        </sect3>
        <sect3 id="message-protocol-names-error">
          <title>Error names</title>
          <para>
            Error names have the same restrictions as interface names.
          </para>
        </sect3>
        <sect3 id="message-protocol-names-error">
          <title>Error names</title>
          <para>
            Error names have the same restrictions as interface names.
          </para>
+
+        <para>
+          Error names have the same naming conventions as interface
+          names, and often contain <literal>.Error.</literal>; for instance,
+          the owner of <literal>example.com</literal> might define the
+          errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
+          and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
+          The errors defined by D-Bus itself, such as
+          <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
+          similar pattern.
+        </para>
        </sect3>
      </sect2>
  
        </sect3>
      </sect2>
  
@@ -1971,7 +2447,7 @@
                </listitem>
                <listitem>
                  <para>
                </listitem>
                <listitem>
                  <para>
-                  Receive REJECT [mechs] &rarr; send AUTH [next mech],
+                  Receive REJECTED [mechs] &rarr; send AUTH [next mech],
                    goto <emphasis>WaitingForData</emphasis> or
                    <emphasis>WaitingForOK</emphasis>
                  </para>
                    goto <emphasis>WaitingForData</emphasis> or
                    <emphasis>WaitingForOK</emphasis>
                  </para>
@@ -2007,7 +2483,7 @@
              <itemizedlist>
                <listitem>
                  <para>
              <itemizedlist>
                <listitem>
                  <para>
-                  Receive REJECT [mechs] &rarr; send AUTH [next mech],
+                  Receive REJECTED [mechs] &rarr; send AUTH [next mech],
                    goto <emphasis>WaitingForData</emphasis> or
                    <emphasis>WaitingForOK</emphasis>
                  </para>
                    goto <emphasis>WaitingForData</emphasis> or
                    <emphasis>WaitingForOK</emphasis>
                  </para>
@@ -2049,7 +2525,7 @@
  
              <listitem>
                <para>
  
              <listitem>
                <para>
-                REJECT means that the client failed to authenticate or
+                REJECTED means that the client failed to authenticate or
                  there was an error in RESP.
                </para>
              </listitem>
                  there was an error in RESP.
                </para>
              </listitem>
@@ -2096,7 +2572,7 @@
                      </member>
  
                      <member>
                      </member>
  
                      <member>
-                      MECH(RESP) returns REJECT &rarr; send REJECTED
+                      MECH(RESP) returns REJECTED &rarr; send REJECTED
                        [mechs], goto
                        <emphasis>WaitingForAuth</emphasis>
                      </member>
                        [mechs], goto
                        <emphasis>WaitingForAuth</emphasis>
                      </member>
@@ -2150,7 +2626,7 @@
                      </member>
  
                      <member>
                      </member>
  
                      <member>
-                      MECH(RESP) returns REJECT &rarr; send REJECTED
+                      MECH(RESP) returns REJECTED &rarr; send REJECTED
                        [mechs], goto
                        <emphasis>WaitingForAuth</emphasis>
                      </member>
                        [mechs], goto
                        <emphasis>WaitingForAuth</emphasis>
                      </member>
@@ -2464,8 +2940,8 @@
        [FIXME we need to specify in detail each transport and its possible arguments]
      
        Current transports include: unix domain sockets (including 
        [FIXME we need to specify in detail each transport and its possible arguments]
      
        Current transports include: unix domain sockets (including 
-      abstract namespace on linux), TCP/IP, and a debug/testing transport using 
-      in-process pipes. Future possible transports include one that 
+      abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
+      using in-process pipes. Future possible transports include one that
        tunnels over X11 protocol.
      </para>
    
        tunnels over X11 protocol.
      </para>
    
@@ -2486,7 +2962,7 @@
         would be padded by Nul bytes.
        </para>
        <para>
         would be padded by Nul bytes.
        </para>
        <para>
-        Unix domain sockets are not available on windows. 
+        Unix domain sockets are not available on Windows.
        </para>
        <sect3 id="transports-unix-domain-sockets-addresses">
          <title>Server Address Format</title>
        </para>
        <sect3 id="transports-unix-domain-sockets-addresses">
          <title>Server Address Format</title>
@@ -2524,6 +3000,74 @@
         </informaltable>
        </sect3>
      </sect2>
         </informaltable>
        </sect3>
      </sect2>
+    <sect2 id="transports-launchd">
+      <title>launchd</title>
+      <para>
+        launchd is an open-source server management system that replaces init, inetd
+        and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
+        bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
+      </para>
+
+      <para>
+        launchd allocates a socket and provides it with the unix path through the
+        DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
+        spawned by launchd (or dbus-daemon, if it was started by launchd) can access
+        it through its environment.
+        Other processes can query for the launchd socket by executing:
+        $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
+        This is normally done by the D-Bus client library so doesn't have to be done
+        manually.
+      </para>
+      <para>
+        launchd is not available on Microsoft Windows.
+      </para>
+      <sect3 id="transports-launchd-addresses">
+        <title>Server Address Format</title>
+        <para>
+          launchd addresses are identified by the "launchd:" prefix
+          and support the following key/value pairs:
+        </para>
+        <informaltable>
+         <tgroup cols="3">
+          <thead>
+           <row>
+            <entry>Name</entry>
+            <entry>Values</entry>
+            <entry>Description</entry>
+           </row>
+          </thead>
+          <tbody>
+           <row>
+            <entry>env</entry>
+            <entry>(environment variable)</entry>
+            <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
+          </row>
+        </tbody>
+        </tgroup>
+       </informaltable>
+      </sect3>
+    </sect2>
+    <sect2 id="transports-systemd">
+      <title>systemd</title>
+      <para>
+        systemd is an open-source server management system that
+        replaces init and inetd on newer Linux systems. It supports
+        socket activation. The D-Bus systemd transport is used to acquire
+        socket activation file descriptors from systemd and use them
+        as D-Bus transport when the current process is spawned by
+        socket activation from it.
+      </para>
+      <para>
+        The systemd transport accepts only one or more Unix domain or
+        TCP streams sockets passed in via socket activation.
+      </para>
+      <para>
+        The systemd transport is not available on non-Linux operating systems.
+      </para>
+      <para>
+        The systemd transport defines no parameter keys.
+      </para>
+    </sect2>
      <sect2 id="transports-tcp-sockets">
        <title>TCP Sockets</title>
        <para>
      <sect2 id="transports-tcp-sockets">
        <title>TCP Sockets</title>
        <para>
@@ -2535,7 +3079,7 @@
          over a network is unsecure. 
        </para>
        <para>  
          over a network is unsecure. 
        </para>
        <para>  
-        Windows notes: Because of the tcp stack on windows does not provide sending 
+        Windows notes: Because of the tcp stack on Windows does not provide sending
          credentials over a tcp connection, the EXTERNAL authentification 
          mechanismus does not work. 
        </para>
          credentials over a tcp connection, the EXTERNAL authentification 
          mechanismus does not work. 
        </para>
@@ -2653,25 +3197,156 @@
         </informaltable>
        </sect3>
      </sect2>
         </informaltable>
        </sect3>
      </sect2>
-
-  </sect1>
-
-  <sect1 id="naming-conventions">
-    <title>Naming Conventions</title>
-    
-    <para>
-      D-Bus namespaces are all lowercase and correspond to reversed domain
-      names, as with Java. e.g. "org.freedesktop"
-    </para>
-    <para>
-      Interface, signal, method, and property names are "WindowsStyleCaps", note
-      that the first letter is capitalized, unlike Java.
-    </para>
+    <sect2 id="transports-exec">
+      <title>Executed Subprocesses on Unix</title>
+      <para>
+        This transport forks off a process and connects its standard
+        input and standard output with an anonymous Unix domain
+        socket. This socket is then used for communication by the
+        transport. This transport may be used to use out-of-process
+        forwarder programs as basis for the D-Bus protocol.
+      </para>
+      <para>
+        The forked process will inherit the standard error output and
+        process group from the parent process.
+      </para>
+      <para>
+        Executed subprocesses are not available on Windows.
+      </para>
+      <sect3 id="transports-exec-addresses">
+        <title>Server Address Format</title>
+        <para>
+          Executed subprocess addresses are identified by the "unixexec:" prefix
+          and support the following key/value pairs:
+        </para>
+        <informaltable>
+         <tgroup cols="3">
+          <thead>
+           <row>
+            <entry>Name</entry>
+            <entry>Values</entry>
+            <entry>Description</entry>
+           </row>
+          </thead>
+          <tbody>
+           <row>
+            <entry>path</entry>
+            <entry>(path)</entry>
+            <entry>Path of the binary to execute, either an absolute
+            path or a binary name that is searched for in the default
+            search path of the OS. This corresponds to the first
+            argument of execlp(). This key is mandatory.</entry>
+          </row>
+          <row>
+            <entry>argv0</entry>
+            <entry>(string)</entry>
+            <entry>The program name to use when executing the
+            binary. If omitted the same value as specified for path=
+            will be used. This corresponds to the second argument of
+            execlp().</entry>
+          </row>
+          <row>
+            <entry>argv1, argv2, ...</entry>
+            <entry>(string)</entry>
+            <entry>Arguments to pass to the binary. This corresponds
+            to the third and later arguments of execlp(). If a
+            specific argvX is not specified no further argvY for Y > X
+            are taken into account.</entry>
+          </row>
+        </tbody>
+        </tgroup>
+       </informaltable>
+      </sect3>
+    </sect2>
+   </sect1>
+   <sect1 id="meta-transports">
+    <title>Meta Transports</title>
      <para>
      <para>
-      Object paths are normally all lowercase with underscores used rather than
-      hyphens.
+      Meta transports are a kind of transport with special enhancements or
+      behavior. Currently available meta transports include: autolaunch
      </para>
      </para>
-  </sect1>
+
+    <sect2 id="meta-transports-autolaunch">
+     <title>Autolaunch</title>
+     <para>The autolaunch transport provides a way for dbus clients to autodetect
+       a running dbus session bus and to autolaunch a session bus if not present.
+     </para>
+     <sect3 id="meta-transports-autolaunch-addresses">
+       <title>Server Address Format</title>
+       <para>
+         Autolaunch addresses uses the "autolaunch:" prefix and support the
+         following key/value pairs:
+       </para>
+       <informaltable>
+        <tgroup cols="3">
+         <thead>
+          <row>
+           <entry>Name</entry>
+           <entry>Values</entry>
+           <entry>Description</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry>scope</entry>
+           <entry>(string)</entry>
+           <entry>scope of autolaunch (Windows only)
+            <itemizedlist>
+             <listitem>
+              <para>
+               "*install-path" - limit session bus to dbus installation path.
+               The dbus installation path is determined from the location of
+               the shared dbus library. If the library is located in a 'bin'
+               subdirectory the installation root is the directory above,
+               otherwise the directory where the library lives is taken as
+               installation root.
+               <programlisting>
+                   &lt;install-root&gt;/bin/[lib]dbus-1.dll
+                   &lt;install-root&gt;/[lib]dbus-1.dll
+               </programlisting>
+              </para>
+             </listitem>
+             <listitem>
+              <para>
+               "*user" - limit session bus to the recent user.
+              </para>
+             </listitem>
+             <listitem>
+              <para>
+               other values - specify dedicated session bus like "release",
+               "debug" or other
+              </para>
+             </listitem>
+            </itemizedlist>
+           </entry>
+         </row>
+        </tbody>
+       </tgroup>
+      </informaltable>
+     </sect3>
+
+     <sect3 id="meta-transports-autolaunch-windows-implementation">
+      <title>Windows implementation</title>
+      <para>
+        On start, the server opens a platform specific transport, creates a mutex
+        and a shared memory section containing the related session bus address.
+        This mutex will be inspected by the dbus client library to detect a
+        running dbus session bus. The access to the mutex and the shared memory
+        section are protected by global locks.
+      </para>
+      <para>
+       In the recent implementation the autolaunch transport uses a tcp transport
+       on localhost with a port choosen from the operating system. This detail may
+       change in the future.
+      </para>
+      <para>
+        Disclaimer: The recent implementation is in an early state and may not
+        work in all cirumstances and/or may have security issues. Because of this
+        the implementation is not documentated yet.
+      </para>
+     </sect3>
+    </sect2>
+   </sect1>
  
    <sect1 id="uuids">
      <title>UUIDs</title>
  
    <sect1 id="uuids">
      <title>UUIDs</title>
@@ -2801,6 +3476,22 @@
          </programlisting>
        </para>
        <para>
          </programlisting>
        </para>
        <para>
+        It is conventional to give D-Bus properties names consisting of
+        capitalized words without punctuation ("CamelCase"), like
+        <link linkend="message-protocol-names-member">member names</link>.
+        For instance, the GObject property
+        <literal>connection-status</literal> or the Qt property
+        <literal>connectionStatus</literal> could be represented on D-Bus
+        as <literal>ConnectionStatus</literal>.
+      </para>
+      <para>
+        Strictly speaking, D-Bus property names are not required to follow
+        the same naming restrictions as member names, but D-Bus property
+        names that would not be valid member names (in particular,
+        GObject-style dash-separated property names) can cause interoperability
+        problems and should be avoided.
+      </para>
+      <para>
          The available properties and whether they are writable can be determined
          by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
          see <xref linkend="standard-interfaces-introspectable"/>.
          The available properties and whether they are writable can be determined
          by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
          see <xref linkend="standard-interfaces-introspectable"/>.
@@ -2846,6 +3537,114 @@
          annotation.
        </para>
      </sect2>
          annotation.
        </para>
      </sect2>
+
+    <sect2 id="standard-interfaces-objectmanager">
+      <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
+      <para>
+        An API can optionally make use of this interface for one or
+        more sub-trees of objects. The root of each sub-tree implements
+        this interface so other applications can get all objects,
+        interfaces and properties in a single method call.  It is
+        appropriate to use this interface if users of the tree of
+        objects are expected to be interested in all interfaces of all
+        objects in the tree; a more granular API should be used if
+        users of the objects are expected to be interested in a small
+        subset of the objects, a small subset of their interfaces, or
+        both.
+      </para>
+      <para>
+        The method that applications can use to get all objects and
+        properties is <literal>GetManagedObjects</literal>:
+      </para>
+      <para>
+        <programlisting>
+          org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT&lt;OBJPATH,DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);
+        </programlisting>
+      </para>
+      <para>
+        The return value of this method is a dict whose keys are
+        object paths. All returned object paths are children of the
+        object path implementing this interface, i.e. their object
+        paths start with the ObjectManager's object path plus '/'.
+      </para>
+      <para>
+        Each value is a dict whose keys are interfaces names.  Each
+        value in this inner dict is the same dict that would be
+        returned by the <link
+        linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
+        method for that combination of object path and interface. If
+        an interface has no properties, the empty dict is returned.
+      </para>
+      <para>
+        Changes are emitted using the following two signals:
+      </para>
+      <para>
+        <programlisting>
+          org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
+                                                              DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt; interfaces_and_properties);
+          org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
+                                                                ARRAY&lt;STRING&gt; interfaces);
+        </programlisting>
+      </para>
+      <para>
+        The <literal>InterfacesAdded</literal> signal is emitted when
+        either a new object is added or when an existing object gains
+        one or more interfaces. The
+        <literal>InterfacesRemoved</literal> signal is emitted
+        whenever an object is removed or it loses one or more
+        interfaces. The second parameter of the
+        <literal>InterfacesAdded</literal> signal contains a dict with
+        the interfaces and properties (if any) that have been added to
+        the given object path. Similarly, the second parameter of the
+        <literal>InterfacesRemoved</literal> signal contains an array
+        of the interfaces that were removed. Note that changes on
+        properties on existing interfaces are not reported using this
+        interface - an application should also monitor the existing <link
+        linkend="standard-interfaces-properties">PropertiesChanged</link>
+        signal on each object.
+      </para>
+      <para>
+        Applications SHOULD NOT export objects that are children of an
+        object (directly or otherwise) implementing this interface but
+        which are not returned in the reply from the
+        <literal>GetManagedObjects()</literal> method of this
+        interface on the given object.
+      </para>
+      <para>
+        The intent of the <literal>ObjectManager</literal> interface
+        is to make it easy to write a robust client
+        implementation. The trivial client implementation only needs
+        to make two method calls:
+      </para>
+      <para>
+        <programlisting>
+          org.freedesktop.DBus.AddMatch (bus_proxy,
+                                         "type='signal',name='org.example.App',path_namespace='/org/example/App'");
+          objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
+        </programlisting>
+      </para>
+      <para>
+        on the message bus and the remote application's
+        <literal>ObjectManager</literal>, respectively. Whenever a new
+        remote object is created (or an existing object gains a new
+        interface), the <literal>InterfacesAdded</literal> signal is
+        emitted, and since this signal contains all properties for the
+        interfaces, no calls to the
+        <literal>org.freedesktop.Properties</literal> interface on the
+        remote object are needed. Additionally, since the initial
+        <literal>AddMatch()</literal> rule already includes signal
+        messages from the newly created child object, no new
+        <literal>AddMatch()</literal> call is needed.
+      </para>
+
+      <para>
+        <emphasis>
+          The <literal>org.freedesktop.DBus.ObjectManager</literal>
+          interface was added in version 0.17 of the D-Bus
+          specification.
+        </emphasis>
+      </para>
+    </sect2>
    </sect1>
  
    <sect1 id="introspection-format">
    </sect1>
  
    <sect1 id="introspection-format">
@@ -2862,8 +3661,8 @@
        <programlisting>
          &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
           "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
        <programlisting>
          &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
           "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
-        &lt;node name="/org/freedesktop/sample_object"&gt;
-          &lt;interface name="org.freedesktop.SampleInterface"&gt;
+        &lt;node name="/com/example/sample_object"&gt;
+          &lt;interface name="com.example.SampleInterface"&gt;
              &lt;method name="Frobate"&gt;
                &lt;arg name="foo" type="i" direction="in"/&gt;
                &lt;arg name="bar" type="s" direction="out"/&gt;
              &lt;method name="Frobate"&gt;
                &lt;arg name="foo" type="i" direction="in"/&gt;
                &lt;arg name="bar" type="s" direction="out"/&gt;
@@ -3023,14 +3822,17 @@
          unique-for-the-lifetime-of-the-bus name automatically assigned.
          Applications may request additional names for a connection. Additional
          names are usually "well-known names" such as
          unique-for-the-lifetime-of-the-bus name automatically assigned.
          Applications may request additional names for a connection. Additional
          names are usually "well-known names" such as
-        "org.freedesktop.TextEditor". When a name is bound to a connection,
+        "com.example.TextEditor". When a name is bound to a connection,
          that connection is said to <firstterm>own</firstterm> the name.
        </para>
        <para>
          that connection is said to <firstterm>own</firstterm> the name.
        </para>
        <para>
-        The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>. 
-        This name routes messages to the bus, allowing applications to make 
-        administrative requests. For example, applications can ask the bus 
-        to assign a name to a connection.
+        The bus itself owns a special name,
+        <literal>org.freedesktop.DBus</literal>, with an object
+        located at <literal>/org/freedesktop/DBus</literal> that
+        implements the <literal>org.freedesktop.DBus</literal>
+        interface. This service allows applications to make
+        administrative requests of the bus itself. For example,
+        applications can ask the bus to assign a name to a connection.
        </para>
        <para>
          Each name may have <firstterm>queued owners</firstterm>.  When an
        </para>
        <para>
          Each name may have <firstterm>queued owners</firstterm>.  When an
@@ -3041,46 +3843,17 @@
        </para>
  
        <para>
        </para>
  
        <para>
-        This feature causes the right thing to happen if you start two text
-        editors for example; the first one may request "org.freedesktop.TextEditor", 
-        and the second will be queued as a possible owner of that name. When 
-        the first exits, the second will take over.
-      </para>
-
-      <para>
-        Messages may have a <literal>DESTINATION</literal> field (see <xref
-        linkend="message-protocol-header-fields"/>).  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>
-        Signals normally do not specify a destination; they are sent to all
-        applications with <firstterm>message matching rules</firstterm> that
-        match the message.
-      </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.
+        This feature causes the right thing to happen if you start two text
+        editors for example; the first one may request "com.example.TextEditor",
+        and the second will be queued as a possible owner of that name. When 
+        the first exits, the second will take over.
        </para>
  
        <para>
        </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.
+        Applications may send <firstterm>unicast messages</firstterm> to
+        a specific recipient or to the message bus itself, or
+        <firstterm>broadcast messages</firstterm> to all interested recipients.
+        See <xref linkend="message-bus-routing"/> for details.
        </para>
      </sect2>
  
        </para>
      </sect2>
  
@@ -3514,20 +4287,122 @@
  
      <sect2 id="message-bus-routing">
        <title>Message Bus Message Routing</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.
+      </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>
        <para>
-        FIXME 
+        Message bus implementations may impose a security policy which
+        prevents certain messages from being sent or received.
+        When a 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>
        </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>
+
+        <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>
+      </sect3>
+
        <sect3 id="message-bus-routing-match-rules">
          <title>Match Rules</title>
          <para>
        <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 what messages can be sent to a client
-          based on the contents of the message.  When a message is routed
-          through the bus it is compared to clients' match rules.  If any
-          of the rules match, the message is dispatched to the client.
-          If none of the rules match the message never leaves the bus.  This
-          is an effective way to control traffic over the bus and to make sure
-          only relevant message need to be processed by the client.
+         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 
          </para>
          <para>
            Match rules are added using the AddMatch bus method 
@@ -3541,8 +4416,7 @@
          </para>
          <para>
            The following table describes the keys that can be used to create 
          </para>
          <para>
            The following table describes the keys that can be used to create 
-          a match rule:
-          The following table summarizes the D-Bus types.
+          a match rule.
            <informaltable>
              <tgroup cols="3">
                <thead>
            <informaltable>
              <tgroup cols="3">
                <thead>
@@ -3587,6 +4461,43 @@
                    path match is path='/org/freedesktop/Hal/Manager'</entry>
                  </row>
                  <row>
                    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
                    <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
@@ -3626,6 +4537,68 @@
                        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>
                        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.backend'</literal>
+                      matches name owner changes for bus names such as
+                      <literal>com.example.backend.foo</literal>,
+                      <literal>com.example.backend.foo.bar</literal>, and
+                      <literal>com.example.backend</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>
                    </entry>
                  </row>
                </tbody>
@@ -3645,9 +4618,9 @@
        <para>
          With D-Bus, starting a service is normally done by name. That is,
          applications ask the message bus to start some program that will own a
        <para>
          With D-Bus, starting a service is normally done by name. That is,
          applications ask the message bus to start some program that will own a
-        well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
-        This implies a contract documented along with the name 
-        <literal>org.freedesktop.TextEditor</literal> for which objects 
+        well-known name, such as <literal>com.example.TextEditor</literal>.
+        This implies a contract documented along with the name
+        <literal>com.example.TextEditor</literal> for which object
          the owner of that name will provide, and what interfaces those 
          objects will have.
        </para>
          the owner of that name will provide, and what interfaces those 
          objects will have.
        </para>
@@ -3659,9 +4632,7 @@
          <xref linkend="message-bus-types"/>.
        </para>
        <para>
          <xref linkend="message-bus-types"/>.
        </para>
        <para>
-        [FIXME the file format should be much better specified than "similar to
-        .desktop entries" esp. since desktop entries are already
-        badly-specified. ;-)] Service description files have the ".service" file
+        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
          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
@@ -3670,14 +4641,26 @@
          encoding. To ensure that there will be no name collisions, service files
          must be namespaced using the same mechanism as messages and service
          names.
          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>
+        [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>
  
          <figure>
           <title>Example service description file</title>
           <programlisting>
              # Sample service description file
              [D-BUS Service]
  
          <figure>
           <title>Example service description file</title>
           <programlisting>
              # Sample service description file
              [D-BUS Service]
-            Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
-            Exec=/usr/libexec/gconfd-2
+            Name=com.example.ConfigurationDatabase
+            Exec=/usr/bin/sample-configd
            </programlisting>
         </figure>
        </para>
            </programlisting>
         </figure>
        </para>
@@ -3974,9 +4957,25 @@
          <sect4>
            <title></title>
            <para>
          <sect4>
            <title></title>
            <para>
-            [FIXME specify location of .service files, probably using
-            DESKTOP_DIRS etc. from basedir specification, though login session
-            bus is not really desktop-specific]
+            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, which
+            should be searched with lower priority than anything in
+            XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
+            for example, the reference implementation also
+            looks in <literal>${datadir}/dbus-1/services</literal> as
+            set at compile time.
+          </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>
            </para>
          </sect4>
        </sect3>
@@ -4003,7 +5002,32 @@
            </footnote>
          </para>
          <para>
            </footnote>
          </para>
          <para>
-          [FIXME specify location of system bus .service files]
+          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>
          </para>
        </sect3>
      </sect2>
@@ -4555,6 +5579,225 @@
         </para>
        </sect3>
  
         </para>
        </sect3>
  
+      <sect3 id="bus-messages-get-connection-credentials">
+        <title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            DICT&lt;STRING,VARIANT&gt; GetConnectionCredentials (in STRING bus_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>Unique or well-known bus name of the connection to
+                    query, such as <literal>:12.34</literal> or
+                    <literal>com.example.tea</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>DICT&lt;STRING,VARIANT&gt;</entry>
+                <entry>Credentials</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+
+      <para>
+        Returns as many credentials as possible for the process connected to
+        the server. If unable to determine certain credentials (for instance,
+        because the process is not on the same machine as the bus daemon,
+        or because this version of the bus daemon does not support a
+        particular security framework), or if the values of those credentials
+        cannot be represented as documented here, then those credentials
+        are omitted.
+      </para>
+
+      <para>
+        Keys in the returned dictionary not containing "." are defined
+        by this specification. Bus daemon implementors supporting
+        credentials frameworks not mentioned in this document should either
+        contribute patches to this specification, or use keys containing
+        "." and starting with a reversed domain name.
+        <informaltable>
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry>Key</entry>
+                <entry>Value type</entry>
+                <entry>Value</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>UnixUserID</entry>
+                <entry>UINT32</entry>
+                <entry>The numeric Unix user ID, as defined by POSIX</entry>
+              </row>
+              <row>
+                <entry>ProcessID</entry>
+                <entry>UINT32</entry>
+                <entry>The numeric process ID, on platforms that have
+                  this concept. On Unix, this is the process ID defined by
+                  POSIX.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+       </para>
+
+        <para>
+          This method was added in D-Bus 1.7 to reduce the round-trips
+          required to list a process's credentials. In older versions, calling
+          this method will fail: applications should recover by using the
+          separate methods such as
+          <xref linkend="bus-messages-get-connection-unix-user"/>
+          instead.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-get-adt-audit-session-data">
+        <title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_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>Unique or well-known bus name of the connection to
+                    query, such as <literal>:12.34</literal> or
+                    <literal>com.example.tea</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 BYTE</entry>
+                  <entry>auditing data as returned by
+                    adt_export_session_data()</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Returns auditing data used by Solaris ADT, in an unspecified
+          binary format. If you know what this means, please contribute
+          documentation via the D-Bus bug tracking system.
+          This method is on the core DBus interface for historical reasons;
+          the same information should be made available via
+          <xref linkend="bus-messages-get-connection-credentials"/>
+          in future.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-get-connection-selinux-security-context">
+        <title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_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>Unique or well-known bus name of the connection to
+                    query, such as <literal>:12.34</literal> or
+                    <literal>com.example.tea</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 BYTE</entry>
+                  <entry>some sort of string of bytes, not necessarily UTF-8,
+                    not including '\0'</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Returns the security context used by SELinux, in an unspecified
+          format. If you know what this means, please contribute
+          documentation via the D-Bus bug tracking system.
+          This method is on the core DBus interface for historical reasons;
+          the same information should be made available via
+          <xref linkend="bus-messages-get-connection-credentials"/>
+          in future.
+        </para>
+      </sect3>
+
+
        <sect3 id="bus-messages-add-match">
          <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
          <para>
        <sect3 id="bus-messages-add-match">
          <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
          <para>
@@ -4690,6 +5933,11 @@
                can be thought of as "well-known names" and are 
                used to find applications that offer specific functionality.
          </para>
                can be thought of as "well-known names" and are 
                used to find applications that offer specific functionality.
          </para>
+
+        <para>
+          See <xref linkend="message-protocol-names-bus"/> for details of
+          the syntax and naming conventions for bus names.
+        </para>
        </glossdef>
      </glossentry>
        
        </glossdef>
      </glossentry>
        
@@ -4728,10 +5976,14 @@
  
      <glossentry id="namespace"><glossterm>Namespace</glossterm>
        <glossdef>
  
      <glossentry id="namespace"><glossterm>Namespace</glossterm>
        <glossdef>
-       <para>
-          Used to prevent collisions when defining new interfaces or bus
-         names. The convention used is the same one Java uses for defining
-         classes: a reversed domain name.
+        <para>
+          Used to prevent collisions when defining new interfaces, bus names
+          etc. The convention used is the same one Java uses for defining
+          classes: a reversed domain name.
+          See <xref linkend="message-protocol-names-bus"/>,
+          <xref linkend="message-protocol-names-interface"/>,
+          <xref linkend="message-protocol-names-error"/>,
+          <xref linkend="message-protocol-marshaling-object-path"/>.
          </para>
        </glossdef>
      </glossentry>
          </para>
        </glossdef>
      </glossentry>
@@ -4788,9 +6040,9 @@
            A service is an executable that can be launched by the bus daemon.
            Services normally guarantee some particular features, for example they
            may guarantee that they will request a specific name such as
            A service is an executable that can be launched by the bus daemon.
            Services normally guarantee some particular features, for example they
            may guarantee that they will request a specific name such as
-          "org.freedesktop.Screensaver", have a singleton object
-          "/org/freedesktop/Application", and that object will implement the
-          interface "org.freedesktop.ScreensaverControl".
+          "com.example.Screensaver", have a singleton object
+         "/com/example/Application", and that object will implement the
+          interface "com.example.Screensaver.Control".
          </para>
        </glossdef>
      </glossentry>
          </para>
        </glossdef>
      </glossentry>