X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=cb10b58e1fbfbfb800bdfd86d093e518157fc54d;hb=6056a3d662c6a089e1d6f2938b3639e071891139;hp=4bd0cb327729b7edc8d9857057dcc5ff24670247;hpb=a09de5c004b8943456ea686e5e9d38fabade5834;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 4bd0cb3..cb10b58 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6,8 +6,8 @@
D-Bus Specification - Version 0.17 - 2011-06-01 + Version 0.19 + UNRELEASED Havoc @@ -78,6 +78,13 @@ + 0.18 + 29 July 2011 + smcv + define eavesdropping, unicast, broadcast; add eavesdrop + match keyword; promote type system to a top-level section + + 0.17 1 June 2011 smcv/davidz @@ -264,27 +271,13 @@ - - Message Protocol - - - A message consists of a - header and a body. If you - think of a message as a package, the header is the address, and the body - contains the package contents. The message delivery system uses the header - information to figure out where to send the message and how to interpret - it; the recipient interprets the body of the message. - - - - The body of the message is made up of zero or more - arguments, which are typed values, such as an - integer or a byte array. - + + Type System - Both header and body use the same type system and format for - serializing data. Each type of value has a wire format. + D-Bus has a type system, in which values of various types can be + serialized into a sequence of bytes referred to as the + wire format in a standard way. Converting a value from some other representation into the wire format is called marshaling and converting it back from the wire format is unmarshaling. @@ -789,9 +782,29 @@ + + Object paths are often namespaced by starting with a reversed + domain name and containing an interface version number, in the + same way as + interface + names and + well-known + bus names. + This makes it possible to implement more than one service, or + more than one version of a service, in the same process, + even if the services share a connection but cannot otherwise + co-operate (for instance, if they are implemented by different + plugins). + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might use the + hierarchy of object paths that start with + /com/example/MusicPlayer1 for its objects. + - Valid Signatures @@ -843,6 +856,31 @@ + + + + Message Protocol + + + A message consists of a + header and a body. If you + think of a message as a package, the header is the address, and the body + contains the package contents. The message delivery system uses the header + information to figure out where to send the message and how to interpret + it; the recipient interprets the body of the message. + + + + The body of the message is made up of zero or more + arguments, which are typed values, such as an + integer or a byte array. + + + + Both header and body use the D-Bus type + system and format for serializing data. + + Message Format @@ -1210,21 +1248,48 @@ Interface names must not exceed the maximum name length. + + + Interface names should start with the reversed DNS domain name of + the author of the interface (in lower-case), like interface names + in Java. It is conventional for the rest of the interface name + to consist of words run together, with initial capital letters + on all words ("CamelCase"). Several levels of hierarchy can be used. + It is also a good idea to include the major version of the interface + in the name, and increment it if incompatible changes are made; + this way, a single object can implement several versions of an + interface in parallel, if necessary. + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might define + interfaces called com.example.MusicPlayer1, + com.example.MusicPlayer1.Track and + com.example.MusicPlayer1.Seekable. + + + + D-Bus does not distinguish between the concepts that would be + called classes and interfaces in Java: either can be identified on + D-Bus by an interface name. + Bus names Connections have one or more bus names associated with them. - A connection has exactly one bus name that is a unique connection - name. The unique connection name remains with the connection for - its entire lifetime. + A connection has exactly one bus name that is a unique + connection name. The unique connection name remains + with the connection for its entire lifetime. A bus name is of type STRING, meaning that it must be valid UTF-8. However, there are also some additional restrictions that apply to bus names specifically: Bus names that start with a colon (':') - character are unique connection names. + character are unique connection names. Other bus names + are called well-known bus names. Bus names are composed of 1 or more elements separated by @@ -1251,6 +1316,31 @@ Note that the hyphen ('-') character is allowed in bus names but not in interface names. + + + Like interface + names, well-known bus names should start with the + reversed DNS domain name of the author of the interface (in + lower-case), and it is conventional for the rest of the well-known + bus name to consist of words run together, with initial + capital letters. As with interface names, including a version + number in well-known bus names is a good idea; it's possible to + have the well-known bus name for more than one version + simultaneously if backwards compatibility is required. + + + + If a well-known bus name implies the presence of a "main" interface, + that "main" interface is often given the same name as + the well-known bus name, and situated at the corresponding object + path. For instance, if the owner of example.com + is developing a D-Bus API for a music player, they might define + that any application that takes the well-known name + com.example.MusicPlayer1 should have an object + at the object path /com/example/MusicPlayer1 + which implements the interface + com.example.MusicPlayer1. + Member names @@ -1265,12 +1355,31 @@ Must be at least 1 byte in length. + + + It is conventional for member names on D-Bus to consist of + capitalized words with no punctuation ("camel-case"). + Method names should usually be verbs, such as + GetItems, and signal names should usually be + a description of an event, such as ItemsChanged. + Error names Error names have the same restrictions as interface names. + + + Error names have the same naming conventions as interface + names, and often contain .Error.; for instance, + the owner of example.com might define the + errors com.example.MusicPlayer.Error.FileNotFound + and com.example.MusicPlayer.Error.OutOfMemory. + The errors defined by D-Bus itself, such as + org.freedesktop.DBus.Error.Failed, follow a + similar pattern. + @@ -2549,7 +2658,7 @@ [FIXME we need to specify in detail each transport and its possible arguments] Current transports include: unix domain sockets (including - abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport + abstract namespace on linux), launchd, systemd, TCP/IP, and a debug/testing transport using in-process pipes. Future possible transports include one that tunnels over X11 protocol. @@ -2612,7 +2721,7 @@ launchd - launchd is a open-source server management system that replaces init, inetd + launchd is an open-source server management system that replaces init, inetd and cron on Apple Mac OS X versions 10.4 and above. It provides a common session bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX. @@ -2656,6 +2765,27 @@ + + systemd + + systemd is an open-source server management system that + replaces init and inetd on newer Linux systems. It supports + socket activation. The D-Bus systemd transport is used to acquire + socket activation file descriptors from systemd and use them + as D-Bus transport when the current process is spawned by + socket activation from it. + + + The systemd transport accepts only one or more Unix domain or + TCP streams sockets passed in via socket activation. + + + The systemd transport is not available on non-Linux operating systems. + + + The systemd transport defines no parameter keys. + + TCP Sockets @@ -2874,22 +3004,6 @@ - - Naming Conventions - - - D-Bus namespaces are all lowercase and correspond to reversed domain - names, as with Java. e.g. "org.freedesktop" - - - Interface, signal, method, and property names are "WindowsStyleCaps", note - that the first letter is capitalized, unlike Java. - - - Object paths are normally all lowercase with underscores used rather than - hyphens. - - UUIDs @@ -3019,6 +3133,22 @@ + It is conventional to give D-Bus properties names consisting of + capitalized words without punctuation ("CamelCase"), like + member names. + For instance, the GObject property + connection-status or the Qt property + connectionStatus could be represented on D-Bus + as ConnectionStatus. + + + Strictly speaking, D-Bus property names are not required to follow + the same naming restrictions as member names, but D-Bus property + names that would not be valid member names (in particular, + GObject-style dash-separated property names) can cause interoperability + problems and should be avoided. + + The available properties and whether they are writable can be determined by calling org.freedesktop.DBus.Introspectable.Introspect, see . @@ -3374,39 +3504,10 @@ - Messages may have a DESTINATION field (see ). If the - DESTINATION field is present, it specifies a message - recipient by name. Method calls and replies normally specify this field. - The message bus must send messages (of any type) with the - DESTINATION field set to the specified recipient, - regardless of whether the recipient has set up a match rule matching - the message. - - - - Signals normally do not specify a destination; they are sent to all - applications with message matching rules that - match the message. - - - - When the message bus receives a method call, if the - DESTINATION field is absent, the call is taken to be - a standard one-to-one message and interpreted by the message bus - itself. For example, sending an - org.freedesktop.DBus.Peer.Ping message with no - DESTINATION will cause the message bus itself to - reply to the ping immediately; the message bus will not make this - message visible to other applications. - - - - Continuing the org.freedesktop.DBus.Peer.Ping example, if - the ping message were sent with a DESTINATION 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. + Applications may send unicast messages to + a specific recipient or to the message bus itself, or + broadcast messages to all interested recipients. + See for details. @@ -3840,20 +3941,122 @@ Message Bus Message Routing + + + Messages may have a DESTINATION field (see ), resulting in a + unicast message. If the + DESTINATION field is present, it specifies a message + recipient by name. Method calls and replies normally specify this field. + The message bus must send messages (of any type) with the + DESTINATION field set to the specified recipient, + regardless of whether the recipient has set up a match rule matching + the message. + + + + When the message bus receives a signal, if the + DESTINATION field is absent, it is considered to + be a broadcast signal, and is sent to all + applications with message matching rules that + match the message. Most signal messages are broadcasts. + + + + Unicast signal messages (those with a DESTINATION + field) are not commonly used, but they are treated like any unicast + message: they are delivered to the specified receipient, + regardless of its match rules. One use for unicast signals is to + avoid a race condition in which a signal is emitted before the intended + recipient can call to + receive that signal: if the signal is sent directly to that recipient + using a unicast message, it does not need to add a match rule at all, + and there is no race condition. Another use for unicast signals, + on message buses whose security policy prevents eavesdropping, is to + send sensitive information which should only be visible to one + recipient. + + + + When the message bus receives a method call, if the + DESTINATION field is absent, the call is taken to be + a standard one-to-one message and interpreted by the message bus + itself. For example, sending an + org.freedesktop.DBus.Peer.Ping message with no + DESTINATION will cause the message bus itself to + reply to the ping immediately; the message bus will not make this + message visible to other applications. + + + + Continuing the org.freedesktop.DBus.Peer.Ping example, if + the ping message were sent with a DESTINATION 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. + + - FIXME + Message bus implementations may impose a security policy which + prevents certain messages from being sent or received. + When a message cannot be sent or received due to a security + policy, the message bus should send an error reply, unless the + original message had the NO_REPLY flag. + + + Eavesdropping + + Receiving a unicast message whose DESTINATION + indicates a different recipient is called + eavesdropping. On a message bus which acts as + a security boundary (like the standard system bus), the security + policy should usually prevent eavesdropping, since unicast messages + are normally kept private and may contain security-sensitive + information. + + + + Eavesdropping is mainly useful for debugging tools, such as + the dbus-monitor tool in the reference + implementation of D-Bus. Tools which eavesdrop on the message bus + should be careful to avoid sending a reply or error in response to + messages intended for a different client. + + + + Clients may attempt to eavesdrop by adding match rules + (see ) containing + the eavesdrop='true' match. If the message bus' + security policy does not allow eavesdropping, the match rule can + still be added, but will not have any practical effect. For + compatibility with older message bus implementations, if adding such + a match rule results in an error reply, the client may fall back to + adding the same rule with the eavesdrop match + omitted. + + + Match Rules - An important part of the message bus routing protocol is match - rules. Match rules describe what messages can be sent to a client - based on the contents of the message. When a message is routed - through the bus it is compared to clients' match rules. If any - of the rules match, the message is dispatched to the client. - If none of the rules match the message never leaves the bus. This - is an effective way to control traffic over the bus and to make sure - only relevant message need to be processed by the client. + An important part of the message bus routing protocol is match + rules. Match rules describe the messages that should be sent to a + client, based on the contents of the message. Broadcast signals + are only sent to clients which have a suitable match rule: this + avoids waking up client processes to deal with signals that are + not relevant to that client. + + + Messages that list a client as their DESTINATION + do not need to match the client's match rules, and are sent to that + client regardless. As a result, match rules are mainly used to + receive a subset of broadcast signals. + + + Match rules can also be used for eavesdropping + (see ), + if the security policy of the message bus allows it. Match rules are added using the AddMatch bus method @@ -4031,6 +4234,28 @@ + + eavesdrop + 'true', 'false' + Since D-Bus 1.5.6, match rules do not + match messages which have a DESTINATION + field unless the match rule specifically + requests this + (see ) + by specifying eavesdrop='true' + in the match rule. eavesdrop='false' + restores the default behaviour. Messages are + delivered to their DESTINATION + regardless of match rules, so this match does not + affect normal delivery of unicast messages. + If the message bus has a security policy which forbids + eavesdropping, this match may still be used without error, + but will not have any practical effect. + In older versions of D-Bus, this match was not allowed + in match rules, and all match rules behaved as if + eavesdrop='true' had been used. + + @@ -4387,9 +4612,25 @@ - [FIXME specify location of .service files, probably using - DESKTOP_DIRS etc. from basedir specification, though login session - bus is not really desktop-specific] + On Unix systems, the session bus should search for .service files + in $XDG_DATA_DIRS/dbus-1/services as defined + by the + XDG Base Directory Specification. + Implementations may also search additional locations, which + should be searched with lower priority than anything in + XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults; + for example, the reference implementation also + looks in ${datadir}/dbus-1/services as + set at compile time. + + + As described in the XDG Base Directory Specification, software + packages should install their session .service files to their + configured ${datadir}/dbus-1/services, + where ${datadir} is as defined by the GNU + coding standards. System administrators or users can arrange + for these service files to be read by setting XDG_DATA_DIRS or by + symlinking them into the default locations. @@ -4416,7 +4657,32 @@ - [FIXME specify location of system bus .service files] + On Unix systems, the system bus should default to searching + for .service files in + /usr/local/share/dbus-1/system-services, + /usr/share/dbus-1/system-services and + /lib/dbus-1/system-services, with that order + of precedence. It may also search other implementation-specific + locations, but should not vary these locations based on environment + variables. + + + The system bus is security-sensitive and is typically executed + by an init system with a clean environment. Its launch helper + process is particularly security-sensitive, and specifically + clears its own environment. + + + + + Software packages should install their system .service + files to their configured + ${datadir}/dbus-1/system-services, + where ${datadir} is as defined by the GNU + coding standards. System administrators can arrange + for these service files to be read by editing the system bus' + configuration file or by symlinking them into the default + locations. @@ -5103,6 +5369,11 @@ can be thought of as "well-known names" and are used to find applications that offer specific functionality. + + + See for details of + the syntax and naming conventions for bus names. + @@ -5141,10 +5412,14 @@ Namespace - - Used to prevent collisions when defining new interfaces or bus - names. The convention used is the same one Java uses for defining - classes: a reversed domain name. + + Used to prevent collisions when defining new interfaces, bus names + etc. The convention used is the same one Java uses for defining + classes: a reversed domain name. + See , + , + , + .