2006-11-14 Havoc Pennington <hp@redhat.com>

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 41d3fb9..77b7e69 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>

-    <releaseinfo>Version 0.11</releaseinfo>
-    <date>6 February 2005</date>
+    <releaseinfo>Version 0.12</releaseinfo>
+    <date>7 November 2006</date>

     <authorgroup>
       <author>
        <firstname>Havoc</firstname>
     <authorgroup>
       <author>
        <firstname>Havoc</firstname>


@@ -114,9 +114,20 @@
       </itemizedlist>
       D-Bus is not intended to be a generic IPC system for any possible 
       application, and intentionally omits many features found in other 
       </itemizedlist>
       D-Bus is not intended to be a generic IPC system for any possible 
       application, and intentionally omits many features found in other 

-      IPC systems for this reason. D-Bus may turn out to be useful 
-      in unanticipated applications, but future versions of this 
-      spec and the reference implementation probably will not 
+      IPC systems for this reason.
+    </para>
+
+    <para>
+      At the same time, the bus daemons offer a number of features not found in
+      other IPC systems, such as single-owner "bus names" (similar to X
+      selections), on-demand startup of services, and security policies.
+      In many ways, these features are the primary motivation for developing 
+      D-Bus; other systems would have sufficed if IPC were the only goal.
+    </para>
+
+    <para>
+      D-Bus may turn out to be useful in unanticipated applications, but future
+      versions of this spec and the reference implementation probably will not

       incorporate features that interfere with the core use cases.
     </para>
 
       incorporate features that interfere with the core use cases.
     </para>
 


@@ -127,6 +138,30 @@
       document could use a serious audit to be sure it makes sense to do
       so. Also, they are not capitalized.
     </para>
       document could use a serious audit to be sure it makes sense to do
       so. Also, they are not capitalized.
     </para>

+
+    <sect2 id="stability">
+      <title>Protocol and Specification Stability</title>
+      <para>
+        The D-Bus protocol is frozen (only compatible extensions are allowed) as
+        of November 8, 2006.  However, this specification could still use a fair
+        bit of work to make interoperable reimplementation possible without
+        reference to the D-Bus reference implementation. Thus, this
+        specification is not marked 1.0. To mark it 1.0, we'd like to see
+        someone invest significant effort in clarifying the specification
+        language, and growing the specification to cover more aspects of the
+        reference implementation's behavior.
+      </para>
+      <para>
+        Until this work is complete, any attempt to reimplement D-Bus will 
+        probably require looking at the reference implementation and/or asking
+        questions on the D-Bus mailing list about intended behavior. 
+        Questions on the list are very welcome.
+      </para>
+      <para>
+        Nonetheless, this document should be a useful starting point and is 
+        to our knowledge accurate, though incomplete.
+      </para>
+    </sect2>

     
   </sect1>
 
     
   </sect1>
 


@@ -1184,7 +1219,8 @@
           A signal emission is simply a single message of type <literal>SIGNAL</literal>.
           It must have three header fields: <literal>PATH</literal> giving the object 
           the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
           A signal emission is simply a single message of type <literal>SIGNAL</literal>.
           It must have three header fields: <literal>PATH</literal> giving the object 
           the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving

-          the fully-qualified name of the signal.
+          the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
+          for signals, though it is optional for method calls.

         </para>
       </sect3>
 
         </para>
       </sect3>
 


@@ -2201,23 +2237,29 @@
 
     <para>
       A server may specify a key-value pair with the key <literal>guid</literal>
 
     <para>
       A server may specify a key-value pair with the key <literal>guid</literal>

-      and the value a hex-encoded 16-byte sequence. This globally unique ID must
-      be created by filling the first 4 bytes with a 32-bit UNIX time since the
-      epoch, and the remaining 12 bytes with random bytes. If present, the GUID
-      may be used to distinguish one server from another. A server should use a
-      different GUID for each address it listens on. For example, if a message
-      bus daemon offers both UNIX domain socket and TCP connections, but treats
-      clients the same regardless of how they connect, those two connections are
-      equivalent post-connection but should have distinct GUIDs to distinguish
-      the kinds of connection.
+      and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
+      describes the format of the <literal>guid</literal> field.  If present,
+      this UUID may be used to distinguish one server address from another. A
+      server should use a different UUID for each address it listens on. For
+      example, if a message bus daemon offers both UNIX domain socket and TCP
+      connections, but treats clients the same regardless of how they connect,
+      those two connections are equivalent post-connection but should have
+      distinct UUIDs to distinguish the kinds of connection.

     </para>
     
     <para>
     </para>
     
     <para>

-      The intent of the GUID feature is to allow a client to avoid opening
-      multiple identical connections to the same server, by allowing the client
-      to check whether an address corresponds to an already-existing connection.
-      Comparing two addresses is insufficient, because addresses can be recycled
-      by distinct servers.
+      The intent of the address UUID feature is to allow a client to avoid
+      opening multiple identical connections to the same server, by allowing the
+      client to check whether an address corresponds to an already-existing
+      connection.  Comparing two addresses is insufficient, because addresses
+      can be recycled by distinct servers, and equivalent addresses may look
+      different if simply compared as strings (for example, the host in a TCP
+      address can be given as an IP address or as a hostname).
+    </para>
+
+    <para>
+      Note that the address key is <literal>guid</literal> even though the 
+      rest of the API and documentation says "UUID," for historical reasons.

     </para>
 
     <para>
     </para>
 
     <para>


@@ -2278,6 +2320,43 @@
       hyphens.
     </para>
   </sect1>
       hyphens.
     </para>
   </sect1>

+
+  <sect1 id="uuids">
+    <title>UUIDs</title>
+    <para>
+      A working D-Bus implementation uses universally-unique IDs in two places.
+      First, each server address has a UUID identifying the address, 
+      as described in <xref linkend="addresses"/>. Second, each operating
+      system kernel instance running a D-Bus client or server has a UUID
+      identifying that kernel, retrieved by invoking the method
+      org.freedesktop.DBus.Peer.GetMachineId() (see <xref
+      linkend="standard-interfaces-peer"/>).
+    </para>
+    <para>
+      The term "UUID" in this document is intended literally, i.e. an
+      identifier that is universally unique. It is not intended to refer to
+      RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
+    </para>
+    <para>
+      The UUID must contain 128 bits of data and be hex-encoded.  The
+      hex-encoded string may not contain hyphens or other non-hex-digit
+      characters, and it must be exactly 32 characters long.  To generate a
+      UUID, the current reference implementation concatenates 96 bits of random
+      data followed by the 32-bit time in seconds since the UNIX epoch (in big
+      endian byte order).
+    </para>
+    <para>
+      It would also be acceptable and probably better to simply generate 128
+      bits of random data, as long as the random number generator is of high
+      quality. The timestamp could conceivably help if the random bits are not
+      very random. With a quality random number generator, collisions are
+      extremely unlikely even with only 96 bits, so it's somewhat academic.
+    </para>
+    <para>
+      Implementations should, however, stick to random data for the first 96 bits
+      of the UUID.
+    </para>
+  </sect1>

     
   <sect1 id="standard-interfaces">
     <title>Standard Interfaces</title>
     
   <sect1 id="standard-interfaces">
     <title>Standard Interfaces</title>


@@ -2310,25 +2389,26 @@
         UUID representing the identity of the machine the process is running on.
         This UUID must be the same for all processes on a single system at least
         until that system next reboots. It should be the same across reboots 
         UUID representing the identity of the machine the process is running on.
         This UUID must be the same for all processes on a single system at least
         until that system next reboots. It should be the same across reboots 

-        if possible, but may change due to reconfiguration or hardware changes.
+        if possible, but this is not always possible to implement and is not 
+        guaranteed.

         It does not matter which object path a GetMachineId is sent to.  The
         reference implementation handles this method automatically.
       </para>
       <para>
         It does not matter which object path a GetMachineId is sent to.  The
         reference implementation handles this method automatically.
       </para>
       <para>

-        The UUID must contain 128 bits of data and be hex-encoded (meaning, the hex 
-        string contains 32 ASCII characters). The hex-encoded string may not contain 
-        hyphens or other non-hex-digit characters, and it must be exactly 32 characters long.
-        To generate a UUID, the recommended algorithm is to put the current time in seconds
-        since the UNIX epoch in the last 32 bits of the UUID, and to put randomly-generated bits
-        in the first 96 bits of the UUID.
-      </para>
-      <para>

         The UUID is intended to be per-instance-of-the-operating-system, so may represent
         a virtual machine running on a hypervisor, rather than a physical machine.
         Basically if two processes see the same UUID, they should also see the same
         shared memory, UNIX domain sockets, process IDs, and other features that require 
         a running OS kernel in common between the processes.
       </para>
         The UUID is intended to be per-instance-of-the-operating-system, so may represent
         a virtual machine running on a hypervisor, rather than a physical machine.
         Basically if two processes see the same UUID, they should also see the same
         shared memory, UNIX domain sockets, process IDs, and other features that require 
         a running OS kernel in common between the processes.
       </para>

+      <para>
+        The UUID is often used where other programs might use a hostname. Hostnames 
+        can change without rebooting, however, or just be "localhost" - so the UUID
+        is more robust.
+      </para>
+      <para>
+        <xref linkend="uuids"/> explains the format of the UUID.
+      </para>

     </sect2>
 
     <sect2 id="standard-interfaces-introspectable">
     </sect2>
 
     <sect2 id="standard-interfaces-introspectable">


@@ -3014,7 +3094,9 @@
                   <entry><literal>interface</literal></entry>
                   <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
                   <entry>Match messages sent over or to a particular interface.  An example of an
                   <entry><literal>interface</literal></entry>
                   <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
                   <entry>Match messages sent over or to a particular interface.  An example of an

-                  interface match is interface='org.freedesktop.Hal.Manager'</entry>
+                  interface match is interface='org.freedesktop.Hal.Manager'.
+                  If a message omits the interface header, it must not match any rule 
+                  that specifies this key.</entry>

                 </row>
                 <row>
                   <entry><literal>member</literal></entry>
                 </row>
                 <row>
                   <entry><literal>member</literal></entry>


@@ -3035,12 +3117,13 @@
                   example of a destination match is destination=':1.0'</entry>
                 </row>
                 <row>
                   example of a destination match is destination=':1.0'</entry>
                 </row>
                 <row>

-                  <entry><literal>arg[1, 2, 3, ...]</literal></entry>
+                  <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>

                   <entry>Any string</entry>
                   <entry>Arg matches are special and are used for further restricting the 
                   match based on the arguments in the body of a message.  As of this time
                   only string arguments can be matched.  An example of an argument match 
                   <entry>Any string</entry>
                   <entry>Arg matches are special and are used for further restricting the 
                   match based on the arguments in the body of a message.  As of this time
                   only string arguments can be matched.  An example of an argument match 

-                  would be arg3='Foo'.</entry>
+                  would be arg3='Foo'. Only argument indexes from 0 to 63 should be 
+                  accepted.</entry>

                 </row>
               </tbody>
             </tgroup>
                 </row>
               </tbody>
             </tgroup>