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"
9 <title>D-BUS Specification</title>
10 <releaseinfo>Version 0.11</releaseinfo>
11 <date>6 February 2005</date>
14 <firstname>Havoc</firstname>
15 <surname>Pennington</surname>
17 <orgname>Red Hat, Inc.</orgname>
19 <email>hp@pobox.com</email>
24 <firstname>Anders</firstname>
25 <surname>Carlsson</surname>
27 <orgname>CodeFactory AB</orgname>
29 <email>andersca@codefactory.se</email>
34 <firstname>Alexander</firstname>
35 <surname>Larsson</surname>
37 <orgname>Red Hat, Inc.</orgname>
39 <email>alexl@redhat.com</email>
46 <sect1 id="introduction">
47 <title>Introduction</title>
49 D-BUS is a system for low-latency, low-overhead, easy to use
50 interprocess communication (IPC). In more detail:
54 D-BUS is <emphasis>low-latency</emphasis> because it is designed
55 to avoid round trips and allow asynchronous operation, much like
61 D-BUS is <emphasis>low-overhead</emphasis> because it uses a
62 binary protocol, and does not have to convert to and from a text
63 format such as XML. Because D-BUS is intended for potentially
64 high-resolution same-machine IPC, not primarily for Internet IPC,
65 this is an interesting optimization.
70 D-BUS is <emphasis>easy to use</emphasis> because it works in terms
71 of <firstterm>messages</firstterm> rather than byte streams, and
72 automatically handles a lot of the hard IPC issues. Also, the D-BUS
73 library is designed to be wrapped in a way that lets developers use
74 their framework's existing object/type system, rather than learning
75 a new one specifically for IPC.
82 The base D-BUS protocol is a one-to-one (peer-to-peer or client-server)
83 protocol, specified in <xref linkend="message-protocol"/>. That is, it is
84 a system for one application to talk to a single other
85 application. However, the primary intended application of the protocol is the
86 D-BUS <firstterm>message bus</firstterm>, specified in <xref
87 linkend="message-bus"/>. The message bus is a special application that
88 accepts connections from multiple other applications, and forwards
93 Uses of D-BUS include notification of system changes (notification of when
94 a camera is plugged in to a computer, or a new version of some software
95 has been installed), or desktop interoperability, for example a file
96 monitoring service or a configuration service.
100 D-BUS is designed for two specific use cases:
104 A "system bus" for notifications from the system to user sessions,
105 and to allow the system to request input from user sessions.
110 A "session bus" used to implement desktop environments such as
115 D-BUS is not intended to be a generic IPC system for any possible
116 application, and intentionally omits many features found in other
117 IPC systems for this reason. D-BUS may turn out to be useful
118 in unanticipated applications, but future versions of this
119 spec and the reference implementation probably will not
120 incorporate features that interfere with the core use cases.
124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
126 document are to be interpreted as described in RFC 2119. However, the
127 document could use a serious audit to be sure it makes sense to do
128 so. Also, they are not capitalized.
133 <sect1 id="message-protocol">
134 <title>Message Protocol</title>
137 A <firstterm>message</firstterm> consists of a
138 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
139 think of a message as a package, the header is the address, and the body
140 contains the package contents. The message delivery system uses the header
141 information to figure out where to send the message and how to interpret
142 it; the recipient inteprets the body of the message.
146 The body of the message is made up of zero or more
147 <firstterm>arguments</firstterm>, which are typed values, such as an
148 integer or a byte array.
152 Both header and body use the same type system and format for
153 serializing data. Each type of value has a wire format.
154 Converting a value from some other representation into the wire
155 format is called <firstterm>marshaling</firstterm> and converting
156 it back from the wire format is <firstterm>unmarshaling</firstterm>.
159 <sect2 id="message-protocol-signatures">
160 <title>Type Signatures</title>
163 The D-BUS protocol does not include type tags in the marshaled data; a
164 block of marshaled values must have a known <firstterm>type
165 signature</firstterm>. The type signature is made up of <firstterm>type
166 codes</firstterm>. A type code is an ASCII character representing the
167 type of a value. Because ASCII characters are used, the type signature
168 will always form a valid ASCII string. A simple string compare
169 determines whether two type signatures are equivalent.
173 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
174 the ASCII character 'i'. So the signature for a block of values
175 containing a single <literal>INT32</literal> would be:
179 A block of values containing two <literal>INT32</literal> would have this signature:
186 All <firstterm>basic</firstterm> types work like
187 <literal>INT32</literal> in this example. To marshal and unmarshal
188 basic types, you simply read one value from the data
189 block corresponding to each type code in the signature.
190 In addition to basic types, there are four <firstterm>container</firstterm>
191 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
192 and <literal>DICT_ENTRY</literal>.
196 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
197 code does not appear in signatures. Instead, ASCII characters
198 '(' and ')' are used to mark the beginning and end of the struct.
199 So for example, a struct containing two integers would have this
204 Structs can be nested, so for example a struct containing
205 an integer and another struct:
209 The value block storing that struct would contain three integers; the
210 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
215 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
216 but is useful in code that implements the protocol. This type code
217 is specified to allow such code to interoperate in non-protocol contexts.
221 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
222 followed by a <firstterm>single complete type</firstterm>. The single
223 complete type following the array is the type of each array element. So
224 the simple example is:
228 which is an array of 32-bit integers. But an array can be of any type,
229 such as this array-of-struct-with-two-int32-fields:
233 Or this array of array of integer:
240 The phrase <firstterm>single complete type</firstterm> deserves some
241 definition. A single complete type is a basic type code, a variant type code,
242 an array with its element type, or a struct with its fields.
243 So the following signatures are not single complete types:
253 And the following signatures contain multiple complete types:
263 Note however that a single complete type may <emphasis>contain</emphasis>
264 multiple other single complete types.
268 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
269 type <literal>VARIANT</literal> will have the signature of a single complete type as part
270 of the <emphasis>value</emphasis>. This signature will be followed by a
271 marshaled value of that type.
275 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
276 than parentheses it uses curly braces, and it has more restrictions.
277 The restrictions are: it occurs only as an array element type; it has
278 exactly two single complete types inside the curly braces; the first
279 single complete type (the "key") must be a basic type rather than a
280 container type. Implementations must not accept dict entries outside of
281 arrays, must not accept dict entries with zero, one, or more than two
282 fields, and must not accept dict entries with non-basic-typed keys. A
283 dict entry is always a key-value pair.
287 The first field in the <literal>DICT_ENTRY</literal> is always the key.
288 A message is considered corrupt if the same key occurs twice in the same
289 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
290 implementations are not required to reject dicts with duplicate keys.
294 In most languages, an array of dict entry would be represented as a
295 map, hash table, or dict object.
299 The following table summarizes the D-BUS types.
304 <entry>Conventional Name</entry>
306 <entry>Description</entry>
311 <entry><literal>INVALID</literal></entry>
312 <entry>0 (ASCII NUL)</entry>
313 <entry>Not a valid type code, used to terminate signatures</entry>
315 <entry><literal>BYTE</literal></entry>
316 <entry>121 (ASCII 'y')</entry>
317 <entry>8-bit unsigned integer</entry>
319 <entry><literal>BOOLEAN</literal></entry>
320 <entry>98 (ASCII 'b')</entry>
321 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
323 <entry><literal>INT16</literal></entry>
324 <entry>110 (ASCII 'n')</entry>
325 <entry>16-bit signed integer</entry>
327 <entry><literal>UINT16</literal></entry>
328 <entry>113 (ASCII 'q')</entry>
329 <entry>16-bit unsigned integer</entry>
331 <entry><literal>INT32</literal></entry>
332 <entry>105 (ASCII 'i')</entry>
333 <entry>32-bit signed integer</entry>
335 <entry><literal>UINT32</literal></entry>
336 <entry>117 (ASCII 'u')</entry>
337 <entry>32-bit unsigned integer</entry>
339 <entry><literal>INT64</literal></entry>
340 <entry>120 (ASCII 'x')</entry>
341 <entry>64-bit signed integer</entry>
343 <entry><literal>UINT64</literal></entry>
344 <entry>116 (ASCII 't')</entry>
345 <entry>64-bit unsigned integer</entry>
347 <entry><literal>DOUBLE</literal></entry>
348 <entry>100 (ASCII 'd')</entry>
349 <entry>IEEE 754 double</entry>
351 <entry><literal>STRING</literal></entry>
352 <entry>115 (ASCII 's')</entry>
353 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated.</entry>
355 <entry><literal>OBJECT_PATH</literal></entry>
356 <entry>111 (ASCII 'o')</entry>
357 <entry>Name of an object instance</entry>
359 <entry><literal>SIGNATURE</literal></entry>
360 <entry>103 (ASCII 'g')</entry>
361 <entry>A type signature</entry>
363 <entry><literal>ARRAY</literal></entry>
364 <entry>97 (ASCII 'a')</entry>
367 <entry><literal>STRUCT</literal></entry>
368 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
369 <entry>Struct</entry>
371 <entry><literal>VARIANT</literal></entry>
372 <entry>118 (ASCII 'v') </entry>
373 <entry>Variant type (the type of the value is part of the value itself)</entry>
375 <entry><literal>DICT_ENTRY</literal></entry>
376 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
377 <entry>Entry in a dict or map (array of key-value pairs)</entry>
386 <sect2 id="message-protocol-marshaling">
387 <title>Marshaling (Wire Format)</title>
390 Given a type signature, a block of bytes can be converted into typed
391 values. This section describes the format of the block of bytes. Byte
392 order and alignment issues are handled uniformly for all D-BUS types.
396 A block of bytes has an associated byte order. The byte order
397 has to be discovered in some way; for D-BUS messages, the
398 byte order is part of the message header as described in
399 <xref linkend="message-protocol-messages"/>. For now, assume
400 that the byte order is known to be either little endian or big
405 Each value in a block of bytes is aligned "naturally," for example
406 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
407 8-byte boundary. To properly align a value, <firstterm>alignment
408 padding</firstterm> may be necessary. The alignment padding must always
409 be the minimum required padding to properly align the following value;
410 and it must always be made up of nul bytes. The alignment padding must
411 not be left uninitialized (it can't contain garbage), and more padding
412 than required must not be used.
416 Given all this, the types are marshaled on the wire as follows:
421 <entry>Conventional Name</entry>
422 <entry>Encoding</entry>
423 <entry>Alignment</entry>
428 <entry><literal>INVALID</literal></entry>
429 <entry>Not applicable; cannot be marshaled.</entry>
432 <entry><literal>BYTE</literal></entry>
433 <entry>A single 8-bit byte.</entry>
436 <entry><literal>BOOLEAN</literal></entry>
437 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
440 <entry><literal>INT16</literal></entry>
441 <entry>16-bit signed integer in the message's byte order.</entry>
444 <entry><literal>UINT16</literal></entry>
445 <entry>16-bit unsigned integer in the message's byte order.</entry>
448 <entry><literal>INT32</literal></entry>
449 <entry>32-bit signed integer in the message's byte order.</entry>
452 <entry><literal>UINT32</literal></entry>
453 <entry>32-bit unsigned integer in the message's byte order.</entry>
456 <entry><literal>INT64</literal></entry>
457 <entry>64-bit signed integer in the message's byte order.</entry>
460 <entry><literal>UINT64</literal></entry>
461 <entry>64-bit unsigned integer in the message's byte order.</entry>
464 <entry><literal>DOUBLE</literal></entry>
465 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
468 <entry><literal>STRING</literal></entry>
469 <entry>A <literal>UINT32</literal> indicating the string's
470 length in bytes excluding its terminating nul, followed by
471 string data of the given length, followed by a terminating nul
478 <entry><literal>OBJECT_PATH</literal></entry>
479 <entry>Exactly the same as <literal>STRING</literal> except the
480 content must be a valid object path (see below).
486 <entry><literal>SIGNATURE</literal></entry>
487 <entry>The same as <literal>STRING</literal> except the length is a single
488 byte (thus signatures have a maximum length of 255)
489 and the content must be a valid signature (see below).
495 <entry><literal>ARRAY</literal></entry>
497 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
498 alignment padding to the alignment boundary of the array element type,
499 followed by each array element. The array length is from the
500 end of the alignment padding to the end of the last element,
501 i.e. it does not include the padding after the length,
502 or any padding after the last element.
503 Arrays have a maximum length defined to be 2 to the 26th power or
504 67108864. Implementations must not send or accept arrays exceeding this
511 <entry><literal>STRUCT</literal></entry>
513 A struct must start on an 8-byte boundary regardless of the
514 type of the struct fields. The struct value consists of each
515 field marshaled in sequence starting from that 8-byte
522 <entry><literal>VARIANT</literal></entry>
524 A variant type has a marshaled <literal>SIGNATURE</literal>
525 followed by a marshaled value with the type
526 given in the signature.
527 Unlike a message signature, the variant signature
528 can contain only a single complete type.
529 So "i" is OK, "ii" is not.
532 1 (alignment of the signature)
535 <entry><literal>DICT_ENTRY</literal></entry>
548 <sect3 id="message-protocol-marshaling-object-path">
549 <title>Valid Object Paths</title>
552 An object path is a name used to refer to an object instance.
553 Conceptually, each participant in a D-BUS message exchange may have
554 any number of object instances (think of C++ or Java objects) and each
555 such instance will have a path. Like a filesystem, the object
556 instances in an application form a hierarchical tree.
560 The following rules define a valid object path. Implementations must
561 not send or accept messages with invalid object paths.
565 The path may be of any length.
570 The path must begin with an ASCII '/' (integer 47) character,
571 and must consist of elements separated by slash characters.
576 Each element must only contain the ASCII characters
582 No element may be the empty string.
587 Multiple '/' characters cannot occur in sequence.
592 A trailing '/' character is not allowed unless the
593 path is the root path (a single '/' character).
602 <sect3 id="message-protocol-marshaling-signature">
603 <title>Valid Signatures</title>
605 An implementation must not send or accept invalid signatures.
606 Valid signatures will conform to the following rules:
610 The signature ends with a nul byte.
615 The signature is a list of single complete types.
616 Arrays must have element types, and structs must
617 have both open and close parentheses.
622 Only type codes and open and close parentheses are
623 allowed in the signature. The <literal>STRUCT</literal> type code
624 is not allowed in signatures, because parentheses
630 The maximum depth of container type nesting is 32 array type
631 codes and 32 open parentheses. This implies that the maximum
632 total depth of recursion is 64, for an "array of array of array
633 of ... struct of struct of struct of ..." where there are 32
639 The maximum length of a signature is 255.
644 Signatures must be nul-terminated.
653 <sect2 id="message-protocol-messages">
654 <title>Message Format</title>
657 A message consists of a header and a body. The header is a block of
658 values with a fixed signature and meaning. The body is a separate block
659 of values, with a signature specified in the header.
663 The length of the header must be a multiple of 8, allowing the body to
664 begin on an 8-byte boundary when storing the entire message in a single
665 buffer. If the header does not naturally end on an 8-byte boundary
666 up to 7 bytes of nul-initialized alignment padding must be added.
670 The message body need not end on an 8-byte boundary.
674 The maximum length of a message, including header, header alignment padding,
675 and body is 2 to the 27th power or 134217728. Implementations must not
676 send or accept messages exceeding this size.
680 The signature of the header is:
684 Written out more readably, this is:
686 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
691 These values have the following meanings:
697 <entry>Description</entry>
702 <entry>1st <literal>BYTE</literal></entry>
703 <entry>Endianness flag; ASCII 'l' for little-endian
704 or ASCII 'B' for big-endian. Both header and body are
705 in this endianness.</entry>
708 <entry>2nd <literal>BYTE</literal></entry>
709 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
710 Currently-defined types are described below.
714 <entry>3rd <literal>BYTE</literal></entry>
715 <entry>Bitwise OR of flags. Unknown flags
716 must be ignored. Currently-defined flags are described below.
720 <entry>4th <literal>BYTE</literal></entry>
721 <entry>Major protocol version of the sending application. If
722 the major protocol version of the receiving application does not
723 match, the applications will not be able to communicate and the
724 D-BUS connection must be disconnected. The major protocol
725 version for this version of the specification is 0.
726 FIXME this field is stupid and pointless to put in
731 <entry>1st <literal>UINT32</literal></entry>
732 <entry>Length in bytes of the message body, starting
733 from the end of the header. The header ends after
734 its alignment padding to an 8-boundary.
738 <entry>2nd <literal>UINT32</literal></entry>
739 <entry>The serial of this message, used as a cookie
740 by the sender to identify the reply corresponding
745 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
746 <entry>An array of zero or more <firstterm>header
747 fields</firstterm> where the byte is the field code, and the
748 variant is the field value. The message type determines
749 which fields are required.
757 <firstterm>Message types</firstterm> that can appear in the second byte
763 <entry>Conventional name</entry>
764 <entry>Decimal value</entry>
765 <entry>Description</entry>
770 <entry><literal>INVALID</literal></entry>
772 <entry>This is an invalid type.</entry>
775 <entry><literal>METHOD_CALL</literal></entry>
777 <entry>Method call.</entry>
780 <entry><literal>METHOD_RETURN</literal></entry>
782 <entry>Method reply with returned data.</entry>
785 <entry><literal>ERROR</literal></entry>
787 <entry>Error reply. If the first argument exists and is a
788 string, it is an error message.</entry>
791 <entry><literal>SIGNAL</literal></entry>
793 <entry>Signal emission.</entry>
800 Flags that can appear in the third byte of the header:
805 <entry>Conventional name</entry>
806 <entry>Hex value</entry>
807 <entry>Description</entry>
812 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
814 <entry>This message does not expect method return replies or
815 error replies; the reply can be omitted as an
816 optimization. However, it is compliant with this specification
817 to return the reply despite this flag and the only harm
818 from doing so is extra network traffic.
822 <entry><literal>NO_AUTO_START</literal></entry>
824 <entry>The bus must not launch an owner
825 for the destination name in response to this message.
833 <sect3 id="message-protocol-header-fields">
834 <title>Header Fields</title>
837 The array at the end of the header contains <firstterm>header
838 fields</firstterm>, where each field is a 1-byte field code followed
839 by a field value. A header must contain the required header fields for
840 its message type, and zero or more of any optional header
841 fields. Future versions of this protocol specification may add new
842 fields. Implementations must ignore fields they do not
843 understand. Implementations must not invent their own header fields;
844 only changes to this specification may introduce new header fields.
848 Again, if an implementation sees a header field code that it does not
849 expect, it must ignore that field, as it will be part of a new
850 (but compatible) version of this specification. This also applies
851 to known header fields appearing in unexpected messages, for
852 example: if a signal has a reply serial it must be ignored
853 even though it has no meaning as of this version of the spec.
857 However, implementations must not send or accept known header fields
858 with the wrong type stored in the field value. So for example a
859 message with an <literal>INTERFACE</literal> field of type
860 <literal>UINT32</literal> would be considered corrupt.
864 Here are the currently-defined header fields:
869 <entry>Conventional Name</entry>
870 <entry>Decimal Code</entry>
872 <entry>Required In</entry>
873 <entry>Description</entry>
878 <entry><literal>INVALID</literal></entry>
881 <entry>not allowed</entry>
882 <entry>Not a valid field name (error if it appears in a message)</entry>
885 <entry><literal>PATH</literal></entry>
887 <entry><literal>OBJECT_PATH</literal></entry>
888 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
889 <entry>The object to send a call to,
890 or the object a signal is emitted from.
894 <entry><literal>INTERFACE</literal></entry>
896 <entry><literal>STRING</literal></entry>
897 <entry><literal>SIGNAL</literal></entry>
899 The interface to invoke a method call on, or
900 that a signal is emitted from. Optional for
901 method calls, required for signals.
905 <entry><literal>MEMBER</literal></entry>
907 <entry><literal>STRING</literal></entry>
908 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
909 <entry>The member, either the method name or signal name.</entry>
912 <entry><literal>ERROR_NAME</literal></entry>
914 <entry><literal>STRING</literal></entry>
915 <entry><literal>ERROR</literal></entry>
916 <entry>The name of the error that occurred, for errors</entry>
919 <entry><literal>REPLY_SERIAL</literal></entry>
921 <entry><literal>UINT32</literal></entry>
922 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
923 <entry>The serial number of the message this message is a reply
924 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
927 <entry><literal>DESTINATION</literal></entry>
929 <entry><literal>STRING</literal></entry>
930 <entry>optional</entry>
931 <entry>The name of the connection this message is intended for.
932 Only used in combination with the message bus, see
933 <xref linkend="message-bus"/>.</entry>
936 <entry><literal>SENDER</literal></entry>
938 <entry><literal>STRING</literal></entry>
939 <entry>optional</entry>
940 <entry>Unique name of the sending connection.
941 The message bus fills in this field so it is reliable; the field is
942 only meaningful in combination with the message bus.</entry>
945 <entry><literal>SIGNATURE</literal></entry>
947 <entry><literal>SIGNATURE</literal></entry>
948 <entry>optional</entry>
949 <entry>The signature of the message body.
950 If omitted, it is assumed to be the
951 empty signature "" (i.e. the body must be 0-length).</entry>
960 <sect2 id="message-protocol-names">
961 <title>Valid Names</title>
963 The various names in D-BUS messages have some restrictions.
966 There is a <firstterm>maximum name length</firstterm>
967 of 255 which applies to bus names, interfaces, and members.
969 <sect3 id="message-protocol-names-interface">
970 <title>Interface names</title>
972 Interfaces have names with type <literal>STRING</literal>, meaning that
973 they must be valid UTF-8. However, there are also some
974 additional restrictions that apply to interface names
977 <listitem><para>Interface names are composed of 1 or more elements separated by
978 a period ('.') character. All elements must contain at least
982 <listitem><para>Each element must only contain the ASCII characters
983 "[A-Z][a-z][0-9]_" and must not begin with a digit.
987 <listitem><para>Interface names must contain at least one '.' (period)
988 character (and thus at least two elements).
991 <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
992 <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
996 <sect3 id="message-protocol-names-bus">
997 <title>Bus names</title>
999 Connections have one or more bus names associated with them.
1000 A connection has exactly one bus name that is a unique connection
1001 name. The unique connection name remains with the connection for
1002 its entire lifetime.
1003 A bus name is of type <literal>STRING</literal>,
1004 meaning that it must be valid UTF-8. However, there are also
1005 some additional restrictions that apply to bus names
1008 <listitem><para>Bus names that start with a colon (':')
1009 character are unique connection names.
1012 <listitem><para>Bus names are composed of 1 or more elements separated by
1013 a period ('.') character. All elements must contain at least
1017 <listitem><para>Each element must only contain the ASCII characters
1018 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
1019 connection name may begin with a digit, elements in
1020 other bus names must not begin with a digit.
1024 <listitem><para>Bus names must contain at least one '.' (period)
1025 character (and thus at least two elements).
1028 <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
1029 <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
1033 Note that the hyphen ('-') character is allowed in bus names but
1034 not in interface names.
1037 <sect3 id="message-protocol-names-member">
1038 <title>Member names</title>
1040 Member (i.e. method or signal) names:
1042 <listitem><para>Must only contain the ASCII characters
1043 "[A-Z][a-z][0-9]_" and may not begin with a
1044 digit.</para></listitem>
1045 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1046 <listitem><para>Must not exceed the maximum name length.</para></listitem>
1047 <listitem><para>Must be at least 1 byte in length.</para></listitem>
1051 <sect3 id="message-protocol-names-error">
1052 <title>Error names</title>
1054 Error names have the same restrictions as interface names.
1059 <sect2 id="message-protocol-types">
1060 <title>Message Types</title>
1062 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1063 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1064 This section describes these conventions.
1066 <sect3 id="message-protocol-types-method">
1067 <title>Method Calls</title>
1069 Some messages invoke an operation on a remote object. These are
1070 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1071 messages map naturally to methods on objects in a typical program.
1074 A method call message is required to have a <literal>MEMBER</literal> header field
1075 indicating the name of the method. Optionally, the message has an
1076 <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1077 absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1078 a method with the same name, it is undefined which of the two methods
1079 will be invoked. Implementations may also choose to return an error in
1080 this ambiguous case. However, if a method name is unique
1081 implementations must not require an interface field.
1084 Method call messages also include a <literal>PATH</literal> field
1085 indicating the object to invoke the method on. If the call is passing
1086 through a message bus, the message will also have a
1087 <literal>DESTINATION</literal> field giving the name of the connection
1088 to receive the message.
1091 When an application handles a method call message, it is required to
1092 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1093 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1094 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1097 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1098 are the return value(s) or "out parameters" of the method call.
1099 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1100 and the call fails; no return value will be provided. It makes
1101 no sense to send multiple replies to the same method call.
1104 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1105 reply is required, so the caller will know the method
1106 was successfully processed.
1109 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1113 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1114 then as an optimization the application receiving the method
1115 call may choose to omit the reply message (regardless of
1116 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1117 However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1118 flag and reply anyway.
1121 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1122 destination name does not exist then a program to own the destination
1123 name will be started before the message is delivered. The message
1124 will be held until the new program is successfully started or has
1125 failed to start; in case of failure, an error will be returned. This
1126 flag is only relevant in the context of a message bus, it is ignored
1127 during one-to-one communication with no intermediate bus.
1129 <sect4 id="message-protocol-types-method-apis">
1130 <title>Mapping method calls to native APIs</title>
1132 APIs for D-BUS may map method calls to a method call in a specific
1133 programming language, such as C++, or may map a method call written
1134 in an IDL to a D-BUS message.
1137 In APIs of this nature, arguments to a method are often termed "in"
1138 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1139 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1140 "inout" arguments, which are both sent and received, i.e. the caller
1141 passes in a value which is modified. Mapped to D-BUS, an "inout"
1142 argument is equivalent to an "in" argument, followed by an "out"
1143 argument. You can't pass things "by reference" over the wire, so
1144 "inout" is purely an illusion of the in-process API.
1147 Given a method with zero or one return values, followed by zero or more
1148 arguments, where each argument may be "in", "out", or "inout", the
1149 caller constructs a message by appending each "in" or "inout" argument,
1150 in order. "out" arguments are not represented in the caller's message.
1153 The recipient constructs a reply by appending first the return value
1154 if any, then each "out" or "inout" argument, in order.
1155 "in" arguments are not represented in the reply message.
1158 Error replies are normally mapped to exceptions in languages that have
1162 In converting from native APIs to D-BUS, it is perhaps nice to
1163 map D-BUS naming conventions ("FooBar") to native conventions
1164 such as "fooBar" or "foo_bar" automatically. This is OK
1165 as long as you can say that the native API is one that
1166 was specifically written for D-BUS. It makes the most sense
1167 when writing object implementations that will be exported
1168 over the bus. Object proxies used to invoke remote D-BUS
1169 objects probably need the ability to call any D-BUS method,
1170 and thus a magic name mapping like this could be a problem.
1173 This specification doesn't require anything of native API bindings;
1174 the preceding is only a suggested convention for consistency
1180 <sect3 id="message-protocol-types-signal">
1181 <title>Signal Emission</title>
1183 Unlike method calls, signal emissions have no replies.
1184 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1185 It must have three header fields: <literal>PATH</literal> giving the object
1186 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1187 the fully-qualified name of the signal.
1191 <sect3 id="message-protocol-types-errors">
1192 <title>Errors</title>
1194 Messages of type <literal>ERROR</literal> are most commonly replies
1195 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1196 to any kind of message. The message bus for example
1197 will return an <literal>ERROR</literal> in reply to a signal emission if
1198 the bus does not have enough memory to send the signal.
1201 An <literal>ERROR</literal> may have any arguments, but if the first
1202 argument is a <literal>STRING</literal>, it must be an error message.
1203 The error message may be logged or shown to the user
1208 <sect3 id="message-protocol-types-notation">
1209 <title>Notation in this document</title>
1211 This document uses a simple pseudo-IDL to describe particular method
1212 calls and signals. Here is an example of a method call:
1214 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1215 out UINT32 resultcode)
1217 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1218 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1219 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1220 characters so it's known that the last part of the name in
1221 the "IDL" is the member name.
1224 In C++ that might end up looking like this:
1226 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1227 unsigned int flags);
1229 or equally valid, the return value could be done as an argument:
1231 void org::freedesktop::DBus::StartServiceByName (const char *name,
1233 unsigned int *resultcode);
1235 It's really up to the API designer how they want to make
1236 this look. You could design an API where the namespace wasn't used
1237 in C++, using STL or Qt, using varargs, or whatever you wanted.
1240 Signals are written as follows:
1242 org.freedesktop.DBus.NameLost (STRING name)
1244 Signals don't specify "in" vs. "out" because only
1245 a single direction is possible.
1248 It isn't especially encouraged to use this lame pseudo-IDL in actual
1249 API implementations; you might use the native notation for the
1250 language you're using, or you might use COM or CORBA IDL, for example.
1255 <sect2 id="message-protocol-handling-invalid">
1256 <title>Invalid Protocol and Spec Extensions</title>
1259 For security reasons, the D-BUS protocol should be strictly parsed and
1260 validated, with the exception of defined extension points. Any invalid
1261 protocol or spec violations should result in immediately dropping the
1262 connection without notice to the other end. Exceptions should be
1263 carefully considered, e.g. an exception may be warranted for a
1264 well-understood idiosyncracy of a widely-deployed implementation. In
1265 cases where the other end of a connection is 100% trusted and known to
1266 be friendly, skipping validation for performance reasons could also make
1267 sense in certain cases.
1271 Generally speaking violations of the "must" requirements in this spec
1272 should be considered possible attempts to exploit security, and violations
1273 of the "should" suggestions should be considered legitimate (though perhaps
1274 they should generate an error in some cases).
1278 The following extension points are built in to D-BUS on purpose and must
1279 not be treated as invalid protocol. The extension points are intended
1280 for use by future versions of this spec, they are not intended for third
1281 parties. At the moment, the only way a third party could extend D-BUS
1282 without breaking interoperability would be to introduce a way to negotiate new
1283 feature support as part of the auth protocol, using EXTENSION_-prefixed
1284 commands. There is not yet a standard way to negotiate features.
1288 In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
1289 commands result in an ERROR rather than a disconnect. This enables
1290 future extensions to the protocol. Commands starting with EXTENSION_ are
1291 reserved for third parties.
1296 The authentication protocol supports pluggable auth mechanisms.
1301 The address format (see <xref linkend="addresses"/>) supports new
1307 Messages with an unknown type (something other than
1308 <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
1309 <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
1310 Unknown-type messages must still be well-formed in the same way
1311 as the known messages, however. They still have the normal
1317 Header fields with an unknown or unexpected field code must be ignored,
1318 though again they must still be well-formed.
1323 New standard interfaces (with new methods and signals) can of course be added.
1333 <sect1 id="auth-protocol">
1334 <title>Authentication Protocol</title>
1336 Before the flow of messages begins, two applications must
1337 authenticate. A simple plain-text protocol is used for
1338 authentication; this protocol is a SASL profile, and maps fairly
1339 directly from the SASL specification. The message encoding is
1340 NOT used here, only plain text messages.
1343 In examples, "C:" and "S:" indicate lines sent by the client and
1344 server respectively.
1346 <sect2 id="auth-protocol-overview">
1347 <title>Protocol Overview</title>
1349 The protocol is a line-based protocol, where each line ends with
1350 \r\n. Each line begins with an all-caps ASCII command name containing
1351 only the character range [A-Z_], a space, then any arguments for the
1352 command, then the \r\n ending the line. The protocol is
1353 case-sensitive. All bytes must be in the ASCII character set.
1355 Commands from the client to the server are as follows:
1358 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1359 <listitem><para>CANCEL</para></listitem>
1360 <listitem><para>BEGIN</para></listitem>
1361 <listitem><para>DATA <data in hex encoding></para></listitem>
1362 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1365 From server to client are as follows:
1368 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
1369 <listitem><para>OK <GUID in hex></para></listitem>
1370 <listitem><para>DATA <data in hex encoding></para></listitem>
1371 <listitem><para>ERROR</para></listitem>
1375 Unofficial extensions to the command set must begin with the letters
1376 "EXTENSION_", to avoid conflicts with future official commands.
1377 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
1380 <sect2 id="auth-nul-byte">
1381 <title>Special credentials-passing nul byte</title>
1383 Immediately after connecting to the server, the client must send a
1384 single nul byte. This byte may be accompanied by credentials
1385 information on some operating systems that use sendmsg() with
1386 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1387 sockets. However, the nul byte must be sent even on other kinds of
1388 socket, and even on operating systems that do not require a byte to be
1389 sent in order to transmit credentials. The text protocol described in
1390 this document begins after the single nul byte. If the first byte
1391 received from the client is not a nul byte, the server may disconnect
1395 A nul byte in any context other than the initial byte is an error;
1396 the protocol is ASCII-only.
1399 The credentials sent along with the nul byte may be used with the
1400 SASL mechanism EXTERNAL.
1403 <sect2 id="auth-command-auth">
1404 <title>AUTH command</title>
1406 If an AUTH command has no arguments, it is a request to list
1407 available mechanisms. The server must respond with a REJECTED
1408 command listing the mechanisms it understands, or with an error.
1411 If an AUTH command specifies a mechanism, and the server supports
1412 said mechanism, the server should begin exchanging SASL
1413 challenge-response data with the client using DATA commands.
1416 If the server does not support the mechanism given in the AUTH
1417 command, it must send either a REJECTED command listing the mechanisms
1418 it does support, or an error.
1421 If the [initial-response] argument is provided, it is intended for use
1422 with mechanisms that have no initial challenge (or an empty initial
1423 challenge), as if it were the argument to an initial DATA command. If
1424 the selected mechanism has an initial challenge and [initial-response]
1425 was provided, the server should reject authentication by sending
1429 If authentication succeeds after exchanging DATA commands,
1430 an OK command must be sent to the client.
1433 The first octet received by the client after the \r\n of the OK
1434 command must be the first octet of the authenticated/encrypted
1435 stream of D-BUS messages.
1438 The first octet received by the server after the \r\n of the BEGIN
1439 command from the client must be the first octet of the
1440 authenticated/encrypted stream of D-BUS messages.
1443 <sect2 id="auth-command-cancel">
1444 <title>CANCEL Command</title>
1446 At any time up to sending the BEGIN command, the client may send a
1447 CANCEL command. On receiving the CANCEL command, the server must
1448 send a REJECTED command and abort the current authentication
1452 <sect2 id="auth-command-data">
1453 <title>DATA Command</title>
1455 The DATA command may come from either client or server, and simply
1456 contains a hex-encoded block of data to be interpreted
1457 according to the SASL mechanism in use.
1460 Some SASL mechanisms support sending an "empty string";
1461 FIXME we need some way to do this.
1464 <sect2 id="auth-command-begin">
1465 <title>BEGIN Command</title>
1467 The BEGIN command acknowledges that the client has received an
1468 OK command from the server, and that the stream of messages
1472 The first octet received by the server after the \r\n of the BEGIN
1473 command from the client must be the first octet of the
1474 authenticated/encrypted stream of D-BUS messages.
1477 <sect2 id="auth-command-rejected">
1478 <title>REJECTED Command</title>
1480 The REJECTED command indicates that the current authentication
1481 exchange has failed, and further exchange of DATA is inappropriate.
1482 The client would normally try another mechanism, or try providing
1483 different responses to challenges.
1485 Optionally, the REJECTED command has a space-separated list of
1486 available auth mechanisms as arguments. If a server ever provides
1487 a list of supported mechanisms, it must provide the same list
1488 each time it sends a REJECTED message. Clients are free to
1489 ignore all lists received after the first.
1492 <sect2 id="auth-command-ok">
1493 <title>OK Command</title>
1495 The OK command indicates that the client has been authenticated,
1496 and that further communication will be a stream of D-BUS messages
1497 (optionally encrypted, as negotiated) rather than this protocol.
1500 The first octet received by the client after the \r\n of the OK
1501 command must be the first octet of the authenticated/encrypted
1502 stream of D-BUS messages.
1505 The client must respond to the OK command by sending a BEGIN
1506 command, followed by its stream of messages, or by disconnecting.
1507 The server must not accept additional commands using this protocol
1508 after the OK command has been sent.
1511 The OK command has one argument, which is the GUID of the server.
1512 See <xref linkend="addresses"/> for more on server GUIDs.
1515 <sect2 id="auth-command-error">
1516 <title>ERROR Command</title>
1518 The ERROR command indicates that either server or client did not
1519 know a command, does not accept the given command in the current
1520 context, or did not understand the arguments to the command. This
1521 allows the protocol to be extended; a client or server can send a
1522 command present or permitted only in new protocol versions, and if
1523 an ERROR is received instead of an appropriate response, fall back
1524 to using some other technique.
1527 If an ERROR is sent, the server or client that sent the
1528 error must continue as if the command causing the ERROR had never been
1529 received. However, the the server or client receiving the error
1530 should try something other than whatever caused the error;
1531 if only canceling/rejecting the authentication.
1534 If the D-BUS protocol changes incompatibly at some future time,
1535 applications implementing the new protocol would probably be able to
1536 check for support of the new protocol by sending a new command and
1537 receiving an ERROR from applications that don't understand it. Thus the
1538 ERROR feature of the auth protocol is an escape hatch that lets us
1539 negotiate extensions or changes to the D-BUS protocol in the future.
1542 <sect2 id="auth-examples">
1543 <title>Authentication examples</title>
1547 <title>Example of successful magic cookie authentication</title>
1549 (MAGIC_COOKIE is a made up mechanism)
1551 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1557 <title>Example of finding out mechanisms then picking one</title>
1560 S: REJECTED KERBEROS_V4 SKEY
1561 C: AUTH SKEY 7ab83f32ee
1562 S: DATA 8799cabb2ea93e
1563 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1569 <title>Example of client sends unknown command then falls back to regular auth</title>
1573 C: AUTH MAGIC_COOKIE 3736343435313230333039
1579 <title>Example of server doesn't support initial auth mechanism</title>
1581 C: AUTH MAGIC_COOKIE 3736343435313230333039
1582 S: REJECTED KERBEROS_V4 SKEY
1583 C: AUTH SKEY 7ab83f32ee
1584 S: DATA 8799cabb2ea93e
1585 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1591 <title>Example of wrong password or the like followed by successful retry</title>
1593 C: AUTH MAGIC_COOKIE 3736343435313230333039
1594 S: REJECTED KERBEROS_V4 SKEY
1595 C: AUTH SKEY 7ab83f32ee
1596 S: DATA 8799cabb2ea93e
1597 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1599 C: AUTH SKEY 7ab83f32ee
1600 S: DATA 8799cabb2ea93e
1601 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1607 <title>Example of skey cancelled and restarted</title>
1609 C: AUTH MAGIC_COOKIE 3736343435313230333039
1610 S: REJECTED KERBEROS_V4 SKEY
1611 C: AUTH SKEY 7ab83f32ee
1612 S: DATA 8799cabb2ea93e
1615 C: AUTH SKEY 7ab83f32ee
1616 S: DATA 8799cabb2ea93e
1617 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1624 <sect2 id="auth-states">
1625 <title>Authentication state diagrams</title>
1628 This section documents the auth protocol in terms of
1629 a state machine for the client and the server. This is
1630 probably the most robust way to implement the protocol.
1633 <sect3 id="auth-states-client">
1634 <title>Client states</title>
1637 To more precisely describe the interaction between the
1638 protocol state machine and the authentication mechanisms the
1639 following notation is used: MECH(CHALL) means that the
1640 server challenge CHALL was fed to the mechanism MECH, which
1646 CONTINUE(RESP) means continue the auth conversation
1647 and send RESP as the response to the server;
1653 OK(RESP) means that after sending RESP to the server
1654 the client side of the auth conversation is finished
1655 and the server should return "OK";
1661 ERROR means that CHALL was invalid and could not be
1667 Both RESP and CHALL may be empty.
1671 The Client starts by getting an initial response from the
1672 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1673 the mechanism did not provide an initial response. If the
1674 mechanism returns CONTINUE, the client starts in state
1675 <emphasis>WaitingForData</emphasis>, if the mechanism
1676 returns OK the client starts in state
1677 <emphasis>WaitingForOK</emphasis>.
1681 The client should keep track of available mechanisms and
1682 which it mechanisms it has already attempted. This list is
1683 used to decide which AUTH command to send. When the list is
1684 exhausted, the client should give up and close the
1689 <title><emphasis>WaitingForData</emphasis></title>
1697 MECH(CHALL) returns CONTINUE(RESP) → send
1699 <emphasis>WaitingForData</emphasis>
1703 MECH(CHALL) returns OK(RESP) → send DATA
1704 RESP, goto <emphasis>WaitingForOK</emphasis>
1708 MECH(CHALL) returns ERROR → send ERROR
1709 [msg], goto <emphasis>WaitingForData</emphasis>
1717 Receive REJECTED [mechs] →
1718 send AUTH [next mech], goto
1719 WaitingForData or <emphasis>WaitingForOK</emphasis>
1724 Receive ERROR → send
1726 <emphasis>WaitingForReject</emphasis>
1731 Receive OK → send
1732 BEGIN, terminate auth
1733 conversation, authenticated
1738 Receive anything else → send
1740 <emphasis>WaitingForData</emphasis>
1748 <title><emphasis>WaitingForOK</emphasis></title>
1753 Receive OK → send BEGIN, terminate auth
1754 conversation, <emphasis>authenticated</emphasis>
1759 Receive REJECT [mechs] → send AUTH [next mech],
1760 goto <emphasis>WaitingForData</emphasis> or
1761 <emphasis>WaitingForOK</emphasis>
1767 Receive DATA → send CANCEL, goto
1768 <emphasis>WaitingForReject</emphasis>
1774 Receive ERROR → send CANCEL, goto
1775 <emphasis>WaitingForReject</emphasis>
1781 Receive anything else → send ERROR, goto
1782 <emphasis>WaitingForOK</emphasis>
1790 <title><emphasis>WaitingForReject</emphasis></title>
1795 Receive REJECT [mechs] → send AUTH [next mech],
1796 goto <emphasis>WaitingForData</emphasis> or
1797 <emphasis>WaitingForOK</emphasis>
1803 Receive anything else → terminate auth
1804 conversation, disconnect
1813 <sect3 id="auth-states-server">
1814 <title>Server states</title>
1817 For the server MECH(RESP) means that the client response
1818 RESP was fed to the the mechanism MECH, which returns one of
1823 CONTINUE(CHALL) means continue the auth conversation and
1824 send CHALL as the challenge to the client;
1830 OK means that the client has been successfully
1837 REJECT means that the client failed to authenticate or
1838 there was an error in RESP.
1843 The server starts out in state
1844 <emphasis>WaitingForAuth</emphasis>. If the client is
1845 rejected too many times the server must disconnect the
1850 <title><emphasis>WaitingForAuth</emphasis></title>
1856 Receive AUTH → send REJECTED [mechs], goto
1857 <emphasis>WaitingForAuth</emphasis>
1863 Receive AUTH MECH RESP
1867 MECH not valid mechanism → send REJECTED
1869 <emphasis>WaitingForAuth</emphasis>
1873 MECH(RESP) returns CONTINUE(CHALL) → send
1875 <emphasis>WaitingForData</emphasis>
1879 MECH(RESP) returns OK → send OK, goto
1880 <emphasis>WaitingForBegin</emphasis>
1884 MECH(RESP) returns REJECT → send REJECTED
1886 <emphasis>WaitingForAuth</emphasis>
1894 Receive BEGIN → terminate
1895 auth conversation, disconnect
1901 Receive ERROR → send REJECTED [mechs], goto
1902 <emphasis>WaitingForAuth</emphasis>
1908 Receive anything else → send
1910 <emphasis>WaitingForAuth</emphasis>
1919 <title><emphasis>WaitingForData</emphasis></title>
1927 MECH(RESP) returns CONTINUE(CHALL) → send
1929 <emphasis>WaitingForData</emphasis>
1933 MECH(RESP) returns OK → send OK, goto
1934 <emphasis>WaitingForBegin</emphasis>
1938 MECH(RESP) returns REJECT → send REJECTED
1940 <emphasis>WaitingForAuth</emphasis>
1948 Receive BEGIN → terminate auth conversation,
1955 Receive CANCEL → send REJECTED [mechs], goto
1956 <emphasis>WaitingForAuth</emphasis>
1962 Receive ERROR → send REJECTED [mechs], goto
1963 <emphasis>WaitingForAuth</emphasis>
1969 Receive anything else → send ERROR, goto
1970 <emphasis>WaitingForData</emphasis>
1978 <title><emphasis>WaitingForBegin</emphasis></title>
1983 Receive BEGIN → terminate auth conversation,
1984 client authenticated
1990 Receive CANCEL → send REJECTED [mechs], goto
1991 <emphasis>WaitingForAuth</emphasis>
1997 Receive ERROR → send REJECTED [mechs], goto
1998 <emphasis>WaitingForAuth</emphasis>
2004 Receive anything else → send ERROR, goto
2005 <emphasis>WaitingForBegin</emphasis>
2015 <sect2 id="auth-mechanisms">
2016 <title>Authentication mechanisms</title>
2018 This section describes some new authentication mechanisms.
2019 D-BUS also allows any standard SASL mechanism of course.
2021 <sect3 id="auth-mechanisms-sha">
2022 <title>DBUS_COOKIE_SHA1</title>
2024 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
2025 has the ability to read a private file owned by the user being
2026 authenticated. If the client can prove that it has access to a secret
2027 cookie stored in this file, then the client is authenticated.
2028 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
2032 Authentication proceeds as follows:
2036 The client sends the username it would like to authenticate
2042 The server sends the name of its "cookie context" (see below); a
2043 space character; the integer ID of the secret cookie the client
2044 must demonstrate knowledge of; a space character; then a
2045 hex-encoded randomly-generated challenge string.
2050 The client locates the cookie, and generates its own hex-encoded
2051 randomly-generated challenge string. The client then
2052 concatentates the server's hex-encoded challenge, a ":"
2053 character, its own hex-encoded challenge, another ":" character,
2054 and the hex-encoded cookie. It computes the SHA-1 hash of this
2055 composite string. It sends back to the server the client's
2056 hex-encoded challenge string, a space character, and the SHA-1
2062 The server generates the same concatenated string used by the
2063 client and computes its SHA-1 hash. It compares the hash with
2064 the hash received from the client; if the two hashes match, the
2065 client is authenticated.
2071 Each server has a "cookie context," which is a name that identifies a
2072 set of cookies that apply to that server. A sample context might be
2073 "org_freedesktop_session_bus". Context names must be valid ASCII,
2074 nonzero length, and may not contain the characters slash ("/"),
2075 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
2076 tab ("\t"), or period ("."). There is a default context,
2077 "org_freedesktop_general" that's used by servers that do not specify
2081 Cookies are stored in a user's home directory, in the directory
2082 <filename>~/.dbus-keyrings/</filename>. This directory must
2083 not be readable or writable by other users. If it is,
2084 clients and servers must ignore it. The directory
2085 contains cookie files named after the cookie context.
2088 A cookie file contains one cookie per line. Each line
2089 has three space-separated fields:
2093 The cookie ID number, which must be a non-negative integer and
2094 may not be used twice in the same file.
2099 The cookie's creation time, in UNIX seconds-since-the-epoch
2105 The cookie itself, a hex-encoded random block of bytes. The cookie
2106 may be of any length, though obviously security increases
2107 as the length increases.
2113 Only server processes modify the cookie file.
2114 They must do so with this procedure:
2118 Create a lockfile name by appending ".lock" to the name of the
2119 cookie file. The server should attempt to create this file
2120 using <literal>O_CREAT | O_EXCL</literal>. If file creation
2121 fails, the lock fails. Servers should retry for a reasonable
2122 period of time, then they may choose to delete an existing lock
2123 to keep users from having to manually delete a stale
2124 lock. <footnote><para>Lockfiles are used instead of real file
2125 locking <literal>fcntl()</literal> because real locking
2126 implementations are still flaky on network
2127 filesystems.</para></footnote>
2132 Once the lockfile has been created, the server loads the cookie
2133 file. It should then delete any cookies that are old (the
2134 timeout can be fairly short), or more than a reasonable
2135 time in the future (so that cookies never accidentally
2136 become permanent, if the clock was set far into the future
2137 at some point). If no recent keys remain, the
2138 server may generate a new key.
2143 The pruned and possibly added-to cookie file
2144 must be resaved atomically (using a temporary
2145 file which is rename()'d).
2150 The lock must be dropped by deleting the lockfile.
2156 Clients need not lock the file in order to load it,
2157 because servers are required to save the file atomically.
2162 <sect1 id="addresses">
2163 <title>Server Addresses</title>
2165 Server addresses consist of a transport name followed by a colon, and
2166 then an optional, comma-separated list of keys and values in the form key=value.
2167 Each value is escaped.
2171 <programlisting>unix:path=/tmp/dbus-test</programlisting>
2172 Which is the address to a unix socket with the path /tmp/dbus-test.
2175 Value escaping is similar to URI escaping but simpler.
2179 The set of optionally-escaped bytes is:
2180 <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
2181 <emphasis>byte</emphasis> (note, not character) which is not in the
2182 set of optionally-escaped bytes must be replaced with an ASCII
2183 percent (<literal>%</literal>) and the value of the byte in hex.
2184 The hex value must always be two digits, even if the first digit is
2185 zero. The optionally-escaped bytes may be escaped if desired.
2190 To unescape, append each byte in the value; if a byte is an ASCII
2191 percent (<literal>%</literal>) character then append the following
2192 hex value instead. It is an error if a <literal>%</literal> byte
2193 does not have two hex digits following. It is an error if a
2194 non-optionally-escaped byte is seen unescaped.
2198 The set of optionally-escaped bytes is intended to preserve address
2199 readability and convenience.
2203 A server may specify a key-value pair with the key <literal>guid</literal>
2204 and the value a hex-encoded 16-byte sequence. This globally unique ID must
2205 be created by filling the first 4 bytes with a 32-bit UNIX time since the
2206 epoch, and the remaining 12 bytes with random bytes. If present, the GUID
2207 may be used to distinguish one server from another. A server should use a
2208 different GUID for each address it listens on. For example, if a message
2209 bus daemon offers both UNIX domain socket and TCP connections, but treats
2210 clients the same regardless of how they connect, those two connections are
2211 equivalent post-connection but should have distinct GUIDs to distinguish
2212 the kinds of connection.
2216 The intent of the GUID feature is to allow a client to avoid opening
2217 multiple identical connections to the same server, by allowing the client
2218 to check whether an address corresponds to an already-existing connection.
2219 Comparing two addresses is insufficient, because addresses can be recycled
2220 by distinct servers.
2224 [FIXME clarify if attempting to connect to each is a requirement
2225 or just a suggestion]
2226 When connecting to a server, multiple server addresses can be
2227 separated by a semi-colon. The library will then try to connect
2228 to the first address and if that fails, it'll try to connect to
2229 the next one specified, and so forth. For example
2230 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2233 [FIXME we need to specify in detail each transport and its possible arguments]
2234 Current transports include: unix domain sockets (including
2235 abstract namespace on linux), TCP/IP, and a debug/testing transport using
2236 in-process pipes. Future possible transports include one that
2237 tunnels over X11 protocol.
2241 <sect1 id="naming-conventions">
2242 <title>Naming Conventions</title>
2245 D-BUS namespaces are all lowercase and correspond to reversed domain
2246 names, as with Java. e.g. "org.freedesktop"
2249 Interface, signal, method, and property names are "WindowsStyleCaps", note
2250 that the first letter is capitalized, unlike Java.
2253 Object paths are normally all lowercase with underscores used rather than
2258 <sect1 id="standard-interfaces">
2259 <title>Standard Interfaces</title>
2261 See <xref linkend="message-protocol-types-notation"/> for details on
2262 the notation used in this section. There are some standard interfaces
2263 that may be useful across various D-BUS applications.
2265 <sect2 id="standard-interfaces-peer">
2266 <title><literal>org.freedesktop.DBus.Peer</literal></title>
2268 The <literal>org.freedesktop.DBus.Peer</literal> interface
2271 org.freedesktop.DBus.Peer.Ping ()
2275 On receipt of the <literal>METHOD_CALL</literal> message
2276 <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
2277 nothing other than reply with a <literal>METHOD_RETURN</literal> as
2278 usual. It does not matter which object path a ping is sent to. The
2279 reference implementation should simply handle this method on behalf of
2280 all objects, though it doesn't yet. (The point is, you're really pinging
2281 the peer process, not a specific object.)
2285 <sect2 id="standard-interfaces-introspectable">
2286 <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
2288 This interface has one method:
2290 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
2294 Objects instances may implement
2295 <literal>Introspect</literal> which returns an XML description of
2296 the object, including its interfaces (with signals and methods), objects
2297 below it in the object path tree, and its properties.
2300 <xref linkend="introspection-format"/> describes the format of this XML string.
2303 <sect2 id="standard-interfaces-properties">
2304 <title><literal>org.freedesktop.DBus.Properties</literal></title>
2306 Many native APIs will have a concept of object <firstterm>properties</firstterm>
2307 or <firstterm>attributes</firstterm>. These can be exposed via the
2308 <literal>org.freedesktop.DBus.Properties</literal> interface.
2312 org.freedesktop.DBus.Properties.Get (in STRING interface_name,
2313 in STRING property_name,
2315 org.freedesktop.DBus.Properties.Set (in STRING interface_name,
2316 in STRING property_name,
2321 The available properties and whether they are writable can be determined
2322 by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
2323 see <xref linkend="standard-interfaces-introspectable"/>.
2326 An empty string may be provided for the interface name; in this case,
2327 if there are multiple properties on an object with the same name,
2328 the results are undefined (picking one by according to an arbitrary
2329 deterministic rule, or returning an error, are the reasonable
2335 <sect1 id="introspection-format">
2336 <title>Introspection Data Format</title>
2338 As described in <xref linkend="standard-interfaces-introspectable"/>,
2339 objects may be introspected at runtime, returning an XML string
2340 that describes the object. The same XML format may be used in
2341 other contexts as well, for example as an "IDL" for generating
2342 static language bindings.
2345 Here is an example of introspection data:
2347 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
2348 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
2349 <node name="/org/freedesktop/sample_object">
2350 <interface name="org.freedesktop.SampleInterface">
2351 <method name="Frobate">
2352 <arg name="foo" type="i" direction="in"/>
2353 <arg name="bar" type="s" direction="out"/>
2354 <arg name="baz" type="a{us}" direction="out"/>
2355 <annotation name="org.freedesktop.DBus.Deprecated" value="true"/>
2357 <method name="Bazify">
2358 <arg name="bar" type="(iiu)" direction="in"/>
2359 <arg name="bar" type="v" direction="out"/>
2361 <method name="Mogrify">
2362 <arg name="bar" type="(iiav)" direction="in"/>
2364 <signal name="Changed">
2365 <arg name="new_value" type="b"/>
2367 <property name="Bar" type="y" access="readwrite"/>
2369 <node name="child_of_sample_object"/>
2370 <node name="another_child_of_sample_object"/>
2375 A more formal DTD and spec needs writing, but here are some quick notes.
2379 Only the root <node> element can omit the node name, as it's
2380 known to be the object that was introspected. If the root
2381 <node> does have a name attribute, it must be an absolute
2382 object path. If child <node> have object paths, they must be
2388 If a child <node> has any sub-elements, then they
2389 must represent a complete introspection of the child.
2390 If a child <node> is empty, then it may or may
2391 not have sub-elements; the child must be introspected
2392 in order to find out. The intent is that if an object
2393 knows that its children are "fast" to introspect
2394 it can go ahead and return their information, but
2395 otherwise it can omit it.
2400 The direction element on <arg> may be omitted,
2401 in which case it defaults to "in" for method calls
2402 and "out" for signals. Signals only allow "out"
2403 so while direction may be specified, it's pointless.
2408 The possible directions are "in" and "out",
2409 unlike CORBA there is no "inout"
2414 The possible property access flags are
2415 "readwrite", "read", and "write"
2420 Multiple interfaces can of course be listed for
2426 The "name" attribute on arguments is optional.
2432 Method, interface, property, and signal elements may have
2433 "annotations", which are generic key/value pairs of metadata.
2434 They are similar conceptually to Java's annotations and C# attributes.
2435 Well-known annotations:
2442 <entry>Values (separated by ,)</entry>
2443 <entry>Description</entry>
2448 <entry>org.freedesktop.DBus.Deprecated</entry>
2449 <entry>true,false</entry>
2450 <entry>Whether or not the entity is deprecated; defaults to false</entry>
2453 <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
2454 <entry>(string)</entry>
2455 <entry>The C symbol; may be used for methods and interfaces</entry>
2461 <sect1 id="message-bus">
2462 <title>Message Bus Specification</title>
2463 <sect2 id="message-bus-overview">
2464 <title>Message Bus Overview</title>
2466 The message bus accepts connections from one or more applications.
2467 Once connected, applications can exchange messages with other
2468 applications that are also connected to the bus.
2471 In order to route messages among connections, the message bus keeps a
2472 mapping from names to connections. Each connection has one
2473 unique-for-the-lifetime-of-the-bus name automatically assigned.
2474 Applications may request additional names for a connection. Additional
2475 names are usually "well-known names" such as
2476 "org.freedesktop.TextEditor". When a name is bound to a connection,
2477 that connection is said to <firstterm>own</firstterm> the name.
2480 The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2481 This name routes messages to the bus, allowing applications to make
2482 administrative requests. For example, applications can ask the bus
2483 to assign a name to a connection.
2486 Each name may have <firstterm>queued owners</firstterm>. When an
2487 application requests a name for a connection and the name is already in
2488 use, the bus will optionally add the connection to a queue waiting for
2489 the name. If the current owner of the name disconnects or releases
2490 the name, the next connection in the queue will become the new owner.
2494 This feature causes the right thing to happen if you start two text
2495 editors for example; the first one may request "org.freedesktop.TextEditor",
2496 and the second will be queued as a possible owner of that name. When
2497 the first exits, the second will take over.
2501 Messages may have a <literal>DESTINATION</literal> field (see <xref
2502 linkend="message-protocol-header-fields"/>). If the
2503 <literal>DESTINATION</literal> field is present, it specifies a message
2504 recipient by name. Method calls and replies normally specify this field.
2508 Signals normally do not specify a destination; they are sent to all
2509 applications with <firstterm>message matching rules</firstterm> that
2514 When the message bus receives a method call, if the
2515 <literal>DESTINATION</literal> field is absent, the call is taken to be
2516 a standard one-to-one message and interpreted by the message bus
2517 itself. For example, sending an
2518 <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
2519 <literal>DESTINATION</literal> will cause the message bus itself to
2520 reply to the ping immediately; the message bus will not make this
2521 message visible to other applications.
2525 Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
2526 the ping message were sent with a <literal>DESTINATION</literal> name of
2527 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2528 forwarded, and the Yoyodyne Corporation screensaver application would be
2529 expected to reply to the ping.
2533 <sect2 id="message-bus-names">
2534 <title>Message Bus Names</title>
2536 Each connection has at least one name, assigned at connection time and
2537 returned in response to the
2538 <literal>org.freedesktop.DBus.Hello</literal> method call. This
2539 automatically-assigned name is called the connection's <firstterm>unique
2540 name</firstterm>. Unique names are never reused for two different
2541 connections to the same bus.
2544 Ownership of a unique name is a prerequisite for interaction with
2545 the message bus. It logically follows that the unique name is always
2546 the first name that an application comes to own, and the last
2547 one that it loses ownership of.
2550 Unique connection names must begin with the character ':' (ASCII colon
2551 character); bus names that are not unique names must not begin
2552 with this character. (The bus must reject any attempt by an application
2553 to manually request a name beginning with ':'.) This restriction
2554 categorically prevents "spoofing"; messages sent to a unique name
2555 will always go to the expected connection.
2558 When a connection is closed, all the names that it owns are deleted (or
2559 transferred to the next connection in the queue if any).
2562 A connection can request additional names to be associated with it using
2563 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2564 linkend="message-protocol-names-bus"/> describes the format of a valid
2568 <sect3 id="bus-messages-request-name">
2569 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2573 UINT32 RequestName (in STRING name, in UINT32 flags)
2580 <entry>Argument</entry>
2582 <entry>Description</entry>
2588 <entry>STRING</entry>
2589 <entry>Name to request</entry>
2593 <entry>UINT32</entry>
2594 <entry>Flags</entry>
2604 <entry>Argument</entry>
2606 <entry>Description</entry>
2612 <entry>UINT32</entry>
2613 <entry>Return value</entry>
2620 This method call should be sent to
2621 <literal>org.freedesktop.DBus</literal> and asks the message bus to
2622 assign the given name to the method caller. The flags argument
2623 contains any of the following values logically ORed together:
2629 <entry>Conventional Name</entry>
2630 <entry>Value</entry>
2631 <entry>Description</entry>
2636 <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2639 If the application succeeds in becoming the owner of the specified name,
2640 then ownership of the name can't be transferred until the application
2641 disconnects. If this flag is not set, then any application trying to become
2642 the owner of the name will succeed and the previous owner will be
2643 sent a <literal>org.freedesktop.DBus.NameLost</literal> signal.
2647 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2650 Try to replace the current owner if there is one. If this
2651 flag is not set the application will only become the owner of
2652 the name if there is no current owner.
2659 The return code can be one of the following values:
2665 <entry>Conventional Name</entry>
2666 <entry>Value</entry>
2667 <entry>Description</entry>
2672 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2673 <entry>1</entry> <entry>The caller is now the primary owner of
2674 the name, replacing any previous owner. Either the name had no
2675 owner before, or the caller specified
2676 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2677 specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2680 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2682 <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2685 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2687 <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2690 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2692 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2701 <sect2 id="message-bus-routing">
2702 <title>Message Bus Message Routing</title>
2707 <sect2 id="message-bus-starting-services">
2708 <title>Message Bus Starting Services</title>
2710 The message bus can start applications on behalf of other applications.
2711 In CORBA terms, this would be called <firstterm>activation</firstterm>.
2712 An application that can be started in this way is called a
2713 <firstterm>service</firstterm>.
2716 With D-BUS, starting a service is normally done by name. That is,
2717 applications ask the message bus to start some program that will own a
2718 well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2719 This implies a contract documented along with the name
2720 <literal>org.freedesktop.TextEditor</literal> for which objects
2721 the owner of that name will provide, and what interfaces those
2725 To find an executable corresponding to a particular name, the bus daemon
2726 looks for <firstterm>service description files</firstterm>. Service
2727 description files define a mapping from names to executables. Different
2728 kinds of message bus will look for these files in different places, see
2729 <xref linkend="message-bus-types"/>.
2732 [FIXME the file format should be much better specified than "similar to
2733 .desktop entries" esp. since desktop entries are already
2734 badly-specified. ;-)] Service description files have the ".service" file
2735 extension. The message bus will only load service description files
2736 ending with .service; all other files will be ignored. The file format
2737 is similar to that of <ulink
2738 url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2739 entries</ulink>. All service description files must be in UTF-8
2740 encoding. To ensure that there will be no name collisions, service files
2741 must be namespaced using the same mechanism as messages and service
2745 <title>Example service description file</title>
2747 # Sample service description file
2749 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2750 Exec=/usr/libexec/gconfd-2
2755 When an application asks to start a service by name, the bus daemon tries to
2756 find a service that will own that name. It then tries to spawn the
2757 executable associated with it. If this fails, it will report an
2758 error. [FIXME what happens if two .service files offer the same service;
2759 what kind of error is reported, should we have a way for the client to
2763 The executable launched will have the environment variable
2764 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2765 message bus so it can connect and request the appropriate names.
2768 The executable being launched may want to know whether the message bus
2769 starting it is one of the well-known message buses (see <xref
2770 linkend="message-bus-types"/>). To facilitate this, the bus must also set
2771 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2772 of the well-known buses. The currently-defined values for this variable
2773 are <literal>system</literal> for the systemwide message bus,
2774 and <literal>session</literal> for the per-login-session message
2775 bus. The new executable must still connect to the address given
2776 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2777 resulting connection is to the well-known bus.
2780 [FIXME there should be a timeout somewhere, either specified
2781 in the .service file, by the client, or just a global value
2782 and if the client being activated fails to connect within that
2783 timeout, an error should be sent back.]
2786 <sect3 id="message-bus-starting-services-scope">
2787 <title>Message Bus Service Scope</title>
2789 The "scope" of a service is its "per-", such as per-session,
2790 per-machine, per-home-directory, or per-display. The reference
2791 implementation doesn't yet support starting services in a different
2792 scope from the message bus itself. So e.g. if you start a service
2793 on the session bus its scope is per-session.
2796 We could add an optional scope to a bus name. For example, for
2797 per-(display,session pair), we could have a unique ID for each display
2798 generated automatically at login and set on screen 0 by executing a
2799 special "set display ID" binary. The ID would be stored in a
2800 <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
2801 random bytes. This ID would then be used to scope names.
2802 Starting/locating a service could be done by ID-name pair rather than
2806 Contrast this with a per-display scope. To achieve that, we would
2807 want a single bus spanning all sessions using a given display.
2808 So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
2809 property on screen 0 of the display, pointing to this bus.
2814 <sect2 id="message-bus-types">
2815 <title>Well-known Message Bus Instances</title>
2817 Two standard message bus instances are defined here, along with how
2818 to locate them and where their service files live.
2820 <sect3 id="message-bus-types-login">
2821 <title>Login session message bus</title>
2823 Each time a user logs in, a <firstterm>login session message
2824 bus</firstterm> may be started. All applications in the user's login
2825 session may interact with one another using this message bus.
2828 The address of the login session message bus is given
2829 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2830 variable. If that variable is not set, applications may
2831 also try to read the address from the X Window System root
2832 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2833 The root window property must have type <literal>STRING</literal>.
2834 The environment variable should have precedence over the
2835 root window property.
2838 [FIXME specify location of .service files, probably using
2839 DESKTOP_DIRS etc. from basedir specification, though login session
2840 bus is not really desktop-specific]
2843 <sect3 id="message-bus-types-system">
2844 <title>System message bus</title>
2846 A computer may have a <firstterm>system message bus</firstterm>,
2847 accessible to all applications on the system. This message bus may be
2848 used to broadcast system events, such as adding new hardware devices,
2849 changes in the printer queue, and so forth.
2852 The address of the system message bus is given
2853 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2854 variable. If that variable is not set, applications should try
2855 to connect to the well-known address
2856 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2859 The D-BUS reference implementation actually honors the
2860 <literal>$(localstatedir)</literal> configure option
2861 for this address, on both client and server side.
2866 [FIXME specify location of system bus .service files]
2871 <sect2 id="message-bus-messages">
2872 <title>Message Bus Messages</title>
2874 The special message bus name <literal>org.freedesktop.DBus</literal>
2875 responds to a number of additional messages.
2878 <sect3 id="bus-messages-hello">
2879 <title><literal>org.freedesktop.DBus.Hello</literal></title>
2890 <entry>Argument</entry>
2892 <entry>Description</entry>
2898 <entry>STRING</entry>
2899 <entry>Unique name assigned to the connection</entry>
2906 Before an application is able to send messages to other applications
2907 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2908 to the message bus to obtain a unique name. If an application without
2909 a unique name tries to send a message to another application, or a
2910 message to the message bus itself that isn't the
2911 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2912 disconnected from the bus.
2915 There is no corresponding "disconnect" request; if a client wishes to
2916 disconnect from the bus, it simply closes the socket (or other
2917 communication channel).
2920 <sect3 id="bus-messages-list-names">
2921 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2925 ARRAY of STRING ListNames ()
2932 <entry>Argument</entry>
2934 <entry>Description</entry>
2940 <entry>ARRAY of STRING</entry>
2941 <entry>Array of strings where each string is a bus name</entry>
2948 Returns a list of all currently-owned names on the bus.
2951 <sect3 id="bus-messages-name-exists">
2952 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2956 BOOLEAN NameHasOwner (in STRING name)
2963 <entry>Argument</entry>
2965 <entry>Description</entry>
2971 <entry>STRING</entry>
2972 <entry>Name to check</entry>
2982 <entry>Argument</entry>
2984 <entry>Description</entry>
2990 <entry>BOOLEAN</entry>
2991 <entry>Return value, true if the name exists</entry>
2998 Checks if the specified name exists (currently has an owner).
3002 <sect3 id="bus-messages-name-owner-changed">
3003 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
3007 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
3014 <entry>Argument</entry>
3016 <entry>Description</entry>
3022 <entry>STRING</entry>
3023 <entry>Name with a new owner</entry>
3027 <entry>STRING</entry>
3028 <entry>Old owner or empty string if none</entry>
3032 <entry>STRING</entry>
3033 <entry>New owner or empty string if none</entry>
3040 This signal indicates that the owner of a name has changed.
3041 It's also the signal to use to detect the appearance of
3042 new names on the bus.
3045 <sect3 id="bus-messages-name-lost">
3046 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
3050 NameLost (STRING name)
3057 <entry>Argument</entry>
3059 <entry>Description</entry>
3065 <entry>STRING</entry>
3066 <entry>Name which was lost</entry>
3073 This signal is sent to a specific application when it loses
3074 ownership of a name.
3078 <sect3 id="bus-messages-name-acquired">
3079 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
3083 NameAcquired (STRING name)
3090 <entry>Argument</entry>
3092 <entry>Description</entry>
3098 <entry>STRING</entry>
3099 <entry>Name which was acquired</entry>
3106 This signal is sent to a specific application when it gains
3107 ownership of a name.
3111 <sect3 id="bus-messages-start-service-by-name">
3112 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
3116 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
3123 <entry>Argument</entry>
3125 <entry>Description</entry>
3131 <entry>STRING</entry>
3132 <entry>Name of the service to start</entry>
3136 <entry>UINT32</entry>
3137 <entry>Flags (currently not used)</entry>
3147 <entry>Argument</entry>
3149 <entry>Description</entry>
3155 <entry>UINT32</entry>
3156 <entry>Return value</entry>
3161 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
3165 The return value can be one of the following values:
3170 <entry>Identifier</entry>
3171 <entry>Value</entry>
3172 <entry>Description</entry>
3177 <entry>DBUS_START_REPLY_SUCCESS</entry>
3179 <entry>The service was successfully started.</entry>
3182 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
3184 <entry>A connection already owns the given name.</entry>
3193 <sect3 id="bus-messages-get-name-owner">
3194 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
3198 STRING GetNameOwner (in STRING name)
3205 <entry>Argument</entry>
3207 <entry>Description</entry>
3213 <entry>STRING</entry>
3214 <entry>Name to get the owner of</entry>
3224 <entry>Argument</entry>
3226 <entry>Description</entry>
3232 <entry>STRING</entry>
3233 <entry>Return value, a unique connection name</entry>
3238 Returns the unique connection name of the primary owner of the name
3239 given. If the requested name doesn't have an owner, returns a
3240 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
3244 <sect3 id="bus-messages-get-connection-unix-user">
3245 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
3249 UINT32 GetConnectionUnixUser (in STRING connection_name)
3256 <entry>Argument</entry>
3258 <entry>Description</entry>
3264 <entry>STRING</entry>
3265 <entry>Name of the connection to query</entry>
3275 <entry>Argument</entry>
3277 <entry>Description</entry>
3283 <entry>UINT32</entry>
3284 <entry>unix user id</entry>
3289 Returns the unix uid of the process connected to the server. If unable to
3290 determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
3299 <appendix id="implementation-notes">
3300 <title>Implementation notes</title>
3301 <sect1 id="implementation-notes-subsection">
3309 <glossary><title>Glossary</title>
3311 This glossary defines some of the terms used in this specification.
3314 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
3317 The message bus maintains an association between names and
3318 connections. (Normally, there's one connection per application.) A
3319 bus name is simply an identifier used to locate connections. For
3320 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
3321 name might be used to send a message to a screensaver from Yoyodyne
3322 Corporation. An application is said to <firstterm>own</firstterm> a
3323 name if the message bus has associated the application's connection
3324 with the name. Names may also have <firstterm>queued
3325 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
3326 The bus assigns a unique name to each connection,
3327 see <xref linkend="term-unique-name"/>. Other names
3328 can be thought of as "well-known names" and are
3329 used to find applications that offer specific functionality.
3334 <glossentry id="term-message"><glossterm>Message</glossterm>
3337 A message is the atomic unit of communication via the D-BUS
3338 protocol. It consists of a <firstterm>header</firstterm> and a
3339 <firstterm>body</firstterm>; the body is made up of
3340 <firstterm>arguments</firstterm>.
3345 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
3348 The message bus is a special application that forwards
3349 or routes messages between a group of applications
3350 connected to the message bus. It also manages
3351 <firstterm>names</firstterm> used for routing
3357 <glossentry id="term-name"><glossterm>Name</glossterm>
3360 See <xref linkend="term-bus-name"/>. "Name" may
3361 also be used to refer to some of the other names
3362 in D-BUS, such as interface names.
3367 <glossentry id="namespace"><glossterm>Namespace</glossterm>
3370 Used to prevent collisions when defining new interfaces or bus
3371 names. The convention used is the same one Java uses for defining
3372 classes: a reversed domain name.
3377 <glossentry id="term-object"><glossterm>Object</glossterm>
3380 Each application contains <firstterm>objects</firstterm>, which have
3381 <firstterm>interfaces</firstterm> and
3382 <firstterm>methods</firstterm>. Objects are referred to by a name,
3383 called a <firstterm>path</firstterm>.
3388 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
3391 An application talking directly to another application, without going
3392 through a message bus. One-to-one connections may be "peer to peer" or
3393 "client to server." The D-BUS protocol has no concept of client
3394 vs. server after a connection has authenticated; the flow of messages
3395 is symmetrical (full duplex).
3400 <glossentry id="term-path"><glossterm>Path</glossterm>
3403 Object references (object names) in D-BUS are organized into a
3404 filesystem-style hierarchy, so each object is named by a path. As in
3405 LDAP, there's no difference between "files" and "directories"; a path
3406 can refer to an object, while still having child objects below it.
3411 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
3414 Each bus name has a primary owner; messages sent to the name go to the
3415 primary owner. However, certain names also maintain a queue of
3416 secondary owners "waiting in the wings." If the primary owner releases
3417 the name, then the first secondary owner in the queue automatically
3418 becomes the new owner of the name.
3423 <glossentry id="term-service"><glossterm>Service</glossterm>
3426 A service is an executable that can be launched by the bus daemon.
3427 Services normally guarantee some particular features, for example they
3428 may guarantee that they will request a specific name such as
3429 "org.freedesktop.Screensaver", have a singleton object
3430 "/org/freedesktop/Application", and that object will implement the
3431 interface "org.freedesktop.ScreensaverControl".
3436 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
3439 ".service files" tell the bus about service applications that can be
3440 launched (see <xref linkend="term-service"/>). Most importantly they
3441 provide a mapping from bus names to services that will request those
3442 names when they start up.
3447 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
3450 The special name automatically assigned to each connection by the
3451 message bus. This name will never change owner, and will be unique
3452 (never reused during the lifetime of the message bus).
3453 It will begin with a ':' character.