1 <?xml version="1.0" standalone="no" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
8 <title>D-Bus Specification</title>
9 <releaseinfo>Version 0.19</releaseinfo>
10 <date>2012-02-21</date>
13 <firstname>Havoc</firstname>
14 <surname>Pennington</surname>
16 <orgname>Red Hat, Inc.</orgname>
18 <email>hp@pobox.com</email>
23 <firstname>Anders</firstname>
24 <surname>Carlsson</surname>
26 <orgname>CodeFactory AB</orgname>
28 <email>andersca@codefactory.se</email>
33 <firstname>Alexander</firstname>
34 <surname>Larsson</surname>
36 <orgname>Red Hat, Inc.</orgname>
38 <email>alexl@redhat.com</email>
43 <firstname>Sven</firstname>
44 <surname>Herzberg</surname>
46 <orgname>Imendio AB</orgname>
48 <email>sven@imendio.com</email>
53 <firstname>Simon</firstname>
54 <surname>McVittie</surname>
56 <orgname>Collabora Ltd.</orgname>
58 <email>simon.mcvittie@collabora.co.uk</email>
63 <firstname>David</firstname>
64 <surname>Zeuthen</surname>
66 <orgname>Red Hat, Inc.</orgname>
68 <email>davidz@redhat.com</email>
75 <revnumber>current</revnumber>
76 <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
77 <authorinitials></authorinitials>
78 <revremark></revremark>
81 <revnumber>0.19</revnumber>
82 <date>20 February 2012</date>
83 <authorinitials>smcv/lp</authorinitials>
84 <revremark>formally define unique connection names and well-known
85 bus names; document best practices for interface, bus, member and
86 error names, and object paths; document the search path for session
87 and system services on Unix; document the systemd transport</revremark>
90 <revnumber>0.18</revnumber>
91 <date>29 July 2011</date>
92 <authorinitials>smcv</authorinitials>
93 <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
94 match keyword; promote type system to a top-level section</revremark>
97 <revnumber>0.17</revnumber>
98 <date>1 June 2011</date>
99 <authorinitials>smcv/davidz</authorinitials>
100 <revremark>define ObjectManager; reserve extra pseudo-type-codes used
101 by GVariant</revremark>
104 <revnumber>0.16</revnumber>
105 <date>11 April 2011</date>
106 <authorinitials></authorinitials>
107 <revremark>add path_namespace, arg0namespace; argNpath matches object
111 <revnumber>0.15</revnumber>
112 <date>3 November 2010</date>
113 <authorinitials></authorinitials>
114 <revremark></revremark>
117 <revnumber>0.14</revnumber>
118 <date>12 May 2010</date>
119 <authorinitials></authorinitials>
120 <revremark></revremark>
123 <revnumber>0.13</revnumber>
124 <date>23 Dezember 2009</date>
125 <authorinitials></authorinitials>
126 <revremark></revremark>
129 <revnumber>0.12</revnumber>
130 <date>7 November, 2006</date>
131 <authorinitials></authorinitials>
132 <revremark></revremark>
135 <revnumber>0.11</revnumber>
136 <date>6 February 2005</date>
137 <authorinitials></authorinitials>
138 <revremark></revremark>
141 <revnumber>0.10</revnumber>
142 <date>28 January 2005</date>
143 <authorinitials></authorinitials>
144 <revremark></revremark>
147 <revnumber>0.9</revnumber>
148 <date>7 Januar 2005</date>
149 <authorinitials></authorinitials>
150 <revremark></revremark>
153 <revnumber>0.8</revnumber>
154 <date>06 September 2003</date>
155 <authorinitials></authorinitials>
156 <revremark>First released document.</revremark>
161 <sect1 id="introduction">
162 <title>Introduction</title>
164 D-Bus is a system for low-latency, low-overhead, easy to use
165 interprocess communication (IPC). In more detail:
169 D-Bus is <emphasis>low-latency</emphasis> because it is designed
170 to avoid round trips and allow asynchronous operation, much like
176 D-Bus is <emphasis>low-overhead</emphasis> because it uses a
177 binary protocol, and does not have to convert to and from a text
178 format such as XML. Because D-Bus is intended for potentially
179 high-resolution same-machine IPC, not primarily for Internet IPC,
180 this is an interesting optimization.
185 D-Bus is <emphasis>easy to use</emphasis> because it works in terms
186 of <firstterm>messages</firstterm> rather than byte streams, and
187 automatically handles a lot of the hard IPC issues. Also, the D-Bus
188 library is designed to be wrapped in a way that lets developers use
189 their framework's existing object/type system, rather than learning
190 a new one specifically for IPC.
197 The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
198 protocol, specified in <xref linkend="message-protocol"/>. That is, it is
199 a system for one application to talk to a single other
200 application. However, the primary intended application of the protocol is the
201 D-Bus <firstterm>message bus</firstterm>, specified in <xref
202 linkend="message-bus"/>. The message bus is a special application that
203 accepts connections from multiple other applications, and forwards
208 Uses of D-Bus include notification of system changes (notification of when
209 a camera is plugged in to a computer, or a new version of some software
210 has been installed), or desktop interoperability, for example a file
211 monitoring service or a configuration service.
215 D-Bus is designed for two specific use cases:
219 A "system bus" for notifications from the system to user sessions,
220 and to allow the system to request input from user sessions.
225 A "session bus" used to implement desktop environments such as
230 D-Bus is not intended to be a generic IPC system for any possible
231 application, and intentionally omits many features found in other
232 IPC systems for this reason.
236 At the same time, the bus daemons offer a number of features not found in
237 other IPC systems, such as single-owner "bus names" (similar to X
238 selections), on-demand startup of services, and security policies.
239 In many ways, these features are the primary motivation for developing
240 D-Bus; other systems would have sufficed if IPC were the only goal.
244 D-Bus may turn out to be useful in unanticipated applications, but future
245 versions of this spec and the reference implementation probably will not
246 incorporate features that interfere with the core use cases.
250 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
251 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
252 document are to be interpreted as described in RFC 2119. However, the
253 document could use a serious audit to be sure it makes sense to do
254 so. Also, they are not capitalized.
257 <sect2 id="stability">
258 <title>Protocol and Specification Stability</title>
260 The D-Bus protocol is frozen (only compatible extensions are allowed) as
261 of November 8, 2006. However, this specification could still use a fair
262 bit of work to make interoperable reimplementation possible without
263 reference to the D-Bus reference implementation. Thus, this
264 specification is not marked 1.0. To mark it 1.0, we'd like to see
265 someone invest significant effort in clarifying the specification
266 language, and growing the specification to cover more aspects of the
267 reference implementation's behavior.
270 Until this work is complete, any attempt to reimplement D-Bus will
271 probably require looking at the reference implementation and/or asking
272 questions on the D-Bus mailing list about intended behavior.
273 Questions on the list are very welcome.
276 Nonetheless, this document should be a useful starting point and is
277 to our knowledge accurate, though incomplete.
283 <sect1 id="type-system">
284 <title>Type System</title>
287 D-Bus has a type system, in which values of various types can be
288 serialized into a sequence of bytes referred to as the
289 <firstterm>wire format</firstterm> in a standard way.
290 Converting a value from some other representation into the wire
291 format is called <firstterm>marshaling</firstterm> and converting
292 it back from the wire format is <firstterm>unmarshaling</firstterm>.
296 The D-Bus protocol does not include type tags in the marshaled data; a
297 block of marshaled values must have a known <firstterm>type
298 signature</firstterm>. The type signature is made up of zero or more
299 <firstterm id="term-single-complete-type">single complete
300 types</firstterm>, each made up of one or more
301 <firstterm>type codes</firstterm>.
305 A type code is an ASCII character representing the
306 type of a value. Because ASCII characters are used, the type signature
307 will always form a valid ASCII string. A simple string compare
308 determines whether two type signatures are equivalent.
312 A single complete type is a sequence of type codes that fully describes
313 one type: either a basic type, or a single fully-described container type.
314 A single complete type is a basic type code, a variant type code,
315 an array with its element type, or a struct with its fields (all of which
316 are defined below). So the following signatures are not single complete
327 And the following signatures contain multiple complete types:
337 Note however that a single complete type may <emphasis>contain</emphasis>
338 multiple other single complete types, by containing a struct or dict
342 <sect2 id="basic-types">
343 <title>Basic types</title>
346 The simplest type codes are the <firstterm id="term-basic-type">basic
347 types</firstterm>, which are the types whose structure is entirely
348 defined by their 1-character type code. Basic types consist of
349 fixed types and string-like types.
353 The <firstterm id="term-fixed-type">fixed types</firstterm>
354 are basic types whose values have a fixed length, namely BYTE,
355 BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
360 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
361 the ASCII character 'i'. So the signature for a block of values
362 containing a single <literal>INT32</literal> would be:
366 A block of values containing two <literal>INT32</literal> would have this signature:
373 The characteristics of the fixed types are listed in this table.
379 <entry>Conventional name</entry>
380 <entry>ASCII type-code</entry>
381 <entry>Encoding</entry>
386 <entry><literal>BYTE</literal></entry>
387 <entry><literal>y</literal> (121)</entry>
388 <entry>Unsigned 8-bit integer</entry>
391 <entry><literal>BOOLEAN</literal></entry>
392 <entry><literal>b</literal> (98)</entry>
393 <entry>Boolean value: 0 is false, 1 is true, any other value
394 allowed by the marshalling format is invalid</entry>
397 <entry><literal>INT16</literal></entry>
398 <entry><literal>n</literal> (110)</entry>
399 <entry>Signed (two's complement) 16-bit integer</entry>
402 <entry><literal>UINT16</literal></entry>
403 <entry><literal>q</literal> (113)</entry>
404 <entry>Unsigned 16-bit integer</entry>
407 <entry><literal>INT32</literal></entry>
408 <entry><literal>i</literal> (105)</entry>
409 <entry>Signed (two's complement) 32-bit integer</entry>
412 <entry><literal>UINT32</literal></entry>
413 <entry><literal>u</literal> (117)</entry>
414 <entry>Unsigned 32-bit integer</entry>
417 <entry><literal>INT64</literal></entry>
418 <entry><literal>x</literal> (120)</entry>
419 <entry>Signed (two's complement) 64-bit integer
420 (mnemonic: x and t are the first characters in "sixty" not
421 already used for something more common)</entry>
424 <entry><literal>UINT64</literal></entry>
425 <entry><literal>t</literal> (116)</entry>
426 <entry>Unsigned 64-bit integer</entry>
429 <entry><literal>DOUBLE</literal></entry>
430 <entry><literal>d</literal> (100)</entry>
431 <entry>IEEE 754 double-precision floating point</entry>
434 <entry><literal>UNIX_FD</literal></entry>
435 <entry><literal>h</literal> (104)</entry>
436 <entry>Unsigned 32-bit integer representing an index into an
437 out-of-band array of file descriptors, transferred via some
438 platform-specific mechanism (mnemonic: h for handle)</entry>
446 The <firstterm id="term-string-like-type">string-like types</firstterm>
447 are basic types with a variable length. The value of any string-like
448 type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
449 none of which may be U+0000. The UTF-8 text must be validated
450 strictly: in particular, it must not contain overlong sequences,
451 noncharacters such as U+FFFE, or codepoints above U+10FFFF.
455 The marshalling formats for the string-like types all end with a
456 single zero (NUL) byte, but that byte is not considered to be part of
461 The characteristics of the string-like types are listed in this table.
467 <entry>Conventional name</entry>
468 <entry>ASCII type-code</entry>
469 <entry>Validity constraints</entry>
474 <entry><literal>STRING</literal></entry>
475 <entry><literal>s</literal> (115)</entry>
476 <entry>No extra constraints</entry>
479 <entry><literal>OBJECT_PATH</literal></entry>
480 <entry><literal>o</literal> (111)</entry>
482 <link linkend="message-protocol-marshaling-object-path">a
483 syntactically valid object path</link></entry>
486 <entry><literal>SIGNATURE</literal></entry>
487 <entry><literal>g</literal> (103)</entry>
489 <firstterm linkend="term-single-complete-type">single
490 complete types</firstterm></entry>
497 <sect3 id="message-protocol-marshaling-object-path">
498 <title>Valid Object Paths</title>
501 An object path is a name used to refer to an object instance.
502 Conceptually, each participant in a D-Bus message exchange may have
503 any number of object instances (think of C++ or Java objects) and each
504 such instance will have a path. Like a filesystem, the object
505 instances in an application form a hierarchical tree.
509 Object paths are often namespaced by starting with a reversed
510 domain name and containing an interface version number, in the
512 <link linkend="message-protocol-names-interface">interface
514 <link linkend="message-protocol-names-bus">well-known
516 This makes it possible to implement more than one service, or
517 more than one version of a service, in the same process,
518 even if the services share a connection but cannot otherwise
519 co-operate (for instance, if they are implemented by different
524 For instance, if the owner of <literal>example.com</literal> is
525 developing a D-Bus API for a music player, they might use the
526 hierarchy of object paths that start with
527 <literal>/com/example/MusicPlayer1</literal> for its objects.
531 The following rules define a valid object path. Implementations must
532 not send or accept messages with invalid object paths.
536 The path may be of any length.
541 The path must begin with an ASCII '/' (integer 47) character,
542 and must consist of elements separated by slash characters.
547 Each element must only contain the ASCII characters
553 No element may be the empty string.
558 Multiple '/' characters cannot occur in sequence.
563 A trailing '/' character is not allowed unless the
564 path is the root path (a single '/' character).
572 <sect3 id="message-protocol-marshaling-signature">
573 <title>Valid Signatures</title>
575 An implementation must not send or accept invalid signatures.
576 Valid signatures will conform to the following rules:
580 The signature is a list of single complete types.
581 Arrays must have element types, and structs must
582 have both open and close parentheses.
587 Only type codes, open and close parentheses, and open and
588 close curly brackets are allowed in the signature. The
589 <literal>STRUCT</literal> type code
590 is not allowed in signatures, because parentheses
591 are used instead. Similarly, the
592 <literal>DICT_ENTRY</literal> type code is not allowed in
593 signatures, because curly brackets are used instead.
598 The maximum depth of container type nesting is 32 array type
599 codes and 32 open parentheses. This implies that the maximum
600 total depth of recursion is 64, for an "array of array of array
601 of ... struct of struct of struct of ..." where there are 32
607 The maximum length of a signature is 255.
614 When signatures appear in messages, the marshalling format
615 guarantees that they will be followed by a nul byte (which can
616 be interpreted as either C-style string termination or the INVALID
617 type-code), but this is not conceptually part of the signature.
623 <sect2 id="container-types">
624 <title>Container types</title>
627 In addition to basic types, there are four <firstterm>container</firstterm>
628 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
629 and <literal>DICT_ENTRY</literal>.
633 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
634 code does not appear in signatures. Instead, ASCII characters
635 '(' and ')' are used to mark the beginning and end of the struct.
636 So for example, a struct containing two integers would have this
641 Structs can be nested, so for example a struct containing
642 an integer and another struct:
646 The value block storing that struct would contain three integers; the
647 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
652 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
653 but is useful in code that implements the protocol. This type code
654 is specified to allow such code to interoperate in non-protocol contexts.
658 Empty structures are not allowed; there must be at least one
659 type code between the parentheses.
663 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
664 followed by a <firstterm>single complete type</firstterm>. The single
665 complete type following the array is the type of each array element. So
666 the simple example is:
670 which is an array of 32-bit integers. But an array can be of any type,
671 such as this array-of-struct-with-two-int32-fields:
675 Or this array of array of integer:
682 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
683 type <literal>VARIANT</literal> will have the signature of a single complete type as part
684 of the <emphasis>value</emphasis>. This signature will be followed by a
685 marshaled value of that type.
689 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
690 than parentheses it uses curly braces, and it has more restrictions.
691 The restrictions are: it occurs only as an array element type; it has
692 exactly two single complete types inside the curly braces; the first
693 single complete type (the "key") must be a basic type rather than a
694 container type. Implementations must not accept dict entries outside of
695 arrays, must not accept dict entries with zero, one, or more than two
696 fields, and must not accept dict entries with non-basic-typed keys. A
697 dict entry is always a key-value pair.
701 The first field in the <literal>DICT_ENTRY</literal> is always the key.
702 A message is considered corrupt if the same key occurs twice in the same
703 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
704 implementations are not required to reject dicts with duplicate keys.
708 In most languages, an array of dict entry would be represented as a
709 map, hash table, or dict object.
714 <title>Summary of types</title>
717 The following table summarizes the D-Bus types.
722 <entry>Conventional Name</entry>
724 <entry>Description</entry>
729 <entry><literal>INVALID</literal></entry>
730 <entry>0 (ASCII NUL)</entry>
731 <entry>Not a valid type code, used to terminate signatures</entry>
733 <entry><literal>BYTE</literal></entry>
734 <entry>121 (ASCII 'y')</entry>
735 <entry>8-bit unsigned integer</entry>
737 <entry><literal>BOOLEAN</literal></entry>
738 <entry>98 (ASCII 'b')</entry>
739 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
741 <entry><literal>INT16</literal></entry>
742 <entry>110 (ASCII 'n')</entry>
743 <entry>16-bit signed integer</entry>
745 <entry><literal>UINT16</literal></entry>
746 <entry>113 (ASCII 'q')</entry>
747 <entry>16-bit unsigned integer</entry>
749 <entry><literal>INT32</literal></entry>
750 <entry>105 (ASCII 'i')</entry>
751 <entry>32-bit signed integer</entry>
753 <entry><literal>UINT32</literal></entry>
754 <entry>117 (ASCII 'u')</entry>
755 <entry>32-bit unsigned integer</entry>
757 <entry><literal>INT64</literal></entry>
758 <entry>120 (ASCII 'x')</entry>
759 <entry>64-bit signed integer</entry>
761 <entry><literal>UINT64</literal></entry>
762 <entry>116 (ASCII 't')</entry>
763 <entry>64-bit unsigned integer</entry>
765 <entry><literal>DOUBLE</literal></entry>
766 <entry>100 (ASCII 'd')</entry>
767 <entry>IEEE 754 double</entry>
769 <entry><literal>STRING</literal></entry>
770 <entry>115 (ASCII 's')</entry>
771 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
773 <entry><literal>OBJECT_PATH</literal></entry>
774 <entry>111 (ASCII 'o')</entry>
775 <entry>Name of an object instance</entry>
777 <entry><literal>SIGNATURE</literal></entry>
778 <entry>103 (ASCII 'g')</entry>
779 <entry>A type signature</entry>
781 <entry><literal>ARRAY</literal></entry>
782 <entry>97 (ASCII 'a')</entry>
785 <entry><literal>STRUCT</literal></entry>
786 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
787 <entry>Struct; type code 114 'r' is reserved for use in
788 bindings and implementations to represent the general
789 concept of a struct, and must not appear in signatures
790 used on D-Bus.</entry>
792 <entry><literal>VARIANT</literal></entry>
793 <entry>118 (ASCII 'v') </entry>
794 <entry>Variant type (the type of the value is part of the value itself)</entry>
796 <entry><literal>DICT_ENTRY</literal></entry>
797 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
798 <entry>Entry in a dict or map (array of key-value pairs).
799 Type code 101 'e' is reserved for use in bindings and
800 implementations to represent the general concept of a
801 dict or dict-entry, and must not appear in signatures
802 used on D-Bus.</entry>
804 <entry><literal>UNIX_FD</literal></entry>
805 <entry>104 (ASCII 'h')</entry>
806 <entry>Unix file descriptor</entry>
809 <entry>(reserved)</entry>
810 <entry>109 (ASCII 'm')</entry>
811 <entry>Reserved for <ulink
812 url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
813 'maybe' type compatible with the one in GVariant</ulink>,
814 and must not appear in signatures used on D-Bus until
815 specified here</entry>
818 <entry>(reserved)</entry>
819 <entry>42 (ASCII '*')</entry>
820 <entry>Reserved for use in bindings/implementations to
821 represent any <firstterm>single complete type</firstterm>,
822 and must not appear in signatures used on D-Bus.</entry>
825 <entry>(reserved)</entry>
826 <entry>63 (ASCII '?')</entry>
827 <entry>Reserved for use in bindings/implementations to
828 represent any <firstterm>basic type</firstterm>, and must
829 not appear in signatures used on D-Bus.</entry>
832 <entry>(reserved)</entry>
833 <entry>64 (ASCII '@'), 38 (ASCII '&'),
834 94 (ASCII '^')</entry>
835 <entry>Reserved for internal use by bindings/implementations,
836 and must not appear in signatures used on D-Bus.
837 GVariant uses these type-codes to encode calling
848 <sect1 id="message-protocol-marshaling">
849 <title>Marshaling (Wire Format)</title>
852 D-Bus defines a marshalling format for its type system, which is
853 used in D-Bus messages. This is not the only possible marshalling
854 format for the type system: for instance, GVariant (part of GLib)
855 re-uses the D-Bus type system but implements an alternative marshalling
860 <title>Byte order and alignment</title>
863 Given a type signature, a block of bytes can be converted into typed
864 values. This section describes the format of the block of bytes. Byte
865 order and alignment issues are handled uniformly for all D-Bus types.
869 A block of bytes has an associated byte order. The byte order
870 has to be discovered in some way; for D-Bus messages, the
871 byte order is part of the message header as described in
872 <xref linkend="message-protocol-messages"/>. For now, assume
873 that the byte order is known to be either little endian or big
878 Each value in a block of bytes is aligned "naturally," for example
879 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
880 8-byte boundary. To properly align a value, <firstterm>alignment
881 padding</firstterm> may be necessary. The alignment padding must always
882 be the minimum required padding to properly align the following value;
883 and it must always be made up of nul bytes. The alignment padding must
884 not be left uninitialized (it can't contain garbage), and more padding
885 than required must not be used.
890 <title>Marshalling basic types</title>
893 To marshal and unmarshal fixed types, you simply read one value
894 from the data block corresponding to each type code in the signature.
895 All signed integer values are encoded in two's complement, DOUBLE
896 values are IEEE 754 double-precision floating-point, and BOOLEAN
897 values are encoded in 32 bits (of which only the least significant
902 The string-like types are all marshalled as a
903 fixed-length unsigned integer <varname>n</varname> giving the
904 length of the variable part, followed by <varname>n</varname>
905 nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
906 which is not considered to be part of the text. The alignment
907 of the string-like type is the same as the alignment of
908 <varname>n</varname>.
912 For the STRING and OBJECT_PATH types, <varname>n</varname> is
913 encoded in 4 bytes, leading to 4-byte alignment.
914 For the SIGNATURE type, <varname>n</varname> is encoded as a single
915 byte. As a result, alignment padding is never required before a
921 <title>Marshalling containers</title>
923 <para>... to be written ...</para>
927 <title>Summary of D-Bus marshalling</title>
930 Given all this, the types are marshaled on the wire as follows:
935 <entry>Conventional Name</entry>
936 <entry>Encoding</entry>
937 <entry>Alignment</entry>
942 <entry><literal>INVALID</literal></entry>
943 <entry>Not applicable; cannot be marshaled.</entry>
946 <entry><literal>BYTE</literal></entry>
947 <entry>A single 8-bit byte.</entry>
950 <entry><literal>BOOLEAN</literal></entry>
951 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
954 <entry><literal>INT16</literal></entry>
955 <entry>16-bit signed integer in the message's byte order.</entry>
958 <entry><literal>UINT16</literal></entry>
959 <entry>16-bit unsigned integer in the message's byte order.</entry>
962 <entry><literal>INT32</literal></entry>
963 <entry>32-bit signed integer in the message's byte order.</entry>
966 <entry><literal>UINT32</literal></entry>
967 <entry>32-bit unsigned integer in the message's byte order.</entry>
970 <entry><literal>INT64</literal></entry>
971 <entry>64-bit signed integer in the message's byte order.</entry>
974 <entry><literal>UINT64</literal></entry>
975 <entry>64-bit unsigned integer in the message's byte order.</entry>
978 <entry><literal>DOUBLE</literal></entry>
979 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
982 <entry><literal>STRING</literal></entry>
983 <entry>A <literal>UINT32</literal> indicating the string's
984 length in bytes excluding its terminating nul, followed by
985 non-nul string data of the given length, followed by a terminating nul
992 <entry><literal>OBJECT_PATH</literal></entry>
993 <entry>Exactly the same as <literal>STRING</literal> except the
994 content must be a valid object path (see above).
1000 <entry><literal>SIGNATURE</literal></entry>
1001 <entry>The same as <literal>STRING</literal> except the length is a single
1002 byte (thus signatures have a maximum length of 255)
1003 and the content must be a valid signature (see above).
1009 <entry><literal>ARRAY</literal></entry>
1011 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
1012 alignment padding to the alignment boundary of the array element type,
1013 followed by each array element. The array length is from the
1014 end of the alignment padding to the end of the last element,
1015 i.e. it does not include the padding after the length,
1016 or any padding after the last element.
1017 Arrays have a maximum length defined to be 2 to the 26th power or
1018 67108864. Implementations must not send or accept arrays exceeding this
1025 <entry><literal>STRUCT</literal></entry>
1027 A struct must start on an 8-byte boundary regardless of the
1028 type of the struct fields. The struct value consists of each
1029 field marshaled in sequence starting from that 8-byte
1036 <entry><literal>VARIANT</literal></entry>
1038 A variant type has a marshaled
1039 <literal>SIGNATURE</literal> followed by a marshaled
1040 value with the type given in the signature. Unlike
1041 a message signature, the variant signature can
1042 contain only a single complete type. So "i", "ai"
1043 or "(ii)" is OK, but "ii" is not. Use of variants may not
1044 cause a total message depth to be larger than 64, including
1045 other container types such as structures.
1048 1 (alignment of the signature)
1051 <entry><literal>DICT_ENTRY</literal></entry>
1053 Identical to STRUCT.
1059 <entry><literal>UNIX_FD</literal></entry>
1060 <entry>32-bit unsigned integer in the message's byte
1061 order. The actual file descriptors need to be
1062 transferred out-of-band via some platform specific
1063 mechanism. On the wire, values of this type store the index to the
1064 file descriptor in the array of file descriptors that
1065 accompany the message.</entry>
1077 <sect1 id="message-protocol">
1078 <title>Message Protocol</title>
1081 A <firstterm>message</firstterm> consists of a
1082 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
1083 think of a message as a package, the header is the address, and the body
1084 contains the package contents. The message delivery system uses the header
1085 information to figure out where to send the message and how to interpret
1086 it; the recipient interprets the body of the message.
1090 The body of the message is made up of zero or more
1091 <firstterm>arguments</firstterm>, which are typed values, such as an
1092 integer or a byte array.
1096 Both header and body use the D-Bus <link linkend="type-system">type
1097 system</link> and format for serializing data.
1100 <sect2 id="message-protocol-messages">
1101 <title>Message Format</title>
1104 A message consists of a header and a body. The header is a block of
1105 values with a fixed signature and meaning. The body is a separate block
1106 of values, with a signature specified in the header.
1110 The length of the header must be a multiple of 8, allowing the body to
1111 begin on an 8-byte boundary when storing the entire message in a single
1112 buffer. If the header does not naturally end on an 8-byte boundary
1113 up to 7 bytes of nul-initialized alignment padding must be added.
1117 The message body need not end on an 8-byte boundary.
1121 The maximum length of a message, including header, header alignment padding,
1122 and body is 2 to the 27th power or 134217728. Implementations must not
1123 send or accept messages exceeding this size.
1127 The signature of the header is:
1131 Written out more readably, this is:
1133 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
1138 These values have the following meanings:
1143 <entry>Value</entry>
1144 <entry>Description</entry>
1149 <entry>1st <literal>BYTE</literal></entry>
1150 <entry>Endianness flag; ASCII 'l' for little-endian
1151 or ASCII 'B' for big-endian. Both header and body are
1152 in this endianness.</entry>
1155 <entry>2nd <literal>BYTE</literal></entry>
1156 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
1157 Currently-defined types are described below.
1161 <entry>3rd <literal>BYTE</literal></entry>
1162 <entry>Bitwise OR of flags. Unknown flags
1163 must be ignored. Currently-defined flags are described below.
1167 <entry>4th <literal>BYTE</literal></entry>
1168 <entry>Major protocol version of the sending application. If
1169 the major protocol version of the receiving application does not
1170 match, the applications will not be able to communicate and the
1171 D-Bus connection must be disconnected. The major protocol
1172 version for this version of the specification is 1.
1176 <entry>1st <literal>UINT32</literal></entry>
1177 <entry>Length in bytes of the message body, starting
1178 from the end of the header. The header ends after
1179 its alignment padding to an 8-boundary.
1183 <entry>2nd <literal>UINT32</literal></entry>
1184 <entry>The serial of this message, used as a cookie
1185 by the sender to identify the reply corresponding
1186 to this request. This must not be zero.
1190 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
1191 <entry>An array of zero or more <firstterm>header
1192 fields</firstterm> where the byte is the field code, and the
1193 variant is the field value. The message type determines
1194 which fields are required.
1202 <firstterm>Message types</firstterm> that can appear in the second byte
1208 <entry>Conventional name</entry>
1209 <entry>Decimal value</entry>
1210 <entry>Description</entry>
1215 <entry><literal>INVALID</literal></entry>
1217 <entry>This is an invalid type.</entry>
1220 <entry><literal>METHOD_CALL</literal></entry>
1222 <entry>Method call.</entry>
1225 <entry><literal>METHOD_RETURN</literal></entry>
1227 <entry>Method reply with returned data.</entry>
1230 <entry><literal>ERROR</literal></entry>
1232 <entry>Error reply. If the first argument exists and is a
1233 string, it is an error message.</entry>
1236 <entry><literal>SIGNAL</literal></entry>
1238 <entry>Signal emission.</entry>
1245 Flags that can appear in the third byte of the header:
1250 <entry>Conventional name</entry>
1251 <entry>Hex value</entry>
1252 <entry>Description</entry>
1257 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
1259 <entry>This message does not expect method return replies or
1260 error replies; the reply can be omitted as an
1261 optimization. However, it is compliant with this specification
1262 to return the reply despite this flag and the only harm
1263 from doing so is extra network traffic.
1267 <entry><literal>NO_AUTO_START</literal></entry>
1269 <entry>The bus must not launch an owner
1270 for the destination name in response to this message.
1278 <sect3 id="message-protocol-header-fields">
1279 <title>Header Fields</title>
1282 The array at the end of the header contains <firstterm>header
1283 fields</firstterm>, where each field is a 1-byte field code followed
1284 by a field value. A header must contain the required header fields for
1285 its message type, and zero or more of any optional header
1286 fields. Future versions of this protocol specification may add new
1287 fields. Implementations must ignore fields they do not
1288 understand. Implementations must not invent their own header fields;
1289 only changes to this specification may introduce new header fields.
1293 Again, if an implementation sees a header field code that it does not
1294 expect, it must ignore that field, as it will be part of a new
1295 (but compatible) version of this specification. This also applies
1296 to known header fields appearing in unexpected messages, for
1297 example: if a signal has a reply serial it must be ignored
1298 even though it has no meaning as of this version of the spec.
1302 However, implementations must not send or accept known header fields
1303 with the wrong type stored in the field value. So for example a
1304 message with an <literal>INTERFACE</literal> field of type
1305 <literal>UINT32</literal> would be considered corrupt.
1309 Here are the currently-defined header fields:
1314 <entry>Conventional Name</entry>
1315 <entry>Decimal Code</entry>
1317 <entry>Required In</entry>
1318 <entry>Description</entry>
1323 <entry><literal>INVALID</literal></entry>
1326 <entry>not allowed</entry>
1327 <entry>Not a valid field name (error if it appears in a message)</entry>
1330 <entry><literal>PATH</literal></entry>
1332 <entry><literal>OBJECT_PATH</literal></entry>
1333 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1334 <entry>The object to send a call to,
1335 or the object a signal is emitted from.
1337 <literal>/org/freedesktop/DBus/Local</literal> is reserved;
1338 implementations should not send messages with this path,
1339 and the reference implementation of the bus daemon will
1340 disconnect any application that attempts to do so.
1344 <entry><literal>INTERFACE</literal></entry>
1346 <entry><literal>STRING</literal></entry>
1347 <entry><literal>SIGNAL</literal></entry>
1349 The interface to invoke a method call on, or
1350 that a signal is emitted from. Optional for
1351 method calls, required for signals.
1352 The special interface
1353 <literal>org.freedesktop.DBus.Local</literal> is reserved;
1354 implementations should not send messages with this
1355 interface, and the reference implementation of the bus
1356 daemon will disconnect any application that attempts to
1361 <entry><literal>MEMBER</literal></entry>
1363 <entry><literal>STRING</literal></entry>
1364 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1365 <entry>The member, either the method name or signal name.</entry>
1368 <entry><literal>ERROR_NAME</literal></entry>
1370 <entry><literal>STRING</literal></entry>
1371 <entry><literal>ERROR</literal></entry>
1372 <entry>The name of the error that occurred, for errors</entry>
1375 <entry><literal>REPLY_SERIAL</literal></entry>
1377 <entry><literal>UINT32</literal></entry>
1378 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
1379 <entry>The serial number of the message this message is a reply
1380 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
1383 <entry><literal>DESTINATION</literal></entry>
1385 <entry><literal>STRING</literal></entry>
1386 <entry>optional</entry>
1387 <entry>The name of the connection this message is intended for.
1388 Only used in combination with the message bus, see
1389 <xref linkend="message-bus"/>.</entry>
1392 <entry><literal>SENDER</literal></entry>
1394 <entry><literal>STRING</literal></entry>
1395 <entry>optional</entry>
1396 <entry>Unique name of the sending connection.
1397 The message bus fills in this field so it is reliable; the field is
1398 only meaningful in combination with the message bus.</entry>
1401 <entry><literal>SIGNATURE</literal></entry>
1403 <entry><literal>SIGNATURE</literal></entry>
1404 <entry>optional</entry>
1405 <entry>The signature of the message body.
1406 If omitted, it is assumed to be the
1407 empty signature "" (i.e. the body must be 0-length).</entry>
1410 <entry><literal>UNIX_FDS</literal></entry>
1412 <entry><literal>UINT32</literal></entry>
1413 <entry>optional</entry>
1414 <entry>The number of Unix file descriptors that
1415 accompany the message. If omitted, it is assumed
1416 that no Unix file descriptors accompany the
1417 message. The actual file descriptors need to be
1418 transferred via platform specific mechanism
1419 out-of-band. They must be sent at the same time as
1420 part of the message itself. They may not be sent
1421 before the first byte of the message itself is
1422 transferred or after the last byte of the message
1432 <sect2 id="message-protocol-names">
1433 <title>Valid Names</title>
1435 The various names in D-Bus messages have some restrictions.
1438 There is a <firstterm>maximum name length</firstterm>
1439 of 255 which applies to bus names, interfaces, and members.
1441 <sect3 id="message-protocol-names-interface">
1442 <title>Interface names</title>
1444 Interfaces have names with type <literal>STRING</literal>, meaning that
1445 they must be valid UTF-8. However, there are also some
1446 additional restrictions that apply to interface names
1449 <listitem><para>Interface names are composed of 1 or more elements separated by
1450 a period ('.') character. All elements must contain at least
1454 <listitem><para>Each element must only contain the ASCII characters
1455 "[A-Z][a-z][0-9]_" and must not begin with a digit.
1459 <listitem><para>Interface names must contain at least one '.' (period)
1460 character (and thus at least two elements).
1463 <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
1464 <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
1469 Interface names should start with the reversed DNS domain name of
1470 the author of the interface (in lower-case), like interface names
1471 in Java. It is conventional for the rest of the interface name
1472 to consist of words run together, with initial capital letters
1473 on all words ("CamelCase"). Several levels of hierarchy can be used.
1474 It is also a good idea to include the major version of the interface
1475 in the name, and increment it if incompatible changes are made;
1476 this way, a single object can implement several versions of an
1477 interface in parallel, if necessary.
1481 For instance, if the owner of <literal>example.com</literal> is
1482 developing a D-Bus API for a music player, they might define
1483 interfaces called <literal>com.example.MusicPlayer1</literal>,
1484 <literal>com.example.MusicPlayer1.Track</literal> and
1485 <literal>com.example.MusicPlayer1.Seekable</literal>.
1489 D-Bus does not distinguish between the concepts that would be
1490 called classes and interfaces in Java: either can be identified on
1491 D-Bus by an interface name.
1494 <sect3 id="message-protocol-names-bus">
1495 <title>Bus names</title>
1497 Connections have one or more bus names associated with them.
1498 A connection has exactly one bus name that is a <firstterm>unique
1499 connection name</firstterm>. The unique connection name remains
1500 with the connection for its entire lifetime.
1501 A bus name is of type <literal>STRING</literal>,
1502 meaning that it must be valid UTF-8. However, there are also
1503 some additional restrictions that apply to bus names
1506 <listitem><para>Bus names that start with a colon (':')
1507 character are unique connection names. Other bus names
1508 are called <firstterm>well-known bus names</firstterm>.
1511 <listitem><para>Bus names are composed of 1 or more elements separated by
1512 a period ('.') character. All elements must contain at least
1516 <listitem><para>Each element must only contain the ASCII characters
1517 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
1518 connection name may begin with a digit, elements in
1519 other bus names must not begin with a digit.
1523 <listitem><para>Bus names must contain at least one '.' (period)
1524 character (and thus at least two elements).
1527 <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
1528 <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
1532 Note that the hyphen ('-') character is allowed in bus names but
1533 not in interface names.
1537 Like <link linkend="message-protocol-names-interface">interface
1538 names</link>, well-known bus names should start with the
1539 reversed DNS domain name of the author of the interface (in
1540 lower-case), and it is conventional for the rest of the well-known
1541 bus name to consist of words run together, with initial
1542 capital letters. As with interface names, including a version
1543 number in well-known bus names is a good idea; it's possible to
1544 have the well-known bus name for more than one version
1545 simultaneously if backwards compatibility is required.
1549 If a well-known bus name implies the presence of a "main" interface,
1550 that "main" interface is often given the same name as
1551 the well-known bus name, and situated at the corresponding object
1552 path. For instance, if the owner of <literal>example.com</literal>
1553 is developing a D-Bus API for a music player, they might define
1554 that any application that takes the well-known name
1555 <literal>com.example.MusicPlayer1</literal> should have an object
1556 at the object path <literal>/com/example/MusicPlayer1</literal>
1557 which implements the interface
1558 <literal>com.example.MusicPlayer1</literal>.
1561 <sect3 id="message-protocol-names-member">
1562 <title>Member names</title>
1564 Member (i.e. method or signal) names:
1566 <listitem><para>Must only contain the ASCII characters
1567 "[A-Z][a-z][0-9]_" and may not begin with a
1568 digit.</para></listitem>
1569 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1570 <listitem><para>Must not exceed the maximum name length.</para></listitem>
1571 <listitem><para>Must be at least 1 byte in length.</para></listitem>
1576 It is conventional for member names on D-Bus to consist of
1577 capitalized words with no punctuation ("camel-case").
1578 Method names should usually be verbs, such as
1579 <literal>GetItems</literal>, and signal names should usually be
1580 a description of an event, such as <literal>ItemsChanged</literal>.
1583 <sect3 id="message-protocol-names-error">
1584 <title>Error names</title>
1586 Error names have the same restrictions as interface names.
1590 Error names have the same naming conventions as interface
1591 names, and often contain <literal>.Error.</literal>; for instance,
1592 the owner of <literal>example.com</literal> might define the
1593 errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
1594 and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
1595 The errors defined by D-Bus itself, such as
1596 <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
1602 <sect2 id="message-protocol-types">
1603 <title>Message Types</title>
1605 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1606 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1607 This section describes these conventions.
1609 <sect3 id="message-protocol-types-method">
1610 <title>Method Calls</title>
1612 Some messages invoke an operation on a remote object. These are
1613 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1614 messages map naturally to methods on objects in a typical program.
1617 A method call message is required to have a <literal>MEMBER</literal> header field
1618 indicating the name of the method. Optionally, the message has an
1619 <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1620 absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1621 a method with the same name, it is undefined which of the two methods
1622 will be invoked. Implementations may also choose to return an error in
1623 this ambiguous case. However, if a method name is unique
1624 implementations must not require an interface field.
1627 Method call messages also include a <literal>PATH</literal> field
1628 indicating the object to invoke the method on. If the call is passing
1629 through a message bus, the message will also have a
1630 <literal>DESTINATION</literal> field giving the name of the connection
1631 to receive the message.
1634 When an application handles a method call message, it is required to
1635 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1636 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1637 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1640 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1641 are the return value(s) or "out parameters" of the method call.
1642 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1643 and the call fails; no return value will be provided. It makes
1644 no sense to send multiple replies to the same method call.
1647 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1648 reply is required, so the caller will know the method
1649 was successfully processed.
1652 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1656 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1657 then as an optimization the application receiving the method
1658 call may choose to omit the reply message (regardless of
1659 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1660 However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1661 flag and reply anyway.
1664 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1665 destination name does not exist then a program to own the destination
1666 name will be started before the message is delivered. The message
1667 will be held until the new program is successfully started or has
1668 failed to start; in case of failure, an error will be returned. This
1669 flag is only relevant in the context of a message bus, it is ignored
1670 during one-to-one communication with no intermediate bus.
1672 <sect4 id="message-protocol-types-method-apis">
1673 <title>Mapping method calls to native APIs</title>
1675 APIs for D-Bus may map method calls to a method call in a specific
1676 programming language, such as C++, or may map a method call written
1677 in an IDL to a D-Bus message.
1680 In APIs of this nature, arguments to a method are often termed "in"
1681 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1682 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1683 "inout" arguments, which are both sent and received, i.e. the caller
1684 passes in a value which is modified. Mapped to D-Bus, an "inout"
1685 argument is equivalent to an "in" argument, followed by an "out"
1686 argument. You can't pass things "by reference" over the wire, so
1687 "inout" is purely an illusion of the in-process API.
1690 Given a method with zero or one return values, followed by zero or more
1691 arguments, where each argument may be "in", "out", or "inout", the
1692 caller constructs a message by appending each "in" or "inout" argument,
1693 in order. "out" arguments are not represented in the caller's message.
1696 The recipient constructs a reply by appending first the return value
1697 if any, then each "out" or "inout" argument, in order.
1698 "in" arguments are not represented in the reply message.
1701 Error replies are normally mapped to exceptions in languages that have
1705 In converting from native APIs to D-Bus, it is perhaps nice to
1706 map D-Bus naming conventions ("FooBar") to native conventions
1707 such as "fooBar" or "foo_bar" automatically. This is OK
1708 as long as you can say that the native API is one that
1709 was specifically written for D-Bus. It makes the most sense
1710 when writing object implementations that will be exported
1711 over the bus. Object proxies used to invoke remote D-Bus
1712 objects probably need the ability to call any D-Bus method,
1713 and thus a magic name mapping like this could be a problem.
1716 This specification doesn't require anything of native API bindings;
1717 the preceding is only a suggested convention for consistency
1723 <sect3 id="message-protocol-types-signal">
1724 <title>Signal Emission</title>
1726 Unlike method calls, signal emissions have no replies.
1727 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1728 It must have three header fields: <literal>PATH</literal> giving the object
1729 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1730 the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
1731 for signals, though it is optional for method calls.
1735 <sect3 id="message-protocol-types-errors">
1736 <title>Errors</title>
1738 Messages of type <literal>ERROR</literal> are most commonly replies
1739 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1740 to any kind of message. The message bus for example
1741 will return an <literal>ERROR</literal> in reply to a signal emission if
1742 the bus does not have enough memory to send the signal.
1745 An <literal>ERROR</literal> may have any arguments, but if the first
1746 argument is a <literal>STRING</literal>, it must be an error message.
1747 The error message may be logged or shown to the user
1752 <sect3 id="message-protocol-types-notation">
1753 <title>Notation in this document</title>
1755 This document uses a simple pseudo-IDL to describe particular method
1756 calls and signals. Here is an example of a method call:
1758 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1759 out UINT32 resultcode)
1761 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1762 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1763 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1764 characters so it's known that the last part of the name in
1765 the "IDL" is the member name.
1768 In C++ that might end up looking like this:
1770 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1771 unsigned int flags);
1773 or equally valid, the return value could be done as an argument:
1775 void org::freedesktop::DBus::StartServiceByName (const char *name,
1777 unsigned int *resultcode);
1779 It's really up to the API designer how they want to make
1780 this look. You could design an API where the namespace wasn't used
1781 in C++, using STL or Qt, using varargs, or whatever you wanted.
1784 Signals are written as follows:
1786 org.freedesktop.DBus.NameLost (STRING name)
1788 Signals don't specify "in" vs. "out" because only
1789 a single direction is possible.
1792 It isn't especially encouraged to use this lame pseudo-IDL in actual
1793 API implementations; you might use the native notation for the
1794 language you're using, or you might use COM or CORBA IDL, for example.
1799 <sect2 id="message-protocol-handling-invalid">
1800 <title>Invalid Protocol and Spec Extensions</title>
1803 For security reasons, the D-Bus protocol should be strictly parsed and
1804 validated, with the exception of defined extension points. Any invalid
1805 protocol or spec violations should result in immediately dropping the
1806 connection without notice to the other end. Exceptions should be
1807 carefully considered, e.g. an exception may be warranted for a
1808 well-understood idiosyncrasy of a widely-deployed implementation. In
1809 cases where the other end of a connection is 100% trusted and known to
1810 be friendly, skipping validation for performance reasons could also make
1811 sense in certain cases.
1815 Generally speaking violations of the "must" requirements in this spec
1816 should be considered possible attempts to exploit security, and violations
1817 of the "should" suggestions should be considered legitimate (though perhaps
1818 they should generate an error in some cases).
1822 The following extension points are built in to D-Bus on purpose and must
1823 not be treated as invalid protocol. The extension points are intended
1824 for use by future versions of this spec, they are not intended for third
1825 parties. At the moment, the only way a third party could extend D-Bus
1826 without breaking interoperability would be to introduce a way to negotiate new
1827 feature support as part of the auth protocol, using EXTENSION_-prefixed
1828 commands. There is not yet a standard way to negotiate features.
1832 In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
1833 commands result in an ERROR rather than a disconnect. This enables
1834 future extensions to the protocol. Commands starting with EXTENSION_ are
1835 reserved for third parties.
1840 The authentication protocol supports pluggable auth mechanisms.
1845 The address format (see <xref linkend="addresses"/>) supports new
1851 Messages with an unknown type (something other than
1852 <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
1853 <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
1854 Unknown-type messages must still be well-formed in the same way
1855 as the known messages, however. They still have the normal
1861 Header fields with an unknown or unexpected field code must be ignored,
1862 though again they must still be well-formed.
1867 New standard interfaces (with new methods and signals) can of course be added.
1877 <sect1 id="auth-protocol">
1878 <title>Authentication Protocol</title>
1880 Before the flow of messages begins, two applications must
1881 authenticate. A simple plain-text protocol is used for
1882 authentication; this protocol is a SASL profile, and maps fairly
1883 directly from the SASL specification. The message encoding is
1884 NOT used here, only plain text messages.
1887 In examples, "C:" and "S:" indicate lines sent by the client and
1888 server respectively.
1890 <sect2 id="auth-protocol-overview">
1891 <title>Protocol Overview</title>
1893 The protocol is a line-based protocol, where each line ends with
1894 \r\n. Each line begins with an all-caps ASCII command name containing
1895 only the character range [A-Z_], a space, then any arguments for the
1896 command, then the \r\n ending the line. The protocol is
1897 case-sensitive. All bytes must be in the ASCII character set.
1899 Commands from the client to the server are as follows:
1902 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1903 <listitem><para>CANCEL</para></listitem>
1904 <listitem><para>BEGIN</para></listitem>
1905 <listitem><para>DATA <data in hex encoding></para></listitem>
1906 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1907 <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
1910 From server to client are as follows:
1913 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
1914 <listitem><para>OK <GUID in hex></para></listitem>
1915 <listitem><para>DATA <data in hex encoding></para></listitem>
1916 <listitem><para>ERROR</para></listitem>
1917 <listitem><para>AGREE_UNIX_FD</para></listitem>
1921 Unofficial extensions to the command set must begin with the letters
1922 "EXTENSION_", to avoid conflicts with future official commands.
1923 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
1926 <sect2 id="auth-nul-byte">
1927 <title>Special credentials-passing nul byte</title>
1929 Immediately after connecting to the server, the client must send a
1930 single nul byte. This byte may be accompanied by credentials
1931 information on some operating systems that use sendmsg() with
1932 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1933 sockets. However, the nul byte must be sent even on other kinds of
1934 socket, and even on operating systems that do not require a byte to be
1935 sent in order to transmit credentials. The text protocol described in
1936 this document begins after the single nul byte. If the first byte
1937 received from the client is not a nul byte, the server may disconnect
1941 A nul byte in any context other than the initial byte is an error;
1942 the protocol is ASCII-only.
1945 The credentials sent along with the nul byte may be used with the
1946 SASL mechanism EXTERNAL.
1949 <sect2 id="auth-command-auth">
1950 <title>AUTH command</title>
1952 If an AUTH command has no arguments, it is a request to list
1953 available mechanisms. The server must respond with a REJECTED
1954 command listing the mechanisms it understands, or with an error.
1957 If an AUTH command specifies a mechanism, and the server supports
1958 said mechanism, the server should begin exchanging SASL
1959 challenge-response data with the client using DATA commands.
1962 If the server does not support the mechanism given in the AUTH
1963 command, it must send either a REJECTED command listing the mechanisms
1964 it does support, or an error.
1967 If the [initial-response] argument is provided, it is intended for use
1968 with mechanisms that have no initial challenge (or an empty initial
1969 challenge), as if it were the argument to an initial DATA command. If
1970 the selected mechanism has an initial challenge and [initial-response]
1971 was provided, the server should reject authentication by sending
1975 If authentication succeeds after exchanging DATA commands,
1976 an OK command must be sent to the client.
1979 The first octet received by the server after the \r\n of the BEGIN
1980 command from the client must be the first octet of the
1981 authenticated/encrypted stream of D-Bus messages.
1984 If BEGIN is received by the server, the first octet received
1985 by the client after the \r\n of the OK command must be the
1986 first octet of the authenticated/encrypted stream of D-Bus
1990 <sect2 id="auth-command-cancel">
1991 <title>CANCEL Command</title>
1993 At any time up to sending the BEGIN command, the client may send a
1994 CANCEL command. On receiving the CANCEL command, the server must
1995 send a REJECTED command and abort the current authentication
1999 <sect2 id="auth-command-data">
2000 <title>DATA Command</title>
2002 The DATA command may come from either client or server, and simply
2003 contains a hex-encoded block of data to be interpreted
2004 according to the SASL mechanism in use.
2007 Some SASL mechanisms support sending an "empty string";
2008 FIXME we need some way to do this.
2011 <sect2 id="auth-command-begin">
2012 <title>BEGIN Command</title>
2014 The BEGIN command acknowledges that the client has received an
2015 OK command from the server, and that the stream of messages
2019 The first octet received by the server after the \r\n of the BEGIN
2020 command from the client must be the first octet of the
2021 authenticated/encrypted stream of D-Bus messages.
2024 <sect2 id="auth-command-rejected">
2025 <title>REJECTED Command</title>
2027 The REJECTED command indicates that the current authentication
2028 exchange has failed, and further exchange of DATA is inappropriate.
2029 The client would normally try another mechanism, or try providing
2030 different responses to challenges.
2032 Optionally, the REJECTED command has a space-separated list of
2033 available auth mechanisms as arguments. If a server ever provides
2034 a list of supported mechanisms, it must provide the same list
2035 each time it sends a REJECTED message. Clients are free to
2036 ignore all lists received after the first.
2039 <sect2 id="auth-command-ok">
2040 <title>OK Command</title>
2042 The OK command indicates that the client has been
2043 authenticated. The client may now proceed with negotiating
2044 Unix file descriptor passing. To do that it shall send
2045 NEGOTIATE_UNIX_FD to the server.
2048 Otherwise, the client must respond to the OK command by
2049 sending a BEGIN command, followed by its stream of messages,
2050 or by disconnecting. The server must not accept additional
2051 commands using this protocol after the BEGIN command has been
2052 received. Further communication will be a stream of D-Bus
2053 messages (optionally encrypted, as negotiated) rather than
2057 If a client sends BEGIN the first octet received by the client
2058 after the \r\n of the OK command must be the first octet of
2059 the authenticated/encrypted stream of D-Bus messages.
2062 The OK command has one argument, which is the GUID of the server.
2063 See <xref linkend="addresses"/> for more on server GUIDs.
2066 <sect2 id="auth-command-error">
2067 <title>ERROR Command</title>
2069 The ERROR command indicates that either server or client did not
2070 know a command, does not accept the given command in the current
2071 context, or did not understand the arguments to the command. This
2072 allows the protocol to be extended; a client or server can send a
2073 command present or permitted only in new protocol versions, and if
2074 an ERROR is received instead of an appropriate response, fall back
2075 to using some other technique.
2078 If an ERROR is sent, the server or client that sent the
2079 error must continue as if the command causing the ERROR had never been
2080 received. However, the the server or client receiving the error
2081 should try something other than whatever caused the error;
2082 if only canceling/rejecting the authentication.
2085 If the D-Bus protocol changes incompatibly at some future time,
2086 applications implementing the new protocol would probably be able to
2087 check for support of the new protocol by sending a new command and
2088 receiving an ERROR from applications that don't understand it. Thus the
2089 ERROR feature of the auth protocol is an escape hatch that lets us
2090 negotiate extensions or changes to the D-Bus protocol in the future.
2093 <sect2 id="auth-command-negotiate-unix-fd">
2094 <title>NEGOTIATE_UNIX_FD Command</title>
2096 The NEGOTIATE_UNIX_FD command indicates that the client
2097 supports Unix file descriptor passing. This command may only
2098 be sent after the connection is authenticated, i.e. after OK
2099 was received by the client. This command may only be sent on
2100 transports that support Unix file descriptor passing.
2103 On receiving NEGOTIATE_UNIX_FD the server must respond with
2104 either AGREE_UNIX_FD or ERROR. It shall respond the former if
2105 the transport chosen supports Unix file descriptor passing and
2106 the server supports this feature. It shall respond the latter
2107 if the transport does not support Unix file descriptor
2108 passing, the server does not support this feature, or the
2109 server decides not to enable file descriptor passing due to
2110 security or other reasons.
2113 <sect2 id="auth-command-agree-unix-fd">
2114 <title>AGREE_UNIX_FD Command</title>
2116 The AGREE_UNIX_FD command indicates that the server supports
2117 Unix file descriptor passing. This command may only be sent
2118 after the connection is authenticated, and the client sent
2119 NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
2120 command may only be sent on transports that support Unix file
2124 On receiving AGREE_UNIX_FD the client must respond with BEGIN,
2125 followed by its stream of messages, or by disconnecting. The
2126 server must not accept additional commands using this protocol
2127 after the BEGIN command has been received. Further
2128 communication will be a stream of D-Bus messages (optionally
2129 encrypted, as negotiated) rather than this protocol.
2132 <sect2 id="auth-command-future">
2133 <title>Future Extensions</title>
2135 Future extensions to the authentication and negotiation
2136 protocol are possible. For that new commands may be
2137 introduced. If a client or server receives an unknown command
2138 it shall respond with ERROR and not consider this fatal. New
2139 commands may be introduced both before, and after
2140 authentication, i.e. both before and after the OK command.
2143 <sect2 id="auth-examples">
2144 <title>Authentication examples</title>
2148 <title>Example of successful magic cookie authentication</title>
2150 (MAGIC_COOKIE is a made up mechanism)
2152 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2158 <title>Example of finding out mechanisms then picking one</title>
2161 S: REJECTED KERBEROS_V4 SKEY
2162 C: AUTH SKEY 7ab83f32ee
2163 S: DATA 8799cabb2ea93e
2164 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2170 <title>Example of client sends unknown command then falls back to regular auth</title>
2174 C: AUTH MAGIC_COOKIE 3736343435313230333039
2180 <title>Example of server doesn't support initial auth mechanism</title>
2182 C: AUTH MAGIC_COOKIE 3736343435313230333039
2183 S: REJECTED KERBEROS_V4 SKEY
2184 C: AUTH SKEY 7ab83f32ee
2185 S: DATA 8799cabb2ea93e
2186 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2192 <title>Example of wrong password or the like followed by successful retry</title>
2194 C: AUTH MAGIC_COOKIE 3736343435313230333039
2195 S: REJECTED KERBEROS_V4 SKEY
2196 C: AUTH SKEY 7ab83f32ee
2197 S: DATA 8799cabb2ea93e
2198 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2200 C: AUTH SKEY 7ab83f32ee
2201 S: DATA 8799cabb2ea93e
2202 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2208 <title>Example of skey cancelled and restarted</title>
2210 C: AUTH MAGIC_COOKIE 3736343435313230333039
2211 S: REJECTED KERBEROS_V4 SKEY
2212 C: AUTH SKEY 7ab83f32ee
2213 S: DATA 8799cabb2ea93e
2216 C: AUTH SKEY 7ab83f32ee
2217 S: DATA 8799cabb2ea93e
2218 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2224 <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
2226 (MAGIC_COOKIE is a made up mechanism)
2228 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2230 C: NEGOTIATE_UNIX_FD
2236 <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
2238 (MAGIC_COOKIE is a made up mechanism)
2240 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2242 C: NEGOTIATE_UNIX_FD
2249 <sect2 id="auth-states">
2250 <title>Authentication state diagrams</title>
2253 This section documents the auth protocol in terms of
2254 a state machine for the client and the server. This is
2255 probably the most robust way to implement the protocol.
2258 <sect3 id="auth-states-client">
2259 <title>Client states</title>
2262 To more precisely describe the interaction between the
2263 protocol state machine and the authentication mechanisms the
2264 following notation is used: MECH(CHALL) means that the
2265 server challenge CHALL was fed to the mechanism MECH, which
2271 CONTINUE(RESP) means continue the auth conversation
2272 and send RESP as the response to the server;
2278 OK(RESP) means that after sending RESP to the server
2279 the client side of the auth conversation is finished
2280 and the server should return "OK";
2286 ERROR means that CHALL was invalid and could not be
2292 Both RESP and CHALL may be empty.
2296 The Client starts by getting an initial response from the
2297 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
2298 the mechanism did not provide an initial response. If the
2299 mechanism returns CONTINUE, the client starts in state
2300 <emphasis>WaitingForData</emphasis>, if the mechanism
2301 returns OK the client starts in state
2302 <emphasis>WaitingForOK</emphasis>.
2306 The client should keep track of available mechanisms and
2307 which it mechanisms it has already attempted. This list is
2308 used to decide which AUTH command to send. When the list is
2309 exhausted, the client should give up and close the
2314 <title><emphasis>WaitingForData</emphasis></title>
2322 MECH(CHALL) returns CONTINUE(RESP) → send
2324 <emphasis>WaitingForData</emphasis>
2328 MECH(CHALL) returns OK(RESP) → send DATA
2329 RESP, goto <emphasis>WaitingForOK</emphasis>
2333 MECH(CHALL) returns ERROR → send ERROR
2334 [msg], goto <emphasis>WaitingForData</emphasis>
2342 Receive REJECTED [mechs] →
2343 send AUTH [next mech], goto
2344 WaitingForData or <emphasis>WaitingForOK</emphasis>
2349 Receive ERROR → send
2351 <emphasis>WaitingForReject</emphasis>
2356 Receive OK → send
2357 BEGIN, terminate auth
2358 conversation, authenticated
2363 Receive anything else → send
2365 <emphasis>WaitingForData</emphasis>
2373 <title><emphasis>WaitingForOK</emphasis></title>
2378 Receive OK → send BEGIN, terminate auth
2379 conversation, <emphasis>authenticated</emphasis>
2384 Receive REJECT [mechs] → send AUTH [next mech],
2385 goto <emphasis>WaitingForData</emphasis> or
2386 <emphasis>WaitingForOK</emphasis>
2392 Receive DATA → send CANCEL, goto
2393 <emphasis>WaitingForReject</emphasis>
2399 Receive ERROR → send CANCEL, goto
2400 <emphasis>WaitingForReject</emphasis>
2406 Receive anything else → send ERROR, goto
2407 <emphasis>WaitingForOK</emphasis>
2415 <title><emphasis>WaitingForReject</emphasis></title>
2420 Receive REJECT [mechs] → send AUTH [next mech],
2421 goto <emphasis>WaitingForData</emphasis> or
2422 <emphasis>WaitingForOK</emphasis>
2428 Receive anything else → terminate auth
2429 conversation, disconnect
2438 <sect3 id="auth-states-server">
2439 <title>Server states</title>
2442 For the server MECH(RESP) means that the client response
2443 RESP was fed to the the mechanism MECH, which returns one of
2448 CONTINUE(CHALL) means continue the auth conversation and
2449 send CHALL as the challenge to the client;
2455 OK means that the client has been successfully
2462 REJECT means that the client failed to authenticate or
2463 there was an error in RESP.
2468 The server starts out in state
2469 <emphasis>WaitingForAuth</emphasis>. If the client is
2470 rejected too many times the server must disconnect the
2475 <title><emphasis>WaitingForAuth</emphasis></title>
2481 Receive AUTH → send REJECTED [mechs], goto
2482 <emphasis>WaitingForAuth</emphasis>
2488 Receive AUTH MECH RESP
2492 MECH not valid mechanism → send REJECTED
2494 <emphasis>WaitingForAuth</emphasis>
2498 MECH(RESP) returns CONTINUE(CHALL) → send
2500 <emphasis>WaitingForData</emphasis>
2504 MECH(RESP) returns OK → send OK, goto
2505 <emphasis>WaitingForBegin</emphasis>
2509 MECH(RESP) returns REJECT → send REJECTED
2511 <emphasis>WaitingForAuth</emphasis>
2519 Receive BEGIN → terminate
2520 auth conversation, disconnect
2526 Receive ERROR → send REJECTED [mechs], goto
2527 <emphasis>WaitingForAuth</emphasis>
2533 Receive anything else → send
2535 <emphasis>WaitingForAuth</emphasis>
2544 <title><emphasis>WaitingForData</emphasis></title>
2552 MECH(RESP) returns CONTINUE(CHALL) → send
2554 <emphasis>WaitingForData</emphasis>
2558 MECH(RESP) returns OK → send OK, goto
2559 <emphasis>WaitingForBegin</emphasis>
2563 MECH(RESP) returns REJECT → send REJECTED
2565 <emphasis>WaitingForAuth</emphasis>
2573 Receive BEGIN → terminate auth conversation,
2580 Receive CANCEL → send REJECTED [mechs], goto
2581 <emphasis>WaitingForAuth</emphasis>
2587 Receive ERROR → send REJECTED [mechs], goto
2588 <emphasis>WaitingForAuth</emphasis>
2594 Receive anything else → send ERROR, goto
2595 <emphasis>WaitingForData</emphasis>
2603 <title><emphasis>WaitingForBegin</emphasis></title>
2608 Receive BEGIN → terminate auth conversation,
2609 client authenticated
2615 Receive CANCEL → send REJECTED [mechs], goto
2616 <emphasis>WaitingForAuth</emphasis>
2622 Receive ERROR → send REJECTED [mechs], goto
2623 <emphasis>WaitingForAuth</emphasis>
2629 Receive anything else → send ERROR, goto
2630 <emphasis>WaitingForBegin</emphasis>
2640 <sect2 id="auth-mechanisms">
2641 <title>Authentication mechanisms</title>
2643 This section describes some new authentication mechanisms.
2644 D-Bus also allows any standard SASL mechanism of course.
2646 <sect3 id="auth-mechanisms-sha">
2647 <title>DBUS_COOKIE_SHA1</title>
2649 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
2650 has the ability to read a private file owned by the user being
2651 authenticated. If the client can prove that it has access to a secret
2652 cookie stored in this file, then the client is authenticated.
2653 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
2657 Throughout this description, "hex encoding" must output the digits
2658 from a to f in lower-case; the digits A to F must not be used
2659 in the DBUS_COOKIE_SHA1 mechanism.
2662 Authentication proceeds as follows:
2666 The client sends the username it would like to authenticate
2672 The server sends the name of its "cookie context" (see below); a
2673 space character; the integer ID of the secret cookie the client
2674 must demonstrate knowledge of; a space character; then a
2675 randomly-generated challenge string, all of this hex-encoded into
2681 The client locates the cookie and generates its own
2682 randomly-generated challenge string. The client then concatenates
2683 the server's decoded challenge, a ":" character, its own challenge,
2684 another ":" character, and the cookie. It computes the SHA-1 hash
2685 of this composite string as a hex digest. It concatenates the
2686 client's challenge string, a space character, and the SHA-1 hex
2687 digest, hex-encodes the result and sends it back to the server.
2692 The server generates the same concatenated string used by the
2693 client and computes its SHA-1 hash. It compares the hash with
2694 the hash received from the client; if the two hashes match, the
2695 client is authenticated.
2701 Each server has a "cookie context," which is a name that identifies a
2702 set of cookies that apply to that server. A sample context might be
2703 "org_freedesktop_session_bus". Context names must be valid ASCII,
2704 nonzero length, and may not contain the characters slash ("/"),
2705 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
2706 tab ("\t"), or period ("."). There is a default context,
2707 "org_freedesktop_general" that's used by servers that do not specify
2711 Cookies are stored in a user's home directory, in the directory
2712 <filename>~/.dbus-keyrings/</filename>. This directory must
2713 not be readable or writable by other users. If it is,
2714 clients and servers must ignore it. The directory
2715 contains cookie files named after the cookie context.
2718 A cookie file contains one cookie per line. Each line
2719 has three space-separated fields:
2723 The cookie ID number, which must be a non-negative integer and
2724 may not be used twice in the same file.
2729 The cookie's creation time, in UNIX seconds-since-the-epoch
2735 The cookie itself, a hex-encoded random block of bytes. The cookie
2736 may be of any length, though obviously security increases
2737 as the length increases.
2743 Only server processes modify the cookie file.
2744 They must do so with this procedure:
2748 Create a lockfile name by appending ".lock" to the name of the
2749 cookie file. The server should attempt to create this file
2750 using <literal>O_CREAT | O_EXCL</literal>. If file creation
2751 fails, the lock fails. Servers should retry for a reasonable
2752 period of time, then they may choose to delete an existing lock
2753 to keep users from having to manually delete a stale
2754 lock. <footnote><para>Lockfiles are used instead of real file
2755 locking <literal>fcntl()</literal> because real locking
2756 implementations are still flaky on network
2757 filesystems.</para></footnote>
2762 Once the lockfile has been created, the server loads the cookie
2763 file. It should then delete any cookies that are old (the
2764 timeout can be fairly short), or more than a reasonable
2765 time in the future (so that cookies never accidentally
2766 become permanent, if the clock was set far into the future
2767 at some point). If no recent keys remain, the
2768 server may generate a new key.
2773 The pruned and possibly added-to cookie file
2774 must be resaved atomically (using a temporary
2775 file which is rename()'d).
2780 The lock must be dropped by deleting the lockfile.
2786 Clients need not lock the file in order to load it,
2787 because servers are required to save the file atomically.
2792 <sect1 id="addresses">
2793 <title>Server Addresses</title>
2795 Server addresses consist of a transport name followed by a colon, and
2796 then an optional, comma-separated list of keys and values in the form key=value.
2797 Each value is escaped.
2801 <programlisting>unix:path=/tmp/dbus-test</programlisting>
2802 Which is the address to a unix socket with the path /tmp/dbus-test.
2805 Value escaping is similar to URI escaping but simpler.
2809 The set of optionally-escaped bytes is:
2810 <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
2811 <emphasis>byte</emphasis> (note, not character) which is not in the
2812 set of optionally-escaped bytes must be replaced with an ASCII
2813 percent (<literal>%</literal>) and the value of the byte in hex.
2814 The hex value must always be two digits, even if the first digit is
2815 zero. The optionally-escaped bytes may be escaped if desired.
2820 To unescape, append each byte in the value; if a byte is an ASCII
2821 percent (<literal>%</literal>) character then append the following
2822 hex value instead. It is an error if a <literal>%</literal> byte
2823 does not have two hex digits following. It is an error if a
2824 non-optionally-escaped byte is seen unescaped.
2828 The set of optionally-escaped bytes is intended to preserve address
2829 readability and convenience.
2833 A server may specify a key-value pair with the key <literal>guid</literal>
2834 and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
2835 describes the format of the <literal>guid</literal> field. If present,
2836 this UUID may be used to distinguish one server address from another. A
2837 server should use a different UUID for each address it listens on. For
2838 example, if a message bus daemon offers both UNIX domain socket and TCP
2839 connections, but treats clients the same regardless of how they connect,
2840 those two connections are equivalent post-connection but should have
2841 distinct UUIDs to distinguish the kinds of connection.
2845 The intent of the address UUID feature is to allow a client to avoid
2846 opening multiple identical connections to the same server, by allowing the
2847 client to check whether an address corresponds to an already-existing
2848 connection. Comparing two addresses is insufficient, because addresses
2849 can be recycled by distinct servers, and equivalent addresses may look
2850 different if simply compared as strings (for example, the host in a TCP
2851 address can be given as an IP address or as a hostname).
2855 Note that the address key is <literal>guid</literal> even though the
2856 rest of the API and documentation says "UUID," for historical reasons.
2860 [FIXME clarify if attempting to connect to each is a requirement
2861 or just a suggestion]
2862 When connecting to a server, multiple server addresses can be
2863 separated by a semi-colon. The library will then try to connect
2864 to the first address and if that fails, it'll try to connect to
2865 the next one specified, and so forth. For example
2866 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2871 <sect1 id="transports">
2872 <title>Transports</title>
2874 [FIXME we need to specify in detail each transport and its possible arguments]
2876 Current transports include: unix domain sockets (including
2877 abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
2878 using in-process pipes. Future possible transports include one that
2879 tunnels over X11 protocol.
2882 <sect2 id="transports-unix-domain-sockets">
2883 <title>Unix Domain Sockets</title>
2885 Unix domain sockets can be either paths in the file system or on Linux
2886 kernels, they can be abstract which are similar to paths but
2887 do not show up in the file system.
2891 When a socket is opened by the D-Bus library it truncates the path
2892 name right before the first trailing Nul byte. This is true for both
2893 normal paths and abstract paths. Note that this is a departure from
2894 previous versions of D-Bus that would create sockets with a fixed
2895 length path name. Names which were shorter than the fixed length
2896 would be padded by Nul bytes.
2899 Unix domain sockets are not available on Windows.
2901 <sect3 id="transports-unix-domain-sockets-addresses">
2902 <title>Server Address Format</title>
2904 Unix domain socket addresses are identified by the "unix:" prefix
2905 and support the following key/value pairs:
2912 <entry>Values</entry>
2913 <entry>Description</entry>
2919 <entry>(path)</entry>
2920 <entry>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</entry>
2923 <entry>tmpdir</entry>
2924 <entry>(path)</entry>
2925 <entry>temporary directory in which a socket file with a random file name starting with 'dbus-' will be created by the server. This key can only be used in server addresses, not in client addresses. If set, the "path" and "abstract" key must not be set.</entry>
2928 <entry>abstract</entry>
2929 <entry>(string)</entry>
2930 <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</entry>
2937 <sect2 id="transports-launchd">
2938 <title>launchd</title>
2940 launchd is an open-source server management system that replaces init, inetd
2941 and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
2942 bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
2946 launchd allocates a socket and provides it with the unix path through the
2947 DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
2948 spawned by launchd (or dbus-daemon, if it was started by launchd) can access
2949 it through its environment.
2950 Other processes can query for the launchd socket by executing:
2951 $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
2952 This is normally done by the D-Bus client library so doesn't have to be done
2956 launchd is not available on Microsoft Windows.
2958 <sect3 id="transports-launchd-addresses">
2959 <title>Server Address Format</title>
2961 launchd addresses are identified by the "launchd:" prefix
2962 and support the following key/value pairs:
2969 <entry>Values</entry>
2970 <entry>Description</entry>
2976 <entry>(environment variable)</entry>
2977 <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
2984 <sect2 id="transports-systemd">
2985 <title>systemd</title>
2987 systemd is an open-source server management system that
2988 replaces init and inetd on newer Linux systems. It supports
2989 socket activation. The D-Bus systemd transport is used to acquire
2990 socket activation file descriptors from systemd and use them
2991 as D-Bus transport when the current process is spawned by
2992 socket activation from it.
2995 The systemd transport accepts only one or more Unix domain or
2996 TCP streams sockets passed in via socket activation.
2999 The systemd transport is not available on non-Linux operating systems.
3002 The systemd transport defines no parameter keys.
3005 <sect2 id="transports-tcp-sockets">
3006 <title>TCP Sockets</title>
3008 The tcp transport provides TCP/IP based connections between clients
3009 located on the same or different hosts.
3012 Using tcp transport without any additional secure authentification mechanismus
3013 over a network is unsecure.
3016 Windows notes: Because of the tcp stack on Windows does not provide sending
3017 credentials over a tcp connection, the EXTERNAL authentification
3018 mechanismus does not work.
3020 <sect3 id="transports-tcp-sockets-addresses">
3021 <title>Server Address Format</title>
3023 TCP/IP socket addresses are identified by the "tcp:" prefix
3024 and support the following key/value pairs:
3031 <entry>Values</entry>
3032 <entry>Description</entry>
3038 <entry>(string)</entry>
3039 <entry>dns name or ip address</entry>
3043 <entry>(number)</entry>
3044 <entry>The tcp port the server will open. A zero value let the server
3045 choose a free port provided from the underlaying operating system.
3046 libdbus is able to retrieve the real used port from the server.
3050 <entry>family</entry>
3051 <entry>(string)</entry>
3052 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3059 <sect2 id="transports-nonce-tcp-sockets">
3060 <title>Nonce-secured TCP Sockets</title>
3062 The nonce-tcp transport provides a secured TCP transport, using a
3063 simple authentication mechanism to ensure that only clients with read
3064 access to a certain location in the filesystem can connect to the server.
3065 The server writes a secret, the nonce, to a file and an incoming client
3066 connection is only accepted if the client sends the nonce right after
3067 the connect. The nonce mechanism requires no setup and is orthogonal to
3068 the higher-level authentication mechanisms described in the
3069 Authentication section.
3073 On start, the server generates a random 16 byte nonce and writes it
3074 to a file in the user's temporary directory. The nonce file location
3075 is published as part of the server's D-Bus address using the
3076 "noncefile" key-value pair.
3078 After an accept, the server reads 16 bytes from the socket. If the
3079 read bytes do not match the nonce stored in the nonce file, the
3080 server MUST immediately drop the connection.
3081 If the nonce match the received byte sequence, the client is accepted
3082 and the transport behaves like an unsecured tcp transport.
3085 After a successful connect to the server socket, the client MUST read
3086 the nonce from the file published by the server via the noncefile=
3087 key-value pair and send it over the socket. After that, the
3088 transport behaves like an unsecured tcp transport.
3090 <sect3 id="transports-nonce-tcp-sockets-addresses">
3091 <title>Server Address Format</title>
3093 Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
3094 and support the following key/value pairs:
3101 <entry>Values</entry>
3102 <entry>Description</entry>
3108 <entry>(string)</entry>
3109 <entry>dns name or ip address</entry>
3113 <entry>(number)</entry>
3114 <entry>The tcp port the server will open. A zero value let the server
3115 choose a free port provided from the underlaying operating system.
3116 libdbus is able to retrieve the real used port from the server.
3120 <entry>family</entry>
3121 <entry>(string)</entry>
3122 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3125 <entry>noncefile</entry>
3126 <entry>(path)</entry>
3127 <entry>file location containing the secret</entry>
3134 <sect2 id="transports-exec">
3135 <title>Executed Subprocesses on Unix</title>
3137 This transport forks off a process and connects its standard
3138 input and standard output with an anonymous Unix domain
3139 socket. This socket is then used for communication by the
3140 transport. This transport may be used to use out-of-process
3141 forwarder programs as basis for the D-Bus protocol.
3144 The forked process will inherit the standard error output and
3145 process group from the parent process.
3148 Executed subprocesses are not available on Windows.
3150 <sect3 id="transports-exec-addresses">
3151 <title>Server Address Format</title>
3153 Executed subprocess addresses are identified by the "unixexec:" prefix
3154 and support the following key/value pairs:
3161 <entry>Values</entry>
3162 <entry>Description</entry>
3168 <entry>(path)</entry>
3169 <entry>Path of the binary to execute, either an absolute
3170 path or a binary name that is searched for in the default
3171 search path of the OS. This corresponds to the first
3172 argument of execlp(). This key is mandatory.</entry>
3175 <entry>argv0</entry>
3176 <entry>(string)</entry>
3177 <entry>The program name to use when executing the
3178 binary. If omitted the same value as specified for path=
3179 will be used. This corresponds to the second argument of
3183 <entry>argv1, argv2, ...</entry>
3184 <entry>(string)</entry>
3185 <entry>Arguments to pass to the binary. This corresponds
3186 to the third and later arguments of execlp(). If a
3187 specific argvX is not specified no further argvY for Y > X
3188 are taken into account.</entry>
3196 <sect1 id="meta-transports">
3197 <title>Meta Transports</title>
3199 Meta transports are a kind of transport with special enhancements or
3200 behavior. Currently available meta transports include: autolaunch
3203 <sect2 id="meta-transports-autolaunch">
3204 <title>Autolaunch</title>
3205 <para>The autolaunch transport provides a way for dbus clients to autodetect
3206 a running dbus session bus and to autolaunch a session bus if not present.
3208 <sect3 id="meta-transports-autolaunch-addresses">
3209 <title>Server Address Format</title>
3211 Autolaunch addresses uses the "autolaunch:" prefix and support the
3212 following key/value pairs:
3219 <entry>Values</entry>
3220 <entry>Description</entry>
3225 <entry>scope</entry>
3226 <entry>(string)</entry>
3227 <entry>scope of autolaunch (Windows only)
3231 "*install-path" - limit session bus to dbus installation path.
3232 The dbus installation path is determined from the location of
3233 the shared dbus library. If the library is located in a 'bin'
3234 subdirectory the installation root is the directory above,
3235 otherwise the directory where the library lives is taken as
3238 <install-root>/bin/[lib]dbus-1.dll
3239 <install-root>/[lib]dbus-1.dll
3245 "*user" - limit session bus to the recent user.
3250 other values - specify dedicated session bus like "release",
3262 <sect3 id="meta-transports-autolaunch-windows-implementation">
3263 <title>Windows implementation</title>
3265 On start, the server opens a platform specific transport, creates a mutex
3266 and a shared memory section containing the related session bus address.
3267 This mutex will be inspected by the dbus client library to detect a
3268 running dbus session bus. The access to the mutex and the shared memory
3269 section are protected by global locks.
3272 In the recent implementation the autolaunch transport uses a tcp transport
3273 on localhost with a port choosen from the operating system. This detail may
3274 change in the future.
3277 Disclaimer: The recent implementation is in an early state and may not
3278 work in all cirumstances and/or may have security issues. Because of this
3279 the implementation is not documentated yet.
3286 <title>UUIDs</title>
3288 A working D-Bus implementation uses universally-unique IDs in two places.
3289 First, each server address has a UUID identifying the address,
3290 as described in <xref linkend="addresses"/>. Second, each operating
3291 system kernel instance running a D-Bus client or server has a UUID
3292 identifying that kernel, retrieved by invoking the method
3293 org.freedesktop.DBus.Peer.GetMachineId() (see <xref
3294 linkend="standard-interfaces-peer"/>).
3297 The term "UUID" in this document is intended literally, i.e. an
3298 identifier that is universally unique. It is not intended to refer to
3299 RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
3302 The UUID must contain 128 bits of data and be hex-encoded. The
3303 hex-encoded string may not contain hyphens or other non-hex-digit
3304 characters, and it must be exactly 32 characters long. To generate a
3305 UUID, the current reference implementation concatenates 96 bits of random
3306 data followed by the 32-bit time in seconds since the UNIX epoch (in big
3310 It would also be acceptable and probably better to simply generate 128
3311 bits of random data, as long as the random number generator is of high
3312 quality. The timestamp could conceivably help if the random bits are not
3313 very random. With a quality random number generator, collisions are
3314 extremely unlikely even with only 96 bits, so it's somewhat academic.
3317 Implementations should, however, stick to random data for the first 96 bits
3322 <sect1 id="standard-interfaces">
3323 <title>Standard Interfaces</title>
3325 See <xref linkend="message-protocol-types-notation"/> for details on
3326 the notation used in this section. There are some standard interfaces
3327 that may be useful across various D-Bus applications.
3329 <sect2 id="standard-interfaces-peer">
3330 <title><literal>org.freedesktop.DBus.Peer</literal></title>
3332 The <literal>org.freedesktop.DBus.Peer</literal> interface
3335 org.freedesktop.DBus.Peer.Ping ()
3336 org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
3340 On receipt of the <literal>METHOD_CALL</literal> message
3341 <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
3342 nothing other than reply with a <literal>METHOD_RETURN</literal> as
3343 usual. It does not matter which object path a ping is sent to. The
3344 reference implementation handles this method automatically.
3347 On receipt of the <literal>METHOD_CALL</literal> message
3348 <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
3349 reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
3350 UUID representing the identity of the machine the process is running on.
3351 This UUID must be the same for all processes on a single system at least
3352 until that system next reboots. It should be the same across reboots
3353 if possible, but this is not always possible to implement and is not
3355 It does not matter which object path a GetMachineId is sent to. The
3356 reference implementation handles this method automatically.
3359 The UUID is intended to be per-instance-of-the-operating-system, so may represent
3360 a virtual machine running on a hypervisor, rather than a physical machine.
3361 Basically if two processes see the same UUID, they should also see the same
3362 shared memory, UNIX domain sockets, process IDs, and other features that require
3363 a running OS kernel in common between the processes.
3366 The UUID is often used where other programs might use a hostname. Hostnames
3367 can change without rebooting, however, or just be "localhost" - so the UUID
3371 <xref linkend="uuids"/> explains the format of the UUID.
3375 <sect2 id="standard-interfaces-introspectable">
3376 <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
3378 This interface has one method:
3380 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
3384 Objects instances may implement
3385 <literal>Introspect</literal> which returns an XML description of
3386 the object, including its interfaces (with signals and methods), objects
3387 below it in the object path tree, and its properties.
3390 <xref linkend="introspection-format"/> describes the format of this XML string.
3393 <sect2 id="standard-interfaces-properties">
3394 <title><literal>org.freedesktop.DBus.Properties</literal></title>
3396 Many native APIs will have a concept of object <firstterm>properties</firstterm>
3397 or <firstterm>attributes</firstterm>. These can be exposed via the
3398 <literal>org.freedesktop.DBus.Properties</literal> interface.
3402 org.freedesktop.DBus.Properties.Get (in STRING interface_name,
3403 in STRING property_name,
3405 org.freedesktop.DBus.Properties.Set (in STRING interface_name,
3406 in STRING property_name,
3408 org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
3409 out DICT<STRING,VARIANT> props);
3413 It is conventional to give D-Bus properties names consisting of
3414 capitalized words without punctuation ("CamelCase"), like
3415 <link linkend="message-protocol-names-member">member names</link>.
3416 For instance, the GObject property
3417 <literal>connection-status</literal> or the Qt property
3418 <literal>connectionStatus</literal> could be represented on D-Bus
3419 as <literal>ConnectionStatus</literal>.
3422 Strictly speaking, D-Bus property names are not required to follow
3423 the same naming restrictions as member names, but D-Bus property
3424 names that would not be valid member names (in particular,
3425 GObject-style dash-separated property names) can cause interoperability
3426 problems and should be avoided.
3429 The available properties and whether they are writable can be determined
3430 by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
3431 see <xref linkend="standard-interfaces-introspectable"/>.
3434 An empty string may be provided for the interface name; in this case,
3435 if there are multiple properties on an object with the same name,
3436 the results are undefined (picking one by according to an arbitrary
3437 deterministic rule, or returning an error, are the reasonable
3441 If one or more properties change on an object, the
3442 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3443 signal may be emitted (this signal was added in 0.14):
3447 org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
3448 DICT<STRING,VARIANT> changed_properties,
3449 ARRAY<STRING> invalidated_properties);
3453 where <literal>changed_properties</literal> is a dictionary
3454 containing the changed properties with the new values and
3455 <literal>invalidated_properties</literal> is an array of
3456 properties that changed but the value is not conveyed.
3459 Whether the <literal>PropertiesChanged</literal> signal is
3460 supported can be determined by calling
3461 <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
3462 that the signal may be supported for an object but it may
3463 differ how whether and how it is used on a per-property basis
3464 (for e.g. performance or security reasons). Each property (or
3465 the parent interface) must be annotated with the
3466 <literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
3467 annotation to convey this (usually the default value
3468 <literal>true</literal> is sufficient meaning that the
3469 annotation does not need to be used). See <xref
3470 linkend="introspection-format"/> for details on this
3475 <sect2 id="standard-interfaces-objectmanager">
3476 <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
3478 An API can optionally make use of this interface for one or
3479 more sub-trees of objects. The root of each sub-tree implements
3480 this interface so other applications can get all objects,
3481 interfaces and properties in a single method call. It is
3482 appropriate to use this interface if users of the tree of
3483 objects are expected to be interested in all interfaces of all
3484 objects in the tree; a more granular API should be used if
3485 users of the objects are expected to be interested in a small
3486 subset of the objects, a small subset of their interfaces, or
3490 The method that applications can use to get all objects and
3491 properties is <literal>GetManagedObjects</literal>:
3495 org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties);
3499 The return value of this method is a dict whose keys are
3500 object paths. All returned object paths are children of the
3501 object path implementing this interface, i.e. their object
3502 paths start with the ObjectManager's object path plus '/'.
3505 Each value is a dict whose keys are interfaces names. Each
3506 value in this inner dict is the same dict that would be
3507 returned by the <link
3508 linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
3509 method for that combination of object path and interface. If
3510 an interface has no properties, the empty dict is returned.
3513 Changes are emitted using the following two signals:
3517 org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
3518 DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties);
3519 org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
3520 ARRAY<STRING> interfaces);
3524 The <literal>InterfacesAdded</literal> signal is emitted when
3525 either a new object is added or when an existing object gains
3526 one or more interfaces. The
3527 <literal>InterfacesRemoved</literal> signal is emitted
3528 whenever an object is removed or it loses one or more
3529 interfaces. The second parameter of the
3530 <literal>InterfacesAdded</literal> signal contains a dict with
3531 the interfaces and properties (if any) that have been added to
3532 the given object path. Similarly, the second parameter of the
3533 <literal>InterfacesRemoved</literal> signal contains an array
3534 of the interfaces that were removed. Note that changes on
3535 properties on existing interfaces are not reported using this
3536 interface - an application should also monitor the existing <link
3537 linkend="standard-interfaces-properties">PropertiesChanged</link>
3538 signal on each object.
3541 Applications SHOULD NOT export objects that are children of an
3542 object (directly or otherwise) implementing this interface but
3543 which are not returned in the reply from the
3544 <literal>GetManagedObjects()</literal> method of this
3545 interface on the given object.
3548 The intent of the <literal>ObjectManager</literal> interface
3549 is to make it easy to write a robust client
3550 implementation. The trivial client implementation only needs
3551 to make two method calls:
3555 org.freedesktop.DBus.AddMatch (bus_proxy,
3556 "type='signal',name='org.example.App',path_namespace='/org/example/App'");
3557 objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
3561 on the message bus and the remote application's
3562 <literal>ObjectManager</literal>, respectively. Whenever a new
3563 remote object is created (or an existing object gains a new
3564 interface), the <literal>InterfacesAdded</literal> signal is
3565 emitted, and since this signal contains all properties for the
3566 interfaces, no calls to the
3567 <literal>org.freedesktop.Properties</literal> interface on the
3568 remote object are needed. Additionally, since the initial
3569 <literal>AddMatch()</literal> rule already includes signal
3570 messages from the newly created child object, no new
3571 <literal>AddMatch()</literal> call is needed.
3576 The <literal>org.freedesktop.DBus.ObjectManager</literal>
3577 interface was added in version 0.17 of the D-Bus
3584 <sect1 id="introspection-format">
3585 <title>Introspection Data Format</title>
3587 As described in <xref linkend="standard-interfaces-introspectable"/>,
3588 objects may be introspected at runtime, returning an XML string
3589 that describes the object. The same XML format may be used in
3590 other contexts as well, for example as an "IDL" for generating
3591 static language bindings.
3594 Here is an example of introspection data:
3596 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
3597 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
3598 <node name="/org/freedesktop/sample_object">
3599 <interface name="org.freedesktop.SampleInterface">
3600 <method name="Frobate">
3601 <arg name="foo" type="i" direction="in"/>
3602 <arg name="bar" type="s" direction="out"/>
3603 <arg name="baz" type="a{us}" direction="out"/>
3604 <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
3606 <method name="Bazify">
3607 <arg name="bar" type="(iiu)" direction="in"/>
3608 <arg name="bar" type="v" direction="out"/>
3610 <method name="Mogrify">
3611 <arg name="bar" type="(iiav)" direction="in"/>
3613 <signal name="Changed">
3614 <arg name="new_value" type="b"/>
3616 <property name="Bar" type="y" access="readwrite"/>
3618 <node name="child_of_sample_object"/>
3619 <node name="another_child_of_sample_object"/>
3624 A more formal DTD and spec needs writing, but here are some quick notes.
3628 Only the root <node> element can omit the node name, as it's
3629 known to be the object that was introspected. If the root
3630 <node> does have a name attribute, it must be an absolute
3631 object path. If child <node> have object paths, they must be
3637 If a child <node> has any sub-elements, then they
3638 must represent a complete introspection of the child.
3639 If a child <node> is empty, then it may or may
3640 not have sub-elements; the child must be introspected
3641 in order to find out. The intent is that if an object
3642 knows that its children are "fast" to introspect
3643 it can go ahead and return their information, but
3644 otherwise it can omit it.
3649 The direction element on <arg> may be omitted,
3650 in which case it defaults to "in" for method calls
3651 and "out" for signals. Signals only allow "out"
3652 so while direction may be specified, it's pointless.
3657 The possible directions are "in" and "out",
3658 unlike CORBA there is no "inout"
3663 The possible property access flags are
3664 "readwrite", "read", and "write"
3669 Multiple interfaces can of course be listed for
3675 The "name" attribute on arguments is optional.
3681 Method, interface, property, and signal elements may have
3682 "annotations", which are generic key/value pairs of metadata.
3683 They are similar conceptually to Java's annotations and C# attributes.
3684 Well-known annotations:
3691 <entry>Values (separated by ,)</entry>
3692 <entry>Description</entry>
3697 <entry>org.freedesktop.DBus.Deprecated</entry>
3698 <entry>true,false</entry>
3699 <entry>Whether or not the entity is deprecated; defaults to false</entry>
3702 <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
3703 <entry>(string)</entry>
3704 <entry>The C symbol; may be used for methods and interfaces</entry>
3707 <entry>org.freedesktop.DBus.Method.NoReply</entry>
3708 <entry>true,false</entry>
3709 <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
3712 <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
3713 <entry>true,invalidates,false</entry>
3716 If set to <literal>false</literal>, the
3717 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3719 linkend="standard-interfaces-properties"/> is not
3720 guaranteed to be emitted if the property changes.
3723 If set to <literal>invalidates</literal> the signal
3724 is emitted but the value is not included in the
3728 If set to <literal>true</literal> the signal is
3729 emitted with the value included.
3732 The value for the annotation defaults to
3733 <literal>true</literal> if the enclosing interface
3734 element does not specify the annotation. Otherwise it
3735 defaults to the value specified in the enclosing
3744 <sect1 id="message-bus">
3745 <title>Message Bus Specification</title>
3746 <sect2 id="message-bus-overview">
3747 <title>Message Bus Overview</title>
3749 The message bus accepts connections from one or more applications.
3750 Once connected, applications can exchange messages with other
3751 applications that are also connected to the bus.
3754 In order to route messages among connections, the message bus keeps a
3755 mapping from names to connections. Each connection has one
3756 unique-for-the-lifetime-of-the-bus name automatically assigned.
3757 Applications may request additional names for a connection. Additional
3758 names are usually "well-known names" such as
3759 "org.freedesktop.TextEditor". When a name is bound to a connection,
3760 that connection is said to <firstterm>own</firstterm> the name.
3763 The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
3764 This name routes messages to the bus, allowing applications to make
3765 administrative requests. For example, applications can ask the bus
3766 to assign a name to a connection.
3769 Each name may have <firstterm>queued owners</firstterm>. When an
3770 application requests a name for a connection and the name is already in
3771 use, the bus will optionally add the connection to a queue waiting for
3772 the name. If the current owner of the name disconnects or releases
3773 the name, the next connection in the queue will become the new owner.
3777 This feature causes the right thing to happen if you start two text
3778 editors for example; the first one may request "org.freedesktop.TextEditor",
3779 and the second will be queued as a possible owner of that name. When
3780 the first exits, the second will take over.
3784 Applications may send <firstterm>unicast messages</firstterm> to
3785 a specific recipient or to the message bus itself, or
3786 <firstterm>broadcast messages</firstterm> to all interested recipients.
3787 See <xref linkend="message-bus-routing"/> for details.
3791 <sect2 id="message-bus-names">
3792 <title>Message Bus Names</title>
3794 Each connection has at least one name, assigned at connection time and
3795 returned in response to the
3796 <literal>org.freedesktop.DBus.Hello</literal> method call. This
3797 automatically-assigned name is called the connection's <firstterm>unique
3798 name</firstterm>. Unique names are never reused for two different
3799 connections to the same bus.
3802 Ownership of a unique name is a prerequisite for interaction with
3803 the message bus. It logically follows that the unique name is always
3804 the first name that an application comes to own, and the last
3805 one that it loses ownership of.
3808 Unique connection names must begin with the character ':' (ASCII colon
3809 character); bus names that are not unique names must not begin
3810 with this character. (The bus must reject any attempt by an application
3811 to manually request a name beginning with ':'.) This restriction
3812 categorically prevents "spoofing"; messages sent to a unique name
3813 will always go to the expected connection.
3816 When a connection is closed, all the names that it owns are deleted (or
3817 transferred to the next connection in the queue if any).
3820 A connection can request additional names to be associated with it using
3821 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
3822 linkend="message-protocol-names-bus"/> describes the format of a valid
3823 name. These names can be released again using the
3824 <literal>org.freedesktop.DBus.ReleaseName</literal> message.
3827 <sect3 id="bus-messages-request-name">
3828 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
3832 UINT32 RequestName (in STRING name, in UINT32 flags)
3839 <entry>Argument</entry>
3841 <entry>Description</entry>
3847 <entry>STRING</entry>
3848 <entry>Name to request</entry>
3852 <entry>UINT32</entry>
3853 <entry>Flags</entry>
3863 <entry>Argument</entry>
3865 <entry>Description</entry>
3871 <entry>UINT32</entry>
3872 <entry>Return value</entry>
3879 This method call should be sent to
3880 <literal>org.freedesktop.DBus</literal> and asks the message bus to
3881 assign the given name to the method caller. Each name maintains a
3882 queue of possible owners, where the head of the queue is the primary
3883 or current owner of the name. Each potential owner in the queue
3884 maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
3885 DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
3886 call. When RequestName is invoked the following occurs:
3890 If the method caller is currently the primary owner of the name,
3891 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
3892 values are updated with the values from the new RequestName call,
3893 and nothing further happens.
3899 If the current primary owner (head of the queue) has
3900 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
3901 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
3902 the caller of RequestName replaces the current primary owner at
3903 the head of the queue and the current primary owner moves to the
3904 second position in the queue. If the caller of RequestName was
3905 in the queue previously its flags are updated with the values from
3906 the new RequestName in addition to moving it to the head of the queue.
3912 If replacement is not possible, and the method caller is
3913 currently in the queue but not the primary owner, its flags are
3914 updated with the values from the new RequestName call.
3920 If replacement is not possible, and the method caller is
3921 currently not in the queue, the method caller is appended to the
3928 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
3929 set and is not the primary owner, it is removed from the
3930 queue. This can apply to the previous primary owner (if it
3931 was replaced) or the method caller (if it updated the
3932 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
3933 queue, or if it was just added to the queue with that flag set).
3939 Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
3940 queue," even if another application already in the queue had specified
3941 DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
3942 that does not allow replacement goes away, and the next primary owner
3943 does allow replacement. In this case, queued items that specified
3944 DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
3945 automatically replace the new primary owner. In other words,
3946 DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
3947 time RequestName is called. This is deliberate to avoid an infinite loop
3948 anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
3949 and DBUS_NAME_FLAG_REPLACE_EXISTING.
3952 The flags argument contains any of the following values logically ORed
3959 <entry>Conventional Name</entry>
3960 <entry>Value</entry>
3961 <entry>Description</entry>
3966 <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
3970 If an application A specifies this flag and succeeds in
3971 becoming the owner of the name, and another application B
3972 later calls RequestName with the
3973 DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
3974 will lose ownership and receive a
3975 <literal>org.freedesktop.DBus.NameLost</literal> signal, and
3976 application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
3977 is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
3978 is not specified by application B, then application B will not replace
3979 application A as the owner.
3984 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
3988 Try to replace the current owner if there is one. If this
3989 flag is not set the application will only become the owner of
3990 the name if there is no current owner. If this flag is set,
3991 the application will replace the current owner if
3992 the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
3997 <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
4001 Without this flag, if an application requests a name that is
4002 already owned, the application will be placed in a queue to
4003 own the name when the current owner gives it up. If this
4004 flag is given, the application will not be placed in the
4005 queue, the request for the name will simply fail. This flag
4006 also affects behavior when an application is replaced as
4007 name owner; by default the application moves back into the
4008 waiting queue, unless this flag was provided when the application
4009 became the name owner.
4017 The return code can be one of the following values:
4023 <entry>Conventional Name</entry>
4024 <entry>Value</entry>
4025 <entry>Description</entry>
4030 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
4031 <entry>1</entry> <entry>The caller is now the primary owner of
4032 the name, replacing any previous owner. Either the name had no
4033 owner before, or the caller specified
4034 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
4035 DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
4038 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
4041 <entry>The name already had an owner,
4042 DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
4043 the current owner did not specify
4044 DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
4045 application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
4049 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
4050 <entry>The name already has an owner,
4051 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
4052 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
4053 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
4054 specified by the requesting application.</entry>
4057 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
4059 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
4067 <sect3 id="bus-messages-release-name">
4068 <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
4072 UINT32 ReleaseName (in STRING name)
4079 <entry>Argument</entry>
4081 <entry>Description</entry>
4087 <entry>STRING</entry>
4088 <entry>Name to release</entry>
4098 <entry>Argument</entry>
4100 <entry>Description</entry>
4106 <entry>UINT32</entry>
4107 <entry>Return value</entry>
4114 This method call should be sent to
4115 <literal>org.freedesktop.DBus</literal> and asks the message bus to
4116 release the method caller's claim to the given name. If the caller is
4117 the primary owner, a new primary owner will be selected from the
4118 queue if any other owners are waiting. If the caller is waiting in
4119 the queue for the name, the caller will removed from the queue and
4120 will not be made an owner of the name if it later becomes available.
4121 If there are no other owners in the queue for the name, it will be
4122 removed from the bus entirely.
4124 The return code can be one of the following values:
4130 <entry>Conventional Name</entry>
4131 <entry>Value</entry>
4132 <entry>Description</entry>
4137 <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
4138 <entry>1</entry> <entry>The caller has released his claim on
4139 the given name. Either the caller was the primary owner of
4140 the name, and the name is now unused or taken by somebody
4141 waiting in the queue for the name, or the caller was waiting
4142 in the queue for the name and has now been removed from the
4146 <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
4148 <entry>The given name does not exist on this bus.</entry>
4151 <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
4153 <entry>The caller was not the primary owner of this name,
4154 and was also not waiting in the queue to own this name.</entry>
4162 <sect3 id="bus-messages-list-queued-owners">
4163 <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
4167 ARRAY of STRING ListQueuedOwners (in STRING name)
4174 <entry>Argument</entry>
4176 <entry>Description</entry>
4182 <entry>STRING</entry>
4183 <entry>The well-known bus name to query, such as
4184 <literal>com.example.cappuccino</literal></entry>
4194 <entry>Argument</entry>
4196 <entry>Description</entry>
4202 <entry>ARRAY of STRING</entry>
4203 <entry>The unique bus names of connections currently queued
4204 for the name</entry>
4211 This method call should be sent to
4212 <literal>org.freedesktop.DBus</literal> and lists the connections
4213 currently queued for a bus name (see
4214 <xref linkend="term-queued-owner"/>).
4219 <sect2 id="message-bus-routing">
4220 <title>Message Bus Message Routing</title>
4223 Messages may have a <literal>DESTINATION</literal> field (see <xref
4224 linkend="message-protocol-header-fields"/>), resulting in a
4225 <firstterm>unicast message</firstterm>. If the
4226 <literal>DESTINATION</literal> field is present, it specifies a message
4227 recipient by name. Method calls and replies normally specify this field.
4228 The message bus must send messages (of any type) with the
4229 <literal>DESTINATION</literal> field set to the specified recipient,
4230 regardless of whether the recipient has set up a match rule matching
4235 When the message bus receives a signal, if the
4236 <literal>DESTINATION</literal> field is absent, it is considered to
4237 be a <firstterm>broadcast signal</firstterm>, and is sent to all
4238 applications with <firstterm>message matching rules</firstterm> that
4239 match the message. Most signal messages are broadcasts.
4243 Unicast signal messages (those with a <literal>DESTINATION</literal>
4244 field) are not commonly used, but they are treated like any unicast
4245 message: they are delivered to the specified receipient,
4246 regardless of its match rules. One use for unicast signals is to
4247 avoid a race condition in which a signal is emitted before the intended
4248 recipient can call <xref linkend="bus-messages-add-match"/> to
4249 receive that signal: if the signal is sent directly to that recipient
4250 using a unicast message, it does not need to add a match rule at all,
4251 and there is no race condition. Another use for unicast signals,
4252 on message buses whose security policy prevents eavesdropping, is to
4253 send sensitive information which should only be visible to one
4258 When the message bus receives a method call, if the
4259 <literal>DESTINATION</literal> field is absent, the call is taken to be
4260 a standard one-to-one message and interpreted by the message bus
4261 itself. For example, sending an
4262 <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
4263 <literal>DESTINATION</literal> will cause the message bus itself to
4264 reply to the ping immediately; the message bus will not make this
4265 message visible to other applications.
4269 Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
4270 the ping message were sent with a <literal>DESTINATION</literal> name of
4271 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
4272 forwarded, and the Yoyodyne Corporation screensaver application would be
4273 expected to reply to the ping.
4277 Message bus implementations may impose a security policy which
4278 prevents certain messages from being sent or received.
4279 When a message cannot be sent or received due to a security
4280 policy, the message bus should send an error reply, unless the
4281 original message had the <literal>NO_REPLY</literal> flag.
4284 <sect3 id="message-bus-routing-eavesdropping">
4285 <title>Eavesdropping</title>
4287 Receiving a unicast message whose <literal>DESTINATION</literal>
4288 indicates a different recipient is called
4289 <firstterm>eavesdropping</firstterm>. On a message bus which acts as
4290 a security boundary (like the standard system bus), the security
4291 policy should usually prevent eavesdropping, since unicast messages
4292 are normally kept private and may contain security-sensitive
4297 Eavesdropping is mainly useful for debugging tools, such as
4298 the <literal>dbus-monitor</literal> tool in the reference
4299 implementation of D-Bus. Tools which eavesdrop on the message bus
4300 should be careful to avoid sending a reply or error in response to
4301 messages intended for a different client.
4305 Clients may attempt to eavesdrop by adding match rules
4306 (see <xref linkend="message-bus-routing-match-rules"/>) containing
4307 the <literal>eavesdrop='true'</literal> match. If the message bus'
4308 security policy does not allow eavesdropping, the match rule can
4309 still be added, but will not have any practical effect. For
4310 compatibility with older message bus implementations, if adding such
4311 a match rule results in an error reply, the client may fall back to
4312 adding the same rule with the <literal>eavesdrop</literal> match
4317 <sect3 id="message-bus-routing-match-rules">
4318 <title>Match Rules</title>
4320 An important part of the message bus routing protocol is match
4321 rules. Match rules describe the messages that should be sent to a
4322 client, based on the contents of the message. Broadcast signals
4323 are only sent to clients which have a suitable match rule: this
4324 avoids waking up client processes to deal with signals that are
4325 not relevant to that client.
4328 Messages that list a client as their <literal>DESTINATION</literal>
4329 do not need to match the client's match rules, and are sent to that
4330 client regardless. As a result, match rules are mainly used to
4331 receive a subset of broadcast signals.
4334 Match rules can also be used for eavesdropping
4335 (see <xref linkend="message-bus-routing-eavesdropping"/>),
4336 if the security policy of the message bus allows it.
4339 Match rules are added using the AddMatch bus method
4340 (see <xref linkend="bus-messages-add-match"/>). Rules are
4341 specified as a string of comma separated key/value pairs.
4342 Excluding a key from the rule indicates a wildcard match.
4343 For instance excluding the the member from a match rule but
4344 adding a sender would let all messages from that sender through.
4345 An example of a complete rule would be
4346 "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
4349 The following table describes the keys that can be used to create
4351 The following table summarizes the D-Bus types.
4357 <entry>Possible Values</entry>
4358 <entry>Description</entry>
4363 <entry><literal>type</literal></entry>
4364 <entry>'signal', 'method_call', 'method_return', 'error'</entry>
4365 <entry>Match on the message type. An example of a type match is type='signal'</entry>
4368 <entry><literal>sender</literal></entry>
4369 <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
4370 and <xref linkend="term-unique-name"/> respectively)
4372 <entry>Match messages sent by a particular sender. An example of a sender match
4373 is sender='org.freedesktop.Hal'</entry>
4376 <entry><literal>interface</literal></entry>
4377 <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
4378 <entry>Match messages sent over or to a particular interface. An example of an
4379 interface match is interface='org.freedesktop.Hal.Manager'.
4380 If a message omits the interface header, it must not match any rule
4381 that specifies this key.</entry>
4384 <entry><literal>member</literal></entry>
4385 <entry>Any valid method or signal name</entry>
4386 <entry>Matches messages which have the give method or signal name. An example of
4387 a member match is member='NameOwnerChanged'</entry>
4390 <entry><literal>path</literal></entry>
4391 <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
4392 <entry>Matches messages which are sent from or to the given object. An example of a
4393 path match is path='/org/freedesktop/Hal/Manager'</entry>
4396 <entry><literal>path_namespace</literal></entry>
4397 <entry>An object path</entry>
4400 Matches messages which are sent from or to an
4401 object for which the object path is either the
4402 given value, or that value followed by one or
4403 more path components.
4408 <literal>path_namespace='/com/example/foo'</literal>
4409 would match signals sent by
4410 <literal>/com/example/foo</literal>
4412 <literal>/com/example/foo/bar</literal>,
4414 <literal>/com/example/foobar</literal>.
4418 Using both <literal>path</literal> and
4419 <literal>path_namespace</literal> in the same match
4420 rule is not allowed.
4425 This match key was added in version 0.16 of the
4426 D-Bus specification and implemented by the bus
4427 daemon in dbus 1.5.0 and later.
4433 <entry><literal>destination</literal></entry>
4434 <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
4435 <entry>Matches messages which are being sent to the given unique name. An
4436 example of a destination match is destination=':1.0'</entry>
4439 <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
4440 <entry>Any string</entry>
4441 <entry>Arg matches are special and are used for further restricting the
4442 match based on the arguments in the body of a message. Only arguments of type
4443 STRING can be matched in this way. An example of an argument match
4444 would be arg3='Foo'. Only argument indexes from 0 to 63 should be
4448 <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
4449 <entry>Any string</entry>
4451 <para>Argument path matches provide a specialised form of wildcard matching for
4452 path-like namespaces. They can match arguments whose type is either STRING or
4453 OBJECT_PATH. As with normal argument matches,
4454 if the argument is exactly equal to the string given in the match
4455 rule then the rule is satisfied. Additionally, there is also a
4456 match when either the string given in the match rule or the
4457 appropriate message argument ends with '/' and is a prefix of the
4458 other. An example argument path match is arg0path='/aa/bb/'. This
4459 would match messages with first arguments of '/', '/aa/',
4460 '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
4461 messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
4463 <para>This is intended for monitoring “directories” in file system-like
4464 hierarchies, as used in the <citetitle>dconf</citetitle> configuration
4465 system. An application interested in all nodes in a particular hierarchy would
4466 monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
4467 emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
4468 represent a modification to the “bar” property, or a signal with zeroth
4469 argument <literal>"/ca/example/"</literal> to represent atomic modification of
4470 many properties within that directory, and the interested application would be
4471 notified in both cases.</para>
4474 This match key was added in version 0.12 of the
4475 D-Bus specification, implemented for STRING
4476 arguments by the bus daemon in dbus 1.2.0 and later,
4477 and implemented for OBJECT_PATH arguments in dbus 1.5.0
4484 <entry><literal>arg0namespace</literal></entry>
4485 <entry>Like a bus name, except that the string is not
4486 required to contain a '.' (period)</entry>
4488 <para>Match messages whose first argument is of type STRING, and is a bus name
4489 or interface name within the specified namespace. This is primarily intended
4490 for watching name owner changes for a group of related bus names, rather than
4491 for a single name or all name changes.</para>
4493 <para>Because every valid interface name is also a valid
4494 bus name, this can also be used for messages whose
4495 first argument is an interface name.</para>
4497 <para>For example, the match rule
4498 <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
4499 matches name owner changes for bus names such as
4500 <literal>com.example.backend.foo</literal>,
4501 <literal>com.example.backend.foo.bar</literal>, and
4502 <literal>com.example.backend</literal> itself.</para>
4504 <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
4507 This match key was added in version 0.16 of the
4508 D-Bus specification and implemented by the bus
4509 daemon in dbus 1.5.0 and later.
4515 <entry><literal>eavesdrop</literal></entry>
4516 <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
4517 <entry>Since D-Bus 1.5.6, match rules do not
4518 match messages which have a <literal>DESTINATION</literal>
4519 field unless the match rule specifically
4521 (see <xref linkend="message-bus-routing-eavesdropping"/>)
4522 by specifying <literal>eavesdrop='true'</literal>
4523 in the match rule. <literal>eavesdrop='false'</literal>
4524 restores the default behaviour. Messages are
4525 delivered to their <literal>DESTINATION</literal>
4526 regardless of match rules, so this match does not
4527 affect normal delivery of unicast messages.
4528 If the message bus has a security policy which forbids
4529 eavesdropping, this match may still be used without error,
4530 but will not have any practical effect.
4531 In older versions of D-Bus, this match was not allowed
4532 in match rules, and all match rules behaved as if
4533 <literal>eavesdrop='true'</literal> had been used.
4542 <sect2 id="message-bus-starting-services">
4543 <title>Message Bus Starting Services</title>
4545 The message bus can start applications on behalf of other applications.
4546 In CORBA terms, this would be called <firstterm>activation</firstterm>.
4547 An application that can be started in this way is called a
4548 <firstterm>service</firstterm>.
4551 With D-Bus, starting a service is normally done by name. That is,
4552 applications ask the message bus to start some program that will own a
4553 well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
4554 This implies a contract documented along with the name
4555 <literal>org.freedesktop.TextEditor</literal> for which objects
4556 the owner of that name will provide, and what interfaces those
4560 To find an executable corresponding to a particular name, the bus daemon
4561 looks for <firstterm>service description files</firstterm>. Service
4562 description files define a mapping from names to executables. Different
4563 kinds of message bus will look for these files in different places, see
4564 <xref linkend="message-bus-types"/>.
4567 Service description files have the ".service" file
4568 extension. The message bus will only load service description files
4569 ending with .service; all other files will be ignored. The file format
4570 is similar to that of <ulink
4571 url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
4572 entries</ulink>. All service description files must be in UTF-8
4573 encoding. To ensure that there will be no name collisions, service files
4574 must be namespaced using the same mechanism as messages and service
4579 [FIXME the file format should be much better specified than "similar to
4580 .desktop entries" esp. since desktop entries are already
4581 badly-specified. ;-)]
4582 These sections from the specification apply to service files as well:
4585 <listitem><para>General syntax</para></listitem>
4586 <listitem><para>Comment format</para></listitem>
4590 <title>Example service description file</title>
4592 # Sample service description file
4594 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
4595 Exec=/usr/libexec/gconfd-2
4600 When an application asks to start a service by name, the bus daemon tries to
4601 find a service that will own that name. It then tries to spawn the
4602 executable associated with it. If this fails, it will report an
4603 error. [FIXME what happens if two .service files offer the same service;
4604 what kind of error is reported, should we have a way for the client to
4608 The executable launched will have the environment variable
4609 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
4610 message bus so it can connect and request the appropriate names.
4613 The executable being launched may want to know whether the message bus
4614 starting it is one of the well-known message buses (see <xref
4615 linkend="message-bus-types"/>). To facilitate this, the bus must also set
4616 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
4617 of the well-known buses. The currently-defined values for this variable
4618 are <literal>system</literal> for the systemwide message bus,
4619 and <literal>session</literal> for the per-login-session message
4620 bus. The new executable must still connect to the address given
4621 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
4622 resulting connection is to the well-known bus.
4625 [FIXME there should be a timeout somewhere, either specified
4626 in the .service file, by the client, or just a global value
4627 and if the client being activated fails to connect within that
4628 timeout, an error should be sent back.]
4631 <sect3 id="message-bus-starting-services-scope">
4632 <title>Message Bus Service Scope</title>
4634 The "scope" of a service is its "per-", such as per-session,
4635 per-machine, per-home-directory, or per-display. The reference
4636 implementation doesn't yet support starting services in a different
4637 scope from the message bus itself. So e.g. if you start a service
4638 on the session bus its scope is per-session.
4641 We could add an optional scope to a bus name. For example, for
4642 per-(display,session pair), we could have a unique ID for each display
4643 generated automatically at login and set on screen 0 by executing a
4644 special "set display ID" binary. The ID would be stored in a
4645 <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
4646 random bytes. This ID would then be used to scope names.
4647 Starting/locating a service could be done by ID-name pair rather than
4651 Contrast this with a per-display scope. To achieve that, we would
4652 want a single bus spanning all sessions using a given display.
4653 So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
4654 property on screen 0 of the display, pointing to this bus.
4659 <sect2 id="message-bus-types">
4660 <title>Well-known Message Bus Instances</title>
4662 Two standard message bus instances are defined here, along with how
4663 to locate them and where their service files live.
4665 <sect3 id="message-bus-types-login">
4666 <title>Login session message bus</title>
4668 Each time a user logs in, a <firstterm>login session message
4669 bus</firstterm> may be started. All applications in the user's login
4670 session may interact with one another using this message bus.
4673 The address of the login session message bus is given
4674 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
4675 variable. If that variable is not set, applications may
4676 also try to read the address from the X Window System root
4677 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
4678 The root window property must have type <literal>STRING</literal>.
4679 The environment variable should have precedence over the
4680 root window property.
4682 <para>The address of the login session message bus is given in the
4683 <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment variable. If
4684 DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string
4685 "autolaunch:", the system should use platform-specific methods of
4686 locating a running D-Bus session server, or starting one if a running
4687 instance cannot be found. Note that this mechanism is not recommended
4688 for attempting to determine if a daemon is running. It is inherently
4689 racy to attempt to make this determination, since the bus daemon may
4690 be started just before or just after the determination is made.
4691 Therefore, it is recommended that applications do not try to make this
4692 determination for their functionality purposes, and instead they
4693 should attempt to start the server.</para>
4695 <sect4 id="message-bus-types-login-x-windows">
4696 <title>X Windowing System</title>
4698 For the X Windowing System, the application must locate the
4699 window owner of the selection represented by the atom formed by
4703 <para>the literal string "_DBUS_SESSION_BUS_SELECTION_"</para>
4707 <para>the current user's username</para>
4711 <para>the literal character '_' (underscore)</para>
4715 <para>the machine's ID</para>
4721 The following properties are defined for the window that owns
4723 <informaltable frame="all">
4732 <para>meaning</para>
4738 <para>_DBUS_SESSION_BUS_ADDRESS</para>
4742 <para>the actual address of the server socket</para>
4748 <para>_DBUS_SESSION_BUS_PID</para>
4752 <para>the PID of the server process</para>
4761 At least the _DBUS_SESSION_BUS_ADDRESS property MUST be
4762 present in this window.
4766 If the X selection cannot be located or if reading the
4767 properties from the window fails, the implementation MUST conclude
4768 that there is no D-Bus server running and proceed to start a new
4769 server. (See below on concurrency issues)
4773 Failure to connect to the D-Bus server address thus obtained
4774 MUST be treated as a fatal connection error and should be reported
4779 As an alternative, an implementation MAY find the information
4780 in the following file located in the current user's home directory,
4781 in subdirectory .dbus/session-bus/:
4784 <para>the machine's ID</para>
4788 <para>the literal character '-' (dash)</para>
4792 <para>the X display without the screen number, with the
4793 following prefixes removed, if present: ":", "localhost:"
4794 ."localhost.localdomain:". That is, a display of
4795 "localhost:10.0" produces just the number "10"</para>
4801 The contents of this file NAME=value assignment pairs and
4802 lines starting with # are comments (no comments are allowed
4803 otherwise). The following variable names are defined:
4810 <para>Variable</para>
4814 <para>meaning</para>
4820 <para>DBUS_SESSION_BUS_ADDRESS</para>
4824 <para>the actual address of the server socket</para>
4830 <para>DBUS_SESSION_BUS_PID</para>
4834 <para>the PID of the server process</para>
4840 <para>DBUS_SESSION_BUS_WINDOWID</para>
4844 <para>the window ID</para>
4853 At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
4858 Failure to open this file MUST be interpreted as absence of a
4859 running server. Therefore, the implementation MUST proceed to
4860 attempting to launch a new bus server if the file cannot be
4865 However, success in opening this file MUST NOT lead to the
4866 conclusion that the server is running. Thus, a failure to connect to
4867 the bus address obtained by the alternative method MUST NOT be
4868 considered a fatal error. If the connection cannot be established,
4869 the implementation MUST proceed to check the X selection settings or
4870 to start the server on its own.
4874 If the implementation concludes that the D-Bus server is not
4875 running it MUST attempt to start a new server and it MUST also
4876 ensure that the daemon started as an effect of the "autolaunch"
4877 mechanism provides the lookup mechanisms described above, so
4878 subsequent calls can locate the newly started server. The
4879 implementation MUST also ensure that if two or more concurrent
4880 initiations happen, only one server remains running and all other
4881 initiations are able to obtain the address of this server and
4882 connect to it. In other words, the implementation MUST ensure that
4883 the X selection is not present when it attempts to set it, without
4884 allowing another process to set the selection between the
4885 verification and the setting (e.g., by using XGrabServer /
4892 On Unix systems, the session bus should search for .service files
4893 in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
4895 <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
4896 Implementations may also search additional locations, which
4897 should be searched with lower priority than anything in
4898 XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
4899 for example, the reference implementation also
4900 looks in <literal>${datadir}/dbus-1/services</literal> as
4901 set at compile time.
4904 As described in the XDG Base Directory Specification, software
4905 packages should install their session .service files to their
4906 configured <literal>${datadir}/dbus-1/services</literal>,
4907 where <literal>${datadir}</literal> is as defined by the GNU
4908 coding standards. System administrators or users can arrange
4909 for these service files to be read by setting XDG_DATA_DIRS or by
4910 symlinking them into the default locations.
4914 <sect3 id="message-bus-types-system">
4915 <title>System message bus</title>
4917 A computer may have a <firstterm>system message bus</firstterm>,
4918 accessible to all applications on the system. This message bus may be
4919 used to broadcast system events, such as adding new hardware devices,
4920 changes in the printer queue, and so forth.
4923 The address of the system message bus is given
4924 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
4925 variable. If that variable is not set, applications should try
4926 to connect to the well-known address
4927 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
4930 The D-Bus reference implementation actually honors the
4931 <literal>$(localstatedir)</literal> configure option
4932 for this address, on both client and server side.
4937 On Unix systems, the system bus should default to searching
4938 for .service files in
4939 <literal>/usr/local/share/dbus-1/system-services</literal>,
4940 <literal>/usr/share/dbus-1/system-services</literal> and
4941 <literal>/lib/dbus-1/system-services</literal>, with that order
4942 of precedence. It may also search other implementation-specific
4943 locations, but should not vary these locations based on environment
4947 The system bus is security-sensitive and is typically executed
4948 by an init system with a clean environment. Its launch helper
4949 process is particularly security-sensitive, and specifically
4950 clears its own environment.
4955 Software packages should install their system .service
4956 files to their configured
4957 <literal>${datadir}/dbus-1/system-services</literal>,
4958 where <literal>${datadir}</literal> is as defined by the GNU
4959 coding standards. System administrators can arrange
4960 for these service files to be read by editing the system bus'
4961 configuration file or by symlinking them into the default
4967 <sect2 id="message-bus-messages">
4968 <title>Message Bus Messages</title>
4970 The special message bus name <literal>org.freedesktop.DBus</literal>
4971 responds to a number of additional messages.
4974 <sect3 id="bus-messages-hello">
4975 <title><literal>org.freedesktop.DBus.Hello</literal></title>
4986 <entry>Argument</entry>
4988 <entry>Description</entry>
4994 <entry>STRING</entry>
4995 <entry>Unique name assigned to the connection</entry>
5002 Before an application is able to send messages to other applications
5003 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
5004 to the message bus to obtain a unique name. If an application without
5005 a unique name tries to send a message to another application, or a
5006 message to the message bus itself that isn't the
5007 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
5008 disconnected from the bus.
5011 There is no corresponding "disconnect" request; if a client wishes to
5012 disconnect from the bus, it simply closes the socket (or other
5013 communication channel).
5016 <sect3 id="bus-messages-list-names">
5017 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
5021 ARRAY of STRING ListNames ()
5028 <entry>Argument</entry>
5030 <entry>Description</entry>
5036 <entry>ARRAY of STRING</entry>
5037 <entry>Array of strings where each string is a bus name</entry>
5044 Returns a list of all currently-owned names on the bus.
5047 <sect3 id="bus-messages-list-activatable-names">
5048 <title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
5052 ARRAY of STRING ListActivatableNames ()
5059 <entry>Argument</entry>
5061 <entry>Description</entry>
5067 <entry>ARRAY of STRING</entry>
5068 <entry>Array of strings where each string is a bus name</entry>
5075 Returns a list of all names that can be activated on the bus.
5078 <sect3 id="bus-messages-name-exists">
5079 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
5083 BOOLEAN NameHasOwner (in STRING name)
5090 <entry>Argument</entry>
5092 <entry>Description</entry>
5098 <entry>STRING</entry>
5099 <entry>Name to check</entry>
5109 <entry>Argument</entry>
5111 <entry>Description</entry>
5117 <entry>BOOLEAN</entry>
5118 <entry>Return value, true if the name exists</entry>
5125 Checks if the specified name exists (currently has an owner).
5129 <sect3 id="bus-messages-name-owner-changed">
5130 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
5134 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
5141 <entry>Argument</entry>
5143 <entry>Description</entry>
5149 <entry>STRING</entry>
5150 <entry>Name with a new owner</entry>
5154 <entry>STRING</entry>
5155 <entry>Old owner or empty string if none</entry>
5159 <entry>STRING</entry>
5160 <entry>New owner or empty string if none</entry>
5167 This signal indicates that the owner of a name has changed.
5168 It's also the signal to use to detect the appearance of
5169 new names on the bus.
5172 <sect3 id="bus-messages-name-lost">
5173 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
5177 NameLost (STRING name)
5184 <entry>Argument</entry>
5186 <entry>Description</entry>
5192 <entry>STRING</entry>
5193 <entry>Name which was lost</entry>
5200 This signal is sent to a specific application when it loses
5201 ownership of a name.
5205 <sect3 id="bus-messages-name-acquired">
5206 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
5210 NameAcquired (STRING name)
5217 <entry>Argument</entry>
5219 <entry>Description</entry>
5225 <entry>STRING</entry>
5226 <entry>Name which was acquired</entry>
5233 This signal is sent to a specific application when it gains
5234 ownership of a name.
5238 <sect3 id="bus-messages-start-service-by-name">
5239 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
5243 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
5250 <entry>Argument</entry>
5252 <entry>Description</entry>
5258 <entry>STRING</entry>
5259 <entry>Name of the service to start</entry>
5263 <entry>UINT32</entry>
5264 <entry>Flags (currently not used)</entry>
5274 <entry>Argument</entry>
5276 <entry>Description</entry>
5282 <entry>UINT32</entry>
5283 <entry>Return value</entry>
5288 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
5292 The return value can be one of the following values:
5297 <entry>Identifier</entry>
5298 <entry>Value</entry>
5299 <entry>Description</entry>
5304 <entry>DBUS_START_REPLY_SUCCESS</entry>
5306 <entry>The service was successfully started.</entry>
5309 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
5311 <entry>A connection already owns the given name.</entry>
5320 <sect3 id="bus-messages-update-activation-environment">
5321 <title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
5325 UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment)
5332 <entry>Argument</entry>
5334 <entry>Description</entry>
5340 <entry>ARRAY of DICT<STRING,STRING></entry>
5341 <entry>Environment to add or update</entry>
5346 Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services.
5349 Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.
5352 Note, both the environment variable names and values must be valid UTF-8. There's no way to update the activation environment with data that is invalid UTF-8.
5357 <sect3 id="bus-messages-get-name-owner">
5358 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
5362 STRING GetNameOwner (in STRING name)
5369 <entry>Argument</entry>
5371 <entry>Description</entry>
5377 <entry>STRING</entry>
5378 <entry>Name to get the owner of</entry>
5388 <entry>Argument</entry>
5390 <entry>Description</entry>
5396 <entry>STRING</entry>
5397 <entry>Return value, a unique connection name</entry>
5402 Returns the unique connection name of the primary owner of the name
5403 given. If the requested name doesn't have an owner, returns a
5404 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
5408 <sect3 id="bus-messages-get-connection-unix-user">
5409 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
5413 UINT32 GetConnectionUnixUser (in STRING bus_name)
5420 <entry>Argument</entry>
5422 <entry>Description</entry>
5428 <entry>STRING</entry>
5429 <entry>Unique or well-known bus name of the connection to
5430 query, such as <literal>:12.34</literal> or
5431 <literal>com.example.tea</literal></entry>
5441 <entry>Argument</entry>
5443 <entry>Description</entry>
5449 <entry>UINT32</entry>
5450 <entry>Unix user ID</entry>
5455 Returns the Unix user ID of the process connected to the server. If
5456 unable to determine it (for instance, because the process is not on the
5457 same machine as the bus daemon), an error is returned.
5461 <sect3 id="bus-messages-get-connection-unix-process-id">
5462 <title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
5466 UINT32 GetConnectionUnixProcessID (in STRING bus_name)
5473 <entry>Argument</entry>
5475 <entry>Description</entry>
5481 <entry>STRING</entry>
5482 <entry>Unique or well-known bus name of the connection to
5483 query, such as <literal>:12.34</literal> or
5484 <literal>com.example.tea</literal></entry>
5494 <entry>Argument</entry>
5496 <entry>Description</entry>
5502 <entry>UINT32</entry>
5503 <entry>Unix process id</entry>
5508 Returns the Unix process ID of the process connected to the server. If
5509 unable to determine it (for instance, because the process is not on the
5510 same machine as the bus daemon), an error is returned.
5514 <sect3 id="bus-messages-add-match">
5515 <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
5519 AddMatch (in STRING rule)
5526 <entry>Argument</entry>
5528 <entry>Description</entry>
5534 <entry>STRING</entry>
5535 <entry>Match rule to add to the connection</entry>
5540 Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
5541 If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
5545 <sect3 id="bus-messages-remove-match">
5546 <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
5550 RemoveMatch (in STRING rule)
5557 <entry>Argument</entry>
5559 <entry>Description</entry>
5565 <entry>STRING</entry>
5566 <entry>Match rule to remove from the connection</entry>
5571 Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
5572 If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
5577 <sect3 id="bus-messages-get-id">
5578 <title><literal>org.freedesktop.DBus.GetId</literal></title>
5582 GetId (out STRING id)
5589 <entry>Argument</entry>
5591 <entry>Description</entry>
5597 <entry>STRING</entry>
5598 <entry>Unique ID identifying the bus daemon</entry>
5603 Gets the unique ID of the bus. The unique ID here is shared among all addresses the
5604 bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
5605 <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
5606 ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
5607 There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
5608 by org.freedesktop.DBus.Peer.GetMachineId().
5609 For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
5617 <appendix id="implementation-notes">
5618 <title>Implementation notes</title>
5619 <sect1 id="implementation-notes-subsection">
5627 <glossary><title>Glossary</title>
5629 This glossary defines some of the terms used in this specification.
5632 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
5635 The message bus maintains an association between names and
5636 connections. (Normally, there's one connection per application.) A
5637 bus name is simply an identifier used to locate connections. For
5638 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
5639 name might be used to send a message to a screensaver from Yoyodyne
5640 Corporation. An application is said to <firstterm>own</firstterm> a
5641 name if the message bus has associated the application's connection
5642 with the name. Names may also have <firstterm>queued
5643 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
5644 The bus assigns a unique name to each connection,
5645 see <xref linkend="term-unique-name"/>. Other names
5646 can be thought of as "well-known names" and are
5647 used to find applications that offer specific functionality.
5651 See <xref linkend="message-protocol-names-bus"/> for details of
5652 the syntax and naming conventions for bus names.
5657 <glossentry id="term-message"><glossterm>Message</glossterm>
5660 A message is the atomic unit of communication via the D-Bus
5661 protocol. It consists of a <firstterm>header</firstterm> and a
5662 <firstterm>body</firstterm>; the body is made up of
5663 <firstterm>arguments</firstterm>.
5668 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
5671 The message bus is a special application that forwards
5672 or routes messages between a group of applications
5673 connected to the message bus. It also manages
5674 <firstterm>names</firstterm> used for routing
5680 <glossentry id="term-name"><glossterm>Name</glossterm>
5683 See <xref linkend="term-bus-name"/>. "Name" may
5684 also be used to refer to some of the other names
5685 in D-Bus, such as interface names.
5690 <glossentry id="namespace"><glossterm>Namespace</glossterm>
5693 Used to prevent collisions when defining new interfaces, bus names
5694 etc. The convention used is the same one Java uses for defining
5695 classes: a reversed domain name.
5696 See <xref linkend="message-protocol-names-bus"/>,
5697 <xref linkend="message-protocol-names-interface"/>,
5698 <xref linkend="message-protocol-names-error"/>,
5699 <xref linkend="message-protocol-marshaling-object-path"/>.
5704 <glossentry id="term-object"><glossterm>Object</glossterm>
5707 Each application contains <firstterm>objects</firstterm>, which have
5708 <firstterm>interfaces</firstterm> and
5709 <firstterm>methods</firstterm>. Objects are referred to by a name,
5710 called a <firstterm>path</firstterm>.
5715 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
5718 An application talking directly to another application, without going
5719 through a message bus. One-to-one connections may be "peer to peer" or
5720 "client to server." The D-Bus protocol has no concept of client
5721 vs. server after a connection has authenticated; the flow of messages
5722 is symmetrical (full duplex).
5727 <glossentry id="term-path"><glossterm>Path</glossterm>
5730 Object references (object names) in D-Bus are organized into a
5731 filesystem-style hierarchy, so each object is named by a path. As in
5732 LDAP, there's no difference between "files" and "directories"; a path
5733 can refer to an object, while still having child objects below it.
5738 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
5741 Each bus name has a primary owner; messages sent to the name go to the
5742 primary owner. However, certain names also maintain a queue of
5743 secondary owners "waiting in the wings." If the primary owner releases
5744 the name, then the first secondary owner in the queue automatically
5745 becomes the new owner of the name.
5750 <glossentry id="term-service"><glossterm>Service</glossterm>
5753 A service is an executable that can be launched by the bus daemon.
5754 Services normally guarantee some particular features, for example they
5755 may guarantee that they will request a specific name such as
5756 "org.freedesktop.Screensaver", have a singleton object
5757 "/org/freedesktop/Application", and that object will implement the
5758 interface "org.freedesktop.ScreensaverControl".
5763 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
5766 ".service files" tell the bus about service applications that can be
5767 launched (see <xref linkend="term-service"/>). Most importantly they
5768 provide a mapping from bus names to services that will request those
5769 names when they start up.
5774 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
5777 The special name automatically assigned to each connection by the
5778 message bus. This name will never change owner, and will be unique
5779 (never reused during the lifetime of the message bus).
5780 It will begin with a ':' character.