2003-09-21 Mark McLoughlin <mark@skynet.ie>

        * doc/dbus-specification.sgml: Change the header field name
        to be an enum and update the rest of the spec to reference
        the fields using the conventinal name.

        * dbus/dbus-protocol.h: update to reflect the spec.

        * doc/TODO: add item to remove the 4 byte alignment requirement.

        * dbus/dbus-message.c: Remove the code to generalise the
        header/body length and serial number header fields as named
        header fields so we can reference field names using the
        protocol values.
        (append_int_field), (append_uint_field), (append_string_field):
        Append the field name as a byte rather than four chars.
        (delete_int_or_uint_field), (delete_string_field): reflect the
        fact that the field name and typecode now occupy 4 bytes instead
        of 8.
        (decode_string_field), (decode_header_data): update to reflect
        protocol changes and move the field specific encoding from
        decode_string_field() back into decode_header_data().

        * dbus/dbus-internals.[ch]: (_dbus_header_field_to_string):
        Add utility to aid debugging.

        * dbus/dbus-message-builder.c:
        (append_string_field), (_dbus_message_data_load): Update to
        reflect protocol changes; Change the FIELD_NAME directive
        to HEADER_FIELD and allow it to take the field's conventional
        name rather than the actual value.

        * test/data/*/*.message: Update to use HEADER_FIELD instead
        of FIELD_NAME; Always align the header on an 8 byte boundary
        *before* updating the header length.

2 files changed, 53 insertions, 36 deletions

diff --git a/doc/TODO b/doc/TODO
index 5c2b149c..caa8856f 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -86,3 +86,6 @@
  - I don't want to introduce DBusObject, but refcounting and object
    data could still be factored out into an internal "base class" 
    perhaps.
+
+ - Header fields names are required to be aligned on a 4 byte boundary
+   at the moment. No alignment should be neccessary.
diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml
index 5d2982fc..a2dd1b13 100644
--- a/doc/dbus-specification.sgml
+++ b/doc/dbus-specification.sgml
@@ -257,22 +257,22 @@
         In addition to the required header information mentioned 
         in <xref linkend="message-protocol-header-encoding">, 
           the header may contain zero or more named 
-          header fields. These fields are named to allow 
-          future versions of this protocol specification to 
-          add new fields; implementations must ignore fields 
-          they do not understand. Implementations must not 
-          invent their own header fields; only changes to 
+          header fields. Future versions of this protocol
+          specification may add new fields. Implementations must
+          ignore fields they do not understand. Implementations
+          must not 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 represented as a single unsigned byte, 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.
+        Header fields MUST be aligned to a 4-byte boundary. Header field
+        names MUST consist of a single byte, possible values of which are
+        defined below. Following the name, the field MUST have a type code
+        represented as a single unsigned byte, 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>
@@ -281,51 +281,65 @@
           <tgroup cols=3>
             <thead>
               <row>
-                <entry>Name</entry>
+                <entry>Conventional Name</entry>
+		<entry>Decimal Value</entry>
                 <entry>Type</entry>
                 <entry>Description</entry>
               </row>
             </thead>
             <tbody>
               <row>
-                <entry>path</entry>
+                <entry>INVALID</entry>
+		<entry>0</entry>
+                <entry>INVALID</entry>
+                <entry>Not a valid field name (error if it appears in a message)</entry>
+              </row>
+              <row>
+                <entry>PATH</entry>
+		<entry>1</entry>
                 <entry>STRING</entry>
                 <entry>The object to send the message to; objects are identified by 
                 a path, "/foo/bar"</entry>
               </row>
               <row>
-                <entry>ifce</entry>
+                <entry>INTERFACE</entry>
+		<entry>2</entry>
                 <entry>STRING</entry>
                 <entry>The interface to invoke a method call on, or 
                 that a signal is emitted from. e.g. "org.freedesktop.Introspectable"</entry>
               </row>
               <row>
-                <entry>mebr</entry>
+                <entry>MEMBER</entry>
+		<entry>3</entry>
                 <entry>STRING</entry>
                 <entry>The member, either the method name or signal name. 
                 e.g. "Frobate"</entry>
               </row>
               <row>
-                <entry>ernm</entry>
+                <entry>ERROR_NAME</entry>
+		<entry>4</entry>
                 <entry>STRING</entry>
                 <entry>The name of the error that occurred, for errors</entry>
               </row>
               <row>
-                <entry>rply</entry>
+                <entry>REPLY_SERIAL</entry>
+		<entry>5</entry>
                 <entry>UINT32</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>SERVICE</entry>
+		<entry>6</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>sdrs</entry>
+                <entry>SENDER_SERVICE</entry>
+		<entry>7</entry>
                 <entry>STRING</entry>
                 <entry>Sender service. The name of the base service that sent
                 this message.  The message bus fills in this field; the field is
@@ -595,24 +609,24 @@
           messages map naturally to methods on objects in a typical program.
         </para>
         <para>
-          A method call message is expected to have a 'mebr' header field
+          A method call message is expected to have a MEMBER header field
           indicating the name of the method. Optionally, the message has an
-          'ifce' field giving the interface the method is a part of. In the
-          absence of an 'ifce' field, if two interfaces on the same object have
+          INTERFACE field giving the interface the method is a part of. In the
+          absence of an INTERFACE field, if two interfaces on the same object have
           a method with the same name, it is undefined which of the two methods
           will be invoked. Implementations may also choose to return an error in
           this ambiguous case. However, if a method name is unique
           implementations should not require an interface field.
         </para>
         <para>
-          Method call messages also include a 'path' field indicating the 
+          Method call messages also include a PATH field indicating the 
           object to invoke the method on. If the call is passing through 
-          a message bus, the message will also have a 'srvc' field giving 
+          a message bus, the message will also have a SERVICE field giving 
           the service to receive the message.
         </para>
         <para>
           When an application handles a method call message, it is expected to
-          return a reply. The reply is identified by a 'rply' header field
+          return a reply. The reply is identified by a REPLY_SERIAL header field
           indicating the serial number of the METHOD_CALL being replied to. The
           reply can have one of two types; either METHOD_RETURN or ERROR.
         </para>
@@ -673,9 +687,9 @@
         <para>
           Unlike method calls, signal emissions have no replies. 
           A signal emission is simply a single message of type SIGNAL.
-          It must have three header fields: 'path' giving the object 
-          the signal was emitted from, plus 'ifce' and 'mebr' giving the 
-          fully-qualified name of the signal.
+          It must have three header fields: PATH giving the object 
+          the signal was emitted from, plus INTERFACE and MEMBER giving
+          the fully-qualified name of the signal.
         </para>
       </sect3>
 
@@ -688,9 +702,9 @@
             org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags,
                                                   out UINT32 resultcode)
           </programlisting>
-          This means ifce = org.freedesktop.DBus, mebr = ActivateService, 
+          This means INTERFACE = org.freedesktop.DBus, MEMBER = ActivateService, 
           METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument
-          is UINT32. Remember that the 'mebr' field can't contain any '.' (period)
+          is UINT32. Remember that the MEMBER field can't contain any '.' (period)
           characters so it's known that the last part of the name in
           the "IDL" is the member name.
         </para>
@@ -1270,18 +1284,18 @@
         the new owner of the service.
       </para>
       <para>
-        Messages may have a <literal>srvc</literal> field (see <xref
+        Messages may have a <literal>SERVICE</literal> field (see <xref
                                                                   linkend="message-protocol-header-fields">).  When the message bus
-          receives a message, if the <literal>srvc</literal> field is absent, the
+          receives a message, if the <literal>SERVICE</literal> field is absent, the
           message is taken to be a standard peer-to-peer message and interpreted
           by the message bus itself. For example, sending
           an <literal>org.freedesktop.Peer.Ping</literal> message with no 
-          <literal>srvc</literal> will cause the message bus itself to reply 
+          <literal>SERVICE</literal> will cause the message bus itself to reply 
           to the ping immediately; the message bus would never make 
           this message visible to other applications.
       </para>
       <para>
-        If the <literal>srvc</literal> field is present, then it indicates a
+        If the <literal>SERVICE</literal> field is present, then it indicates a
         request for the message bus to route the message. In the usual case,
         messages are routed to the owner of the named service.
         Messages may also be <firstterm>broadcast</firstterm>
@@ -1292,7 +1306,7 @@
       </para>
       <para>
         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
-        the ping message were sent with a <literal>srvc</literal> name of
+        the ping message were sent with a <literal>SERVICE</literal> name of
         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
         forwarded, and the Yoyodyne Corporation screensaver application would be
         expected to reply to the ping. If