Remove the old, vague Naming Conventions section

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

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 63146bb..86e2b9b 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -6,8 +6,8 @@
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>
 <article id="index">
   <articleinfo>
     <title>D-Bus Specification</title>

-    <releaseinfo>Version 0.15</releaseinfo>
-    <date>3 November 2010</date>
+    <releaseinfo>Version 0.17</releaseinfo>
+    <date>(not final)</date>

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


@@ -39,6 +39,16 @@
           </address>
        </affiliation>
       </author>
           </address>
        </affiliation>
       </author>

+      <author>
+       <firstname>Sven</firstname>
+       <surname>Herzberg</surname>
+       <affiliation>
+         <orgname>Imendio AB</orgname>
+         <address>
+            <email>sven@imendio.com</email>
+          </address>
+       </affiliation>
+      </author>

     </authorgroup>
    <revhistory>
      <revision>
     </authorgroup>
    <revhistory>
      <revision>


@@ -48,6 +58,13 @@
        <revremark></revremark>
      </revision>
      <revision>
        <revremark></revremark>
      </revision>
      <revision>

+       <revnumber>0.16</revnumber>
+       <date>11 April 2011</date>
+       <authorinitials></authorinitials>
+       <revremark>add path_namespace, arg0namespace; argNpath matches object
+        paths</revremark>
+     </revision>
+     <revision>

        <revnumber>0.15</revnumber>
        <date>3 November 2010</date>
        <authorinitials></authorinitials>
        <revnumber>0.15</revnumber>
        <date>3 November 2010</date>
        <authorinitials></authorinitials>


@@ -461,7 +478,10 @@
               </row><row>
                 <entry><literal>STRUCT</literal></entry>
                 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
               </row><row>
                 <entry><literal>STRUCT</literal></entry>
                 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>

-                <entry>Struct</entry>
+                <entry>Struct; type code 114 'r' is reserved for use in
+                  bindings and implementations to represent the general
+                  concept of a struct, and must not appear in signatures
+                  used on D-Bus.</entry>

               </row><row>
                 <entry><literal>VARIANT</literal></entry>
                 <entry>118 (ASCII 'v') </entry>
               </row><row>
                 <entry><literal>VARIANT</literal></entry>
                 <entry>118 (ASCII 'v') </entry>


@@ -469,12 +489,48 @@
               </row><row>
                 <entry><literal>DICT_ENTRY</literal></entry>
                 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
               </row><row>
                 <entry><literal>DICT_ENTRY</literal></entry>
                 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>

-                <entry>Entry in a dict or map (array of key-value pairs)</entry>
+                <entry>Entry in a dict or map (array of key-value pairs).
+                  Type code 101 'e' is reserved for use in bindings and
+                  implementations to represent the general concept of a
+                  dict or dict-entry, and must not appear in signatures
+                  used on D-Bus.</entry>

               </row><row>
                 <entry><literal>UNIX_FD</literal></entry>
                 <entry>104 (ASCII 'h')</entry>
                 <entry>Unix file descriptor</entry>
               </row>
               </row><row>
                 <entry><literal>UNIX_FD</literal></entry>
                 <entry>104 (ASCII 'h')</entry>
                 <entry>Unix file descriptor</entry>
               </row>

+              <row>
+                <entry>(reserved)</entry>
+                <entry>109 (ASCII 'm')</entry>
+                <entry>Reserved for <ulink
+                    url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
+                  'maybe' type compatible with the one in GVariant</ulink>,
+                  and must not appear in signatures used on D-Bus until
+                  specified here</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>42 (ASCII '*')</entry>
+                <entry>Reserved for use in bindings/implementations to
+                  represent any <firstterm>single complete type</firstterm>,
+                  and must not appear in signatures used on D-Bus.</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>63 (ASCII '?')</entry>
+                <entry>Reserved for use in bindings/implementations to
+                  represent any <firstterm>basic type</firstterm>, and must
+                  not appear in signatures used on D-Bus.</entry>
+              </row>
+              <row>
+                <entry>(reserved)</entry>
+                <entry>64 (ASCII '@'), 38 (ASCII '&amp;'),
+                  94 (ASCII '^')</entry>
+                <entry>Reserved for internal use by bindings/implementations,
+                  and must not appear in signatures used on D-Bus.
+                  GVariant uses these type-codes to encode calling
+                  conventions.</entry>
+              </row>

             </tbody>
           </tgroup>
         </informaltable>
             </tbody>
           </tgroup>
         </informaltable>


@@ -706,9 +762,29 @@
           </itemizedlist>
         </para>
 
           </itemizedlist>
         </para>
 

+        <para>
+          Object paths are often namespaced by starting with a reversed
+          domain name and containing an interface version number, in the
+          same way as
+          <link linkend="message-protocol-names-interface">interface
+            names</link> and
+          <link linkend="message-protocol-names-bus">well-known
+            bus names</link>.
+          This makes it possible to implement more than one service, or
+          more than one version of a service, in the same process,
+          even if the services share a connection but cannot otherwise
+          co-operate (for instance, if they are implemented by different
+          plugins).
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might use the
+          hierarchy of object paths that start with
+          <literal>/com/example/MusicPlayer1</literal> for its objects.
+        </para>

       </sect3>
 
       </sect3>
 

-      

       <sect3 id="message-protocol-marshaling-signature">
         <title>Valid Signatures</title>
         <para>
       <sect3 id="message-protocol-marshaling-signature">
         <title>Valid Signatures</title>
         <para>


@@ -1127,21 +1203,48 @@
            <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
           </itemizedlist>
         </para>
            <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
           </itemizedlist>
         </para>

+
+        <para>
+          Interface names should start with the reversed DNS domain name of
+          the author of the interface (in lower-case), like interface names
+          in Java. It is conventional for the rest of the interface name
+          to consist of words run together, with initial capital letters
+          on all words ("CamelCase"). Several levels of hierarchy can be used.
+          It is also a good idea to include the major version of the interface
+          in the name, and increment it if incompatible changes are made;
+          this way, a single object can implement several versions of an
+          interface in parallel, if necessary.
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might define
+          interfaces called <literal>com.example.MusicPlayer1</literal>,
+          <literal>com.example.MusicPlayer1.Track</literal> and
+          <literal>com.example.MusicPlayer1.Seekable</literal>.
+        </para>
+
+        <para>
+          D-Bus does not distinguish between the concepts that would be
+          called classes and interfaces in Java: either can be identified on
+          D-Bus by an interface name.
+        </para>

       </sect3>
       <sect3 id="message-protocol-names-bus">
         <title>Bus names</title>
         <para>
           Connections have one or more bus names associated with them.
       </sect3>
       <sect3 id="message-protocol-names-bus">
         <title>Bus names</title>
         <para>
           Connections have one or more bus names associated with them.

-          A connection has exactly one bus name that is a unique connection
-          name. The unique connection name remains with the connection for
-          its entire lifetime.
+          A connection has exactly one bus name that is a <firstterm>unique
+            connection name</firstterm>. The unique connection name remains
+          with the connection for its entire lifetime.

           A bus name is of type <literal>STRING</literal>,
           meaning that it must be valid UTF-8. However, there are also
           some additional restrictions that apply to bus names 
           specifically:
           <itemizedlist>
             <listitem><para>Bus names that start with a colon (':')
           A bus name is of type <literal>STRING</literal>,
           meaning that it must be valid UTF-8. However, there are also
           some additional restrictions that apply to bus names 
           specifically:
           <itemizedlist>
             <listitem><para>Bus names that start with a colon (':')

-                character are unique connection names.
+                character are unique connection names. Other bus names
+                are called <firstterm>well-known bus names</firstterm>.

                 </para>
             </listitem>
             <listitem><para>Bus names are composed of 1 or more elements separated by
                 </para>
             </listitem>
             <listitem><para>Bus names are composed of 1 or more elements separated by


@@ -1168,6 +1271,31 @@
           Note that the hyphen ('-') character is allowed in bus names but
           not in interface names.
         </para>
           Note that the hyphen ('-') character is allowed in bus names but
           not in interface names.
         </para>

+
+        <para>
+          Like <link linkend="message-protocol-names-interface">interface
+            names</link>, well-known bus names should start with the
+          reversed DNS domain name of the author of the interface (in
+          lower-case), and it is conventional for the rest of the well-known
+          bus name to consist of words run together, with initial
+          capital letters. As with interface names, including a version
+          number in well-known bus names is a good idea; it's possible to
+          have the well-known bus name for more than one version
+          simultaneously if backwards compatibility is required.
+        </para>
+
+        <para>
+          If a well-known bus name implies the presence of a "main" interface,
+          that "main" interface is often given the same name as
+          the well-known bus name, and situated at the corresponding object
+          path. For instance, if the owner of <literal>example.com</literal>
+          is developing a D-Bus API for a music player, they might define
+          that any application that takes the well-known name
+          <literal>com.example.MusicPlayer1</literal> should have an object
+          at the object path <literal>/com/example/MusicPlayer1</literal>
+          which implements the interface
+          <literal>com.example.MusicPlayer1</literal>.
+        </para>

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


@@ -1182,12 +1310,31 @@
            <listitem><para>Must be at least 1 byte in length.</para></listitem>
           </itemizedlist>
         </para>
            <listitem><para>Must be at least 1 byte in length.</para></listitem>
           </itemizedlist>
         </para>

+
+        <para>
+          It is conventional for member names on D-Bus to consist of
+          capitalized words with no punctuation ("camel-case").
+          Method names should usually be verbs, such as
+          <literal>GetItems</literal>, and signal names should usually be
+          a description of an event, such as <literal>ItemsChanged</literal>.
+        </para>

       </sect3>
       <sect3 id="message-protocol-names-error">
         <title>Error names</title>
         <para>
           Error names have the same restrictions as interface names.
         </para>
       </sect3>
       <sect3 id="message-protocol-names-error">
         <title>Error names</title>
         <para>
           Error names have the same restrictions as interface names.
         </para>

+
+        <para>
+          Error names have the same naming conventions as interface
+          names, and often contain <literal>.Error.</literal>; for instance,
+          the owner of <literal>example.com</literal> might define the
+          errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
+          and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
+          The errors defined by D-Bus itself, such as
+          <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
+          similar pattern.
+        </para>

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


@@ -2791,22 +2938,6 @@
      </sect3>
     </sect2>
    </sect1>
      </sect3>
     </sect2>
    </sect1>

-   <sect1 id="naming-conventions">
-    <title>Naming Conventions</title>
-    
-    <para>
-      D-Bus namespaces are all lowercase and correspond to reversed domain
-      names, as with Java. e.g. "org.freedesktop"
-    </para>
-    <para>
-      Interface, signal, method, and property names are "WindowsStyleCaps", note
-      that the first letter is capitalized, unlike Java.
-    </para>
-    <para>
-      Object paths are normally all lowercase with underscores used rather than
-      hyphens.
-    </para>
-  </sect1>

 
   <sect1 id="uuids">
     <title>UUIDs</title>
 
   <sect1 id="uuids">
     <title>UUIDs</title>


@@ -3722,22 +3853,19 @@
                   path match is path='/org/freedesktop/Hal/Manager'</entry>
                 </row>
                 <row>
                   path match is path='/org/freedesktop/Hal/Manager'</entry>
                 </row>
                 <row>

-                  <entry><literal>path_prefix</literal></entry>
-                  <entry>An object path optionally ending in a slash</entry>
+                  <entry><literal>path_namespace</literal></entry>
+                  <entry>An object path</entry>

                   <entry>
                     <para>
                       Matches messages which are sent from or to an
                   <entry>
                     <para>
                       Matches messages which are sent from or to an

-                      object for which the object path is a descendant of
-                      the given value. If the prefix ends with a slash, it
-                      matches all paths starting with that string;
-                      if it does not end with a slash, it matches either
-                      that exact path, or that path followed by one or
+                      object for which the object path is either the
+                      given value, or that value followed by one or

                       more path components.
                     </para>
 
                     <para>
                       For example,
                       more path components.
                     </para>
 
                     <para>
                       For example,

-                      <literal>path_prefix='/com/example/foo'</literal>
+                      <literal>path_namespace='/com/example/foo'</literal>

                       would match signals sent by
                       <literal>/com/example/foo</literal>
                       or by
                       would match signals sent by
                       <literal>/com/example/foo</literal>
                       or by


@@ -3747,19 +3875,16 @@
                     </para>
 
                     <para>
                     </para>
 
                     <para>

-                      However,
-                      <literal>path_prefix='/com/example/foo/'</literal>
-                      would still match signals sent by
-                      <literal>/com/example/foo/bar</literal>,
-                      but would not match signals sent by
-                      <literal>/com/example/foo</literal> or
-                      <literal>/com/example/foobar</literal>.
+                      Using both <literal>path</literal> and
+                      <literal>path_namespace</literal> in the same match
+                      rule is not allowed.

                     </para>
                     </para>

+

                     <para>
                       <emphasis>
                     <para>
                       <emphasis>

-                        This match key was added in version 0.15 of the
+                        This match key was added in version 0.16 of the

                         D-Bus specification and implemented by the bus
                         D-Bus specification and implemented by the bus

-                        daemon in dbus 1.4.7 and later.
+                        daemon in dbus 1.5.0 and later.

                       </emphasis>
                     </para>
                 </entry>
                       </emphasis>
                     </para>
                 </entry>


@@ -3804,6 +3929,15 @@
                       argument <literal>"/ca/example/"</literal> to represent atomic modification of
                       many properties within that directory, and the interested application would be
                       notified in both cases.</para>
                       argument <literal>"/ca/example/"</literal> to represent atomic modification of
                       many properties within that directory, and the interested application would be
                       notified in both cases.</para>

+                    <para>
+                      <emphasis>
+                        This match key was added in version 0.12 of the
+                        D-Bus specification, implemented for STRING
+                        arguments by the bus daemon in dbus 1.2.0 and later,
+                        and implemented for OBJECT_PATH arguments in dbus 1.5.0
+                        and later.
+                      </emphasis>
+                    </para>

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


@@ -3820,10 +3954,6 @@
                       bus name, this can also be used for messages whose
                       first argument is an interface name.</para>
 
                       bus name, this can also be used for messages whose
                       first argument is an interface name.</para>
 

-                    <para>If the value has a trailing period, then only bus names or interface names
-                      within that namespace are matched. If it has no trailing period, an exact
-                      match is also allowed.</para>
-

                     <para>For example, the match rule
                       <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
                       matches name owner changes for bus names such as
                     <para>For example, the match rule
                       <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
                       matches name owner changes for bus names such as


@@ -3831,15 +3961,14 @@
                       <literal>com.example.backend.foo.bar</literal>, and
                       <literal>com.example.backend</literal> itself.</para>
 
                       <literal>com.example.backend.foo.bar</literal>, and
                       <literal>com.example.backend</literal> itself.</para>
 

-                    <para>On the other hand, the match rule
-                      <literal>member='NameOwnerChanged',arg0namespace='com.example.backend.'</literal>
-                      (with a trailing period in the namespace) matches owner changes for
-                      <literal>com.example.backend.foo</literal> and
-                      <literal>com.example.backend.foo.bar</literal>, but not for
-                      <literal>com.example.backend</literal>.
-                    </para>
-

                     <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
                     <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>

+                    <para>
+                      <emphasis>
+                        This match key was added in version 0.16 of the
+                        D-Bus specification and implemented by the bus
+                        daemon in dbus 1.5.0 and later.
+                      </emphasis>
+                    </para>

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


@@ -3873,9 +4002,7 @@
         <xref linkend="message-bus-types"/>.
       </para>
       <para>
         <xref linkend="message-bus-types"/>.
       </para>
       <para>

-        [FIXME the file format should be much better specified than "similar to
-        .desktop entries" esp. since desktop entries are already
-        badly-specified. ;-)] Service description files have the ".service" file
+        Service description files have the ".service" file

         extension. The message bus will only load service description files
         ending with .service; all other files will be ignored.  The file format
         is similar to that of <ulink
         extension. The message bus will only load service description files
         ending with .service; all other files will be ignored.  The file format
         is similar to that of <ulink


@@ -3884,6 +4011,18 @@
         encoding. To ensure that there will be no name collisions, service files
         must be namespaced using the same mechanism as messages and service
         names.
         encoding. To ensure that there will be no name collisions, service files
         must be namespaced using the same mechanism as messages and service
         names.

+      </para>
+
+      <para>
+        [FIXME the file format should be much better specified than "similar to
+        .desktop entries" esp. since desktop entries are already
+        badly-specified. ;-)]
+        These sections from the specification apply to service files as well:
+
+        <itemizedlist>
+          <listitem><para>General syntax</para></listitem>
+          <listitem><para>Comment format</para></listitem>
+        </itemizedlist>

 
         <figure>
          <title>Example service description file</title>
 
         <figure>
          <title>Example service description file</title>