1 <?xml version="1.0" standalone="no" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
8 <title>D-Bus Specification</title>
9 <releaseinfo>Version 0.27</releaseinfo>
10 <date>2015-12-02</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>
67 <email>zeuthen@gmail.com</email>
74 <revnumber>0.27</revnumber>
75 <date>2015-12-02</date>
76 <authorinitials>LU</authorinitials>
77 <revremark>Services should not send unwanted replies</revremark>
80 <revnumber>0.26</revnumber>
81 <date>2015-02-19</date>
82 <authorinitials>smcv, rh</authorinitials>
84 GetConnectionCredentials can return LinuxSecurityLabel or
85 WindowsSID; add privileged BecomeMonitor method
89 <revnumber>0.25</revnumber>
90 <date>2014-11-10</date>
91 <authorinitials>smcv, lennart</authorinitials>
93 ALLOW_INTERACTIVE_AUTHORIZATION flag, EmitsChangedSignal=const
97 <revnumber>0.24</revnumber>
98 <date>2014-10-01</date>
99 <authorinitials>SMcV</authorinitials>
101 non-method-calls never expect a reply even without NO_REPLY_EXPECTED;
102 document how to quote match rules
106 <revnumber>0.23</revnumber>
107 <date>2014-01-06</date>
108 <authorinitials>SMcV, CY</authorinitials>
110 method call messages with no INTERFACE may be considered an error;
111 document tcp:bind=... and nonce-tcp:bind=...; define listenable
112 and connectable addresses
116 <revnumber>0.22</revnumber>
117 <date>2013-10-09</date>
118 <authorinitials></authorinitials>
119 <revremark>add GetConnectionCredentials, document
120 GetAtdAuditSessionData, document GetConnectionSELinuxSecurityContext,
121 document and correct .service file syntax and naming
125 <revnumber>0.21</revnumber>
126 <date>2013-04-25</date>
127 <authorinitials>smcv</authorinitials>
128 <revremark>allow Unicode noncharacters in UTF-8 (Unicode
129 Corrigendum #9)</revremark>
132 <revnumber>0.20</revnumber>
133 <date>22 February 2013</date>
134 <authorinitials>smcv, walters</authorinitials>
135 <revremark>reorganise for clarity, remove false claims about
136 basic types, mention /o/fd/DBus</revremark>
139 <revnumber>0.19</revnumber>
140 <date>20 February 2012</date>
141 <authorinitials>smcv/lp</authorinitials>
142 <revremark>formally define unique connection names and well-known
143 bus names; document best practices for interface, bus, member and
144 error names, and object paths; document the search path for session
145 and system services on Unix; document the systemd transport</revremark>
148 <revnumber>0.18</revnumber>
149 <date>29 July 2011</date>
150 <authorinitials>smcv</authorinitials>
151 <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
152 match keyword; promote type system to a top-level section</revremark>
155 <revnumber>0.17</revnumber>
156 <date>1 June 2011</date>
157 <authorinitials>smcv/davidz</authorinitials>
158 <revremark>define ObjectManager; reserve extra pseudo-type-codes used
159 by GVariant</revremark>
162 <revnumber>0.16</revnumber>
163 <date>11 April 2011</date>
164 <authorinitials></authorinitials>
165 <revremark>add path_namespace, arg0namespace; argNpath matches object
169 <revnumber>0.15</revnumber>
170 <date>3 November 2010</date>
171 <authorinitials></authorinitials>
172 <revremark></revremark>
175 <revnumber>0.14</revnumber>
176 <date>12 May 2010</date>
177 <authorinitials></authorinitials>
178 <revremark></revremark>
181 <revnumber>0.13</revnumber>
182 <date>23 Dezember 2009</date>
183 <authorinitials></authorinitials>
184 <revremark></revremark>
187 <revnumber>0.12</revnumber>
188 <date>7 November, 2006</date>
189 <authorinitials></authorinitials>
190 <revremark></revremark>
193 <revnumber>0.11</revnumber>
194 <date>6 February 2005</date>
195 <authorinitials></authorinitials>
196 <revremark></revremark>
199 <revnumber>0.10</revnumber>
200 <date>28 January 2005</date>
201 <authorinitials></authorinitials>
202 <revremark></revremark>
205 <revnumber>0.9</revnumber>
206 <date>7 Januar 2005</date>
207 <authorinitials></authorinitials>
208 <revremark></revremark>
211 <revnumber>0.8</revnumber>
212 <date>06 September 2003</date>
213 <authorinitials></authorinitials>
214 <revremark>First released document.</revremark>
219 <sect1 id="introduction">
220 <title>Introduction</title>
222 D-Bus is a system for low-overhead, easy to use
223 interprocess communication (IPC). In more detail:
227 D-Bus is <emphasis>low-overhead</emphasis> because it uses a
228 binary protocol, and does not have to convert to and from a text
229 format such as XML. Because D-Bus is intended for potentially
230 high-resolution same-machine IPC, not primarily for Internet IPC,
231 this is an interesting optimization. D-Bus is also designed to
232 avoid round trips and allow asynchronous operation, much like
238 D-Bus is <emphasis>easy to use</emphasis> because it works in terms
239 of <firstterm>messages</firstterm> rather than byte streams, and
240 automatically handles a lot of the hard IPC issues. Also, the D-Bus
241 library is designed to be wrapped in a way that lets developers use
242 their framework's existing object/type system, rather than learning
243 a new one specifically for IPC.
250 The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
251 protocol, specified in <xref linkend="message-protocol"/>. That is, it is
252 a system for one application to talk to a single other
253 application. However, the primary intended application of the protocol is the
254 D-Bus <firstterm>message bus</firstterm>, specified in <xref
255 linkend="message-bus"/>. The message bus is a special application that
256 accepts connections from multiple other applications, and forwards
261 Uses of D-Bus include notification of system changes (notification of when
262 a camera is plugged in to a computer, or a new version of some software
263 has been installed), or desktop interoperability, for example a file
264 monitoring service or a configuration service.
268 D-Bus is designed for two specific use cases:
272 A "system bus" for notifications from the system to user sessions,
273 and to allow the system to request input from user sessions.
278 A "session bus" used to implement desktop environments such as
283 D-Bus is not intended to be a generic IPC system for any possible
284 application, and intentionally omits many features found in other
285 IPC systems for this reason.
289 At the same time, the bus daemons offer a number of features not found in
290 other IPC systems, such as single-owner "bus names" (similar to X
291 selections), on-demand startup of services, and security policies.
292 In many ways, these features are the primary motivation for developing
293 D-Bus; other systems would have sufficed if IPC were the only goal.
297 D-Bus may turn out to be useful in unanticipated applications, but future
298 versions of this spec and the reference implementation probably will not
299 incorporate features that interfere with the core use cases.
303 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
304 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
305 document are to be interpreted as described in RFC 2119. However, the
306 document could use a serious audit to be sure it makes sense to do
307 so. Also, they are not capitalized.
310 <sect2 id="stability">
311 <title>Protocol and Specification Stability</title>
313 The D-Bus protocol is frozen (only compatible extensions are allowed) as
314 of November 8, 2006. However, this specification could still use a fair
315 bit of work to make interoperable reimplementation possible without
316 reference to the D-Bus reference implementation. Thus, this
317 specification is not marked 1.0. To mark it 1.0, we'd like to see
318 someone invest significant effort in clarifying the specification
319 language, and growing the specification to cover more aspects of the
320 reference implementation's behavior.
323 Until this work is complete, any attempt to reimplement D-Bus will
324 probably require looking at the reference implementation and/or asking
325 questions on the D-Bus mailing list about intended behavior.
326 Questions on the list are very welcome.
329 Nonetheless, this document should be a useful starting point and is
330 to our knowledge accurate, though incomplete.
336 <sect1 id="type-system">
337 <title>Type System</title>
340 D-Bus has a type system, in which values of various types can be
341 serialized into a sequence of bytes referred to as the
342 <firstterm>wire format</firstterm> in a standard way.
343 Converting a value from some other representation into the wire
344 format is called <firstterm>marshaling</firstterm> and converting
345 it back from the wire format is <firstterm>unmarshaling</firstterm>.
349 The D-Bus protocol does not include type tags in the marshaled data; a
350 block of marshaled values must have a known <firstterm>type
351 signature</firstterm>. The type signature is made up of zero or more
352 <firstterm id="term-single-complete-type">single complete
353 types</firstterm>, each made up of one or more
354 <firstterm>type codes</firstterm>.
358 A type code is an ASCII character representing the
359 type of a value. Because ASCII characters are used, the type signature
360 will always form a valid ASCII string. A simple string compare
361 determines whether two type signatures are equivalent.
365 A single complete type is a sequence of type codes that fully describes
366 one type: either a basic type, or a single fully-described container type.
367 A single complete type is a basic type code, a variant type code,
368 an array with its element type, or a struct with its fields (all of which
369 are defined below). So the following signatures are not single complete
380 And the following signatures contain multiple complete types:
390 Note however that a single complete type may <emphasis>contain</emphasis>
391 multiple other single complete types, by containing a struct or dict
395 <sect2 id="basic-types">
396 <title>Basic types</title>
399 The simplest type codes are the <firstterm id="term-basic-type">basic
400 types</firstterm>, which are the types whose structure is entirely
401 defined by their 1-character type code. Basic types consist of
402 fixed types and string-like types.
406 The <firstterm id="term-fixed-type">fixed types</firstterm>
407 are basic types whose values have a fixed length, namely BYTE,
408 BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
413 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
414 the ASCII character 'i'. So the signature for a block of values
415 containing a single <literal>INT32</literal> would be:
419 A block of values containing two <literal>INT32</literal> would have this signature:
426 The characteristics of the fixed types are listed in this table.
432 <entry>Conventional name</entry>
433 <entry>ASCII type-code</entry>
434 <entry>Encoding</entry>
439 <entry><literal>BYTE</literal></entry>
440 <entry><literal>y</literal> (121)</entry>
441 <entry>Unsigned 8-bit integer</entry>
444 <entry><literal>BOOLEAN</literal></entry>
445 <entry><literal>b</literal> (98)</entry>
446 <entry>Boolean value: 0 is false, 1 is true, any other value
447 allowed by the marshalling format is invalid</entry>
450 <entry><literal>INT16</literal></entry>
451 <entry><literal>n</literal> (110)</entry>
452 <entry>Signed (two's complement) 16-bit integer</entry>
455 <entry><literal>UINT16</literal></entry>
456 <entry><literal>q</literal> (113)</entry>
457 <entry>Unsigned 16-bit integer</entry>
460 <entry><literal>INT32</literal></entry>
461 <entry><literal>i</literal> (105)</entry>
462 <entry>Signed (two's complement) 32-bit integer</entry>
465 <entry><literal>UINT32</literal></entry>
466 <entry><literal>u</literal> (117)</entry>
467 <entry>Unsigned 32-bit integer</entry>
470 <entry><literal>INT64</literal></entry>
471 <entry><literal>x</literal> (120)</entry>
472 <entry>Signed (two's complement) 64-bit integer
473 (mnemonic: x and t are the first characters in "sixty" not
474 already used for something more common)</entry>
477 <entry><literal>UINT64</literal></entry>
478 <entry><literal>t</literal> (116)</entry>
479 <entry>Unsigned 64-bit integer</entry>
482 <entry><literal>DOUBLE</literal></entry>
483 <entry><literal>d</literal> (100)</entry>
484 <entry>IEEE 754 double-precision floating point</entry>
487 <entry><literal>UNIX_FD</literal></entry>
488 <entry><literal>h</literal> (104)</entry>
489 <entry>Unsigned 32-bit integer representing an index into an
490 out-of-band array of file descriptors, transferred via some
491 platform-specific mechanism (mnemonic: h for handle)</entry>
499 The <firstterm id="term-string-like-type">string-like types</firstterm>
500 are basic types with a variable length. The value of any string-like
501 type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
502 none of which may be U+0000. The UTF-8 text must be validated
503 strictly: in particular, it must not contain overlong sequences
504 or codepoints above U+10FFFF.
508 Since D-Bus Specification version 0.21, in accordance with Unicode
509 Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and
510 U+nFFFF are allowed in UTF-8 strings (but note that older versions of
511 D-Bus rejected these noncharacters).
515 The marshalling formats for the string-like types all end with a
516 single zero (NUL) byte, but that byte is not considered to be part of
521 The characteristics of the string-like types are listed in this table.
527 <entry>Conventional name</entry>
528 <entry>ASCII type-code</entry>
529 <entry>Validity constraints</entry>
534 <entry><literal>STRING</literal></entry>
535 <entry><literal>s</literal> (115)</entry>
536 <entry>No extra constraints</entry>
539 <entry><literal>OBJECT_PATH</literal></entry>
540 <entry><literal>o</literal> (111)</entry>
542 <link linkend="message-protocol-marshaling-object-path">a
543 syntactically valid object path</link></entry>
546 <entry><literal>SIGNATURE</literal></entry>
547 <entry><literal>g</literal> (103)</entry>
549 <firstterm linkend="term-single-complete-type">single
550 complete types</firstterm></entry>
557 <sect3 id="message-protocol-marshaling-object-path">
558 <title>Valid Object Paths</title>
561 An object path is a name used to refer to an object instance.
562 Conceptually, each participant in a D-Bus message exchange may have
563 any number of object instances (think of C++ or Java objects) and each
564 such instance will have a path. Like a filesystem, the object
565 instances in an application form a hierarchical tree.
569 Object paths are often namespaced by starting with a reversed
570 domain name and containing an interface version number, in the
572 <link linkend="message-protocol-names-interface">interface
574 <link linkend="message-protocol-names-bus">well-known
576 This makes it possible to implement more than one service, or
577 more than one version of a service, in the same process,
578 even if the services share a connection but cannot otherwise
579 co-operate (for instance, if they are implemented by different
584 For instance, if the owner of <literal>example.com</literal> is
585 developing a D-Bus API for a music player, they might use the
586 hierarchy of object paths that start with
587 <literal>/com/example/MusicPlayer1</literal> for its objects.
591 The following rules define a valid object path. Implementations must
592 not send or accept messages with invalid object paths.
596 The path may be of any length.
601 The path must begin with an ASCII '/' (integer 47) character,
602 and must consist of elements separated by slash characters.
607 Each element must only contain the ASCII characters
613 No element may be the empty string.
618 Multiple '/' characters cannot occur in sequence.
623 A trailing '/' character is not allowed unless the
624 path is the root path (a single '/' character).
632 <sect3 id="message-protocol-marshaling-signature">
633 <title>Valid Signatures</title>
635 An implementation must not send or accept invalid signatures.
636 Valid signatures will conform to the following rules:
640 The signature is a list of single complete types.
641 Arrays must have element types, and structs must
642 have both open and close parentheses.
647 Only type codes, open and close parentheses, and open and
648 close curly brackets are allowed in the signature. The
649 <literal>STRUCT</literal> type code
650 is not allowed in signatures, because parentheses
651 are used instead. Similarly, the
652 <literal>DICT_ENTRY</literal> type code is not allowed in
653 signatures, because curly brackets are used instead.
658 The maximum depth of container type nesting is 32 array type
659 codes and 32 open parentheses. This implies that the maximum
660 total depth of recursion is 64, for an "array of array of array
661 of ... struct of struct of struct of ..." where there are 32
667 The maximum length of a signature is 255.
674 When signatures appear in messages, the marshalling format
675 guarantees that they will be followed by a nul byte (which can
676 be interpreted as either C-style string termination or the INVALID
677 type-code), but this is not conceptually part of the signature.
683 <sect2 id="container-types">
684 <title>Container types</title>
687 In addition to basic types, there are four <firstterm>container</firstterm>
688 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
689 and <literal>DICT_ENTRY</literal>.
693 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
694 code does not appear in signatures. Instead, ASCII characters
695 '(' and ')' are used to mark the beginning and end of the struct.
696 So for example, a struct containing two integers would have this
701 Structs can be nested, so for example a struct containing
702 an integer and another struct:
706 The value block storing that struct would contain three integers; the
707 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
712 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
713 but is useful in code that implements the protocol. This type code
714 is specified to allow such code to interoperate in non-protocol contexts.
718 Empty structures are not allowed; there must be at least one
719 type code between the parentheses.
723 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
724 followed by a <firstterm>single complete type</firstterm>. The single
725 complete type following the array is the type of each array element. So
726 the simple example is:
730 which is an array of 32-bit integers. But an array can be of any type,
731 such as this array-of-struct-with-two-int32-fields:
735 Or this array of array of integer:
742 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
743 type <literal>VARIANT</literal> will have the signature of a single complete type as part
744 of the <emphasis>value</emphasis>. This signature will be followed by a
745 marshaled value of that type.
749 Unlike a message signature, the variant signature can
750 contain only a single complete type. So "i", "ai"
751 or "(ii)" is OK, but "ii" is not. Use of variants may not
752 cause a total message depth to be larger than 64, including
753 other container types such as structures.
757 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
758 than parentheses it uses curly braces, and it has more restrictions.
759 The restrictions are: it occurs only as an array element type; it has
760 exactly two single complete types inside the curly braces; the first
761 single complete type (the "key") must be a basic type rather than a
762 container type. Implementations must not accept dict entries outside of
763 arrays, must not accept dict entries with zero, one, or more than two
764 fields, and must not accept dict entries with non-basic-typed keys. A
765 dict entry is always a key-value pair.
769 The first field in the <literal>DICT_ENTRY</literal> is always the key.
770 A message is considered corrupt if the same key occurs twice in the same
771 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
772 implementations are not required to reject dicts with duplicate keys.
776 In most languages, an array of dict entry would be represented as a
777 map, hash table, or dict object.
782 <title>Summary of types</title>
785 The following table summarizes the D-Bus types.
790 <entry>Category</entry>
791 <entry>Conventional Name</entry>
793 <entry>Description</entry>
798 <entry>reserved</entry>
799 <entry><literal>INVALID</literal></entry>
800 <entry>0 (ASCII NUL)</entry>
801 <entry>Not a valid type code, used to terminate signatures</entry>
803 <entry>fixed, basic</entry>
804 <entry><literal>BYTE</literal></entry>
805 <entry>121 (ASCII 'y')</entry>
806 <entry>8-bit unsigned integer</entry>
808 <entry>fixed, basic</entry>
809 <entry><literal>BOOLEAN</literal></entry>
810 <entry>98 (ASCII 'b')</entry>
811 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
813 <entry>fixed, basic</entry>
814 <entry><literal>INT16</literal></entry>
815 <entry>110 (ASCII 'n')</entry>
816 <entry>16-bit signed integer</entry>
818 <entry>fixed, basic</entry>
819 <entry><literal>UINT16</literal></entry>
820 <entry>113 (ASCII 'q')</entry>
821 <entry>16-bit unsigned integer</entry>
823 <entry>fixed, basic</entry>
824 <entry><literal>INT32</literal></entry>
825 <entry>105 (ASCII 'i')</entry>
826 <entry>32-bit signed integer</entry>
828 <entry>fixed, basic</entry>
829 <entry><literal>UINT32</literal></entry>
830 <entry>117 (ASCII 'u')</entry>
831 <entry>32-bit unsigned integer</entry>
833 <entry>fixed, basic</entry>
834 <entry><literal>INT64</literal></entry>
835 <entry>120 (ASCII 'x')</entry>
836 <entry>64-bit signed integer</entry>
838 <entry>fixed, basic</entry>
839 <entry><literal>UINT64</literal></entry>
840 <entry>116 (ASCII 't')</entry>
841 <entry>64-bit unsigned integer</entry>
843 <entry>fixed, basic</entry>
844 <entry><literal>DOUBLE</literal></entry>
845 <entry>100 (ASCII 'd')</entry>
846 <entry>IEEE 754 double</entry>
848 <entry>string-like, basic</entry>
849 <entry><literal>STRING</literal></entry>
850 <entry>115 (ASCII 's')</entry>
851 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
853 <entry>string-like, basic</entry>
854 <entry><literal>OBJECT_PATH</literal></entry>
855 <entry>111 (ASCII 'o')</entry>
856 <entry>Name of an object instance</entry>
858 <entry>string-like, basic</entry>
859 <entry><literal>SIGNATURE</literal></entry>
860 <entry>103 (ASCII 'g')</entry>
861 <entry>A type signature</entry>
863 <entry>container</entry>
864 <entry><literal>ARRAY</literal></entry>
865 <entry>97 (ASCII 'a')</entry>
868 <entry>container</entry>
869 <entry><literal>STRUCT</literal></entry>
870 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
871 <entry>Struct; type code 114 'r' is reserved for use in
872 bindings and implementations to represent the general
873 concept of a struct, and must not appear in signatures
874 used on D-Bus.</entry>
876 <entry>container</entry>
877 <entry><literal>VARIANT</literal></entry>
878 <entry>118 (ASCII 'v') </entry>
879 <entry>Variant type (the type of the value is part of the value itself)</entry>
881 <entry>container</entry>
882 <entry><literal>DICT_ENTRY</literal></entry>
883 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
884 <entry>Entry in a dict or map (array of key-value pairs).
885 Type code 101 'e' is reserved for use in bindings and
886 implementations to represent the general concept of a
887 dict or dict-entry, and must not appear in signatures
888 used on D-Bus.</entry>
890 <entry>fixed, basic</entry>
891 <entry><literal>UNIX_FD</literal></entry>
892 <entry>104 (ASCII 'h')</entry>
893 <entry>Unix file descriptor</entry>
896 <entry>reserved</entry>
897 <entry>(reserved)</entry>
898 <entry>109 (ASCII 'm')</entry>
899 <entry>Reserved for <ulink
900 url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
901 'maybe' type compatible with the one in GVariant</ulink>,
902 and must not appear in signatures used on D-Bus until
903 specified here</entry>
906 <entry>reserved</entry>
907 <entry>(reserved)</entry>
908 <entry>42 (ASCII '*')</entry>
909 <entry>Reserved for use in bindings/implementations to
910 represent any <firstterm>single complete type</firstterm>,
911 and must not appear in signatures used on D-Bus.</entry>
914 <entry>reserved</entry>
915 <entry>(reserved)</entry>
916 <entry>63 (ASCII '?')</entry>
917 <entry>Reserved for use in bindings/implementations to
918 represent any <firstterm>basic type</firstterm>, and must
919 not appear in signatures used on D-Bus.</entry>
922 <entry>reserved</entry>
923 <entry>(reserved)</entry>
924 <entry>64 (ASCII '@'), 38 (ASCII '&'),
925 94 (ASCII '^')</entry>
926 <entry>Reserved for internal use by bindings/implementations,
927 and must not appear in signatures used on D-Bus.
928 GVariant uses these type-codes to encode calling
939 <sect1 id="message-protocol-marshaling">
940 <title>Marshaling (Wire Format)</title>
943 D-Bus defines a marshalling format for its type system, which is
944 used in D-Bus messages. This is not the only possible marshalling
945 format for the type system: for instance, GVariant (part of GLib)
946 re-uses the D-Bus type system but implements an alternative marshalling
951 <title>Byte order and alignment</title>
954 Given a type signature, a block of bytes can be converted into typed
955 values. This section describes the format of the block of bytes. Byte
956 order and alignment issues are handled uniformly for all D-Bus types.
960 A block of bytes has an associated byte order. The byte order
961 has to be discovered in some way; for D-Bus messages, the
962 byte order is part of the message header as described in
963 <xref linkend="message-protocol-messages"/>. For now, assume
964 that the byte order is known to be either little endian or big
969 Each value in a block of bytes is aligned "naturally," for example
970 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
971 8-byte boundary. To properly align a value, <firstterm>alignment
972 padding</firstterm> may be necessary. The alignment padding must always
973 be the minimum required padding to properly align the following value;
974 and it must always be made up of nul bytes. The alignment padding must
975 not be left uninitialized (it can't contain garbage), and more padding
976 than required must not be used.
980 As an exception to natural alignment, <literal>STRUCT</literal> and
981 <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
982 boundary, regardless of the alignments of their contents.
987 <title>Marshalling basic types</title>
990 To marshal and unmarshal fixed types, you simply read one value
991 from the data block corresponding to each type code in the signature.
992 All signed integer values are encoded in two's complement, DOUBLE
993 values are IEEE 754 double-precision floating-point, and BOOLEAN
994 values are encoded in 32 bits (of which only the least significant
999 The string-like types are all marshalled as a
1000 fixed-length unsigned integer <varname>n</varname> giving the
1001 length of the variable part, followed by <varname>n</varname>
1002 nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
1003 which is not considered to be part of the text. The alignment
1004 of the string-like type is the same as the alignment of
1005 <varname>n</varname>.
1009 For the STRING and OBJECT_PATH types, <varname>n</varname> is
1010 encoded in 4 bytes, leading to 4-byte alignment.
1011 For the SIGNATURE type, <varname>n</varname> is encoded as a single
1012 byte. As a result, alignment padding is never required before a
1018 <title>Marshalling containers</title>
1021 Arrays are marshalled as a <literal>UINT32</literal>
1022 <varname>n</varname> giving the length of the array data in bytes,
1023 followed by alignment padding to the alignment boundary of the array
1024 element type, followed by the <varname>n</varname> bytes of the
1025 array elements marshalled in sequence. <varname>n</varname> does not
1026 include the padding after the length, or any padding after the
1031 For instance, if the current position in the message is a multiple
1032 of 8 bytes and the byte-order is big-endian, an array containing only
1033 the 64-bit integer 5 would be marshalled as:
1036 00 00 00 08 <lineannotation>8 bytes of data</lineannotation>
1037 00 00 00 00 <lineannotation>padding to 8-byte boundary</lineannotation>
1038 00 00 00 00 00 00 00 05 <lineannotation>first element = 5</lineannotation>
1043 Arrays have a maximum length defined to be 2 to the 26th power or
1044 67108864 (64 MiB). Implementations must not send or accept arrays
1045 exceeding this length.
1049 Structs and dict entries are marshalled in the same way as their
1050 contents, but their alignment is always to an 8-byte boundary,
1051 even if their contents would normally be less strictly aligned.
1055 Variants are marshalled as the <literal>SIGNATURE</literal> of
1056 the contents (which must be a single complete type), followed by a
1057 marshalled value with the type given by that signature. The
1058 variant has the same 1-byte alignment as the signature, which means
1059 that alignment padding before a variant is never needed.
1060 Use of variants may not cause a total message depth to be larger
1061 than 64, including other container types such as structures.
1066 <title>Summary of D-Bus marshalling</title>
1069 Given all this, the types are marshaled on the wire as follows:
1074 <entry>Conventional Name</entry>
1075 <entry>Encoding</entry>
1076 <entry>Alignment</entry>
1081 <entry><literal>INVALID</literal></entry>
1082 <entry>Not applicable; cannot be marshaled.</entry>
1085 <entry><literal>BYTE</literal></entry>
1086 <entry>A single 8-bit byte.</entry>
1089 <entry><literal>BOOLEAN</literal></entry>
1090 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
1093 <entry><literal>INT16</literal></entry>
1094 <entry>16-bit signed integer in the message's byte order.</entry>
1097 <entry><literal>UINT16</literal></entry>
1098 <entry>16-bit unsigned integer in the message's byte order.</entry>
1101 <entry><literal>INT32</literal></entry>
1102 <entry>32-bit signed integer in the message's byte order.</entry>
1105 <entry><literal>UINT32</literal></entry>
1106 <entry>32-bit unsigned integer in the message's byte order.</entry>
1109 <entry><literal>INT64</literal></entry>
1110 <entry>64-bit signed integer in the message's byte order.</entry>
1113 <entry><literal>UINT64</literal></entry>
1114 <entry>64-bit unsigned integer in the message's byte order.</entry>
1117 <entry><literal>DOUBLE</literal></entry>
1118 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
1121 <entry><literal>STRING</literal></entry>
1122 <entry>A <literal>UINT32</literal> indicating the string's
1123 length in bytes excluding its terminating nul, followed by
1124 non-nul string data of the given length, followed by a terminating nul
1131 <entry><literal>OBJECT_PATH</literal></entry>
1132 <entry>Exactly the same as <literal>STRING</literal> except the
1133 content must be a valid object path (see above).
1139 <entry><literal>SIGNATURE</literal></entry>
1140 <entry>The same as <literal>STRING</literal> except the length is a single
1141 byte (thus signatures have a maximum length of 255)
1142 and the content must be a valid signature (see above).
1148 <entry><literal>ARRAY</literal></entry>
1150 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
1151 alignment padding to the alignment boundary of the array element type,
1152 followed by each array element.
1158 <entry><literal>STRUCT</literal></entry>
1160 A struct must start on an 8-byte boundary regardless of the
1161 type of the struct fields. The struct value consists of each
1162 field marshaled in sequence starting from that 8-byte
1169 <entry><literal>VARIANT</literal></entry>
1171 The marshaled <literal>SIGNATURE</literal> of a single
1172 complete type, followed by a marshaled value with the type
1173 given in the signature.
1176 1 (alignment of the signature)
1179 <entry><literal>DICT_ENTRY</literal></entry>
1181 Identical to STRUCT.
1187 <entry><literal>UNIX_FD</literal></entry>
1188 <entry>32-bit unsigned integer in the message's byte
1189 order. The actual file descriptors need to be
1190 transferred out-of-band via some platform specific
1191 mechanism. On the wire, values of this type store the index to the
1192 file descriptor in the array of file descriptors that
1193 accompany the message.</entry>
1205 <sect1 id="message-protocol">
1206 <title>Message Protocol</title>
1209 A <firstterm>message</firstterm> consists of a
1210 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
1211 think of a message as a package, the header is the address, and the body
1212 contains the package contents. The message delivery system uses the header
1213 information to figure out where to send the message and how to interpret
1214 it; the recipient interprets the body of the message.
1218 The body of the message is made up of zero or more
1219 <firstterm>arguments</firstterm>, which are typed values, such as an
1220 integer or a byte array.
1224 Both header and body use the D-Bus <link linkend="type-system">type
1225 system</link> and format for serializing data.
1228 <sect2 id="message-protocol-messages">
1229 <title>Message Format</title>
1232 A message consists of a header and a body. The header is a block of
1233 values with a fixed signature and meaning. The body is a separate block
1234 of values, with a signature specified in the header.
1238 The length of the header must be a multiple of 8, allowing the body to
1239 begin on an 8-byte boundary when storing the entire message in a single
1240 buffer. If the header does not naturally end on an 8-byte boundary
1241 up to 7 bytes of nul-initialized alignment padding must be added.
1245 The message body need not end on an 8-byte boundary.
1249 The maximum length of a message, including header, header alignment padding,
1250 and body is 2 to the 27th power or 134217728 (128 MiB).
1251 Implementations must not send or accept messages exceeding this size.
1255 The signature of the header is:
1259 Written out more readably, this is:
1261 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
1266 These values have the following meanings:
1271 <entry>Value</entry>
1272 <entry>Description</entry>
1277 <entry>1st <literal>BYTE</literal></entry>
1278 <entry>Endianness flag; ASCII 'l' for little-endian
1279 or ASCII 'B' for big-endian. Both header and body are
1280 in this endianness.</entry>
1283 <entry>2nd <literal>BYTE</literal></entry>
1284 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
1285 Currently-defined types are described below.
1289 <entry>3rd <literal>BYTE</literal></entry>
1290 <entry>Bitwise OR of flags. Unknown flags
1291 must be ignored. Currently-defined flags are described below.
1295 <entry>4th <literal>BYTE</literal></entry>
1296 <entry>Major protocol version of the sending application. If
1297 the major protocol version of the receiving application does not
1298 match, the applications will not be able to communicate and the
1299 D-Bus connection must be disconnected. The major protocol
1300 version for this version of the specification is 1.
1304 <entry>1st <literal>UINT32</literal></entry>
1305 <entry>Length in bytes of the message body, starting
1306 from the end of the header. The header ends after
1307 its alignment padding to an 8-boundary.
1311 <entry>2nd <literal>UINT32</literal></entry>
1312 <entry>The serial of this message, used as a cookie
1313 by the sender to identify the reply corresponding
1314 to this request. This must not be zero.
1318 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
1319 <entry>An array of zero or more <firstterm>header
1320 fields</firstterm> where the byte is the field code, and the
1321 variant is the field value. The message type determines
1322 which fields are required.
1330 <firstterm>Message types</firstterm> that can appear in the second byte
1336 <entry>Conventional name</entry>
1337 <entry>Decimal value</entry>
1338 <entry>Description</entry>
1343 <entry><literal>INVALID</literal></entry>
1345 <entry>This is an invalid type.</entry>
1348 <entry><literal>METHOD_CALL</literal></entry>
1350 <entry>Method call. This message type may prompt a
1354 <entry><literal>METHOD_RETURN</literal></entry>
1356 <entry>Method reply with returned data.</entry>
1359 <entry><literal>ERROR</literal></entry>
1361 <entry>Error reply. If the first argument exists and is a
1362 string, it is an error message.</entry>
1365 <entry><literal>SIGNAL</literal></entry>
1367 <entry>Signal emission.</entry>
1374 Flags that can appear in the third byte of the header:
1379 <entry>Conventional name</entry>
1380 <entry>Hex value</entry>
1381 <entry>Description</entry>
1386 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
1390 This message does not expect method return replies or
1391 error replies, even if it is of a type that can
1392 have a reply; the reply should be omitted.
1395 Note that METHOD_CALL is the only message type currently
1396 defined in this specification that can expect a reply,
1397 so the presence or absence of this flag in the other
1398 three message types that are currently
1399 documented is meaningless: replies to those message
1400 types should not be sent, whether this flag is present
1406 <entry><literal>NO_AUTO_START</literal></entry>
1408 <entry>The bus must not launch an owner
1409 for the destination name in response to this message.
1413 <entry><literal>ALLOW_INTERACTIVE_AUTHORIZATION</literal></entry>
1417 This flag may be set on a method call message to
1418 inform the receiving side that the caller is prepared
1419 to wait for interactive authorization, which might
1420 take a considerable time to complete. For instance,
1421 if this flag is set, it would be appropriate to
1422 query the user for passwords or confirmation via
1423 Polkit or a similar framework.
1426 This flag is only useful when
1427 unprivileged code calls a more privileged method call,
1428 and an authorization framework is deployed that allows
1429 possibly interactive authorization. If no such framework
1430 is deployed it has no effect. This flag should not
1431 be set by default by client implementations. If it is
1432 set, the caller should also set a suitably long timeout
1433 on the method call to make sure the user interaction
1434 may complete. This flag is only valid for method call
1435 messages, and shall be ignored otherwise.
1438 Interaction that takes place as a part of the
1439 effect of the method being called is outside the scope
1440 of this flag, even if it could also be characterized
1441 as authentication or authorization. For instance, in
1442 a method call that directs a network management service
1443 to attempt to connect to a virtual private network,
1444 this flag should control how the network management
1445 service makes the decision "is this user allowed to
1446 change system network configuration?", but it should
1447 not affect how or whether the network management
1448 service interacts with the user to obtain the credentials
1449 that are required for access to the VPN.
1452 If a this flag is not set on a method call, and a
1453 service determines that the requested operation is
1454 not allowed without interactive authorization, but
1455 could be allowed after successful interactive
1456 authorization, it may return the
1457 <literal>org.freedesktop.DBus.Error.InteractiveAuthorizationRequired</literal>
1461 The absence of this flag does not guarantee that
1462 interactive authorization will not be applied, since
1463 existing services that pre-date this flag might
1464 already use interactive authorization. However,
1465 existing D-Bus APIs that will use interactive
1466 authorization should document that the call may take
1467 longer than usual, and new D-Bus APIs should avoid
1468 interactive authorization in the absence of this flag.
1477 <sect3 id="message-protocol-header-fields">
1478 <title>Header Fields</title>
1481 The array at the end of the header contains <firstterm>header
1482 fields</firstterm>, where each field is a 1-byte field code followed
1483 by a field value. A header must contain the required header fields for
1484 its message type, and zero or more of any optional header
1485 fields. Future versions of this protocol specification may add new
1486 fields. Implementations must ignore fields they do not
1487 understand. Implementations must not invent their own header fields;
1488 only changes to this specification may introduce new header fields.
1492 Again, if an implementation sees a header field code that it does not
1493 expect, it must ignore that field, as it will be part of a new
1494 (but compatible) version of this specification. This also applies
1495 to known header fields appearing in unexpected messages, for
1496 example: if a signal has a reply serial it must be ignored
1497 even though it has no meaning as of this version of the spec.
1501 However, implementations must not send or accept known header fields
1502 with the wrong type stored in the field value. So for example a
1503 message with an <literal>INTERFACE</literal> field of type
1504 <literal>UINT32</literal> would be considered corrupt.
1508 Here are the currently-defined header fields:
1513 <entry>Conventional Name</entry>
1514 <entry>Decimal Code</entry>
1516 <entry>Required In</entry>
1517 <entry>Description</entry>
1522 <entry><literal>INVALID</literal></entry>
1525 <entry>not allowed</entry>
1526 <entry>Not a valid field name (error if it appears in a message)</entry>
1529 <entry><literal>PATH</literal></entry>
1531 <entry><literal>OBJECT_PATH</literal></entry>
1532 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1533 <entry>The object to send a call to,
1534 or the object a signal is emitted from.
1536 <literal>/org/freedesktop/DBus/Local</literal> is reserved;
1537 implementations should not send messages with this path,
1538 and the reference implementation of the bus daemon will
1539 disconnect any application that attempts to do so.
1543 <entry><literal>INTERFACE</literal></entry>
1545 <entry><literal>STRING</literal></entry>
1546 <entry><literal>SIGNAL</literal></entry>
1548 The interface to invoke a method call on, or
1549 that a signal is emitted from. Optional for
1550 method calls, required for signals.
1551 The special interface
1552 <literal>org.freedesktop.DBus.Local</literal> is reserved;
1553 implementations should not send messages with this
1554 interface, and the reference implementation of the bus
1555 daemon will disconnect any application that attempts to
1560 <entry><literal>MEMBER</literal></entry>
1562 <entry><literal>STRING</literal></entry>
1563 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1564 <entry>The member, either the method name or signal name.</entry>
1567 <entry><literal>ERROR_NAME</literal></entry>
1569 <entry><literal>STRING</literal></entry>
1570 <entry><literal>ERROR</literal></entry>
1571 <entry>The name of the error that occurred, for errors</entry>
1574 <entry><literal>REPLY_SERIAL</literal></entry>
1576 <entry><literal>UINT32</literal></entry>
1577 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
1578 <entry>The serial number of the message this message is a reply
1579 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
1582 <entry><literal>DESTINATION</literal></entry>
1584 <entry><literal>STRING</literal></entry>
1585 <entry>optional</entry>
1586 <entry>The name of the connection this message is intended for.
1587 Only used in combination with the message bus, see
1588 <xref linkend="message-bus"/>.</entry>
1591 <entry><literal>SENDER</literal></entry>
1593 <entry><literal>STRING</literal></entry>
1594 <entry>optional</entry>
1595 <entry>Unique name of the sending connection.
1596 The message bus fills in this field so it is reliable; the field is
1597 only meaningful in combination with the message bus.</entry>
1600 <entry><literal>SIGNATURE</literal></entry>
1602 <entry><literal>SIGNATURE</literal></entry>
1603 <entry>optional</entry>
1604 <entry>The signature of the message body.
1605 If omitted, it is assumed to be the
1606 empty signature "" (i.e. the body must be 0-length).</entry>
1609 <entry><literal>UNIX_FDS</literal></entry>
1611 <entry><literal>UINT32</literal></entry>
1612 <entry>optional</entry>
1613 <entry>The number of Unix file descriptors that
1614 accompany the message. If omitted, it is assumed
1615 that no Unix file descriptors accompany the
1616 message. The actual file descriptors need to be
1617 transferred via platform specific mechanism
1618 out-of-band. They must be sent at the same time as
1619 part of the message itself. They may not be sent
1620 before the first byte of the message itself is
1621 transferred or after the last byte of the message
1631 <sect2 id="message-protocol-names">
1632 <title>Valid Names</title>
1634 The various names in D-Bus messages have some restrictions.
1637 There is a <firstterm>maximum name length</firstterm>
1638 of 255 which applies to bus names, interfaces, and members.
1640 <sect3 id="message-protocol-names-interface">
1641 <title>Interface names</title>
1643 Interfaces have names with type <literal>STRING</literal>, meaning that
1644 they must be valid UTF-8. However, there are also some
1645 additional restrictions that apply to interface names
1648 <listitem><para>Interface names are composed of 1 or more elements separated by
1649 a period ('.') character. All elements must contain at least
1653 <listitem><para>Each element must only contain the ASCII characters
1654 "[A-Z][a-z][0-9]_" and must not begin with a digit.
1658 <listitem><para>Interface names must contain at least one '.' (period)
1659 character (and thus at least two elements).
1662 <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
1663 <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
1668 Interface names should start with the reversed DNS domain name of
1669 the author of the interface (in lower-case), like interface names
1670 in Java. It is conventional for the rest of the interface name
1671 to consist of words run together, with initial capital letters
1672 on all words ("CamelCase"). Several levels of hierarchy can be used.
1673 It is also a good idea to include the major version of the interface
1674 in the name, and increment it if incompatible changes are made;
1675 this way, a single object can implement several versions of an
1676 interface in parallel, if necessary.
1680 For instance, if the owner of <literal>example.com</literal> is
1681 developing a D-Bus API for a music player, they might define
1682 interfaces called <literal>com.example.MusicPlayer1</literal>,
1683 <literal>com.example.MusicPlayer1.Track</literal> and
1684 <literal>com.example.MusicPlayer1.Seekable</literal>.
1688 D-Bus does not distinguish between the concepts that would be
1689 called classes and interfaces in Java: either can be identified on
1690 D-Bus by an interface name.
1693 <sect3 id="message-protocol-names-bus">
1694 <title>Bus names</title>
1696 Connections have one or more bus names associated with them.
1697 A connection has exactly one bus name that is a <firstterm>unique
1698 connection name</firstterm>. The unique connection name remains
1699 with the connection for its entire lifetime.
1700 A bus name is of type <literal>STRING</literal>,
1701 meaning that it must be valid UTF-8. However, there are also
1702 some additional restrictions that apply to bus names
1705 <listitem><para>Bus names that start with a colon (':')
1706 character are unique connection names. Other bus names
1707 are called <firstterm>well-known bus names</firstterm>.
1710 <listitem><para>Bus names are composed of 1 or more elements separated by
1711 a period ('.') character. All elements must contain at least
1715 <listitem><para>Each element must only contain the ASCII characters
1716 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
1717 connection name may begin with a digit, elements in
1718 other bus names must not begin with a digit.
1722 <listitem><para>Bus names must contain at least one '.' (period)
1723 character (and thus at least two elements).
1726 <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
1727 <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
1731 Note that the hyphen ('-') character is allowed in bus names but
1732 not in interface names.
1736 Like <link linkend="message-protocol-names-interface">interface
1737 names</link>, well-known bus names should start with the
1738 reversed DNS domain name of the author of the interface (in
1739 lower-case), and it is conventional for the rest of the well-known
1740 bus name to consist of words run together, with initial
1741 capital letters. As with interface names, including a version
1742 number in well-known bus names is a good idea; it's possible to
1743 have the well-known bus name for more than one version
1744 simultaneously if backwards compatibility is required.
1748 If a well-known bus name implies the presence of a "main" interface,
1749 that "main" interface is often given the same name as
1750 the well-known bus name, and situated at the corresponding object
1751 path. For instance, if the owner of <literal>example.com</literal>
1752 is developing a D-Bus API for a music player, they might define
1753 that any application that takes the well-known name
1754 <literal>com.example.MusicPlayer1</literal> should have an object
1755 at the object path <literal>/com/example/MusicPlayer1</literal>
1756 which implements the interface
1757 <literal>com.example.MusicPlayer1</literal>.
1760 <sect3 id="message-protocol-names-member">
1761 <title>Member names</title>
1763 Member (i.e. method or signal) names:
1765 <listitem><para>Must only contain the ASCII characters
1766 "[A-Z][a-z][0-9]_" and may not begin with a
1767 digit.</para></listitem>
1768 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1769 <listitem><para>Must not exceed the maximum name length.</para></listitem>
1770 <listitem><para>Must be at least 1 byte in length.</para></listitem>
1775 It is conventional for member names on D-Bus to consist of
1776 capitalized words with no punctuation ("camel-case").
1777 Method names should usually be verbs, such as
1778 <literal>GetItems</literal>, and signal names should usually be
1779 a description of an event, such as <literal>ItemsChanged</literal>.
1782 <sect3 id="message-protocol-names-error">
1783 <title>Error names</title>
1785 Error names have the same restrictions as interface names.
1789 Error names have the same naming conventions as interface
1790 names, and often contain <literal>.Error.</literal>; for instance,
1791 the owner of <literal>example.com</literal> might define the
1792 errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
1793 and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
1794 The errors defined by D-Bus itself, such as
1795 <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
1801 <sect2 id="message-protocol-types">
1802 <title>Message Types</title>
1804 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1805 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1806 This section describes these conventions.
1808 <sect3 id="message-protocol-types-method">
1809 <title>Method Calls</title>
1811 Some messages invoke an operation on a remote object. These are
1812 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1813 messages map naturally to methods on objects in a typical program.
1816 A method call message is required to have a <literal>MEMBER</literal> header field
1817 indicating the name of the method. Optionally, the message has an
1818 <literal>INTERFACE</literal> field giving the interface the method is a part of.
1819 Including the <literal>INTERFACE</literal> in all method call
1820 messages is strongly recommended.
1823 In the absence of an <literal>INTERFACE</literal> field, if two
1824 or more interfaces on the same object have a method with the same
1825 name, it is undefined which of those methods will be invoked.
1826 Implementations may choose to either return an error, or deliver the
1827 message as though it had an arbitrary one of those interfaces.
1830 In some situations (such as the well-known system bus), messages
1831 are filtered through an access-control list external to the
1832 remote object implementation. If that filter rejects certain
1833 messages by matching their interface, or accepts only messages
1834 to specific interfaces, it must also reject messages that have no
1835 <literal>INTERFACE</literal>: otherwise, malicious
1836 applications could use this to bypass the filter.
1839 Method call messages also include a <literal>PATH</literal> field
1840 indicating the object to invoke the method on. If the call is passing
1841 through a message bus, the message will also have a
1842 <literal>DESTINATION</literal> field giving the name of the connection
1843 to receive the message.
1846 When an application handles a method call message, it is required to
1847 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1848 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1849 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1852 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1853 are the return value(s) or "out parameters" of the method call.
1854 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1855 and the call fails; no return value will be provided. It makes
1856 no sense to send multiple replies to the same method call.
1859 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1860 reply is required, so the caller will know the method
1861 was successfully processed.
1864 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1868 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1869 then the application receiving the method should not send the reply message (regardless of
1870 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1873 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1874 destination name does not exist then a program to own the destination
1875 name will be started before the message is delivered. The message
1876 will be held until the new program is successfully started or has
1877 failed to start; in case of failure, an error will be returned. This
1878 flag is only relevant in the context of a message bus, it is ignored
1879 during one-to-one communication with no intermediate bus.
1881 <sect4 id="message-protocol-types-method-apis">
1882 <title>Mapping method calls to native APIs</title>
1884 APIs for D-Bus may map method calls to a method call in a specific
1885 programming language, such as C++, or may map a method call written
1886 in an IDL to a D-Bus message.
1889 In APIs of this nature, arguments to a method are often termed "in"
1890 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1891 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1892 "inout" arguments, which are both sent and received, i.e. the caller
1893 passes in a value which is modified. Mapped to D-Bus, an "inout"
1894 argument is equivalent to an "in" argument, followed by an "out"
1895 argument. You can't pass things "by reference" over the wire, so
1896 "inout" is purely an illusion of the in-process API.
1899 Given a method with zero or one return values, followed by zero or more
1900 arguments, where each argument may be "in", "out", or "inout", the
1901 caller constructs a message by appending each "in" or "inout" argument,
1902 in order. "out" arguments are not represented in the caller's message.
1905 The recipient constructs a reply by appending first the return value
1906 if any, then each "out" or "inout" argument, in order.
1907 "in" arguments are not represented in the reply message.
1910 Error replies are normally mapped to exceptions in languages that have
1914 In converting from native APIs to D-Bus, it is perhaps nice to
1915 map D-Bus naming conventions ("FooBar") to native conventions
1916 such as "fooBar" or "foo_bar" automatically. This is OK
1917 as long as you can say that the native API is one that
1918 was specifically written for D-Bus. It makes the most sense
1919 when writing object implementations that will be exported
1920 over the bus. Object proxies used to invoke remote D-Bus
1921 objects probably need the ability to call any D-Bus method,
1922 and thus a magic name mapping like this could be a problem.
1925 This specification doesn't require anything of native API bindings;
1926 the preceding is only a suggested convention for consistency
1932 <sect3 id="message-protocol-types-signal">
1933 <title>Signal Emission</title>
1935 Unlike method calls, signal emissions have no replies.
1936 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1937 It must have three header fields: <literal>PATH</literal> giving the object
1938 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1939 the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
1940 for signals, though it is optional for method calls.
1944 <sect3 id="message-protocol-types-errors">
1945 <title>Errors</title>
1947 Messages of type <literal>ERROR</literal> are most commonly replies
1948 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1949 to any kind of message. The message bus for example
1950 will return an <literal>ERROR</literal> in reply to a signal emission if
1951 the bus does not have enough memory to send the signal.
1954 An <literal>ERROR</literal> may have any arguments, but if the first
1955 argument is a <literal>STRING</literal>, it must be an error message.
1956 The error message may be logged or shown to the user
1961 <sect3 id="message-protocol-types-notation">
1962 <title>Notation in this document</title>
1964 This document uses a simple pseudo-IDL to describe particular method
1965 calls and signals. Here is an example of a method call:
1967 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1968 out UINT32 resultcode)
1970 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1971 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1972 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1973 characters so it's known that the last part of the name in
1974 the "IDL" is the member name.
1977 In C++ that might end up looking like this:
1979 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1980 unsigned int flags);
1982 or equally valid, the return value could be done as an argument:
1984 void org::freedesktop::DBus::StartServiceByName (const char *name,
1986 unsigned int *resultcode);
1988 It's really up to the API designer how they want to make
1989 this look. You could design an API where the namespace wasn't used
1990 in C++, using STL or Qt, using varargs, or whatever you wanted.
1993 Signals are written as follows:
1995 org.freedesktop.DBus.NameLost (STRING name)
1997 Signals don't specify "in" vs. "out" because only
1998 a single direction is possible.
2001 It isn't especially encouraged to use this lame pseudo-IDL in actual
2002 API implementations; you might use the native notation for the
2003 language you're using, or you might use COM or CORBA IDL, for example.
2008 <sect2 id="message-protocol-handling-invalid">
2009 <title>Invalid Protocol and Spec Extensions</title>
2012 For security reasons, the D-Bus protocol should be strictly parsed and
2013 validated, with the exception of defined extension points. Any invalid
2014 protocol or spec violations should result in immediately dropping the
2015 connection without notice to the other end. Exceptions should be
2016 carefully considered, e.g. an exception may be warranted for a
2017 well-understood idiosyncrasy of a widely-deployed implementation. In
2018 cases where the other end of a connection is 100% trusted and known to
2019 be friendly, skipping validation for performance reasons could also make
2020 sense in certain cases.
2024 Generally speaking violations of the "must" requirements in this spec
2025 should be considered possible attempts to exploit security, and violations
2026 of the "should" suggestions should be considered legitimate (though perhaps
2027 they should generate an error in some cases).
2031 The following extension points are built in to D-Bus on purpose and must
2032 not be treated as invalid protocol. The extension points are intended
2033 for use by future versions of this spec, they are not intended for third
2034 parties. At the moment, the only way a third party could extend D-Bus
2035 without breaking interoperability would be to introduce a way to negotiate new
2036 feature support as part of the auth protocol, using EXTENSION_-prefixed
2037 commands. There is not yet a standard way to negotiate features.
2041 In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
2042 commands result in an ERROR rather than a disconnect. This enables
2043 future extensions to the protocol. Commands starting with EXTENSION_ are
2044 reserved for third parties.
2049 The authentication protocol supports pluggable auth mechanisms.
2054 The address format (see <xref linkend="addresses"/>) supports new
2060 Messages with an unknown type (something other than
2061 <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
2062 <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
2063 Unknown-type messages must still be well-formed in the same way
2064 as the known messages, however. They still have the normal
2070 Header fields with an unknown or unexpected field code must be ignored,
2071 though again they must still be well-formed.
2076 New standard interfaces (with new methods and signals) can of course be added.
2086 <sect1 id="auth-protocol">
2087 <title>Authentication Protocol</title>
2089 Before the flow of messages begins, two applications must
2090 authenticate. A simple plain-text protocol is used for
2091 authentication; this protocol is a SASL profile, and maps fairly
2092 directly from the SASL specification. The message encoding is
2093 NOT used here, only plain text messages.
2096 In examples, "C:" and "S:" indicate lines sent by the client and
2097 server respectively.
2099 <sect2 id="auth-protocol-overview">
2100 <title>Protocol Overview</title>
2102 The protocol is a line-based protocol, where each line ends with
2103 \r\n. Each line begins with an all-caps ASCII command name containing
2104 only the character range [A-Z_], a space, then any arguments for the
2105 command, then the \r\n ending the line. The protocol is
2106 case-sensitive. All bytes must be in the ASCII character set.
2108 Commands from the client to the server are as follows:
2111 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
2112 <listitem><para>CANCEL</para></listitem>
2113 <listitem><para>BEGIN</para></listitem>
2114 <listitem><para>DATA <data in hex encoding></para></listitem>
2115 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
2116 <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
2119 From server to client are as follows:
2122 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
2123 <listitem><para>OK <GUID in hex></para></listitem>
2124 <listitem><para>DATA <data in hex encoding></para></listitem>
2125 <listitem><para>ERROR</para></listitem>
2126 <listitem><para>AGREE_UNIX_FD</para></listitem>
2130 Unofficial extensions to the command set must begin with the letters
2131 "EXTENSION_", to avoid conflicts with future official commands.
2132 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
2135 <sect2 id="auth-nul-byte">
2136 <title>Special credentials-passing nul byte</title>
2138 Immediately after connecting to the server, the client must send a
2139 single nul byte. This byte may be accompanied by credentials
2140 information on some operating systems that use sendmsg() with
2141 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
2142 sockets. However, the nul byte must be sent even on other kinds of
2143 socket, and even on operating systems that do not require a byte to be
2144 sent in order to transmit credentials. The text protocol described in
2145 this document begins after the single nul byte. If the first byte
2146 received from the client is not a nul byte, the server may disconnect
2150 A nul byte in any context other than the initial byte is an error;
2151 the protocol is ASCII-only.
2154 The credentials sent along with the nul byte may be used with the
2155 SASL mechanism EXTERNAL.
2158 <sect2 id="auth-command-auth">
2159 <title>AUTH command</title>
2161 If an AUTH command has no arguments, it is a request to list
2162 available mechanisms. The server must respond with a REJECTED
2163 command listing the mechanisms it understands, or with an error.
2166 If an AUTH command specifies a mechanism, and the server supports
2167 said mechanism, the server should begin exchanging SASL
2168 challenge-response data with the client using DATA commands.
2171 If the server does not support the mechanism given in the AUTH
2172 command, it must send either a REJECTED command listing the mechanisms
2173 it does support, or an error.
2176 If the [initial-response] argument is provided, it is intended for use
2177 with mechanisms that have no initial challenge (or an empty initial
2178 challenge), as if it were the argument to an initial DATA command. If
2179 the selected mechanism has an initial challenge and [initial-response]
2180 was provided, the server should reject authentication by sending
2184 If authentication succeeds after exchanging DATA commands,
2185 an OK command must be sent to the client.
2188 The first octet received by the server after the \r\n of the BEGIN
2189 command from the client must be the first octet of the
2190 authenticated/encrypted stream of D-Bus messages.
2193 If BEGIN is received by the server, the first octet received
2194 by the client after the \r\n of the OK command must be the
2195 first octet of the authenticated/encrypted stream of D-Bus
2199 <sect2 id="auth-command-cancel">
2200 <title>CANCEL Command</title>
2202 At any time up to sending the BEGIN command, the client may send a
2203 CANCEL command. On receiving the CANCEL command, the server must
2204 send a REJECTED command and abort the current authentication
2208 <sect2 id="auth-command-data">
2209 <title>DATA Command</title>
2211 The DATA command may come from either client or server, and simply
2212 contains a hex-encoded block of data to be interpreted
2213 according to the SASL mechanism in use.
2216 Some SASL mechanisms support sending an "empty string";
2217 FIXME we need some way to do this.
2220 <sect2 id="auth-command-begin">
2221 <title>BEGIN Command</title>
2223 The BEGIN command acknowledges that the client has received an
2224 OK command from the server, and that the stream of messages
2228 The first octet received by the server after the \r\n of the BEGIN
2229 command from the client must be the first octet of the
2230 authenticated/encrypted stream of D-Bus messages.
2233 <sect2 id="auth-command-rejected">
2234 <title>REJECTED Command</title>
2236 The REJECTED command indicates that the current authentication
2237 exchange has failed, and further exchange of DATA is inappropriate.
2238 The client would normally try another mechanism, or try providing
2239 different responses to challenges.
2241 Optionally, the REJECTED command has a space-separated list of
2242 available auth mechanisms as arguments. If a server ever provides
2243 a list of supported mechanisms, it must provide the same list
2244 each time it sends a REJECTED message. Clients are free to
2245 ignore all lists received after the first.
2248 <sect2 id="auth-command-ok">
2249 <title>OK Command</title>
2251 The OK command indicates that the client has been
2252 authenticated. The client may now proceed with negotiating
2253 Unix file descriptor passing. To do that it shall send
2254 NEGOTIATE_UNIX_FD to the server.
2257 Otherwise, the client must respond to the OK command by
2258 sending a BEGIN command, followed by its stream of messages,
2259 or by disconnecting. The server must not accept additional
2260 commands using this protocol after the BEGIN command has been
2261 received. Further communication will be a stream of D-Bus
2262 messages (optionally encrypted, as negotiated) rather than
2266 If a client sends BEGIN the first octet received by the client
2267 after the \r\n of the OK command must be the first octet of
2268 the authenticated/encrypted stream of D-Bus messages.
2271 The OK command has one argument, which is the GUID of the server.
2272 See <xref linkend="addresses"/> for more on server GUIDs.
2275 <sect2 id="auth-command-error">
2276 <title>ERROR Command</title>
2278 The ERROR command indicates that either server or client did not
2279 know a command, does not accept the given command in the current
2280 context, or did not understand the arguments to the command. This
2281 allows the protocol to be extended; a client or server can send a
2282 command present or permitted only in new protocol versions, and if
2283 an ERROR is received instead of an appropriate response, fall back
2284 to using some other technique.
2287 If an ERROR is sent, the server or client that sent the
2288 error must continue as if the command causing the ERROR had never been
2289 received. However, the the server or client receiving the error
2290 should try something other than whatever caused the error;
2291 if only canceling/rejecting the authentication.
2294 If the D-Bus protocol changes incompatibly at some future time,
2295 applications implementing the new protocol would probably be able to
2296 check for support of the new protocol by sending a new command and
2297 receiving an ERROR from applications that don't understand it. Thus the
2298 ERROR feature of the auth protocol is an escape hatch that lets us
2299 negotiate extensions or changes to the D-Bus protocol in the future.
2302 <sect2 id="auth-command-negotiate-unix-fd">
2303 <title>NEGOTIATE_UNIX_FD Command</title>
2305 The NEGOTIATE_UNIX_FD command indicates that the client
2306 supports Unix file descriptor passing. This command may only
2307 be sent after the connection is authenticated, i.e. after OK
2308 was received by the client. This command may only be sent on
2309 transports that support Unix file descriptor passing.
2312 On receiving NEGOTIATE_UNIX_FD the server must respond with
2313 either AGREE_UNIX_FD or ERROR. It shall respond the former if
2314 the transport chosen supports Unix file descriptor passing and
2315 the server supports this feature. It shall respond the latter
2316 if the transport does not support Unix file descriptor
2317 passing, the server does not support this feature, or the
2318 server decides not to enable file descriptor passing due to
2319 security or other reasons.
2322 <sect2 id="auth-command-agree-unix-fd">
2323 <title>AGREE_UNIX_FD Command</title>
2325 The AGREE_UNIX_FD command indicates that the server supports
2326 Unix file descriptor passing. This command may only be sent
2327 after the connection is authenticated, and the client sent
2328 NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
2329 command may only be sent on transports that support Unix file
2333 On receiving AGREE_UNIX_FD the client must respond with BEGIN,
2334 followed by its stream of messages, or by disconnecting. The
2335 server must not accept additional commands using this protocol
2336 after the BEGIN command has been received. Further
2337 communication will be a stream of D-Bus messages (optionally
2338 encrypted, as negotiated) rather than this protocol.
2341 <sect2 id="auth-command-future">
2342 <title>Future Extensions</title>
2344 Future extensions to the authentication and negotiation
2345 protocol are possible. For that new commands may be
2346 introduced. If a client or server receives an unknown command
2347 it shall respond with ERROR and not consider this fatal. New
2348 commands may be introduced both before, and after
2349 authentication, i.e. both before and after the OK command.
2352 <sect2 id="auth-examples">
2353 <title>Authentication examples</title>
2357 <title>Example of successful magic cookie authentication</title>
2359 (MAGIC_COOKIE is a made up mechanism)
2361 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2367 <title>Example of finding out mechanisms then picking one</title>
2370 S: REJECTED KERBEROS_V4 SKEY
2371 C: AUTH SKEY 7ab83f32ee
2372 S: DATA 8799cabb2ea93e
2373 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2379 <title>Example of client sends unknown command then falls back to regular auth</title>
2383 C: AUTH MAGIC_COOKIE 3736343435313230333039
2389 <title>Example of server doesn't support initial auth mechanism</title>
2391 C: AUTH MAGIC_COOKIE 3736343435313230333039
2392 S: REJECTED KERBEROS_V4 SKEY
2393 C: AUTH SKEY 7ab83f32ee
2394 S: DATA 8799cabb2ea93e
2395 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2401 <title>Example of wrong password or the like followed by successful retry</title>
2403 C: AUTH MAGIC_COOKIE 3736343435313230333039
2404 S: REJECTED KERBEROS_V4 SKEY
2405 C: AUTH SKEY 7ab83f32ee
2406 S: DATA 8799cabb2ea93e
2407 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2409 C: AUTH SKEY 7ab83f32ee
2410 S: DATA 8799cabb2ea93e
2411 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2417 <title>Example of skey cancelled and restarted</title>
2419 C: AUTH MAGIC_COOKIE 3736343435313230333039
2420 S: REJECTED KERBEROS_V4 SKEY
2421 C: AUTH SKEY 7ab83f32ee
2422 S: DATA 8799cabb2ea93e
2425 C: AUTH SKEY 7ab83f32ee
2426 S: DATA 8799cabb2ea93e
2427 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2433 <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
2435 (MAGIC_COOKIE is a made up mechanism)
2437 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2439 C: NEGOTIATE_UNIX_FD
2445 <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
2447 (MAGIC_COOKIE is a made up mechanism)
2449 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2451 C: NEGOTIATE_UNIX_FD
2458 <sect2 id="auth-states">
2459 <title>Authentication state diagrams</title>
2462 This section documents the auth protocol in terms of
2463 a state machine for the client and the server. This is
2464 probably the most robust way to implement the protocol.
2467 <sect3 id="auth-states-client">
2468 <title>Client states</title>
2471 To more precisely describe the interaction between the
2472 protocol state machine and the authentication mechanisms the
2473 following notation is used: MECH(CHALL) means that the
2474 server challenge CHALL was fed to the mechanism MECH, which
2480 CONTINUE(RESP) means continue the auth conversation
2481 and send RESP as the response to the server;
2487 OK(RESP) means that after sending RESP to the server
2488 the client side of the auth conversation is finished
2489 and the server should return "OK";
2495 ERROR means that CHALL was invalid and could not be
2501 Both RESP and CHALL may be empty.
2505 The Client starts by getting an initial response from the
2506 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
2507 the mechanism did not provide an initial response. If the
2508 mechanism returns CONTINUE, the client starts in state
2509 <emphasis>WaitingForData</emphasis>, if the mechanism
2510 returns OK the client starts in state
2511 <emphasis>WaitingForOK</emphasis>.
2515 The client should keep track of available mechanisms and
2516 which it mechanisms it has already attempted. This list is
2517 used to decide which AUTH command to send. When the list is
2518 exhausted, the client should give up and close the
2523 <title><emphasis>WaitingForData</emphasis></title>
2531 MECH(CHALL) returns CONTINUE(RESP) → send
2533 <emphasis>WaitingForData</emphasis>
2537 MECH(CHALL) returns OK(RESP) → send DATA
2538 RESP, goto <emphasis>WaitingForOK</emphasis>
2542 MECH(CHALL) returns ERROR → send ERROR
2543 [msg], goto <emphasis>WaitingForData</emphasis>
2551 Receive REJECTED [mechs] →
2552 send AUTH [next mech], goto
2553 WaitingForData or <emphasis>WaitingForOK</emphasis>
2558 Receive ERROR → send
2560 <emphasis>WaitingForReject</emphasis>
2565 Receive OK → send
2566 BEGIN, terminate auth
2567 conversation, authenticated
2572 Receive anything else → send
2574 <emphasis>WaitingForData</emphasis>
2582 <title><emphasis>WaitingForOK</emphasis></title>
2587 Receive OK → send BEGIN, terminate auth
2588 conversation, <emphasis>authenticated</emphasis>
2593 Receive REJECTED [mechs] → send AUTH [next mech],
2594 goto <emphasis>WaitingForData</emphasis> or
2595 <emphasis>WaitingForOK</emphasis>
2601 Receive DATA → send CANCEL, goto
2602 <emphasis>WaitingForReject</emphasis>
2608 Receive ERROR → send CANCEL, goto
2609 <emphasis>WaitingForReject</emphasis>
2615 Receive anything else → send ERROR, goto
2616 <emphasis>WaitingForOK</emphasis>
2624 <title><emphasis>WaitingForReject</emphasis></title>
2629 Receive REJECTED [mechs] → send AUTH [next mech],
2630 goto <emphasis>WaitingForData</emphasis> or
2631 <emphasis>WaitingForOK</emphasis>
2637 Receive anything else → terminate auth
2638 conversation, disconnect
2647 <sect3 id="auth-states-server">
2648 <title>Server states</title>
2651 For the server MECH(RESP) means that the client response
2652 RESP was fed to the the mechanism MECH, which returns one of
2657 CONTINUE(CHALL) means continue the auth conversation and
2658 send CHALL as the challenge to the client;
2664 OK means that the client has been successfully
2671 REJECTED means that the client failed to authenticate or
2672 there was an error in RESP.
2677 The server starts out in state
2678 <emphasis>WaitingForAuth</emphasis>. If the client is
2679 rejected too many times the server must disconnect the
2684 <title><emphasis>WaitingForAuth</emphasis></title>
2690 Receive AUTH → send REJECTED [mechs], goto
2691 <emphasis>WaitingForAuth</emphasis>
2697 Receive AUTH MECH RESP
2701 MECH not valid mechanism → send REJECTED
2703 <emphasis>WaitingForAuth</emphasis>
2707 MECH(RESP) returns CONTINUE(CHALL) → send
2709 <emphasis>WaitingForData</emphasis>
2713 MECH(RESP) returns OK → send OK, goto
2714 <emphasis>WaitingForBegin</emphasis>
2718 MECH(RESP) returns REJECTED → send REJECTED
2720 <emphasis>WaitingForAuth</emphasis>
2728 Receive BEGIN → terminate
2729 auth conversation, disconnect
2735 Receive ERROR → send REJECTED [mechs], goto
2736 <emphasis>WaitingForAuth</emphasis>
2742 Receive anything else → send
2744 <emphasis>WaitingForAuth</emphasis>
2753 <title><emphasis>WaitingForData</emphasis></title>
2761 MECH(RESP) returns CONTINUE(CHALL) → send
2763 <emphasis>WaitingForData</emphasis>
2767 MECH(RESP) returns OK → send OK, goto
2768 <emphasis>WaitingForBegin</emphasis>
2772 MECH(RESP) returns REJECTED → send REJECTED
2774 <emphasis>WaitingForAuth</emphasis>
2782 Receive BEGIN → terminate auth conversation,
2789 Receive CANCEL → send REJECTED [mechs], goto
2790 <emphasis>WaitingForAuth</emphasis>
2796 Receive ERROR → send REJECTED [mechs], goto
2797 <emphasis>WaitingForAuth</emphasis>
2803 Receive anything else → send ERROR, goto
2804 <emphasis>WaitingForData</emphasis>
2812 <title><emphasis>WaitingForBegin</emphasis></title>
2817 Receive BEGIN → terminate auth conversation,
2818 client authenticated
2824 Receive CANCEL → send REJECTED [mechs], goto
2825 <emphasis>WaitingForAuth</emphasis>
2831 Receive ERROR → send REJECTED [mechs], goto
2832 <emphasis>WaitingForAuth</emphasis>
2838 Receive anything else → send ERROR, goto
2839 <emphasis>WaitingForBegin</emphasis>
2849 <sect2 id="auth-mechanisms">
2850 <title>Authentication mechanisms</title>
2852 This section describes some new authentication mechanisms.
2853 D-Bus also allows any standard SASL mechanism of course.
2855 <sect3 id="auth-mechanisms-sha">
2856 <title>DBUS_COOKIE_SHA1</title>
2858 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
2859 has the ability to read a private file owned by the user being
2860 authenticated. If the client can prove that it has access to a secret
2861 cookie stored in this file, then the client is authenticated.
2862 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
2866 Throughout this description, "hex encoding" must output the digits
2867 from a to f in lower-case; the digits A to F must not be used
2868 in the DBUS_COOKIE_SHA1 mechanism.
2871 Authentication proceeds as follows:
2875 The client sends the username it would like to authenticate
2881 The server sends the name of its "cookie context" (see below); a
2882 space character; the integer ID of the secret cookie the client
2883 must demonstrate knowledge of; a space character; then a
2884 randomly-generated challenge string, all of this hex-encoded into
2890 The client locates the cookie and generates its own
2891 randomly-generated challenge string. The client then concatenates
2892 the server's decoded challenge, a ":" character, its own challenge,
2893 another ":" character, and the cookie. It computes the SHA-1 hash
2894 of this composite string as a hex digest. It concatenates the
2895 client's challenge string, a space character, and the SHA-1 hex
2896 digest, hex-encodes the result and sends it back to the server.
2901 The server generates the same concatenated string used by the
2902 client and computes its SHA-1 hash. It compares the hash with
2903 the hash received from the client; if the two hashes match, the
2904 client is authenticated.
2910 Each server has a "cookie context," which is a name that identifies a
2911 set of cookies that apply to that server. A sample context might be
2912 "org_freedesktop_session_bus". Context names must be valid ASCII,
2913 nonzero length, and may not contain the characters slash ("/"),
2914 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
2915 tab ("\t"), or period ("."). There is a default context,
2916 "org_freedesktop_general" that's used by servers that do not specify
2920 Cookies are stored in a user's home directory, in the directory
2921 <filename>~/.dbus-keyrings/</filename>. This directory must
2922 not be readable or writable by other users. If it is,
2923 clients and servers must ignore it. The directory
2924 contains cookie files named after the cookie context.
2927 A cookie file contains one cookie per line. Each line
2928 has three space-separated fields:
2932 The cookie ID number, which must be a non-negative integer and
2933 may not be used twice in the same file.
2938 The cookie's creation time, in UNIX seconds-since-the-epoch
2944 The cookie itself, a hex-encoded random block of bytes. The cookie
2945 may be of any length, though obviously security increases
2946 as the length increases.
2952 Only server processes modify the cookie file.
2953 They must do so with this procedure:
2957 Create a lockfile name by appending ".lock" to the name of the
2958 cookie file. The server should attempt to create this file
2959 using <literal>O_CREAT | O_EXCL</literal>. If file creation
2960 fails, the lock fails. Servers should retry for a reasonable
2961 period of time, then they may choose to delete an existing lock
2962 to keep users from having to manually delete a stale
2963 lock. <footnote><para>Lockfiles are used instead of real file
2964 locking <literal>fcntl()</literal> because real locking
2965 implementations are still flaky on network
2966 filesystems.</para></footnote>
2971 Once the lockfile has been created, the server loads the cookie
2972 file. It should then delete any cookies that are old (the
2973 timeout can be fairly short), or more than a reasonable
2974 time in the future (so that cookies never accidentally
2975 become permanent, if the clock was set far into the future
2976 at some point). If no recent keys remain, the
2977 server may generate a new key.
2982 The pruned and possibly added-to cookie file
2983 must be resaved atomically (using a temporary
2984 file which is rename()'d).
2989 The lock must be dropped by deleting the lockfile.
2995 Clients need not lock the file in order to load it,
2996 because servers are required to save the file atomically.
3001 <sect1 id="addresses">
3002 <title>Server Addresses</title>
3004 Server addresses consist of a transport name followed by a colon, and
3005 then an optional, comma-separated list of keys and values in the form key=value.
3006 Each value is escaped.
3010 <programlisting>unix:path=/tmp/dbus-test</programlisting>
3011 Which is the address to a unix socket with the path /tmp/dbus-test.
3014 Value escaping is similar to URI escaping but simpler.
3018 The set of optionally-escaped bytes is:
3019 <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
3020 <emphasis>byte</emphasis> (note, not character) which is not in the
3021 set of optionally-escaped bytes must be replaced with an ASCII
3022 percent (<literal>%</literal>) and the value of the byte in hex.
3023 The hex value must always be two digits, even if the first digit is
3024 zero. The optionally-escaped bytes may be escaped if desired.
3029 To unescape, append each byte in the value; if a byte is an ASCII
3030 percent (<literal>%</literal>) character then append the following
3031 hex value instead. It is an error if a <literal>%</literal> byte
3032 does not have two hex digits following. It is an error if a
3033 non-optionally-escaped byte is seen unescaped.
3037 The set of optionally-escaped bytes is intended to preserve address
3038 readability and convenience.
3042 A server may specify a key-value pair with the key <literal>guid</literal>
3043 and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
3044 describes the format of the <literal>guid</literal> field. If present,
3045 this UUID may be used to distinguish one server address from another. A
3046 server should use a different UUID for each address it listens on. For
3047 example, if a message bus daemon offers both UNIX domain socket and TCP
3048 connections, but treats clients the same regardless of how they connect,
3049 those two connections are equivalent post-connection but should have
3050 distinct UUIDs to distinguish the kinds of connection.
3054 The intent of the address UUID feature is to allow a client to avoid
3055 opening multiple identical connections to the same server, by allowing the
3056 client to check whether an address corresponds to an already-existing
3057 connection. Comparing two addresses is insufficient, because addresses
3058 can be recycled by distinct servers, and equivalent addresses may look
3059 different if simply compared as strings (for example, the host in a TCP
3060 address can be given as an IP address or as a hostname).
3064 Note that the address key is <literal>guid</literal> even though the
3065 rest of the API and documentation says "UUID," for historical reasons.
3069 [FIXME clarify if attempting to connect to each is a requirement
3070 or just a suggestion]
3071 When connecting to a server, multiple server addresses can be
3072 separated by a semi-colon. The library will then try to connect
3073 to the first address and if that fails, it'll try to connect to
3074 the next one specified, and so forth. For example
3075 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
3079 Some addresses are <firstterm>connectable</firstterm>. A connectable
3080 address is one containing enough information for a client to connect
3081 to it. For instance, <literal>tcp:host=127.0.0.1,port=4242</literal>
3082 is a connectable address. It is not necessarily possible to listen
3083 on every connectable address: for instance, it is not possible to
3084 listen on a <literal>unixexec:</literal> address.
3088 Some addresses are <firstterm>listenable</firstterm>. A listenable
3089 address is one containing enough information for a server to listen on
3090 it, producing a connectable address (which may differ from the
3091 original address). Many listenable addresses are not connectable:
3092 for instance, <literal>tcp:host=127.0.0.1</literal>
3093 is listenable, but not connectable (because it does not specify
3098 Listening on an address that is not connectable will result in a
3099 connectable address that is not the same as the listenable address.
3100 For instance, listening on <literal>tcp:host=127.0.0.1</literal>
3101 might result in the connectable address
3102 <literal>tcp:host=127.0.0.1,port=30958</literal>,
3103 listening on <literal>unix:tmpdir=/tmp</literal>
3104 might result in the connectable address
3105 <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>, or
3106 listening on <literal>unix:runtime=yes</literal>
3107 might result in the connectable address
3108 <literal>unix:path=/run/user/1234/bus</literal>.
3112 <sect1 id="transports">
3113 <title>Transports</title>
3115 [FIXME we need to specify in detail each transport and its possible arguments]
3117 Current transports include: unix domain sockets (including
3118 abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
3119 using in-process pipes. Future possible transports include one that
3120 tunnels over X11 protocol.
3123 <sect2 id="transports-unix-domain-sockets">
3124 <title>Unix Domain Sockets</title>
3126 Unix domain sockets can be either paths in the file system or on Linux
3127 kernels, they can be abstract which are similar to paths but
3128 do not show up in the file system.
3132 When a socket is opened by the D-Bus library it truncates the path
3133 name right before the first trailing Nul byte. This is true for both
3134 normal paths and abstract paths. Note that this is a departure from
3135 previous versions of D-Bus that would create sockets with a fixed
3136 length path name. Names which were shorter than the fixed length
3137 would be padded by Nul bytes.
3140 Unix domain sockets are not available on Windows.
3143 Unix addresses that specify <literal>path</literal> or
3144 <literal>abstract</literal> are both listenable and connectable.
3145 Unix addresses that specify <literal>tmpdir</literal> are only
3146 listenable: the corresponding connectable address will specify
3147 either <literal>path</literal> or <literal>abstract</literal>.
3148 Similarly, Unix addresses that specify <literal>runtime</literal>
3149 are only listenable, and the corresponding connectable address
3150 will specify <literal>path</literal>.
3152 <sect3 id="transports-unix-domain-sockets-addresses">
3153 <title>Server Address Format</title>
3155 Unix domain socket addresses are identified by the "unix:" prefix
3156 and support the following key/value pairs:
3163 <entry>Values</entry>
3164 <entry>Description</entry>
3170 <entry>(path)</entry>
3171 <entry>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</entry>
3174 <entry>tmpdir</entry>
3175 <entry>(path)</entry>
3176 <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>
3179 <entry>abstract</entry>
3180 <entry>(string)</entry>
3181 <entry>unique string (path) in the abstract namespace. If set, the "path" or "tmpdir" key must not be set. This key is only supported on platforms with "abstract Unix sockets", of which Linux is the only known example.</entry>
3184 <entry>runtime</entry>
3185 <entry><literal>yes</literal></entry>
3186 <entry>If given, This key can only be used in server addresses, not in client addresses. If set, its value must be <literal>yes</literal>. This is typically used in an address string like <literal>unix:runtime=yes;unix:tmpdir=/tmp</literal> so that there can be a fallback if <literal>XDG_RUNTIME_DIR</literal> is not set.</entry>
3192 Exactly one of the keys <literal>path</literal>,
3193 <literal>abstract</literal>, <literal>runtime</literal> or
3194 <literal>tmpdir</literal> must be provided.
3198 <sect2 id="transports-launchd">
3199 <title>launchd</title>
3201 launchd is an open-source server management system that replaces init, inetd
3202 and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
3203 bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
3207 launchd allocates a socket and provides it with the unix path through the
3208 DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
3209 spawned by launchd (or dbus-daemon, if it was started by launchd) can access
3210 it through its environment.
3211 Other processes can query for the launchd socket by executing:
3212 $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
3213 This is normally done by the D-Bus client library so doesn't have to be done
3217 launchd is not available on Microsoft Windows.
3220 launchd addresses are listenable and connectable.
3222 <sect3 id="transports-launchd-addresses">
3223 <title>Server Address Format</title>
3225 launchd addresses are identified by the "launchd:" prefix
3226 and support the following key/value pairs:
3233 <entry>Values</entry>
3234 <entry>Description</entry>
3240 <entry>(environment variable)</entry>
3241 <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
3247 The <literal>env</literal> key is required.
3251 <sect2 id="transports-systemd">
3252 <title>systemd</title>
3254 systemd is an open-source server management system that
3255 replaces init and inetd on newer Linux systems. It supports
3256 socket activation. The D-Bus systemd transport is used to acquire
3257 socket activation file descriptors from systemd and use them
3258 as D-Bus transport when the current process is spawned by
3259 socket activation from it.
3262 The systemd transport accepts only one or more Unix domain or
3263 TCP streams sockets passed in via socket activation.
3266 The systemd transport is not available on non-Linux operating systems.
3269 The systemd transport defines no parameter keys.
3272 systemd addresses are listenable, but not connectable. The
3273 corresponding connectable address is the <literal>unix</literal>
3274 or <literal>tcp</literal> address of the socket.
3277 <sect2 id="transports-tcp-sockets">
3278 <title>TCP Sockets</title>
3280 The tcp transport provides TCP/IP based connections between clients
3281 located on the same or different hosts.
3284 Using tcp transport without any additional secure authentification mechanismus
3285 over a network is unsecure.
3288 On Windows and most Unix platforms, the TCP stack is unable to transfer
3289 credentials over a TCP connection, so the EXTERNAL authentication
3290 mechanism does not work for this transport.
3293 All <literal>tcp</literal> addresses are listenable.
3294 <literal>tcp</literal> addresses in which both
3295 <literal>host</literal> and <literal>port</literal> are
3296 specified, and <literal>port</literal> is non-zero,
3297 are also connectable.
3299 <sect3 id="transports-tcp-sockets-addresses">
3300 <title>Server Address Format</title>
3302 TCP/IP socket addresses are identified by the "tcp:" prefix
3303 and support the following key/value pairs:
3310 <entry>Values</entry>
3311 <entry>Description</entry>
3317 <entry>(string)</entry>
3318 <entry>DNS name or IP address</entry>
3322 <entry>(string)</entry>
3323 <entry>Used in a listenable address to configure the interface
3324 on which the server will listen: either the IP address of one of
3325 the local machine's interfaces (most commonly <literal>127.0.0.1
3326 </literal>), or a DNS name that resolves to one of those IP
3327 addresses, or '*' to listen on all interfaces simultaneously.
3328 If not specified, the default is the same value as "host".
3333 <entry>(number)</entry>
3334 <entry>The tcp port the server will open. A zero value let the server
3335 choose a free port provided from the underlaying operating system.
3336 libdbus is able to retrieve the real used port from the server.
3340 <entry>family</entry>
3341 <entry>(string)</entry>
3342 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3349 <sect2 id="transports-nonce-tcp-sockets">
3350 <title>Nonce-secured TCP Sockets</title>
3352 The nonce-tcp transport provides a secured TCP transport, using a
3353 simple authentication mechanism to ensure that only clients with read
3354 access to a certain location in the filesystem can connect to the server.
3355 The server writes a secret, the nonce, to a file and an incoming client
3356 connection is only accepted if the client sends the nonce right after
3357 the connect. The nonce mechanism requires no setup and is orthogonal to
3358 the higher-level authentication mechanisms described in the
3359 Authentication section.
3363 On start, the server generates a random 16 byte nonce and writes it
3364 to a file in the user's temporary directory. The nonce file location
3365 is published as part of the server's D-Bus address using the
3366 "noncefile" key-value pair.
3368 After an accept, the server reads 16 bytes from the socket. If the
3369 read bytes do not match the nonce stored in the nonce file, the
3370 server MUST immediately drop the connection.
3371 If the nonce match the received byte sequence, the client is accepted
3372 and the transport behaves like an unsecured tcp transport.
3375 After a successful connect to the server socket, the client MUST read
3376 the nonce from the file published by the server via the noncefile=
3377 key-value pair and send it over the socket. After that, the
3378 transport behaves like an unsecured tcp transport.
3381 All nonce-tcp addresses are listenable. nonce-tcp addresses in which
3382 <literal>host</literal>, <literal>port</literal> and
3383 <literal>noncefile</literal> are all specified,
3384 and <literal>port</literal> is nonzero, are also connectable.
3386 <sect3 id="transports-nonce-tcp-sockets-addresses">
3387 <title>Server Address Format</title>
3389 Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
3390 and support the following key/value pairs:
3397 <entry>Values</entry>
3398 <entry>Description</entry>
3404 <entry>(string)</entry>
3405 <entry>DNS name or IP address</entry>
3409 <entry>(string)</entry>
3410 <entry>The same as for tcp: addresses
3415 <entry>(number)</entry>
3416 <entry>The tcp port the server will open. A zero value let the server
3417 choose a free port provided from the underlaying operating system.
3418 libdbus is able to retrieve the real used port from the server.
3422 <entry>family</entry>
3423 <entry>(string)</entry>
3424 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3427 <entry>noncefile</entry>
3428 <entry>(path)</entry>
3429 <entry>File location containing the secret.
3430 This is only meaningful in connectable addresses:
3431 a listening D-Bus server that offers this transport
3432 will always create a new nonce file.</entry>
3439 <sect2 id="transports-exec">
3440 <title>Executed Subprocesses on Unix</title>
3442 This transport forks off a process and connects its standard
3443 input and standard output with an anonymous Unix domain
3444 socket. This socket is then used for communication by the
3445 transport. This transport may be used to use out-of-process
3446 forwarder programs as basis for the D-Bus protocol.
3449 The forked process will inherit the standard error output and
3450 process group from the parent process.
3453 Executed subprocesses are not available on Windows.
3456 <literal>unixexec</literal> addresses are connectable, but are not
3459 <sect3 id="transports-exec-addresses">
3460 <title>Server Address Format</title>
3462 Executed subprocess addresses are identified by the "unixexec:" prefix
3463 and support the following key/value pairs:
3470 <entry>Values</entry>
3471 <entry>Description</entry>
3477 <entry>(path)</entry>
3478 <entry>Path of the binary to execute, either an absolute
3479 path or a binary name that is searched for in the default
3480 search path of the OS. This corresponds to the first
3481 argument of execlp(). This key is mandatory.</entry>
3484 <entry>argv0</entry>
3485 <entry>(string)</entry>
3486 <entry>The program name to use when executing the
3487 binary. If omitted the same value as specified for path=
3488 will be used. This corresponds to the second argument of
3492 <entry>argv1, argv2, ...</entry>
3493 <entry>(string)</entry>
3494 <entry>Arguments to pass to the binary. This corresponds
3495 to the third and later arguments of execlp(). If a
3496 specific argvX is not specified no further argvY for Y > X
3497 are taken into account.</entry>
3505 <sect1 id="meta-transports">
3506 <title>Meta Transports</title>
3508 Meta transports are a kind of transport with special enhancements or
3509 behavior. Currently available meta transports include: autolaunch
3512 <sect2 id="meta-transports-autolaunch">
3513 <title>Autolaunch</title>
3514 <para>The autolaunch transport provides a way for dbus clients to autodetect
3515 a running dbus session bus and to autolaunch a session bus if not present.
3518 On Unix, <literal>autolaunch</literal> addresses are connectable,
3522 On Windows, <literal>autolaunch</literal> addresses are both
3523 connectable and listenable.
3526 <sect3 id="meta-transports-autolaunch-addresses">
3527 <title>Server Address Format</title>
3529 Autolaunch addresses uses the "autolaunch:" prefix and support the
3530 following key/value pairs:
3537 <entry>Values</entry>
3538 <entry>Description</entry>
3543 <entry>scope</entry>
3544 <entry>(string)</entry>
3545 <entry>scope of autolaunch (Windows only)
3549 "*install-path" - limit session bus to dbus installation path.
3550 The dbus installation path is determined from the location of
3551 the shared dbus library. If the library is located in a 'bin'
3552 subdirectory the installation root is the directory above,
3553 otherwise the directory where the library lives is taken as
3556 <install-root>/bin/[lib]dbus-1.dll
3557 <install-root>/[lib]dbus-1.dll
3563 "*user" - limit session bus to the recent user.
3568 other values - specify dedicated session bus like "release",
3580 <sect3 id="meta-transports-autolaunch-windows-implementation">
3581 <title>Windows implementation</title>
3583 On start, the server opens a platform specific transport, creates a mutex
3584 and a shared memory section containing the related session bus address.
3585 This mutex will be inspected by the dbus client library to detect a
3586 running dbus session bus. The access to the mutex and the shared memory
3587 section are protected by global locks.
3590 In the recent implementation the autolaunch transport uses a tcp transport
3591 on localhost with a port choosen from the operating system. This detail may
3592 change in the future.
3595 Disclaimer: The recent implementation is in an early state and may not
3596 work in all cirumstances and/or may have security issues. Because of this
3597 the implementation is not documentated yet.
3604 <title>UUIDs</title>
3606 A working D-Bus implementation uses universally-unique IDs in two places.
3607 First, each server address has a UUID identifying the address,
3608 as described in <xref linkend="addresses"/>. Second, each operating
3609 system kernel instance running a D-Bus client or server has a UUID
3610 identifying that kernel, retrieved by invoking the method
3611 org.freedesktop.DBus.Peer.GetMachineId() (see <xref
3612 linkend="standard-interfaces-peer"/>).
3615 The term "UUID" in this document is intended literally, i.e. an
3616 identifier that is universally unique. It is not intended to refer to
3617 RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
3620 The UUID must contain 128 bits of data and be hex-encoded. The
3621 hex-encoded string may not contain hyphens or other non-hex-digit
3622 characters, and it must be exactly 32 characters long. To generate a
3623 UUID, the current reference implementation concatenates 96 bits of random
3624 data followed by the 32-bit time in seconds since the UNIX epoch (in big
3628 It would also be acceptable and probably better to simply generate 128
3629 bits of random data, as long as the random number generator is of high
3630 quality. The timestamp could conceivably help if the random bits are not
3631 very random. With a quality random number generator, collisions are
3632 extremely unlikely even with only 96 bits, so it's somewhat academic.
3635 Implementations should, however, stick to random data for the first 96 bits
3640 <sect1 id="standard-interfaces">
3641 <title>Standard Interfaces</title>
3643 See <xref linkend="message-protocol-types-notation"/> for details on
3644 the notation used in this section. There are some standard interfaces
3645 that may be useful across various D-Bus applications.
3647 <sect2 id="standard-interfaces-peer">
3648 <title><literal>org.freedesktop.DBus.Peer</literal></title>
3650 The <literal>org.freedesktop.DBus.Peer</literal> interface
3653 org.freedesktop.DBus.Peer.Ping ()
3654 org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
3658 On receipt of the <literal>METHOD_CALL</literal> message
3659 <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
3660 nothing other than reply with a <literal>METHOD_RETURN</literal> as
3661 usual. It does not matter which object path a ping is sent to. The
3662 reference implementation handles this method automatically.
3665 On receipt of the <literal>METHOD_CALL</literal> message
3666 <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
3667 reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
3668 UUID representing the identity of the machine the process is running on.
3669 This UUID must be the same for all processes on a single system at least
3670 until that system next reboots. It should be the same across reboots
3671 if possible, but this is not always possible to implement and is not
3673 It does not matter which object path a GetMachineId is sent to. The
3674 reference implementation handles this method automatically.
3677 The UUID is intended to be per-instance-of-the-operating-system, so may represent
3678 a virtual machine running on a hypervisor, rather than a physical machine.
3679 Basically if two processes see the same UUID, they should also see the same
3680 shared memory, UNIX domain sockets, process IDs, and other features that require
3681 a running OS kernel in common between the processes.
3684 The UUID is often used where other programs might use a hostname. Hostnames
3685 can change without rebooting, however, or just be "localhost" - so the UUID
3689 <xref linkend="uuids"/> explains the format of the UUID.
3693 <sect2 id="standard-interfaces-introspectable">
3694 <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
3696 This interface has one method:
3698 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
3702 Objects instances may implement
3703 <literal>Introspect</literal> which returns an XML description of
3704 the object, including its interfaces (with signals and methods), objects
3705 below it in the object path tree, and its properties.
3708 <xref linkend="introspection-format"/> describes the format of this XML string.
3711 <sect2 id="standard-interfaces-properties">
3712 <title><literal>org.freedesktop.DBus.Properties</literal></title>
3714 Many native APIs will have a concept of object <firstterm>properties</firstterm>
3715 or <firstterm>attributes</firstterm>. These can be exposed via the
3716 <literal>org.freedesktop.DBus.Properties</literal> interface.
3720 org.freedesktop.DBus.Properties.Get (in STRING interface_name,
3721 in STRING property_name,
3723 org.freedesktop.DBus.Properties.Set (in STRING interface_name,
3724 in STRING property_name,
3726 org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
3727 out DICT<STRING,VARIANT> props);
3731 It is conventional to give D-Bus properties names consisting of
3732 capitalized words without punctuation ("CamelCase"), like
3733 <link linkend="message-protocol-names-member">member names</link>.
3734 For instance, the GObject property
3735 <literal>connection-status</literal> or the Qt property
3736 <literal>connectionStatus</literal> could be represented on D-Bus
3737 as <literal>ConnectionStatus</literal>.
3740 Strictly speaking, D-Bus property names are not required to follow
3741 the same naming restrictions as member names, but D-Bus property
3742 names that would not be valid member names (in particular,
3743 GObject-style dash-separated property names) can cause interoperability
3744 problems and should be avoided.
3747 The available properties and whether they are writable can be determined
3748 by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
3749 see <xref linkend="standard-interfaces-introspectable"/>.
3752 An empty string may be provided for the interface name; in this case,
3753 if there are multiple properties on an object with the same name,
3754 the results are undefined (picking one by according to an arbitrary
3755 deterministic rule, or returning an error, are the reasonable
3759 If one or more properties change on an object, the
3760 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3761 signal may be emitted (this signal was added in 0.14):
3765 org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
3766 DICT<STRING,VARIANT> changed_properties,
3767 ARRAY<STRING> invalidated_properties);
3771 where <literal>changed_properties</literal> is a dictionary
3772 containing the changed properties with the new values and
3773 <literal>invalidated_properties</literal> is an array of
3774 properties that changed but the value is not conveyed.
3777 Whether the <literal>PropertiesChanged</literal> signal is
3778 supported can be determined by calling
3779 <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
3780 that the signal may be supported for an object but it may
3781 differ how whether and how it is used on a per-property basis
3782 (for e.g. performance or security reasons). Each property (or
3783 the parent interface) must be annotated with the
3784 <literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
3785 annotation to convey this (usually the default value
3786 <literal>true</literal> is sufficient meaning that the
3787 annotation does not need to be used). See <xref
3788 linkend="introspection-format"/> for details on this
3793 <sect2 id="standard-interfaces-objectmanager">
3794 <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
3796 An API can optionally make use of this interface for one or
3797 more sub-trees of objects. The root of each sub-tree implements
3798 this interface so other applications can get all objects,
3799 interfaces and properties in a single method call. It is
3800 appropriate to use this interface if users of the tree of
3801 objects are expected to be interested in all interfaces of all
3802 objects in the tree; a more granular API should be used if
3803 users of the objects are expected to be interested in a small
3804 subset of the objects, a small subset of their interfaces, or
3808 The method that applications can use to get all objects and
3809 properties is <literal>GetManagedObjects</literal>:
3813 org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties);
3817 The return value of this method is a dict whose keys are
3818 object paths. All returned object paths are children of the
3819 object path implementing this interface, i.e. their object
3820 paths start with the ObjectManager's object path plus '/'.
3823 Each value is a dict whose keys are interfaces names. Each
3824 value in this inner dict is the same dict that would be
3825 returned by the <link
3826 linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
3827 method for that combination of object path and interface. If
3828 an interface has no properties, the empty dict is returned.
3831 Changes are emitted using the following two signals:
3835 org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
3836 DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties);
3837 org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
3838 ARRAY<STRING> interfaces);
3842 The <literal>InterfacesAdded</literal> signal is emitted when
3843 either a new object is added or when an existing object gains
3844 one or more interfaces. The
3845 <literal>InterfacesRemoved</literal> signal is emitted
3846 whenever an object is removed or it loses one or more
3847 interfaces. The second parameter of the
3848 <literal>InterfacesAdded</literal> signal contains a dict with
3849 the interfaces and properties (if any) that have been added to
3850 the given object path. Similarly, the second parameter of the
3851 <literal>InterfacesRemoved</literal> signal contains an array
3852 of the interfaces that were removed. Note that changes on
3853 properties on existing interfaces are not reported using this
3854 interface - an application should also monitor the existing <link
3855 linkend="standard-interfaces-properties">PropertiesChanged</link>
3856 signal on each object.
3859 Applications SHOULD NOT export objects that are children of an
3860 object (directly or otherwise) implementing this interface but
3861 which are not returned in the reply from the
3862 <literal>GetManagedObjects()</literal> method of this
3863 interface on the given object.
3866 The intent of the <literal>ObjectManager</literal> interface
3867 is to make it easy to write a robust client
3868 implementation. The trivial client implementation only needs
3869 to make two method calls:
3873 org.freedesktop.DBus.AddMatch (bus_proxy,
3874 "type='signal',name='org.example.App',path_namespace='/org/example/App'");
3875 objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
3879 on the message bus and the remote application's
3880 <literal>ObjectManager</literal>, respectively. Whenever a new
3881 remote object is created (or an existing object gains a new
3882 interface), the <literal>InterfacesAdded</literal> signal is
3883 emitted, and since this signal contains all properties for the
3884 interfaces, no calls to the
3885 <literal>org.freedesktop.Properties</literal> interface on the
3886 remote object are needed. Additionally, since the initial
3887 <literal>AddMatch()</literal> rule already includes signal
3888 messages from the newly created child object, no new
3889 <literal>AddMatch()</literal> call is needed.
3894 The <literal>org.freedesktop.DBus.ObjectManager</literal>
3895 interface was added in version 0.17 of the D-Bus
3902 <sect1 id="introspection-format">
3903 <title>Introspection Data Format</title>
3905 As described in <xref linkend="standard-interfaces-introspectable"/>,
3906 objects may be introspected at runtime, returning an XML string
3907 that describes the object. The same XML format may be used in
3908 other contexts as well, for example as an "IDL" for generating
3909 static language bindings.
3912 Here is an example of introspection data:
3914 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
3915 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
3916 <node name="/com/example/sample_object">
3917 <interface name="com.example.SampleInterface">
3918 <method name="Frobate">
3919 <arg name="foo" type="i" direction="in"/>
3920 <arg name="bar" type="s" direction="out"/>
3921 <arg name="baz" type="a{us}" direction="out"/>
3922 <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
3924 <method name="Bazify">
3925 <arg name="bar" type="(iiu)" direction="in"/>
3926 <arg name="bar" type="v" direction="out"/>
3928 <method name="Mogrify">
3929 <arg name="bar" type="(iiav)" direction="in"/>
3931 <signal name="Changed">
3932 <arg name="new_value" type="b"/>
3934 <property name="Bar" type="y" access="readwrite"/>
3936 <node name="child_of_sample_object"/>
3937 <node name="another_child_of_sample_object"/>
3942 A more formal DTD and spec needs writing, but here are some quick notes.
3946 Only the root <node> element can omit the node name, as it's
3947 known to be the object that was introspected. If the root
3948 <node> does have a name attribute, it must be an absolute
3949 object path. If child <node> have object paths, they must be
3955 If a child <node> has any sub-elements, then they
3956 must represent a complete introspection of the child.
3957 If a child <node> is empty, then it may or may
3958 not have sub-elements; the child must be introspected
3959 in order to find out. The intent is that if an object
3960 knows that its children are "fast" to introspect
3961 it can go ahead and return their information, but
3962 otherwise it can omit it.
3967 The direction element on <arg> may be omitted,
3968 in which case it defaults to "in" for method calls
3969 and "out" for signals. Signals only allow "out"
3970 so while direction may be specified, it's pointless.
3975 The possible directions are "in" and "out",
3976 unlike CORBA there is no "inout"
3981 The possible property access flags are
3982 "readwrite", "read", and "write"
3987 Multiple interfaces can of course be listed for
3993 The "name" attribute on arguments is optional.
3999 Method, interface, property, and signal elements may have
4000 "annotations", which are generic key/value pairs of metadata.
4001 They are similar conceptually to Java's annotations and C# attributes.
4002 Well-known annotations:
4009 <entry>Values (separated by ,)</entry>
4010 <entry>Description</entry>
4015 <entry>org.freedesktop.DBus.Deprecated</entry>
4016 <entry>true,false</entry>
4017 <entry>Whether or not the entity is deprecated; defaults to false</entry>
4020 <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
4021 <entry>(string)</entry>
4022 <entry>The C symbol; may be used for methods and interfaces</entry>
4025 <entry>org.freedesktop.DBus.Method.NoReply</entry>
4026 <entry>true,false</entry>
4027 <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
4030 <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
4031 <entry>true,invalidates,const,false</entry>
4034 If set to <literal>false</literal>, the
4035 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
4037 linkend="standard-interfaces-properties"/> is not
4038 guaranteed to be emitted if the property changes.
4041 If set to <literal>const</literal> the property never
4042 changes value during the lifetime of the object it
4043 belongs to, and hence the signal is never emitted for
4047 If set to <literal>invalidates</literal> the signal
4048 is emitted but the value is not included in the
4052 If set to <literal>true</literal> the signal is
4053 emitted with the value included.
4056 The value for the annotation defaults to
4057 <literal>true</literal> if the enclosing interface
4058 element does not specify the annotation. Otherwise it
4059 defaults to the value specified in the enclosing
4063 This annotation is intended to be used by code
4064 generators to implement client-side caching of
4065 property values. For all properties for which the
4066 annotation is set to <literal>const</literal>,
4067 <literal>invalidates</literal> or
4068 <literal>true</literal> the client may
4069 unconditionally cache the values as the properties
4070 don't change or notifications are generated for them
4079 <sect1 id="message-bus">
4080 <title>Message Bus Specification</title>
4081 <sect2 id="message-bus-overview">
4082 <title>Message Bus Overview</title>
4084 The message bus accepts connections from one or more applications.
4085 Once connected, applications can exchange messages with other
4086 applications that are also connected to the bus.
4089 In order to route messages among connections, the message bus keeps a
4090 mapping from names to connections. Each connection has one
4091 unique-for-the-lifetime-of-the-bus name automatically assigned.
4092 Applications may request additional names for a connection. Additional
4093 names are usually "well-known names" such as
4094 "com.example.TextEditor". When a name is bound to a connection,
4095 that connection is said to <firstterm>own</firstterm> the name.
4098 The bus itself owns a special name,
4099 <literal>org.freedesktop.DBus</literal>, with an object
4100 located at <literal>/org/freedesktop/DBus</literal> that
4101 implements the <literal>org.freedesktop.DBus</literal>
4102 interface. This service allows applications to make
4103 administrative requests of the bus itself. For example,
4104 applications can ask the bus to assign a name to a connection.
4107 Each name may have <firstterm>queued owners</firstterm>. When an
4108 application requests a name for a connection and the name is already in
4109 use, the bus will optionally add the connection to a queue waiting for
4110 the name. If the current owner of the name disconnects or releases
4111 the name, the next connection in the queue will become the new owner.
4115 This feature causes the right thing to happen if you start two text
4116 editors for example; the first one may request "com.example.TextEditor",
4117 and the second will be queued as a possible owner of that name. When
4118 the first exits, the second will take over.
4122 Applications may send <firstterm>unicast messages</firstterm> to
4123 a specific recipient or to the message bus itself, or
4124 <firstterm>broadcast messages</firstterm> to all interested recipients.
4125 See <xref linkend="message-bus-routing"/> for details.
4129 <sect2 id="message-bus-names">
4130 <title>Message Bus Names</title>
4132 Each connection has at least one name, assigned at connection time and
4133 returned in response to the
4134 <literal>org.freedesktop.DBus.Hello</literal> method call. This
4135 automatically-assigned name is called the connection's <firstterm>unique
4136 name</firstterm>. Unique names are never reused for two different
4137 connections to the same bus.
4140 Ownership of a unique name is a prerequisite for interaction with
4141 the message bus. It logically follows that the unique name is always
4142 the first name that an application comes to own, and the last
4143 one that it loses ownership of.
4146 Unique connection names must begin with the character ':' (ASCII colon
4147 character); bus names that are not unique names must not begin
4148 with this character. (The bus must reject any attempt by an application
4149 to manually request a name beginning with ':'.) This restriction
4150 categorically prevents "spoofing"; messages sent to a unique name
4151 will always go to the expected connection.
4154 When a connection is closed, all the names that it owns are deleted (or
4155 transferred to the next connection in the queue if any).
4158 A connection can request additional names to be associated with it using
4159 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
4160 linkend="message-protocol-names-bus"/> describes the format of a valid
4161 name. These names can be released again using the
4162 <literal>org.freedesktop.DBus.ReleaseName</literal> message.
4165 <sect3 id="bus-messages-request-name">
4166 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
4170 UINT32 RequestName (in STRING name, in UINT32 flags)
4177 <entry>Argument</entry>
4179 <entry>Description</entry>
4185 <entry>STRING</entry>
4186 <entry>Name to request</entry>
4190 <entry>UINT32</entry>
4191 <entry>Flags</entry>
4201 <entry>Argument</entry>
4203 <entry>Description</entry>
4209 <entry>UINT32</entry>
4210 <entry>Return value</entry>
4217 This method call should be sent to
4218 <literal>org.freedesktop.DBus</literal> and asks the message bus to
4219 assign the given name to the method caller. Each name maintains a
4220 queue of possible owners, where the head of the queue is the primary
4221 or current owner of the name. Each potential owner in the queue
4222 maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
4223 DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
4224 call. When RequestName is invoked the following occurs:
4228 If the method caller is currently the primary owner of the name,
4229 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
4230 values are updated with the values from the new RequestName call,
4231 and nothing further happens.
4237 If the current primary owner (head of the queue) has
4238 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
4239 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
4240 the caller of RequestName replaces the current primary owner at
4241 the head of the queue and the current primary owner moves to the
4242 second position in the queue. If the caller of RequestName was
4243 in the queue previously its flags are updated with the values from
4244 the new RequestName in addition to moving it to the head of the queue.
4250 If replacement is not possible, and the method caller is
4251 currently in the queue but not the primary owner, its flags are
4252 updated with the values from the new RequestName call.
4258 If replacement is not possible, and the method caller is
4259 currently not in the queue, the method caller is appended to the
4266 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
4267 set and is not the primary owner, it is removed from the
4268 queue. This can apply to the previous primary owner (if it
4269 was replaced) or the method caller (if it updated the
4270 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
4271 queue, or if it was just added to the queue with that flag set).
4277 Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
4278 queue," even if another application already in the queue had specified
4279 DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
4280 that does not allow replacement goes away, and the next primary owner
4281 does allow replacement. In this case, queued items that specified
4282 DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
4283 automatically replace the new primary owner. In other words,
4284 DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
4285 time RequestName is called. This is deliberate to avoid an infinite loop
4286 anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
4287 and DBUS_NAME_FLAG_REPLACE_EXISTING.
4290 The flags argument contains any of the following values logically ORed
4297 <entry>Conventional Name</entry>
4298 <entry>Value</entry>
4299 <entry>Description</entry>
4304 <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
4308 If an application A specifies this flag and succeeds in
4309 becoming the owner of the name, and another application B
4310 later calls RequestName with the
4311 DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
4312 will lose ownership and receive a
4313 <literal>org.freedesktop.DBus.NameLost</literal> signal, and
4314 application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
4315 is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
4316 is not specified by application B, then application B will not replace
4317 application A as the owner.
4322 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
4326 Try to replace the current owner if there is one. If this
4327 flag is not set the application will only become the owner of
4328 the name if there is no current owner. If this flag is set,
4329 the application will replace the current owner if
4330 the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
4335 <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
4339 Without this flag, if an application requests a name that is
4340 already owned, the application will be placed in a queue to
4341 own the name when the current owner gives it up. If this
4342 flag is given, the application will not be placed in the
4343 queue, the request for the name will simply fail. This flag
4344 also affects behavior when an application is replaced as
4345 name owner; by default the application moves back into the
4346 waiting queue, unless this flag was provided when the application
4347 became the name owner.
4355 The return code can be one of the following values:
4361 <entry>Conventional Name</entry>
4362 <entry>Value</entry>
4363 <entry>Description</entry>
4368 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
4369 <entry>1</entry> <entry>The caller is now the primary owner of
4370 the name, replacing any previous owner. Either the name had no
4371 owner before, or the caller specified
4372 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
4373 DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
4376 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
4379 <entry>The name already had an owner,
4380 DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
4381 the current owner did not specify
4382 DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
4383 application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
4387 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
4388 <entry>The name already has an owner,
4389 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
4390 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
4391 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
4392 specified by the requesting application.</entry>
4395 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
4397 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
4405 <sect3 id="bus-messages-release-name">
4406 <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
4410 UINT32 ReleaseName (in STRING name)
4417 <entry>Argument</entry>
4419 <entry>Description</entry>
4425 <entry>STRING</entry>
4426 <entry>Name to release</entry>
4436 <entry>Argument</entry>
4438 <entry>Description</entry>
4444 <entry>UINT32</entry>
4445 <entry>Return value</entry>
4452 This method call should be sent to
4453 <literal>org.freedesktop.DBus</literal> and asks the message bus to
4454 release the method caller's claim to the given name. If the caller is
4455 the primary owner, a new primary owner will be selected from the
4456 queue if any other owners are waiting. If the caller is waiting in
4457 the queue for the name, the caller will removed from the queue and
4458 will not be made an owner of the name if it later becomes available.
4459 If there are no other owners in the queue for the name, it will be
4460 removed from the bus entirely.
4462 The return code can be one of the following values:
4468 <entry>Conventional Name</entry>
4469 <entry>Value</entry>
4470 <entry>Description</entry>
4475 <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
4476 <entry>1</entry> <entry>The caller has released his claim on
4477 the given name. Either the caller was the primary owner of
4478 the name, and the name is now unused or taken by somebody
4479 waiting in the queue for the name, or the caller was waiting
4480 in the queue for the name and has now been removed from the
4484 <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
4486 <entry>The given name does not exist on this bus.</entry>
4489 <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
4491 <entry>The caller was not the primary owner of this name,
4492 and was also not waiting in the queue to own this name.</entry>
4500 <sect3 id="bus-messages-list-queued-owners">
4501 <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
4505 ARRAY of STRING ListQueuedOwners (in STRING name)
4512 <entry>Argument</entry>
4514 <entry>Description</entry>
4520 <entry>STRING</entry>
4521 <entry>The well-known bus name to query, such as
4522 <literal>com.example.cappuccino</literal></entry>
4532 <entry>Argument</entry>
4534 <entry>Description</entry>
4540 <entry>ARRAY of STRING</entry>
4541 <entry>The unique bus names of connections currently queued
4542 for the name</entry>
4549 This method call should be sent to
4550 <literal>org.freedesktop.DBus</literal> and lists the connections
4551 currently queued for a bus name (see
4552 <xref linkend="term-queued-owner"/>).
4557 <sect2 id="message-bus-routing">
4558 <title>Message Bus Message Routing</title>
4561 Messages may have a <literal>DESTINATION</literal> field (see <xref
4562 linkend="message-protocol-header-fields"/>), resulting in a
4563 <firstterm>unicast message</firstterm>. If the
4564 <literal>DESTINATION</literal> field is present, it specifies a message
4565 recipient by name. Method calls and replies normally specify this field.
4566 The message bus must send messages (of any type) with the
4567 <literal>DESTINATION</literal> field set to the specified recipient,
4568 regardless of whether the recipient has set up a match rule matching
4573 When the message bus receives a signal, if the
4574 <literal>DESTINATION</literal> field is absent, it is considered to
4575 be a <firstterm>broadcast signal</firstterm>, and is sent to all
4576 applications with <firstterm>message matching rules</firstterm> that
4577 match the message. Most signal messages are broadcasts, and
4578 no other message types currently defined in this specification
4583 Unicast signal messages (those with a <literal>DESTINATION</literal>
4584 field) are not commonly used, but they are treated like any unicast
4585 message: they are delivered to the specified receipient,
4586 regardless of its match rules. One use for unicast signals is to
4587 avoid a race condition in which a signal is emitted before the intended
4588 recipient can call <xref linkend="bus-messages-add-match"/> to
4589 receive that signal: if the signal is sent directly to that recipient
4590 using a unicast message, it does not need to add a match rule at all,
4591 and there is no race condition. Another use for unicast signals,
4592 on message buses whose security policy prevents eavesdropping, is to
4593 send sensitive information which should only be visible to one
4598 When the message bus receives a method call, if the
4599 <literal>DESTINATION</literal> field is absent, the call is taken to be
4600 a standard one-to-one message and interpreted by the message bus
4601 itself. For example, sending an
4602 <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
4603 <literal>DESTINATION</literal> will cause the message bus itself to
4604 reply to the ping immediately; the message bus will not make this
4605 message visible to other applications.
4609 Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
4610 the ping message were sent with a <literal>DESTINATION</literal> name of
4611 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
4612 forwarded, and the Yoyodyne Corporation screensaver application would be
4613 expected to reply to the ping.
4617 Message bus implementations may impose a security policy which
4618 prevents certain messages from being sent or received.
4619 When a method call message cannot be sent or received due to a security
4620 policy, the message bus should send an error reply, unless the
4621 original message had the <literal>NO_REPLY</literal> flag.
4624 <sect3 id="message-bus-routing-eavesdropping">
4625 <title>Eavesdropping</title>
4627 Receiving a unicast message whose <literal>DESTINATION</literal>
4628 indicates a different recipient is called
4629 <firstterm>eavesdropping</firstterm>. On a message bus which acts as
4630 a security boundary (like the standard system bus), the security
4631 policy should usually prevent eavesdropping, since unicast messages
4632 are normally kept private and may contain security-sensitive
4637 Eavesdropping is mainly useful for debugging tools, such as
4638 the <literal>dbus-monitor</literal> tool in the reference
4639 implementation of D-Bus. Tools which eavesdrop on the message bus
4640 should be careful to avoid sending a reply or error in response to
4641 messages intended for a different client.
4645 Clients may attempt to eavesdrop by adding match rules
4646 (see <xref linkend="message-bus-routing-match-rules"/>) containing
4647 the <literal>eavesdrop='true'</literal> match. If the message bus'
4648 security policy does not allow eavesdropping, the match rule can
4649 still be added, but will not have any practical effect. For
4650 compatibility with older message bus implementations, if adding such
4651 a match rule results in an error reply, the client may fall back to
4652 adding the same rule with the <literal>eavesdrop</literal> match
4657 Eavesdropping interacts poorly with buses with non-trivial
4658 access control restrictions. The
4659 <xref linkend="bus-messages-become-monitor"/> method provides
4660 an alternative way to monitor buses.
4664 <sect3 id="message-bus-routing-match-rules">
4665 <title>Match Rules</title>
4667 An important part of the message bus routing protocol is match
4668 rules. Match rules describe the messages that should be sent to a
4669 client, based on the contents of the message. Broadcast signals
4670 are only sent to clients which have a suitable match rule: this
4671 avoids waking up client processes to deal with signals that are
4672 not relevant to that client.
4675 Messages that list a client as their <literal>DESTINATION</literal>
4676 do not need to match the client's match rules, and are sent to that
4677 client regardless. As a result, match rules are mainly used to
4678 receive a subset of broadcast signals.
4681 Match rules can also be used for eavesdropping
4682 (see <xref linkend="message-bus-routing-eavesdropping"/>),
4683 if the security policy of the message bus allows it.
4686 Match rules are added using the AddMatch bus method
4687 (see <xref linkend="bus-messages-add-match"/>). Rules are
4688 specified as a string of comma separated key/value pairs.
4689 Excluding a key from the rule indicates a wildcard match.
4690 For instance excluding the the member from a match rule but
4691 adding a sender would let all messages from that sender through.
4692 An example of a complete rule would be
4693 "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
4696 Within single quotes (ASCII apostrophe, U+0027), a backslash
4697 (U+005C) represents itself, and an apostrophe ends the quoted
4698 section. Outside single quotes, \' (backslash, apostrophe)
4699 represents an apostrophe, and any backslash not followed by
4700 an apostrophe represents itself. For instance, the match rules
4701 <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
4702 <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
4703 both match messages where the arguments are a 1-character string
4704 containing an apostrophe, a 1-character string containing a
4705 backslash, a 1-character string containing a comma, and a
4706 2-character string containing two backslashes<footnote>
4708 This idiosyncratic quoting style is based on the rules for
4709 escaping items to appear inside single-quoted strings
4710 in POSIX <literal>/bin/sh</literal>, but please
4711 note that backslashes that are not inside single quotes have
4712 different behaviour. This syntax does not offer any way to
4713 represent an apostrophe inside single quotes (it is necessary
4714 to leave the single-quoted section, backslash-escape the
4715 apostrophe and re-enter single quotes), or to represent a
4716 comma outside single quotes (it is necessary to wrap it in
4717 a single-quoted section).
4722 The following table describes the keys that can be used to create
4729 <entry>Possible Values</entry>
4730 <entry>Description</entry>
4735 <entry><literal>type</literal></entry>
4736 <entry>'signal', 'method_call', 'method_return', 'error'</entry>
4737 <entry>Match on the message type. An example of a type match is type='signal'</entry>
4740 <entry><literal>sender</literal></entry>
4741 <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
4742 and <xref linkend="term-unique-name"/> respectively)
4744 <entry>Match messages sent by a particular sender. An example of a sender match
4745 is sender='org.freedesktop.Hal'</entry>
4748 <entry><literal>interface</literal></entry>
4749 <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
4750 <entry>Match messages sent over or to a particular interface. An example of an
4751 interface match is interface='org.freedesktop.Hal.Manager'.
4752 If a message omits the interface header, it must not match any rule
4753 that specifies this key.</entry>
4756 <entry><literal>member</literal></entry>
4757 <entry>Any valid method or signal name</entry>
4758 <entry>Matches messages which have the give method or signal name. An example of
4759 a member match is member='NameOwnerChanged'</entry>
4762 <entry><literal>path</literal></entry>
4763 <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
4764 <entry>Matches messages which are sent from or to the given object. An example of a
4765 path match is path='/org/freedesktop/Hal/Manager'</entry>
4768 <entry><literal>path_namespace</literal></entry>
4769 <entry>An object path</entry>
4772 Matches messages which are sent from or to an
4773 object for which the object path is either the
4774 given value, or that value followed by one or
4775 more path components.
4780 <literal>path_namespace='/com/example/foo'</literal>
4781 would match signals sent by
4782 <literal>/com/example/foo</literal>
4784 <literal>/com/example/foo/bar</literal>,
4786 <literal>/com/example/foobar</literal>.
4790 Using both <literal>path</literal> and
4791 <literal>path_namespace</literal> in the same match
4792 rule is not allowed.
4797 This match key was added in version 0.16 of the
4798 D-Bus specification and implemented by the bus
4799 daemon in dbus 1.5.0 and later.
4805 <entry><literal>destination</literal></entry>
4806 <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
4807 <entry>Matches messages which are being sent to the given unique name. An
4808 example of a destination match is destination=':1.0'</entry>
4811 <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
4812 <entry>Any string</entry>
4813 <entry>Arg matches are special and are used for further restricting the
4814 match based on the arguments in the body of a message. Only arguments of type
4815 STRING can be matched in this way. An example of an argument match
4816 would be arg3='Foo'. Only argument indexes from 0 to 63 should be
4820 <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
4821 <entry>Any string</entry>
4823 <para>Argument path matches provide a specialised form of wildcard matching for
4824 path-like namespaces. They can match arguments whose type is either STRING or
4825 OBJECT_PATH. As with normal argument matches,
4826 if the argument is exactly equal to the string given in the match
4827 rule then the rule is satisfied. Additionally, there is also a
4828 match when either the string given in the match rule or the
4829 appropriate message argument ends with '/' and is a prefix of the
4830 other. An example argument path match is arg0path='/aa/bb/'. This
4831 would match messages with first arguments of '/', '/aa/',
4832 '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
4833 messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
4835 <para>This is intended for monitoring “directories” in file system-like
4836 hierarchies, as used in the <citetitle>dconf</citetitle> configuration
4837 system. An application interested in all nodes in a particular hierarchy would
4838 monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
4839 emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
4840 represent a modification to the “bar” property, or a signal with zeroth
4841 argument <literal>"/ca/example/"</literal> to represent atomic modification of
4842 many properties within that directory, and the interested application would be
4843 notified in both cases.</para>
4846 This match key was added in version 0.12 of the
4847 D-Bus specification, implemented for STRING
4848 arguments by the bus daemon in dbus 1.2.0 and later,
4849 and implemented for OBJECT_PATH arguments in dbus 1.5.0
4856 <entry><literal>arg0namespace</literal></entry>
4857 <entry>Like a bus name, except that the string is not
4858 required to contain a '.' (period)</entry>
4860 <para>Match messages whose first argument is of type STRING, and is a bus name
4861 or interface name within the specified namespace. This is primarily intended
4862 for watching name owner changes for a group of related bus names, rather than
4863 for a single name or all name changes.</para>
4865 <para>Because every valid interface name is also a valid
4866 bus name, this can also be used for messages whose
4867 first argument is an interface name.</para>
4869 <para>For example, the match rule
4870 <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
4871 matches name owner changes for bus names such as
4872 <literal>com.example.backend.foo</literal>,
4873 <literal>com.example.backend.foo.bar</literal>, and
4874 <literal>com.example.backend</literal> itself.</para>
4876 <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
4879 This match key was added in version 0.16 of the
4880 D-Bus specification and implemented by the bus
4881 daemon in dbus 1.5.0 and later.
4887 <entry><literal>eavesdrop</literal></entry>
4888 <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
4889 <entry>Since D-Bus 1.5.6, match rules do not
4890 match messages which have a <literal>DESTINATION</literal>
4891 field unless the match rule specifically
4893 (see <xref linkend="message-bus-routing-eavesdropping"/>)
4894 by specifying <literal>eavesdrop='true'</literal>
4895 in the match rule. <literal>eavesdrop='false'</literal>
4896 restores the default behaviour. Messages are
4897 delivered to their <literal>DESTINATION</literal>
4898 regardless of match rules, so this match does not
4899 affect normal delivery of unicast messages.
4900 If the message bus has a security policy which forbids
4901 eavesdropping, this match may still be used without error,
4902 but will not have any practical effect.
4903 In older versions of D-Bus, this match was not allowed
4904 in match rules, and all match rules behaved as if
4905 <literal>eavesdrop='true'</literal> had been used.
4914 <sect2 id="message-bus-starting-services">
4915 <title>Message Bus Starting Services</title>
4917 The message bus can start applications on behalf of other applications.
4918 In CORBA terms, this would be called <firstterm>activation</firstterm>.
4919 An application that can be started in this way is called a
4920 <firstterm>service</firstterm>.
4923 With D-Bus, starting a service is normally done by name. That is,
4924 applications ask the message bus to start some program that will own a
4925 well-known name, such as <literal>com.example.TextEditor</literal>.
4926 This implies a contract documented along with the name
4927 <literal>com.example.TextEditor</literal> for which object
4928 the owner of that name will provide, and what interfaces those
4932 To find an executable corresponding to a particular name, the bus daemon
4933 looks for <firstterm>service description files</firstterm>. Service
4934 description files define a mapping from names to executables. Different
4935 kinds of message bus will look for these files in different places, see
4936 <xref linkend="message-bus-types"/>.
4939 Service description files have the ".service" file
4940 extension. The message bus will only load service description files
4941 ending with .service; all other files will be ignored. The file format
4942 is similar to that of <ulink
4943 url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
4944 entries</ulink>. All service description files must be in UTF-8
4945 encoding. To ensure that there will be no name collisions, service files
4946 must be namespaced using the same mechanism as messages and service
4951 On the well-known system bus, the name of a service description file
4952 must be its well-known name plus <literal>.service</literal>,
4954 <literal>com.example.ConfigurationDatabase.service</literal>.
4958 On the well-known session bus, services should follow the same
4959 service description file naming convention as on the system bus,
4960 but for backwards compatibility they are not required to do so.
4964 [FIXME the file format should be much better specified than "similar to
4965 .desktop entries" esp. since desktop entries are already
4966 badly-specified. ;-)]
4967 These sections from the specification apply to service files as well:
4970 <listitem><para>General syntax</para></listitem>
4971 <listitem><para>Comment format</para></listitem>
4974 Service description files must contain a
4975 <literal>D-BUS Service</literal> group with at least the keys
4976 <literal>Name</literal> (the well-known name of the service)
4977 and <literal>Exec</literal> (the command to be executed).
4980 <title>Example service description file</title>
4982 # Sample service description file
4984 Name=com.example.ConfigurationDatabase
4985 Exec=/usr/bin/sample-configd
4991 Additionally, service description files for the well-known system
4992 bus on Unix must contain a <literal>User</literal> key, whose value
4993 is the name of a user account (e.g. <literal>root</literal>).
4994 The system service will be run as that user.
4998 When an application asks to start a service by name, the bus daemon tries to
4999 find a service that will own that name. It then tries to spawn the
5000 executable associated with it. If this fails, it will report an
5005 On the well-known system bus, it is not possible for two .service files
5006 in the same directory to offer the same service, because they are
5007 constrained to have names that match the service name.
5011 On the well-known session bus, if two .service files in the same
5012 directory offer the same service name, the result is undefined.
5013 Distributors should avoid this situation, for instance by naming
5014 session services' .service files according to their service name.
5018 If two .service files in different directories offer the same
5019 service name, the one in the higher-priority directory is used:
5020 for instance, on the system bus, .service files in
5021 /usr/local/share/dbus-1/system-services take precedence over those
5022 in /usr/share/dbus-1/system-services.
5025 The executable launched will have the environment variable
5026 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
5027 message bus so it can connect and request the appropriate names.
5030 The executable being launched may want to know whether the message bus
5031 starting it is one of the well-known message buses (see <xref
5032 linkend="message-bus-types"/>). To facilitate this, the bus must also set
5033 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
5034 of the well-known buses. The currently-defined values for this variable
5035 are <literal>system</literal> for the systemwide message bus,
5036 and <literal>session</literal> for the per-login-session message
5037 bus. The new executable must still connect to the address given
5038 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
5039 resulting connection is to the well-known bus.
5042 [FIXME there should be a timeout somewhere, either specified
5043 in the .service file, by the client, or just a global value
5044 and if the client being activated fails to connect within that
5045 timeout, an error should be sent back.]
5048 <sect3 id="message-bus-starting-services-scope">
5049 <title>Message Bus Service Scope</title>
5051 The "scope" of a service is its "per-", such as per-session,
5052 per-machine, per-home-directory, or per-display. The reference
5053 implementation doesn't yet support starting services in a different
5054 scope from the message bus itself. So e.g. if you start a service
5055 on the session bus its scope is per-session.
5058 We could add an optional scope to a bus name. For example, for
5059 per-(display,session pair), we could have a unique ID for each display
5060 generated automatically at login and set on screen 0 by executing a
5061 special "set display ID" binary. The ID would be stored in a
5062 <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
5063 random bytes. This ID would then be used to scope names.
5064 Starting/locating a service could be done by ID-name pair rather than
5068 Contrast this with a per-display scope. To achieve that, we would
5069 want a single bus spanning all sessions using a given display.
5070 So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
5071 property on screen 0 of the display, pointing to this bus.
5076 <sect2 id="message-bus-types">
5077 <title>Well-known Message Bus Instances</title>
5079 Two standard message bus instances are defined here, along with how
5080 to locate them and where their service files live.
5082 <sect3 id="message-bus-types-login">
5083 <title>Login session message bus</title>
5085 Each time a user logs in, a <firstterm>login session message
5086 bus</firstterm> may be started. All applications in the user's login
5087 session may interact with one another using this message bus.
5090 The address of the login session message bus is given
5091 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
5092 variable. If that variable is not set, applications may
5093 also try to read the address from the X Window System root
5094 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
5095 The root window property must have type <literal>STRING</literal>.
5096 The environment variable should have precedence over the
5097 root window property.
5099 <para>The address of the login session message bus is given in the
5100 <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment variable. If
5101 DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string
5102 "autolaunch:", the system should use platform-specific methods of
5103 locating a running D-Bus session server, or starting one if a running
5104 instance cannot be found. Note that this mechanism is not recommended
5105 for attempting to determine if a daemon is running. It is inherently
5106 racy to attempt to make this determination, since the bus daemon may
5107 be started just before or just after the determination is made.
5108 Therefore, it is recommended that applications do not try to make this
5109 determination for their functionality purposes, and instead they
5110 should attempt to start the server.</para>
5112 <sect4 id="message-bus-types-login-x-windows">
5113 <title>X Windowing System</title>
5115 For the X Windowing System, the application must locate the
5116 window owner of the selection represented by the atom formed by
5120 <para>the literal string "_DBUS_SESSION_BUS_SELECTION_"</para>
5124 <para>the current user's username</para>
5128 <para>the literal character '_' (underscore)</para>
5132 <para>the machine's ID</para>
5138 The following properties are defined for the window that owns
5140 <informaltable frame="all">
5149 <para>meaning</para>
5155 <para>_DBUS_SESSION_BUS_ADDRESS</para>
5159 <para>the actual address of the server socket</para>
5165 <para>_DBUS_SESSION_BUS_PID</para>
5169 <para>the PID of the server process</para>
5178 At least the _DBUS_SESSION_BUS_ADDRESS property MUST be
5179 present in this window.
5183 If the X selection cannot be located or if reading the
5184 properties from the window fails, the implementation MUST conclude
5185 that there is no D-Bus server running and proceed to start a new
5186 server. (See below on concurrency issues)
5190 Failure to connect to the D-Bus server address thus obtained
5191 MUST be treated as a fatal connection error and should be reported
5196 As an alternative, an implementation MAY find the information
5197 in the following file located in the current user's home directory,
5198 in subdirectory .dbus/session-bus/:
5201 <para>the machine's ID</para>
5205 <para>the literal character '-' (dash)</para>
5209 <para>the X display without the screen number, with the
5210 following prefixes removed, if present: ":", "localhost:"
5211 ."localhost.localdomain:". That is, a display of
5212 "localhost:10.0" produces just the number "10"</para>
5218 The contents of this file NAME=value assignment pairs and
5219 lines starting with # are comments (no comments are allowed
5220 otherwise). The following variable names are defined:
5227 <para>Variable</para>
5231 <para>meaning</para>
5237 <para>DBUS_SESSION_BUS_ADDRESS</para>
5241 <para>the actual address of the server socket</para>
5247 <para>DBUS_SESSION_BUS_PID</para>
5251 <para>the PID of the server process</para>
5257 <para>DBUS_SESSION_BUS_WINDOWID</para>
5261 <para>the window ID</para>
5270 At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
5275 Failure to open this file MUST be interpreted as absence of a
5276 running server. Therefore, the implementation MUST proceed to
5277 attempting to launch a new bus server if the file cannot be
5282 However, success in opening this file MUST NOT lead to the
5283 conclusion that the server is running. Thus, a failure to connect to
5284 the bus address obtained by the alternative method MUST NOT be
5285 considered a fatal error. If the connection cannot be established,
5286 the implementation MUST proceed to check the X selection settings or
5287 to start the server on its own.
5291 If the implementation concludes that the D-Bus server is not
5292 running it MUST attempt to start a new server and it MUST also
5293 ensure that the daemon started as an effect of the "autolaunch"
5294 mechanism provides the lookup mechanisms described above, so
5295 subsequent calls can locate the newly started server. The
5296 implementation MUST also ensure that if two or more concurrent
5297 initiations happen, only one server remains running and all other
5298 initiations are able to obtain the address of this server and
5299 connect to it. In other words, the implementation MUST ensure that
5300 the X selection is not present when it attempts to set it, without
5301 allowing another process to set the selection between the
5302 verification and the setting (e.g., by using XGrabServer /
5309 On Unix systems, the session bus should search for .service files
5310 in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
5312 <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
5313 Implementations may also search additional locations, which
5314 should be searched with lower priority than anything in
5315 XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
5316 for example, the reference implementation also
5317 looks in <literal>${datadir}/dbus-1/services</literal> as
5318 set at compile time.
5321 As described in the XDG Base Directory Specification, software
5322 packages should install their session .service files to their
5323 configured <literal>${datadir}/dbus-1/services</literal>,
5324 where <literal>${datadir}</literal> is as defined by the GNU
5325 coding standards. System administrators or users can arrange
5326 for these service files to be read by setting XDG_DATA_DIRS or by
5327 symlinking them into the default locations.
5331 <sect3 id="message-bus-types-system">
5332 <title>System message bus</title>
5334 A computer may have a <firstterm>system message bus</firstterm>,
5335 accessible to all applications on the system. This message bus may be
5336 used to broadcast system events, such as adding new hardware devices,
5337 changes in the printer queue, and so forth.
5340 The address of the system message bus is given
5341 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
5342 variable. If that variable is not set, applications should try
5343 to connect to the well-known address
5344 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
5347 The D-Bus reference implementation actually honors the
5348 <literal>$(localstatedir)</literal> configure option
5349 for this address, on both client and server side.
5354 On Unix systems, the system bus should default to searching
5355 for .service files in
5356 <literal>/usr/local/share/dbus-1/system-services</literal>,
5357 <literal>/usr/share/dbus-1/system-services</literal> and
5358 <literal>/lib/dbus-1/system-services</literal>, with that order
5359 of precedence. It may also search other implementation-specific
5360 locations, but should not vary these locations based on environment
5364 The system bus is security-sensitive and is typically executed
5365 by an init system with a clean environment. Its launch helper
5366 process is particularly security-sensitive, and specifically
5367 clears its own environment.
5372 Software packages should install their system .service
5373 files to their configured
5374 <literal>${datadir}/dbus-1/system-services</literal>,
5375 where <literal>${datadir}</literal> is as defined by the GNU
5376 coding standards. System administrators can arrange
5377 for these service files to be read by editing the system bus'
5378 configuration file or by symlinking them into the default
5384 <sect2 id="message-bus-messages">
5385 <title>Message Bus Messages</title>
5387 The special message bus name <literal>org.freedesktop.DBus</literal>
5388 responds to a number of additional messages.
5391 <sect3 id="bus-messages-hello">
5392 <title><literal>org.freedesktop.DBus.Hello</literal></title>
5403 <entry>Argument</entry>
5405 <entry>Description</entry>
5411 <entry>STRING</entry>
5412 <entry>Unique name assigned to the connection</entry>
5419 Before an application is able to send messages to other applications
5420 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
5421 to the message bus to obtain a unique name. If an application without
5422 a unique name tries to send a message to another application, or a
5423 message to the message bus itself that isn't the
5424 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
5425 disconnected from the bus.
5428 There is no corresponding "disconnect" request; if a client wishes to
5429 disconnect from the bus, it simply closes the socket (or other
5430 communication channel).
5433 <sect3 id="bus-messages-list-names">
5434 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
5438 ARRAY of STRING ListNames ()
5445 <entry>Argument</entry>
5447 <entry>Description</entry>
5453 <entry>ARRAY of STRING</entry>
5454 <entry>Array of strings where each string is a bus name</entry>
5461 Returns a list of all currently-owned names on the bus.
5464 <sect3 id="bus-messages-list-activatable-names">
5465 <title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
5469 ARRAY of STRING ListActivatableNames ()
5476 <entry>Argument</entry>
5478 <entry>Description</entry>
5484 <entry>ARRAY of STRING</entry>
5485 <entry>Array of strings where each string is a bus name</entry>
5492 Returns a list of all names that can be activated on the bus.
5495 <sect3 id="bus-messages-name-exists">
5496 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
5500 BOOLEAN NameHasOwner (in STRING name)
5507 <entry>Argument</entry>
5509 <entry>Description</entry>
5515 <entry>STRING</entry>
5516 <entry>Name to check</entry>
5526 <entry>Argument</entry>
5528 <entry>Description</entry>
5534 <entry>BOOLEAN</entry>
5535 <entry>Return value, true if the name exists</entry>
5542 Checks if the specified name exists (currently has an owner).
5546 <sect3 id="bus-messages-name-owner-changed">
5547 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
5551 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
5558 <entry>Argument</entry>
5560 <entry>Description</entry>
5566 <entry>STRING</entry>
5567 <entry>Name with a new owner</entry>
5571 <entry>STRING</entry>
5572 <entry>Old owner or empty string if none</entry>
5576 <entry>STRING</entry>
5577 <entry>New owner or empty string if none</entry>
5584 This signal indicates that the owner of a name has changed.
5585 It's also the signal to use to detect the appearance of
5586 new names on the bus.
5589 <sect3 id="bus-messages-name-lost">
5590 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
5594 NameLost (STRING name)
5601 <entry>Argument</entry>
5603 <entry>Description</entry>
5609 <entry>STRING</entry>
5610 <entry>Name which was lost</entry>
5617 This signal is sent to a specific application when it loses
5618 ownership of a name.
5622 <sect3 id="bus-messages-name-acquired">
5623 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
5627 NameAcquired (STRING name)
5634 <entry>Argument</entry>
5636 <entry>Description</entry>
5642 <entry>STRING</entry>
5643 <entry>Name which was acquired</entry>
5650 This signal is sent to a specific application when it gains
5651 ownership of a name.
5655 <sect3 id="bus-messages-start-service-by-name">
5656 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
5660 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
5667 <entry>Argument</entry>
5669 <entry>Description</entry>
5675 <entry>STRING</entry>
5676 <entry>Name of the service to start</entry>
5680 <entry>UINT32</entry>
5681 <entry>Flags (currently not used)</entry>
5691 <entry>Argument</entry>
5693 <entry>Description</entry>
5699 <entry>UINT32</entry>
5700 <entry>Return value</entry>
5705 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
5709 The return value can be one of the following values:
5714 <entry>Identifier</entry>
5715 <entry>Value</entry>
5716 <entry>Description</entry>
5721 <entry>DBUS_START_REPLY_SUCCESS</entry>
5723 <entry>The service was successfully started.</entry>
5726 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
5728 <entry>A connection already owns the given name.</entry>
5737 <sect3 id="bus-messages-update-activation-environment">
5738 <title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
5742 UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment)
5749 <entry>Argument</entry>
5751 <entry>Description</entry>
5757 <entry>ARRAY of DICT<STRING,STRING></entry>
5758 <entry>Environment to add or update</entry>
5763 Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services.
5766 Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.
5769 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.
5774 <sect3 id="bus-messages-get-name-owner">
5775 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
5779 STRING GetNameOwner (in STRING name)
5786 <entry>Argument</entry>
5788 <entry>Description</entry>
5794 <entry>STRING</entry>
5795 <entry>Name to get the owner of</entry>
5805 <entry>Argument</entry>
5807 <entry>Description</entry>
5813 <entry>STRING</entry>
5814 <entry>Return value, a unique connection name</entry>
5819 Returns the unique connection name of the primary owner of the name
5820 given. If the requested name doesn't have an owner, returns a
5821 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
5825 <sect3 id="bus-messages-get-connection-unix-user">
5826 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
5830 UINT32 GetConnectionUnixUser (in STRING bus_name)
5837 <entry>Argument</entry>
5839 <entry>Description</entry>
5845 <entry>STRING</entry>
5846 <entry>Unique or well-known bus name of the connection to
5847 query, such as <literal>:12.34</literal> or
5848 <literal>com.example.tea</literal></entry>
5858 <entry>Argument</entry>
5860 <entry>Description</entry>
5866 <entry>UINT32</entry>
5867 <entry>Unix user ID</entry>
5872 Returns the Unix user ID of the process connected to the server. If
5873 unable to determine it (for instance, because the process is not on the
5874 same machine as the bus daemon), an error is returned.
5878 <sect3 id="bus-messages-get-connection-unix-process-id">
5879 <title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
5883 UINT32 GetConnectionUnixProcessID (in STRING bus_name)
5890 <entry>Argument</entry>
5892 <entry>Description</entry>
5898 <entry>STRING</entry>
5899 <entry>Unique or well-known bus name of the connection to
5900 query, such as <literal>:12.34</literal> or
5901 <literal>com.example.tea</literal></entry>
5911 <entry>Argument</entry>
5913 <entry>Description</entry>
5919 <entry>UINT32</entry>
5920 <entry>Unix process id</entry>
5925 Returns the Unix process ID of the process connected to the server. If
5926 unable to determine it (for instance, because the process is not on the
5927 same machine as the bus daemon), an error is returned.
5931 <sect3 id="bus-messages-get-connection-credentials">
5932 <title><literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
5936 DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name)
5943 <entry>Argument</entry>
5945 <entry>Description</entry>
5951 <entry>STRING</entry>
5952 <entry>Unique or well-known bus name of the connection to
5953 query, such as <literal>:12.34</literal> or
5954 <literal>com.example.tea</literal></entry>
5964 <entry>Argument</entry>
5966 <entry>Description</entry>
5972 <entry>DICT<STRING,VARIANT></entry>
5973 <entry>Credentials</entry>
5981 Returns as many credentials as possible for the process connected to
5982 the server. If unable to determine certain credentials (for instance,
5983 because the process is not on the same machine as the bus daemon,
5984 or because this version of the bus daemon does not support a
5985 particular security framework), or if the values of those credentials
5986 cannot be represented as documented here, then those credentials
5991 Keys in the returned dictionary not containing "." are defined
5992 by this specification. Bus daemon implementors supporting
5993 credentials frameworks not mentioned in this document should either
5994 contribute patches to this specification, or use keys containing
5995 "." and starting with a reversed domain name.
6001 <entry>Value type</entry>
6002 <entry>Value</entry>
6007 <entry>UnixUserID</entry>
6008 <entry>UINT32</entry>
6009 <entry>The numeric Unix user ID, as defined by POSIX</entry>
6012 <entry>ProcessID</entry>
6013 <entry>UINT32</entry>
6014 <entry>The numeric process ID, on platforms that have
6015 this concept. On Unix, this is the process ID defined by
6019 <entry>WindowsSID</entry>
6020 <entry>STRING</entry>
6021 <entry>The Windows security identifier in its string form,
6022 e.g. "S-1-5-21-3623811015-3361044348-30300820-1013" for
6023 a domain or local computer user or "S-1-5-18" for the
6024 LOCAL_SYSTEM user</entry>
6028 <entry>LinuxSecurityLabel</entry>
6029 <entry>ARRAY of BYTE</entry>
6031 <para>On Linux systems, the security label that would result
6032 from the SO_PEERSEC getsockopt call. The array contains
6033 the non-zero bytes of the security label in an unspecified
6034 ASCII-compatible encoding<footnote>
6035 <para>It could be ASCII or UTF-8, but could also be
6036 ISO Latin-1 or any other encoding.</para>
6037 </footnote>, followed by a single zero byte.</para>
6039 For example, the SELinux context
6040 <literal>system_u:system_r:init_t:s0</literal>
6041 (a string of length 27) would be encoded as 28 bytes
6042 ending with ':', 's', '0', '\x00'.<footnote>
6043 <para>Note that this is not the same as the older
6044 GetConnectionSELinuxContext method, which does
6045 not append the zero byte. Always appending the
6046 zero byte allows callers to read the string
6047 from the message payload without copying.</para>
6051 On SELinux systems this is the SELinux context, as output
6052 by <literal>ps -Z</literal> or <literal>ls -Z</literal>.
6053 Typical values might include
6054 <literal>system_u:system_r:init_t:s0</literal>,
6055 <literal>unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023</literal>,
6057 <literal>unconfined_u:unconfined_r:chrome_sandbox_t:s0-s0:c0.c1023</literal>.
6060 On Smack systems, this is the Smack label.
6061 Typical values might include
6062 <literal>_</literal>, <literal>*</literal>,
6063 <literal>User</literal>, <literal>System</literal>
6064 or <literal>System::Shared</literal>.
6067 On AppArmor systems, this is the AppArmor context,
6068 a composite string encoding the AppArmor label (one or more
6069 profiles) and the enforcement mode.
6070 Typical values might include <literal>unconfined</literal>,
6071 <literal>/usr/bin/firefox (enforce)</literal> or
6072 <literal>user1 (complain)</literal>.
6083 This method was added in D-Bus 1.7 to reduce the round-trips
6084 required to list a process's credentials. In older versions, calling
6085 this method will fail: applications should recover by using the
6086 separate methods such as
6087 <xref linkend="bus-messages-get-connection-unix-user"/>
6092 <sect3 id="bus-messages-get-adt-audit-session-data">
6093 <title><literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
6097 ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name)
6104 <entry>Argument</entry>
6106 <entry>Description</entry>
6112 <entry>STRING</entry>
6113 <entry>Unique or well-known bus name of the connection to
6114 query, such as <literal>:12.34</literal> or
6115 <literal>com.example.tea</literal></entry>
6125 <entry>Argument</entry>
6127 <entry>Description</entry>
6133 <entry>ARRAY of BYTE</entry>
6134 <entry>auditing data as returned by
6135 adt_export_session_data()</entry>
6140 Returns auditing data used by Solaris ADT, in an unspecified
6141 binary format. If you know what this means, please contribute
6142 documentation via the D-Bus bug tracking system.
6143 This method is on the core DBus interface for historical reasons;
6144 the same information should be made available via
6145 <xref linkend="bus-messages-get-connection-credentials"/>
6150 <sect3 id="bus-messages-get-connection-selinux-security-context">
6151 <title><literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
6155 ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name)
6162 <entry>Argument</entry>
6164 <entry>Description</entry>
6170 <entry>STRING</entry>
6171 <entry>Unique or well-known bus name of the connection to
6172 query, such as <literal>:12.34</literal> or
6173 <literal>com.example.tea</literal></entry>
6183 <entry>Argument</entry>
6185 <entry>Description</entry>
6191 <entry>ARRAY of BYTE</entry>
6192 <entry>some sort of string of bytes, not necessarily UTF-8,
6193 not including '\0'</entry>
6198 Returns the security context used by SELinux, in an unspecified
6199 format. If you know what this means, please contribute
6200 documentation via the D-Bus bug tracking system.
6201 This method is on the core DBus interface for historical reasons;
6202 the same information should be made available via
6203 <xref linkend="bus-messages-get-connection-credentials"/>
6209 <sect3 id="bus-messages-add-match">
6210 <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
6214 AddMatch (in STRING rule)
6221 <entry>Argument</entry>
6223 <entry>Description</entry>
6229 <entry>STRING</entry>
6230 <entry>Match rule to add to the connection</entry>
6235 Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
6236 If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
6240 <sect3 id="bus-messages-remove-match">
6241 <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
6245 RemoveMatch (in STRING rule)
6252 <entry>Argument</entry>
6254 <entry>Description</entry>
6260 <entry>STRING</entry>
6261 <entry>Match rule to remove from the connection</entry>
6266 Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
6267 If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
6272 <sect3 id="bus-messages-get-id">
6273 <title><literal>org.freedesktop.DBus.GetId</literal></title>
6277 GetId (out STRING id)
6284 <entry>Argument</entry>
6286 <entry>Description</entry>
6292 <entry>STRING</entry>
6293 <entry>Unique ID identifying the bus daemon</entry>
6298 Gets the unique ID of the bus. The unique ID here is shared among all addresses the
6299 bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
6300 <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
6301 ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
6302 There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
6303 by org.freedesktop.DBus.Peer.GetMachineId().
6304 For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
6308 <sect3 id="bus-messages-become-monitor">
6309 <title><literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
6313 BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
6320 <entry>Argument</entry>
6322 <entry>Description</entry>
6328 <entry>ARRAY of STRING</entry>
6329 <entry>Match rules to add to the connection</entry>
6333 <entry>UINT32</entry>
6334 <entry>Not used, must be 0</entry>
6342 Converts the connection into a <emphasis>monitor
6343 connection</emphasis> which can be used as a debugging/monitoring
6344 tool. Only a user who is privileged on this
6345 bus (by some implementation-specific definition) may create
6346 monitor connections<footnote>
6348 In the reference implementation,
6349 the default configuration is that each user (identified by
6350 numeric user ID) may monitor their own session bus,
6351 and the root user (user ID zero) may monitor the
6358 Monitor connections lose all their bus names, including the unique
6359 connection name, and all their match rules. Sending messages on a
6360 monitor connection is not allowed: applications should use a private
6361 connection for monitoring.
6365 Monitor connections may receive all messages, even messages that
6366 should only have gone to some other connection ("eavesdropping").
6367 The first argument is a list of match rules, which replace any
6368 match rules that were previously active for this connection.
6369 These match rules are always treated as if they contained the
6370 special <literal>eavesdrop='true'</literal> member.
6374 As a special case, an empty list of match rules (which would
6375 otherwise match nothing, making the monitor useless) is treated
6376 as a shorthand for matching all messages.
6380 The second argument might be used for flags to influence the
6381 behaviour of the monitor connection in future D-Bus versions.
6385 Message bus implementations should attempt to minimize the
6386 side-effects of monitoring — in particular, unlike ordinary
6387 eavesdropping, monitoring the system bus does not require the
6388 access control rules to be relaxed, which would change the set
6389 of messages that can be delivered to their (non-monitor)
6390 destinations. However, it is unavoidable that monitoring
6391 will increase the message bus's resource consumption. In
6392 edge cases where there was barely enough time or memory without
6393 monitoring, this might result in message deliveries failing
6394 when they would otherwise have succeeded.
6402 <appendix id="implementation-notes">
6403 <title>Implementation notes</title>
6404 <sect1 id="implementation-notes-subsection">
6412 <glossary><title>Glossary</title>
6414 This glossary defines some of the terms used in this specification.
6417 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
6420 The message bus maintains an association between names and
6421 connections. (Normally, there's one connection per application.) A
6422 bus name is simply an identifier used to locate connections. For
6423 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
6424 name might be used to send a message to a screensaver from Yoyodyne
6425 Corporation. An application is said to <firstterm>own</firstterm> a
6426 name if the message bus has associated the application's connection
6427 with the name. Names may also have <firstterm>queued
6428 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
6429 The bus assigns a unique name to each connection,
6430 see <xref linkend="term-unique-name"/>. Other names
6431 can be thought of as "well-known names" and are
6432 used to find applications that offer specific functionality.
6436 See <xref linkend="message-protocol-names-bus"/> for details of
6437 the syntax and naming conventions for bus names.
6442 <glossentry id="term-message"><glossterm>Message</glossterm>
6445 A message is the atomic unit of communication via the D-Bus
6446 protocol. It consists of a <firstterm>header</firstterm> and a
6447 <firstterm>body</firstterm>; the body is made up of
6448 <firstterm>arguments</firstterm>.
6453 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
6456 The message bus is a special application that forwards
6457 or routes messages between a group of applications
6458 connected to the message bus. It also manages
6459 <firstterm>names</firstterm> used for routing
6465 <glossentry id="term-name"><glossterm>Name</glossterm>
6468 See <xref linkend="term-bus-name"/>. "Name" may
6469 also be used to refer to some of the other names
6470 in D-Bus, such as interface names.
6475 <glossentry id="namespace"><glossterm>Namespace</glossterm>
6478 Used to prevent collisions when defining new interfaces, bus names
6479 etc. The convention used is the same one Java uses for defining
6480 classes: a reversed domain name.
6481 See <xref linkend="message-protocol-names-bus"/>,
6482 <xref linkend="message-protocol-names-interface"/>,
6483 <xref linkend="message-protocol-names-error"/>,
6484 <xref linkend="message-protocol-marshaling-object-path"/>.
6489 <glossentry id="term-object"><glossterm>Object</glossterm>
6492 Each application contains <firstterm>objects</firstterm>, which have
6493 <firstterm>interfaces</firstterm> and
6494 <firstterm>methods</firstterm>. Objects are referred to by a name,
6495 called a <firstterm>path</firstterm>.
6500 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
6503 An application talking directly to another application, without going
6504 through a message bus. One-to-one connections may be "peer to peer" or
6505 "client to server." The D-Bus protocol has no concept of client
6506 vs. server after a connection has authenticated; the flow of messages
6507 is symmetrical (full duplex).
6512 <glossentry id="term-path"><glossterm>Path</glossterm>
6515 Object references (object names) in D-Bus are organized into a
6516 filesystem-style hierarchy, so each object is named by a path. As in
6517 LDAP, there's no difference between "files" and "directories"; a path
6518 can refer to an object, while still having child objects below it.
6523 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
6526 Each bus name has a primary owner; messages sent to the name go to the
6527 primary owner. However, certain names also maintain a queue of
6528 secondary owners "waiting in the wings." If the primary owner releases
6529 the name, then the first secondary owner in the queue automatically
6530 becomes the new owner of the name.
6535 <glossentry id="term-service"><glossterm>Service</glossterm>
6538 A service is an executable that can be launched by the bus daemon.
6539 Services normally guarantee some particular features, for example they
6540 may guarantee that they will request a specific name such as
6541 "com.example.Screensaver", have a singleton object
6542 "/com/example/Application", and that object will implement the
6543 interface "com.example.Screensaver.Control".
6548 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
6551 ".service files" tell the bus about service applications that can be
6552 launched (see <xref linkend="term-service"/>). Most importantly they
6553 provide a mapping from bus names to services that will request those
6554 names when they start up.
6559 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
6562 The special name automatically assigned to each connection by the
6563 message bus. This name will never change owner, and will be unique
6564 (never reused during the lifetime of the message bus).
6565 It will begin with a ':' character.