X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=fdb247d934c42e4cf45b28ac3ef054b39886eaa1;hb=89c1ecdd7cdd6c836506065a47bfb47d20bbb874;hp=208a8e91b0e9cfe4acca69f26ac8ef69ec2648d5;hpb=8de8646311537055907e21951d1f1f39e2dddfa5;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 208a8e9..fdb247d 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.21 + (not yet released) Havoc @@ -72,12 +72,35 @@ - current - commit log + 0.21 + not yet released (commit log) + 0.20 + 22 February 2013 + smcv, walters + reorganise for clarity, remove false claims about + basic types, mention /o/fd/DBus + + + 0.19 + 20 February 2012 + smcv/lp + formally define unique connection names and well-known + bus names; document best practices for interface, bus, member and + error names, and object paths; document the search path for session + and system services on Unix; document the systemd transport + + + 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 @@ -276,17 +299,68 @@ it back from the wire format is unmarshaling. - - Type Signatures + + The D-Bus protocol does not include type tags in the marshaled data; a + block of marshaled values must have a known type + signature. The type signature is made up of zero or more + single complete + types, each made up of one or more + type codes. + + + + A type code is an ASCII character representing the + type of a value. Because ASCII characters are used, the type signature + will always form a valid ASCII string. A simple string compare + determines whether two type signatures are equivalent. + + + + A single complete type is a sequence of type codes that fully describes + one type: either a basic type, or a single fully-described container type. + A single complete type is a basic type code, a variant type code, + an array with its element type, or a struct with its fields (all of which + are defined below). So the following signatures are not single complete + types: + + "aa" + + + "(ii" + + + "ii)" + + And the following signatures contain multiple complete types: + + "ii" + + + "aiai" + + + "(ii)(ii)" + + Note however that a single complete type may contain + multiple other single complete types, by containing a struct or dict + entry. + + + + Basic types + + + The simplest type codes are the basic + types, which are the types whose structure is entirely + defined by their 1-character type code. Basic types consist of + fixed types and string-like types. + - The D-Bus protocol does not include type tags in the marshaled data; a - block of marshaled values must have a known type - signature. The type signature is made up of type - codes. A type code is an ASCII character representing the - type of a value. Because ASCII characters are used, the type signature - will always form a valid ASCII string. A simple string compare - determines whether two type signatures are equivalent. + The fixed types + are basic types whose values have a fixed length, namely BYTE, + BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length + 16, 32 or 64 bits. @@ -303,10 +377,260 @@ - All basic types work like - INT32 in this example. To marshal and unmarshal - basic types, you simply read one value from the data - block corresponding to each type code in the signature. + The characteristics of the fixed types are listed in this table. + + + + + + Conventional name + ASCII type-code + Encoding + + + + + BYTE + y (121) + Unsigned 8-bit integer + + + BOOLEAN + b (98) + Boolean value: 0 is false, 1 is true, any other value + allowed by the marshalling format is invalid + + + INT16 + n (110) + Signed (two's complement) 16-bit integer + + + UINT16 + q (113) + Unsigned 16-bit integer + + + INT32 + i (105) + Signed (two's complement) 32-bit integer + + + UINT32 + u (117) + Unsigned 32-bit integer + + + INT64 + x (120) + Signed (two's complement) 64-bit integer + (mnemonic: x and t are the first characters in "sixty" not + already used for something more common) + + + UINT64 + t (116) + Unsigned 64-bit integer + + + DOUBLE + d (100) + IEEE 754 double-precision floating point + + + UNIX_FD + h (104) + Unsigned 32-bit integer representing an index into an + out-of-band array of file descriptors, transferred via some + platform-specific mechanism (mnemonic: h for handle) + + + + + + + + The string-like types + are basic types with a variable length. The value of any string-like + type is conceptually 0 or more Unicode codepoints encoded in UTF-8, + none of which may be U+0000. The UTF-8 text must be validated + strictly: in particular, it must not contain overlong sequences, + noncharacters such as U+FFFE, or codepoints above U+10FFFF. + + + + The marshalling formats for the string-like types all end with a + single zero (NUL) byte, but that byte is not considered to be part of + the text. + + + + The characteristics of the string-like types are listed in this table. + + + + + + Conventional name + ASCII type-code + Validity constraints + + + + + STRING + s (115) + No extra constraints + + + OBJECT_PATH + o (111) + Must be + a + syntactically valid object path + + + SIGNATURE + g (103) + Zero or more + single + complete types + + + + + + + + Valid Object Paths + + + An object path is a name used to refer to an object instance. + Conceptually, each participant in a D-Bus message exchange may have + any number of object instances (think of C++ or Java objects) and each + such instance will have a path. Like a filesystem, the object + instances in an application form a hierarchical tree. + + + + 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. + + + + The following rules define a valid object path. Implementations must + not send or accept messages with invalid object paths. + + + + The path may be of any length. + + + + + The path must begin with an ASCII '/' (integer 47) character, + and must consist of elements separated by slash characters. + + + + + Each element must only contain the ASCII characters + "[A-Z][a-z][0-9]_" + + + + + No element may be the empty string. + + + + + Multiple '/' characters cannot occur in sequence. + + + + + A trailing '/' character is not allowed unless the + path is the root path (a single '/' character). + + + + + + + + + Valid Signatures + + An implementation must not send or accept invalid signatures. + Valid signatures will conform to the following rules: + + + + The signature is a list of single complete types. + Arrays must have element types, and structs must + have both open and close parentheses. + + + + + Only type codes, open and close parentheses, and open and + close curly brackets are allowed in the signature. The + STRUCT type code + is not allowed in signatures, because parentheses + are used instead. Similarly, the + DICT_ENTRY type code is not allowed in + signatures, because curly brackets are used instead. + + + + + The maximum depth of container type nesting is 32 array type + codes and 32 open parentheses. This implies that the maximum + total depth of recursion is 64, for an "array of array of array + of ... struct of struct of struct of ..." where there are 32 + array and 32 struct. + + + + + The maximum length of a signature is 255. + + + + + + + When signatures appear in messages, the marshalling format + guarantees that they will be followed by a nul byte (which can + be interpreted as either C-style string termination or the INVALID + type-code), but this is not conceptually part of the signature. + + + + + + + Container types + + In addition to basic types, there are four container types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY. @@ -362,34 +686,6 @@ - The phrase single complete type deserves some - definition. A single complete type is a basic type code, a variant type code, - an array with its element type, or a struct with its fields. - So the following signatures are not single complete types: - - "aa" - - - "(ii" - - - "ii)" - - And the following signatures contain multiple complete types: - - "ii" - - - "aiai" - - - "(ii)(ii)" - - Note however that a single complete type may contain - multiple other single complete types. - - - VARIANT has ASCII character 'v' as its type code. A marshaled value of type VARIANT will have the signature of a single complete type as part of the value. This signature will be followed by a @@ -397,6 +693,14 @@ + Unlike a message signature, the variant signature can + contain only a single complete type. So "i", "ai" + or "(ii)" is OK, but "ii" is not. Use of variants may not + cause a total message depth to be larger than 64, including + other container types such as structures. + + + A DICT_ENTRY works exactly like a struct, but rather than parentheses it uses curly braces, and it has more restrictions. The restrictions are: it occurs only as an array element type; it has @@ -419,6 +723,10 @@ In most languages, an array of dict entry would be represented as a map, hash table, or dict object. + + + + Summary of types The following table summarizes the D-Bus types. @@ -550,9 +858,21 @@ + - - Marshaling (Wire Format) + + Marshaling (Wire Format) + + + D-Bus defines a marshalling format for its type system, which is + used in D-Bus messages. This is not the only possible marshalling + format for the type system: for instance, GVariant (part of GLib) + re-uses the D-Bus type system but implements an alternative marshalling + format. + + + + Byte order and alignment Given a type signature, a block of bytes can be converted into typed @@ -561,11 +881,11 @@ - A block of bytes has an associated byte order. The byte order - has to be discovered in some way; for D-Bus messages, the - byte order is part of the message header as described in - . For now, assume - that the byte order is known to be either little endian or big + A block of bytes has an associated byte order. The byte order + has to be discovered in some way; for D-Bus messages, the + byte order is part of the message header as described in + . For now, assume + that the byte order is known to be either little endian or big endian. @@ -581,6 +901,95 @@ + As an exception to natural alignment, STRUCT and + DICT_ENTRY values are always aligned to an 8-byte + boundary, regardless of the alignments of their contents. + + + + + Marshalling basic types + + + To marshal and unmarshal fixed types, you simply read one value + from the data block corresponding to each type code in the signature. + All signed integer values are encoded in two's complement, DOUBLE + values are IEEE 754 double-precision floating-point, and BOOLEAN + values are encoded in 32 bits (of which only the least significant + bit is used). + + + + The string-like types are all marshalled as a + fixed-length unsigned integer n giving the + length of the variable part, followed by n + nonzero bytes of UTF-8 text, followed by a single zero (nul) byte + which is not considered to be part of the text. The alignment + of the string-like type is the same as the alignment of + n. + + + + For the STRING and OBJECT_PATH types, n is + encoded in 4 bytes, leading to 4-byte alignment. + For the SIGNATURE type, n is encoded as a single + byte. As a result, alignment padding is never required before a + SIGNATURE. + + + + + Marshalling containers + + + Arrays are marshalled as a UINT32 + n giving the length of the array data in bytes, + followed by alignment padding to the alignment boundary of the array + element type, followed by the n bytes of the + array elements marshalled in sequence. n does not + include the padding after the length, or any padding after the + last element. + + + + For instance, if the current position in the message is a multiple + of 8 bytes and the byte-order is big-endian, an array containing only + the 64-bit integer 5 would be marshalled as: + + +00 00 00 08 8 bytes of data +00 00 00 00 padding to 8-byte boundary +00 00 00 00 00 00 00 05 first element = 5 + + + + + Arrays have a maximum length defined to be 2 to the 26th power or + 67108864. Implementations must not send or accept arrays exceeding this + length. + + + + Structs and dict entries are marshalled in the same way as their + contents, but their alignment is always to an 8-byte boundary, + even if their contents would normally be less strictly aligned. + + + + Variants are marshalled as the SIGNATURE of + the contents (which must be a single complete type), followed by a + marshalled value with the type given by that signature. The + variant has the same 1-byte alignment as the signature, which means + that alignment padding before a variant is never needed. + Use of variants may not cause a total message depth to be larger + than 64, including other container types such as structures. + + + + + Summary of D-Bus marshalling + + Given all this, the types are marshaled on the wire as follows: @@ -645,7 +1054,7 @@ OBJECT_PATH Exactly the same as STRING except the - content must be a valid object path (see below). + content must be a valid object path (see above). 4 (for the length) @@ -654,7 +1063,7 @@ SIGNATURE The same as STRING except the length is a single byte (thus signatures have a maximum length of 255) - and the content must be a valid signature (see below). + and the content must be a valid signature (see above). 1 @@ -663,14 +1072,8 @@ ARRAY A UINT32 giving the length of the array data in bytes, followed by - alignment padding to the alignment boundary of the array element type, - followed by each array element. The array length is from the - end of the alignment padding to the end of the last element, - i.e. it does not include the padding after the length, - or any padding after the last element. - Arrays have a maximum length defined to be 2 to the 26th power or - 67108864. Implementations must not send or accept arrays exceeding this - length. + alignment padding to the alignment boundary of the array element type, + followed by each array element. 4 (for the length) @@ -689,14 +1092,9 @@ VARIANT - A variant type has a marshaled - SIGNATURE followed by a marshaled - value with the type given in the signature. Unlike - a message signature, the variant signature can - contain only a single complete type. So "i", "ai" - or "(ii)" is OK, but "ii" is not. Use of variants may not - cause a total message depth to be larger than 64, including - other container types such as structures. + The marshaled SIGNATURE of a single + complete type, followed by a marshaled value with the type + given in the signature. 1 (alignment of the signature) @@ -721,112 +1119,9 @@ - - - - - Valid Object Paths - - - An object path is a name used to refer to an object instance. - Conceptually, each participant in a D-Bus message exchange may have - any number of object instances (think of C++ or Java objects) and each - such instance will have a path. Like a filesystem, the object - instances in an application form a hierarchical tree. - - - - The following rules define a valid object path. Implementations must - not send or accept messages with invalid object paths. - - - - The path may be of any length. - - - - - The path must begin with an ASCII '/' (integer 47) character, - and must consist of elements separated by slash characters. - - - - - Each element must only contain the ASCII characters - "[A-Z][a-z][0-9]_" - - - - - No element may be the empty string. - - - - - Multiple '/' characters cannot occur in sequence. - - - - - A trailing '/' character is not allowed unless the - path is the root path (a single '/' character). - - - - - - + + - - - Valid Signatures - - An implementation must not send or accept invalid signatures. - Valid signatures will conform to the following rules: - - - - The signature ends with a nul byte. - - - - - The signature is a list of single complete types. - Arrays must have element types, and structs must - have both open and close parentheses. - - - - - Only type codes and open and close parentheses are - allowed in the signature. The STRUCT type code - is not allowed in signatures, because parentheses - are used instead. - - - - - The maximum depth of container type nesting is 32 array type - codes and 32 open parentheses. This implies that the maximum - total depth of recursion is 64, for an "array of array of array - of ... struct of struct of struct of ..." where there are 32 - array and 32 struct. - - - - - The maximum length of a signature is 255. - - - - - Signatures must be nul-terminated. - - - - - - @@ -1221,21 +1516,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 @@ -1262,6 +1584,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 @@ -1276,12 +1623,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. + @@ -2067,7 +2433,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2103,7 +2469,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2145,7 +2511,7 @@ - REJECT means that the client failed to authenticate or + REJECTED means that the client failed to authenticate or there was an error in RESP. @@ -2192,7 +2558,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2246,7 +2612,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2560,7 +2926,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, an executed subprocess and a debug/testing transport using in-process pipes. Future possible transports include one that tunnels over X11 protocol. @@ -2582,7 +2948,7 @@ would be padded by Nul bytes. - Unix domain sockets are not available on windows. + Unix domain sockets are not available on Windows. Server Address Format @@ -2623,7 +2989,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. @@ -2667,6 +3033,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 @@ -2678,7 +3065,7 @@ over a network is unsecure. - Windows notes: Because of the tcp stack on windows does not provide sending + Windows notes: Because of the tcp stack on Windows does not provide sending credentials over a tcp connection, the EXTERNAL authentification mechanismus does not work. @@ -2796,6 +3183,67 @@ + + Executed Subprocesses on Unix + + This transport forks off a process and connects its standard + input and standard output with an anonymous Unix domain + socket. This socket is then used for communication by the + transport. This transport may be used to use out-of-process + forwarder programs as basis for the D-Bus protocol. + + + The forked process will inherit the standard error output and + process group from the parent process. + + + Executed subprocesses are not available on Windows. + + + Server Address Format + + Executed subprocess addresses are identified by the "unixexec:" prefix + and support the following key/value pairs: + + + + + + Name + Values + Description + + + + + path + (path) + Path of the binary to execute, either an absolute + path or a binary name that is searched for in the default + search path of the OS. This corresponds to the first + argument of execlp(). This key is mandatory. + + + argv0 + (string) + The program name to use when executing the + binary. If omitted the same value as specified for path= + will be used. This corresponds to the second argument of + execlp(). + + + argv1, argv2, ... + (string) + Arguments to pass to the binary. This corresponds + to the third and later arguments of execlp(). If a + specific argvX is not specified no further argvY for Y > X + are taken into account. + + + + + + Meta Transports @@ -2885,22 +3333,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 @@ -3030,6 +3462,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 . @@ -3364,10 +3812,13 @@ that connection is said to own the name. - The bus itself owns a special name, org.freedesktop.DBus. - This name routes messages to the bus, allowing applications to make - administrative requests. For example, applications can ask the bus - to assign a name to a connection. + The bus itself owns a special name, + org.freedesktop.DBus, with an object + located at /org/freedesktop/DBus that + implements the org.freedesktop.DBus + interface. This service allows applications to make + administrative requests of the bus itself. For example, + applications can ask the bus to assign a name to a connection. Each name may have queued owners. When an @@ -3385,57 +3836,10 @@ - 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. + 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. @@ -3869,9 +4273,102 @@ 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 @@ -3888,6 +4385,10 @@ 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 @@ -4065,6 +4566,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. + + @@ -4421,9 +4944,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. @@ -4450,7 +4989,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. @@ -5137,6 +5701,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. + @@ -5175,10 +5744,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 , + , + , + .