dbus/doc TODO,1.57,1.58 dbus-specification.xml,1.16,1.17

[Havoc Pennington]

Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv14245/doc

Modified Files:
	TODO dbus-specification.xml 
Log Message:
2005-01-28  Havoc Pennington  <hp@redhat.com>

	* doc/dbus-specification.xml: update to describe 16-bit types and
	dict entries

	* dbus/dbus-marshal-basic.c (_dbus_unpack_uint16): fix broken
	assertion

	* dbus/dbus-protocol.h (DBUS_TYPE_DICT_ENTRY): add DICT_ENTRY as a
	type

	* dbus/dbus-marshal-recursive.c: implement



Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -d -r1.57 -r1.58
--- TODO	28 Jan 2005 00:08:28 -0000	1.57
+++ TODO	28 Jan 2005 05:30:53 -0000	1.58
@@ -36,14 +36,15 @@
    yourself; is it an error, or allowed? If allowed, 
    we need to have a test for it in the test suite.
 
- - array lengths should probably be returned as size_t rather than int
-   (though they are kind of a pita to pass in as size_t with the 
-    varargs, so maybe not - what does glib do with g_object_get()?)
-
  - add string array support back to append_args()
 
+ - validate dict entry number of fields
+
  - just before 1.0, try a HAVE_INT64=0 build and be sure it runs
 
+ - the spec and implementation should probably require dict keys
+   to be basic types
+
 Important for 1.0 GLib Bindings
 ===
 

Index: dbus-specification.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-specification.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- dbus-specification.xml	21 Jan 2005 03:44:10 -0000	1.16
+++ dbus-specification.xml	28 Jan 2005 05:30:53 -0000	1.17
@@ -7,8 +7,8 @@
 <article id="index">
   <articleinfo>
     <title>D-BUS Specification</title>
-    <releaseinfo>Version 0.9</releaseinfo>
-    <date>17 January 2005</date>
+    <releaseinfo>Version 0.10</releaseinfo>
+    <date>28 January 2005</date>
     <authorgroup>
       <author>
 	<firstname>Havoc</firstname>
@@ -263,6 +263,28 @@
       </para>
 
       <para>
+        A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
+        than parentheses it uses curly braces, and it has more restrictions.
+        The restrictions are: it occurs only as an array element type; and it
+        has exactly two single complete types inside the curly
+        braces. Implementations must not accept dict entries outside of arrays,
+        and must not accept dict entries with zero, one, or more than two
+        fields. A dict entry is always a key-value pair.
+      </para>
+      
+      <para>
+        The first field in the <literal>DICT_ENTRY</literal> is always the key.
+        A message is considered corrupt if the same key occurs twice in the same
+        array of <literal>DICT_ENTRY</literal>. However, for performance reasons
+        implementations are not required to reject dicts with duplicate keys.
+      </para>
+
+      <para>
+        In most languages, an array of dict entry would be represented as a 
+        map, hash table, or dict object.
+      </para>
+
+      <para>
         The following table summarizes the D-BUS types.
         <informaltable>
           <tgroup cols="3">
@@ -287,6 +309,14 @@
 		<entry>98 (ASCII 'b')</entry>
 		<entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
 	      </row><row>
+                <entry><literal>INT16</literal></entry>
+                <entry>110 (ASCII 'n')</entry>
+                <entry>16-bit signed integer</entry>
+              </row><row>
+                <entry><literal>UINT16</literal></entry>
+                <entry>113 (ASCII 'q')</entry>
+                <entry>16-bit unsigned integer</entry>
+	      </row><row>
                 <entry><literal>INT32</literal></entry>
                 <entry>105 (ASCII 'i')</entry>
                 <entry>32-bit signed integer</entry>
@@ -330,6 +360,10 @@
                 <entry><literal>VARIANT</literal></entry>
                 <entry>118 (ASCII 'v') </entry>
                 <entry>Variant type (the type of the value is part of the value itself)</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>
               </row>
             </tbody>
           </tgroup>
@@ -392,6 +426,14 @@
                 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
                 <entry>4</entry>
               </row><row>
+                <entry><literal>INT16</literal></entry>
+                <entry>16-bit signed integer in the message's byte order.</entry>
+                <entry>2</entry>
+              </row><row>
+                <entry><literal>UINT16</literal></entry>
+                <entry>16-bit unsigned integer in the message's byte order.</entry>
+                <entry>2</entry>
+              </row><row>
                 <entry><literal>INT32</literal></entry>
                 <entry>32-bit signed integer in the message's byte order.</entry>
                 <entry>4</entry>
@@ -478,6 +520,14 @@
                 <entry>
                   1 (alignment of the signature)
                 </entry>
+	      </row><row>
+                <entry><literal>DICT_ENTRY</literal></entry>
+                <entry>
+                  Identical to STRUCT.
+                </entry>
+                <entry>
+                  8
+                </entry>
 	      </row>
             </tbody>
           </tgroup>