2005-01-18 Havoc Pennington <hp@redhat.com>

        * Throughout, grand renaming to strip out the use of "service",
	just say "name" instead (or "bus name" when ambiguous).  Did not
	change the internal code of the message bus itself, only the
	programmer-facing API and messages.

	* doc/dbus-specification.xml: further update the message bus section

	* bus/config-parser.c (all_are_equiv): fix bug using freed string
	in error case

1 files changed, 459 insertions, 503 deletions

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index f2c0146b..821c6011 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -96,6 +96,30 @@
       monitoring service or a configuration service.
     </para>
 
+    <para>
+      D-BUS is designed for two specific use cases:
+      <itemizedlist>
+        <listitem>
+          <para>
+            A "system bus" for notifications from the system to user sessions,
+            and to allow the system to request input from user sessions.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            A "session bus" used to implement desktop environments such as 
+            GNOME and KDE.
+          </para>
+        </listitem>
+      </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 
+      incorporate features that interfere with the core use cases.
+    </para>
+    
   </sect1>
 
   <sect1 id="message-protocol">
@@ -733,10 +757,11 @@
                 to return the reply despite this flag.</entry>
               </row>
               <row>
-                <entry><literal>AUTO_ACTIVATION</literal></entry>
+                <entry><literal>AUTO_START</literal></entry>
                 <entry>0x2</entry>
-                <entry>This message automatically activates the
-                addressed service before the message is delivered.</entry>
+                <entry>This message automatically launches an owner
+                  for the destination name before the message is delivered.
+                </entry>
               </row>
             </tbody>
           </tgroup>
@@ -841,7 +866,7 @@
                   <entry>6</entry>
                   <entry><literal>STRING</literal></entry>
                   <entry>optional</entry>
-                  <entry>The name of the service this message should be routed to. 
+                  <entry>The name of the connection this message should be routed to. 
                     Only used in combination with the message bus, see 
                     <xref linkend="message-bus"/>.</entry>
                 </row>
@@ -850,8 +875,8 @@
                   <entry>7</entry>
                   <entry><literal>STRING</literal></entry>
                   <entry>optional</entry>
-                  <entry>Sender service. The name of the base service that sent
-                    this message.  The message bus fills in this field; the field is
+                  <entry>Unique name of the sending connection.
+                    The message bus fills in this field so it is reliable; the field is
                     only meaningful in combination with the message bus.</entry>
                 </row>
                 <row>
@@ -877,8 +902,7 @@
       </para>
       <para>
         There is a <firstterm>maximum name length</firstterm> 
-        of 255 which applies to service, interface, and member 
-        names.
+        of 255 which applies to bus names, interfaces, and members. 
       </para>
       <sect3 id="message-protocol-names-interface">
         <title>Interface names</title>
@@ -907,15 +931,15 @@
           </itemizedlist>
         </para>
       </sect3>
-      <sect3 id="message-protocol-names-service">
-        <title>Service names</title>
+      <sect3 id="message-protocol-names-bus">
+        <title>Bus names</title>
         <para>
-          Service names have the same restrictions as interface names, with a
-          special exception for base services. A base service name's first
+          Bus names have the same restrictions as interface names, with a
+          special exception for unique connection names. A unique name's first
           element must start with a colon (':') character. After the colon, any
           characters in "[A-Z][a-z][0-9]_" may appear. Elements after
           the first must follow the usual rules, except that they may start with
-          a digit. Service names not starting with a colon have none of these 
+          a digit. Bus names not starting with a colon have none of these 
           exceptions and follow the same rules as interface names.
         </para>
       </sect3>
@@ -966,10 +990,11 @@
           implementations must not require an interface field.
         </para>
         <para>
-          Method call messages also include a <literal>PATH</literal> field indicating the 
-          object to invoke the method on. If the call is passing through 
-          a message bus, the message will also have a <literal>DESTINATION</literal> field giving 
-          the service to receive the message.
+          Method call messages also include a <literal>PATH</literal> field
+          indicating the object to invoke the method on. If the call is passing
+          through a message bus, the message will also have a
+          <literal>DESTINATION</literal> field giving the name of the connection
+          to receive the message.
         </para>
         <para>
           When an application handles a method call message, it is expected to
@@ -1002,14 +1027,13 @@
           flag and reply anyway.
         </para>
         <para>
-          If a message has the flag <literal>AUTO_ACTIVATION</literal>, then the addressed
-          service will be activated before the message is delivered, if
-          not already active. The message will be held until the service
-          is successfully activated or has failed to activate; in case
-          of failure, an activation error will be returned. Activation 
-          is only relevant in the context of a message bus, so this 
-          flag is ignored for one-to-one communication with no 
-          intermediate bus.
+          If a message has the flag <literal>AUTO_START</literal> and the
+          destination name does not exist, then a program to own the destination
+          name will be started before the message is delivered.  The message
+          will be held until the new program is successfully started or has
+          failed to start; in case of failure, an error will be returned. This
+          flag is only relevant in the context of a message bus, it is ignored
+          during one-to-one communication with no intermediate bus.
         </para>
         <sect4 id="message-protocol-types-method-apis">
           <title>Mapping method calls to native APIs</title>
@@ -1086,10 +1110,10 @@
           This document uses a simple pseudo-IDL to describe particular method 
           calls and signals. Here is an example of a method call:
           <programlisting>
-            org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags,
-                                                  out UINT32 resultcode)
+            org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
+                                                     out UINT32 resultcode)
           </programlisting>
-          This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = ActivateService, 
+          This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName, 
           <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
           is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
           characters so it's known that the last part of the name in
@@ -1098,14 +1122,14 @@
         <para>
           In C++ that might end up looking like this:
           <programlisting>
-            unsigned int org::freedesktop::DBus::ActivateService (const char  *service_name, 
-                                                                  unsigned int flags);
+            unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
+                                                                     unsigned int flags);
           </programlisting>
           or equally valid, the return value could be done as an argument:
           <programlisting>
-            void org::freedesktop::DBus::ActivateService (const char   *service_name, 
-                                                          unsigned int  flags,
-                                                          unsigned int *resultcode);
+            void org::freedesktop::DBus::StartServiceByName (const char   *name, 
+                                                             unsigned int  flags,
+                                                             unsigned int *resultcode);
           </programlisting>
           It's really up to the API designer how they want to make 
           this look. You could design an API where the namespace wasn't used 
@@ -1114,7 +1138,7 @@
         <para>
           Signals are written as follows:
           <programlisting>
-            org.freedesktop.DBus.ServiceLost (STRING service_name)
+            org.freedesktop.DBus.NameLost (STRING name)
           </programlisting>
           Signals don't specify "in" vs. "out" because only 
           a single direction is possible.
@@ -1988,42 +2012,6 @@
       </para>
     </sect2>
 
-    <sect2 id="standard-messages-get-props">
-      <title><literal>org.freedesktop.Props.Get</literal></title>
-      <para>
-        [FIXME this is just a bogus made-up method that isn't implemented 
-        or thought through, to save an example of table formatting for the 
-        argument descriptions]
-        <programlisting>
-          org.freedesktop.Props.Get (in STRING property_name,
-                                     out ANY_OR_NIL property_value)
-        </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>in STRING</entry>
-                <entry>Name of the property to get</entry>
-              </row>
-              <row>
-                <entry>1</entry>
-                <entry>out ANY_OR_NIL</entry>
-                <entry>The value of the property. The type depends on the property.</entry>
-              </row>
-            </tbody>
-          </tgroup>
-        </informaltable>
-      </para>
-    </sect2>
   </sect1>
 
   <sect1 id="message-bus">
@@ -2032,188 +2020,316 @@
       <title>Message Bus Overview</title>
       <para>
         The message bus accepts connections from one or more applications. 
-        Once connected, applications can send and receive messages from 
-        the message bus, as in the one-to-one case.
+        Once connected, applications can exchange messages with other 
+        applications that are also connected to the bus.
       </para>
       <para>
-        The message bus keeps track of a set of
-        <firstterm>services</firstterm>. A service is simply a name, such as
-        <literal>com.yoyodyne.Screensaver</literal>, which can be
-        <firstterm>owned</firstterm> by one or more of the connected
-        applications.  The message bus itself always owns the special service
-        <literal>org.freedesktop.DBus</literal>.
+        In order to route messages among connections, the message bus keeps a
+        mapping from names to connections. Each connection has one
+        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,
+        that connection is said to <firstterm>own</firstterm> the name.
       </para>
       <para>
-        Services may have <firstterm>secondary owners</firstterm>. Secondary owners
-        of a service are kept in a queue; if the primary owner of a service 
-        disconnects, or releases the service, the next secondary owner becomes
-        the new owner of the service.
+        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.
       </para>
       <para>
+        Each name may have <firstterm>queued owners</firstterm>.  When an
+        application requests a name for a connection and the name is already in
+        use, the bus will optionally add the connection to a queue waiting for 
+        the name. If the current owner of the name disconnects or releases
+        the name, the next connection in the queue will become the new owner.
+      </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"/>).  When the message bus
-          receives a message, if the <literal>DESTINATION</literal> field is absent, the
-          message is taken to be a standard one-to-one message and interpreted
-          by the message bus itself. For example, sending
-          an <literal>org.freedesktop.Peer.Ping</literal> message with no 
-          <literal>DESTINATION</literal> will cause the message bus itself to reply 
-          to the ping immediately; the message bus would never make 
-          this message visible to other applications.
-      </para>
-      <para>
-        If the <literal>DESTINATION</literal> field is present, then it indicates a
-        request for the message bus to route the message. In the usual case,
-        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.DBus.Broadcast</literal>. Broadcast messages are
-        sent to all applications with <firstterm>message matching
-          rules</firstterm> that match the message.
+        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.
       </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.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.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. If
-        <literal>org.freedesktop.Peer.Ping</literal> were sent to
-        <literal>org.freedesktop.DBus.Broadcast</literal>, then multiple applications
-        might receive the ping, and all would normally reply to it.
+        expected to reply to the ping.
       </para>
     </sect2>
 
-    <sect2 id="message-bus-services">
-      <title>Message Bus Services</title>
+    <sect2 id="message-bus-names">
+      <title>Message Bus Names</title>
       <para>
-        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.
+        Each connection has at least one name, assigned at connection time and
+        returned in response to the
+        <literal>org.freedesktop.DBus.Hello</literal> method call.  This
+        automatically-assigned name is called the connection's <firstterm>unique
+        name</firstterm>.  Unique names are never reused for two different
+        connections to the same bus.
       </para>
       <para>
-        Ownership of the base service is a prerequisite for interaction with 
-        the message bus. It logically follows that the base service is always 
-        the first service that an application comes to own, and the last 
-        service that it loses ownership of.
+        Ownership of a unique name is a prerequisite for interaction with 
+        the message bus. It logically follows that the unique name is always 
+        the first name that an application comes to own, and the last 
+        one that it loses ownership of.
       </para>
       <para>
-        Base service names must begin with the character ':' (ASCII colon
-        character); service names that are not base service names must not begin
+        Unique connection names must begin with the character ':' (ASCII colon
+        character); bus names that are not unique names must not begin
         with this character. (The bus must reject any attempt by an application
-        to manually create a service name beginning with ':'.) This restriction
-        categorically prevents "spoofing"; messages sent to a base service name
-        will always go to a single application instance and that instance only.
-      </para>
-      <para>
-        An application can request additional service names to be associated
-        with it using the
-        <literal>org.freedesktop.DBus.AcquireService</literal>
-        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 an application specifies the
-        <literal>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</literal> 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 application in the queue will be the
-        primary owner. If the <literal>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</literal>
-        flag is not specified, then the primary owner will lose
-        ownership whenever another application requests ownership of the
-        service.
-      </para>
-      <para>
-        When a client disconnects from the bus, all the services that
-        the clients own are deleted, or in the case of a service that
-        prohibits replacement, ownership is transferred to the next
-        client in the queue, if any.
+        to manually request a name beginning with ':'.) This restriction
+        categorically prevents "spoofing"; messages sent to a unique name
+        will always go to the expected connection.
       </para>
+      <para>
+        When a connection is closed, all the names that it owns are deleted (or
+        transferred to the next connection in the queue if any).
+      </para>
+      <para>
+        A connection can request additional names to be associated with it using
+        the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
+        linkend="message-protocol-names-bus"/> describes the format of a valid
+        name.
+      </para>
+
+      <sect3 id="bus-messages-request-name">
+        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            UINT32 RequestName (in STRING name, in UINT32 flags)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name to request</entry>
+                </row>
+	        <row>
+		  <entry>1</entry>
+		  <entry>UINT32</entry>
+		  <entry>Flags</entry>
+	        </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>UINT32</entry>
+                  <entry>Return value</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This method call should be sent to
+          <literal>org.freedesktop.DBus</literal> and asks the message bus to
+          assign the given name to the method caller.  The flags argument
+          contains any of the following values logically ORed together:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Conventional Name</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	        <row>
+		  <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
+		  <entry>0x1</entry>
+		  <entry>
+                    If the application succeeds in becoming the owner of the specified name,
+                    then ownership of the name can't be transferred until the application
+                    disconnects. If this flag is not set, then any application trying to become
+                    the owner of the name will succeed and the previous owner will be
+                    sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
+                  </entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
+		  <entry>0x2</entry>
+		  <entry>
+                    Try to replace the current owner if there is one. If this
+                    flag is not set the application will only become the owner of
+                    the name if there is no current owner.
+                  </entry>
+	        </row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+
+          The return code can be one of the following values:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Conventional Name</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	        <row>
+                  <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
+		  <entry>1</entry> <entry>The caller is now the primary owner of
+		  the name, replacing any previous owner. Either the name had no
+		  owner before, or the caller specified
+		  DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
+		  specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
+		  <entry>2</entry>
+		  <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
+		  <entry>3</entry>
+		  <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
+	        </row>
+	        <row>
+		  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
+		  <entry>4</entry>
+		  <entry>The application trying to request ownership of a name is already the owner of it.</entry>
+	        </row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+        </para>
+      </sect3>
     </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.
+        FIXME 
       </para>
+    </sect2>
+    <sect2 id="message-bus-starting-services">
+      <title>Message Bus Starting Services</title>
       <para>
-        [FIXME go into detail about broadcast, multicast, unicast, etc.]
+        The message bus can start applications on behalf of other applications.
+        In CORBA terms, this would be called <firstterm>activation</firstterm>.
+        An application that can be started in this way is called a
+        <firstterm>service</firstterm>.
       </para>
-    </sect2>
-    <sect2 id="message-bus-activation">
-      <title>Message Bus Service Activation</title>
       <para>
-        <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.
+        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 
+        the owner of that name will provide, and what interfaces those 
+        objects will have.
       </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"/>.
+        To find an executable corresponding to a particular name, the bus daemon
+        looks for <firstterm>service description files</firstterm>.  Service
+        description files define a mapping from names to executables. Different
+        kinds of message bus will look for these files in different places, see
+        <xref linkend="message-bus-types"/>.
       </para>
       <para>
-        [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
+        [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
-        UTF-8 encoding. To ensure that there will be no name
-        collisions, service files must be namespaced using the same
-        mechanism as messages and service names.
+        entries</ulink>. All service description files must be in UTF-8
+        encoding. To ensure that there will be no name collisions, service files
+        must be namespaced using the same mechanism as messages and service
+        names.
 
         <figure>
 	  <title>Example service description file</title>
 	  <programlisting>
             # Sample service description file
             [D-BUS Service]
-            Name=org.gnome.ConfigurationDatabase
+            Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
             Exec=/usr/libexec/gconfd-2
           </programlisting>
 	</figure>
       </para>
       <para>
-        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. [FIXME what
-        happens if two .service files offer the same service; what
-        kind of error is reported, should we have a way for the client
-        to choose one?]
+        When an application asks to start a service by name, the bus daemon tries to
+        find a service that will own that name. It then tries to spawn the
+        executable associated with it. If this fails, it will report an
+        error. [FIXME what happens if two .service files offer the same service;
+        what kind of error is reported, should we have a way for the client to
+        choose one?]
       </para>
       <para>
         The executable launched will have the environment variable
-        <literal>DBUS_ACTIVATION_ADDRESS</literal> set to the address of the
-        message bus so it can connect and register the appropriate services.
+        <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
+        message bus so it can connect and request the appropriate names.
       </para>
       <para>
         The executable being launched may want to know whether the message bus
-        activating it is one of the well-known message buses (see <xref
+        starting it is one of the well-known message buses (see <xref
         linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
-        the <literal>DBUS_ACTIVATION_BUS_TYPE</literal> environment variable if it is one
+        the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
         of the well-known buses. The currently-defined values for this variable
         are <literal>system</literal> for the systemwide message bus,
         and <literal>session</literal> for the per-login-session message
-        bus. The activated executable must still connect to the address given
-        in <literal>DBUS_ACTIVATION_ADDRESS</literal>, but may assume that the
+        bus. The new executable must still connect to the address given
+        in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
         resulting connection is to the well-known bus.
       </para>
       <para>
@@ -2262,7 +2378,7 @@
           changes in the printer queue, and so forth.
         </para>
         <para>
-          The address of the login session message bus is given 
+          The address of the system message bus is given 
           in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment 
           variable. If that variable is not set, applications should try 
           to connect to the well-known address
@@ -2284,9 +2400,8 @@
     <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.
+        The special message bus name <literal>org.freedesktop.DBus</literal>
+        responds to a number of additional messages.
       </para>
 
       <sect3 id="bus-messages-hello">
@@ -2310,34 +2425,33 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service assigned to the application</entry>
+                  <entry>Unique name assigned to the connection</entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
         </para>
         <para>
-          Before an application is able to send messages to other
-          applications it must send the
-          <literal>org.freedesktop.DBus.Hello</literal> message to the
-          message bus 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. If a client wishes to
-          disconnect from the bus, it just has to disconnect from the
-          transport used. No de-registration message is necessary.
+          Before an application is able to send messages to other applications
+          it must send the <literal>org.freedesktop.DBus.Hello</literal> message
+          to the message bus to obtain a unique name. If an application without
+          a unique name tries to send a message to another application, or a
+          message to the message bus itself that isn't the
+          <literal>org.freedesktop.DBus.Hello</literal> message, it will be
+          disconnected from the bus.
         </para>
         <para>
-          The reply message contains the name of the application's base service.
+          There is no corresponding "disconnect" request; if a client wishes to
+          disconnect from the bus, it simply closes the socket (or other 
+          communication channel).
         </para>
       </sect3>
-      <sect3 id="bus-messages-list-services">
-        <title><literal>org.freedesktop.DBus.ListServices</literal></title>
+      <sect3 id="bus-messages-list-names">
+        <title><literal>org.freedesktop.DBus.ListNames</literal></title>
         <para>
           As a method:
           <programlisting>
-            STRING_ARRAY ListServices ()
+            ARRAY of STRING ListNames ()
           </programlisting>
           Reply arguments:
           <informaltable>
@@ -2352,23 +2466,23 @@
               <tbody>
                 <row>
                   <entry>0</entry>
-                  <entry>STRING_ARRAY</entry>
-                  <entry>Array of strings where each string is the name of a service</entry>
+                  <entry>ARRAY of STRING</entry>
+                  <entry>Array of strings where each string is a bus name</entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
         </para>
         <para>
-          Returns a list of all existing services registered with the message bus. 
+          Returns a list of all currently-owned names on the bus.
         </para>
       </sect3>
-      <sect3 id="bus-messages-service-exists">
-        <title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
+      <sect3 id="bus-messages-name-exists">
+        <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
         <para>
           As a method:
           <programlisting>
-            BOOLEAN ServiceExists (in STRING service_name)
+            BOOLEAN NameHasOwner (in STRING name)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2384,7 +2498,7 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service</entry>
+                  <entry>Name to check</entry>
                 </row>
               </tbody>
             </tgroup>
@@ -2403,23 +2517,23 @@
                 <row>
                   <entry>0</entry>
                   <entry>BOOLEAN</entry>
-                  <entry>Return value, true if the service exists</entry>
+                  <entry>Return value, true if the name exists</entry>
                 </row>
               </tbody>
             </tgroup>
           </informaltable>
         </para>
         <para>
-          Checks if a service with a specified name exists.
+          Checks if the specified name exists (currently has an owner).
         </para>
       </sect3>
 
-      <sect3 id="bus-messages-acquire-service">
-        <title><literal>org.freedesktop.DBus.AcquireService</literal></title>
+      <sect3 id="bus-messages-name-owner-changed">
+        <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
         <para>
-          As a method:
+          This is a signal:
           <programlisting>
-            UINT32 AcquireService (in STRING service_name)
+            NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2435,154 +2549,34 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service</entry>
+                  <entry>Name with a new owner</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>Try to replace the current owner if there is one. If this flag
-                  is not set the application will only become the owner of the 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>
+		  <entry>STRING</entry>
+		  <entry>Old owner or empty string if none</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>
+		  <entry>2</entry>
+		  <entry>STRING</entry>
+		  <entry>New owner or empty string if none</entry>
 	        </row>
               </tbody>
             </tgroup>
           </informaltable>
         </para>
         <para>
-          This message is sent to a specific application when it becomes the
-          primary owner of a service.
+          This signal indicates that the owner of a name has changed.
+          It's also the signal to use to detect the appearance of 
+          new names on the bus.
         </para>
       </sect3>
-      <sect3 id="bus-messages-service-lost">
-        <title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
+      <sect3 id="bus-messages-name-lost">
+        <title><literal>org.freedesktop.DBus.NameLost</literal></title>
         <para>
-          As a method:
+          This is a signal:
           <programlisting>
-            ServiceLost (in STRING service_name)
+            NameLost (STRING name)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2598,28 +2592,24 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service</entry>
+                  <entry>Name which was lost</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.
+          This signal is sent to a specific application when it loses
+          ownership of a name.
         </para>
       </sect3>
 
-      <sect3 id="bus-messages-service-owner-changed">
-        <title><literal>org.freedesktop.DBus.ServiceOwnerChanged</literal></title>
+      <sect3 id="bus-messages-name-acquired">
+        <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
         <para>
+          This is a signal:
           <programlisting>
-            ServiceOwnerChanged (STRING service_name, STRING old_owner, STRING new_owner)
+            NameAcquired (STRING name)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2635,37 +2625,24 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service</entry>
+                  <entry>Name which was acquired</entry>
                 </row>
-	        <row>
-		  <entry>1</entry>
-		  <entry>STRING</entry>
-		  <entry>Base service of previous owner, empty string if the
-		  service is newly created</entry>
-	        </row>
-	        <row>
-		  <entry>2</entry>
-		  <entry>STRING</entry>
-		  <entry>Base service of new owner, empty string if the
-		  service is no longer available</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, has been deleted
-          or its primary owner has changed.
+          This signal is sent to a specific application when it gains
+          ownership of a name.
         </para>
       </sect3>
 
-      <sect3 id="bus-messages-activate-service">
-        <title><literal>org.freedesktop.DBus.ActivateService</literal></title>
+      <sect3 id="bus-messages-start-service-by-name">
+        <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
         <para>
           As a method:
           <programlisting>
-            UINT32 ActivateService (in STRING service_name, in UINT32 flags)
+            UINT32 StartServiceByName (in STRING name, in UINT32 flags)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2681,7 +2658,7 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service to activate</entry>
+                  <entry>Name of the service to start</entry>
                 </row>
 	        <row>
 		  <entry>1</entry>
@@ -2710,15 +2687,12 @@
             </tbody>
           </tgroup>
         </informaltable>
-          Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation"/>.
+          Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
 
-            [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>
         <para>
           The return value can be one of the following values:
-    <informaltable>
+          <informaltable>
             <tgroup cols="3">
               <thead>
                 <row>
@@ -2729,14 +2703,14 @@
               </thead>
               <tbody>
 	        <row>
-                  <entry>DBUS_ACTIVATION_REPLY_ACTIVATED</entry>
-                  <entry>0x0</entry>
-                  <entry>The service was activated successfully.</entry>
+                  <entry>DBUS_START_REPLY_SUCCESS</entry>
+                  <entry>1</entry>
+                  <entry>The service was successfully started.</entry>
                 </row>
                 <row>
-                  <entry>DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE</entry>
-                  <entry>0x1</entry>
-                  <entry>The service is already active.</entry>
+                  <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
+                  <entry>2</entry>
+                  <entry>A connection already owns the given name.</entry>
                 </row>
               </tbody>
              </tgroup>
@@ -2745,12 +2719,12 @@
 
       </sect3>
 
-      <sect3 id="bus-messages-get-service-owner">
-        <title><literal>org.freedesktop.DBus.GetServiceOwner</literal></title>
+      <sect3 id="bus-messages-get-name-owner">
+        <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
         <para>
           As a method:
           <programlisting>
-            STRING GetServiceOwner (in STRING service_name)
+            STRING GetNameOwner (in STRING name)
           </programlisting>
           Message arguments:
           <informaltable>
@@ -2766,7 +2740,7 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the service to query</entry>
+                  <entry>Name to get the owner of</entry>
                 </row>
               </tbody>
             </tgroup>
@@ -2785,15 +2759,14 @@
               <row>
                 <entry>0</entry>
                 <entry>STRING</entry>
-                <entry>Return value, a base service name</entry>
+                <entry>Return value, a unique connection name</entry>
               </row>
             </tbody>
           </tgroup>
         </informaltable>
-        Returns the base service name of the primary owner of the
-        service in argument. If the requested service isn't active,
-        returns a
-        <literal>org.freedesktop.DBus.Error.ServiceHasNoOwner</literal> error.
+        Returns the unique connection name of the primary owner of the name
+        given. If the requested name doesn't have an owner, returns a
+        <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
        </para>
       </sect3>
 
@@ -2818,7 +2791,7 @@
                 <row>
                   <entry>0</entry>
                   <entry>STRING</entry>
-                  <entry>Name of the connection/service to query</entry>
+                  <entry>Name of the connection to query</entry>
                 </row>
               </tbody>
             </tgroup>
@@ -2848,31 +2821,6 @@
        </para>
       </sect3>
 
-      <sect3 id="bus-messages-out-of-memory">
-        <title><literal>org.freedesktop.DBus.Error.NoMemory</literal></title>
-        <para>
-          As a method:
-          <programlisting>
-            void NoMemory ()
-          </programlisting>
-        </para>
-        <para>
-          Sent by the message bus when it can't process a message due to an out of memory failure.
-        </para>
-      </sect3>
-
-      <sect3 id="bus-messages-service-does-not-exist">
-        <title><literal>org.freedesktop.DBus.Error.ServiceDoesNotExist</literal></title>
-        <para>
-          As a method:
-          <programlisting>
-            void ServiceDoesNotExist (in STRING error)
-          </programlisting>
-        </para>
-        <para>
-          Sent by the message bus as a reply to a client that tried to send a message to a service that doesn't exist.
-        </para>
-      </sect3>
     </sect2>
 
   </sect1>
@@ -2892,32 +2840,22 @@
       This glossary defines some of the terms used in this specification.
     </para>
 
-    <glossentry id="term-activation"><glossterm>Activation</glossterm>
+    <glossentry id="term-bus-name"><glossterm>Bus Name</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.DBus.Broadcast</literal>
-          service; the message bus will forward the broadcast message 
-          to all applications that have expressed interest in it.
+          The message bus maintains an association between names and
+          connections. (Normally, there's one connection per application.)  A
+          bus name is simply an identifier used to locate connections. For
+          example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
+          name might be used to send a message to a screensaver from Yoyodyne
+          Corporation.  An application is said to <firstterm>own</firstterm> a
+          name if the message bus has associated the application's connection
+          with the name.  Names may also have <firstterm>queued
+          owners</firstterm> (see <xref linkend="term-queued-owner"/>).
+            The bus assigns a unique name to each connection, 
+            see <xref linkend="term-unique-name"/>. Other names 
+              can be thought of as "well-known names" and are 
+              used to find applications that offer specific functionality.
         </para>
       </glossdef>
     </glossentry>
@@ -2937,9 +2875,20 @@
       <glossdef>
         <para>
           The message bus is a special application that forwards 
-          or broadcasts messages between a group of applications
+          or routes messages between a group of applications
           connected to the message bus. It also manages 
-          <firstterm>services</firstterm>.
+          <firstterm>names</firstterm> used for routing
+          messages.
+        </para>
+      </glossdef>
+    </glossentry>
+
+    <glossentry id="term-name"><glossterm>Name</glossterm>
+      <glossdef>
+        <para>
+          See <xref linkend="term-bus-name"/>. "Name" may 
+            also be used to refer to some of the other names
+            in D-BUS, such as interface names.
         </para>
       </glossdef>
     </glossentry>
@@ -2947,9 +2896,9 @@
     <glossentry id="namespace"><glossterm>Namespace</glossterm>
       <glossdef>
 	<para>
-          Used to prevent collisions when defining message and service
-	  names. The convention used is the same as Java uses for
-	  defining classes: a reversed domain name.
+          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>
       </glossdef>
     </glossentry>
@@ -2957,73 +2906,80 @@
     <glossentry id="term-object"><glossterm>Object</glossterm>
       <glossdef>
         <para>
-          Each application contains <firstterm>objects</firstterm>,
-          which have <firstterm>interfaces</firstterm> and 
-          <firstterm>methods</firstterm>. Objects are referred to 
-          by a name, called a <firstterm>path</firstterm> or 
-          <firstterm>object reference</firstterm>.
+          Each application contains <firstterm>objects</firstterm>, which have
+          <firstterm>interfaces</firstterm> and
+          <firstterm>methods</firstterm>. Objects are referred to by a name,
+          called a <firstterm>path</firstterm>.
         </para>
       </glossdef>
     </glossentry>
 
-    <glossentry id="term-path"><glossterm>Path</glossterm>
+    <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
       <glossdef>
-        <para>
-          Object references (object names) in D-BUS are 
-          organized into a filesystem-style hierarchy, so 
-          each object is named by a path. As in LDAP, 
-          there's no difference between "files" and "directories";
-          a path can refer to an object, while still having 
-          child objects below it.
+	<para>
+          An application talking directly to another application, without going
+          through a message bus. One-to-one connections may be "peer to peer" or
+          "client to server." The D-BUS protocol has no concept of client
+          vs. server after a connection has authenticated; the flow of messages
+          is symmetrical (full duplex).
         </para>
       </glossdef>
     </glossentry>
 
-    <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
+    <glossentry id="term-path"><glossterm>Path</glossterm>
       <glossdef>
-	<para>
-          An application talking directly to another application, without going through a message bus. 
+        <para>
+          Object references (object names) in D-BUS are organized into a
+          filesystem-style hierarchy, so each object is named by a path. As in
+          LDAP, there's no difference between "files" and "directories"; a path
+          can refer to an object, while still having child objects below it.
         </para>
       </glossdef>
     </glossentry>
-    <glossentry id="term-secondary-owner"><glossterm>Secondary service owner</glossterm>
+
+    <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
       <glossdef>
         <para>
-          Each service has a primary owner; messages sent to the service name 
-          go to the primary owner. However, certain services also maintain 
-          a queue of secondary owners "waiting in the wings." If 
-          the primary owner releases the service, then the first secondary 
-          owner in the queue automatically becomes the primary owner.
+          Each bus name has a primary owner; messages sent to the name go to the
+          primary owner. However, certain names also maintain a queue of
+          secondary owners "waiting in the wings." If the primary owner releases
+          the name, then the first secondary owner in the queue automatically
+          becomes the new owner of the name.
         </para>
       </glossdef>
     </glossentry>
+
     <glossentry id="term-service"><glossterm>Service</glossterm>
       <glossdef>
         <para>
-          A service is simply a named list of applications. For example, the
-          hypothetical <literal>com.yoyodyne.Screensaver</literal> service might
-          accept messages that affect a screensaver from Yoyodyne Corporation.
-          An application is said to <firstterm>own</firstterm> a service if the
-          message bus has associated the application with the service name.
-          Services may also have <firstterm>secondary owners</firstterm> (see
-          <xref linkend="term-secondary-owner"/>).
+          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".
         </para>
       </glossdef>
     </glossentry>
-    <glossentry id="term-service-name"><glossterm>Service name</glossterm>
+
+    <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
       <glossdef>
-	<para>
-          The name used when referring to a service. If the service is
-          a base service it has a unique service name, for example
-          ":1-20", and otherwise it should be namespaced.
+        <para>
+          ".service files" tell the bus about service applications that can be
+          launched (see <xref linkend="term-service"/>). Most importantly they
+          provide a mapping from bus names to services that will request those
+            names when they start up.
         </para>
       </glossdef>
     </glossentry>
-    <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
+
+    <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
       <glossdef>
         <para>
-          ".service files" tell the bus how to activate a particular service.
-          See <xref linkend="term-activation"/>
+          The special name automatically assigned to each connection by the
+          message bus. This name will never change owner, and will be unique
+          (never reused during the lifetime of the message bus).
+          It will begin with a ':' character.
         </para>
       </glossdef>
     </glossentry>