X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=673383a99bbd1ab5d4cb4c9988aceac3c880aa44;hb=04c58b9e5fbdf3acc7565f989e5fcd11f0c23c57;hp=297eaa2222eea45c3e982a0853e6859cca5af6c6;hpb=318c55c9c0e07e0da6e5994c2abb4e23a42cfed9;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 297eaa2..673383a 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1,14 +1,13 @@ - -
D-Bus Specification - Version 0.14 - May 12, 2010 + Version 0.22 + (not yet released) Havoc @@ -40,7 +39,137 @@ + + Sven + Herzberg + + Imendio AB +
+ sven@imendio.com +
+ + + + Simon + McVittie + + Collabora Ltd. +
+ simon.mcvittie@collabora.co.uk +
+ + + + David + Zeuthen + + Red Hat, Inc. +
+ davidz@redhat.com +
+ + + + + 0.22 + not yet released (commit log) + + + + + 0.21 + 2013-04-25 + smcv + allow Unicode noncharacters in UTF-8 (Unicode + Corrigendum #9) + + + 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 + define ObjectManager; reserve extra pseudo-type-codes used + by GVariant + + + 0.16 + 11 April 2011 + + add path_namespace, arg0namespace; argNpath matches object + paths + + + 0.15 + 3 November 2010 + + + + + 0.14 + 12 May 2010 + + + + + 0.13 + 23 Dezember 2009 + + + + + 0.12 + 7 November, 2006 + + + + + 0.11 + 6 February 2005 + + + + + 0.10 + 28 January 2005 + + + + + 0.9 + 7 Januar 2005 + + + + + 0.8 + 06 September 2003 + + First released document. + + @@ -165,43 +294,80 @@ - - Message Protocol + + Type System - 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. + 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. - + - 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. + 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. - Both header and body use the same type system and format for - serializing data. Each type of value has a wire format. - Converting a value from some other representation into the wire - format is called marshaling and converting - it back from the wire format is unmarshaling. + 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. - - Type Signatures + + Basic 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 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 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. @@ -218,10 +384,267 @@ - 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 + or codepoints above U+10FFFF. + + + + Since D-Bus Specification version 0.21, in accordance with Unicode + Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and + U+nFFFF are allowed in UTF-8 strings (but note that older versions of + D-Bus rejected these noncharacters). + + + + 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. @@ -277,34 +700,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 @@ -312,6 +707,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 @@ -334,6 +737,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. @@ -406,7 +813,10 @@ STRUCT 114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')') - Struct + Struct; type code 114 'r' is reserved for use in + bindings and implementations to represent the general + concept of a struct, and must not appear in signatures + used on D-Bus. VARIANT 118 (ASCII 'v') @@ -414,21 +824,69 @@ DICT_ENTRY 101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') - Entry in a dict or map (array of key-value pairs) + Entry in a dict or map (array of key-value pairs). + Type code 101 'e' is reserved for use in bindings and + implementations to represent the general concept of a + dict or dict-entry, and must not appear in signatures + used on D-Bus. UNIX_FD 104 (ASCII 'h') Unix file descriptor + + (reserved) + 109 (ASCII 'm') + Reserved for a + 'maybe' type compatible with the one in GVariant, + and must not appear in signatures used on D-Bus until + specified here + + + (reserved) + 42 (ASCII '*') + Reserved for use in bindings/implementations to + represent any single complete type, + and must not appear in signatures used on D-Bus. + + + (reserved) + 63 (ASCII '?') + Reserved for use in bindings/implementations to + represent any basic type, and must + not appear in signatures used on D-Bus. + + + (reserved) + 64 (ASCII '@'), 38 (ASCII '&'), + 94 (ASCII '^') + Reserved for internal use by bindings/implementations, + and must not appear in signatures used on D-Bus. + GVariant uses these type-codes to encode calling + conventions. + + + + + 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. + - - Marshaling (Wire Format) + + Byte order and alignment Given a type signature, a block of bytes can be converted into typed @@ -437,11 +895,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. @@ -457,6 +915,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: @@ -521,7 +1068,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) @@ -530,7 +1077,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 @@ -539,14 +1086,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) @@ -565,12 +1106,9 @@ VARIANT - A variant type has a marshaled SIGNATURE - followed by a marshaled value with the type + The marshaled SIGNATURE of a single + complete type, 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. 1 (alignment of the signature) @@ -593,116 +1131,38 @@ accompany the message. 4 - - - - - - - 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. - - - - - - + + + + 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 @@ -1070,21 +1530,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 @@ -1111,6 +1598,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 @@ -1125,12 +1637,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. + @@ -1916,7 +2447,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -1952,7 +2483,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -1994,7 +2525,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. @@ -2041,7 +2572,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2095,7 +2626,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2409,8 +2940,8 @@ [FIXME we need to specify in detail each transport and its possible arguments] Current transports include: unix domain sockets (including - abstract namespace on linux), TCP/IP, and a debug/testing transport using - in-process pipes. Future possible transports include one that + 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. @@ -2431,7 +2962,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 @@ -2469,6 +3000,74 @@ + + launchd + + 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. + + + + launchd allocates a socket and provides it with the unix path through the + DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process + spawned by launchd (or dbus-daemon, if it was started by launchd) can access + it through its environment. + Other processes can query for the launchd socket by executing: + $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET + This is normally done by the D-Bus client library so doesn't have to be done + manually. + + + launchd is not available on Microsoft Windows. + + + Server Address Format + + launchd addresses are identified by the "launchd:" prefix + and support the following key/value pairs: + + + + + + Name + Values + Description + + + + + env + (environment variable) + path of the unix domain socket for the launchd created dbus-daemon. + + + + + + + + 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 @@ -2480,7 +3079,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. @@ -2598,25 +3197,156 @@ - - - - - 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. - + + 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 - Object paths are normally all lowercase with underscores used rather than - hyphens. + Meta transports are a kind of transport with special enhancements or + behavior. Currently available meta transports include: autolaunch - + + + Autolaunch + The autolaunch transport provides a way for dbus clients to autodetect + a running dbus session bus and to autolaunch a session bus if not present. + + + Server Address Format + + Autolaunch addresses uses the "autolaunch:" prefix and support the + following key/value pairs: + + + + + + Name + Values + Description + + + + + scope + (string) + scope of autolaunch (Windows only) + + + + "*install-path" - limit session bus to dbus installation path. + The dbus installation path is determined from the location of + the shared dbus library. If the library is located in a 'bin' + subdirectory the installation root is the directory above, + otherwise the directory where the library lives is taken as + installation root. + + <install-root>/bin/[lib]dbus-1.dll + <install-root>/[lib]dbus-1.dll + + + + + + "*user" - limit session bus to the recent user. + + + + + other values - specify dedicated session bus like "release", + "debug" or other + + + + + + + + + + + + Windows implementation + + On start, the server opens a platform specific transport, creates a mutex + and a shared memory section containing the related session bus address. + This mutex will be inspected by the dbus client library to detect a + running dbus session bus. The access to the mutex and the shared memory + section are protected by global locks. + + + In the recent implementation the autolaunch transport uses a tcp transport + on localhost with a port choosen from the operating system. This detail may + change in the future. + + + Disclaimer: The recent implementation is in an early state and may not + work in all cirumstances and/or may have security issues. Because of this + the implementation is not documentated yet. + + + + UUIDs @@ -2746,6 +3476,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 . @@ -2791,6 +3537,114 @@ annotation. + + + <literal>org.freedesktop.DBus.ObjectManager</literal> + + An API can optionally make use of this interface for one or + more sub-trees of objects. The root of each sub-tree implements + this interface so other applications can get all objects, + interfaces and properties in a single method call. It is + appropriate to use this interface if users of the tree of + objects are expected to be interested in all interfaces of all + objects in the tree; a more granular API should be used if + users of the objects are expected to be interested in a small + subset of the objects, a small subset of their interfaces, or + both. + + + The method that applications can use to get all objects and + properties is GetManagedObjects: + + + + org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties); + + + + The return value of this method is a dict whose keys are + object paths. All returned object paths are children of the + object path implementing this interface, i.e. their object + paths start with the ObjectManager's object path plus '/'. + + + Each value is a dict whose keys are interfaces names. Each + value in this inner dict is the same dict that would be + returned by the org.freedesktop.DBus.Properties.GetAll() + method for that combination of object path and interface. If + an interface has no properties, the empty dict is returned. + + + Changes are emitted using the following two signals: + + + + org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path, + DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties); + org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path, + ARRAY<STRING> interfaces); + + + + The InterfacesAdded signal is emitted when + either a new object is added or when an existing object gains + one or more interfaces. The + InterfacesRemoved signal is emitted + whenever an object is removed or it loses one or more + interfaces. The second parameter of the + InterfacesAdded signal contains a dict with + the interfaces and properties (if any) that have been added to + the given object path. Similarly, the second parameter of the + InterfacesRemoved signal contains an array + of the interfaces that were removed. Note that changes on + properties on existing interfaces are not reported using this + interface - an application should also monitor the existing PropertiesChanged + signal on each object. + + + Applications SHOULD NOT export objects that are children of an + object (directly or otherwise) implementing this interface but + which are not returned in the reply from the + GetManagedObjects() method of this + interface on the given object. + + + The intent of the ObjectManager interface + is to make it easy to write a robust client + implementation. The trivial client implementation only needs + to make two method calls: + + + + org.freedesktop.DBus.AddMatch (bus_proxy, + "type='signal',name='org.example.App',path_namespace='/org/example/App'"); + objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy); + + + + on the message bus and the remote application's + ObjectManager, respectively. Whenever a new + remote object is created (or an existing object gains a new + interface), the InterfacesAdded signal is + emitted, and since this signal contains all properties for the + interfaces, no calls to the + org.freedesktop.Properties interface on the + remote object are needed. Additionally, since the initial + AddMatch() rule already includes signal + messages from the newly created child object, no new + AddMatch() call is needed. + + + + + The org.freedesktop.DBus.ObjectManager + interface was added in version 0.17 of the D-Bus + specification. + + + @@ -2807,8 +3661,8 @@ <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> - <node name="/org/freedesktop/sample_object"> - <interface name="org.freedesktop.SampleInterface"> + <node name="/com/example/sample_object"> + <interface name="com.example.SampleInterface"> <method name="Frobate"> <arg name="foo" type="i" direction="in"/> <arg name="bar" type="s" direction="out"/> @@ -2968,60 +3822,38 @@ unique-for-the-lifetime-of-the-bus name automatically assigned. Applications may request additional names for a connection. Additional names are usually "well-known names" such as - "org.freedesktop.TextEditor". When a name is bound to a connection, + "com.example.TextEditor". When a name is bound to a connection, 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. - - - Each name may have queued owners. When an - application requests a name for a connection and the name is already in - use, the bus will optionally add the connection to a queue waiting for - the name. If the current owner of the name disconnects or releases - the name, the next connection in the queue will become the new owner. - - - - This feature causes the right thing to happen if you start two text - editors for example; the first one may request "org.freedesktop.TextEditor", - and the second will be queued as a possible owner of that name. When - the first exits, the second will take over. - - - - 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 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. - - Signals normally do not specify a destination; they are sent to all - applications with message matching rules that - match the message. + Each name may have queued owners. When an + application requests a name for a connection and the name is already in + use, the bus will optionally add the connection to a queue waiting for + the name. If the current owner of the name disconnects or releases + the name, the next connection in the queue will become the new owner. - 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. + This feature causes the right thing to happen if you start two text + editors for example; the first one may request "com.example.TextEditor", + and the second will be queued as a possible owner of that name. When + the first exits, the second will take over. - 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. @@ -3394,25 +4226,183 @@ - + + + + <literal>org.freedesktop.DBus.ListQueuedOwners</literal> + + As a method: + + ARRAY of STRING ListQueuedOwners (in STRING name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + The well-known bus name to query, such as + com.example.cappuccino + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of STRING + The unique bus names of connections currently queued + for the name + + + + + + + This method call should be sent to + org.freedesktop.DBus and lists the connections + currently queued for a bus name (see + ). + + 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. + + - FIXME + 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. + + + + 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 @@ -3426,8 +4416,7 @@ The following table describes the keys that can be used to create - a match rule: - The following table summarizes the D-Bus types. + a match rule. @@ -3472,6 +4461,43 @@ path match is path='/org/freedesktop/Hal/Manager' + path_namespace + An object path + + + Matches messages which are sent from or to an + object for which the object path is either the + given value, or that value followed by one or + more path components. + + + + For example, + path_namespace='/com/example/foo' + would match signals sent by + /com/example/foo + or by + /com/example/foo/bar, + but not by + /com/example/foobar. + + + + Using both path and + path_namespace in the same match + rule is not allowed. + + + + + This match key was added in version 0.16 of the + D-Bus specification and implemented by the bus + daemon in dbus 1.5.0 and later. + + + + + destination A unique name (see ) Matches messages which are being sent to the given unique name. An @@ -3481,24 +4507,99 @@ arg[0, 1, 2, 3, ...] Any string Arg matches are special and are used for further restricting the - match based on the arguments in the body of a message. As of this time - only string arguments can be matched. An example of an argument match + match based on the arguments in the body of a message. Only arguments of type + STRING can be matched in this way. An example of an argument match would be arg3='Foo'. Only argument indexes from 0 to 63 should be accepted. arg[0, 1, 2, 3, ...]path Any string - Argument path matches provide a specialised form of wildcard - matching for path-like namespaces. As with normal argument matches, - if the argument is exactly equal to the string given in the match - rule then the rule is satisfied. Additionally, there is also a - match when either the string given in the match rule or the - appropriate message argument ends with '/' and is a prefix of the - other. An example argument path match is arg0path='/aa/bb/'. This - would match messages with first arguments of '/', '/aa/', - '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match - messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'. + + Argument path matches provide a specialised form of wildcard matching for + path-like namespaces. They can match arguments whose type is either STRING or + OBJECT_PATH. As with normal argument matches, + if the argument is exactly equal to the string given in the match + rule then the rule is satisfied. Additionally, there is also a + match when either the string given in the match rule or the + appropriate message argument ends with '/' and is a prefix of the + other. An example argument path match is arg0path='/aa/bb/'. This + would match messages with first arguments of '/', '/aa/', + '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match + messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'. + + This is intended for monitoring “directories” in file system-like + hierarchies, as used in the dconf configuration + system. An application interested in all nodes in a particular hierarchy would + monitor arg0path='/ca/example/foo/'. Then the service could + emit a signal with zeroth argument "/ca/example/foo/bar" to + represent a modification to the “bar” property, or a signal with zeroth + argument "/ca/example/" to represent atomic modification of + many properties within that directory, and the interested application would be + notified in both cases. + + + This match key was added in version 0.12 of the + D-Bus specification, implemented for STRING + arguments by the bus daemon in dbus 1.2.0 and later, + and implemented for OBJECT_PATH arguments in dbus 1.5.0 + and later. + + + + + + arg0namespace + Like a bus name, except that the string is not + required to contain a '.' (period) + + Match messages whose first argument is of type STRING, and is a bus name + or interface name within the specified namespace. This is primarily intended + for watching name owner changes for a group of related bus names, rather than + for a single name or all name changes. + + Because every valid interface name is also a valid + bus name, this can also be used for messages whose + first argument is an interface name. + + For example, the match rule + member='NameOwnerChanged',arg0namespace='com.example.backend' + matches name owner changes for bus names such as + com.example.backend.foo, + com.example.backend.foo.bar, and + com.example.backend itself. + + See also . + + + This match key was added in version 0.16 of the + D-Bus specification and implemented by the bus + daemon in dbus 1.5.0 and later. + + + + + + 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. + @@ -3517,9 +4618,9 @@ With D-Bus, starting a service is normally done by name. That is, applications ask the message bus to start some program that will own a - well-known name, such as org.freedesktop.TextEditor. - This implies a contract documented along with the name - org.freedesktop.TextEditor for which objects + well-known name, such as com.example.TextEditor. + This implies a contract documented along with the name + com.example.TextEditor for which object the owner of that name will provide, and what interfaces those objects will have. @@ -3531,25 +4632,35 @@ . - [FIXME the file format should be much better specified than "similar to - .desktop entries" esp. since desktop entries are already - badly-specified. ;-)] Service description files have the ".service" file + Service description files have the ".service" file extension. The message bus will only load service description files ending with .service; all other files will be ignored. The file format is similar to that of desktop + url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop entries. All service description files must be in UTF-8 encoding. To ensure that there will be no name collisions, service files must be namespaced using the same mechanism as messages and service names. + + + + [FIXME the file format should be much better specified than "similar to + .desktop entries" esp. since desktop entries are already + badly-specified. ;-)] + These sections from the specification apply to service files as well: + + + General syntax + Comment format +
Example service description file # Sample service description file [D-BUS Service] - Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; - Exec=/usr/libexec/gconfd-2 + Name=com.example.ConfigurationDatabase + Exec=/usr/bin/sample-configd
@@ -3585,62 +4696,288 @@ timeout, an error should be sent back.] - - Message Bus Service Scope - - The "scope" of a service is its "per-", such as per-session, - per-machine, per-home-directory, or per-display. The reference - implementation doesn't yet support starting services in a different - scope from the message bus itself. So e.g. if you start a service - on the session bus its scope is per-session. - - - We could add an optional scope to a bus name. For example, for - per-(display,session pair), we could have a unique ID for each display - generated automatically at login and set on screen 0 by executing a - special "set display ID" binary. The ID would be stored in a - _DBUS_DISPLAY_ID property and would be a string of - random bytes. This ID would then be used to scope names. - Starting/locating a service could be done by ID-name pair rather than - only by name. - - - Contrast this with a per-display scope. To achieve that, we would - want a single bus spanning all sessions using a given display. - So we might set a _DBUS_DISPLAY_BUS_ADDRESS - property on screen 0 of the display, pointing to this bus. - - - + + Message Bus Service Scope + + The "scope" of a service is its "per-", such as per-session, + per-machine, per-home-directory, or per-display. The reference + implementation doesn't yet support starting services in a different + scope from the message bus itself. So e.g. if you start a service + on the session bus its scope is per-session. + + + We could add an optional scope to a bus name. For example, for + per-(display,session pair), we could have a unique ID for each display + generated automatically at login and set on screen 0 by executing a + special "set display ID" binary. The ID would be stored in a + _DBUS_DISPLAY_ID property and would be a string of + random bytes. This ID would then be used to scope names. + Starting/locating a service could be done by ID-name pair rather than + only by name. + + + Contrast this with a per-display scope. To achieve that, we would + want a single bus spanning all sessions using a given display. + So we might set a _DBUS_DISPLAY_BUS_ADDRESS + property on screen 0 of the display, pointing to this bus. + + + + + + Well-known Message Bus Instances + + Two standard message bus instances are defined here, along with how + to locate them and where their service files live. + + + Login session message bus + + Each time a user logs in, a login session message + bus may be started. All applications in the user's login + session may interact with one another using this message bus. + + + The address of the login session message bus is given + in the DBUS_SESSION_BUS_ADDRESS environment + variable. If that variable is not set, applications may + also try to read the address from the X Window System root + window property _DBUS_SESSION_BUS_ADDRESS. + The root window property must have type STRING. + The environment variable should have precedence over the + root window property. + + The address of the login session message bus is given in the + DBUS_SESSION_BUS_ADDRESS environment variable. If + DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string + "autolaunch:", the system should use platform-specific methods of + locating a running D-Bus session server, or starting one if a running + instance cannot be found. Note that this mechanism is not recommended + for attempting to determine if a daemon is running. It is inherently + racy to attempt to make this determination, since the bus daemon may + be started just before or just after the determination is made. + Therefore, it is recommended that applications do not try to make this + determination for their functionality purposes, and instead they + should attempt to start the server. + + + X Windowing System + + For the X Windowing System, the application must locate the + window owner of the selection represented by the atom formed by + concatenating: + + + the literal string "_DBUS_SESSION_BUS_SELECTION_" + + + + the current user's username + + + + the literal character '_' (underscore) + + + + the machine's ID + + + + + + The following properties are defined for the window that owns + this X selection: + + + + + + Atom + + + + meaning + + + + + + _DBUS_SESSION_BUS_ADDRESS + + + + the actual address of the server socket + + + + + + _DBUS_SESSION_BUS_PID + + + + the PID of the server process + + + + + + + + + At least the _DBUS_SESSION_BUS_ADDRESS property MUST be + present in this window. + + + + If the X selection cannot be located or if reading the + properties from the window fails, the implementation MUST conclude + that there is no D-Bus server running and proceed to start a new + server. (See below on concurrency issues) + + + + Failure to connect to the D-Bus server address thus obtained + MUST be treated as a fatal connection error and should be reported + to the application. + + + + As an alternative, an implementation MAY find the information + in the following file located in the current user's home directory, + in subdirectory .dbus/session-bus/: + + + the machine's ID + + + + the literal character '-' (dash) + + + + the X display without the screen number, with the + following prefixes removed, if present: ":", "localhost:" + ."localhost.localdomain:". That is, a display of + "localhost:10.0" produces just the number "10" + + + + + + The contents of this file NAME=value assignment pairs and + lines starting with # are comments (no comments are allowed + otherwise). The following variable names are defined: + + + + + + Variable + + + + meaning + + + + + + DBUS_SESSION_BUS_ADDRESS + + + + the actual address of the server socket + + + + + + DBUS_SESSION_BUS_PID + + + + the PID of the server process + + - - Well-known Message Bus Instances - - Two standard message bus instances are defined here, along with how - to locate them and where their service files live. - - - Login session message bus - - Each time a user logs in, a login session message - bus may be started. All applications in the user's login - session may interact with one another using this message bus. - - - The address of the login session message bus is given - in the DBUS_SESSION_BUS_ADDRESS environment - variable. If that variable is not set, applications may - also try to read the address from the X Window System root - window property _DBUS_SESSION_BUS_ADDRESS. - The root window property must have type STRING. - The environment variable should have precedence over the - root window property. - - - [FIXME specify location of .service files, probably using - DESKTOP_DIRS etc. from basedir specification, though login session - bus is not really desktop-specific] - + + + DBUS_SESSION_BUS_WINDOWID + + + + the window ID + + + + + + + + + At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present + in this file. + + + + Failure to open this file MUST be interpreted as absence of a + running server. Therefore, the implementation MUST proceed to + attempting to launch a new bus server if the file cannot be + opened. + + + + However, success in opening this file MUST NOT lead to the + conclusion that the server is running. Thus, a failure to connect to + the bus address obtained by the alternative method MUST NOT be + considered a fatal error. If the connection cannot be established, + the implementation MUST proceed to check the X selection settings or + to start the server on its own. + + + + If the implementation concludes that the D-Bus server is not + running it MUST attempt to start a new server and it MUST also + ensure that the daemon started as an effect of the "autolaunch" + mechanism provides the lookup mechanisms described above, so + subsequent calls can locate the newly started server. The + implementation MUST also ensure that if two or more concurrent + initiations happen, only one server remains running and all other + initiations are able to obtain the address of this server and + connect to it. In other words, the implementation MUST ensure that + the X selection is not present when it attempts to set it, without + allowing another process to set the selection between the + verification and the setting (e.g., by using XGrabServer / + XungrabServer). + + + + + + 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. + + System message bus @@ -3665,7 +5002,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. @@ -4116,7 +5478,7 @@ As a method: - UINT32 GetConnectionUnixUser (in STRING connection_name) + UINT32 GetConnectionUnixUser (in STRING bus_name) Message arguments: @@ -4132,7 +5494,9 @@ 0 STRING - Name of the connection to query + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea @@ -4151,14 +5515,14 @@ 0 UINT32 - unix user id + Unix user ID - Returns the unix uid of the process connected to the server. If unable to - determine it, a org.freedesktop.DBus.Error.Failed - error is returned. + Returns the Unix user ID of the process connected to the server. If + unable to determine it (for instance, because the process is not on the + same machine as the bus daemon), an error is returned. @@ -4215,6 +5579,225 @@ + + <literal>org.freedesktop.DBus.GetConnectionCredentials</literal> + + As a method: + + DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + DICT<STRING,VARIANT> + Credentials + + + + + + + + Returns as many credentials as possible for the process connected to + the server. If unable to determine certain credentials (for instance, + because the process is not on the same machine as the bus daemon, + or because this version of the bus daemon does not support a + particular security framework), or if the values of those credentials + cannot be represented as documented here, then those credentials + are omitted. + + + + Keys in the returned dictionary not containing "." are defined + by this specification. Bus daemon implementors supporting + credentials frameworks not mentioned in this document should either + contribute patches to this specification, or use keys containing + "." and starting with a reversed domain name. + + + + + Key + Value type + Value + + + + + UnixUserID + UINT32 + The numeric Unix user ID, as defined by POSIX + + + ProcessID + UINT32 + The numeric process ID, on platforms that have + this concept. On Unix, this is the process ID defined by + POSIX. + + + + + + + + This method was added in D-Bus 1.7 to reduce the round-trips + required to list a process's credentials. In older versions, calling + this method will fail: applications should recover by using the + separate methods such as + + instead. + + + + + <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal> + + As a method: + + ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of BYTE + auditing data as returned by + adt_export_session_data() + + + + + Returns auditing data used by Solaris ADT, in an unspecified + binary format. If you know what this means, please contribute + documentation via the D-Bus bug tracking system. + This method is on the core DBus interface for historical reasons; + the same information should be made available via + + in future. + + + + + <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal> + + As a method: + + ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + + + Reply arguments: + + + + + Argument + Type + Description + + + + + 0 + ARRAY of BYTE + some sort of string of bytes, not necessarily UTF-8, + not including '\0' + + + + + Returns the security context used by SELinux, in an unspecified + format. If you know what this means, please contribute + documentation via the D-Bus bug tracking system. + This method is on the core DBus interface for historical reasons; + the same information should be made available via + + in future. + + + + <literal>org.freedesktop.DBus.AddMatch</literal> @@ -4350,6 +5933,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. + @@ -4388,10 +5976,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 , + , + , + . @@ -4448,9 +6040,9 @@ A service is an executable that can be launched by the bus daemon. Services normally guarantee some particular features, for example they may guarantee that they will request a specific name such as - "org.freedesktop.Screensaver", have a singleton object - "/org/freedesktop/Application", and that object will implement the - interface "org.freedesktop.ScreensaverControl". + "com.example.Screensaver", have a singleton object + "/com/example/Application", and that object will implement the + interface "com.example.Screensaver.Control".