2003-01-31 Havoc Pennington <hp@pobox.com>

	* doc/dbus-specification.sgml: work on the specification

	* dbus/dbus-message.c (_dbus_message_loader_return_buffer): check
	the protocol version of the message.

	* dbus/dbus-protocol.h: drop special _REPLY names, the spec
	no longer specifies that.
	(DBUS_SERVICE_REPLY_SERVICE_EXISTS): fix flags (1/2/4/8 not
	1/2/3/4)

	* dbus/dbus-marshal.c (_dbus_marshal_get_arg_end_pos): add missing
	"break" for DBUS_TYPE_NIL, remove @todo

7 files changed, 169 insertions, 22 deletions

diff --git a/ChangeLog b/ChangeLog
index 8fd570e5..2857feda 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,20 @@
 2003-01-31  Havoc Pennington  <hp@pobox.com>
 
+	* doc/dbus-specification.sgml: work on the specification
+
+	* dbus/dbus-message.c (_dbus_message_loader_return_buffer): check 
+	the protocol version of the message.
+
+	* dbus/dbus-protocol.h: drop special _REPLY names, the spec 
+	no longer specifies that.
+	(DBUS_SERVICE_REPLY_SERVICE_EXISTS): fix flags (1/2/4/8 not 
+	1/2/3/4)
+
+	* dbus/dbus-marshal.c (_dbus_marshal_get_arg_end_pos): add missing
+	"break" for DBUS_TYPE_NIL, remove @todo
+
+2003-01-31  Havoc Pennington  <hp@pobox.com>
+
 	* dbus/dbus-message.c (dbus_message_set_is_error_reply): rename 
 	just set_is_error/get_is_error as this is a commonly-used
 	function, and write docs.
diff --git a/Makefile.am b/Makefile.am
index c5b3c1af..7ec5e7fc 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -8,7 +8,7 @@ if HAVE_QT
    QT_SUBDIR=qt
 endif
 
-SUBDIRS=dbus $(GLIB_SUBDIR) $(QT_SUBDIR) bus test doc 
+SUBDIRS=dbus bus test doc $(GLIB_SUBDIR) $(QT_SUBDIR) 
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = dbus-1.0.pc $(GLIB_PC)
diff --git a/bus/driver.c b/bus/driver.c
index c8631ffb..ea13a9e6 100644
--- a/bus/driver.c
+++ b/bus/driver.c
@@ -221,7 +221,7 @@ bus_driver_send_welcome_message (DBusConnection *connection,
   name = bus_connection_get_name (connection);
   _dbus_assert (name != NULL);
   
-  _DBUS_HANDLE_OOM (welcome = dbus_message_new_reply (DBUS_MESSAGE_HELLO_REPLY,
+  _DBUS_HANDLE_OOM (welcome = dbus_message_new_reply (DBUS_MESSAGE_HELLO,
 						      hello_message));
   
   _DBUS_HANDLE_OOM (dbus_message_set_sender (welcome, DBUS_SERVICE_DBUS));
@@ -243,7 +243,7 @@ bus_driver_handle_list_services (DBusConnection *connection,
   int len, i;
   char **services;
 
-  _DBUS_HANDLE_OOM (reply = dbus_message_new_reply (DBUS_MESSAGE_LIST_SERVICES_REPLY, message));
+  _DBUS_HANDLE_OOM (reply = dbus_message_new_reply (DBUS_MESSAGE_LIST_SERVICES, message));
 
   _DBUS_HANDLE_OOM (services = bus_services_list (&len));
 
@@ -292,7 +292,7 @@ bus_driver_handle_own_service (DBusConnection *connection,
   _dbus_string_init_const (&service_name, name);
   service = bus_service_lookup (&service_name, TRUE);
 
-  _DBUS_HANDLE_OOM ((reply = dbus_message_new_reply (DBUS_MESSAGE_ACQUIRE_SERVICE_REPLY, message)));
+  _DBUS_HANDLE_OOM ((reply = dbus_message_new_reply (DBUS_MESSAGE_ACQUIRE_SERVICE, message)));
   
   /*
    * Check if the service already has an owner
@@ -372,7 +372,7 @@ bus_driver_handle_service_exists (DBusConnection *connection,
  _dbus_string_init_const (&service_name, name);
  service = bus_service_lookup (&service_name, FALSE);
  
- _DBUS_HANDLE_OOM ((reply = dbus_message_new_reply (DBUS_MESSAGE_ACQUIRE_SERVICE_REPLY, message)));
+ _DBUS_HANDLE_OOM ((reply = dbus_message_new_reply (DBUS_MESSAGE_ACQUIRE_SERVICE, message)));
  _DBUS_HANDLE_OOM (dbus_message_set_sender (message, DBUS_SERVICE_DBUS));
 
  _DBUS_HANDLE_OOM (dbus_message_append_fields (message,
diff --git a/dbus/dbus-marshal.c b/dbus/dbus-marshal.c
index a31e0f49..2a674987 100644
--- a/dbus/dbus-marshal.c
+++ b/dbus/dbus-marshal.c
@@ -847,8 +847,6 @@ _dbus_demarshal_string_array (const DBusString *str,
  * NO VALIDATION WHATSOEVER. The message must have been previously
  * validated.
  *
- * @todo handle DBUS_TYPE_NIL
- *
  * @param str a string
  * @param byte_order the byte order to use
  * @param pos the pos where the arg starts
@@ -877,6 +875,7 @@ _dbus_marshal_get_arg_end_pos (const DBusString *str,
 
     case DBUS_TYPE_NIL:
       *end_pos = pos + 1;
+      break;
       
     case DBUS_TYPE_INT32:
       *end_pos = _DBUS_ALIGN_VALUE (pos + 1, sizeof (dbus_int32_t)) + sizeof (dbus_int32_t);
@@ -1071,8 +1070,6 @@ validate_string (const DBusString *str,
  * returns #TRUE if a valid arg begins at "pos"
  *
  * @todo security: need to audit this function.
- *
- * @todo handle DBUS_TYPE_NIL
  * 
  * @param str a string
  * @param byte_order the byte order to use
diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c
index 7875d90e..66c6bd59 100644
--- a/dbus/dbus-message.c
+++ b/dbus/dbus-message.c
@@ -2037,6 +2037,14 @@ _dbus_message_loader_return_buffer (DBusMessageLoader  *loader,
       _dbus_string_get_const_data_len (&loader->data, &header_data, 0, 16);
 
       _dbus_assert (_DBUS_ALIGN_ADDRESS (header_data, 4) == header_data);
+
+      if (header_data[2] != DBUS_MAJOR_PROTOCOL_VERSION)
+        {
+          _dbus_verbose ("Message has protocol version %d ours is %d\n",
+                         (int) header_data[2], DBUS_MAJOR_PROTOCOL_VERSION);
+          loader->corrupted = TRUE;
+          return;
+        }
       
       byte_order = header_data[0];
 
diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h
index 5ff6d580..f1d66ac4 100644
--- a/dbus/dbus-protocol.h
+++ b/dbus/dbus-protocol.h
@@ -72,18 +72,14 @@ extern "C" {
 /* Service replies */
 #define DBUS_SERVICE_REPLY_PRIMARY_OWNER  0x1
 #define DBUS_SERVICE_REPLY_IN_QUEUE       0x2
-#define DBUS_SERVICE_REPLY_SERVICE_EXISTS 0x3
-#define DBUS_SERVICE_REPLY_ALREADY_OWNER  0x4
+#define DBUS_SERVICE_REPLY_SERVICE_EXISTS 0x4
+#define DBUS_SERVICE_REPLY_ALREADY_OWNER  0x8
   
 /* Messages */
 #define DBUS_MESSAGE_SERVICE_EXISTS        "org.freedesktop.DBus.ServiceExists"
-#define DBUS_MESSAGE_SERVICE_EXISTS_REPLY  "org.freedesktop.DBus.ServiceExists:Reply"
 #define DBUS_MESSAGE_HELLO                 "org.freedesktop.DBus.Hello"
-#define DBUS_MESSAGE_HELLO_REPLY           "org.freedesktop.DBus.Hello:Reply"
 #define DBUS_MESSAGE_LIST_SERVICES         "org.freedesktop.DBus.ListServices"
-#define DBUS_MESSAGE_LIST_SERVICES_REPLY   "org.freedesktop.DBus.ListServices:Reply"
 #define DBUS_MESSAGE_ACQUIRE_SERVICE       "org.freedesktop.DBus.OwnService"
-#define DBUS_MESSAGE_ACQUIRE_SERVICE_REPLY "org.freedesktop.DBus.OwnService:Reply"
 #define DBUS_MESSAGE_SERVICE_ACQUIRED      "org.freedesktop.DBus.ServiceAcquired"
 #define DBUS_MESSAGE_SERVICE_CREATED       "org.freedesktop.DBus.ServiceCreated"
 #define DBUS_MESSAGE_SERVICE_DELETED       "org.freedesktop.DBus.ServiceDeleted"
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml
index b8d80bb8..8e862f1b 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.sgml
@@ -156,7 +156,7 @@
       </para>
       <para>
         Flags that can appear in the second byte of the header:
-        <informaltable id="message-protocol-header-flags">
+        <informaltable>
           <tgroup cols=2>
             <thead>
               <row>
@@ -188,6 +188,60 @@
           invent their own header fields; only changes to 
           this specification may introduce new header fields.
       </para>
+
+      <para>
+        Header field names MUST consist of 4 non-nul bytes.  The field name is
+        NOT nul terminated; it occupies exactly 4 bytes. Following the name, 
+        the field MUST have a type code, and then a properly-aligned value 
+        of that type. 
+        See <xref linkend="message-protocol-arguments"> for a description 
+          of how each type is encoded. If an implementation sees a header 
+          field name that it does not understand, it MUST ignore 
+          that field.
+      </para>
+
+      <para>
+        Here are the currently-defined named header fields:
+        <informaltable>
+          <tgroup cols=3>
+            <thead>
+              <row>
+                <entry>Name</entry>
+                <entry>Type</entry>
+                <entry>Description</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>name</entry>
+                <entry>STRING</entry>
+                <entry>The name of the message, such as org.freedesktop.Peer.Ping</entry>
+              </row>
+              <row>
+                <entry>rply</entry>
+                <entry>INT32</entry>
+                <entry>The serial number of the message this message is a reply
+                to. (The serial number is one of the mandatory header fields,
+                see <xref linkend="message-protocol-header-encoding">.)</entry>
+              </row>
+              <row>
+                <entry>srvc</entry>
+                <entry>STRING</entry>
+                <entry>The name of the service this message should be routed to. 
+                Only used in combination with the message bus, see 
+                <xref linkend="message-bus">.</entry>
+              </row>
+              <row>
+                <entry>sndr</entry>
+                <entry>STRING</entry>
+                <entry>The name of the service that sent this message. 
+                The message bus fills in this field; the field is 
+                only meaningful in combination with the message bus.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
       
     </sect2>
     <sect2 id="message-protocol-header-padding">
@@ -274,6 +328,68 @@
       </para>
       <para>
         The types are encoded as follows:
+        <informaltable>
+          <tgroup cols=2>
+            <thead>
+              <row>
+                <entry>Type name</entry>
+                <entry>Encoding</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>INVALID</entry>
+                <entry>Not applicable; cannot be encoded.</entry>
+              </row><row>
+                <entry>NIL</entry>
+                <entry>No data is encoded; the type code is followed immediately 
+                by the type code of the next argument.</entry>
+              </row><row>
+                <entry>INT32</entry>
+                <entry>32-bit signed integer in the message's byte order, aligned to 4-byte boundary.</entry>
+              </row><row>
+                <entry>UINT32</entry>
+                <entry>32-bit unsigned integer in the message's byte order, aligned to 4-byte boundary.</entry>
+              </row><row>
+                <entry>DOUBLE</entry>
+                <entry>64-bit IEEE 754 double in the message's byte order, aligned to 8-byte boundary.</entry>
+              </row><row>
+                <entry>STRING</entry>
+                <entry>UINT32 aligned to 4-byte boundary indicating the string's 
+                  length in bytes excluding its terminating nul, followed by 
+                  string data of the given length, followed by a terminating nul 
+                  byte.
+                </entry>
+              </row><row>
+                <entry>INT32_ARRAY</entry>
+                <entry>UINT32 giving the number of values in the array, 
+                  followed by the given number of INT32 values.
+                </entry>
+              </row><row>
+                <entry>UINT32_ARRAY</entry>
+                <entry>UINT32 giving the number of values in the array, 
+                  followed by the given number of UINT32 values.
+                </entry>
+              </row><row>
+                <entry>DOUBLE_ARRAY</entry>
+                <entry>UINT32 giving the number of values in the array, 
+                  followed by the given number of DOUBLE values aligned
+                  to 8-byte boundary.
+                </entry>
+              </row><row>
+                <entry>BYTE_ARRAY</entry>
+                <entry>UINT32 giving the number of values in the array, 
+                  followed by the given number of one-byte values.
+                </entry>
+              </row><row>
+                <entry>STRING_ARRAY</entry>
+                <entry>UINT32 giving the number of values in the array, 
+                  followed by the given number of STRING values.
+                </entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
       </para>
     </sect2>
   </sect1>
@@ -348,10 +464,11 @@
         </variablelist>
       </para>
       <para>
-        A reply to a message is conventionally named by 
-        appending the string <literal>:Reply</literal>. 
-        So the reply to <literal>org.freedesktop.Peer.Ping</literal>
-        is <literal>org.freedesktop.Peer.Ping:Reply</literal>.
+        A reply to a message conventionally has the same name as the message
+        being replied to. When following method call conventions (see <xref
+        linkend="message-conventions-method">), this convention is mandatory, 
+          because a message with multiple possible replies can't be mapped
+          to method call semantics without special-case code.
       </para>
     </sect2>
     <sect2 id="message-conventions-method">
@@ -385,7 +502,8 @@
         Arguments to a method may be considered "in" (processed by the
         recipient of the message), or "out" (returned to the sender of the
         message in the reply). "inout" arguments are both sent and received,
-        i.e. the caller passes in a value which is modified.
+        i.e. the caller passes in a value which is modified. An "inout" argument 
+        is equivalent to an "in" argument, followed by an "out" argument.
       </para>
       <para>
         Given a method with zero or one return values, followed by zero or more
@@ -398,6 +516,19 @@
         if any, then each "out" or "inout" argument, in order. 
         "in" arguments are not represented in the reply message.
       </para>
+      <para>
+        The standard reply message MUST have the same name as the message being 
+        replied to, and MUST set the "rply" header field to the serial 
+        number of the message being replied to.
+      </para>
+      <para>
+        If an error occurs, an error reply may be sent in place of the 
+        standard reply. Error replies can be identified by a special 
+        header flag, see <xref linkend="message-protocol-header-encoding">.
+          Error replies have a name which reflects the type of 
+          error that occurred. Error replies would generally 
+          be mapped to exceptions in a programming language.
+      </para>
     </sect2>
   </sect1>
 
@@ -422,7 +553,7 @@
       <para>
         On receipt of the message <literal>org.freedesktop.Peer.Ping</literal>,
         an application should reply with
-        <literal>org.freedesktop.Peer.Ping:Reply</literal>. Neither the 
+        <literal>org.freedesktop.Peer.Ping</literal>. Neither the 
         message nor its reply have any arguments.
       [FIXME the messages here are just made up to illustrate the 
       format for defining them]