From daf8d6579e1ae0ea748810b63180bd5eea2ab9c4 Mon Sep 17 00:00:00 2001 From: Mark McLoughlin Date: Sun, 21 Sep 2003 18:43:20 +0000 Subject: 2003-09-21 Mark McLoughlin * 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. --- doc/TODO | 3 ++ doc/dbus-specification.sgml | 86 ++++++++++++++++++++++++++------------------- 2 files changed, 53 insertions(+), 36 deletions(-) (limited to 'doc') 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 , 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. - 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 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 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. @@ -281,51 +281,65 @@ - Name + Conventional Name + Decimal Value Type Description - path + INVALID + 0 + INVALID + Not a valid field name (error if it appears in a message) + + + PATH + 1 STRING The object to send the message to; objects are identified by a path, "/foo/bar" - ifce + INTERFACE + 2 STRING The interface to invoke a method call on, or that a signal is emitted from. e.g. "org.freedesktop.Introspectable" - mebr + MEMBER + 3 STRING The member, either the method name or signal name. e.g. "Frobate" - ernm + ERROR_NAME + 4 STRING The name of the error that occurred, for errors - rply + REPLY_SERIAL + 5 UINT32 The serial number of the message this message is a reply to. (The serial number is one of the mandatory header fields, see .) - srvc + SERVICE + 6 STRING The name of the service this message should be routed to. Only used in combination with the message bus, see . - sdrs + SENDER_SERVICE + 7 STRING 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. - 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. - 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. 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. @@ -673,9 +687,9 @@ 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. @@ -688,9 +702,9 @@ org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags, out UINT32 resultcode) - 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. @@ -1270,18 +1284,18 @@ the new owner of the service. - Messages may have a srvc field (see SERVICE field (see ). When the message bus - receives a message, if the srvc field is absent, the + receives a message, if the SERVICE 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 org.freedesktop.Peer.Ping message with no - srvc will cause the message bus itself to reply + SERVICE will cause the message bus itself to reply to the ping immediately; the message bus would never make this message visible to other applications. - If the srvc field is present, then it indicates a + If the SERVICE 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 broadcast @@ -1292,7 +1306,7 @@ Continuing the org.freedesktop.Peer.Ping example, if - the ping message were sent with a srvc name of + the ping message were sent with a SERVICE name of com.yoyodyne.Screensaver, then the ping would be forwarded, and the Yoyodyne Corporation screensaver application would be expected to reply to the ping. If -- cgit