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 --- ChangeLog | 4 + doc/dbus-specification.sgml | 460 +++++++++++++++++++++++++++----------------- 2 files changed, 284 insertions(+), 180 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1e60a09e..908229a8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2003-09-07 Havoc Pennington + + * doc/dbus-specification.sgml: more updates + 2003-09-06 Havoc Pennington * doc/dbus-specification.sgml: partial updates 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 v1.2.1