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.9</releaseinfo>
11 <date>17 January 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.
125 <sect1 id="message-protocol">
126 <title>Message Protocol</title>
129 A <firstterm>message</firstterm> consists of a
130 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
131 think of a message as a package, the header is the address, and the body
132 contains the package contents. The message delivery system uses the header
133 information to figure out where to send the message and how to interpret
134 it; the recipient inteprets the body of the message.
138 The body of the message is made up of zero or more
139 <firstterm>arguments</firstterm>, which are typed values, such as an
140 integer or a byte array.
144 Both header and body use the same type system and format for
145 serializing data. Each type of value has a wire format.
146 Converting a value from some other representation into the wire
147 format is called <firstterm>marshaling</firstterm> and converting
148 it back from the wire format is <firstterm>unmarshaling</firstterm>.
151 <sect2 id="message-protocol-signatures">
152 <title>Type Signatures</title>
155 The D-BUS protocol does not include type tags in the marshaled data; a
156 block of marshaled values must have a known <firstterm>type
157 signature</firstterm>. The type signature is made up of <firstterm>type
158 codes</firstterm>. A type code is an ASCII character representing the
159 type of a value. Because ASCII characters are used, the type signature
160 will always form a valid ASCII string. A simple string compare
161 determines whether two type signatures are equivalent.
165 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
166 the ASCII character 'i'. So the signature for a block of values
167 containing a single <literal>INT32</literal> would be:
171 A block of values containing two <literal>INT32</literal> would have this signature:
178 All <firstterm>basic</firstterm> types work like
179 <literal>INT32</literal> in this example. To marshal and unmarshal
180 basic types, you simply read one value from the data
181 block corresponding to each type code in the signature.
182 In addition to basic types, there are three <firstterm>container</firstterm>
183 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, and <literal>VARIANT</literal>.
187 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
188 code does not appear in signatures. Instead, ASCII characters
189 '(' and ')' are used to mark the beginning and end of the struct.
190 So for example, a struct containing two integers would have this
195 Structs can be nested, so for example a struct containing
196 an integer and another struct:
200 The value block storing that struct would contain three integers; the
201 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
206 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
207 but is useful in code that implements the protocol. This type code
208 is specified to allow such code to interoperate in non-protocol contexts.
212 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
213 followed by a <firstterm>single complete type</firstterm>. The single
214 complete type following the array is the type of each array element. So
215 the simple example is:
219 which is an array of 32-bit integers. But an array can be of any type,
220 such as this array-of-struct-with-two-int32-fields:
224 Or this array of array of integer:
231 The phrase <firstterm>single complete type</firstterm> deserves some
232 definition. A single complete type is a basic type code, a variant type code,
233 an array with its element type, or a struct with its fields.
234 So the following signatures are not single complete types:
244 And the following signatures contain multiple complete types:
254 Note however that a single complete type may <emphasis>contain</emphasis>
255 multiple other single complete types.
259 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
260 type <literal>VARIANT</literal> will have the signature of a single complete type as part
261 of the <emphasis>value</emphasis>. This signature will be followed by a
262 marshaled value of that type.
266 The following table summarizes the D-BUS types.
271 <entry>Conventional Name</entry>
273 <entry>Description</entry>
278 <entry><literal>INVALID</literal></entry>
279 <entry>0 (ASCII NUL)</entry>
280 <entry>Not a valid type code, used to terminate signatures</entry>
282 <entry><literal>BYTE</literal></entry>
283 <entry>121 (ASCII 'y')</entry>
284 <entry>8-bit unsigned integer</entry>
286 <entry><literal>BOOLEAN</literal></entry>
287 <entry>98 (ASCII 'b')</entry>
288 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
290 <entry><literal>INT32</literal></entry>
291 <entry>105 (ASCII 'i')</entry>
292 <entry>32-bit signed integer</entry>
294 <entry><literal>UINT32</literal></entry>
295 <entry>117 (ASCII 'u')</entry>
296 <entry>32-bit unsigned integer</entry>
298 <entry><literal>INT64</literal></entry>
299 <entry>120 (ASCII 'x')</entry>
300 <entry>64-bit signed integer</entry>
302 <entry><literal>UINT64</literal></entry>
303 <entry>116 (ASCII 't')</entry>
304 <entry>64-bit unsigned integer</entry>
306 <entry><literal>DOUBLE</literal></entry>
307 <entry>100 (ASCII 'd')</entry>
308 <entry>IEEE 754 double</entry>
310 <entry><literal>STRING</literal></entry>
311 <entry>115 (ASCII 's')</entry>
312 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated.</entry>
314 <entry><literal>OBJECT_PATH</literal></entry>
315 <entry>111 (ASCII 'o')</entry>
316 <entry>Name of an object instance</entry>
318 <entry><literal>SIGNATURE</literal></entry>
319 <entry>103 (ASCII 'g')</entry>
320 <entry>A type signature</entry>
322 <entry><literal>ARRAY</literal></entry>
323 <entry>97 (ASCII 'a')</entry>
326 <entry><literal>STRUCT</literal></entry>
327 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
328 <entry>Struct</entry>
330 <entry><literal>VARIANT</literal></entry>
331 <entry>118 (ASCII 'v') </entry>
332 <entry>Variant type (the type of the value is part of the value itself)</entry>
341 <sect2 id="message-protocol-marshaling">
342 <title>Marshaling (Wire Format)</title>
345 Given a type signature, a block of bytes can be converted into typed
346 values. This section describes the format of the block of bytes. Byte
347 order and alignment issues are handled uniformly for all D-BUS types.
351 A block of bytes has an associated byte order. The byte order
352 has to be discovered in some way; for D-BUS messages, the
353 byte order is part of the message header as described in
354 <xref linkend="message-protocol-messages"/>. For now, assume
355 that the byte order is known to be either little endian or big
360 Each value in a block of bytes is aligned "naturally," for example
361 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
362 8-byte boundary. To properly align a value, <firstterm>alignment
363 padding</firstterm> may be necessary. The alignment padding must always
364 be the minimum required padding to properly align the following value;
365 and it must always be made up of nul bytes. The alignment padding must
366 not be left uninitialized (it can't contain garbage), and more padding
367 than required must not be used.
371 Given all this, the types are marshaled on the wire as follows:
376 <entry>Conventional Name</entry>
377 <entry>Encoding</entry>
378 <entry>Alignment</entry>
383 <entry><literal>INVALID</literal></entry>
384 <entry>Not applicable; cannot be marshaled.</entry>
387 <entry><literal>BYTE</literal></entry>
388 <entry>A single 8-bit byte.</entry>
391 <entry><literal>BOOLEAN</literal></entry>
392 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
395 <entry><literal>INT32</literal></entry>
396 <entry>32-bit signed integer in the message's byte order.</entry>
399 <entry><literal>UINT32</literal></entry>
400 <entry>32-bit unsigned integer in the message's byte order.</entry>
403 <entry><literal>INT64</literal></entry>
404 <entry>64-bit signed integer in the message's byte order.</entry>
407 <entry><literal>UINT64</literal></entry>
408 <entry>64-bit unsigned integer in the message's byte order.</entry>
411 <entry><literal>DOUBLE</literal></entry>
412 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
415 <entry><literal>STRING</literal></entry>
416 <entry>A <literal>UINT32</literal> indicating the string's
417 length in bytes excluding its terminating nul, followed by
418 string data of the given length, followed by a terminating nul
425 <entry><literal>OBJECT_PATH</literal></entry>
426 <entry>Exactly the same as <literal>STRING</literal> except the
427 content must be a valid object path (see below).
433 <entry><literal>SIGNATURE</literal></entry>
434 <entry>The same as <literal>STRING</literal> except the length is a single
435 byte (thus signatures have a maximum length of 255)
436 and the content must be a valid signature (see below).
442 <entry><literal>ARRAY</literal></entry>
444 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
445 alignment padding to the alignment boundary of the array element type,
446 followed by each array element. The array length is from the
447 end of the alignment padding to the end of the last element,
448 i.e. it does not include the padding after the length,
449 or any padding after the last element.
450 Arrays have a maximum length defined to be 2 to the 26th power or
451 67108864. Implementations must not send or accept arrays exceeding this
458 <entry><literal>STRUCT</literal></entry>
460 A struct must start on an 8-byte boundary regardless of the
461 type of the struct fields. The struct value consists of each
462 field marshaled in sequence starting from that 8-byte
469 <entry><literal>VARIANT</literal></entry>
471 A variant type has a marshaled <literal>SIGNATURE</literal>
472 followed by a marshaled value with the type
473 given in the signature.
474 Unlike a message signature, the variant signature
475 can contain only a single complete type.
476 So "i" is OK, "ii" is not.
479 1 (alignment of the signature)
487 <sect3 id="message-protocol-marshaling-object-path">
488 <title>Valid Object Paths</title>
491 An object path is a name used to refer to an object instance.
492 Conceptually, each participant in a D-BUS message exchange may have
493 any number of object instances (think of C++ or Java objects) and each
494 such instance will have a path. Like a filesystem, the object
495 instances in an application form a hierarchical tree.
499 The following rules define a valid object path. Implementations must
500 not send or accept messages with invalid object paths.
504 The path may be of any length.
509 The path must begin with an ASCII '/' (integer 47) character,
510 and must consist of elements separated by slash characters.
515 Each element must only contain the ASCII characters
521 No element may be the empty string.
526 Multiple '/' characters cannot occur in sequence.
531 A trailing '/' character is not allowed unless the
532 path is the root path (a single '/' character).
541 <sect3 id="message-protocol-marshaling-signature">
542 <title>Valid Signatures</title>
544 An implementation must not send or accept invalid signatures.
545 Valid signatures will conform to the following rules:
549 The signature ends with a nul byte.
554 The signature is a list of single complete types.
555 Arrays must have element types, and structs must
556 have both open and close parentheses.
561 Only type codes and open and close parentheses are
562 allowed in the signature. The <literal>STRUCT</literal> type code
563 is not allowed in signatures, because parentheses
569 The maximum depth of container type nesting is 32 array type
570 codes and 32 open parentheses. This implies that the maximum
571 total depth of recursion is 64, for an "array of array of array
572 of ... struct of struct of struct of ..." where there are 32
578 The maximum length of a signature is 255.
583 Signatures must be nul-terminated.
592 <sect2 id="message-protocol-messages">
593 <title>Message Format</title>
596 A message consists of a header and a body. The header is a block of
597 values with a fixed signature and meaning. The body is a separate block
598 of values, with a signature specified in the header.
602 The length of the header must be a multiple of 8, allowing the body to
603 begin on an 8-byte boundary when storing the entire message in a single
604 buffer. If the header does not naturally end on an 8-byte boundary
605 up to 7 bytes of nul-initialized alignment padding must be added.
609 The message body need not end on an 8-byte boundary.
613 The maximum length of a message, including header, header alignment padding,
614 and body is 2 to the 27th power or 134217728. Implementations must not
615 send or accept messages exceeding this size.
619 The signature of the header is:
623 Written out more readably, this is:
625 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
630 These values have the following meanings:
636 <entry>Description</entry>
641 <entry>1st <literal>BYTE</literal></entry>
642 <entry>Endianness flag; ASCII 'l' for little-endian
643 or ASCII 'B' for big-endian. Both header and body are
644 in this endianness.</entry>
647 <entry>2nd <literal>BYTE</literal></entry>
648 <entry><firstterm>Message type</firstterm>. Unknown types MUST be ignored.
649 Currently-defined types are described below.
653 <entry>3rd <literal>BYTE</literal></entry>
654 <entry>Bitwise OR of flags. Unknown flags
655 MUST be ignored. Currently-defined flags are described below.
659 <entry>4th <literal>BYTE</literal></entry>
660 <entry>Major protocol version of the sending application. If
661 the major protocol version of the receiving application does not
662 match, the applications will not be able to communicate and the
663 D-BUS connection MUST be disconnected. The major protocol
664 version for this version of the specification is 0.
665 FIXME this field is stupid and pointless to put in
670 <entry>1st <literal>UINT32</literal></entry>
671 <entry>Length in bytes of the message body, starting
672 from the end of the header. The header ends after
673 its alignment padding to an 8-boundary.
677 <entry>2nd <literal>UINT32</literal></entry>
678 <entry>The serial of this message, used as a cookie
679 by the sender to identify the reply corresponding
684 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
685 <entry>An array of zero or more <firstterm>header
686 fields</firstterm> where the byte is the field code, and the
687 variant is the field value. The message type determines
688 which fields are required.
696 <firstterm>Message types</firstterm> that can appear in the second byte
702 <entry>Conventional name</entry>
703 <entry>Decimal value</entry>
704 <entry>Description</entry>
709 <entry><literal>INVALID</literal></entry>
711 <entry>This is an invalid type, if seen in a message
712 the connection should be dropped immediately.</entry>
715 <entry><literal>METHOD_CALL</literal></entry>
717 <entry>Method call.</entry>
720 <entry><literal>METHOD_RETURN</literal></entry>
722 <entry>Method reply with returned data.</entry>
725 <entry><literal>ERROR</literal></entry>
727 <entry>Error reply. If the first argument exists and is a
728 string, it is an error message.</entry>
731 <entry><literal>SIGNAL</literal></entry>
733 <entry>Signal emission.</entry>
740 Flags that can appear in the third byte of the header:
745 <entry>Conventional name</entry>
746 <entry>Hex value</entry>
747 <entry>Description</entry>
752 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
754 <entry>This message does not expect method return replies or
755 error replies; the reply can be omitted as an
756 optimization. However, it is compliant with this specification
757 to return the reply despite this flag.</entry>
760 <entry><literal>NO_AUTO_START</literal></entry>
762 <entry>This message should not automatically launch an owner
763 for the destination name.
771 <sect3 id="message-protocol-header-fields">
772 <title>Header Fields</title>
775 The array at the end of the header contains <firstterm>header
776 fields</firstterm>, where each field is a 1-byte field code followed
777 by a field value. A header must contain the required header fields for
778 its message type, and zero or more of any optional header
779 fields. Future versions of this protocol specification may add new
780 fields. Implementations must ignore fields they do not
781 understand. Implementations must not invent their own header fields;
782 only changes to this specification may introduce new header fields.
786 Again, if an implementation sees a header field code that it does not
787 expect, it MUST ignore that field, as it will be part of a new
788 (but compatible) version of this specification. This also applies
789 to known header fields appearing in unexpected messages, for
790 example if a signal has a reply serial that should be ignored
791 even though it has no meaning as of this version of the spec.
795 However, implementations must not send or accept known header fields
796 with the wrong type stored in the field value. So for example
797 a message with an <literal>INTERFACE</literal> field of type <literal>UINT32</literal> would be considered
802 Here are the currently-defined header fields:
807 <entry>Conventional Name</entry>
808 <entry>Decimal Code</entry>
810 <entry>Required In</entry>
811 <entry>Description</entry>
816 <entry><literal>INVALID</literal></entry>
819 <entry>not allowed</entry>
820 <entry>Not a valid field name (error if it appears in a message)</entry>
823 <entry><literal>PATH</literal></entry>
825 <entry><literal>OBJECT_PATH</literal></entry>
826 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
827 <entry>The object to send a call to,
828 or the object a signal is emitted from.
832 <entry><literal>INTERFACE</literal></entry>
834 <entry><literal>STRING</literal></entry>
835 <entry><literal>SIGNAL</literal></entry>
837 The interface to invoke a method call on, or
838 that a signal is emitted from. Optional for
839 method calls, required for signals.
843 <entry><literal>MEMBER</literal></entry>
845 <entry><literal>STRING</literal></entry>
846 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
847 <entry>The member, either the method name or signal name.</entry>
850 <entry><literal>ERROR_NAME</literal></entry>
852 <entry><literal>STRING</literal></entry>
853 <entry><literal>ERROR</literal></entry>
854 <entry>The name of the error that occurred, for errors</entry>
857 <entry><literal>REPLY_SERIAL</literal></entry>
859 <entry><literal>UINT32</literal></entry>
860 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
861 <entry>The serial number of the message this message is a reply
862 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
865 <entry><literal>DESTINATION</literal></entry>
867 <entry><literal>STRING</literal></entry>
868 <entry>optional</entry>
869 <entry>The name of the connection this message should be routed to.
870 Only used in combination with the message bus, see
871 <xref linkend="message-bus"/>.</entry>
874 <entry><literal>SENDER</literal></entry>
876 <entry><literal>STRING</literal></entry>
877 <entry>optional</entry>
878 <entry>Unique name of the sending connection.
879 The message bus fills in this field so it is reliable; the field is
880 only meaningful in combination with the message bus.</entry>
883 <entry><literal>SIGNATURE</literal></entry>
885 <entry><literal>SIGNATURE</literal></entry>
886 <entry>optional</entry>
887 <entry>The signature of the message body.
888 If omitted, it is assumed to be the
889 empty signature "" (i.e. the body must be 0-length).</entry>
898 <sect2 id="message-protocol-names">
899 <title>Valid Names</title>
901 The various names in D-BUS messages have some restrictions.
904 There is a <firstterm>maximum name length</firstterm>
905 of 255 which applies to bus names, interfaces, and members.
907 <sect3 id="message-protocol-names-interface">
908 <title>Interface names</title>
910 Interfaces have names with type <literal>STRING</literal>, meaning that
911 they must be valid UTF-8. However, there are also some
912 additional restrictions that apply to interface names
915 <listitem><para>They are composed of 1 or more elements separated by
916 a period ('.') character. All elements must contain at least
920 <listitem><para>Each element must only contain the ASCII characters
921 "[A-Z][a-z][0-9]_" and must not begin with a digit.
925 <listitem><para>They must contain at least one '.' (period)
926 character (and thus at least two elements).
929 <listitem><para>They must not begin with a '.' (period) character.</para></listitem>
930 <listitem><para>They must not exceed the maximum name length.</para></listitem>
934 <sect3 id="message-protocol-names-bus">
935 <title>Bus names</title>
937 Bus names have the same restrictions as interface names, with a
938 special exception for unique connection names. A unique name's first
939 element must start with a colon (':') character. After the colon, any
940 characters in "[A-Z][a-z][0-9]_" may appear. Elements after
941 the first must follow the usual rules, except that they may start with
942 a digit. Bus names not starting with a colon have none of these
943 exceptions and follow the same rules as interface names.
946 <sect3 id="message-protocol-names-member">
947 <title>Member names</title>
949 Member (i.e. method or signal) names:
951 <listitem><para>Must only contain the ASCII characters
952 "[A-Z][a-z][0-9]_" and may not begin with a
953 digit.</para></listitem>
954 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
955 <listitem><para>Must not exceed the maximum name length.</para></listitem>
956 <listitem><para>Must be at least 1 byte in length.</para></listitem>
960 <sect3 id="message-protocol-names-error">
961 <title>Error names</title>
963 Error names have the same restrictions as interface names.
968 <sect2 id="message-protocol-types">
969 <title>Message Types</title>
971 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
972 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
973 This section describes these conventions.
975 <sect3 id="message-protocol-types-method">
976 <title>Method Calls</title>
978 Some messages invoke an operation on a remote object. These are
979 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
980 messages map naturally to methods on objects in a typical program.
983 A method call message is expected to have a <literal>MEMBER</literal> header field
984 indicating the name of the method. Optionally, the message has an
985 <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
986 absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
987 a method with the same name, it is undefined which of the two methods
988 will be invoked. Implementations may also choose to return an error in
989 this ambiguous case. However, if a method name is unique
990 implementations must not require an interface field.
993 Method call messages also include a <literal>PATH</literal> field
994 indicating the object to invoke the method on. If the call is passing
995 through a message bus, the message will also have a
996 <literal>DESTINATION</literal> field giving the name of the connection
997 to receive the message.
1000 When an application handles a method call message, it is expected to
1001 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1002 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1003 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1006 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1007 are the return value(s) or "out parameters" of the method call.
1008 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1009 and the call fails; no return value will be provided. It makes
1010 no sense to send multiple replies to the same method call.
1013 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1014 reply is expected, so the caller will know the method
1015 was successfully processed.
1018 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1022 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1023 then as an optimization the application receiving the method
1024 call may choose to omit the reply message (regardless of
1025 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1026 However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1027 flag and reply anyway.
1030 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1031 destination name does not exist then a program to own the destination
1032 name will be started before the message is delivered. The message
1033 will be held until the new program is successfully started or has
1034 failed to start; in case of failure, an error will be returned. This
1035 flag is only relevant in the context of a message bus, it is ignored
1036 during one-to-one communication with no intermediate bus.
1038 <sect4 id="message-protocol-types-method-apis">
1039 <title>Mapping method calls to native APIs</title>
1041 APIs for D-BUS may map method calls to a method call in a specific
1042 programming language, such as C++, or may map a method call written
1043 in an IDL to a D-BUS message.
1046 In APIs of this nature, arguments to a method are often termed "in"
1047 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1048 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1049 "inout" arguments, which are both sent and received, i.e. the caller
1050 passes in a value which is modified. Mapped to D-BUS, an "inout"
1051 argument is equivalent to an "in" argument, followed by an "out"
1052 argument. You can't pass things "by reference" over the wire, so
1053 "inout" is purely an illusion of the in-process API.
1056 Given a method with zero or one return values, followed by zero or more
1057 arguments, where each argument may be "in", "out", or "inout", the
1058 caller constructs a message by appending each "in" or "inout" argument,
1059 in order. "out" arguments are not represented in the caller's message.
1062 The recipient constructs a reply by appending first the return value
1063 if any, then each "out" or "inout" argument, in order.
1064 "in" arguments are not represented in the reply message.
1067 Error replies are normally mapped to exceptions in languages that have
1071 This specification doesn't require anything of native API bindings;
1072 the preceding is only a suggested convention for consistency
1079 <sect3 id="message-protocol-types-signal">
1080 <title>Signal Emission</title>
1082 Unlike method calls, signal emissions have no replies.
1083 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1084 It must have three header fields: <literal>PATH</literal> giving the object
1085 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1086 the fully-qualified name of the signal.
1090 <sect3 id="message-protocol-types-errors">
1091 <title>Errors</title>
1093 Messages of type <literal>ERROR</literal> are most commonly replies
1094 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1095 to any kind of message. The message bus for example
1096 will return an <literal>ERROR</literal> in reply to a signal emission if
1097 the bus does not have enough memory to send the signal.
1100 An <literal>ERROR</literal> may have any arguments, but if the first
1101 argument is a <literal>STRING</literal>, it must be an error message.
1102 The error message may be logged or shown to the user
1107 <sect3 id="message-protocol-types-notation">
1108 <title>Notation in this document</title>
1110 This document uses a simple pseudo-IDL to describe particular method
1111 calls and signals. Here is an example of a method call:
1113 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1114 out UINT32 resultcode)
1116 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1117 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1118 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1119 characters so it's known that the last part of the name in
1120 the "IDL" is the member name.
1123 In C++ that might end up looking like this:
1125 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1126 unsigned int flags);
1128 or equally valid, the return value could be done as an argument:
1130 void org::freedesktop::DBus::StartServiceByName (const char *name,
1132 unsigned int *resultcode);
1134 It's really up to the API designer how they want to make
1135 this look. You could design an API where the namespace wasn't used
1136 in C++, using STL or Qt, using varargs, or whatever you wanted.
1139 Signals are written as follows:
1141 org.freedesktop.DBus.NameLost (STRING name)
1143 Signals don't specify "in" vs. "out" because only
1144 a single direction is possible.
1147 It isn't especially encouraged to use this lame pseudo-IDL in actual
1148 API implementations; you might use the native notation for the
1149 language you're using, or you might use COM or CORBA IDL, for example.
1156 <sect1 id="auth-protocol">
1157 <title>Authentication Protocol</title>
1159 Before the flow of messages begins, two applications must
1160 authenticate. A simple plain-text protocol is used for
1161 authentication; this protocol is a SASL profile, and maps fairly
1162 directly from the SASL specification. The message encoding is
1163 NOT used here, only plain text messages.
1166 In examples, "C:" and "S:" indicate lines sent by the client and
1167 server respectively.
1169 <sect2 id="auth-protocol-overview">
1170 <title>Protocol Overview</title>
1172 The protocol is a line-based protocol, where each line ends with
1173 \r\n. Each line begins with an all-caps ASCII command name containing
1174 only the character range [A-Z], a space, then any arguments for the
1175 command, then the \r\n ending the line. The protocol is
1176 case-sensitive. All bytes must be in the ASCII character set.
1178 Commands from the client to the server are as follows:
1181 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1182 <listitem><para>CANCEL</para></listitem>
1183 <listitem><para>BEGIN</para></listitem>
1184 <listitem><para>DATA <data in hex encoding></para></listitem>
1185 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1188 From server to client are as follows:
1191 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
1192 <listitem><para>OK</para></listitem>
1193 <listitem><para>DATA <data in hex encoding></para></listitem>
1194 <listitem><para>ERROR</para></listitem>
1198 <sect2 id="auth-nul-byte">
1199 <title>Special credentials-passing nul byte</title>
1201 Immediately after connecting to the server, the client must send a
1202 single nul byte. This byte may be accompanied by credentials
1203 information on some operating systems that use sendmsg() with
1204 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1205 sockets. However, the nul byte MUST be sent even on other kinds of
1206 socket, and even on operating systems that do not require a byte to be
1207 sent in order to transmit credentials. The text protocol described in
1208 this document begins after the single nul byte. If the first byte
1209 received from the client is not a nul byte, the server may disconnect
1213 A nul byte in any context other than the initial byte is an error;
1214 the protocol is ASCII-only.
1217 The credentials sent along with the nul byte may be used with the
1218 SASL mechanism EXTERNAL.
1221 <sect2 id="auth-command-auth">
1222 <title>AUTH command</title>
1224 If an AUTH command has no arguments, it is a request to list
1225 available mechanisms. The server SHOULD respond with a REJECTED
1226 command listing the mechanisms it understands.
1229 If an AUTH command specifies a mechanism, and the server supports
1230 said mechanism, the server SHOULD begin exchanging SASL
1231 challenge-response data with the client using DATA commands.
1234 If the server does not support the mechanism given in the AUTH
1235 command, it SHOULD send a REJECTED command listing the mechanisms
1239 If the [initial-response] argument is provided, it is intended for
1240 use with mechanisms that have no initial challenge (or an empty
1241 initial challenge), as if it were the argument to an initial DATA
1242 command. If the selected mechanism has an initial challenge, the
1243 server should reject authentication by sending REJECTED.
1246 If authentication succeeds after exchanging DATA commands,
1247 an OK command should be sent to the client.
1250 The first octet received by the client after the \r\n of the OK
1251 command MUST be the first octet of the authenticated/encrypted
1252 stream of D-BUS messages.
1255 The first octet received by the server after the \r\n of the BEGIN
1256 command from the client MUST be the first octet of the
1257 authenticated/encrypted stream of D-BUS messages.
1260 <sect2 id="auth-command-cancel">
1261 <title>CANCEL Command</title>
1263 At any time up to sending the BEGIN command, the client may send a
1264 CANCEL command. On receiving the CANCEL command, the server MUST
1265 send a REJECTED command and abort the current authentication
1269 <sect2 id="auth-command-data">
1270 <title>DATA Command</title>
1272 The DATA command may come from either client or server, and simply
1273 contains a hex-encoded block of data to be interpreted
1274 according to the SASL mechanism in use.
1277 Some SASL mechanisms support sending an "empty string";
1278 FIXME we need some way to do this.
1281 <sect2 id="auth-command-begin">
1282 <title>BEGIN Command</title>
1284 The BEGIN command acknowledges that the client has received an
1285 OK command from the server, and that the stream of messages
1289 The first octet received by the server after the \r\n of the BEGIN
1290 command from the client MUST be the first octet of the
1291 authenticated/encrypted stream of D-BUS messages.
1294 <sect2 id="auth-command-rejected">
1295 <title>REJECTED Command</title>
1297 The REJECTED command indicates that the current authentication
1298 exchange has failed, and further exchange of DATA is inappropriate.
1299 The client would normally try another mechanism, or try providing
1300 different responses to challenges.
1302 Optionally, the REJECTED command has a space-separated list of
1303 available auth mechanisms as arguments. If a server ever provides
1304 a list of supported mechanisms, it MUST provide the same list
1305 each time it sends a REJECTED message. Clients are free to
1306 ignore all lists received after the first.
1309 <sect2 id="auth-command-ok">
1310 <title>OK Command</title>
1312 The OK command indicates that the client has been authenticated,
1313 and that further communication will be a stream of D-BUS messages
1314 (optionally encrypted, as negotiated) rather than this protocol.
1317 The first octet received by the client after the \r\n of the OK
1318 command MUST be the first octet of the authenticated/encrypted
1319 stream of D-BUS messages.
1322 The client MUST respond to the OK command by sending a BEGIN
1323 command, followed by its stream of messages, or by disconnecting.
1324 The server MUST NOT accept additional commands using this protocol
1325 after the OK command has been sent.
1328 <sect2 id="auth-command-error">
1329 <title>ERROR Command</title>
1331 The ERROR command indicates that either server or client did not
1332 know a command, does not accept the given command in the current
1333 context, or did not understand the arguments to the command. This
1334 allows the protocol to be extended; a client or server can send a
1335 command present or permitted only in new protocol versions, and if
1336 an ERROR is received instead of an appropriate response, fall back
1337 to using some other technique.
1340 If an ERROR is sent, the server or client that sent the
1341 error MUST continue as if the command causing the ERROR had never been
1342 received. However, the the server or client receiving the error
1343 should try something other than whatever caused the error;
1344 if only canceling/rejecting the authentication.
1347 <sect2 id="auth-examples">
1348 <title>Authentication examples</title>
1352 <title>Example of successful magic cookie authentication</title>
1354 (MAGIC_COOKIE is a made up mechanism)
1356 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1362 <title>Example of finding out mechanisms then picking one</title>
1365 S: REJECTED KERBEROS_V4 SKEY
1366 C: AUTH SKEY 7ab83f32ee
1367 S: DATA 8799cabb2ea93e
1368 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1374 <title>Example of client sends unknown command then falls back to regular auth</title>
1378 C: AUTH MAGIC_COOKIE 3736343435313230333039
1384 <title>Example of server doesn't support initial auth mechanism</title>
1386 C: AUTH MAGIC_COOKIE 3736343435313230333039
1387 S: REJECTED KERBEROS_V4 SKEY
1388 C: AUTH SKEY 7ab83f32ee
1389 S: DATA 8799cabb2ea93e
1390 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1396 <title>Example of wrong password or the like followed by successful retry</title>
1398 C: AUTH MAGIC_COOKIE 3736343435313230333039
1399 S: REJECTED KERBEROS_V4 SKEY
1400 C: AUTH SKEY 7ab83f32ee
1401 S: DATA 8799cabb2ea93e
1402 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1404 C: AUTH SKEY 7ab83f32ee
1405 S: DATA 8799cabb2ea93e
1406 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1412 <title>Example of skey cancelled and restarted</title>
1414 C: AUTH MAGIC_COOKIE 3736343435313230333039
1415 S: REJECTED KERBEROS_V4 SKEY
1416 C: AUTH SKEY 7ab83f32ee
1417 S: DATA 8799cabb2ea93e
1420 C: AUTH SKEY 7ab83f32ee
1421 S: DATA 8799cabb2ea93e
1422 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1429 <sect2 id="auth-states">
1430 <title>Authentication state diagrams</title>
1433 This section documents the auth protocol in terms of
1434 a state machine for the client and the server. This is
1435 probably the most robust way to implement the protocol.
1438 <sect3 id="auth-states-client">
1439 <title>Client states</title>
1442 To more precisely describe the interaction between the
1443 protocol state machine and the authentication mechanisms the
1444 following notation is used: MECH(CHALL) means that the
1445 server challenge CHALL was fed to the mechanism MECH, which
1451 CONTINUE(RESP) means continue the auth conversation
1452 and send RESP as the response to the server;
1458 OK(RESP) means that after sending RESP to the server
1459 the client side of the auth conversation is finished
1460 and the server should return "OK";
1466 ERROR means that CHALL was invalid and could not be
1472 Both RESP and CHALL may be empty.
1476 The Client starts by getting an initial response from the
1477 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1478 the mechanism did not provide an initial response. If the
1479 mechanism returns CONTINUE, the client starts in state
1480 <emphasis>WaitingForData</emphasis>, if the mechanism
1481 returns OK the client starts in state
1482 <emphasis>WaitingForOK</emphasis>.
1486 The client should keep track of available mechanisms and
1487 which it mechanisms it has already attempted. This list is
1488 used to decide which AUTH command to send. When the list is
1489 exhausted, the client should give up and close the
1494 <title><emphasis>WaitingForData</emphasis></title>
1502 MECH(CHALL) returns CONTINUE(RESP) → send
1504 <emphasis>WaitingForData</emphasis>
1508 MECH(CHALL) returns OK(RESP) → send DATA
1509 RESP, goto <emphasis>WaitingForOK</emphasis>
1513 MECH(CHALL) returns ERROR → send ERROR
1514 [msg], goto <emphasis>WaitingForData</emphasis>
1522 Receive REJECTED [mechs] →
1523 send AUTH [next mech], goto
1524 WaitingForData or <emphasis>WaitingForOK</emphasis>
1529 Receive ERROR → send
1531 <emphasis>WaitingForReject</emphasis>
1536 Receive OK → send
1537 BEGIN, terminate auth
1538 conversation, authenticated
1543 Receive anything else → send
1545 <emphasis>WaitingForData</emphasis>
1553 <title><emphasis>WaitingForOK</emphasis></title>
1558 Receive OK → send BEGIN, terminate auth
1559 conversation, <emphasis>authenticated</emphasis>
1564 Receive REJECT [mechs] → send AUTH [next mech],
1565 goto <emphasis>WaitingForData</emphasis> or
1566 <emphasis>WaitingForOK</emphasis>
1572 Receive DATA → send CANCEL, goto
1573 <emphasis>WaitingForReject</emphasis>
1579 Receive ERROR → send CANCEL, goto
1580 <emphasis>WaitingForReject</emphasis>
1586 Receive anything else → send ERROR, goto
1587 <emphasis>WaitingForOK</emphasis>
1595 <title><emphasis>WaitingForReject</emphasis></title>
1600 Receive REJECT [mechs] → send AUTH [next mech],
1601 goto <emphasis>WaitingForData</emphasis> or
1602 <emphasis>WaitingForOK</emphasis>
1608 Receive anything else → terminate auth
1609 conversation, disconnect
1618 <sect3 id="auth-states-server">
1619 <title>Server states</title>
1622 For the server MECH(RESP) means that the client response
1623 RESP was fed to the the mechanism MECH, which returns one of
1628 CONTINUE(CHALL) means continue the auth conversation and
1629 send CHALL as the challenge to the client;
1635 OK means that the client has been successfully
1642 REJECT means that the client failed to authenticate or
1643 there was an error in RESP.
1648 The server starts out in state
1649 <emphasis>WaitingForAuth</emphasis>. If the client is
1650 rejected too many times the server must disconnect the
1655 <title><emphasis>WaitingForAuth</emphasis></title>
1661 Receive AUTH → send REJECTED [mechs], goto
1662 <emphasis>WaitingForAuth</emphasis>
1668 Receive AUTH MECH RESP
1672 MECH not valid mechanism → send REJECTED
1674 <emphasis>WaitingForAuth</emphasis>
1678 MECH(RESP) returns CONTINUE(CHALL) → send
1680 <emphasis>WaitingForData</emphasis>
1684 MECH(RESP) returns OK → send OK, goto
1685 <emphasis>WaitingForBegin</emphasis>
1689 MECH(RESP) returns REJECT → send REJECTED
1691 <emphasis>WaitingForAuth</emphasis>
1699 Receive BEGIN → terminate
1700 auth conversation, disconnect
1706 Receive ERROR → send REJECTED [mechs], goto
1707 <emphasis>WaitingForAuth</emphasis>
1713 Receive anything else → send
1715 <emphasis>WaitingForAuth</emphasis>
1724 <title><emphasis>WaitingForData</emphasis></title>
1732 MECH(RESP) returns CONTINUE(CHALL) → send
1734 <emphasis>WaitingForData</emphasis>
1738 MECH(RESP) returns OK → send OK, goto
1739 <emphasis>WaitingForBegin</emphasis>
1743 MECH(RESP) returns REJECT → send REJECTED
1745 <emphasis>WaitingForAuth</emphasis>
1753 Receive BEGIN → terminate auth conversation,
1760 Receive CANCEL → send REJECTED [mechs], goto
1761 <emphasis>WaitingForAuth</emphasis>
1767 Receive ERROR → send REJECTED [mechs], goto
1768 <emphasis>WaitingForAuth</emphasis>
1774 Receive anything else → send ERROR, goto
1775 <emphasis>WaitingForData</emphasis>
1783 <title><emphasis>WaitingForBegin</emphasis></title>
1788 Receive BEGIN → terminate auth conversation,
1789 client authenticated
1795 Receive CANCEL → send REJECTED [mechs], goto
1796 <emphasis>WaitingForAuth</emphasis>
1802 Receive ERROR → send REJECTED [mechs], goto
1803 <emphasis>WaitingForAuth</emphasis>
1809 Receive anything else → send ERROR, goto
1810 <emphasis>WaitingForBegin</emphasis>
1820 <sect2 id="auth-mechanisms">
1821 <title>Authentication mechanisms</title>
1823 This section describes some new authentication mechanisms.
1824 D-BUS also allows any standard SASL mechanism of course.
1826 <sect3 id="auth-mechanisms-sha">
1827 <title>DBUS_COOKIE_SHA1</title>
1829 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
1830 has the ability to read a private file owned by the user being
1831 authenticated. If the client can prove that it has access to a secret
1832 cookie stored in this file, then the client is authenticated.
1833 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
1837 Authentication proceeds as follows:
1841 The client sends the username it would like to authenticate
1847 The server sends the name of its "cookie context" (see below); a
1848 space character; the integer ID of the secret cookie the client
1849 must demonstrate knowledge of; a space character; then a
1850 hex-encoded randomly-generated challenge string.
1855 The client locates the cookie, and generates its own hex-encoded
1856 randomly-generated challenge string. The client then
1857 concatentates the server's hex-encoded challenge, a ":"
1858 character, its own hex-encoded challenge, another ":" character,
1859 and the hex-encoded cookie. It computes the SHA-1 hash of this
1860 composite string. It sends back to the server the client's
1861 hex-encoded challenge string, a space character, and the SHA-1
1867 The server generates the same concatenated string used by the
1868 client and computes its SHA-1 hash. It compares the hash with
1869 the hash received from the client; if the two hashes match, the
1870 client is authenticated.
1876 Each server has a "cookie context," which is a name that identifies a
1877 set of cookies that apply to that server. A sample context might be
1878 "org_freedesktop_session_bus". Context names must be valid ASCII,
1879 nonzero length, and may not contain the characters slash ("/"),
1880 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
1881 tab ("\t"), or period ("."). There is a default context,
1882 "org_freedesktop_global" that's used by servers that do not specify
1886 Cookies are stored in a user's home directory, in the directory
1887 <filename>~/.dbus-keyrings/</filename>. This directory must
1888 not be readable or writable by other users. If it is,
1889 clients and servers must ignore it. The directory
1890 contains cookie files named after the cookie context.
1893 A cookie file contains one cookie per line. Each line
1894 has three space-separated fields:
1898 The cookie ID number, which must be a non-negative integer and
1899 may not be used twice in the same file.
1904 The cookie's creation time, in UNIX seconds-since-the-epoch
1910 The cookie itself, a hex-encoded random block of bytes.
1916 Only server processes modify the cookie file.
1917 They must do so with this procedure:
1921 Create a lockfile name by appending ".lock" to the name of the
1922 cookie file. The server should attempt to create this file
1923 using <literal>O_CREAT | O_EXCL</literal>. If file creation
1924 fails, the lock fails. Servers should retry for a reasonable
1925 period of time, then they may choose to delete an existing lock
1926 to keep users from having to manually delete a stale
1927 lock. <footnote><para>Lockfiles are used instead of real file
1928 locking <literal>fcntl()</literal> because real locking
1929 implementations are still flaky on network
1930 filesystems.</para></footnote>
1935 Once the lockfile has been created, the server loads the cookie
1936 file. It should then delete any cookies that are old (the
1937 timeout can be fairly short), or more than a reasonable
1938 time in the future (so that cookies never accidentally
1939 become permanent, if the clock was set far into the future
1940 at some point). If no recent keys remain, the
1941 server may generate a new key.
1946 The pruned and possibly added-to cookie file
1947 must be resaved atomically (using a temporary
1948 file which is rename()'d).
1953 The lock must be dropped by deleting the lockfile.
1959 Clients need not lock the file in order to load it,
1960 because servers are required to save the file atomically.
1965 <sect1 id="addresses">
1966 <title>Server Addresses</title>
1968 Server addresses consist of a transport name followed by a colon, and
1969 then an optional, comma-separated list of keys and values in the form key=value.
1970 [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
1974 <programlisting>unix:path=/tmp/dbus-test</programlisting>
1975 Which is the address to a unix socket with the path /tmp/dbus-test.
1978 [FIXME clarify if attempting to connect to each is a requirement
1979 or just a suggestion]
1980 When connecting to a server, multiple server addresses can be
1981 separated by a semi-colon. The library will then try to connect
1982 to the first address and if that fails, it'll try to connect to
1983 the next one specified, and so forth. For example
1984 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
1987 [FIXME we need to specify in detail each transport and its possible arguments]
1988 Current transports include: unix domain sockets (including
1989 abstract namespace on linux), TCP/IP, and a debug/testing transport using
1990 in-process pipes. Future possible transports include one that
1991 tunnels over X11 protocol.
1995 <sect1 id="standard-messages">
1996 <title>Standard One-to-One Messages</title>
1998 See <xref linkend="message-protocol-types-notation"/> for details on
1999 the notation used in this section.
2001 <sect2 id="standard-messages-ping">
2002 <title><literal>org.freedesktop.Peer.Ping</literal></title>
2005 org.freedesktop.Peer.Ping ()
2009 On receipt of the <literal>METHOD_CALL</literal>
2010 message <literal>org.freedesktop.Peer.Ping</literal>, an application
2011 should do nothing other than reply with a <literal>METHOD_RETURN</literal> as usual.
2017 <sect1 id="message-bus">
2018 <title>Message Bus Specification</title>
2019 <sect2 id="message-bus-overview">
2020 <title>Message Bus Overview</title>
2022 The message bus accepts connections from one or more applications.
2023 Once connected, applications can exchange messages with other
2024 applications that are also connected to the bus.
2027 In order to route messages among connections, the message bus keeps a
2028 mapping from names to connections. Each connection has one
2029 unique-for-the-lifetime-of-the-bus name automatically assigned.
2030 Applications may request additional names for a connection. Additional
2031 names are usually "well-known names" such as
2032 "org.freedesktop.TextEditor". When a name is bound to a connection,
2033 that connection is said to <firstterm>own</firstterm> the name.
2036 The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2037 This name routes messages to the bus, allowing applications to make
2038 administrative requests. For example, applications can ask the bus
2039 to assign a name to a connection.
2042 Each name may have <firstterm>queued owners</firstterm>. When an
2043 application requests a name for a connection and the name is already in
2044 use, the bus will optionally add the connection to a queue waiting for
2045 the name. If the current owner of the name disconnects or releases
2046 the name, the next connection in the queue will become the new owner.
2050 This feature causes the right thing to happen if you start two text
2051 editors for example; the first one may request "org.freedesktop.TextEditor",
2052 and the second will be queued as a possible owner of that name. When
2053 the first exits, the second will take over.
2057 Messages may have a <literal>DESTINATION</literal> field (see <xref
2058 linkend="message-protocol-header-fields"/>). If the
2059 <literal>DESTINATION</literal> field is present, it specifies a message
2060 recipient by name. Method calls and replies normally specify this field.
2064 Signals normally do not specify a destination; they are sent to all
2065 applications with <firstterm>message matching rules</firstterm> that
2070 When the message bus receives a method call, if the
2071 <literal>DESTINATION</literal> field is absent, the call is taken to be
2072 a standard one-to-one message and interpreted by the message bus
2073 itself. For example, sending an
2074 <literal>org.freedesktop.Peer.Ping</literal> message with no
2075 <literal>DESTINATION</literal> will cause the message bus itself to
2076 reply to the ping immediately; the message bus will not make this
2077 message visible to other applications.
2081 Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
2082 the ping message were sent with a <literal>DESTINATION</literal> name of
2083 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2084 forwarded, and the Yoyodyne Corporation screensaver application would be
2085 expected to reply to the ping.
2089 <sect2 id="message-bus-names">
2090 <title>Message Bus Names</title>
2092 Each connection has at least one name, assigned at connection time and
2093 returned in response to the
2094 <literal>org.freedesktop.DBus.Hello</literal> method call. This
2095 automatically-assigned name is called the connection's <firstterm>unique
2096 name</firstterm>. Unique names are never reused for two different
2097 connections to the same bus.
2100 Ownership of a unique name is a prerequisite for interaction with
2101 the message bus. It logically follows that the unique name is always
2102 the first name that an application comes to own, and the last
2103 one that it loses ownership of.
2106 Unique connection names must begin with the character ':' (ASCII colon
2107 character); bus names that are not unique names must not begin
2108 with this character. (The bus must reject any attempt by an application
2109 to manually request a name beginning with ':'.) This restriction
2110 categorically prevents "spoofing"; messages sent to a unique name
2111 will always go to the expected connection.
2114 When a connection is closed, all the names that it owns are deleted (or
2115 transferred to the next connection in the queue if any).
2118 A connection can request additional names to be associated with it using
2119 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2120 linkend="message-protocol-names-bus"/> describes the format of a valid
2124 <sect3 id="bus-messages-request-name">
2125 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2129 UINT32 RequestName (in STRING name, in UINT32 flags)
2136 <entry>Argument</entry>
2138 <entry>Description</entry>
2144 <entry>STRING</entry>
2145 <entry>Name to request</entry>
2149 <entry>UINT32</entry>
2150 <entry>Flags</entry>
2160 <entry>Argument</entry>
2162 <entry>Description</entry>
2168 <entry>UINT32</entry>
2169 <entry>Return value</entry>
2176 This method call should be sent to
2177 <literal>org.freedesktop.DBus</literal> and asks the message bus to
2178 assign the given name to the method caller. The flags argument
2179 contains any of the following values logically ORed together:
2185 <entry>Conventional Name</entry>
2186 <entry>Value</entry>
2187 <entry>Description</entry>
2192 <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2195 If the application succeeds in becoming the owner of the specified name,
2196 then ownership of the name can't be transferred until the application
2197 disconnects. If this flag is not set, then any application trying to become
2198 the owner of the name will succeed and the previous owner will be
2199 sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
2203 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2206 Try to replace the current owner if there is one. If this
2207 flag is not set the application will only become the owner of
2208 the name if there is no current owner.
2215 The return code can be one of the following values:
2221 <entry>Conventional Name</entry>
2222 <entry>Value</entry>
2223 <entry>Description</entry>
2228 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2229 <entry>1</entry> <entry>The caller is now the primary owner of
2230 the name, replacing any previous owner. Either the name had no
2231 owner before, or the caller specified
2232 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2233 specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2236 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2238 <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>
2241 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2243 <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2246 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2248 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2257 <sect2 id="message-bus-routing">
2258 <title>Message Bus Message Routing</title>
2263 <sect2 id="message-bus-starting-services">
2264 <title>Message Bus Starting Services</title>
2266 The message bus can start applications on behalf of other applications.
2267 In CORBA terms, this would be called <firstterm>activation</firstterm>.
2268 An application that can be started in this way is called a
2269 <firstterm>service</firstterm>.
2272 With D-BUS, starting a service is normally done by name. That is,
2273 applications ask the message bus to start some program that will own a
2274 well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2275 This implies a contract documented along with the name
2276 <literal>org.freedesktop.TextEditor</literal> for which objects
2277 the owner of that name will provide, and what interfaces those
2281 To find an executable corresponding to a particular name, the bus daemon
2282 looks for <firstterm>service description files</firstterm>. Service
2283 description files define a mapping from names to executables. Different
2284 kinds of message bus will look for these files in different places, see
2285 <xref linkend="message-bus-types"/>.
2288 [FIXME the file format should be much better specified than "similar to
2289 .desktop entries" esp. since desktop entries are already
2290 badly-specified. ;-)] Service description files have the ".service" file
2291 extension. The message bus will only load service description files
2292 ending with .service; all other files will be ignored. The file format
2293 is similar to that of <ulink
2294 url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2295 entries</ulink>. All service description files must be in UTF-8
2296 encoding. To ensure that there will be no name collisions, service files
2297 must be namespaced using the same mechanism as messages and service
2301 <title>Example service description file</title>
2303 # Sample service description file
2305 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2306 Exec=/usr/libexec/gconfd-2
2311 When an application asks to start a service by name, the bus daemon tries to
2312 find a service that will own that name. It then tries to spawn the
2313 executable associated with it. If this fails, it will report an
2314 error. [FIXME what happens if two .service files offer the same service;
2315 what kind of error is reported, should we have a way for the client to
2319 The executable launched will have the environment variable
2320 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2321 message bus so it can connect and request the appropriate names.
2324 The executable being launched may want to know whether the message bus
2325 starting it is one of the well-known message buses (see <xref
2326 linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
2327 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2328 of the well-known buses. The currently-defined values for this variable
2329 are <literal>system</literal> for the systemwide message bus,
2330 and <literal>session</literal> for the per-login-session message
2331 bus. The new executable must still connect to the address given
2332 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2333 resulting connection is to the well-known bus.
2336 [FIXME there should be a timeout somewhere, either specified
2337 in the .service file, by the client, or just a global value
2338 and if the client being activated fails to connect within that
2339 timeout, an error should be sent back.]
2343 <sect2 id="message-bus-types">
2344 <title>Well-known Message Bus Instances</title>
2346 Two standard message bus instances are defined here, along with how
2347 to locate them and where their service files live.
2349 <sect3 id="message-bus-types-login">
2350 <title>Login session message bus</title>
2352 Each time a user logs in, a <firstterm>login session message
2353 bus</firstterm> may be started. All applications in the user's login
2354 session may interact with one another using this message bus.
2357 The address of the login session message bus is given
2358 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2359 variable. If that variable is not set, applications may
2360 also try to read the address from the X Window System root
2361 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2362 The root window property must have type <literal>STRING</literal>.
2363 The environment variable should have precedence over the
2364 root window property.
2367 [FIXME specify location of .service files, probably using
2368 DESKTOP_DIRS etc. from basedir specification, though login session
2369 bus is not really desktop-specific]
2372 <sect3 id="message-bus-types-system">
2373 <title>System message bus</title>
2375 A computer may have a <firstterm>system message bus</firstterm>,
2376 accessible to all applications on the system. This message bus may be
2377 used to broadcast system events, such as adding new hardware devices,
2378 changes in the printer queue, and so forth.
2381 The address of the system message bus is given
2382 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2383 variable. If that variable is not set, applications should try
2384 to connect to the well-known address
2385 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2388 The D-BUS reference implementation actually honors the
2389 <literal>$(localstatedir)</literal> configure option
2390 for this address, on both client and server side.
2395 [FIXME specify location of system bus .service files]
2400 <sect2 id="message-bus-messages">
2401 <title>Message Bus Messages</title>
2403 The special message bus name <literal>org.freedesktop.DBus</literal>
2404 responds to a number of additional messages.
2407 <sect3 id="bus-messages-hello">
2408 <title><literal>org.freedesktop.DBus.Hello</literal></title>
2419 <entry>Argument</entry>
2421 <entry>Description</entry>
2427 <entry>STRING</entry>
2428 <entry>Unique name assigned to the connection</entry>
2435 Before an application is able to send messages to other applications
2436 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2437 to the message bus to obtain a unique name. If an application without
2438 a unique name tries to send a message to another application, or a
2439 message to the message bus itself that isn't the
2440 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2441 disconnected from the bus.
2444 There is no corresponding "disconnect" request; if a client wishes to
2445 disconnect from the bus, it simply closes the socket (or other
2446 communication channel).
2449 <sect3 id="bus-messages-list-names">
2450 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2454 ARRAY of STRING ListNames ()
2461 <entry>Argument</entry>
2463 <entry>Description</entry>
2469 <entry>ARRAY of STRING</entry>
2470 <entry>Array of strings where each string is a bus name</entry>
2477 Returns a list of all currently-owned names on the bus.
2480 <sect3 id="bus-messages-name-exists">
2481 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2485 BOOLEAN NameHasOwner (in STRING name)
2492 <entry>Argument</entry>
2494 <entry>Description</entry>
2500 <entry>STRING</entry>
2501 <entry>Name to check</entry>
2511 <entry>Argument</entry>
2513 <entry>Description</entry>
2519 <entry>BOOLEAN</entry>
2520 <entry>Return value, true if the name exists</entry>
2527 Checks if the specified name exists (currently has an owner).
2531 <sect3 id="bus-messages-name-owner-changed">
2532 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
2536 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
2543 <entry>Argument</entry>
2545 <entry>Description</entry>
2551 <entry>STRING</entry>
2552 <entry>Name with a new owner</entry>
2556 <entry>STRING</entry>
2557 <entry>Old owner or empty string if none</entry>
2561 <entry>STRING</entry>
2562 <entry>New owner or empty string if none</entry>
2569 This signal indicates that the owner of a name has changed.
2570 It's also the signal to use to detect the appearance of
2571 new names on the bus.
2574 <sect3 id="bus-messages-name-lost">
2575 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
2579 NameLost (STRING name)
2586 <entry>Argument</entry>
2588 <entry>Description</entry>
2594 <entry>STRING</entry>
2595 <entry>Name which was lost</entry>
2602 This signal is sent to a specific application when it loses
2603 ownership of a name.
2607 <sect3 id="bus-messages-name-acquired">
2608 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
2612 NameAcquired (STRING name)
2619 <entry>Argument</entry>
2621 <entry>Description</entry>
2627 <entry>STRING</entry>
2628 <entry>Name which was acquired</entry>
2635 This signal is sent to a specific application when it gains
2636 ownership of a name.
2640 <sect3 id="bus-messages-start-service-by-name">
2641 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
2645 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
2652 <entry>Argument</entry>
2654 <entry>Description</entry>
2660 <entry>STRING</entry>
2661 <entry>Name of the service to start</entry>
2665 <entry>UINT32</entry>
2666 <entry>Flags (currently not used)</entry>
2676 <entry>Argument</entry>
2678 <entry>Description</entry>
2684 <entry>UINT32</entry>
2685 <entry>Return value</entry>
2690 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
2694 The return value can be one of the following values:
2699 <entry>Identifier</entry>
2700 <entry>Value</entry>
2701 <entry>Description</entry>
2706 <entry>DBUS_START_REPLY_SUCCESS</entry>
2708 <entry>The service was successfully started.</entry>
2711 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
2713 <entry>A connection already owns the given name.</entry>
2722 <sect3 id="bus-messages-get-name-owner">
2723 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
2727 STRING GetNameOwner (in STRING name)
2734 <entry>Argument</entry>
2736 <entry>Description</entry>
2742 <entry>STRING</entry>
2743 <entry>Name to get the owner of</entry>
2753 <entry>Argument</entry>
2755 <entry>Description</entry>
2761 <entry>STRING</entry>
2762 <entry>Return value, a unique connection name</entry>
2767 Returns the unique connection name of the primary owner of the name
2768 given. If the requested name doesn't have an owner, returns a
2769 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
2773 <sect3 id="bus-messages-get-connection-unix-user">
2774 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
2778 UINT32 GetConnectionUnixUser (in STRING connection_name)
2785 <entry>Argument</entry>
2787 <entry>Description</entry>
2793 <entry>STRING</entry>
2794 <entry>Name of the connection to query</entry>
2804 <entry>Argument</entry>
2806 <entry>Description</entry>
2812 <entry>UINT32</entry>
2813 <entry>unix user id</entry>
2818 Returns the unix uid of the process connected to the server. If unable to
2819 determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
2828 <appendix id="implementation-notes">
2829 <title>Implementation notes</title>
2830 <sect1 id="implementation-notes-subsection">
2838 <glossary><title>Glossary</title>
2840 This glossary defines some of the terms used in this specification.
2843 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
2846 The message bus maintains an association between names and
2847 connections. (Normally, there's one connection per application.) A
2848 bus name is simply an identifier used to locate connections. For
2849 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
2850 name might be used to send a message to a screensaver from Yoyodyne
2851 Corporation. An application is said to <firstterm>own</firstterm> a
2852 name if the message bus has associated the application's connection
2853 with the name. Names may also have <firstterm>queued
2854 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
2855 The bus assigns a unique name to each connection,
2856 see <xref linkend="term-unique-name"/>. Other names
2857 can be thought of as "well-known names" and are
2858 used to find applications that offer specific functionality.
2863 <glossentry id="term-message"><glossterm>Message</glossterm>
2866 A message is the atomic unit of communication via the D-BUS
2867 protocol. It consists of a <firstterm>header</firstterm> and a
2868 <firstterm>body</firstterm>; the body is made up of
2869 <firstterm>arguments</firstterm>.
2874 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
2877 The message bus is a special application that forwards
2878 or routes messages between a group of applications
2879 connected to the message bus. It also manages
2880 <firstterm>names</firstterm> used for routing
2886 <glossentry id="term-name"><glossterm>Name</glossterm>
2889 See <xref linkend="term-bus-name"/>. "Name" may
2890 also be used to refer to some of the other names
2891 in D-BUS, such as interface names.
2896 <glossentry id="namespace"><glossterm>Namespace</glossterm>
2899 Used to prevent collisions when defining new interfaces or bus
2900 names. The convention used is the same one Java uses for defining
2901 classes: a reversed domain name.
2906 <glossentry id="term-object"><glossterm>Object</glossterm>
2909 Each application contains <firstterm>objects</firstterm>, which have
2910 <firstterm>interfaces</firstterm> and
2911 <firstterm>methods</firstterm>. Objects are referred to by a name,
2912 called a <firstterm>path</firstterm>.
2917 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
2920 An application talking directly to another application, without going
2921 through a message bus. One-to-one connections may be "peer to peer" or
2922 "client to server." The D-BUS protocol has no concept of client
2923 vs. server after a connection has authenticated; the flow of messages
2924 is symmetrical (full duplex).
2929 <glossentry id="term-path"><glossterm>Path</glossterm>
2932 Object references (object names) in D-BUS are organized into a
2933 filesystem-style hierarchy, so each object is named by a path. As in
2934 LDAP, there's no difference between "files" and "directories"; a path
2935 can refer to an object, while still having child objects below it.
2940 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
2943 Each bus name has a primary owner; messages sent to the name go to the
2944 primary owner. However, certain names also maintain a queue of
2945 secondary owners "waiting in the wings." If the primary owner releases
2946 the name, then the first secondary owner in the queue automatically
2947 becomes the new owner of the name.
2952 <glossentry id="term-service"><glossterm>Service</glossterm>
2955 A service is an executable that can be launched by the bus daemon.
2956 Services normally guarantee some particular features, for example they
2957 may guarantee that they will request a specific name such as
2958 "org.freedesktop.Screensaver", have a singleton object
2959 "/org/freedesktop/Application", and that object will implement the
2960 interface "org.freedesktop.ScreensaverControl".
2965 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
2968 ".service files" tell the bus about service applications that can be
2969 launched (see <xref linkend="term-service"/>). Most importantly they
2970 provide a mapping from bus names to services that will request those
2971 names when they start up.
2976 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
2979 The special name automatically assigned to each connection by the
2980 message bus. This name will never change owner, and will be unique
2981 (never reused during the lifetime of the message bus).
2982 It will begin with a ':' character.