From 9c5d01f0fe1ba855c0f7518c4f27d75a609b8faa Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sat, 2 Aug 2003 03:39:35 +0000 Subject: 2003-08-01 Havoc Pennington * dbus/dbus-object-registry.c (_dbus_object_registry_handle_and_unlock): implement * dbus/dbus-message.c (dbus_message_get_type): new function * doc/dbus-specification.sgml: add "type" byte to messages --- doc/dbus-specification.sgml | 58 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 7 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 68a71cec..a53be53d 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -133,6 +133,12 @@ Endianness flag; ASCII 'l' for little-endian or ASCII 'B' for big-endian. + + 1 byte + Type of message. Unknown types MUST be ignored. + Currently-defined types are described below. + + 1 byte Bitwise OR of flags. Unknown flags @@ -148,12 +154,6 @@ version for this version of the specification is 0. - - 1 byte - A nul byte, reserved for future use. - Any value for this byte MUST be accepted. - - 4 bytes An unsigned 32-bit integer in the @@ -182,7 +182,44 @@ - Flags that can appear in the second byte of the header: + Types that can appear in the second byte of the header: + + + + + Decimal value + Description + + + + + 0 + This is an invalid type, if seen in a message + the connection should be dropped immediately. + + + 1 + Method call. + + + + 2 + Method reply with returned data. + + + 3 + Error. + + + 4 + Signal emission. + + + + + + + Flags that can appear in the third byte of the header: @@ -196,6 +233,13 @@ 0x1 This message is an error reply. If the first argument exists and is a string, it is an error message. + + 0x2 + This message does not expect method return replies or + error replies; the reply can be omitted as an + optimization. However, it is compliant with this specification + to return the reply despite this flag. + -- cgit From ff8908f1e98eda82b0a77abb449ecff36abf14aa Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sat, 2 Aug 2003 14:58:33 +0000 Subject: 2003-08-02 Havoc Pennington * dbus/dbus-message.c (dbus_message_get_no_reply) (dbus_message_set_no_reply): add these and remove set_is_error/get_is_error * dbus/dbus-protocol.h, doc/dbus-specification.sgml: remove the ERROR flag, since there's now an ERROR type --- doc/dbus-specification.sgml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index a53be53d..0dd4fbc4 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -208,7 +208,8 @@ 3 - Error. + Error reply. If the first argument exists and is a + string, it is an error message. 4 @@ -231,10 +232,6 @@ 0x1 - This message is an error reply. If the first argument exists and is a string, it is an error message. - - - 0x2 This message does not expect method return replies or error replies; the reply can be omitted as an optimization. However, it is compliant with this specification -- cgit From b29ea9115ea3277354b7ccbe442026279220f4ac Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Mon, 11 Aug 2003 02:11:58 +0000 Subject: 2003-08-10 Havoc Pennington * tools/dbus-send.c (main): add --type argument, for now supporting only method_call and signal types. * tools/dbus-print-message.c: print message type * dbus/dbus-connection.c (_dbus_connection_new_for_transport): init connection->objects * doc/dbus-specification.sgml: fix sgml * bus/*.c: port over to object-instance API changes * test/test-service.c: ditto * dbus/dbus-message.c (dbus_message_create_header): allow #NULL name, we will have to fix up the rest of the code to also handle this (dbus_message_new): generic message-creation call (set_string_field): allow appending name field --- doc/dbus-specification.sgml | 1 - 1 file changed, 1 deletion(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 0dd4fbc4..6c6f679a 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -201,7 +201,6 @@ 1 Method call. - 2 Method reply with returned data. -- cgit From fdb114e5cce2790fd3c68cfa13113c7b59b83e4e Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 31 Aug 2003 17:26:22 +0000 Subject: 2003-08-31 Havoc Pennington * fix build with --disable-tests --- doc/dbus-specification.sgml | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 6c6f679a..031bb329 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -770,6 +770,13 @@ + + Authentication state diagrams + + + WRITEME + + Authentication mechanisms -- cgit From 83e41dff82abe99e1a35e70ca0bb60672204ffcd Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sat, 6 Sep 2003 21:12:11 +0000 Subject: 2003-09-06 Havoc Pennington * doc/dbus-specification.sgml: partial updates * bus/dbus-daemon-1.1.in: fix the config file docs for the zillionth time; hopefully I edited the right file this time. * bus/config-parser.c (append_rule_from_element): support send_type, send_path, receive_type, receive_path * bus/policy.c: add message type and path to the list of things that can be "firewalled" --- doc/dbus-specification.sgml | 53 ++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 18 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 031bb329..7800165b 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -3,8 +3,8 @@
D-BUS Specification - Version 0.7 - 26 March 2003 + Version 0.8 + 06 September 2003 Havoc @@ -65,10 +65,10 @@ D-BUS is easy to use because it works in terms of messages rather than byte streams, and - does not require users to understand any complex concepts such as a - new type system or elaborate APIs. Libraries implementing D-BUS - may choose to abstract messages as "method calls" (see - ). + automatically handles a lot of the hard IPC issues. Also, the D-BUS + library is designed to be wrapped in a way that lets users use their + framework's existing object/type system, rather than learning a new + one specifically for IPC. @@ -83,11 +83,10 @@ forwards messages among them. - Things that D-BUS can be used for is for example notification of - system changes (notification of when a camera is plugged in to a - computer, or a new version of some software has been installed), - or desktop interoperablity, for example a file monitoring - service or a configuration service. + Uses of D-BUS include notification of system changes (notification of when + a camera is plugged in to a computer, or a new version of some software + has been installed), or desktop interoperablity, for example a file + monitoring service or a configuration service. @@ -279,9 +278,27 @@ - name + path STRING - The name of the message, such as org.freedesktop.Peer.Ping + The object to send the message to; objects are identified by + a path, "/foo/bar" + + + ifce + STRING + The interface to invoke a method call on, or + that a signal is emitted from. e.g. "org.freedesktop.Introspectable" + + + mebr + STRING + The member, either the method name or signal name. + e.g. "Frobate" + + + ernm + STRING + The name of the error that occurred, for errors rply @@ -298,10 +315,10 @@ . - sndr + sdrs STRING - The name of the base service that sent this message. - The message bus fills in this field; the field is + Sender service. The name of the base service that sent + this message. The message bus fills in this field; the field is only meaningful in combination with the message bus. @@ -480,9 +497,9 @@ Valid names - Messages and services have names with type STRING, meaning that + Services have names with type STRING, meaning that they must be valid UTF-8. However, there are also some - additional restrictions that apply to message and service names + additional restrictions that apply to service names specifically: They must contain at least one '.' (period) character -- cgit From b8e4216fecda267db8304494f52a0da5e6f3e0ae Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 7 Sep 2003 05:01:48 +0000 Subject: 2003-09-07 Havoc Pennington * doc/dbus-specification.sgml: more updates --- doc/dbus-specification.sgml | 460 +++++++++++++++++++++++++++----------------- 1 file changed, 280 insertions(+), 180 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 7800165b..5d2982fc 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -66,9 +66,9 @@ D-BUS is easy to use because it works in terms of messages rather than byte streams, and automatically handles a lot of the hard IPC issues. Also, the D-BUS - library is designed to be wrapped in a way that lets users use their - framework's existing object/type system, rather than learning a new - one specifically for IPC. + library is designed to be wrapped in a way that lets developers use + their framework's existing object/type system, rather than learning + a new one specifically for IPC. @@ -171,9 +171,11 @@ 4 bytes The message's serial number, an unsigned 32-bit integer in - the message's byte order. Applications MUST NOT reuse the same - serial number for different messages more often than 32-bit - unsigned integer wraparound. Zero is not a valid serial number. + the message's byte order. The serial number is a cookie used to + identify message replies; thus all outstanding unreplied-to messages + from the same connection MUST have a different serial number. + Zero is not a valid serial number, but all other numbers are + allowed. @@ -183,33 +185,39 @@ Types that can appear in the second byte of the header: - + + Conventional name Decimal value Description + INVALID 0 This is an invalid type, if seen in a message the connection should be dropped immediately. + METHOD_CALL 1 Method call. + METHOD_RETURN 2 Method reply with returned data. + ERROR 3 Error reply. If the first argument exists and is a string, it is an error message. + SIGNAL 4 Signal emission. @@ -220,15 +228,17 @@ Flags that can appear in the third byte of the header: - + + Conventional name Hex value Description + NO_REPLY_EXPECTED 0x1 This message does not expect method return replies or error replies; the reply can be omitted as an @@ -497,19 +507,228 @@ Valid names - Services 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 - specifically: - - They must contain at least one '.' (period) character - They must not begin with a '.' (period) character - They must not exceed 256 bytes in length - They must be at least 1 byte in length - - As a special exception, base service names (those beginning with a colon (':') character) - need not contain a period. + The various header fields of type STRING have some restrictions + on the string's format. + + Service names + + Services 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 + specifically: + + They must contain at least one '.' (period) character + They must not begin with a '.' (period) character + They must not exceed 256 bytes in length + They must be at least 1 byte in length + + + As a special exception, base service names (those beginning with a colon + (':') character) need not contain a period. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Interface names + + Interface names have the same restrictions as service names, + but do not have the special exception for names beginning with + a colon. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Method names + + Method names: + + May not contain the '.' (period) character + Must not exceed 256 bytes in length + Must be at least 1 byte in length + + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + Path names + + 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. + + + + Error names + + Error names have the same restrictions as interface names. + + + FIXME really, shouldn't we ban basically everything non-alphanumeric + so the name will work in all programming languages? + + + + + + Message types + + Each of the message types (METHOD_CALL, METHOD_RETURN, ERROR, and + SIGNAL) has its own expected usage conventions and header fields. + + + Method Calls, Returns, and Errors + + Some messages invoke an operation on a remote object. These are + called method call messages and have the type tag METHOD_CALL. Such + messages map naturally to methods on objects in a typical program. + + + A method call message is expected to have a 'mebr' 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 + 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 + object to invoke the method on. If the call is passing through + a message bus, the message will also have a 'srvc' 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 + indicating the serial number of the METHOD_CALL being replied to. The + reply can have one of two types; either METHOD_RETURN or ERROR. + + + If the reply has type METHOD_RETURN, the arguments to the reply message + are the return value(s) or "out parameters" of the method call. + If the reply has type ERROR, then an "exception" has been thrown, + and the call fails; no return value will be provided. It makes + no sense to send multiple replies to the same method call. + + + Even if a method call has no return values, a METHOD_RETURN + reply is expected, so the caller will know the method + was successfully processed. + + + If a METHOD_CALL message has the flag NO_REPLY_EXPECTED, + then as an optimization the application receiving the method + call may choose to omit the reply message (regardless of + whether the reply would have been METHOD_RETURN or ERROR). + However, it is also acceptable to ignore the NO_REPLY_EXPECTED + flag and reply anyway. + + + Mapping method calls to native APIs + + APIs for D-BUS may map method calls to a method call in a specific + programming language, such as C++, or may map a method call written + in an IDL to a D-BUS message. + + + In APIs of this nature, arguments to a method are often termed "in" + (which implies sent in the METHOD_CALL), or "out" (which implies + returned in the METHOD_RETURN). Some APIs such as CORBA also have + "inout" arguments, which are both sent and received, i.e. the caller + passes in a value which is modified. Mapped to D-BUS, an "inout" + argument is equivalent to an "in" argument, followed by an "out" + argument. You can't pass things "by reference" over the wire, so + "inout" is purely an illusion of the in-process API. + + + Given a method with zero or one return values, followed by zero or more + arguments, where each argument may be "in", "out", or "inout", the + caller constructs a message by appending each "in" or "inout" argument, + in order. "out" arguments are not represented in the caller's message. + + + The recipient constructs a reply by appending first the return value + if any, then each "out" or "inout" argument, in order. + "in" arguments are not represented in the reply message. + + + + + + + Signal Emission + + 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. + + + + + Notation in this document + + This document uses a simple pseudo-IDL to describe particular method + calls and signals. Here is an example of a method call: + + org.freedesktop.DBus.ActivateService (in STRING service_name, in UINT32 flags, + out UINT32 resultcode) + + This means ifce = org.freedesktop.DBus, mebr = ActivateService, + METHOD_CALL arguments are STRING and UINT32, METHOD_RETURN argument + is UINT32. Remember that the 'mebr' 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. + + + In C++ that might end up looking like this: + + unsigned int org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags); + + or equally valid, the return value could be done as an argument: + + void org::freedesktop::DBus::ActivateService (const char *service_name, + unsigned int flags, + unsigned int *resultcode); + + It's really up to the API designer how they want to make + this look. You could design an API where the namespace wasn't used + in C++, using STL or Qt, using varargs, or whatever you wanted. + + + Signals are written as follows: + + org.freedesktop.DBus.ServiceLost (STRING service_name) + + Signals don't specify "in" vs. "out" because only + a single direction is possible. + + + In this ad hoc notation, the special type name ANY means any type + other than NIL, and the special type name ANY_OR_NIL means any valid + type. + + + It isn't especially encouraged to use this lame pseudo-IDL in actual + API implementations; you might use the native notation for the + language you're using, or you might use COM or CORBA IDL, for example. + + @@ -969,161 +1188,35 @@ - - Message Conventions - - This section documents conventions that are not essential to D-BUS - functionality, but should generally be followed in order to simplify - programmer's lives. - - - Message Naming - - Messages are normally named in the form - "org.freedesktop.Peer.Ping", which has three - distinct components: - - - Namespace e.g. org.freedesktop - - - Message names have a Java-style namespace: a reversed domain - name. The components of the domain are normally lowercase. - - - - - Package or object e.g. Peer - - - The next part of the message name can be thought of as the name - of a singleton object, or as the name of a package of related - messages. More than one dot-separated component might be used - here. (Note that D-BUS does not define any idea of object - instances or object references.) The package or object name is - capitalized LikeThis. - - - - - Method or operation e.g. Ping - - - The final part of the message name is the most specific, and - should be a verb indicating an operation to be performed on the - object. The method or operation name is capitalized LikeThis. - - - - - - - A reply to a message conventionally has the same name as the message - being replied to. When following method call conventions (see ), this convention is mandatory, - because a message with multiple possible replies can't be mapped - to method call semantics without special-case code. - - - - Method Call Mapping - - Some implementations of D-BUS may present an API that translates object - method calls into D-BUS messages. This document does not specify in - detail how such an API should look or work. However, it does specify how - message-based protocols should be designed to be friendly to such an - API. - - - Remember that D-BUS does not have object references or object instances. - So when one application sends the message - org.freedesktop.Peer.Ping, it sends it to another - application, not to any kind of sub-portion of that application. - However, a convenience API used within the recipient application may - route all messages that start with - org.freedesktop.Peer to a particular object instance, - and may invoke the Ping() method on said instance in - order to handle the message. This is a convenience API based on - method calls. - - - A "method call" consists of a message and, optionally, a reply to that - message. The name of the "method" is the last component of the message, - for example, org.freedesktop.Peer.Ping would map to - the method Ping() on some object. - - - 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. An "inout" argument - is equivalent to an "in" argument, followed by an "out" argument. - - - Given a method with zero or one return values, followed by zero or more - arguments, where each argument may be "in", "out", or "inout", the - caller constructs a message by appending each "in" or "inout" argument, - in order. "out" arguments are not represented in the caller's message. - - - The recipient constructs a reply by appending first the return value - if any, then each "out" or "inout" argument, in order. - "in" arguments are not represented in the reply message. - - - 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. - - - 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 - . 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. If an - error reply has a first argument, and that argument has type STRING, - then the argument must be an error message. - - - [FIXME discuss mapping of broadcast messages + matching rules - to signals and slots] - - - - Standard Peer-to-Peer Messages - In the following message definitions, "method call notation" is presented - in addition to simply listing the message names and arguments. The special - type name ANY means any type other than NIL, and the special type name - ANY_OR_NIL means any valid type. - [FIXME the messages here are just made up to illustrate the - format for defining them] + See for details on + the notation used in this section. <literal>org.freedesktop.Peer.Ping</literal> - As a method: - void Ping () + org.freedesktop.Peer.Ping () - On receipt of the message org.freedesktop.Peer.Ping, - an application should reply with - org.freedesktop.Peer.Ping. Neither the - message nor its reply have any arguments. - [FIXME the messages here are just made up to illustrate the - format for defining them] + On receipt of the METHOD_CALL + message org.freedesktop.Peer.Ping, an application + should do nothing other than reply with a METHOD_RETURN as usual. + <literal>org.freedesktop.Props.Get</literal> - As a method: + [FIXME this is just a bogus made-up method that isn't implemented + or thought through, to save an example of table formatting for the + argument descriptions] - ANY_OR_NIL Get (in STRING property_name) + org.freedesktop.Props.Get (in STRING property_name, + out ANY_OR_NIL property_value) Message arguments: @@ -1138,37 +1231,18 @@ 0 - STRING + in STRING Name of the property to get - - - - Reply arguments: - - - - Argument - Type - Description - - - - - 0 - ANY_OR_NIL + 1 + out ANY_OR_NIL The value of the property. The type depends on the property. - - - [FIXME the messages here are just made up to illustrate the - format for defining them] - @@ -2009,6 +2083,32 @@ + + Object + + + Each application contains objects, + which have interfaces and + methods. Objects are referred to + by a name, called a path or + object reference. + + + + + Path + + + Object references (object names) in D-BUS are + organized into a filesystem-style hierarchy, so + each object is named by a path. As in LDAP, + there's no difference between "files" and "directories"; + a path can refer to an object, while still having + child objects below it. + + + + Peer-to-peer -- cgit 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/dbus-specification.sgml | 86 ++++++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 36 deletions(-) (limited to 'doc/dbus-specification.sgml') 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 From 46c072e1136ca101aefd5fdae35c457899d55bbb Mon Sep 17 00:00:00 2001 From: Mark McLoughlin Date: Thu, 25 Sep 2003 08:50:14 +0000 Subject: 2003-09-25 Mark McLoughlin * doc/dbus-specification.sgml: don't require header fields to be 4-byte aligned and specify that fields should be distinguished from padding by the fact that zero is not a valid field name. * doc/TODO: remove re-alignment item and add item to doc the OBJECT_PATH type. * dbus/dbus-message.c: (HeaderField): rename the original member to value_offset and introduce a name_offset member to keep track of where the field actually begins. (adjust_field_offsets): remove. (append_int_field), (append_uint_field), (append_string_field): don't align the start of the header field to a 4-byte boundary. (get_next_field): impl finding the next marhsalled field after a given field. (re_align_field_recurse): impl re-aligning a number of already marshalled fields. (delete_field): impl deleting a field of any type and re-aligning any following fields. (delete_int_or_uint_field), (delete_string_field): remove. (set_int_field), (set_uint_field): no need to re-check that we have the correct type for the field. (set_string_field): ditto and impl re-aligning any following fields. (decode_header_data): update to take into account that the fields aren't 4-byte aligned any more and the new way to distinguish padding from header fields. Also, don't exit when there is too much header padding. (process_test_subdir): print the directory. (_dbus_message_test): add test to make sure a following field is re-aligned correctly after field deletion. * dbus/dbus-string.[ch]: (_dbus_string_insert_bytes): rename from insert_byte and allow the insert of multiple bytes. (_dbus_string_test): test inserting multiple bytes. * dbus/dbus-marshal.c: (_dbus_marshal_set_string): add warning note to docs about having to re-align any marshalled values following the string. * dbus/dbus-message-builder.c: (append_string_field), (_dbus_message_data_load): don't align the header field. * dbus/dbus-auth.c: (process_test_subdir): print the directory. * test/break-loader.c: (randomly_add_one_byte): upd. for insert_byte change. * test/data/invalid-messages/bad-header-field-alignment.message: new test case. * test/data/valid-messages/unknown-header-field.message: shove a dict in the unknown field. --- doc/dbus-specification.sgml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index a2dd1b13..c772b3e5 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -265,11 +265,10 @@ - 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. @@ -358,10 +357,9 @@ buffer while keeping data types aligned, the total length of the header must be a multiple of 8 bytes. To achieve this, the header MUST be padded with nul bytes to align its total length on an 8-byte boundary. - The minimum number of padding bytes MUST be used. Because all possible - named fields use at least 8 bytes, implementations can distinguish - padding (which must be less than 8 bytes) from additional named fields - (which must be at least 8 bytes). + The minimum number of padding bytes MUST be used. Because zero is an + invalid field name, implementations can distinguish padding (which must be + zero initialized) from additional named fields. -- cgit