* configure.in: Add test/name-test/Makefile to the generated

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index b56e0fc..da9a813 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -974,7 +974,7 @@
           additional restrictions that apply to interface names 
           specifically:
           <itemizedlist>
           additional restrictions that apply to interface names 
           specifically:
           <itemizedlist>

-            <listitem><para>They are composed of 1 or more elements separated by
+            <listitem><para>Interface names are composed of 1 or more elements separated by

                 a period ('.') character. All elements must contain at least 
                 one character.
                 </para>
                 a period ('.') character. All elements must contain at least 
                 one character.
                 </para>


@@ -984,25 +984,54 @@
                 </para>
             </listitem>
 
                 </para>
             </listitem>
 

-           <listitem><para>They must contain at least one '.' (period)
+           <listitem><para>Interface names must contain at least one '.' (period)

               character (and thus at least two elements).
               </para></listitem>
 
               character (and thus at least two elements).
               </para></listitem>
 

-           <listitem><para>They must not begin with a '.' (period) character.</para></listitem>
-           <listitem><para>They must not exceed the maximum name length.</para></listitem>
+           <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
+           <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>

           </itemizedlist>
         </para>
       </sect3>
       <sect3 id="message-protocol-names-bus">
         <title>Bus names</title>
         <para>
           </itemizedlist>
         </para>
       </sect3>
       <sect3 id="message-protocol-names-bus">
         <title>Bus names</title>
         <para>

-          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. Bus names not starting with a colon have none of these 
-          exceptions and follow the same rules as interface names.
+          Connections have one or more bus names associated with them.
+          A connection has exactly one bus name that is a unique connection
+          name. The unique connection name remains with the connection for
+          its entire lifetime.
+          A bus name is of type <literal>STRING</literal>,
+          meaning that it must be valid UTF-8. However, there are also
+          some additional restrictions that apply to bus names 
+          specifically:
+          <itemizedlist>
+            <listitem><para>Bus names that start with a colon (':')
+                character are unique connection names.
+                </para>
+            </listitem>
+            <listitem><para>Bus names are composed of 1 or more elements separated by
+                a period ('.') character. All elements must contain at least 
+                one character.
+                </para>
+            </listitem>
+            <listitem><para>Each element must only contain the ASCII characters 
+                "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
+                connection name may begin with a digit, elements in
+                other bus names must not begin with a digit.
+                </para>
+            </listitem>
+
+           <listitem><para>Bus names must contain at least one '.' (period)
+              character (and thus at least two elements).
+              </para></listitem>
+
+           <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
+           <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
+          </itemizedlist>
+        </para>
+        <para>
+          Note that the hyphen ('-') character is allowed in bus names but
+          not in interface names.

         </para>
       </sect3>
       <sect3 id="message-protocol-names-member">
         </para>
       </sect3>
       <sect3 id="message-protocol-names-member">


@@ -1337,7 +1366,7 @@
 
         <itemizedlist>
          <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
 
         <itemizedlist>
          <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>

-         <listitem><para>OK</para></listitem>
+         <listitem><para>OK &lt;GUID in hex&gt;</para></listitem>

          <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
          <listitem><para>ERROR</para></listitem>
        </itemizedlist>
          <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
          <listitem><para>ERROR</para></listitem>
        </itemizedlist>


@@ -1478,6 +1507,10 @@
         The server must not accept additional commands using this protocol 
         after the OK command has been sent.
       </para>
         The server must not accept additional commands using this protocol 
         after the OK command has been sent.
       </para>

+      <para>
+        The OK command has one argument, which is the GUID of the server.
+        See <xref linkend="addresses"/> for more on server GUIDs.
+      </para>

     </sect2>
     <sect2 id="auth-command-error">
       <title>ERROR Command</title>
     </sect2>
     <sect2 id="auth-command-error">
       <title>ERROR Command</title>


@@ -1516,7 +1549,7 @@
             (MAGIC_COOKIE is a made up mechanism)
 
             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
             (MAGIC_COOKIE is a made up mechanism)
 
             C: AUTH MAGIC_COOKIE 3138363935333137393635383634

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -1528,7 +1561,7 @@
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -1538,7 +1571,7 @@
             C: FOOBAR
             S: ERROR
             C: AUTH MAGIC_COOKIE 3736343435313230333039
             C: FOOBAR
             S: ERROR
             C: AUTH MAGIC_COOKIE 3736343435313230333039

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -1550,7 +1583,7 @@
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -1566,7 +1599,7 @@
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -1582,7 +1615,7 @@
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
             C: AUTH SKEY 7ab83f32ee
             S: DATA 8799cabb2ea93e
             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f

-            S: OK
+            S: OK 1234deadbeef

             C: BEGIN
           </programlisting>
        </figure>
             C: BEGIN
           </programlisting>
        </figure>


@@ -2165,6 +2198,28 @@
       The set of optionally-escaped bytes is intended to preserve address 
       readability and convenience.
     </para>
       The set of optionally-escaped bytes is intended to preserve address 
       readability and convenience.
     </para>

+
+    <para>
+      A server may specify a key-value pair with the key <literal>guid</literal>
+      and the value a hex-encoded 16-byte sequence. This globally unique ID must
+      be created by filling the first 4 bytes with a 32-bit UNIX time since the
+      epoch, and the remaining 12 bytes with random bytes. If present, the GUID
+      may be used to distinguish one server from another. A server should use a
+      different GUID for each address it listens on. For example, if a message
+      bus daemon offers both UNIX domain socket and TCP connections, but treats
+      clients the same regardless of how they connect, those two connections are
+      equivalent post-connection but should have distinct GUIDs to distinguish
+      the kinds of connection.
+    </para>
+    
+    <para>
+      The intent of the GUID feature is to allow a client to avoid opening
+      multiple identical connections to the same server, by allowing the client
+      to check whether an address corresponds to an already-existing connection.
+      Comparing two addresses is insufficient, because addresses can be recycled
+      by distinct servers.
+    </para>
+

     <para>
       [FIXME clarify if attempting to connect to each is a requirement 
       or just a suggestion]
     <para>
       [FIXME clarify if attempting to connect to each is a requirement 
       or just a suggestion]


@@ -2174,13 +2229,37 @@
       the next one specified, and so forth. For example
       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
     </para>
       the next one specified, and so forth. For example
       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
     </para>

+
+  </sect1>
+  
+  <sect1 id="transports">
+    <title>Transports</title>

     <para>
       [FIXME we need to specify in detail each transport and its possible arguments]
     <para>
       [FIXME we need to specify in detail each transport and its possible arguments]

+    

       Current transports include: unix domain sockets (including 
       abstract namespace on linux), TCP/IP, and a debug/testing transport using 
       in-process pipes. Future possible transports include one that 
       tunnels over X11 protocol.
     </para>
       Current transports include: unix domain sockets (including 
       abstract namespace on linux), TCP/IP, and a debug/testing transport using 
       in-process pipes. Future possible transports include one that 
       tunnels over X11 protocol.
     </para>

+  
+    <sect2 id="transports-unix-domain-sockets">
+      <title>Unix Domain Sockets</title>
+      <para>
+        Unix domain sockets can be either paths in the file system or on Linux 
+       kernels, they can be abstract which are similar to paths but i
+       do not show up in the file system.  
+      </para>
+
+      <para>
+        When a socket is opened by the D-Bus library it truncates the path 
+       name right befor the first trailing Nul byte.  This is true for both
+       normal paths and abstract paths.  Note that this is a departure from
+       previous versions of D-Bus that would create sockets with a fixed 
+       length path name.  Names which were shorter than the fixed length
+       would be padded by Nul bytes.
+      </para>
+    </sect2>

   </sect1>
 
   <sect1 id="naming-conventions">
   </sect1>
 
   <sect1 id="naming-conventions">


@@ -2208,17 +2287,17 @@
       that may be useful across various D-BUS applications.
     </para>
     <sect2 id="standard-interfaces-peer">
       that may be useful across various D-BUS applications.
     </para>
     <sect2 id="standard-interfaces-peer">

-      <title><literal>org.freedesktop.Peer</literal></title>
+      <title><literal>org.freedesktop.DBus.Peer</literal></title>

       <para>
       <para>

-        The <literal>org.freedesktop.Peer</literal> interface 
+        The <literal>org.freedesktop.DBus.Peer</literal> interface 

         has one method:
         <programlisting>
         has one method:
         <programlisting>

-          org.freedesktop.Peer.Ping ()
+          org.freedesktop.DBus.Peer.Ping ()

         </programlisting>
       </para>
       <para>
         On receipt of the <literal>METHOD_CALL</literal> message
         </programlisting>
       </para>
       <para>
         On receipt of the <literal>METHOD_CALL</literal> message

-        <literal>org.freedesktop.Peer.Ping</literal>, an application should do
+        <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do

         nothing other than reply with a <literal>METHOD_RETURN</literal> as
         usual.  It does not matter which object path a ping is sent to.  The
         reference implementation should simply handle this method on behalf of
         nothing other than reply with a <literal>METHOD_RETURN</literal> as
         usual.  It does not matter which object path a ping is sent to.  The
         reference implementation should simply handle this method on behalf of


@@ -2228,11 +2307,11 @@
     </sect2>
 
     <sect2 id="standard-interfaces-introspectable">
     </sect2>
 
     <sect2 id="standard-interfaces-introspectable">

-      <title><literal>org.freedesktop.Introspectable</literal></title>
+      <title><literal>org.freedesktop.DBus.Introspectable</literal></title>

       <para>
         This interface has one method:
         <programlisting>
       <para>
         This interface has one method:
         <programlisting>

-          org.freedesktop.Introspectable.Introspect (out STRING xml_data)
+          org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)

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


@@ -2246,25 +2325,25 @@
       </para>
     </sect2>
     <sect2 id="standard-interfaces-properties">
       </para>
     </sect2>
     <sect2 id="standard-interfaces-properties">

-      <title><literal>org.freedesktop.Properties</literal></title>
+      <title><literal>org.freedesktop.DBus.Properties</literal></title>

       <para>
         Many native APIs will have a concept of object <firstterm>properties</firstterm> 
         or <firstterm>attributes</firstterm>. These can be exposed via the 
       <para>
         Many native APIs will have a concept of object <firstterm>properties</firstterm> 
         or <firstterm>attributes</firstterm>. These can be exposed via the 

-        <literal>org.freedesktop.Properties</literal> interface.
+        <literal>org.freedesktop.DBus.Properties</literal> interface.

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

-              org.freedesktop.Properties.Get (in STRING interface_name,
-                                              in STRING property_name,
-                                              out VARIANT value);
-              org.freedesktop.Properties.Set (in STRING interface_name,
-                                              in STRING property_name,
-                                              in VARIANT value);
+              org.freedesktop.DBus.Properties.Get (in STRING interface_name,
+                                                   in STRING property_name,
+                                                   out VARIANT value);
+              org.freedesktop.DBus.Properties.Set (in STRING interface_name,
+                                                   in STRING property_name,
+                                                   in VARIANT value);

         </programlisting>
       </para>
       <para>
         The available properties and whether they are writable can be determined
         </programlisting>
       </para>
       <para>
         The available properties and whether they are writable can be determined

-        by calling <literal>org.freedesktop.Introspectable.Introspect</literal>,
+        by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,

         see <xref linkend="standard-interfaces-introspectable"/>.
       </para>
       <para>
         see <xref linkend="standard-interfaces-introspectable"/>.
       </para>
       <para>


@@ -2294,13 +2373,22 @@
         &lt;node name="/org/freedesktop/sample_object"&gt;
           &lt;interface name="org.freedesktop.SampleInterface"&gt;
             &lt;method name="Frobate"&gt;
         &lt;node name="/org/freedesktop/sample_object"&gt;
           &lt;interface name="org.freedesktop.SampleInterface"&gt;
             &lt;method name="Frobate"&gt;

-              &lt;arg name="foo" type="int32" direction="in"/&gt;
-              &lt;arg name="bar" type="string" direction="out"/&gt;
+              &lt;arg name="foo" type="i" direction="in"/&gt;
+              &lt;arg name="bar" type="s" direction="out"/&gt;
+              &lt;arg name="baz" type="a{us}" direction="out"/&gt;
+              &lt;annotation name="org.freedesktop.DBus.Deprecated" value="true"/&gt;
+            &lt;/method&gt;
+            &lt;method name="Bazify"&gt;
+              &lt;arg name="bar" type="(iiu)" direction="in"/&gt;
+              &lt;arg name="bar" type="v" direction="out"/&gt;
+            &lt;/method&gt;
+            &lt;method name="Mogrify"&gt;
+              &lt;arg name="bar" type="(iiav)" direction="in"/&gt;

             &lt;/method&gt;
             &lt;signal name="Changed"&gt;
             &lt;/method&gt;
             &lt;signal name="Changed"&gt;

-              &lt;arg name="new_value" type="boolean"/&gt;
+              &lt;arg name="new_value" type="b"/&gt;

             &lt;/signal&gt;
             &lt;/signal&gt;

-            &lt;property name="Bar" type="byte" access="readwrite"/&gt;
+            &lt;property name="Bar" type="y" access="readwrite"/&gt;

           &lt;/interface&gt;
           &lt;node name="child_of_sample_object"/&gt;
           &lt;node name="another_child_of_sample_object"/&gt;
           &lt;/interface&gt;
           &lt;node name="child_of_sample_object"/&gt;
           &lt;node name="another_child_of_sample_object"/&gt;


@@ -2353,32 +2441,52 @@
         </listitem>
         <listitem>
           <para>
         </listitem>
         <listitem>
           <para>

-            The current type="uint32" stuff is totally broken,
-            instead we have to do full signatures. 
-            However, then this format will suck for human readability. 
-            So, some thinking to do here.
-          </para>
-        </listitem>
-        <listitem>
-          <para>

             Multiple interfaces can of course be listed for 
             one &lt;node&gt;.
           </para>
         </listitem>
         <listitem>
           <para>
             Multiple interfaces can of course be listed for 
             one &lt;node&gt;.
           </para>
         </listitem>
         <listitem>
           <para>

-            The method, interface, property, and signal elements may have 
-            an attribute deprecated="yes|no". If the attribute is not 
-            present, the default value for an interface is "no", and 
-            the default value for methods, properties, and signals is 
-            the deprecation status of the interface.
+            The "name" attribute on arguments is optional.

           </para>
         </listitem>
       </itemizedlist>
     </para>
           </para>
         </listitem>
       </itemizedlist>
     </para>

-
+    <para>
+        Method, interface, property, and signal elements may have
+        "annotations", which are generic key/value pairs of metadata.
+       They are similar conceptually to Java's annotations and C# attributes.
+        Well-known annotations:
+     </para>
+     <informaltable>
+       <tgroup cols="3">
+        <thead>
+          <row>
+            <entry>Name</entry>
+            <entry>Values (separated by ,)</entry>
+            <entry>Description</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>org.freedesktop.DBus.Deprecated</entry>
+            <entry>true,false</entry>
+            <entry>Whether or not the entity is deprecated; defaults to false</entry>
+          </row>
+          <row>
+            <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
+            <entry>(string)</entry>
+            <entry>The C symbol; may be used for methods and interfaces</entry>
+          </row>
+          <row>
+            <entry>org.freedesktop.DBus.Method.NoReply</entry>
+            <entry>true,false</entry>
+            <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
+          </row>
+        </tbody>
+       </tgroup>
+     </informaltable>

   </sect1>
   </sect1>

-

   <sect1 id="message-bus">
     <title>Message Bus Specification</title>
     <sect2 id="message-bus-overview">
   <sect1 id="message-bus">
     <title>Message Bus Specification</title>
     <sect2 id="message-bus-overview">


@@ -2436,14 +2544,14 @@
         <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>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>org.freedesktop.DBus.Peer.Ping</literal> message with no

         <literal>DESTINATION</literal> will cause the message bus itself to
         reply to the ping immediately; the message bus will not make this
         message visible to other applications.
       </para>
 
       <para>
         <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
+        Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if

         the ping message were sent with a <literal>DESTINATION</literal> name of
         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
         forwarded, and the Yoyodyne Corporation screensaver application would be
         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


@@ -2483,7 +2591,8 @@
         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
         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.
+        name. These names can be released again using the
+        <literal>org.freedesktop.DBus.ReleaseName</literal> message.

       </para>
 
       <sect3 id="bus-messages-request-name">
       </para>
 
       <sect3 id="bus-messages-request-name">


@@ -2540,8 +2649,79 @@
         <para>
           This method call should be sent to
           <literal>org.freedesktop.DBus</literal> and asks the message bus to
         <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:
+          assign the given name to the method caller. Each name maintains a
+          queue of possible owners, where the head of the queue is the primary
+          or current owner of the name. Each potential owner in the queue
+          maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
+          DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
+          call.  When RequestName is invoked the following occurs:
+          <itemizedlist>
+            <listitem>
+              <para>
+                If the method caller is currently the primary owner of the name,
+                the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
+                values are updated with the values from the new RequestName call, 
+                and nothing further happens.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If the current primary owner (head of the queue) has
+                DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
+                invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
+                the caller of RequestName replaces the current primary owner at
+                the head of the queue and the current primary owner moves to the
+                second position in the queue. If the caller of RequestName was 
+                in the queue previously its flags are updated with the values from 
+                the new RequestName in addition to moving it to the head of the queue.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If replacement is not possible, and the method caller is
+                currently in the queue but not the primary owner, its flags are
+                updated with the values from the new RequestName call.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If replacement is not possible, and the method caller is
+                currently not in the queue, the method caller is appended to the
+                queue.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
+                set and is not the primary owner, it is removed from the
+                queue. This can apply to the previous primary owner (if it
+                was replaced) or the method caller (if it updated the
+                DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
+                queue, or if it was just added to the queue with that flag set).
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+        <para>
+          Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
+          queue," even if another application already in the queue had specified
+          DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
+          that does not allow replacement goes away, and the next primary owner
+          does allow replacement. In this case, queued items that specified
+          DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
+          automatically replace the new primary owner. In other words,
+          DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
+          time RequestName is called. This is deliberate to avoid an infinite loop
+          anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT 
+          and DBUS_NAME_FLAG_REPLACE_EXISTING.
+        </para>
+        <para>
+          The flags argument contains any of the following values logically ORed
+          together:

 
           <informaltable>
             <tgroup cols="3">
 
           <informaltable>
             <tgroup cols="3">


@@ -2554,23 +2734,51 @@
               </thead>
               <tbody>
                <row>
               </thead>
               <tbody>
                <row>

-                 <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
+                 <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>

                  <entry>0x1</entry>
                  <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.NameLost</literal> signal.
+
+                    If an application A specifies this flag and succeeds in
+                    becoming the owner of the name, and another application B
+                    later calls RequestName with the
+                    DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
+                    will lose ownership and receive a
+                    <literal>org.freedesktop.DBus.NameLost</literal> signal, and
+                    application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+                    is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
+                    is not specified by application B, then application B will not replace
+                    application A as the owner.
+

                   </entry>
                </row>
                <row>
                  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
                  <entry>0x2</entry>
                  <entry>
                   </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
                     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.
+                    the name if there is no current owner. If this flag is set,
+                    the application will replace the current owner if
+                    the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
+
+                  </entry>
+               </row>
+               <row>
+                 <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
+                 <entry>0x4</entry>
+                 <entry>
+
+                    Without this flag, if an application requests a name that is
+                    already owned, the application will be placed in a queue to
+                    own the name when the current owner gives it up. If this
+                    flag is given, the application will not be placed in the
+                    queue, the request for the name will simply fail.  This flag
+                    also affects behavior when an application is replaced as
+                    name owner; by default the application moves back into the
+                    waiting queue, unless this flag was provided when the application
+                    became the name owner.
+

                   </entry>
                </row>
              </tbody>
                   </entry>
                </row>
              </tbody>


@@ -2594,18 +2802,27 @@
                  <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
                  <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>
+                 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
+                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>

                </row>
                <row>
                  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
                  <entry>2</entry>
                </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>
+
+                 <entry>The name already had an owner,
+                    DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
+                    the current owner did not specify
+                    DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
+                    application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
+                    </entry>

                </row>
                <row>
                </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>
+                 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
+                 <entry>The name already has an owner,
+                 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
+                 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
+                 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
+                 specified by the requesting application.</entry>

                </row>
                <row>
                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
                </row>
                <row>
                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>


@@ -2616,6 +2833,101 @@
            </tgroup>
          </informaltable>
         </para>
            </tgroup>
          </informaltable>
         </para>

+       </sect3>
+
+       <sect3 id="bus-messages-release-name">
+        <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            UINT32 ReleaseName (in STRING name)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name to release</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>UINT32</entry>
+                  <entry>Return value</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This method call should be sent to
+          <literal>org.freedesktop.DBus</literal> and asks the message bus to
+          release the method caller's claim to the given name. If the caller is
+          the primary owner, a new primary owner will be selected from the
+          queue if any other owners are waiting. If the caller is waiting in
+          the queue for the name, the caller will removed from the queue and
+          will not be made an owner of the name if it later becomes available.
+          If there are no other owners in the queue for the name, it will be
+          removed from the bus entirely.
+
+          The return code can be one of the following values:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Conventional Name</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+               <row>
+                  <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
+                  <entry>1</entry> <entry>The caller has released his claim on
+                  the given name. Either the caller was the primary owner of
+                  the name, and the name is now unused or taken by somebody
+                  waiting in the queue for the name, or the caller was waiting
+                  in the queue for the name and has now been removed from the
+                  queue.</entry>
+               </row>
+               <row>
+                 <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
+                 <entry>2</entry>
+                 <entry>The given name does not exist on this bus.</entry>
+               </row>
+               <row>
+                 <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
+                 <entry>3</entry>
+                 <entry>The caller was not the primary owner of this name,
+                  and was also not waiting in the queue to own this name.</entry>
+               </row>
+             </tbody>
+           </tgroup>
+         </informaltable>
+        </para>

       </sect3>
     </sect2>
 
       </sect3>
     </sect2>
 


@@ -2703,6 +3015,33 @@
         and if the client being activated fails to connect within that
         timeout, an error should be sent back.]
       </para>
         and if the client being activated fails to connect within that
         timeout, an error should be sent back.]
       </para>

+
+      <sect3 id="message-bus-starting-services-scope">
+        <title>Message Bus Service Scope</title>
+        <para>
+          The "scope" of a service is its "per-", such as per-session,
+          per-machine, per-home-directory, or per-display. The reference
+          implementation doesn't yet support starting services in a different
+          scope from the message bus itself. So e.g. if you start a service
+          on the session bus its scope is per-session.
+        </para>
+        <para>
+          We could add an optional scope to a bus name. For example, for
+          per-(display,session pair), we could have a unique ID for each display
+          generated automatically at login and set on screen 0 by executing a
+          special "set display ID" binary. The ID would be stored in a
+          <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
+          random bytes. This ID would then be used to scope names.
+          Starting/locating a service could be done by ID-name pair rather than
+          only by name.
+        </para>
+        <para>
+          Contrast this with a per-display scope. To achieve that, we would 
+          want a single bus spanning all sessions using a given display.
+          So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal> 
+          property on screen 0 of the display, pointing to this bus.
+        </para>
+      </sect3>

     </sect2>
 
     <sect2 id="message-bus-types">
     </sect2>
 
     <sect2 id="message-bus-types">