dbus/doc TODO,1.31,1.32 dbus-specification.xml,1.2,1.3

[Havoc Pennington]

Update of /cvs/dbus/dbus/doc
In directory pdx:/tmp/cvs-serv23383/doc

Modified Files:
	TODO dbus-specification.xml 
Log Message:
2003-10-20  Havoc Pennington  <hp@redhat.com>

        hmm, make check is currently not passing.
	
	* doc/dbus-specification.xml: add requirement that custom type
	names follow the same rules as interface names.

	* dbus/dbus-protocol.h: change some of the byte codes, to avoid
	duplication and allow 'c' to be 'custom'; dict is now 'm' for
	'map'

	* doc/dbus-specification.xml: update type codes to match
	dbus-protocol.h, using the ASCII byte values. Rename type NAMED to
	CUSTOM. Add type OBJECT_PATH to the spec.

2003-10-17  Havoc Pennington  <hp@redhat.com>

	* bus/driver.c (create_unique_client_name): use "." as separator
	in base service names instead of '-'

	* dbus/dbus-string.c (_dbus_string_get_byte): allow getting nul
	byte at the end of the string

	* dbus/dbus-internals.h (_DBUS_LIKELY, _DBUS_UNLIKELY): add
	optimization macros since string validation seems to be a slow
	point.
	
	* doc/dbus-specification.xml: restrict valid
	service/interface/member/error names. Add test suite code for the
	name validation.

	* dbus/dbus-string.c: limit service/interface/member/error names 
	to [0-9][A-Z][a-z]_

	* dbus/dbus-connection.c (dbus_connection_dispatch): add missing
	format arg to verbose spew

	* glib/dbus-gproxy.c (dbus_gproxy_call_no_reply): if not out of
	memory, return instead of g_error

	* test/test-service.c (path_message_func): support emitting a
	signal on request

	* dbus/dbus-bus.c (init_connections_unlocked): only fill in
	activation bus type if DBUS_BUS_ACTIVATION was set; default to
	assuming the activation bus was the session bus so that services
	started manually will still register.
	(init_connections_unlocked): fix so that in OOM situation we get
	the same semantics when retrying the function
	
	* test/test-service.c (main): change to use path registration, to
	test those codepaths; register with DBUS_BUS_ACTIVATION rather
	than DBUS_BUS_SESSION


Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -d -r1.31 -r1.32
--- TODO	16 Oct 2003 06:34:51 -0000	1.31
+++ TODO	21 Oct 2003 05:46:52 -0000	1.32
@@ -26,19 +26,10 @@
    which of these functions to include, in light of the fact that 
    GLib/Qt native stubs will probably also exist.
 
- - The message handler interface needs rethinking, perhaps handlers should be able 
-   to return an error that automatically gets turned into a message; most likely 
-   some basic spec'ing out of the GLib/Qt level stubs/skels stuff will be 
-   needed to understand the right approach.
-
  - assorted _-prefixed symbols in libdbus aren't actually used by
    libdbus, only by the message bus. These bloat up the library
    size. Not sure how to fix, really.
 
- - if you send a message to a service then block for reply, and the service exits/crashes
-   after the message bus has processed your message but before the service has replied, 
-   it would be nice if the message bus sent you an error reply.
-
  - build and install the Doxygen manual in Makefile when --enable-docs
 
  - if you send the same message to multiple connections, the serial number 
@@ -89,8 +80,6 @@
 
  - add dbus_message_has_path(), maybe has_member/interface
 
- - The OBJECT_PATH type is not documented in the spec.
-
  - re_align_field_recurse() in dbus-message.c is broken because it 
    crashes on some types of header field values. security problem.
 
@@ -99,18 +88,21 @@
    be coded to handle it restarting
 
  - modify the wire protocol to keep the args signature separate 
-   from the args themselves. Make the name of TYPE_NAMED part 
+   from the args themselves. Make the name of TYPE_CUSTOM part 
    of the type signature, rather than part of the value.
    Then you have the full typecheck in a single string.
 
- - rename TYPE_NAMED to TYPE_CUSTOM, probably a clearer name.
-
  - dbus_message_iter_init_array_iterator has "iter" and "iterator" 
    in the same function name
 
  - the GLib bindings varargs take DBUS_TYPE_WHATEVER and 
    return stuff allocated with dbus_malloc(); should this 
    be made more "G" at some expense in code duplication?
+   You also still have to use some D-BUS functions such as 
+   dbus_message_get_args() which takes a DBusError. 
+   Probably we need to either fully encapsulate and hide 
+   dbus/dbus.h, or encapsulate it slightly less e.g. no 
+   GError.
 
  - need to define bus behavior if you send a message to 
    yourself; is it an error, or allowed? If allowed, 
@@ -124,3 +116,9 @@
 
  - the varargs dbus_message_get_args() needs to support OBJECT_PATH 
    and OBJECT_PATH_ARRAY
+
+ - recursive dispatch, see dbus_connection_dispatch()
+
+ - the auth protocol may as well use hex encoding instead of 
+   base64, then we can dump the base64 implementation and 
+   save some bloat.

Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- dbus-specification.xml	14 Oct 2003 22:16:03 -0000	1.2
+++ dbus-specification.xml	21 Oct 2003 05:46:52 -0000	1.3
@@ -300,7 +300,7 @@
               <row>
                 <entry>PATH</entry>
 		<entry>1</entry>
-                <entry>STRING</entry>
+                <entry>OBJECT_PATH</entry>
                 <entry>The object to send the message to; objects are identified by 
                 a path, "/foo/bar"</entry>
               </row>
@@ -388,56 +388,60 @@
             <tbody>
               <row>
                 <entry>INVALID</entry>
-                <entry>0</entry>
+                <entry>0 (ASCII NUL)</entry>
                 <entry>Not a valid type code (error if it appears in a message)</entry>
               </row><row>
                 <entry>NIL</entry>
-                <entry>1</entry>
-                <entry>Marks an "unset" or "nonexistent" argument</entry>
+                <entry>118 (ASCII 'v') </entry>
+                <entry>Marks a "void"/"unset"/"nonexistent"/"null" argument</entry>
               </row><row>
 		<entry>BYTE</entry>
-		<entry>2</entry>
+		<entry>121 (ASCII 'y')</entry>
 		<entry>8-bit unsigned integer</entry>
               </row><row>
 		<entry>BOOLEAN</entry>
-		<entry>3</entry>
+		<entry>98 (ASCII 'b')</entry>
 		<entry>Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid.</entry>
 	      </row><row>
                 <entry>INT32</entry>
-                <entry>4</entry>
+                <entry>105 (ASCII 'i')</entry>
                 <entry>32-bit signed integer</entry>
               </row><row>
                 <entry>UINT32</entry>
-                <entry>5</entry>
+                <entry>117 (ASCII 'u')</entry>
                 <entry>32-bit unsigned integer</entry>
 	      </row><row>
                 <entry>INT64</entry>
-                <entry>6</entry>
+                <entry>120 (ASCII 'x')</entry>
                 <entry>64-bit signed integer</entry>
               </row><row>
                 <entry>UINT64</entry>
-                <entry>7</entry>
+                <entry>116 (ASCII 't')</entry>
                 <entry>64-bit unsigned integer</entry>
               </row><row>
                 <entry>DOUBLE</entry>
-                <entry>8</entry>
+                <entry>100 (ASCII 'd')</entry>
                 <entry>IEEE 754 double</entry>
               </row><row>
                 <entry>STRING</entry>
-                <entry>9</entry>
+                <entry>115 (ASCII 's')</entry>
                 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be zero terminated. </entry>
               </row><row>
-		<entry>NAMED</entry>
-		<entry>10</entry>
+		<entry>CUSTOM</entry>
+		<entry>99 (ASCII 'c')</entry>
 		<entry>A named byte array, used for custom types</entry>
 	      </row><row>
                 <entry>ARRAY</entry>
-                <entry>11</entry>
+                <entry>97 (ASCII 'a')</entry>
                 <entry>Array</entry>
               </row><row>
                 <entry>DICT</entry>
-                <entry>12</entry>
+                <entry>109 (ASCII 'm')</entry>
                 <entry>A dictionary of key/value pairs</entry>
+              </row><row>
+                <entry>OBJECT_PATH</entry>
+                <entry>111 (ASCII 'o')</entry>
+                <entry>Name of an object</entry>
               </row>
             </tbody>
           </tgroup>
@@ -490,10 +494,12 @@
                   byte.
                 </entry>
               </row><row>
-                <entry>NAMED</entry>
+                <entry>CUSTOM</entry>
                 <entry>A string (encoded as the STRING type above) giving the
                   name of the type followed by an UINT32 aligned to 4-byte boundary
                   indicating the data length in bytes, followed by the data.
+                  The string has some restrictions on its content, see 
+                  <xref linkend="message-protocol-names"/>.
                 </entry>
               </row><row>
                 <entry>ARRAY</entry>
@@ -513,6 +519,10 @@
                 as a byte with typecode and how that type normally would be encoded
                 alone.
                 </entry>
+	      </row><row>
+                <entry>OBJECT_PATH</entry>
+                <entry>Encoded as if it were a STRING.
+                </entry>
 	      </row>
             </tbody>
           </tgroup>
@@ -523,41 +533,46 @@
     <sect2 id="message-protocol-names">
       <title>Valid names</title>
       <para>
-        The various header fields of type STRING have some restrictions 
-        on the string's format.
+        The various names in D-BUS messages have some restrictions.
       </para>
-      <sect3 id="message-protocol-names-service">
-        <title>Service names</title>
+      <sect3 id="message-protocol-names-interface">
+        <title>Interface names</title>
         <para>
-          Services have names with type STRING, meaning that 
+          Interfaces have names with type STRING, meaning that 
           they must be valid UTF-8. However, there are also some 
-          additional restrictions that apply to service names 
+          additional restrictions that apply to interface names 
           specifically:
           <itemizedlist>
-	    <listitem><para>They must contain at least one '.' (period) character</para></listitem>
-	    <listitem><para>They must not begin with a '.' (period) character</para></listitem>
-	    <listitem><para>They must not exceed 256 bytes in length</para></listitem>
-	    <listitem><para>They must be at least 1 byte in length</para></listitem>
+            <listitem><para>They 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]_" and must not begin with a digit.
+                </para>
+            </listitem>
+
+	    <listitem><para>They must contain at least one '.' (period)
+              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 256 bytes in length.</para></listitem>
+	    <listitem><para>They must be at least 1 byte in length.</para></listitem>
           </itemizedlist>
-          
-          As a special exception, base service names (those beginning with a colon
-          (':') character) need not contain a period.
-        </para>
-        <para>
-          FIXME really, shouldn't we ban basically everything non-alphanumeric 
-          so the name will work in all programming languages?
         </para>
       </sect3>
-      <sect3 id="message-protocol-names-interface">
-        <title>Interface names</title>
-        <para>
-          Interface names have the same restrictions as service names, 
-          but do not have the special exception for names beginning with 
-          a colon.
-        </para>
+      <sect3 id="message-protocol-names-service">
+        <title>Service names</title>
         <para>
-          FIXME really, shouldn't we ban basically everything non-alphanumeric 
-          so the name will work in all programming languages?
+          Service names have the same restrictions as interface names, with a
+          special exception for base services. A base service name's first
+          element must start with a colon (':') character. After the colon, any
+          characters in the range "[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 
+          exceptions and follow the same rules as interface names.
         </para>
       </sect3>
       <sect3 id="message-protocol-names-method">
@@ -565,24 +580,23 @@
         <para>
           Method names:
           <itemizedlist>
-	    <listitem><para>May not contain the '.' (period) character</para></listitem>
+	    <listitem><para>Must only contain the ASCII characters
+                "[A-Z][a-z][0-9]_" and may not begin with a
+                digit.</para></listitem>
+	    <listitem><para>Must not contain the '.' (period) character</para></listitem>
 	    <listitem><para>Must not exceed 256 bytes in length</para></listitem>
 	    <listitem><para>Must be at least 1 byte in length</para></listitem>
           </itemizedlist>
         </para>
-        <para>
-          FIXME really, shouldn't we ban basically everything non-alphanumeric 
-          so the name will work in all programming languages?
-        </para>
       </sect3>
       <sect3 id="message-protocol-names-path">
         <title>Path names</title>
         <para>
-          A path must begin with an ASCII '/' (slash) character. Paths may not
-          end with a slash character unless the path is the one-byte string
-          "/". Two slash characters may not appear adjacent to one another (the
-          empty string is not a valid "subdirectory"). Paths may not exceed
-          256 bytes in length.
+          A path (type OBJECT_PATH) must begin with an ASCII '/' (slash)
+          character. Paths may not end with a slash character unless the path is
+          the one-byte string "/". Two slash characters may not appear adjacent
+          to one another (the empty string is not a valid "subdirectory"). Paths
+          may not exceed 256 bytes in length.
         </para>
       </sect3>
       <sect3 id="message-protocol-names-error">
@@ -590,9 +604,12 @@
         <para>
           Error names have the same restrictions as interface names.
         </para>
+      </sect3>
+      <sect3 id="message-protocol-names-custom">
+        <title>Custom types</title>
         <para>
-          FIXME really, shouldn't we ban basically everything non-alphanumeric 
-          so the name will work in all programming languages?
+          Custom type names for values of type CUSTOM follow the same
+          restrictions as interface names.
         </para>
       </sect3>
     </sect2>