X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fdbus-specification.xml;h=673383a99bbd1ab5d4cb4c9988aceac3c880aa44;hb=7d9239c9c78cb6d0b9c282376fcf3cda1de23209;hp=7280cf1768611b037b8168796e3e2031fddfb5a6;hpb=33a77c860593083cdbc55bf25633c41f59e77c16;p=platform%2Fupstream%2Fdbus.git diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 7280cf1..673383a 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1,13 +1,13 @@ -
D-Bus Specification - Version 0.19 - UNRELEASED + Version 0.22 + (not yet released) Havoc @@ -72,12 +72,35 @@ - current - commit log + 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 @@ -283,17 +306,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. @@ -310,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. @@ -369,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 @@ -404,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 @@ -426,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. @@ -557,9 +872,21 @@ + + + + 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 @@ -568,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. @@ -588,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: @@ -652,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) @@ -661,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 @@ -670,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) @@ -696,14 +1106,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) @@ -727,113 +1132,10 @@ 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. - - - - - - + + + + @@ -1228,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 @@ -1269,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 @@ -1283,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. + @@ -2074,7 +2447,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2110,7 +2483,7 @@ - Receive REJECT [mechs] → send AUTH [next mech], + Receive REJECTED [mechs] → send AUTH [next mech], goto WaitingForData or WaitingForOK @@ -2152,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. @@ -2199,7 +2572,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2253,7 +2626,7 @@ - MECH(RESP) returns REJECT → send REJECTED + MECH(RESP) returns REJECTED → send REJECTED [mechs], goto WaitingForAuth @@ -2567,7 +2940,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. @@ -2589,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 @@ -2630,7 +3003,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. @@ -2674,6 +3047,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 @@ -2685,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. @@ -2803,6 +3197,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 @@ -2892,22 +3347,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 @@ -3037,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 . @@ -3206,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"/> @@ -3367,14 +3822,17 @@ 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. + 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 @@ -3386,7 +3844,7 @@ This feature causes the right thing to happen if you start two text - editors for example; the first one may request "org.freedesktop.TextEditor", + 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. @@ -3958,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. @@ -4161,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. @@ -4202,8 +4659,8 @@ # 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 @@ -4500,9 +4957,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. @@ -4529,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. @@ -5081,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> @@ -5216,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. + @@ -5254,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 , + , + , + . @@ -5314,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".