1 <?xml version="1.0" standalone="no" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
8 <title>D-Bus Specification</title>
9 <releaseinfo>Version 0.16</releaseinfo>
10 <date>(not finalized)</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>
45 <revnumber>current</revnumber>
46 <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
47 <authorinitials></authorinitials>
48 <revremark></revremark>
51 <revnumber>0.15</revnumber>
52 <date>3 November 2010</date>
53 <authorinitials></authorinitials>
54 <revremark></revremark>
57 <revnumber>0.14</revnumber>
58 <date>12 May 2010</date>
59 <authorinitials></authorinitials>
60 <revremark></revremark>
63 <revnumber>0.13</revnumber>
64 <date>23 Dezember 2009</date>
65 <authorinitials></authorinitials>
66 <revremark></revremark>
69 <revnumber>0.12</revnumber>
70 <date>7 November, 2006</date>
71 <authorinitials></authorinitials>
72 <revremark></revremark>
75 <revnumber>0.11</revnumber>
76 <date>6 February 2005</date>
77 <authorinitials></authorinitials>
78 <revremark></revremark>
81 <revnumber>0.10</revnumber>
82 <date>28 January 2005</date>
83 <authorinitials></authorinitials>
84 <revremark></revremark>
87 <revnumber>0.9</revnumber>
88 <date>7 Januar 2005</date>
89 <authorinitials></authorinitials>
90 <revremark></revremark>
93 <revnumber>0.8</revnumber>
94 <date>06 September 2003</date>
95 <authorinitials></authorinitials>
96 <revremark>First released document.</revremark>
101 <sect1 id="introduction">
102 <title>Introduction</title>
104 D-Bus is a system for low-latency, low-overhead, easy to use
105 interprocess communication (IPC). In more detail:
109 D-Bus is <emphasis>low-latency</emphasis> because it is designed
110 to avoid round trips and allow asynchronous operation, much like
116 D-Bus is <emphasis>low-overhead</emphasis> because it uses a
117 binary protocol, and does not have to convert to and from a text
118 format such as XML. Because D-Bus is intended for potentially
119 high-resolution same-machine IPC, not primarily for Internet IPC,
120 this is an interesting optimization.
125 D-Bus is <emphasis>easy to use</emphasis> because it works in terms
126 of <firstterm>messages</firstterm> rather than byte streams, and
127 automatically handles a lot of the hard IPC issues. Also, the D-Bus
128 library is designed to be wrapped in a way that lets developers use
129 their framework's existing object/type system, rather than learning
130 a new one specifically for IPC.
137 The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
138 protocol, specified in <xref linkend="message-protocol"/>. That is, it is
139 a system for one application to talk to a single other
140 application. However, the primary intended application of the protocol is the
141 D-Bus <firstterm>message bus</firstterm>, specified in <xref
142 linkend="message-bus"/>. The message bus is a special application that
143 accepts connections from multiple other applications, and forwards
148 Uses of D-Bus include notification of system changes (notification of when
149 a camera is plugged in to a computer, or a new version of some software
150 has been installed), or desktop interoperability, for example a file
151 monitoring service or a configuration service.
155 D-Bus is designed for two specific use cases:
159 A "system bus" for notifications from the system to user sessions,
160 and to allow the system to request input from user sessions.
165 A "session bus" used to implement desktop environments such as
170 D-Bus is not intended to be a generic IPC system for any possible
171 application, and intentionally omits many features found in other
172 IPC systems for this reason.
176 At the same time, the bus daemons offer a number of features not found in
177 other IPC systems, such as single-owner "bus names" (similar to X
178 selections), on-demand startup of services, and security policies.
179 In many ways, these features are the primary motivation for developing
180 D-Bus; other systems would have sufficed if IPC were the only goal.
184 D-Bus may turn out to be useful in unanticipated applications, but future
185 versions of this spec and the reference implementation probably will not
186 incorporate features that interfere with the core use cases.
190 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
191 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
192 document are to be interpreted as described in RFC 2119. However, the
193 document could use a serious audit to be sure it makes sense to do
194 so. Also, they are not capitalized.
197 <sect2 id="stability">
198 <title>Protocol and Specification Stability</title>
200 The D-Bus protocol is frozen (only compatible extensions are allowed) as
201 of November 8, 2006. However, this specification could still use a fair
202 bit of work to make interoperable reimplementation possible without
203 reference to the D-Bus reference implementation. Thus, this
204 specification is not marked 1.0. To mark it 1.0, we'd like to see
205 someone invest significant effort in clarifying the specification
206 language, and growing the specification to cover more aspects of the
207 reference implementation's behavior.
210 Until this work is complete, any attempt to reimplement D-Bus will
211 probably require looking at the reference implementation and/or asking
212 questions on the D-Bus mailing list about intended behavior.
213 Questions on the list are very welcome.
216 Nonetheless, this document should be a useful starting point and is
217 to our knowledge accurate, though incomplete.
223 <sect1 id="message-protocol">
224 <title>Message Protocol</title>
227 A <firstterm>message</firstterm> consists of a
228 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
229 think of a message as a package, the header is the address, and the body
230 contains the package contents. The message delivery system uses the header
231 information to figure out where to send the message and how to interpret
232 it; the recipient interprets the body of the message.
236 The body of the message is made up of zero or more
237 <firstterm>arguments</firstterm>, which are typed values, such as an
238 integer or a byte array.
242 Both header and body use the same type system and format for
243 serializing data. Each type of value has a wire format.
244 Converting a value from some other representation into the wire
245 format is called <firstterm>marshaling</firstterm> and converting
246 it back from the wire format is <firstterm>unmarshaling</firstterm>.
249 <sect2 id="message-protocol-signatures">
250 <title>Type Signatures</title>
253 The D-Bus protocol does not include type tags in the marshaled data; a
254 block of marshaled values must have a known <firstterm>type
255 signature</firstterm>. The type signature is made up of <firstterm>type
256 codes</firstterm>. A type code is an ASCII character representing the
257 type of a value. Because ASCII characters are used, the type signature
258 will always form a valid ASCII string. A simple string compare
259 determines whether two type signatures are equivalent.
263 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
264 the ASCII character 'i'. So the signature for a block of values
265 containing a single <literal>INT32</literal> would be:
269 A block of values containing two <literal>INT32</literal> would have this signature:
276 All <firstterm>basic</firstterm> types work like
277 <literal>INT32</literal> in this example. To marshal and unmarshal
278 basic types, you simply read one value from the data
279 block corresponding to each type code in the signature.
280 In addition to basic types, there are four <firstterm>container</firstterm>
281 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
282 and <literal>DICT_ENTRY</literal>.
286 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
287 code does not appear in signatures. Instead, ASCII characters
288 '(' and ')' are used to mark the beginning and end of the struct.
289 So for example, a struct containing two integers would have this
294 Structs can be nested, so for example a struct containing
295 an integer and another struct:
299 The value block storing that struct would contain three integers; the
300 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
305 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
306 but is useful in code that implements the protocol. This type code
307 is specified to allow such code to interoperate in non-protocol contexts.
311 Empty structures are not allowed; there must be at least one
312 type code between the parentheses.
316 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
317 followed by a <firstterm>single complete type</firstterm>. The single
318 complete type following the array is the type of each array element. So
319 the simple example is:
323 which is an array of 32-bit integers. But an array can be of any type,
324 such as this array-of-struct-with-two-int32-fields:
328 Or this array of array of integer:
335 The phrase <firstterm>single complete type</firstterm> deserves some
336 definition. A single complete type is a basic type code, a variant type code,
337 an array with its element type, or a struct with its fields.
338 So the following signatures are not single complete types:
348 And the following signatures contain multiple complete types:
358 Note however that a single complete type may <emphasis>contain</emphasis>
359 multiple other single complete types.
363 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
364 type <literal>VARIANT</literal> will have the signature of a single complete type as part
365 of the <emphasis>value</emphasis>. This signature will be followed by a
366 marshaled value of that type.
370 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
371 than parentheses it uses curly braces, and it has more restrictions.
372 The restrictions are: it occurs only as an array element type; it has
373 exactly two single complete types inside the curly braces; the first
374 single complete type (the "key") must be a basic type rather than a
375 container type. Implementations must not accept dict entries outside of
376 arrays, must not accept dict entries with zero, one, or more than two
377 fields, and must not accept dict entries with non-basic-typed keys. A
378 dict entry is always a key-value pair.
382 The first field in the <literal>DICT_ENTRY</literal> is always the key.
383 A message is considered corrupt if the same key occurs twice in the same
384 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
385 implementations are not required to reject dicts with duplicate keys.
389 In most languages, an array of dict entry would be represented as a
390 map, hash table, or dict object.
394 The following table summarizes the D-Bus types.
399 <entry>Conventional Name</entry>
401 <entry>Description</entry>
406 <entry><literal>INVALID</literal></entry>
407 <entry>0 (ASCII NUL)</entry>
408 <entry>Not a valid type code, used to terminate signatures</entry>
410 <entry><literal>BYTE</literal></entry>
411 <entry>121 (ASCII 'y')</entry>
412 <entry>8-bit unsigned integer</entry>
414 <entry><literal>BOOLEAN</literal></entry>
415 <entry>98 (ASCII 'b')</entry>
416 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
418 <entry><literal>INT16</literal></entry>
419 <entry>110 (ASCII 'n')</entry>
420 <entry>16-bit signed integer</entry>
422 <entry><literal>UINT16</literal></entry>
423 <entry>113 (ASCII 'q')</entry>
424 <entry>16-bit unsigned integer</entry>
426 <entry><literal>INT32</literal></entry>
427 <entry>105 (ASCII 'i')</entry>
428 <entry>32-bit signed integer</entry>
430 <entry><literal>UINT32</literal></entry>
431 <entry>117 (ASCII 'u')</entry>
432 <entry>32-bit unsigned integer</entry>
434 <entry><literal>INT64</literal></entry>
435 <entry>120 (ASCII 'x')</entry>
436 <entry>64-bit signed integer</entry>
438 <entry><literal>UINT64</literal></entry>
439 <entry>116 (ASCII 't')</entry>
440 <entry>64-bit unsigned integer</entry>
442 <entry><literal>DOUBLE</literal></entry>
443 <entry>100 (ASCII 'd')</entry>
444 <entry>IEEE 754 double</entry>
446 <entry><literal>STRING</literal></entry>
447 <entry>115 (ASCII 's')</entry>
448 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
450 <entry><literal>OBJECT_PATH</literal></entry>
451 <entry>111 (ASCII 'o')</entry>
452 <entry>Name of an object instance</entry>
454 <entry><literal>SIGNATURE</literal></entry>
455 <entry>103 (ASCII 'g')</entry>
456 <entry>A type signature</entry>
458 <entry><literal>ARRAY</literal></entry>
459 <entry>97 (ASCII 'a')</entry>
462 <entry><literal>STRUCT</literal></entry>
463 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
464 <entry>Struct</entry>
466 <entry><literal>VARIANT</literal></entry>
467 <entry>118 (ASCII 'v') </entry>
468 <entry>Variant type (the type of the value is part of the value itself)</entry>
470 <entry><literal>DICT_ENTRY</literal></entry>
471 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
472 <entry>Entry in a dict or map (array of key-value pairs)</entry>
474 <entry><literal>UNIX_FD</literal></entry>
475 <entry>104 (ASCII 'h')</entry>
476 <entry>Unix file descriptor</entry>
485 <sect2 id="message-protocol-marshaling">
486 <title>Marshaling (Wire Format)</title>
489 Given a type signature, a block of bytes can be converted into typed
490 values. This section describes the format of the block of bytes. Byte
491 order and alignment issues are handled uniformly for all D-Bus types.
495 A block of bytes has an associated byte order. The byte order
496 has to be discovered in some way; for D-Bus messages, the
497 byte order is part of the message header as described in
498 <xref linkend="message-protocol-messages"/>. For now, assume
499 that the byte order is known to be either little endian or big
504 Each value in a block of bytes is aligned "naturally," for example
505 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
506 8-byte boundary. To properly align a value, <firstterm>alignment
507 padding</firstterm> may be necessary. The alignment padding must always
508 be the minimum required padding to properly align the following value;
509 and it must always be made up of nul bytes. The alignment padding must
510 not be left uninitialized (it can't contain garbage), and more padding
511 than required must not be used.
515 Given all this, the types are marshaled on the wire as follows:
520 <entry>Conventional Name</entry>
521 <entry>Encoding</entry>
522 <entry>Alignment</entry>
527 <entry><literal>INVALID</literal></entry>
528 <entry>Not applicable; cannot be marshaled.</entry>
531 <entry><literal>BYTE</literal></entry>
532 <entry>A single 8-bit byte.</entry>
535 <entry><literal>BOOLEAN</literal></entry>
536 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
539 <entry><literal>INT16</literal></entry>
540 <entry>16-bit signed integer in the message's byte order.</entry>
543 <entry><literal>UINT16</literal></entry>
544 <entry>16-bit unsigned integer in the message's byte order.</entry>
547 <entry><literal>INT32</literal></entry>
548 <entry>32-bit signed integer in the message's byte order.</entry>
551 <entry><literal>UINT32</literal></entry>
552 <entry>32-bit unsigned integer in the message's byte order.</entry>
555 <entry><literal>INT64</literal></entry>
556 <entry>64-bit signed integer in the message's byte order.</entry>
559 <entry><literal>UINT64</literal></entry>
560 <entry>64-bit unsigned integer in the message's byte order.</entry>
563 <entry><literal>DOUBLE</literal></entry>
564 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
567 <entry><literal>STRING</literal></entry>
568 <entry>A <literal>UINT32</literal> indicating the string's
569 length in bytes excluding its terminating nul, followed by
570 non-nul string data of the given length, followed by a terminating nul
577 <entry><literal>OBJECT_PATH</literal></entry>
578 <entry>Exactly the same as <literal>STRING</literal> except the
579 content must be a valid object path (see below).
585 <entry><literal>SIGNATURE</literal></entry>
586 <entry>The same as <literal>STRING</literal> except the length is a single
587 byte (thus signatures have a maximum length of 255)
588 and the content must be a valid signature (see below).
594 <entry><literal>ARRAY</literal></entry>
596 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
597 alignment padding to the alignment boundary of the array element type,
598 followed by each array element. The array length is from the
599 end of the alignment padding to the end of the last element,
600 i.e. it does not include the padding after the length,
601 or any padding after the last element.
602 Arrays have a maximum length defined to be 2 to the 26th power or
603 67108864. Implementations must not send or accept arrays exceeding this
610 <entry><literal>STRUCT</literal></entry>
612 A struct must start on an 8-byte boundary regardless of the
613 type of the struct fields. The struct value consists of each
614 field marshaled in sequence starting from that 8-byte
621 <entry><literal>VARIANT</literal></entry>
623 A variant type has a marshaled
624 <literal>SIGNATURE</literal> followed by a marshaled
625 value with the type given in the signature. Unlike
626 a message signature, the variant signature can
627 contain only a single complete type. So "i", "ai"
628 or "(ii)" is OK, but "ii" is not. Use of variants may not
629 cause a total message depth to be larger than 64, including
630 other container types such as structures.
633 1 (alignment of the signature)
636 <entry><literal>DICT_ENTRY</literal></entry>
644 <entry><literal>UNIX_FD</literal></entry>
645 <entry>32-bit unsigned integer in the message's byte
646 order. The actual file descriptors need to be
647 transferred out-of-band via some platform specific
648 mechanism. On the wire, values of this type store the index to the
649 file descriptor in the array of file descriptors that
650 accompany the message.</entry>
658 <sect3 id="message-protocol-marshaling-object-path">
659 <title>Valid Object Paths</title>
662 An object path is a name used to refer to an object instance.
663 Conceptually, each participant in a D-Bus message exchange may have
664 any number of object instances (think of C++ or Java objects) and each
665 such instance will have a path. Like a filesystem, the object
666 instances in an application form a hierarchical tree.
670 The following rules define a valid object path. Implementations must
671 not send or accept messages with invalid object paths.
675 The path may be of any length.
680 The path must begin with an ASCII '/' (integer 47) character,
681 and must consist of elements separated by slash characters.
686 Each element must only contain the ASCII characters
692 No element may be the empty string.
697 Multiple '/' characters cannot occur in sequence.
702 A trailing '/' character is not allowed unless the
703 path is the root path (a single '/' character).
712 <sect3 id="message-protocol-marshaling-signature">
713 <title>Valid Signatures</title>
715 An implementation must not send or accept invalid signatures.
716 Valid signatures will conform to the following rules:
720 The signature ends with a nul byte.
725 The signature is a list of single complete types.
726 Arrays must have element types, and structs must
727 have both open and close parentheses.
732 Only type codes and open and close parentheses are
733 allowed in the signature. The <literal>STRUCT</literal> type code
734 is not allowed in signatures, because parentheses
740 The maximum depth of container type nesting is 32 array type
741 codes and 32 open parentheses. This implies that the maximum
742 total depth of recursion is 64, for an "array of array of array
743 of ... struct of struct of struct of ..." where there are 32
749 The maximum length of a signature is 255.
754 Signatures must be nul-terminated.
763 <sect2 id="message-protocol-messages">
764 <title>Message Format</title>
767 A message consists of a header and a body. The header is a block of
768 values with a fixed signature and meaning. The body is a separate block
769 of values, with a signature specified in the header.
773 The length of the header must be a multiple of 8, allowing the body to
774 begin on an 8-byte boundary when storing the entire message in a single
775 buffer. If the header does not naturally end on an 8-byte boundary
776 up to 7 bytes of nul-initialized alignment padding must be added.
780 The message body need not end on an 8-byte boundary.
784 The maximum length of a message, including header, header alignment padding,
785 and body is 2 to the 27th power or 134217728. Implementations must not
786 send or accept messages exceeding this size.
790 The signature of the header is:
794 Written out more readably, this is:
796 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
801 These values have the following meanings:
807 <entry>Description</entry>
812 <entry>1st <literal>BYTE</literal></entry>
813 <entry>Endianness flag; ASCII 'l' for little-endian
814 or ASCII 'B' for big-endian. Both header and body are
815 in this endianness.</entry>
818 <entry>2nd <literal>BYTE</literal></entry>
819 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
820 Currently-defined types are described below.
824 <entry>3rd <literal>BYTE</literal></entry>
825 <entry>Bitwise OR of flags. Unknown flags
826 must be ignored. Currently-defined flags are described below.
830 <entry>4th <literal>BYTE</literal></entry>
831 <entry>Major protocol version of the sending application. If
832 the major protocol version of the receiving application does not
833 match, the applications will not be able to communicate and the
834 D-Bus connection must be disconnected. The major protocol
835 version for this version of the specification is 1.
839 <entry>1st <literal>UINT32</literal></entry>
840 <entry>Length in bytes of the message body, starting
841 from the end of the header. The header ends after
842 its alignment padding to an 8-boundary.
846 <entry>2nd <literal>UINT32</literal></entry>
847 <entry>The serial of this message, used as a cookie
848 by the sender to identify the reply corresponding
849 to this request. This must not be zero.
853 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
854 <entry>An array of zero or more <firstterm>header
855 fields</firstterm> where the byte is the field code, and the
856 variant is the field value. The message type determines
857 which fields are required.
865 <firstterm>Message types</firstterm> that can appear in the second byte
871 <entry>Conventional name</entry>
872 <entry>Decimal value</entry>
873 <entry>Description</entry>
878 <entry><literal>INVALID</literal></entry>
880 <entry>This is an invalid type.</entry>
883 <entry><literal>METHOD_CALL</literal></entry>
885 <entry>Method call.</entry>
888 <entry><literal>METHOD_RETURN</literal></entry>
890 <entry>Method reply with returned data.</entry>
893 <entry><literal>ERROR</literal></entry>
895 <entry>Error reply. If the first argument exists and is a
896 string, it is an error message.</entry>
899 <entry><literal>SIGNAL</literal></entry>
901 <entry>Signal emission.</entry>
908 Flags that can appear in the third byte of the header:
913 <entry>Conventional name</entry>
914 <entry>Hex value</entry>
915 <entry>Description</entry>
920 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
922 <entry>This message does not expect method return replies or
923 error replies; the reply can be omitted as an
924 optimization. However, it is compliant with this specification
925 to return the reply despite this flag and the only harm
926 from doing so is extra network traffic.
930 <entry><literal>NO_AUTO_START</literal></entry>
932 <entry>The bus must not launch an owner
933 for the destination name in response to this message.
941 <sect3 id="message-protocol-header-fields">
942 <title>Header Fields</title>
945 The array at the end of the header contains <firstterm>header
946 fields</firstterm>, where each field is a 1-byte field code followed
947 by a field value. A header must contain the required header fields for
948 its message type, and zero or more of any optional header
949 fields. Future versions of this protocol specification may add new
950 fields. Implementations must ignore fields they do not
951 understand. Implementations must not invent their own header fields;
952 only changes to this specification may introduce new header fields.
956 Again, if an implementation sees a header field code that it does not
957 expect, it must ignore that field, as it will be part of a new
958 (but compatible) version of this specification. This also applies
959 to known header fields appearing in unexpected messages, for
960 example: if a signal has a reply serial it must be ignored
961 even though it has no meaning as of this version of the spec.
965 However, implementations must not send or accept known header fields
966 with the wrong type stored in the field value. So for example a
967 message with an <literal>INTERFACE</literal> field of type
968 <literal>UINT32</literal> would be considered corrupt.
972 Here are the currently-defined header fields:
977 <entry>Conventional Name</entry>
978 <entry>Decimal Code</entry>
980 <entry>Required In</entry>
981 <entry>Description</entry>
986 <entry><literal>INVALID</literal></entry>
989 <entry>not allowed</entry>
990 <entry>Not a valid field name (error if it appears in a message)</entry>
993 <entry><literal>PATH</literal></entry>
995 <entry><literal>OBJECT_PATH</literal></entry>
996 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
997 <entry>The object to send a call to,
998 or the object a signal is emitted from.
1000 <literal>/org/freedesktop/DBus/Local</literal> is reserved;
1001 implementations should not send messages with this path,
1002 and the reference implementation of the bus daemon will
1003 disconnect any application that attempts to do so.
1007 <entry><literal>INTERFACE</literal></entry>
1009 <entry><literal>STRING</literal></entry>
1010 <entry><literal>SIGNAL</literal></entry>
1012 The interface to invoke a method call on, or
1013 that a signal is emitted from. Optional for
1014 method calls, required for signals.
1015 The special interface
1016 <literal>org.freedesktop.DBus.Local</literal> is reserved;
1017 implementations should not send messages with this
1018 interface, and the reference implementation of the bus
1019 daemon will disconnect any application that attempts to
1024 <entry><literal>MEMBER</literal></entry>
1026 <entry><literal>STRING</literal></entry>
1027 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1028 <entry>The member, either the method name or signal name.</entry>
1031 <entry><literal>ERROR_NAME</literal></entry>
1033 <entry><literal>STRING</literal></entry>
1034 <entry><literal>ERROR</literal></entry>
1035 <entry>The name of the error that occurred, for errors</entry>
1038 <entry><literal>REPLY_SERIAL</literal></entry>
1040 <entry><literal>UINT32</literal></entry>
1041 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
1042 <entry>The serial number of the message this message is a reply
1043 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
1046 <entry><literal>DESTINATION</literal></entry>
1048 <entry><literal>STRING</literal></entry>
1049 <entry>optional</entry>
1050 <entry>The name of the connection this message is intended for.
1051 Only used in combination with the message bus, see
1052 <xref linkend="message-bus"/>.</entry>
1055 <entry><literal>SENDER</literal></entry>
1057 <entry><literal>STRING</literal></entry>
1058 <entry>optional</entry>
1059 <entry>Unique name of the sending connection.
1060 The message bus fills in this field so it is reliable; the field is
1061 only meaningful in combination with the message bus.</entry>
1064 <entry><literal>SIGNATURE</literal></entry>
1066 <entry><literal>SIGNATURE</literal></entry>
1067 <entry>optional</entry>
1068 <entry>The signature of the message body.
1069 If omitted, it is assumed to be the
1070 empty signature "" (i.e. the body must be 0-length).</entry>
1073 <entry><literal>UNIX_FDS</literal></entry>
1075 <entry><literal>UINT32</literal></entry>
1076 <entry>optional</entry>
1077 <entry>The number of Unix file descriptors that
1078 accompany the message. If omitted, it is assumed
1079 that no Unix file descriptors accompany the
1080 message. The actual file descriptors need to be
1081 transferred via platform specific mechanism
1082 out-of-band. They must be sent at the same time as
1083 part of the message itself. They may not be sent
1084 before the first byte of the message itself is
1085 transferred or after the last byte of the message
1095 <sect2 id="message-protocol-names">
1096 <title>Valid Names</title>
1098 The various names in D-Bus messages have some restrictions.
1101 There is a <firstterm>maximum name length</firstterm>
1102 of 255 which applies to bus names, interfaces, and members.
1104 <sect3 id="message-protocol-names-interface">
1105 <title>Interface names</title>
1107 Interfaces have names with type <literal>STRING</literal>, meaning that
1108 they must be valid UTF-8. However, there are also some
1109 additional restrictions that apply to interface names
1112 <listitem><para>Interface names are composed of 1 or more elements separated by
1113 a period ('.') character. All elements must contain at least
1117 <listitem><para>Each element must only contain the ASCII characters
1118 "[A-Z][a-z][0-9]_" and must not begin with a digit.
1122 <listitem><para>Interface names must contain at least one '.' (period)
1123 character (and thus at least two elements).
1126 <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
1127 <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
1131 <sect3 id="message-protocol-names-bus">
1132 <title>Bus names</title>
1134 Connections have one or more bus names associated with them.
1135 A connection has exactly one bus name that is a unique connection
1136 name. The unique connection name remains with the connection for
1137 its entire lifetime.
1138 A bus name is of type <literal>STRING</literal>,
1139 meaning that it must be valid UTF-8. However, there are also
1140 some additional restrictions that apply to bus names
1143 <listitem><para>Bus names that start with a colon (':')
1144 character are unique connection names.
1147 <listitem><para>Bus names are composed of 1 or more elements separated by
1148 a period ('.') character. All elements must contain at least
1152 <listitem><para>Each element must only contain the ASCII characters
1153 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
1154 connection name may begin with a digit, elements in
1155 other bus names must not begin with a digit.
1159 <listitem><para>Bus names must contain at least one '.' (period)
1160 character (and thus at least two elements).
1163 <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
1164 <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
1168 Note that the hyphen ('-') character is allowed in bus names but
1169 not in interface names.
1172 <sect3 id="message-protocol-names-member">
1173 <title>Member names</title>
1175 Member (i.e. method or signal) names:
1177 <listitem><para>Must only contain the ASCII characters
1178 "[A-Z][a-z][0-9]_" and may not begin with a
1179 digit.</para></listitem>
1180 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1181 <listitem><para>Must not exceed the maximum name length.</para></listitem>
1182 <listitem><para>Must be at least 1 byte in length.</para></listitem>
1186 <sect3 id="message-protocol-names-error">
1187 <title>Error names</title>
1189 Error names have the same restrictions as interface names.
1194 <sect2 id="message-protocol-types">
1195 <title>Message Types</title>
1197 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1198 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1199 This section describes these conventions.
1201 <sect3 id="message-protocol-types-method">
1202 <title>Method Calls</title>
1204 Some messages invoke an operation on a remote object. These are
1205 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1206 messages map naturally to methods on objects in a typical program.
1209 A method call message is required to have a <literal>MEMBER</literal> header field
1210 indicating the name of the method. Optionally, the message has an
1211 <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1212 absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1213 a method with the same name, it is undefined which of the two methods
1214 will be invoked. Implementations may also choose to return an error in
1215 this ambiguous case. However, if a method name is unique
1216 implementations must not require an interface field.
1219 Method call messages also include a <literal>PATH</literal> field
1220 indicating the object to invoke the method on. If the call is passing
1221 through a message bus, the message will also have a
1222 <literal>DESTINATION</literal> field giving the name of the connection
1223 to receive the message.
1226 When an application handles a method call message, it is required to
1227 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1228 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1229 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1232 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1233 are the return value(s) or "out parameters" of the method call.
1234 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1235 and the call fails; no return value will be provided. It makes
1236 no sense to send multiple replies to the same method call.
1239 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1240 reply is required, so the caller will know the method
1241 was successfully processed.
1244 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1248 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1249 then as an optimization the application receiving the method
1250 call may choose to omit the reply message (regardless of
1251 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1252 However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1253 flag and reply anyway.
1256 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1257 destination name does not exist then a program to own the destination
1258 name will be started before the message is delivered. The message
1259 will be held until the new program is successfully started or has
1260 failed to start; in case of failure, an error will be returned. This
1261 flag is only relevant in the context of a message bus, it is ignored
1262 during one-to-one communication with no intermediate bus.
1264 <sect4 id="message-protocol-types-method-apis">
1265 <title>Mapping method calls to native APIs</title>
1267 APIs for D-Bus may map method calls to a method call in a specific
1268 programming language, such as C++, or may map a method call written
1269 in an IDL to a D-Bus message.
1272 In APIs of this nature, arguments to a method are often termed "in"
1273 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1274 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1275 "inout" arguments, which are both sent and received, i.e. the caller
1276 passes in a value which is modified. Mapped to D-Bus, an "inout"
1277 argument is equivalent to an "in" argument, followed by an "out"
1278 argument. You can't pass things "by reference" over the wire, so
1279 "inout" is purely an illusion of the in-process API.
1282 Given a method with zero or one return values, followed by zero or more
1283 arguments, where each argument may be "in", "out", or "inout", the
1284 caller constructs a message by appending each "in" or "inout" argument,
1285 in order. "out" arguments are not represented in the caller's message.
1288 The recipient constructs a reply by appending first the return value
1289 if any, then each "out" or "inout" argument, in order.
1290 "in" arguments are not represented in the reply message.
1293 Error replies are normally mapped to exceptions in languages that have
1297 In converting from native APIs to D-Bus, it is perhaps nice to
1298 map D-Bus naming conventions ("FooBar") to native conventions
1299 such as "fooBar" or "foo_bar" automatically. This is OK
1300 as long as you can say that the native API is one that
1301 was specifically written for D-Bus. It makes the most sense
1302 when writing object implementations that will be exported
1303 over the bus. Object proxies used to invoke remote D-Bus
1304 objects probably need the ability to call any D-Bus method,
1305 and thus a magic name mapping like this could be a problem.
1308 This specification doesn't require anything of native API bindings;
1309 the preceding is only a suggested convention for consistency
1315 <sect3 id="message-protocol-types-signal">
1316 <title>Signal Emission</title>
1318 Unlike method calls, signal emissions have no replies.
1319 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1320 It must have three header fields: <literal>PATH</literal> giving the object
1321 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1322 the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
1323 for signals, though it is optional for method calls.
1327 <sect3 id="message-protocol-types-errors">
1328 <title>Errors</title>
1330 Messages of type <literal>ERROR</literal> are most commonly replies
1331 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1332 to any kind of message. The message bus for example
1333 will return an <literal>ERROR</literal> in reply to a signal emission if
1334 the bus does not have enough memory to send the signal.
1337 An <literal>ERROR</literal> may have any arguments, but if the first
1338 argument is a <literal>STRING</literal>, it must be an error message.
1339 The error message may be logged or shown to the user
1344 <sect3 id="message-protocol-types-notation">
1345 <title>Notation in this document</title>
1347 This document uses a simple pseudo-IDL to describe particular method
1348 calls and signals. Here is an example of a method call:
1350 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1351 out UINT32 resultcode)
1353 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1354 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1355 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1356 characters so it's known that the last part of the name in
1357 the "IDL" is the member name.
1360 In C++ that might end up looking like this:
1362 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1363 unsigned int flags);
1365 or equally valid, the return value could be done as an argument:
1367 void org::freedesktop::DBus::StartServiceByName (const char *name,
1369 unsigned int *resultcode);
1371 It's really up to the API designer how they want to make
1372 this look. You could design an API where the namespace wasn't used
1373 in C++, using STL or Qt, using varargs, or whatever you wanted.
1376 Signals are written as follows:
1378 org.freedesktop.DBus.NameLost (STRING name)
1380 Signals don't specify "in" vs. "out" because only
1381 a single direction is possible.
1384 It isn't especially encouraged to use this lame pseudo-IDL in actual
1385 API implementations; you might use the native notation for the
1386 language you're using, or you might use COM or CORBA IDL, for example.
1391 <sect2 id="message-protocol-handling-invalid">
1392 <title>Invalid Protocol and Spec Extensions</title>
1395 For security reasons, the D-Bus protocol should be strictly parsed and
1396 validated, with the exception of defined extension points. Any invalid
1397 protocol or spec violations should result in immediately dropping the
1398 connection without notice to the other end. Exceptions should be
1399 carefully considered, e.g. an exception may be warranted for a
1400 well-understood idiosyncrasy of a widely-deployed implementation. In
1401 cases where the other end of a connection is 100% trusted and known to
1402 be friendly, skipping validation for performance reasons could also make
1403 sense in certain cases.
1407 Generally speaking violations of the "must" requirements in this spec
1408 should be considered possible attempts to exploit security, and violations
1409 of the "should" suggestions should be considered legitimate (though perhaps
1410 they should generate an error in some cases).
1414 The following extension points are built in to D-Bus on purpose and must
1415 not be treated as invalid protocol. The extension points are intended
1416 for use by future versions of this spec, they are not intended for third
1417 parties. At the moment, the only way a third party could extend D-Bus
1418 without breaking interoperability would be to introduce a way to negotiate new
1419 feature support as part of the auth protocol, using EXTENSION_-prefixed
1420 commands. There is not yet a standard way to negotiate features.
1424 In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
1425 commands result in an ERROR rather than a disconnect. This enables
1426 future extensions to the protocol. Commands starting with EXTENSION_ are
1427 reserved for third parties.
1432 The authentication protocol supports pluggable auth mechanisms.
1437 The address format (see <xref linkend="addresses"/>) supports new
1443 Messages with an unknown type (something other than
1444 <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
1445 <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
1446 Unknown-type messages must still be well-formed in the same way
1447 as the known messages, however. They still have the normal
1453 Header fields with an unknown or unexpected field code must be ignored,
1454 though again they must still be well-formed.
1459 New standard interfaces (with new methods and signals) can of course be added.
1469 <sect1 id="auth-protocol">
1470 <title>Authentication Protocol</title>
1472 Before the flow of messages begins, two applications must
1473 authenticate. A simple plain-text protocol is used for
1474 authentication; this protocol is a SASL profile, and maps fairly
1475 directly from the SASL specification. The message encoding is
1476 NOT used here, only plain text messages.
1479 In examples, "C:" and "S:" indicate lines sent by the client and
1480 server respectively.
1482 <sect2 id="auth-protocol-overview">
1483 <title>Protocol Overview</title>
1485 The protocol is a line-based protocol, where each line ends with
1486 \r\n. Each line begins with an all-caps ASCII command name containing
1487 only the character range [A-Z_], a space, then any arguments for the
1488 command, then the \r\n ending the line. The protocol is
1489 case-sensitive. All bytes must be in the ASCII character set.
1491 Commands from the client to the server are as follows:
1494 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1495 <listitem><para>CANCEL</para></listitem>
1496 <listitem><para>BEGIN</para></listitem>
1497 <listitem><para>DATA <data in hex encoding></para></listitem>
1498 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1499 <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
1502 From server to client are as follows:
1505 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
1506 <listitem><para>OK <GUID in hex></para></listitem>
1507 <listitem><para>DATA <data in hex encoding></para></listitem>
1508 <listitem><para>ERROR</para></listitem>
1509 <listitem><para>AGREE_UNIX_FD</para></listitem>
1513 Unofficial extensions to the command set must begin with the letters
1514 "EXTENSION_", to avoid conflicts with future official commands.
1515 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
1518 <sect2 id="auth-nul-byte">
1519 <title>Special credentials-passing nul byte</title>
1521 Immediately after connecting to the server, the client must send a
1522 single nul byte. This byte may be accompanied by credentials
1523 information on some operating systems that use sendmsg() with
1524 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1525 sockets. However, the nul byte must be sent even on other kinds of
1526 socket, and even on operating systems that do not require a byte to be
1527 sent in order to transmit credentials. The text protocol described in
1528 this document begins after the single nul byte. If the first byte
1529 received from the client is not a nul byte, the server may disconnect
1533 A nul byte in any context other than the initial byte is an error;
1534 the protocol is ASCII-only.
1537 The credentials sent along with the nul byte may be used with the
1538 SASL mechanism EXTERNAL.
1541 <sect2 id="auth-command-auth">
1542 <title>AUTH command</title>
1544 If an AUTH command has no arguments, it is a request to list
1545 available mechanisms. The server must respond with a REJECTED
1546 command listing the mechanisms it understands, or with an error.
1549 If an AUTH command specifies a mechanism, and the server supports
1550 said mechanism, the server should begin exchanging SASL
1551 challenge-response data with the client using DATA commands.
1554 If the server does not support the mechanism given in the AUTH
1555 command, it must send either a REJECTED command listing the mechanisms
1556 it does support, or an error.
1559 If the [initial-response] argument is provided, it is intended for use
1560 with mechanisms that have no initial challenge (or an empty initial
1561 challenge), as if it were the argument to an initial DATA command. If
1562 the selected mechanism has an initial challenge and [initial-response]
1563 was provided, the server should reject authentication by sending
1567 If authentication succeeds after exchanging DATA commands,
1568 an OK command must be sent to the client.
1571 The first octet received by the server after the \r\n of the BEGIN
1572 command from the client must be the first octet of the
1573 authenticated/encrypted stream of D-Bus messages.
1576 If BEGIN is received by the server, the first octet received
1577 by the client after the \r\n of the OK command must be the
1578 first octet of the authenticated/encrypted stream of D-Bus
1582 <sect2 id="auth-command-cancel">
1583 <title>CANCEL Command</title>
1585 At any time up to sending the BEGIN command, the client may send a
1586 CANCEL command. On receiving the CANCEL command, the server must
1587 send a REJECTED command and abort the current authentication
1591 <sect2 id="auth-command-data">
1592 <title>DATA Command</title>
1594 The DATA command may come from either client or server, and simply
1595 contains a hex-encoded block of data to be interpreted
1596 according to the SASL mechanism in use.
1599 Some SASL mechanisms support sending an "empty string";
1600 FIXME we need some way to do this.
1603 <sect2 id="auth-command-begin">
1604 <title>BEGIN Command</title>
1606 The BEGIN command acknowledges that the client has received an
1607 OK command from the server, and that the stream of messages
1611 The first octet received by the server after the \r\n of the BEGIN
1612 command from the client must be the first octet of the
1613 authenticated/encrypted stream of D-Bus messages.
1616 <sect2 id="auth-command-rejected">
1617 <title>REJECTED Command</title>
1619 The REJECTED command indicates that the current authentication
1620 exchange has failed, and further exchange of DATA is inappropriate.
1621 The client would normally try another mechanism, or try providing
1622 different responses to challenges.
1624 Optionally, the REJECTED command has a space-separated list of
1625 available auth mechanisms as arguments. If a server ever provides
1626 a list of supported mechanisms, it must provide the same list
1627 each time it sends a REJECTED message. Clients are free to
1628 ignore all lists received after the first.
1631 <sect2 id="auth-command-ok">
1632 <title>OK Command</title>
1634 The OK command indicates that the client has been
1635 authenticated. The client may now proceed with negotiating
1636 Unix file descriptor passing. To do that it shall send
1637 NEGOTIATE_UNIX_FD to the server.
1640 Otherwise, the client must respond to the OK command by
1641 sending a BEGIN command, followed by its stream of messages,
1642 or by disconnecting. The server must not accept additional
1643 commands using this protocol after the BEGIN command has been
1644 received. Further communication will be a stream of D-Bus
1645 messages (optionally encrypted, as negotiated) rather than
1649 If a client sends BEGIN the first octet received by the client
1650 after the \r\n of the OK command must be the first octet of
1651 the authenticated/encrypted stream of D-Bus messages.
1654 The OK command has one argument, which is the GUID of the server.
1655 See <xref linkend="addresses"/> for more on server GUIDs.
1658 <sect2 id="auth-command-error">
1659 <title>ERROR Command</title>
1661 The ERROR command indicates that either server or client did not
1662 know a command, does not accept the given command in the current
1663 context, or did not understand the arguments to the command. This
1664 allows the protocol to be extended; a client or server can send a
1665 command present or permitted only in new protocol versions, and if
1666 an ERROR is received instead of an appropriate response, fall back
1667 to using some other technique.
1670 If an ERROR is sent, the server or client that sent the
1671 error must continue as if the command causing the ERROR had never been
1672 received. However, the the server or client receiving the error
1673 should try something other than whatever caused the error;
1674 if only canceling/rejecting the authentication.
1677 If the D-Bus protocol changes incompatibly at some future time,
1678 applications implementing the new protocol would probably be able to
1679 check for support of the new protocol by sending a new command and
1680 receiving an ERROR from applications that don't understand it. Thus the
1681 ERROR feature of the auth protocol is an escape hatch that lets us
1682 negotiate extensions or changes to the D-Bus protocol in the future.
1685 <sect2 id="auth-command-negotiate-unix-fd">
1686 <title>NEGOTIATE_UNIX_FD Command</title>
1688 The NEGOTIATE_UNIX_FD command indicates that the client
1689 supports Unix file descriptor passing. This command may only
1690 be sent after the connection is authenticated, i.e. after OK
1691 was received by the client. This command may only be sent on
1692 transports that support Unix file descriptor passing.
1695 On receiving NEGOTIATE_UNIX_FD the server must respond with
1696 either AGREE_UNIX_FD or ERROR. It shall respond the former if
1697 the transport chosen supports Unix file descriptor passing and
1698 the server supports this feature. It shall respond the latter
1699 if the transport does not support Unix file descriptor
1700 passing, the server does not support this feature, or the
1701 server decides not to enable file descriptor passing due to
1702 security or other reasons.
1705 <sect2 id="auth-command-agree-unix-fd">
1706 <title>AGREE_UNIX_FD Command</title>
1708 The AGREE_UNIX_FD command indicates that the server supports
1709 Unix file descriptor passing. This command may only be sent
1710 after the connection is authenticated, and the client sent
1711 NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
1712 command may only be sent on transports that support Unix file
1716 On receiving AGREE_UNIX_FD the client must respond with BEGIN,
1717 followed by its stream of messages, or by disconnecting. The
1718 server must not accept additional commands using this protocol
1719 after the BEGIN command has been received. Further
1720 communication will be a stream of D-Bus messages (optionally
1721 encrypted, as negotiated) rather than this protocol.
1724 <sect2 id="auth-command-future">
1725 <title>Future Extensions</title>
1727 Future extensions to the authentication and negotiation
1728 protocol are possible. For that new commands may be
1729 introduced. If a client or server receives an unknown command
1730 it shall respond with ERROR and not consider this fatal. New
1731 commands may be introduced both before, and after
1732 authentication, i.e. both before and after the OK command.
1735 <sect2 id="auth-examples">
1736 <title>Authentication examples</title>
1740 <title>Example of successful magic cookie authentication</title>
1742 (MAGIC_COOKIE is a made up mechanism)
1744 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1750 <title>Example of finding out mechanisms then picking one</title>
1753 S: REJECTED KERBEROS_V4 SKEY
1754 C: AUTH SKEY 7ab83f32ee
1755 S: DATA 8799cabb2ea93e
1756 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1762 <title>Example of client sends unknown command then falls back to regular auth</title>
1766 C: AUTH MAGIC_COOKIE 3736343435313230333039
1772 <title>Example of server doesn't support initial auth mechanism</title>
1774 C: AUTH MAGIC_COOKIE 3736343435313230333039
1775 S: REJECTED KERBEROS_V4 SKEY
1776 C: AUTH SKEY 7ab83f32ee
1777 S: DATA 8799cabb2ea93e
1778 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1784 <title>Example of wrong password or the like followed by successful retry</title>
1786 C: AUTH MAGIC_COOKIE 3736343435313230333039
1787 S: REJECTED KERBEROS_V4 SKEY
1788 C: AUTH SKEY 7ab83f32ee
1789 S: DATA 8799cabb2ea93e
1790 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1792 C: AUTH SKEY 7ab83f32ee
1793 S: DATA 8799cabb2ea93e
1794 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1800 <title>Example of skey cancelled and restarted</title>
1802 C: AUTH MAGIC_COOKIE 3736343435313230333039
1803 S: REJECTED KERBEROS_V4 SKEY
1804 C: AUTH SKEY 7ab83f32ee
1805 S: DATA 8799cabb2ea93e
1808 C: AUTH SKEY 7ab83f32ee
1809 S: DATA 8799cabb2ea93e
1810 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1816 <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
1818 (MAGIC_COOKIE is a made up mechanism)
1820 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1822 C: NEGOTIATE_UNIX_FD
1828 <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
1830 (MAGIC_COOKIE is a made up mechanism)
1832 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1834 C: NEGOTIATE_UNIX_FD
1841 <sect2 id="auth-states">
1842 <title>Authentication state diagrams</title>
1845 This section documents the auth protocol in terms of
1846 a state machine for the client and the server. This is
1847 probably the most robust way to implement the protocol.
1850 <sect3 id="auth-states-client">
1851 <title>Client states</title>
1854 To more precisely describe the interaction between the
1855 protocol state machine and the authentication mechanisms the
1856 following notation is used: MECH(CHALL) means that the
1857 server challenge CHALL was fed to the mechanism MECH, which
1863 CONTINUE(RESP) means continue the auth conversation
1864 and send RESP as the response to the server;
1870 OK(RESP) means that after sending RESP to the server
1871 the client side of the auth conversation is finished
1872 and the server should return "OK";
1878 ERROR means that CHALL was invalid and could not be
1884 Both RESP and CHALL may be empty.
1888 The Client starts by getting an initial response from the
1889 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1890 the mechanism did not provide an initial response. If the
1891 mechanism returns CONTINUE, the client starts in state
1892 <emphasis>WaitingForData</emphasis>, if the mechanism
1893 returns OK the client starts in state
1894 <emphasis>WaitingForOK</emphasis>.
1898 The client should keep track of available mechanisms and
1899 which it mechanisms it has already attempted. This list is
1900 used to decide which AUTH command to send. When the list is
1901 exhausted, the client should give up and close the
1906 <title><emphasis>WaitingForData</emphasis></title>
1914 MECH(CHALL) returns CONTINUE(RESP) → send
1916 <emphasis>WaitingForData</emphasis>
1920 MECH(CHALL) returns OK(RESP) → send DATA
1921 RESP, goto <emphasis>WaitingForOK</emphasis>
1925 MECH(CHALL) returns ERROR → send ERROR
1926 [msg], goto <emphasis>WaitingForData</emphasis>
1934 Receive REJECTED [mechs] →
1935 send AUTH [next mech], goto
1936 WaitingForData or <emphasis>WaitingForOK</emphasis>
1941 Receive ERROR → send
1943 <emphasis>WaitingForReject</emphasis>
1948 Receive OK → send
1949 BEGIN, terminate auth
1950 conversation, authenticated
1955 Receive anything else → send
1957 <emphasis>WaitingForData</emphasis>
1965 <title><emphasis>WaitingForOK</emphasis></title>
1970 Receive OK → send BEGIN, terminate auth
1971 conversation, <emphasis>authenticated</emphasis>
1976 Receive REJECT [mechs] → send AUTH [next mech],
1977 goto <emphasis>WaitingForData</emphasis> or
1978 <emphasis>WaitingForOK</emphasis>
1984 Receive DATA → send CANCEL, goto
1985 <emphasis>WaitingForReject</emphasis>
1991 Receive ERROR → send CANCEL, goto
1992 <emphasis>WaitingForReject</emphasis>
1998 Receive anything else → send ERROR, goto
1999 <emphasis>WaitingForOK</emphasis>
2007 <title><emphasis>WaitingForReject</emphasis></title>
2012 Receive REJECT [mechs] → send AUTH [next mech],
2013 goto <emphasis>WaitingForData</emphasis> or
2014 <emphasis>WaitingForOK</emphasis>
2020 Receive anything else → terminate auth
2021 conversation, disconnect
2030 <sect3 id="auth-states-server">
2031 <title>Server states</title>
2034 For the server MECH(RESP) means that the client response
2035 RESP was fed to the the mechanism MECH, which returns one of
2040 CONTINUE(CHALL) means continue the auth conversation and
2041 send CHALL as the challenge to the client;
2047 OK means that the client has been successfully
2054 REJECT means that the client failed to authenticate or
2055 there was an error in RESP.
2060 The server starts out in state
2061 <emphasis>WaitingForAuth</emphasis>. If the client is
2062 rejected too many times the server must disconnect the
2067 <title><emphasis>WaitingForAuth</emphasis></title>
2073 Receive AUTH → send REJECTED [mechs], goto
2074 <emphasis>WaitingForAuth</emphasis>
2080 Receive AUTH MECH RESP
2084 MECH not valid mechanism → send REJECTED
2086 <emphasis>WaitingForAuth</emphasis>
2090 MECH(RESP) returns CONTINUE(CHALL) → send
2092 <emphasis>WaitingForData</emphasis>
2096 MECH(RESP) returns OK → send OK, goto
2097 <emphasis>WaitingForBegin</emphasis>
2101 MECH(RESP) returns REJECT → send REJECTED
2103 <emphasis>WaitingForAuth</emphasis>
2111 Receive BEGIN → terminate
2112 auth conversation, disconnect
2118 Receive ERROR → send REJECTED [mechs], goto
2119 <emphasis>WaitingForAuth</emphasis>
2125 Receive anything else → send
2127 <emphasis>WaitingForAuth</emphasis>
2136 <title><emphasis>WaitingForData</emphasis></title>
2144 MECH(RESP) returns CONTINUE(CHALL) → send
2146 <emphasis>WaitingForData</emphasis>
2150 MECH(RESP) returns OK → send OK, goto
2151 <emphasis>WaitingForBegin</emphasis>
2155 MECH(RESP) returns REJECT → send REJECTED
2157 <emphasis>WaitingForAuth</emphasis>
2165 Receive BEGIN → terminate auth conversation,
2172 Receive CANCEL → send REJECTED [mechs], goto
2173 <emphasis>WaitingForAuth</emphasis>
2179 Receive ERROR → send REJECTED [mechs], goto
2180 <emphasis>WaitingForAuth</emphasis>
2186 Receive anything else → send ERROR, goto
2187 <emphasis>WaitingForData</emphasis>
2195 <title><emphasis>WaitingForBegin</emphasis></title>
2200 Receive BEGIN → terminate auth conversation,
2201 client authenticated
2207 Receive CANCEL → send REJECTED [mechs], goto
2208 <emphasis>WaitingForAuth</emphasis>
2214 Receive ERROR → send REJECTED [mechs], goto
2215 <emphasis>WaitingForAuth</emphasis>
2221 Receive anything else → send ERROR, goto
2222 <emphasis>WaitingForBegin</emphasis>
2232 <sect2 id="auth-mechanisms">
2233 <title>Authentication mechanisms</title>
2235 This section describes some new authentication mechanisms.
2236 D-Bus also allows any standard SASL mechanism of course.
2238 <sect3 id="auth-mechanisms-sha">
2239 <title>DBUS_COOKIE_SHA1</title>
2241 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
2242 has the ability to read a private file owned by the user being
2243 authenticated. If the client can prove that it has access to a secret
2244 cookie stored in this file, then the client is authenticated.
2245 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
2249 Throughout this description, "hex encoding" must output the digits
2250 from a to f in lower-case; the digits A to F must not be used
2251 in the DBUS_COOKIE_SHA1 mechanism.
2254 Authentication proceeds as follows:
2258 The client sends the username it would like to authenticate
2264 The server sends the name of its "cookie context" (see below); a
2265 space character; the integer ID of the secret cookie the client
2266 must demonstrate knowledge of; a space character; then a
2267 randomly-generated challenge string, all of this hex-encoded into
2273 The client locates the cookie and generates its own
2274 randomly-generated challenge string. The client then concatenates
2275 the server's decoded challenge, a ":" character, its own challenge,
2276 another ":" character, and the cookie. It computes the SHA-1 hash
2277 of this composite string as a hex digest. It concatenates the
2278 client's challenge string, a space character, and the SHA-1 hex
2279 digest, hex-encodes the result and sends it back to the server.
2284 The server generates the same concatenated string used by the
2285 client and computes its SHA-1 hash. It compares the hash with
2286 the hash received from the client; if the two hashes match, the
2287 client is authenticated.
2293 Each server has a "cookie context," which is a name that identifies a
2294 set of cookies that apply to that server. A sample context might be
2295 "org_freedesktop_session_bus". Context names must be valid ASCII,
2296 nonzero length, and may not contain the characters slash ("/"),
2297 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
2298 tab ("\t"), or period ("."). There is a default context,
2299 "org_freedesktop_general" that's used by servers that do not specify
2303 Cookies are stored in a user's home directory, in the directory
2304 <filename>~/.dbus-keyrings/</filename>. This directory must
2305 not be readable or writable by other users. If it is,
2306 clients and servers must ignore it. The directory
2307 contains cookie files named after the cookie context.
2310 A cookie file contains one cookie per line. Each line
2311 has three space-separated fields:
2315 The cookie ID number, which must be a non-negative integer and
2316 may not be used twice in the same file.
2321 The cookie's creation time, in UNIX seconds-since-the-epoch
2327 The cookie itself, a hex-encoded random block of bytes. The cookie
2328 may be of any length, though obviously security increases
2329 as the length increases.
2335 Only server processes modify the cookie file.
2336 They must do so with this procedure:
2340 Create a lockfile name by appending ".lock" to the name of the
2341 cookie file. The server should attempt to create this file
2342 using <literal>O_CREAT | O_EXCL</literal>. If file creation
2343 fails, the lock fails. Servers should retry for a reasonable
2344 period of time, then they may choose to delete an existing lock
2345 to keep users from having to manually delete a stale
2346 lock. <footnote><para>Lockfiles are used instead of real file
2347 locking <literal>fcntl()</literal> because real locking
2348 implementations are still flaky on network
2349 filesystems.</para></footnote>
2354 Once the lockfile has been created, the server loads the cookie
2355 file. It should then delete any cookies that are old (the
2356 timeout can be fairly short), or more than a reasonable
2357 time in the future (so that cookies never accidentally
2358 become permanent, if the clock was set far into the future
2359 at some point). If no recent keys remain, the
2360 server may generate a new key.
2365 The pruned and possibly added-to cookie file
2366 must be resaved atomically (using a temporary
2367 file which is rename()'d).
2372 The lock must be dropped by deleting the lockfile.
2378 Clients need not lock the file in order to load it,
2379 because servers are required to save the file atomically.
2384 <sect1 id="addresses">
2385 <title>Server Addresses</title>
2387 Server addresses consist of a transport name followed by a colon, and
2388 then an optional, comma-separated list of keys and values in the form key=value.
2389 Each value is escaped.
2393 <programlisting>unix:path=/tmp/dbus-test</programlisting>
2394 Which is the address to a unix socket with the path /tmp/dbus-test.
2397 Value escaping is similar to URI escaping but simpler.
2401 The set of optionally-escaped bytes is:
2402 <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
2403 <emphasis>byte</emphasis> (note, not character) which is not in the
2404 set of optionally-escaped bytes must be replaced with an ASCII
2405 percent (<literal>%</literal>) and the value of the byte in hex.
2406 The hex value must always be two digits, even if the first digit is
2407 zero. The optionally-escaped bytes may be escaped if desired.
2412 To unescape, append each byte in the value; if a byte is an ASCII
2413 percent (<literal>%</literal>) character then append the following
2414 hex value instead. It is an error if a <literal>%</literal> byte
2415 does not have two hex digits following. It is an error if a
2416 non-optionally-escaped byte is seen unescaped.
2420 The set of optionally-escaped bytes is intended to preserve address
2421 readability and convenience.
2425 A server may specify a key-value pair with the key <literal>guid</literal>
2426 and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
2427 describes the format of the <literal>guid</literal> field. If present,
2428 this UUID may be used to distinguish one server address from another. A
2429 server should use a different UUID for each address it listens on. For
2430 example, if a message bus daemon offers both UNIX domain socket and TCP
2431 connections, but treats clients the same regardless of how they connect,
2432 those two connections are equivalent post-connection but should have
2433 distinct UUIDs to distinguish the kinds of connection.
2437 The intent of the address UUID feature is to allow a client to avoid
2438 opening multiple identical connections to the same server, by allowing the
2439 client to check whether an address corresponds to an already-existing
2440 connection. Comparing two addresses is insufficient, because addresses
2441 can be recycled by distinct servers, and equivalent addresses may look
2442 different if simply compared as strings (for example, the host in a TCP
2443 address can be given as an IP address or as a hostname).
2447 Note that the address key is <literal>guid</literal> even though the
2448 rest of the API and documentation says "UUID," for historical reasons.
2452 [FIXME clarify if attempting to connect to each is a requirement
2453 or just a suggestion]
2454 When connecting to a server, multiple server addresses can be
2455 separated by a semi-colon. The library will then try to connect
2456 to the first address and if that fails, it'll try to connect to
2457 the next one specified, and so forth. For example
2458 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2463 <sect1 id="transports">
2464 <title>Transports</title>
2466 [FIXME we need to specify in detail each transport and its possible arguments]
2468 Current transports include: unix domain sockets (including
2469 abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport
2470 using in-process pipes. Future possible transports include one that
2471 tunnels over X11 protocol.
2474 <sect2 id="transports-unix-domain-sockets">
2475 <title>Unix Domain Sockets</title>
2477 Unix domain sockets can be either paths in the file system or on Linux
2478 kernels, they can be abstract which are similar to paths but
2479 do not show up in the file system.
2483 When a socket is opened by the D-Bus library it truncates the path
2484 name right before the first trailing Nul byte. This is true for both
2485 normal paths and abstract paths. Note that this is a departure from
2486 previous versions of D-Bus that would create sockets with a fixed
2487 length path name. Names which were shorter than the fixed length
2488 would be padded by Nul bytes.
2491 Unix domain sockets are not available on windows.
2493 <sect3 id="transports-unix-domain-sockets-addresses">
2494 <title>Server Address Format</title>
2496 Unix domain socket addresses are identified by the "unix:" prefix
2497 and support the following key/value pairs:
2504 <entry>Values</entry>
2505 <entry>Description</entry>
2511 <entry>(path)</entry>
2512 <entry>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</entry>
2515 <entry>tmpdir</entry>
2516 <entry>(path)</entry>
2517 <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>
2520 <entry>abstract</entry>
2521 <entry>(string)</entry>
2522 <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</entry>
2529 <sect2 id="transports-launchd">
2530 <title>launchd</title>
2532 launchd is a open-source server management system that replaces init, inetd
2533 and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
2534 bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
2538 launchd allocates a socket and provides it with the unix path through the
2539 DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
2540 spawned by launchd (or dbus-daemon, if it was started by launchd) can access
2541 it through its environment.
2542 Other processes can query for the launchd socket by executing:
2543 $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
2544 This is normally done by the D-Bus client library so doesn't have to be done
2548 launchd is not available on Microsoft Windows.
2550 <sect3 id="transports-launchd-addresses">
2551 <title>Server Address Format</title>
2553 launchd addresses are identified by the "launchd:" prefix
2554 and support the following key/value pairs:
2561 <entry>Values</entry>
2562 <entry>Description</entry>
2568 <entry>(environment variable)</entry>
2569 <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
2576 <sect2 id="transports-tcp-sockets">
2577 <title>TCP Sockets</title>
2579 The tcp transport provides TCP/IP based connections between clients
2580 located on the same or different hosts.
2583 Using tcp transport without any additional secure authentification mechanismus
2584 over a network is unsecure.
2587 Windows notes: Because of the tcp stack on windows does not provide sending
2588 credentials over a tcp connection, the EXTERNAL authentification
2589 mechanismus does not work.
2591 <sect3 id="transports-tcp-sockets-addresses">
2592 <title>Server Address Format</title>
2594 TCP/IP socket addresses are identified by the "tcp:" prefix
2595 and support the following key/value pairs:
2602 <entry>Values</entry>
2603 <entry>Description</entry>
2609 <entry>(string)</entry>
2610 <entry>dns name or ip address</entry>
2614 <entry>(number)</entry>
2615 <entry>The tcp port the server will open. A zero value let the server
2616 choose a free port provided from the underlaying operating system.
2617 libdbus is able to retrieve the real used port from the server.
2621 <entry>family</entry>
2622 <entry>(string)</entry>
2623 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
2630 <sect2 id="transports-nonce-tcp-sockets">
2631 <title>Nonce-secured TCP Sockets</title>
2633 The nonce-tcp transport provides a secured TCP transport, using a
2634 simple authentication mechanism to ensure that only clients with read
2635 access to a certain location in the filesystem can connect to the server.
2636 The server writes a secret, the nonce, to a file and an incoming client
2637 connection is only accepted if the client sends the nonce right after
2638 the connect. The nonce mechanism requires no setup and is orthogonal to
2639 the higher-level authentication mechanisms described in the
2640 Authentication section.
2644 On start, the server generates a random 16 byte nonce and writes it
2645 to a file in the user's temporary directory. The nonce file location
2646 is published as part of the server's D-Bus address using the
2647 "noncefile" key-value pair.
2649 After an accept, the server reads 16 bytes from the socket. If the
2650 read bytes do not match the nonce stored in the nonce file, the
2651 server MUST immediately drop the connection.
2652 If the nonce match the received byte sequence, the client is accepted
2653 and the transport behaves like an unsecured tcp transport.
2656 After a successful connect to the server socket, the client MUST read
2657 the nonce from the file published by the server via the noncefile=
2658 key-value pair and send it over the socket. After that, the
2659 transport behaves like an unsecured tcp transport.
2661 <sect3 id="transports-nonce-tcp-sockets-addresses">
2662 <title>Server Address Format</title>
2664 Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
2665 and support the following key/value pairs:
2672 <entry>Values</entry>
2673 <entry>Description</entry>
2679 <entry>(string)</entry>
2680 <entry>dns name or ip address</entry>
2684 <entry>(number)</entry>
2685 <entry>The tcp port the server will open. A zero value let the server
2686 choose a free port provided from the underlaying operating system.
2687 libdbus is able to retrieve the real used port from the server.
2691 <entry>family</entry>
2692 <entry>(string)</entry>
2693 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
2696 <entry>noncefile</entry>
2697 <entry>(path)</entry>
2698 <entry>file location containing the secret</entry>
2706 <sect1 id="meta-transports">
2707 <title>Meta Transports</title>
2709 Meta transports are a kind of transport with special enhancements or
2710 behavior. Currently available meta transports include: autolaunch
2713 <sect2 id="meta-transports-autolaunch">
2714 <title>Autolaunch</title>
2715 <para>The autolaunch transport provides a way for dbus clients to autodetect
2716 a running dbus session bus and to autolaunch a session bus if not present.
2718 <sect3 id="meta-transports-autolaunch-addresses">
2719 <title>Server Address Format</title>
2721 Autolaunch addresses uses the "autolaunch:" prefix and support the
2722 following key/value pairs:
2729 <entry>Values</entry>
2730 <entry>Description</entry>
2735 <entry>scope</entry>
2736 <entry>(string)</entry>
2737 <entry>scope of autolaunch (Windows only)
2741 "*install-path" - limit session bus to dbus installation path.
2742 The dbus installation path is determined from the location of
2743 the shared dbus library. If the library is located in a 'bin'
2744 subdirectory the installation root is the directory above,
2745 otherwise the directory where the library lives is taken as
2748 <install-root>/bin/[lib]dbus-1.dll
2749 <install-root>/[lib]dbus-1.dll
2755 "*user" - limit session bus to the recent user.
2760 other values - specify dedicated session bus like "release",
2772 <sect3 id="meta-transports-autolaunch-windows-implementation">
2773 <title>Windows implementation</title>
2775 On start, the server opens a platform specific transport, creates a mutex
2776 and a shared memory section containing the related session bus address.
2777 This mutex will be inspected by the dbus client library to detect a
2778 running dbus session bus. The access to the mutex and the shared memory
2779 section are protected by global locks.
2782 In the recent implementation the autolaunch transport uses a tcp transport
2783 on localhost with a port choosen from the operating system. This detail may
2784 change in the future.
2787 Disclaimer: The recent implementation is in an early state and may not
2788 work in all cirumstances and/or may have security issues. Because of this
2789 the implementation is not documentated yet.
2794 <sect1 id="naming-conventions">
2795 <title>Naming Conventions</title>
2798 D-Bus namespaces are all lowercase and correspond to reversed domain
2799 names, as with Java. e.g. "org.freedesktop"
2802 Interface, signal, method, and property names are "WindowsStyleCaps", note
2803 that the first letter is capitalized, unlike Java.
2806 Object paths are normally all lowercase with underscores used rather than
2812 <title>UUIDs</title>
2814 A working D-Bus implementation uses universally-unique IDs in two places.
2815 First, each server address has a UUID identifying the address,
2816 as described in <xref linkend="addresses"/>. Second, each operating
2817 system kernel instance running a D-Bus client or server has a UUID
2818 identifying that kernel, retrieved by invoking the method
2819 org.freedesktop.DBus.Peer.GetMachineId() (see <xref
2820 linkend="standard-interfaces-peer"/>).
2823 The term "UUID" in this document is intended literally, i.e. an
2824 identifier that is universally unique. It is not intended to refer to
2825 RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
2828 The UUID must contain 128 bits of data and be hex-encoded. The
2829 hex-encoded string may not contain hyphens or other non-hex-digit
2830 characters, and it must be exactly 32 characters long. To generate a
2831 UUID, the current reference implementation concatenates 96 bits of random
2832 data followed by the 32-bit time in seconds since the UNIX epoch (in big
2836 It would also be acceptable and probably better to simply generate 128
2837 bits of random data, as long as the random number generator is of high
2838 quality. The timestamp could conceivably help if the random bits are not
2839 very random. With a quality random number generator, collisions are
2840 extremely unlikely even with only 96 bits, so it's somewhat academic.
2843 Implementations should, however, stick to random data for the first 96 bits
2848 <sect1 id="standard-interfaces">
2849 <title>Standard Interfaces</title>
2851 See <xref linkend="message-protocol-types-notation"/> for details on
2852 the notation used in this section. There are some standard interfaces
2853 that may be useful across various D-Bus applications.
2855 <sect2 id="standard-interfaces-peer">
2856 <title><literal>org.freedesktop.DBus.Peer</literal></title>
2858 The <literal>org.freedesktop.DBus.Peer</literal> interface
2861 org.freedesktop.DBus.Peer.Ping ()
2862 org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
2866 On receipt of the <literal>METHOD_CALL</literal> message
2867 <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
2868 nothing other than reply with a <literal>METHOD_RETURN</literal> as
2869 usual. It does not matter which object path a ping is sent to. The
2870 reference implementation handles this method automatically.
2873 On receipt of the <literal>METHOD_CALL</literal> message
2874 <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
2875 reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
2876 UUID representing the identity of the machine the process is running on.
2877 This UUID must be the same for all processes on a single system at least
2878 until that system next reboots. It should be the same across reboots
2879 if possible, but this is not always possible to implement and is not
2881 It does not matter which object path a GetMachineId is sent to. The
2882 reference implementation handles this method automatically.
2885 The UUID is intended to be per-instance-of-the-operating-system, so may represent
2886 a virtual machine running on a hypervisor, rather than a physical machine.
2887 Basically if two processes see the same UUID, they should also see the same
2888 shared memory, UNIX domain sockets, process IDs, and other features that require
2889 a running OS kernel in common between the processes.
2892 The UUID is often used where other programs might use a hostname. Hostnames
2893 can change without rebooting, however, or just be "localhost" - so the UUID
2897 <xref linkend="uuids"/> explains the format of the UUID.
2901 <sect2 id="standard-interfaces-introspectable">
2902 <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
2904 This interface has one method:
2906 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
2910 Objects instances may implement
2911 <literal>Introspect</literal> which returns an XML description of
2912 the object, including its interfaces (with signals and methods), objects
2913 below it in the object path tree, and its properties.
2916 <xref linkend="introspection-format"/> describes the format of this XML string.
2919 <sect2 id="standard-interfaces-properties">
2920 <title><literal>org.freedesktop.DBus.Properties</literal></title>
2922 Many native APIs will have a concept of object <firstterm>properties</firstterm>
2923 or <firstterm>attributes</firstterm>. These can be exposed via the
2924 <literal>org.freedesktop.DBus.Properties</literal> interface.
2928 org.freedesktop.DBus.Properties.Get (in STRING interface_name,
2929 in STRING property_name,
2931 org.freedesktop.DBus.Properties.Set (in STRING interface_name,
2932 in STRING property_name,
2934 org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
2935 out DICT<STRING,VARIANT> props);
2939 The available properties and whether they are writable can be determined
2940 by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
2941 see <xref linkend="standard-interfaces-introspectable"/>.
2944 An empty string may be provided for the interface name; in this case,
2945 if there are multiple properties on an object with the same name,
2946 the results are undefined (picking one by according to an arbitrary
2947 deterministic rule, or returning an error, are the reasonable
2951 If one or more properties change on an object, the
2952 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
2953 signal may be emitted (this signal was added in 0.14):
2957 org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
2958 DICT<STRING,VARIANT> changed_properties,
2959 ARRAY<STRING> invalidated_properties);
2963 where <literal>changed_properties</literal> is a dictionary
2964 containing the changed properties with the new values and
2965 <literal>invalidated_properties</literal> is an array of
2966 properties that changed but the value is not conveyed.
2969 Whether the <literal>PropertiesChanged</literal> signal is
2970 supported can be determined by calling
2971 <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
2972 that the signal may be supported for an object but it may
2973 differ how whether and how it is used on a per-property basis
2974 (for e.g. performance or security reasons). Each property (or
2975 the parent interface) must be annotated with the
2976 <literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
2977 annotation to convey this (usually the default value
2978 <literal>true</literal> is sufficient meaning that the
2979 annotation does not need to be used). See <xref
2980 linkend="introspection-format"/> for details on this
2986 <sect1 id="introspection-format">
2987 <title>Introspection Data Format</title>
2989 As described in <xref linkend="standard-interfaces-introspectable"/>,
2990 objects may be introspected at runtime, returning an XML string
2991 that describes the object. The same XML format may be used in
2992 other contexts as well, for example as an "IDL" for generating
2993 static language bindings.
2996 Here is an example of introspection data:
2998 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
2999 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
3000 <node name="/org/freedesktop/sample_object">
3001 <interface name="org.freedesktop.SampleInterface">
3002 <method name="Frobate">
3003 <arg name="foo" type="i" direction="in"/>
3004 <arg name="bar" type="s" direction="out"/>
3005 <arg name="baz" type="a{us}" direction="out"/>
3006 <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
3008 <method name="Bazify">
3009 <arg name="bar" type="(iiu)" direction="in"/>
3010 <arg name="bar" type="v" direction="out"/>
3012 <method name="Mogrify">
3013 <arg name="bar" type="(iiav)" direction="in"/>
3015 <signal name="Changed">
3016 <arg name="new_value" type="b"/>
3018 <property name="Bar" type="y" access="readwrite"/>
3020 <node name="child_of_sample_object"/>
3021 <node name="another_child_of_sample_object"/>
3026 A more formal DTD and spec needs writing, but here are some quick notes.
3030 Only the root <node> element can omit the node name, as it's
3031 known to be the object that was introspected. If the root
3032 <node> does have a name attribute, it must be an absolute
3033 object path. If child <node> have object paths, they must be
3039 If a child <node> has any sub-elements, then they
3040 must represent a complete introspection of the child.
3041 If a child <node> is empty, then it may or may
3042 not have sub-elements; the child must be introspected
3043 in order to find out. The intent is that if an object
3044 knows that its children are "fast" to introspect
3045 it can go ahead and return their information, but
3046 otherwise it can omit it.
3051 The direction element on <arg> may be omitted,
3052 in which case it defaults to "in" for method calls
3053 and "out" for signals. Signals only allow "out"
3054 so while direction may be specified, it's pointless.
3059 The possible directions are "in" and "out",
3060 unlike CORBA there is no "inout"
3065 The possible property access flags are
3066 "readwrite", "read", and "write"
3071 Multiple interfaces can of course be listed for
3077 The "name" attribute on arguments is optional.
3083 Method, interface, property, and signal elements may have
3084 "annotations", which are generic key/value pairs of metadata.
3085 They are similar conceptually to Java's annotations and C# attributes.
3086 Well-known annotations:
3093 <entry>Values (separated by ,)</entry>
3094 <entry>Description</entry>
3099 <entry>org.freedesktop.DBus.Deprecated</entry>
3100 <entry>true,false</entry>
3101 <entry>Whether or not the entity is deprecated; defaults to false</entry>
3104 <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
3105 <entry>(string)</entry>
3106 <entry>The C symbol; may be used for methods and interfaces</entry>
3109 <entry>org.freedesktop.DBus.Method.NoReply</entry>
3110 <entry>true,false</entry>
3111 <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
3114 <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
3115 <entry>true,invalidates,false</entry>
3118 If set to <literal>false</literal>, the
3119 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3121 linkend="standard-interfaces-properties"/> is not
3122 guaranteed to be emitted if the property changes.
3125 If set to <literal>invalidates</literal> the signal
3126 is emitted but the value is not included in the
3130 If set to <literal>true</literal> the signal is
3131 emitted with the value included.
3134 The value for the annotation defaults to
3135 <literal>true</literal> if the enclosing interface
3136 element does not specify the annotation. Otherwise it
3137 defaults to the value specified in the enclosing
3146 <sect1 id="message-bus">
3147 <title>Message Bus Specification</title>
3148 <sect2 id="message-bus-overview">
3149 <title>Message Bus Overview</title>
3151 The message bus accepts connections from one or more applications.
3152 Once connected, applications can exchange messages with other
3153 applications that are also connected to the bus.
3156 In order to route messages among connections, the message bus keeps a
3157 mapping from names to connections. Each connection has one
3158 unique-for-the-lifetime-of-the-bus name automatically assigned.
3159 Applications may request additional names for a connection. Additional
3160 names are usually "well-known names" such as
3161 "org.freedesktop.TextEditor". When a name is bound to a connection,
3162 that connection is said to <firstterm>own</firstterm> the name.
3165 The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
3166 This name routes messages to the bus, allowing applications to make
3167 administrative requests. For example, applications can ask the bus
3168 to assign a name to a connection.
3171 Each name may have <firstterm>queued owners</firstterm>. When an
3172 application requests a name for a connection and the name is already in
3173 use, the bus will optionally add the connection to a queue waiting for
3174 the name. If the current owner of the name disconnects or releases
3175 the name, the next connection in the queue will become the new owner.
3179 This feature causes the right thing to happen if you start two text
3180 editors for example; the first one may request "org.freedesktop.TextEditor",
3181 and the second will be queued as a possible owner of that name. When
3182 the first exits, the second will take over.
3186 Messages may have a <literal>DESTINATION</literal> field (see <xref
3187 linkend="message-protocol-header-fields"/>). If the
3188 <literal>DESTINATION</literal> field is present, it specifies a message
3189 recipient by name. Method calls and replies normally specify this field.
3190 The message bus must send messages (of any type) with the
3191 <literal>DESTINATION</literal> field set to the specified recipient,
3192 regardless of whether the recipient has set up a match rule matching
3197 Signals normally do not specify a destination; they are sent to all
3198 applications with <firstterm>message matching rules</firstterm> that
3203 When the message bus receives a method call, if the
3204 <literal>DESTINATION</literal> field is absent, the call is taken to be
3205 a standard one-to-one message and interpreted by the message bus
3206 itself. For example, sending an
3207 <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
3208 <literal>DESTINATION</literal> will cause the message bus itself to
3209 reply to the ping immediately; the message bus will not make this
3210 message visible to other applications.
3214 Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
3215 the ping message were sent with a <literal>DESTINATION</literal> name of
3216 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
3217 forwarded, and the Yoyodyne Corporation screensaver application would be
3218 expected to reply to the ping.
3222 <sect2 id="message-bus-names">
3223 <title>Message Bus Names</title>
3225 Each connection has at least one name, assigned at connection time and
3226 returned in response to the
3227 <literal>org.freedesktop.DBus.Hello</literal> method call. This
3228 automatically-assigned name is called the connection's <firstterm>unique
3229 name</firstterm>. Unique names are never reused for two different
3230 connections to the same bus.
3233 Ownership of a unique name is a prerequisite for interaction with
3234 the message bus. It logically follows that the unique name is always
3235 the first name that an application comes to own, and the last
3236 one that it loses ownership of.
3239 Unique connection names must begin with the character ':' (ASCII colon
3240 character); bus names that are not unique names must not begin
3241 with this character. (The bus must reject any attempt by an application
3242 to manually request a name beginning with ':'.) This restriction
3243 categorically prevents "spoofing"; messages sent to a unique name
3244 will always go to the expected connection.
3247 When a connection is closed, all the names that it owns are deleted (or
3248 transferred to the next connection in the queue if any).
3251 A connection can request additional names to be associated with it using
3252 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
3253 linkend="message-protocol-names-bus"/> describes the format of a valid
3254 name. These names can be released again using the
3255 <literal>org.freedesktop.DBus.ReleaseName</literal> message.
3258 <sect3 id="bus-messages-request-name">
3259 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
3263 UINT32 RequestName (in STRING name, in UINT32 flags)
3270 <entry>Argument</entry>
3272 <entry>Description</entry>
3278 <entry>STRING</entry>
3279 <entry>Name to request</entry>
3283 <entry>UINT32</entry>
3284 <entry>Flags</entry>
3294 <entry>Argument</entry>
3296 <entry>Description</entry>
3302 <entry>UINT32</entry>
3303 <entry>Return value</entry>
3310 This method call should be sent to
3311 <literal>org.freedesktop.DBus</literal> and asks the message bus to
3312 assign the given name to the method caller. Each name maintains a
3313 queue of possible owners, where the head of the queue is the primary
3314 or current owner of the name. Each potential owner in the queue
3315 maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
3316 DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
3317 call. When RequestName is invoked the following occurs:
3321 If the method caller is currently the primary owner of the name,
3322 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
3323 values are updated with the values from the new RequestName call,
3324 and nothing further happens.
3330 If the current primary owner (head of the queue) has
3331 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
3332 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
3333 the caller of RequestName replaces the current primary owner at
3334 the head of the queue and the current primary owner moves to the
3335 second position in the queue. If the caller of RequestName was
3336 in the queue previously its flags are updated with the values from
3337 the new RequestName in addition to moving it to the head of the queue.
3343 If replacement is not possible, and the method caller is
3344 currently in the queue but not the primary owner, its flags are
3345 updated with the values from the new RequestName call.
3351 If replacement is not possible, and the method caller is
3352 currently not in the queue, the method caller is appended to the
3359 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
3360 set and is not the primary owner, it is removed from the
3361 queue. This can apply to the previous primary owner (if it
3362 was replaced) or the method caller (if it updated the
3363 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
3364 queue, or if it was just added to the queue with that flag set).
3370 Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
3371 queue," even if another application already in the queue had specified
3372 DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
3373 that does not allow replacement goes away, and the next primary owner
3374 does allow replacement. In this case, queued items that specified
3375 DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
3376 automatically replace the new primary owner. In other words,
3377 DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
3378 time RequestName is called. This is deliberate to avoid an infinite loop
3379 anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
3380 and DBUS_NAME_FLAG_REPLACE_EXISTING.
3383 The flags argument contains any of the following values logically ORed
3390 <entry>Conventional Name</entry>
3391 <entry>Value</entry>
3392 <entry>Description</entry>
3397 <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
3401 If an application A specifies this flag and succeeds in
3402 becoming the owner of the name, and another application B
3403 later calls RequestName with the
3404 DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
3405 will lose ownership and receive a
3406 <literal>org.freedesktop.DBus.NameLost</literal> signal, and
3407 application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
3408 is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
3409 is not specified by application B, then application B will not replace
3410 application A as the owner.
3415 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
3419 Try to replace the current owner if there is one. If this
3420 flag is not set the application will only become the owner of
3421 the name if there is no current owner. If this flag is set,
3422 the application will replace the current owner if
3423 the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
3428 <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
3432 Without this flag, if an application requests a name that is
3433 already owned, the application will be placed in a queue to
3434 own the name when the current owner gives it up. If this
3435 flag is given, the application will not be placed in the
3436 queue, the request for the name will simply fail. This flag
3437 also affects behavior when an application is replaced as
3438 name owner; by default the application moves back into the
3439 waiting queue, unless this flag was provided when the application
3440 became the name owner.
3448 The return code can be one of the following values:
3454 <entry>Conventional Name</entry>
3455 <entry>Value</entry>
3456 <entry>Description</entry>
3461 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
3462 <entry>1</entry> <entry>The caller is now the primary owner of
3463 the name, replacing any previous owner. Either the name had no
3464 owner before, or the caller specified
3465 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
3466 DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
3469 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
3472 <entry>The name already had an owner,
3473 DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
3474 the current owner did not specify
3475 DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
3476 application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
3480 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
3481 <entry>The name already has an owner,
3482 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
3483 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
3484 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
3485 specified by the requesting application.</entry>
3488 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
3490 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
3498 <sect3 id="bus-messages-release-name">
3499 <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
3503 UINT32 ReleaseName (in STRING name)
3510 <entry>Argument</entry>
3512 <entry>Description</entry>
3518 <entry>STRING</entry>
3519 <entry>Name to release</entry>
3529 <entry>Argument</entry>
3531 <entry>Description</entry>
3537 <entry>UINT32</entry>
3538 <entry>Return value</entry>
3545 This method call should be sent to
3546 <literal>org.freedesktop.DBus</literal> and asks the message bus to
3547 release the method caller's claim to the given name. If the caller is
3548 the primary owner, a new primary owner will be selected from the
3549 queue if any other owners are waiting. If the caller is waiting in
3550 the queue for the name, the caller will removed from the queue and
3551 will not be made an owner of the name if it later becomes available.
3552 If there are no other owners in the queue for the name, it will be
3553 removed from the bus entirely.
3555 The return code can be one of the following values:
3561 <entry>Conventional Name</entry>
3562 <entry>Value</entry>
3563 <entry>Description</entry>
3568 <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
3569 <entry>1</entry> <entry>The caller has released his claim on
3570 the given name. Either the caller was the primary owner of
3571 the name, and the name is now unused or taken by somebody
3572 waiting in the queue for the name, or the caller was waiting
3573 in the queue for the name and has now been removed from the
3577 <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
3579 <entry>The given name does not exist on this bus.</entry>
3582 <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
3584 <entry>The caller was not the primary owner of this name,
3585 and was also not waiting in the queue to own this name.</entry>
3593 <sect3 id="bus-messages-list-queued-owners">
3594 <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
3598 ARRAY of STRING ListQueuedOwners (in STRING name)
3605 <entry>Argument</entry>
3607 <entry>Description</entry>
3613 <entry>STRING</entry>
3614 <entry>The well-known bus name to query, such as
3615 <literal>com.example.cappuccino</literal></entry>
3625 <entry>Argument</entry>
3627 <entry>Description</entry>
3633 <entry>ARRAY of STRING</entry>
3634 <entry>The unique bus names of connections currently queued
3635 for the name</entry>
3642 This method call should be sent to
3643 <literal>org.freedesktop.DBus</literal> and lists the connections
3644 currently queued for a bus name (see
3645 <xref linkend="term-queued-owner"/>).
3650 <sect2 id="message-bus-routing">
3651 <title>Message Bus Message Routing</title>
3655 <sect3 id="message-bus-routing-match-rules">
3656 <title>Match Rules</title>
3658 An important part of the message bus routing protocol is match
3659 rules. Match rules describe what messages can be sent to a client
3660 based on the contents of the message. When a message is routed
3661 through the bus it is compared to clients' match rules. If any
3662 of the rules match, the message is dispatched to the client.
3663 If none of the rules match the message never leaves the bus. This
3664 is an effective way to control traffic over the bus and to make sure
3665 only relevant message need to be processed by the client.
3668 Match rules are added using the AddMatch bus method
3669 (see <xref linkend="bus-messages-add-match"/>). Rules are
3670 specified as a string of comma separated key/value pairs.
3671 Excluding a key from the rule indicates a wildcard match.
3672 For instance excluding the the member from a match rule but
3673 adding a sender would let all messages from that sender through.
3674 An example of a complete rule would be
3675 "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
3678 The following table describes the keys that can be used to create
3680 The following table summarizes the D-Bus types.
3686 <entry>Possible Values</entry>
3687 <entry>Description</entry>
3692 <entry><literal>type</literal></entry>
3693 <entry>'signal', 'method_call', 'method_return', 'error'</entry>
3694 <entry>Match on the message type. An example of a type match is type='signal'</entry>
3697 <entry><literal>sender</literal></entry>
3698 <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
3699 and <xref linkend="term-unique-name"/> respectively)
3701 <entry>Match messages sent by a particular sender. An example of a sender match
3702 is sender='org.freedesktop.Hal'</entry>
3705 <entry><literal>interface</literal></entry>
3706 <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
3707 <entry>Match messages sent over or to a particular interface. An example of an
3708 interface match is interface='org.freedesktop.Hal.Manager'.
3709 If a message omits the interface header, it must not match any rule
3710 that specifies this key.</entry>
3713 <entry><literal>member</literal></entry>
3714 <entry>Any valid method or signal name</entry>
3715 <entry>Matches messages which have the give method or signal name. An example of
3716 a member match is member='NameOwnerChanged'</entry>
3719 <entry><literal>path</literal></entry>
3720 <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
3721 <entry>Matches messages which are sent from or to the given object. An example of a
3722 path match is path='/org/freedesktop/Hal/Manager'</entry>
3725 <entry><literal>path_prefix</literal></entry>
3726 <entry>An object path optionally ending in a slash</entry>
3729 Matches messages which are sent from or to an
3730 object for which the object path is a descendant of
3731 the given value. If the prefix ends with a slash, it
3732 matches all paths starting with that string;
3733 if it does not end with a slash, it matches either
3734 that exact path, or that path followed by one or
3735 more path components.
3740 <literal>path_prefix='/com/example/foo'</literal>
3741 would match signals sent by
3742 <literal>/com/example/foo</literal>
3744 <literal>/com/example/foo/bar</literal>,
3746 <literal>/com/example/foobar</literal>.
3751 <literal>path_prefix='/com/example/foo/'</literal>
3752 would still match signals sent by
3753 <literal>/com/example/foo/bar</literal>,
3754 but would not match signals sent by
3755 <literal>/com/example/foo</literal> or
3756 <literal>/com/example/foobar</literal>.
3760 This match key was added in version 0.16 of the
3761 D-Bus specification and implemented by the bus
3762 daemon in dbus 1.5.0 and later.
3768 <entry><literal>destination</literal></entry>
3769 <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
3770 <entry>Matches messages which are being sent to the given unique name. An
3771 example of a destination match is destination=':1.0'</entry>
3774 <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
3775 <entry>Any string</entry>
3776 <entry>Arg matches are special and are used for further restricting the
3777 match based on the arguments in the body of a message. Only arguments of type
3778 STRING can be matched in this way. An example of an argument match
3779 would be arg3='Foo'. Only argument indexes from 0 to 63 should be
3783 <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
3784 <entry>Any string</entry>
3786 <para>Argument path matches provide a specialised form of wildcard matching for
3787 path-like namespaces. They can match arguments whose type is either STRING or
3788 OBJECT_PATH. As with normal argument matches,
3789 if the argument is exactly equal to the string given in the match
3790 rule then the rule is satisfied. Additionally, there is also a
3791 match when either the string given in the match rule or the
3792 appropriate message argument ends with '/' and is a prefix of the
3793 other. An example argument path match is arg0path='/aa/bb/'. This
3794 would match messages with first arguments of '/', '/aa/',
3795 '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
3796 messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
3798 <para>This is intended for monitoring “directories” in file system-like
3799 hierarchies, as used in the <citetitle>dconf</citetitle> configuration
3800 system. An application interested in all nodes in a particular hierarchy would
3801 monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
3802 emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
3803 represent a modification to the “bar” property, or a signal with zeroth
3804 argument <literal>"/ca/example/"</literal> to represent atomic modification of
3805 many properties within that directory, and the interested application would be
3806 notified in both cases.</para>
3809 This match key was added in version 0.12 of the
3810 D-Bus specification, implemented for STRING
3811 arguments by the bus daemon in dbus 1.2.0 and later,
3812 and implemented for OBJECT_PATH arguments in dbus 1.5.0
3819 <entry><literal>arg0namespace</literal></entry>
3820 <entry>Like a bus name, except that the string is not
3821 required to contain a '.' (period)</entry>
3823 <para>Match messages whose first argument is of type STRING, and is a bus name
3824 or interface name within the specified namespace. This is primarily intended
3825 for watching name owner changes for a group of related bus names, rather than
3826 for a single name or all name changes.</para>
3828 <para>Because every valid interface name is also a valid
3829 bus name, this can also be used for messages whose
3830 first argument is an interface name.</para>
3832 <para>If the value has a trailing period, then only bus names or interface names
3833 within that namespace are matched. If it has no trailing period, an exact
3834 match is also allowed.</para>
3836 <para>For example, the match rule
3837 <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
3838 matches name owner changes for bus names such as
3839 <literal>com.example.backend.foo</literal>,
3840 <literal>com.example.backend.foo.bar</literal>, and
3841 <literal>com.example.backend</literal> itself.</para>
3843 <para>On the other hand, the match rule
3844 <literal>member='NameOwnerChanged',arg0namespace='com.example.backend.'</literal>
3845 (with a trailing period in the namespace) matches owner changes for
3846 <literal>com.example.backend.foo</literal> and
3847 <literal>com.example.backend.foo.bar</literal>, but not for
3848 <literal>com.example.backend</literal>.
3851 <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
3860 <sect2 id="message-bus-starting-services">
3861 <title>Message Bus Starting Services</title>
3863 The message bus can start applications on behalf of other applications.
3864 In CORBA terms, this would be called <firstterm>activation</firstterm>.
3865 An application that can be started in this way is called a
3866 <firstterm>service</firstterm>.
3869 With D-Bus, starting a service is normally done by name. That is,
3870 applications ask the message bus to start some program that will own a
3871 well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
3872 This implies a contract documented along with the name
3873 <literal>org.freedesktop.TextEditor</literal> for which objects
3874 the owner of that name will provide, and what interfaces those
3878 To find an executable corresponding to a particular name, the bus daemon
3879 looks for <firstterm>service description files</firstterm>. Service
3880 description files define a mapping from names to executables. Different
3881 kinds of message bus will look for these files in different places, see
3882 <xref linkend="message-bus-types"/>.
3885 [FIXME the file format should be much better specified than "similar to
3886 .desktop entries" esp. since desktop entries are already
3887 badly-specified. ;-)] Service description files have the ".service" file
3888 extension. The message bus will only load service description files
3889 ending with .service; all other files will be ignored. The file format
3890 is similar to that of <ulink
3891 url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
3892 entries</ulink>. All service description files must be in UTF-8
3893 encoding. To ensure that there will be no name collisions, service files
3894 must be namespaced using the same mechanism as messages and service
3898 <title>Example service description file</title>
3900 # Sample service description file
3902 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
3903 Exec=/usr/libexec/gconfd-2
3908 When an application asks to start a service by name, the bus daemon tries to
3909 find a service that will own that name. It then tries to spawn the
3910 executable associated with it. If this fails, it will report an
3911 error. [FIXME what happens if two .service files offer the same service;
3912 what kind of error is reported, should we have a way for the client to
3916 The executable launched will have the environment variable
3917 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
3918 message bus so it can connect and request the appropriate names.
3921 The executable being launched may want to know whether the message bus
3922 starting it is one of the well-known message buses (see <xref
3923 linkend="message-bus-types"/>). To facilitate this, the bus must also set
3924 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
3925 of the well-known buses. The currently-defined values for this variable
3926 are <literal>system</literal> for the systemwide message bus,
3927 and <literal>session</literal> for the per-login-session message
3928 bus. The new executable must still connect to the address given
3929 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
3930 resulting connection is to the well-known bus.
3933 [FIXME there should be a timeout somewhere, either specified
3934 in the .service file, by the client, or just a global value
3935 and if the client being activated fails to connect within that
3936 timeout, an error should be sent back.]
3939 <sect3 id="message-bus-starting-services-scope">
3940 <title>Message Bus Service Scope</title>
3942 The "scope" of a service is its "per-", such as per-session,
3943 per-machine, per-home-directory, or per-display. The reference
3944 implementation doesn't yet support starting services in a different
3945 scope from the message bus itself. So e.g. if you start a service
3946 on the session bus its scope is per-session.
3949 We could add an optional scope to a bus name. For example, for
3950 per-(display,session pair), we could have a unique ID for each display
3951 generated automatically at login and set on screen 0 by executing a
3952 special "set display ID" binary. The ID would be stored in a
3953 <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
3954 random bytes. This ID would then be used to scope names.
3955 Starting/locating a service could be done by ID-name pair rather than
3959 Contrast this with a per-display scope. To achieve that, we would
3960 want a single bus spanning all sessions using a given display.
3961 So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
3962 property on screen 0 of the display, pointing to this bus.
3967 <sect2 id="message-bus-types">
3968 <title>Well-known Message Bus Instances</title>
3970 Two standard message bus instances are defined here, along with how
3971 to locate them and where their service files live.
3973 <sect3 id="message-bus-types-login">
3974 <title>Login session message bus</title>
3976 Each time a user logs in, a <firstterm>login session message
3977 bus</firstterm> may be started. All applications in the user's login
3978 session may interact with one another using this message bus.
3981 The address of the login session message bus is given
3982 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
3983 variable. If that variable is not set, applications may
3984 also try to read the address from the X Window System root
3985 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
3986 The root window property must have type <literal>STRING</literal>.
3987 The environment variable should have precedence over the
3988 root window property.
3990 <para>The address of the login session message bus is given in the
3991 <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment variable. If
3992 DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string
3993 "autolaunch:", the system should use platform-specific methods of
3994 locating a running D-Bus session server, or starting one if a running
3995 instance cannot be found. Note that this mechanism is not recommended
3996 for attempting to determine if a daemon is running. It is inherently
3997 racy to attempt to make this determination, since the bus daemon may
3998 be started just before or just after the determination is made.
3999 Therefore, it is recommended that applications do not try to make this
4000 determination for their functionality purposes, and instead they
4001 should attempt to start the server.</para>
4003 <sect4 id="message-bus-types-login-x-windows">
4004 <title>X Windowing System</title>
4006 For the X Windowing System, the application must locate the
4007 window owner of the selection represented by the atom formed by
4011 <para>the literal string "_DBUS_SESSION_BUS_SELECTION_"</para>
4015 <para>the current user's username</para>
4019 <para>the literal character '_' (underscore)</para>
4023 <para>the machine's ID</para>
4029 The following properties are defined for the window that owns
4031 <informaltable frame="all">
4040 <para>meaning</para>
4046 <para>_DBUS_SESSION_BUS_ADDRESS</para>
4050 <para>the actual address of the server socket</para>
4056 <para>_DBUS_SESSION_BUS_PID</para>
4060 <para>the PID of the server process</para>
4069 At least the _DBUS_SESSION_BUS_ADDRESS property MUST be
4070 present in this window.
4074 If the X selection cannot be located or if reading the
4075 properties from the window fails, the implementation MUST conclude
4076 that there is no D-Bus server running and proceed to start a new
4077 server. (See below on concurrency issues)
4081 Failure to connect to the D-Bus server address thus obtained
4082 MUST be treated as a fatal connection error and should be reported
4087 As an alternative, an implementation MAY find the information
4088 in the following file located in the current user's home directory,
4089 in subdirectory .dbus/session-bus/:
4092 <para>the machine's ID</para>
4096 <para>the literal character '-' (dash)</para>
4100 <para>the X display without the screen number, with the
4101 following prefixes removed, if present: ":", "localhost:"
4102 ."localhost.localdomain:". That is, a display of
4103 "localhost:10.0" produces just the number "10"</para>
4109 The contents of this file NAME=value assignment pairs and
4110 lines starting with # are comments (no comments are allowed
4111 otherwise). The following variable names are defined:
4118 <para>Variable</para>
4122 <para>meaning</para>
4128 <para>DBUS_SESSION_BUS_ADDRESS</para>
4132 <para>the actual address of the server socket</para>
4138 <para>DBUS_SESSION_BUS_PID</para>
4142 <para>the PID of the server process</para>
4148 <para>DBUS_SESSION_BUS_WINDOWID</para>
4152 <para>the window ID</para>
4161 At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
4166 Failure to open this file MUST be interpreted as absence of a
4167 running server. Therefore, the implementation MUST proceed to
4168 attempting to launch a new bus server if the file cannot be
4173 However, success in opening this file MUST NOT lead to the
4174 conclusion that the server is running. Thus, a failure to connect to
4175 the bus address obtained by the alternative method MUST NOT be
4176 considered a fatal error. If the connection cannot be established,
4177 the implementation MUST proceed to check the X selection settings or
4178 to start the server on its own.
4182 If the implementation concludes that the D-Bus server is not
4183 running it MUST attempt to start a new server and it MUST also
4184 ensure that the daemon started as an effect of the "autolaunch"
4185 mechanism provides the lookup mechanisms described above, so
4186 subsequent calls can locate the newly started server. The
4187 implementation MUST also ensure that if two or more concurrent
4188 initiations happen, only one server remains running and all other
4189 initiations are able to obtain the address of this server and
4190 connect to it. In other words, the implementation MUST ensure that
4191 the X selection is not present when it attempts to set it, without
4192 allowing another process to set the selection between the
4193 verification and the setting (e.g., by using XGrabServer /
4200 [FIXME specify location of .service files, probably using
4201 DESKTOP_DIRS etc. from basedir specification, though login session
4202 bus is not really desktop-specific]
4206 <sect3 id="message-bus-types-system">
4207 <title>System message bus</title>
4209 A computer may have a <firstterm>system message bus</firstterm>,
4210 accessible to all applications on the system. This message bus may be
4211 used to broadcast system events, such as adding new hardware devices,
4212 changes in the printer queue, and so forth.
4215 The address of the system message bus is given
4216 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
4217 variable. If that variable is not set, applications should try
4218 to connect to the well-known address
4219 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
4222 The D-Bus reference implementation actually honors the
4223 <literal>$(localstatedir)</literal> configure option
4224 for this address, on both client and server side.
4229 [FIXME specify location of system bus .service files]
4234 <sect2 id="message-bus-messages">
4235 <title>Message Bus Messages</title>
4237 The special message bus name <literal>org.freedesktop.DBus</literal>
4238 responds to a number of additional messages.
4241 <sect3 id="bus-messages-hello">
4242 <title><literal>org.freedesktop.DBus.Hello</literal></title>
4253 <entry>Argument</entry>
4255 <entry>Description</entry>
4261 <entry>STRING</entry>
4262 <entry>Unique name assigned to the connection</entry>
4269 Before an application is able to send messages to other applications
4270 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
4271 to the message bus to obtain a unique name. If an application without
4272 a unique name tries to send a message to another application, or a
4273 message to the message bus itself that isn't the
4274 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
4275 disconnected from the bus.
4278 There is no corresponding "disconnect" request; if a client wishes to
4279 disconnect from the bus, it simply closes the socket (or other
4280 communication channel).
4283 <sect3 id="bus-messages-list-names">
4284 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
4288 ARRAY of STRING ListNames ()
4295 <entry>Argument</entry>
4297 <entry>Description</entry>
4303 <entry>ARRAY of STRING</entry>
4304 <entry>Array of strings where each string is a bus name</entry>
4311 Returns a list of all currently-owned names on the bus.
4314 <sect3 id="bus-messages-list-activatable-names">
4315 <title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
4319 ARRAY of STRING ListActivatableNames ()
4326 <entry>Argument</entry>
4328 <entry>Description</entry>
4334 <entry>ARRAY of STRING</entry>
4335 <entry>Array of strings where each string is a bus name</entry>
4342 Returns a list of all names that can be activated on the bus.
4345 <sect3 id="bus-messages-name-exists">
4346 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
4350 BOOLEAN NameHasOwner (in STRING name)
4357 <entry>Argument</entry>
4359 <entry>Description</entry>
4365 <entry>STRING</entry>
4366 <entry>Name to check</entry>
4376 <entry>Argument</entry>
4378 <entry>Description</entry>
4384 <entry>BOOLEAN</entry>
4385 <entry>Return value, true if the name exists</entry>
4392 Checks if the specified name exists (currently has an owner).
4396 <sect3 id="bus-messages-name-owner-changed">
4397 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
4401 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
4408 <entry>Argument</entry>
4410 <entry>Description</entry>
4416 <entry>STRING</entry>
4417 <entry>Name with a new owner</entry>
4421 <entry>STRING</entry>
4422 <entry>Old owner or empty string if none</entry>
4426 <entry>STRING</entry>
4427 <entry>New owner or empty string if none</entry>
4434 This signal indicates that the owner of a name has changed.
4435 It's also the signal to use to detect the appearance of
4436 new names on the bus.
4439 <sect3 id="bus-messages-name-lost">
4440 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
4444 NameLost (STRING name)
4451 <entry>Argument</entry>
4453 <entry>Description</entry>
4459 <entry>STRING</entry>
4460 <entry>Name which was lost</entry>
4467 This signal is sent to a specific application when it loses
4468 ownership of a name.
4472 <sect3 id="bus-messages-name-acquired">
4473 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
4477 NameAcquired (STRING name)
4484 <entry>Argument</entry>
4486 <entry>Description</entry>
4492 <entry>STRING</entry>
4493 <entry>Name which was acquired</entry>
4500 This signal is sent to a specific application when it gains
4501 ownership of a name.
4505 <sect3 id="bus-messages-start-service-by-name">
4506 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
4510 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
4517 <entry>Argument</entry>
4519 <entry>Description</entry>
4525 <entry>STRING</entry>
4526 <entry>Name of the service to start</entry>
4530 <entry>UINT32</entry>
4531 <entry>Flags (currently not used)</entry>
4541 <entry>Argument</entry>
4543 <entry>Description</entry>
4549 <entry>UINT32</entry>
4550 <entry>Return value</entry>
4555 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
4559 The return value can be one of the following values:
4564 <entry>Identifier</entry>
4565 <entry>Value</entry>
4566 <entry>Description</entry>
4571 <entry>DBUS_START_REPLY_SUCCESS</entry>
4573 <entry>The service was successfully started.</entry>
4576 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
4578 <entry>A connection already owns the given name.</entry>
4587 <sect3 id="bus-messages-update-activation-environment">
4588 <title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
4592 UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment)
4599 <entry>Argument</entry>
4601 <entry>Description</entry>
4607 <entry>ARRAY of DICT<STRING,STRING></entry>
4608 <entry>Environment to add or update</entry>
4613 Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services.
4616 Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.
4619 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.
4624 <sect3 id="bus-messages-get-name-owner">
4625 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
4629 STRING GetNameOwner (in STRING name)
4636 <entry>Argument</entry>
4638 <entry>Description</entry>
4644 <entry>STRING</entry>
4645 <entry>Name to get the owner of</entry>
4655 <entry>Argument</entry>
4657 <entry>Description</entry>
4663 <entry>STRING</entry>
4664 <entry>Return value, a unique connection name</entry>
4669 Returns the unique connection name of the primary owner of the name
4670 given. If the requested name doesn't have an owner, returns a
4671 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
4675 <sect3 id="bus-messages-get-connection-unix-user">
4676 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
4680 UINT32 GetConnectionUnixUser (in STRING bus_name)
4687 <entry>Argument</entry>
4689 <entry>Description</entry>
4695 <entry>STRING</entry>
4696 <entry>Unique or well-known bus name of the connection to
4697 query, such as <literal>:12.34</literal> or
4698 <literal>com.example.tea</literal></entry>
4708 <entry>Argument</entry>
4710 <entry>Description</entry>
4716 <entry>UINT32</entry>
4717 <entry>Unix user ID</entry>
4722 Returns the Unix user ID of the process connected to the server. If
4723 unable to determine it (for instance, because the process is not on the
4724 same machine as the bus daemon), an error is returned.
4728 <sect3 id="bus-messages-get-connection-unix-process-id">
4729 <title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
4733 UINT32 GetConnectionUnixProcessID (in STRING bus_name)
4740 <entry>Argument</entry>
4742 <entry>Description</entry>
4748 <entry>STRING</entry>
4749 <entry>Unique or well-known bus name of the connection to
4750 query, such as <literal>:12.34</literal> or
4751 <literal>com.example.tea</literal></entry>
4761 <entry>Argument</entry>
4763 <entry>Description</entry>
4769 <entry>UINT32</entry>
4770 <entry>Unix process id</entry>
4775 Returns the Unix process ID of the process connected to the server. If
4776 unable to determine it (for instance, because the process is not on the
4777 same machine as the bus daemon), an error is returned.
4781 <sect3 id="bus-messages-add-match">
4782 <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
4786 AddMatch (in STRING rule)
4793 <entry>Argument</entry>
4795 <entry>Description</entry>
4801 <entry>STRING</entry>
4802 <entry>Match rule to add to the connection</entry>
4807 Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
4808 If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
4812 <sect3 id="bus-messages-remove-match">
4813 <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
4817 RemoveMatch (in STRING rule)
4824 <entry>Argument</entry>
4826 <entry>Description</entry>
4832 <entry>STRING</entry>
4833 <entry>Match rule to remove from the connection</entry>
4838 Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
4839 If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
4844 <sect3 id="bus-messages-get-id">
4845 <title><literal>org.freedesktop.DBus.GetId</literal></title>
4849 GetId (out STRING id)
4856 <entry>Argument</entry>
4858 <entry>Description</entry>
4864 <entry>STRING</entry>
4865 <entry>Unique ID identifying the bus daemon</entry>
4870 Gets the unique ID of the bus. The unique ID here is shared among all addresses the
4871 bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
4872 <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
4873 ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
4874 There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
4875 by org.freedesktop.DBus.Peer.GetMachineId().
4876 For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
4884 <appendix id="implementation-notes">
4885 <title>Implementation notes</title>
4886 <sect1 id="implementation-notes-subsection">
4894 <glossary><title>Glossary</title>
4896 This glossary defines some of the terms used in this specification.
4899 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
4902 The message bus maintains an association between names and
4903 connections. (Normally, there's one connection per application.) A
4904 bus name is simply an identifier used to locate connections. For
4905 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
4906 name might be used to send a message to a screensaver from Yoyodyne
4907 Corporation. An application is said to <firstterm>own</firstterm> a
4908 name if the message bus has associated the application's connection
4909 with the name. Names may also have <firstterm>queued
4910 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
4911 The bus assigns a unique name to each connection,
4912 see <xref linkend="term-unique-name"/>. Other names
4913 can be thought of as "well-known names" and are
4914 used to find applications that offer specific functionality.
4919 <glossentry id="term-message"><glossterm>Message</glossterm>
4922 A message is the atomic unit of communication via the D-Bus
4923 protocol. It consists of a <firstterm>header</firstterm> and a
4924 <firstterm>body</firstterm>; the body is made up of
4925 <firstterm>arguments</firstterm>.
4930 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
4933 The message bus is a special application that forwards
4934 or routes messages between a group of applications
4935 connected to the message bus. It also manages
4936 <firstterm>names</firstterm> used for routing
4942 <glossentry id="term-name"><glossterm>Name</glossterm>
4945 See <xref linkend="term-bus-name"/>. "Name" may
4946 also be used to refer to some of the other names
4947 in D-Bus, such as interface names.
4952 <glossentry id="namespace"><glossterm>Namespace</glossterm>
4955 Used to prevent collisions when defining new interfaces or bus
4956 names. The convention used is the same one Java uses for defining
4957 classes: a reversed domain name.
4962 <glossentry id="term-object"><glossterm>Object</glossterm>
4965 Each application contains <firstterm>objects</firstterm>, which have
4966 <firstterm>interfaces</firstterm> and
4967 <firstterm>methods</firstterm>. Objects are referred to by a name,
4968 called a <firstterm>path</firstterm>.
4973 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
4976 An application talking directly to another application, without going
4977 through a message bus. One-to-one connections may be "peer to peer" or
4978 "client to server." The D-Bus protocol has no concept of client
4979 vs. server after a connection has authenticated; the flow of messages
4980 is symmetrical (full duplex).
4985 <glossentry id="term-path"><glossterm>Path</glossterm>
4988 Object references (object names) in D-Bus are organized into a
4989 filesystem-style hierarchy, so each object is named by a path. As in
4990 LDAP, there's no difference between "files" and "directories"; a path
4991 can refer to an object, while still having child objects below it.
4996 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
4999 Each bus name has a primary owner; messages sent to the name go to the
5000 primary owner. However, certain names also maintain a queue of
5001 secondary owners "waiting in the wings." If the primary owner releases
5002 the name, then the first secondary owner in the queue automatically
5003 becomes the new owner of the name.
5008 <glossentry id="term-service"><glossterm>Service</glossterm>
5011 A service is an executable that can be launched by the bus daemon.
5012 Services normally guarantee some particular features, for example they
5013 may guarantee that they will request a specific name such as
5014 "org.freedesktop.Screensaver", have a singleton object
5015 "/org/freedesktop/Application", and that object will implement the
5016 interface "org.freedesktop.ScreensaverControl".
5021 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
5024 ".service files" tell the bus about service applications that can be
5025 launched (see <xref linkend="term-service"/>). Most importantly they
5026 provide a mapping from bus names to services that will request those
5027 names when they start up.
5032 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
5035 The special name automatically assigned to each connection by the
5036 message bus. This name will never change owner, and will be unique
5037 (never reused during the lifetime of the message bus).
5038 It will begin with a ':' character.