2003-02-17 Havoc Pennington <hp@pobox.com>

	* doc/dbus-specification.sgml: lots of cosmetic
	cleanups/rearrangement, add assorted FIXME, change DBUS_ADDRESS
	env variable to DBUS_BUS_ADDRESS, s/client/application/,
	s/server/bus/ (except in authentication section). Add a section
	"Message Bus Message Routing"

2 files changed, 796 insertions, 684 deletions

diff --git a/ChangeLog b/ChangeLog
index 7999581c..05e01eab 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2003-02-17  Havoc Pennington  <hp@pobox.com>
+
+	* doc/dbus-specification.sgml: lots of cosmetic
+	cleanups/rearrangement, add assorted FIXME, change DBUS_ADDRESS
+	env variable to DBUS_BUS_ADDRESS, s/client/application/,
+	s/server/bus/ (except in authentication section). Add a section
+	"Message Bus Message Routing"
+
 2003-02-17  Anders Carlsson  <andersca@codefactory.se.>
 
 	Release 0.4
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml
index e94980f2..fc48d337 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.sgml
@@ -244,7 +244,7 @@
               <row>
                 <entry>sndr</entry>
                 <entry>STRING</entry>
-                <entry>The name of the service that sent this message. 
+                <entry>The name of the base service that sent this message. 
                 The message bus fills in this field; the field is 
                 only meaningful in combination with the message bus.</entry>
               </row>
@@ -419,23 +419,23 @@
     <sect2 id="auth-protocol-overview">
       <title>Protocol Overview</title>
       <para>
-The protocol is a line-based protocol, where each line ends with
-\r\n. Each line begins with an all-caps ASCII command name containing
-only the character range [A-Z], a space, then any arguments for the
-command, then the \r\n ending the line. The protocol is
-case-sensitive. All bytes must be in the ASCII character set.
+        The protocol is a line-based protocol, where each line ends with
+        \r\n. Each line begins with an all-caps ASCII command name containing
+        only the character range [A-Z], a space, then any arguments for the
+        command, then the \r\n ending the line. The protocol is
+        case-sensitive. All bytes must be in the ASCII character set.
 
-Commands from the client to the server are as follows:
+        Commands from the client to the server are as follows:
 
-       <itemizedlist>
+        <itemizedlist>
 	  <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
 	  <listitem><para>CANCEL</para></listitem
-	  <listitem><para>BEGIN</para></listitem>
-	  <listitem><para>DATA &lt;data in base 64 encoding&gt;</para></listitem>
-	  <listitem><para>ERROR [human-readable error explanation]</para></listitem>
+	                                  <listitem><para>BEGIN</para></listitem>
+	                                  <listitem><para>DATA &lt;data in base 64 encoding&gt;</para></listitem>
+	                                  <listitem><para>ERROR [human-readable error explanation]</para></listitem>
 	</itemizedlist>
 
-From server to client are as follows:
+        From server to client are as follows:
 
         <itemizedlist>
 	  <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
@@ -448,227 +448,227 @@ From server to client are as follows:
     <sect2 id="auth-nul-byte">
       <title>Special credentials-passing nul byte</title>
       <para>
-Immediately after connecting to the server, the client must send a
-single nul byte. This byte may be accompanied by credentials
-information on some operating systems that use sendmsg() with
-SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
-sockets. However, the nul byte MUST be sent even on other kinds of
-socket, and even on operating systems that do not require a byte to be
-sent in order to transmit credentials. The text protocol described in
-this document begins after the single nul byte. If the first byte
-received from the client is not a nul byte, the server may disconnect 
-that client.
-</para>
-<para>
-A nul byte in any context other than the initial byte is an error; 
-the protocol is ASCII-only.
-</para>
-<para>
-The credentials sent along with the nul byte may be used with the 
-SASL mechanism EXTERNAL.
+        Immediately after connecting to the server, the client must send a
+        single nul byte. This byte may be accompanied by credentials
+        information on some operating systems that use sendmsg() with
+        SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
+        sockets. However, the nul byte MUST be sent even on other kinds of
+        socket, and even on operating systems that do not require a byte to be
+        sent in order to transmit credentials. The text protocol described in
+        this document begins after the single nul byte. If the first byte
+        received from the client is not a nul byte, the server may disconnect 
+        that client.
+      </para>
+      <para>
+        A nul byte in any context other than the initial byte is an error; 
+        the protocol is ASCII-only.
+      </para>
+      <para>
+        The credentials sent along with the nul byte may be used with the 
+        SASL mechanism EXTERNAL.
 
       </para>
     </sect2>
     <sect2 id="auth-command-auth">
       <title>AUTH command</title>
-<para>
-   If an AUTH command has no arguments, it is a request to list
-   available mechanisms. The server SHOULD respond with a REJECTED
-   command listing the mechanisms it understands.
-</para>
-<para>
-   If an AUTH command specifies a mechanism, and the server supports
-   said mechanism, the server SHOULD begin exchanging SASL
-   challenge-response data with the client using DATA commands.
-</para>
-<para>
-   If the server does not support the mechanism given in the AUTH
-   command, it SHOULD send a REJECTED command listing the mechanisms
-   it does support.
-</para>
-<para>
-   If the [initial-response] argument is provided, it is intended for
-   use with mechanisms that have no initial challenge (or an empty
-   initial challenge), as if it were the argument to an initial DATA
-   command. If the selected mechanism has an initial challenge, the
-   server should reject authentication by sending REJECTED.
-</para>
-<para>
-   If authentication succeeds after exchanging DATA commands, 
-   an OK command should be sent to the client. 
-</para>
-<para>
-   The first octet received by the client after the \r\n of the OK
-   command MUST be the first octet of the authenticated/encrypted 
-   stream of D-BUS messages.
-</para>
-<para>
-   The first octet received by the server after the \r\n of the BEGIN
-   command from the client MUST be the first octet of the
-   authenticated/encrypted stream of D-BUS messages.
-</para>
+      <para>
+        If an AUTH command has no arguments, it is a request to list
+        available mechanisms. The server SHOULD respond with a REJECTED
+        command listing the mechanisms it understands.
+      </para>
+      <para>
+        If an AUTH command specifies a mechanism, and the server supports
+        said mechanism, the server SHOULD begin exchanging SASL
+        challenge-response data with the client using DATA commands.
+      </para>
+      <para>
+        If the server does not support the mechanism given in the AUTH
+        command, it SHOULD send a REJECTED command listing the mechanisms
+        it does support.
+      </para>
+      <para>
+        If the [initial-response] argument is provided, it is intended for
+        use with mechanisms that have no initial challenge (or an empty
+        initial challenge), as if it were the argument to an initial DATA
+        command. If the selected mechanism has an initial challenge, the
+        server should reject authentication by sending REJECTED.
+      </para>
+      <para>
+        If authentication succeeds after exchanging DATA commands, 
+        an OK command should be sent to the client. 
+      </para>
+      <para>
+        The first octet received by the client after the \r\n of the OK
+        command MUST be the first octet of the authenticated/encrypted 
+        stream of D-BUS messages.
+      </para>
+      <para>
+        The first octet received by the server after the \r\n of the BEGIN
+        command from the client MUST be the first octet of the
+        authenticated/encrypted stream of D-BUS messages.
+      </para>
     </sect2>
-  <sect2 id="auth-command-cancel">
-    <title>CANCEL Command</title>
-    <para>
-   At any time up to sending the BEGIN command, the client may send a
-   CANCEL command. On receiving the CANCEL command, the server MUST
-   send a REJECTED command and abort the current authentication
-   exchange.
-    </para>
-  </sect2>
-  <sect2 id="auth-command-data">
-    <title>DATA Command</title>
-    <para>
-   The DATA command may come from either client or server, and simply 
-   contains a base64-encoded block of data to be interpreted 
-   according to the SASL mechanism in use.
-    </para>
-    <para>
-   Some SASL mechanisms support sending an "empty string"; 
-   FIXME we need some way to do this.
-    </para>
-  </sect2>
-  <sect2 id="auth-command-begin">
-    <title>BEGIN Command</title>
-    <para>
-   The BEGIN command acknowledges that the client has received an 
-   OK command from the server, and that the stream of messages
-   is about to begin. 
-   </para>
-   <para>
-   The first octet received by the server after the \r\n of the BEGIN
-   command from the client MUST be the first octet of the
-   authenticated/encrypted stream of D-BUS messages.
-    </para>
-  </sect2>
-  <sect2 id="auth-command-rejected">
-    <title>REJECTED Command</title>
-    <para>
-   The REJECTED command indicates that the current authentication
-   exchange has failed, and further exchange of DATA is inappropriate.
-   The client would normally try another mechanism, or try providing
-   different responses to challenges.
-   </para><para>
-   Optionally, the REJECTED command has a space-separated list of
-   available auth mechanisms as arguments. If a server ever provides
-   a list of supported mechanisms, it MUST provide the same list 
-   each time it sends a REJECTED message. Clients are free to 
-   ignore all lists received after the first.
-    </para>
-  </sect2>
-  <sect2 id="auth-command-ok">
-    <title>OK Command</title>
-    <para>
-   The OK command indicates that the client has been authenticated,
-   and that further communication will be a stream of D-BUS messages
-   (optionally encrypted, as negotiated) rather than this protocol.
-   </para>
-   <para>
-   The first octet received by the client after the \r\n of the OK
-   command MUST be the first octet of the authenticated/encrypted 
-   stream of D-BUS messages.
-   </para>
-   <para>
-   The client MUST respond to the OK command by sending a BEGIN
-   command, followed by its stream of messages, or by disconnecting.
-   The server MUST NOT accept additional commands using this protocol 
-   after the OK command has been sent.
-    </para>
-  </sect2>
-  <sect2 id="auth-command-error">
-    <title>ERROR Command</title>
-    <para>
-   The ERROR command indicates that either server or client did not
-   know a command, does not accept the given command in the current
-   context, or did not understand the arguments to the command. This
-   allows the protocol to be extended; a client or server can send a
-   command present or permitted only in new protocol versions, and if
-   an ERROR is received instead of an appropriate response, fall back
-   to using some other technique.
- </para><para>
-   If an ERROR is sent, the server or client MUST continue as if the
-   command causing the ERROR had never been received.
-    </para>
-  </sect2>
-  <sect2 id="auth-examples">
+    <sect2 id="auth-command-cancel">
+      <title>CANCEL Command</title>
+      <para>
+        At any time up to sending the BEGIN command, the client may send a
+        CANCEL command. On receiving the CANCEL command, the server MUST
+        send a REJECTED command and abort the current authentication
+        exchange.
+      </para>
+    </sect2>
+    <sect2 id="auth-command-data">
+      <title>DATA Command</title>
+      <para>
+        The DATA command may come from either client or server, and simply 
+        contains a base64-encoded block of data to be interpreted 
+        according to the SASL mechanism in use.
+      </para>
+      <para>
+        Some SASL mechanisms support sending an "empty string"; 
+        FIXME we need some way to do this.
+      </para>
+    </sect2>
+    <sect2 id="auth-command-begin">
+      <title>BEGIN Command</title>
+      <para>
+        The BEGIN command acknowledges that the client has received an 
+        OK command from the server, and that the stream of messages
+        is about to begin. 
+      </para>
+      <para>
+        The first octet received by the server after the \r\n of the BEGIN
+        command from the client MUST be the first octet of the
+        authenticated/encrypted stream of D-BUS messages.
+      </para>
+    </sect2>
+    <sect2 id="auth-command-rejected">
+      <title>REJECTED Command</title>
+      <para>
+        The REJECTED command indicates that the current authentication
+        exchange has failed, and further exchange of DATA is inappropriate.
+        The client would normally try another mechanism, or try providing
+        different responses to challenges.
+      </para><para>
+        Optionally, the REJECTED command has a space-separated list of
+        available auth mechanisms as arguments. If a server ever provides
+        a list of supported mechanisms, it MUST provide the same list 
+        each time it sends a REJECTED message. Clients are free to 
+        ignore all lists received after the first.
+      </para>
+    </sect2>
+    <sect2 id="auth-command-ok">
+      <title>OK Command</title>
+      <para>
+        The OK command indicates that the client has been authenticated,
+        and that further communication will be a stream of D-BUS messages
+        (optionally encrypted, as negotiated) rather than this protocol.
+      </para>
+      <para>
+        The first octet received by the client after the \r\n of the OK
+        command MUST be the first octet of the authenticated/encrypted 
+        stream of D-BUS messages.
+      </para>
+      <para>
+        The client MUST respond to the OK command by sending a BEGIN
+        command, followed by its stream of messages, or by disconnecting.
+        The server MUST NOT accept additional commands using this protocol 
+        after the OK command has been sent.
+      </para>
+    </sect2>
+    <sect2 id="auth-command-error">
+      <title>ERROR Command</title>
+      <para>
+        The ERROR command indicates that either server or client did not
+        know a command, does not accept the given command in the current
+        context, or did not understand the arguments to the command. This
+        allows the protocol to be extended; a client or server can send a
+        command present or permitted only in new protocol versions, and if
+        an ERROR is received instead of an appropriate response, fall back
+        to using some other technique.
+      </para><para>
+        If an ERROR is sent, the server or client MUST continue as if the
+        command causing the ERROR had never been received.
+      </para>
+    </sect2>
+    <sect2 id="auth-examples">
       <title>Authentication examples</title>
       
       <para>
-      <figure>
+        <figure>
 	  <title>Example of successful magic cookie authentication</title>
 	  <programlisting>
-(MAGIC_COOKIE is a made up mechanism)
+            (MAGIC_COOKIE is a made up mechanism)
 
-  C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
-  S: OK
-  C: BEGIN
+            C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
-      <figure>
+        <figure>
 	  <title>Example of finding out mechanisms then picking one</title>
 	  <programlisting>
-  C: AUTH
-  S: REJECTED KERBEROS_V4 SKEY
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
-  S: OK
-  C: BEGIN
+            C: AUTH
+            S: REJECTED KERBEROS_V4 SKEY
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
-      <figure>
+        <figure>
 	  <title>Example of client sends unknown command then falls back to regular auth</title>
 	  <programlisting>
-  C: FOOBAR
-  S: ERROR
-  C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
-  S: OK
-  C: BEGIN
+            C: FOOBAR
+            S: ERROR
+            C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
-      <figure>
+        <figure>
 	  <title>Example of server doesn't support initial auth mechanism</title>
 	  <programlisting>
-  C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
-  S: REJECTED KERBEROS_V4 SKEY
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
-  S: OK
-  C: BEGIN
+            C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+            S: REJECTED KERBEROS_V4 SKEY
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
-      <figure>
+        <figure>
 	  <title>Example of wrong password or the like followed by successful retry</title>
 	  <programlisting>
-  C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
-  S: REJECTED KERBEROS_V4 SKEY
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
-  S: REJECTED
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
-  S: OK
-  C: BEGIN
+            C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+            S: REJECTED KERBEROS_V4 SKEY
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+            S: REJECTED
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
-      <figure>
+        <figure>
 	  <title>Example of skey cancelled and restarted</title>
 	  <programlisting>
-  C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
-  S: REJECTED KERBEROS_V4 SKEY
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: CANCEL
-  S: REJECTED
-  C: AUTH SKEY bW9yZ2Fu
-  S: DATA OTUgUWE1ODMwOA==
-  C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
-  S: OK
-  C: BEGIN
+            C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
+            S: REJECTED KERBEROS_V4 SKEY
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: CANCEL
+            S: REJECTED
+            C: AUTH SKEY bW9yZ2Fu
+            S: DATA OTUgUWE1ODMwOA==
+            C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+            S: OK
+            C: BEGIN
           </programlisting>
 	</figure>
       </para>
@@ -679,6 +679,7 @@ SASL mechanism EXTERNAL.
     <para>
       Server addresses consist of a transport name followed by a colon, and
       then an optional, comma-separated list of keys and values in the form key=value.
+      [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
     </para>
     <para>
       For example: 
@@ -686,6 +687,8 @@ SASL mechanism EXTERNAL.
       Which is the address to a unix socket with the path /tmp/dbus-test.
     </para>
     <para>
+      [FIXME clarify if attempting to connect to each is a requirement 
+      or just a suggestion]
       When connecting to a server, multiple server addresses can be
       separated by a semi-colon. The library will then try to connect
       to the first address and if that fails, it'll try to connect to
@@ -693,6 +696,7 @@ SASL mechanism EXTERNAL.
       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
     </para>
     <para>
+      [FIXME we need to specify in detail each transport and its possible arguments]
       Currently, a transport over local UNIX sockets exists, a debug
       transport that only works in-process and therefore can be used
       for for unit testing also exists. It is possible that other
@@ -752,7 +756,7 @@ SASL mechanism EXTERNAL.
       <para>
         A reply to a message conventionally has the same name as the message
         being replied to. When following method call conventions (see <xref
-        linkend="message-conventions-method">), this convention is mandatory, 
+                                                                         linkend="message-conventions-method">), this convention is mandatory, 
           because a message with multiple possible replies can't be mapped
           to method call semantics without special-case code.
       </para>
@@ -841,8 +845,8 @@ SASL mechanism EXTERNAL.
         an application should reply with
         <literal>org.freedesktop.Peer.Ping</literal>. Neither the 
         message nor its reply have any arguments.
-      [FIXME the messages here are just made up to illustrate the 
-      format for defining them]
+        [FIXME the messages here are just made up to illustrate the 
+        format for defining them]
       </para>
     </sect2>
     <sect2 id="standard-messages-get-props">
@@ -893,8 +897,8 @@ SASL mechanism EXTERNAL.
       </para>
       <para>
         
-      [FIXME the messages here are just made up to illustrate the 
-      format for defining them]
+        [FIXME the messages here are just made up to illustrate the 
+        format for defining them]
       </para>
     </sect2>
   </sect1>
@@ -918,10 +922,10 @@ SASL mechanism EXTERNAL.
       </para>
       <para>
         Messages may have a <literal>srvc</literal> field (see <xref
-        linkend="message-protocol-header-fields">).  When the message bus
-        receives a message, if the <literal>srvc</literal> field is absent, the
-        message is taken to be a standard peer-to-peer message and interpreted
-        by the message bus itself. For example, sending
+                                                                  linkend="message-protocol-header-fields">).  When the message bus
+          receives a message, if the <literal>srvc</literal> field is absent, the
+          message is taken to be a standard peer-to-peer message and interpreted
+          by the message bus itself. For example, sending
           an <literal>org.freedesktop.Peer.Ping</literal> message with no 
           <literal>srvc</literal> will cause the message bus itself to reply 
           to the ping immediately; the message bus would never make 
@@ -933,9 +937,9 @@ SASL mechanism EXTERNAL.
         messages are routed to the owner of the named service.
         Messages may also be <firstterm>broadcast</firstterm>
         by sending them to the special service 
-        <literal>org.freedesktop.Broadcast</literal>. Broadcast messages 
-        are sent to all applications with <firstterm>message matching rules</firstterm>
-        that match the message.
+        <literal>org.freedesktop.Broadcast</literal>. Broadcast messages are
+        sent to all applications with <firstterm>message matching
+          rules</firstterm> that match the message.
       </para>
       <para>
         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
@@ -948,485 +952,88 @@ SASL mechanism EXTERNAL.
         might receive the ping, and all would normally reply to it.
       </para>
     </sect2>
-    <sect2 id="message-bus-messages">
-      <title>Message Bus Messages</title>
-      <para>
-        The special message bus service <literal>org.freedesktop.DBus</literal>
-        responds to a number of messages, allowing applications to 
-        interact with the message bus.
-      </para>
-    </sect2>
-    <sect2 id="bus-messages-hello">
-      <title><literal>org.freedesktop.DBus.Hello</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          STRING Hello ()
-        </programlisting>
-        Reply arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service assigned to the client</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        Before a client is able to send messages to other clients it
-        must send the <literal>org.freedesktop.DBus.Hello</literal>
-        message to the message bus service. If a client tries to send
-        a message to another client, or a message to the message bus
-        service that isn't the
-        <literal>org.freedesktop.DBus.Hello</literal> message, it will
-        be disconnected from the bus.
-      </para>
-      <para>
-        The reply message contains the name of the base service. Any
-        messages sent to the base service will be rereouted by the
-        message bus, delivering it to the client.
-      </para>
-    </sect2>
-    <sect2 id="bus-messages-list-services">
-      <title><literal>org.freedesktop.DBus.ListServices</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          STRING_ARRAY ListServices ()
-        </programlisting>
-        Reply arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING_ARRAY</entry>
-                <entry>Array of strings where each string is the name of a service</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        Returns a list of all existing services registered with the message bus. 
-      </para>
-    </sect2>
-    <sect2 id="bus-messages-service-exists">
-      <title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          UINT32 ServiceExists (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-        Reply arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>UINT32</entry>
-                <entry>Return value, 1 if the service exists and 0 otherwise</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        Checks if a service with a specified name exists.
-      </para>
-    </sect2>
-
-    <sect2 id="bus-messages-acquire-service">
-      <title><literal>org.freedesktop.DBus.AcquireService</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          UINT32 AcquireService (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-        Reply arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>UINT32</entry>
-                <entry>Return value</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        Tries to become owner of a specific service. The flags
-        specified can be the following values logically ORed together:
-
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Identifier</entry>
-                <entry>Value</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-	      <row>
-		<entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry>
-		<entry>0x1</entry>
-		<entry>
-                  If the client succeeds in being the owner of the specified service,
-                  then ownership of the service can't be transferred until the service
-                  disconnects. If this flag is not set, then any client trying to become
-                  the owner of the service will succeed and the previous owner will be
-                  sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message.
-</entry>
-	      </row>
-	      <row>
-		<entry>DBUS_SERVICE_FLAGS_REPLACE_EXISTING</entry>
-		<entry>0x2</entry>
-		<entry>Only become the owner of the service if there is no current owner.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</informaltable>
-
-        The return value can be one of the following values:
-
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Identifier</entry>
-                <entry>Value</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-	      <row>
-                <entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry>
-		<entry>0x1</entry>
-		<entry>The client is now the primary owner of the service.</entry>
-	      </row>
-	      <row>
-		<entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry>
-		<entry>0x2</entry>
-		<entry>The service already has an owner which do not want to give up ownership and therefore the client has been put in a queue.</entry>
-	      </row>
-	      <row>
-		<entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry>
-		<entry>0x4</entry>
-		<entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry>
-	      </row>
-	      <row>
-		<entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry>
-		<entry>0x8</entry>
-		<entry>The client trying to request ownership of the service is already the owner of it.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</informaltable>
-      </para>
-    </sect2>
-    <sect2 id="bus-messages-service-acquired">
-      <title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          ServiceAcquired (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        This message is sent to a specific client when it becomes the primary owner of a service.
-      </para>
-    </sect2>
-    <sect2 id="bus-messages-service-lost">
-      <title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          ServiceLost (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        This message is sent to a specific client when it loses primary ownership of a service.
-      </para>
-    </sect2>
-
-    <sect2 id="bus-messages-service-created">
-      <title><literal>org.freedesktop.DBus.ServiceCreated</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          ServiceCreated (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        This message is broadcast to all clients when a service has been successfully registered on the message bus.
-      </para>
-    </sect2>
 
-    <sect2 id="bus-messages-service-deleted">
-      <title><literal>org.freedesktop.DBus.ServiceDeleted</literal></title>
-      <para>
-        As a method:
-        <programlisting>
-          ServiceDeleted (in STRING service_name)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-      <para>
-        This message is broadcast to all clients when a service has been deleted from the message bus.
-      </para>
-    </sect2>
-
-    <sect2 id="bus-messages-activate-service">
-      <title><literal>org.freedesktop.DBus.ActivateService</literal></title>
+    <sect2 id="message-bus-services">
+      <title>Message Bus Services</title>
       <para>
-        As a method:
-        <programlisting>
-          void ActivateService (in STRING service_name, in UINT32 flags)
-        </programlisting>
-        Message arguments:
-        <informaltable>
-          <tgroup cols=3>
-            <thead>
-              <row>
-                <entry>Argument</entry>
-                <entry>Type</entry>
-                <entry>Description</entry>
-              </row>
-            </thead>
-            <tbody>
-              <row>
-                <entry>0</entry>
-                <entry>STRING</entry>
-                <entry>Name of the service to activate</entry>
-              </row>
-	      <row>
-		<entry>1</entry>
-		<entry>UINT32</entry>
-		<entry>Flags (currently not used)</entry>
-	      </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
+        A service is a name that identifies a certain application. Each
+        application connected to the message bus has at least one service name
+        assigned at connection time and returned in response to the
+        <literal>org.freedesktop.DBus.Hello</literal> message.
+        This automatically-assigned service name is called 
+        the application's <firstterm>base service</firstterm>. 
+        Base service names are unique and MUST never be reused for two different 
+        applications.
       </para>
       <para>
-        Tries to launch the executable associated with a service. For more information, see the part on <xref linkend="message-bus-activation">
+        [FIXME I think we should define the format of the base service name, 
+        and specify that a regular service name can never be in that 
+        format; this allows us to categorically prevent "spoofing" - for 
+        example perhaps the base service name starts with a certain 
+        character that no real service name can start with]
       </para>
-    </sect2>
-
-    <sect2 id="services">
-      <title>Message Bus Services</title>
       <para>
-        A service is a name that identifies a certain client. Each
-        client connected to the message bus has at least one service
-        name acquired through the
-        <literal>org.freedesktop.DBus.Hello</literal> message. In
-        addition, a client can request additional service names to be
-        associated with it using the
+        An application can request additional service names to be associated
+        with it using the
         <literal>org.freedesktop.DBus.AcquireService</literal>
-        message.
+        message. [FIXME what service names are allowed; ASCII or unicode; 
+        length limit; etc.]
       </para>
       <para>
+        [FIXME this needs more detail, and should move the service-related message 
+        descriptions up into this section perhaps]
         Service ownership handling can be specified in the flags part
         of the <literal>org.freedesktop.DBus.AcquireService</literal>
-        message. If a client specifies the
-        DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all clients
+        message. If an application specifies the
+        DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications
         trying to acquire the service will be put in a queue. When the
         primary owner disconnects from the bus or removes ownership
-        from the service, the next client in the queue will be the
+        from the service, the next application in the queue will be the
         primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT
         flag is not specified, then the primary owner will lose
-        ownership whenever another client requests ownership of the
+        ownership whenever another application requests ownership of the
         service.
       </para>
     </sect2>
+    <sect2 id="message-bus-routing">
+      <title>Message Bus Message Routing</title>
+      <para>
+        When a message is received by the message bus, the message's 
+        <literal>sndr</literal> header field MUST be set to the base service of
+        the application which sent the message.  If the service already has
+        a <literal>sndr</literal> field, the pre-existing field is replaced.
+        This rule means that a replies are always sent to the base service name,
+        i.e. to the same application that sent the message being replied to.
+      </para>
+      <para>
+        [FIXME go into detail about broadcast, multicast, unicast, etc.]
+      </para>
+    </sect2>
     <sect2 id="message-bus-activation">
       <title>Message Bus Service Activation</title>
       <para>
-        Activation is a way to launch executables that handle certain
-        services. The bus daemon looks in certain directories
-        (possibly different depending on if it's a system bus or a
-        message bus) for service description files.
+        <firstterm>Activation</firstterm> means to locate a service 
+        owner for a service that is currently unowned. For now, it 
+        means to launch an executable that will take ownership of 
+        a particular service.
       </para>
       <para>
+        To find an executable corresponding to a particular service, the bus
+        daemon looks for <firstterm>service description files</firstterm>.
+        Service description files define a mapping from service names to
+        executables. Different kinds of message bus will look for these files
+        in different places, see <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
         extension. The message bus will only load service description
         files ending with .service; all other files will be ignored.
         The file format is similar to that of <ulink
-        url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
-        entries</ulink>. All service description files must be in
+                                                 url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
+          entries</ulink>. All service description files must be in
         UTF-8 encoding.
 
         <figure>
@@ -1440,37 +1047,505 @@ SASL mechanism EXTERNAL.
 	</figure>
       </para>
       <para>
-        When a client requests a service to be activated, the bus
+        When an application requests a service to be activated, the bus
         daemon tries to find it in the list of activation entries. It
         then tries to spawn the executable associated with it. If this
-        fails, it will report an error.
+        fails, it will report an error. [FIXME what happens if two 
+        .service files offer the same service; what kind of error is reported]
       </para>
       <para>
         The executable launched will have the environment variable
-        <literal>DBUS_ADDRESS</literal> set to the address of the
-        server so it can connect and register the appropriate services.
+        <literal>DBUS_BUS_ADDRESS</literal> set to the address of the
+        message bus so it can connect and register the appropriate services.
       </para>
     </sect2>
-    <sect2 id="message-bus-location">
-      <title>Finding The Message Bus</title>
+
+    <sect2 id="message-bus-types">
+      <title>Standard Message Bus Instances</title>
       <para>
         Two standard message bus instances are defined here, along with how 
-        to locate them.
-      </para>
-      <para>
-        Each time a user logs in, a <firstterm>login session message
-        bus</firstterm> may be started. All applications in the user's login
-        session may interact with one another using this message bus.  [specify
-        how to find the address of the login session message bus via
-        environment variable and/or X property]
+        to locate them and where their service files live.
       </para>
+      <sect3 id="message-bus-types-login">
+        <title>Login session message bus</title>
+        <para>
+          Each time a user logs in, a <firstterm>login session message
+            bus</firstterm> may be started. All applications in the user's login
+          session may interact with one another using this message bus.  [specify
+          how to find the address of the login session message bus via
+          environment variable and/or X property]
+        </para>
+        <para>
+          [FIXME specify location of .service files, probably using 
+          DESKTOP_DIRS etc. from basedir specification, though login session 
+          bus is not really desktop-specific]
+        </para>
+      </sect3>
+      <sect3 id="message-bus-types-system">
+        <title>System message bus</title>
+        <para>
+          A computer may have a <firstterm>system message bus</firstterm>,
+          accessible to all applications on the system. This message bus may be
+          used to broadcast system events, such as adding new hardware devices.
+          [specify how to find the address of the system message bus]
+        </para>
+        <para>
+          [FIXME specify location of system bus .service files]
+        </para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="message-bus-messages">
+      <title>Message Bus Messages</title>
       <para>
-        A computer may have a <firstterm>system message bus</firstterm>,
-        accessible to all applications on the system. This message bus may be
-        used to broadcast system events, such as adding new hardware devices.
-        [specify how to find the address of the system message bus]
+        The special message bus service <literal>org.freedesktop.DBus</literal>
+        responds to a number of messages, allowing applications to 
+        interact with the message bus.
       </para>
+
+      <sect3 id="bus-messages-hello">
+        <title><literal>org.freedesktop.DBus.Hello</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            STRING Hello ()
+          </programlisting>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service assigned to the application</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          Before an application is able to send messages to other applications it
+          must send the <literal>org.freedesktop.DBus.Hello</literal>
+          message to the message bus service. If an application tries to send
+          a message to another application, or a message to the message bus
+          service that isn't the
+          <literal>org.freedesktop.DBus.Hello</literal> message, it will
+          be disconnected from the bus.
+        </para>
+        <para>
+          The reply message contains the name of the application's base service.
+        </para>
+      </sect3>
+      <sect3 id="bus-messages-list-services">
+        <title><literal>org.freedesktop.DBus.ListServices</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            STRING_ARRAY ListServices ()
+          </programlisting>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING_ARRAY</entry>
+                  <entry>Array of strings where each string is the name of a service</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          Returns a list of all existing services registered with the message bus. 
+        </para>
+      </sect3>
+      <sect3 id="bus-messages-service-exists">
+        <title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            UINT32 ServiceExists (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>UINT32</entry>
+                  <entry>Return value, 1 if the service exists and 0 otherwise</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          Checks if a service with a specified name exists.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-acquire-service">
+        <title><literal>org.freedesktop.DBus.AcquireService</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            UINT32 AcquireService (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>UINT32</entry>
+                  <entry>Return value</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          Tries to become owner of a specific service. The flags
+          specified can be the following values logically ORed together:
+
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Identifier</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	        <row>
+		  <entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry>
+		  <entry>0x1</entry>
+		  <entry>
+                    If the application succeeds in being the owner of the specified service,
+                    then ownership of the service can't be transferred until the service
+                    disconnects. If this flag is not set, then any application trying to become
+                    the owner of the service will succeed and the previous owner will be
+                    sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message.
+                  </entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_SERVICE_FLAGS_REPLACE_EXISTING</entry>
+		  <entry>0x2</entry>
+		  <entry>Only become the owner of the service if there is no current owner.</entry>
+	        </row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+
+          [FIXME if it's one of the following values, why are the values
+          done as flags instead of just 0, 1, 2, 3, 4]
+          The return value can be one of the following values:
+
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Identifier</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	        <row>
+                  <entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry>
+		  <entry>0x1</entry>
+		  <entry>The application is now the primary owner of the service.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry>
+		  <entry>0x2</entry>
+		  <entry>The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry>
+		  <entry>0x4</entry>
+		  <entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry>
+		  <entry>0x8</entry>
+		  <entry>The application trying to request ownership of the service is already the owner of it.</entry>
+	        </row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+        </para>
+      </sect3>
+      <sect3 id="bus-messages-service-acquired">
+        <title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ServiceAcquired (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This message is sent to a specific application when it becomes the
+          primary owner of a service.
+        </para>
+      </sect3>
+      <sect3 id="bus-messages-service-lost">
+        <title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ServiceLost (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This message is sent to a specific application when it loses primary
+          ownership of a service.
+
+          [FIXME instead of ServiceLost/ServiceCreated going only to 
+          a specific app, why not just OwnerChanged that covers both 
+          lost and created and changed owner and deleted]
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-service-created">
+        <title><literal>org.freedesktop.DBus.ServiceCreated</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ServiceCreated (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This message is broadcast to all applications when a service has been
+          successfully registered on the message bus.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-service-deleted">
+        <title><literal>org.freedesktop.DBus.ServiceDeleted</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            ServiceDeleted (in STRING service_name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This message is broadcast to all applications when a service has been
+          deleted from the message bus.
+        </para>
+      </sect3>
+
+      <sect3 id="bus-messages-activate-service">
+        <title><literal>org.freedesktop.DBus.ActivateService</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            void ActivateService (in STRING service_name, in UINT32 flags)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols=3>
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name of the service to activate</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags (currently not used)</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation">.
+
+            [FIXME need semantics in much more detail here; for example, 
+            if I activate a service then send it a message, is the message 
+            queued for the new service or is there a race]
+        </para>
+      </sect3>
     </sect2>
+
   </sect1>
 <!--
   <appendix id="implementation-notes">
@@ -1488,12 +1563,32 @@ SASL mechanism EXTERNAL.
       This glossary defines some of the terms used in this specification.
     </para>
 
+    <glossentry id="term-activation"><glossterm>Activation</glossterm>
+      <glossdef>
+        <para>
+          The process of creating an owner for a particular service, 
+          typically by launching an executable.
+        </para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry id="term-base-service"><glossterm>Base Service</glossterm>
+      <glossdef>
+        <para>
+          The special service automatically assigned to an application by the 
+          message bus. This service may never change owner, and the service 
+          name will be unique (never reused during the lifetime of the 
+          message bus).
+        </para>
+      </glossdef>
+    </glossentry>
+
     <glossentry id="term-broadcast"><glossterm>Broadcast</glossterm>
       <glossdef>
         <para>
           A message sent to the special <literal>org.freedesktop.Broadcast</literal>
           service; the message bus will forward the broadcast message 
-          to all clients that have expressed interest in it.
+          to all applications that have expressed interest in it.
         </para>
       </glossdef>
     </glossentry>
@@ -1535,6 +1630,15 @@ SASL mechanism EXTERNAL.
       </glossdef>
     </glossentry>
 
+    <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
+      <glossdef>
+        <para>
+          ".service files" tell the bus how to activate a particular service.
+          See <xref linkend="term-activation">
+        </para>
+      </glossdef>
+    </glossentry>
+
   </glossary>
 </article>