From c514c719ec52bba3ad359580c989d0944d2f6ffe Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Fri, 24 Jan 2003 05:16:42 +0000 Subject: 2003-01-24 Havoc Pennington * doc/dbus-specification.sgml: add some stuff --- doc/dbus-specification.sgml | 238 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 229 insertions(+), 9 deletions(-) (limited to 'doc/dbus-specification.sgml') diff --git a/doc/dbus-specification.sgml b/doc/dbus-specification.sgml index 38572149..632575b0 100644 --- a/doc/dbus-specification.sgml +++ b/doc/dbus-specification.sgml @@ -47,7 +47,7 @@ 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 - ). + ). @@ -109,7 +109,65 @@ in a type-dependent format. - The types are: + The type codes are as follows: + + + + + Type name + Code + Description + + + + + INVALID + 0 + Not a valid type code (error if it appears in a message) + + NIL + 1 + Marks an "unset" or "nonexistent" argument + + INT32 + 2 + 32-bit signed integer + + UINT32 + 3 + 32-bit unsigned integer + + DOUBLE + 4 + IEEE 754 double + + STRING + 5 + UTF-8 string (must be valid UTF-8) + + INT32_ARRAY + 6 + Array of INT32 + + UINT32_ARRAY + 7 + Array of UINT32 + + DOUBLE_ARRAY + 8 + Array of DOUBLE + + BYTE_ARRAY + 9 + Array of bytes + + STRING_ARRAY + 10 + Array of STRING + + + + The types are encoded as follows: @@ -138,23 +196,185 @@ - - Method Call Mapping + + Message Conventions - [document how something that looks like a method call is conventionally - represented in terms of messages, for method-call-style API bindings] + 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 is conventionally named by + appending the string :Reply. + So the reply to org.freedesktop.Peer.Ping + is org.freedesktop.Peer.Ping:Reply. + + + + 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. + + + 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. + + 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] - Ping Protocol + <literal>org.freedesktop.Peer.Ping</literal> + + As a method: + + void Ping () + + + + On receipt of the message org.freedesktop.Peer.Ping, + an application should reply with + org.freedesktop.Peer.Ping:Reply. Neither the + message nor its reply have any arguments. + [FIXME the messages here are just made up to illustrate the + format for defining them] + + + + <literal>org.freedesktop.Props.Get</literal> + + As a method: + + ANY_OR_NIL Get (in STRING property_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Name of the property to get + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ANY_OR_NIL + The value of the property. The type depends on the property. + + + + + - org.freedesktop.Peer.Ping - generates org.freedesktop.Peer.PingReply + + [FIXME the messages here are just made up to illustrate the + format for defining them] -- cgit