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.10</releaseinfo>
11 <date>28 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 four <firstterm>container</firstterm>
183 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
184 and <literal>DICT_ENTRY</literal>.
188 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
189 code does not appear in signatures. Instead, ASCII characters
190 '(' and ')' are used to mark the beginning and end of the struct.
191 So for example, a struct containing two integers would have this
196 Structs can be nested, so for example a struct containing
197 an integer and another struct:
201 The value block storing that struct would contain three integers; the
202 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
207 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
208 but is useful in code that implements the protocol. This type code
209 is specified to allow such code to interoperate in non-protocol contexts.
213 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
214 followed by a <firstterm>single complete type</firstterm>. The single
215 complete type following the array is the type of each array element. So
216 the simple example is:
220 which is an array of 32-bit integers. But an array can be of any type,
221 such as this array-of-struct-with-two-int32-fields:
225 Or this array of array of integer:
232 The phrase <firstterm>single complete type</firstterm> deserves some
233 definition. A single complete type is a basic type code, a variant type code,
234 an array with its element type, or a struct with its fields.
235 So the following signatures are not single complete types:
245 And the following signatures contain multiple complete types:
255 Note however that a single complete type may <emphasis>contain</emphasis>
256 multiple other single complete types.
260 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
261 type <literal>VARIANT</literal> will have the signature of a single complete type as part
262 of the <emphasis>value</emphasis>. This signature will be followed by a
263 marshaled value of that type.
267 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
268 than parentheses it uses curly braces, and it has more restrictions.
269 The restrictions are: it occurs only as an array element type; and it
270 has exactly two single complete types inside the curly
271 braces. Implementations must not accept dict entries outside of arrays,
272 and must not accept dict entries with zero, one, or more than two
273 fields. A dict entry is always a key-value pair.
277 The first field in the <literal>DICT_ENTRY</literal> is always the key.
278 A message is considered corrupt if the same key occurs twice in the same
279 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
280 implementations are not required to reject dicts with duplicate keys.
284 In most languages, an array of dict entry would be represented as a
285 map, hash table, or dict object.
289 The following table summarizes the D-BUS types.
294 <entry>Conventional Name</entry>
296 <entry>Description</entry>
301 <entry><literal>INVALID</literal></entry>
302 <entry>0 (ASCII NUL)</entry>
303 <entry>Not a valid type code, used to terminate signatures</entry>
305 <entry><literal>BYTE</literal></entry>
306 <entry>121 (ASCII 'y')</entry>
307 <entry>8-bit unsigned integer</entry>
309 <entry><literal>BOOLEAN</literal></entry>
310 <entry>98 (ASCII 'b')</entry>
311 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
313 <entry><literal>INT16</literal></entry>
314 <entry>110 (ASCII 'n')</entry>
315 <entry>16-bit signed integer</entry>
317 <entry><literal>UINT16</literal></entry>
318 <entry>113 (ASCII 'q')</entry>
319 <entry>16-bit unsigned integer</entry>
321 <entry><literal>INT32</literal></entry>
322 <entry>105 (ASCII 'i')</entry>
323 <entry>32-bit signed integer</entry>
325 <entry><literal>UINT32</literal></entry>
326 <entry>117 (ASCII 'u')</entry>
327 <entry>32-bit unsigned integer</entry>
329 <entry><literal>INT64</literal></entry>
330 <entry>120 (ASCII 'x')</entry>
331 <entry>64-bit signed integer</entry>
333 <entry><literal>UINT64</literal></entry>
334 <entry>116 (ASCII 't')</entry>
335 <entry>64-bit unsigned integer</entry>
337 <entry><literal>DOUBLE</literal></entry>
338 <entry>100 (ASCII 'd')</entry>
339 <entry>IEEE 754 double</entry>
341 <entry><literal>STRING</literal></entry>
342 <entry>115 (ASCII 's')</entry>
343 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated.</entry>
345 <entry><literal>OBJECT_PATH</literal></entry>
346 <entry>111 (ASCII 'o')</entry>
347 <entry>Name of an object instance</entry>
349 <entry><literal>SIGNATURE</literal></entry>
350 <entry>103 (ASCII 'g')</entry>
351 <entry>A type signature</entry>
353 <entry><literal>ARRAY</literal></entry>
354 <entry>97 (ASCII 'a')</entry>
357 <entry><literal>STRUCT</literal></entry>
358 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
359 <entry>Struct</entry>
361 <entry><literal>VARIANT</literal></entry>
362 <entry>118 (ASCII 'v') </entry>
363 <entry>Variant type (the type of the value is part of the value itself)</entry>
365 <entry><literal>DICT_ENTRY</literal></entry>
366 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
367 <entry>Entry in a dict or map (array of key-value pairs)</entry>
376 <sect2 id="message-protocol-marshaling">
377 <title>Marshaling (Wire Format)</title>
380 Given a type signature, a block of bytes can be converted into typed
381 values. This section describes the format of the block of bytes. Byte
382 order and alignment issues are handled uniformly for all D-BUS types.
386 A block of bytes has an associated byte order. The byte order
387 has to be discovered in some way; for D-BUS messages, the
388 byte order is part of the message header as described in
389 <xref linkend="message-protocol-messages"/>. For now, assume
390 that the byte order is known to be either little endian or big
395 Each value in a block of bytes is aligned "naturally," for example
396 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
397 8-byte boundary. To properly align a value, <firstterm>alignment
398 padding</firstterm> may be necessary. The alignment padding must always
399 be the minimum required padding to properly align the following value;
400 and it must always be made up of nul bytes. The alignment padding must
401 not be left uninitialized (it can't contain garbage), and more padding
402 than required must not be used.
406 Given all this, the types are marshaled on the wire as follows:
411 <entry>Conventional Name</entry>
412 <entry>Encoding</entry>
413 <entry>Alignment</entry>
418 <entry><literal>INVALID</literal></entry>
419 <entry>Not applicable; cannot be marshaled.</entry>
422 <entry><literal>BYTE</literal></entry>
423 <entry>A single 8-bit byte.</entry>
426 <entry><literal>BOOLEAN</literal></entry>
427 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
430 <entry><literal>INT16</literal></entry>
431 <entry>16-bit signed integer in the message's byte order.</entry>
434 <entry><literal>UINT16</literal></entry>
435 <entry>16-bit unsigned integer in the message's byte order.</entry>
438 <entry><literal>INT32</literal></entry>
439 <entry>32-bit signed integer in the message's byte order.</entry>
442 <entry><literal>UINT32</literal></entry>
443 <entry>32-bit unsigned integer in the message's byte order.</entry>
446 <entry><literal>INT64</literal></entry>
447 <entry>64-bit signed integer in the message's byte order.</entry>
450 <entry><literal>UINT64</literal></entry>
451 <entry>64-bit unsigned integer in the message's byte order.</entry>
454 <entry><literal>DOUBLE</literal></entry>
455 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
458 <entry><literal>STRING</literal></entry>
459 <entry>A <literal>UINT32</literal> indicating the string's
460 length in bytes excluding its terminating nul, followed by
461 string data of the given length, followed by a terminating nul
468 <entry><literal>OBJECT_PATH</literal></entry>
469 <entry>Exactly the same as <literal>STRING</literal> except the
470 content must be a valid object path (see below).
476 <entry><literal>SIGNATURE</literal></entry>
477 <entry>The same as <literal>STRING</literal> except the length is a single
478 byte (thus signatures have a maximum length of 255)
479 and the content must be a valid signature (see below).
485 <entry><literal>ARRAY</literal></entry>
487 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
488 alignment padding to the alignment boundary of the array element type,
489 followed by each array element. The array length is from the
490 end of the alignment padding to the end of the last element,
491 i.e. it does not include the padding after the length,
492 or any padding after the last element.
493 Arrays have a maximum length defined to be 2 to the 26th power or
494 67108864. Implementations must not send or accept arrays exceeding this
501 <entry><literal>STRUCT</literal></entry>
503 A struct must start on an 8-byte boundary regardless of the
504 type of the struct fields. The struct value consists of each
505 field marshaled in sequence starting from that 8-byte
512 <entry><literal>VARIANT</literal></entry>
514 A variant type has a marshaled <literal>SIGNATURE</literal>
515 followed by a marshaled value with the type
516 given in the signature.
517 Unlike a message signature, the variant signature
518 can contain only a single complete type.
519 So "i" is OK, "ii" is not.
522 1 (alignment of the signature)
525 <entry><literal>DICT_ENTRY</literal></entry>
538 <sect3 id="message-protocol-marshaling-object-path">
539 <title>Valid Object Paths</title>
542 An object path is a name used to refer to an object instance.
543 Conceptually, each participant in a D-BUS message exchange may have
544 any number of object instances (think of C++ or Java objects) and each
545 such instance will have a path. Like a filesystem, the object
546 instances in an application form a hierarchical tree.
550 The following rules define a valid object path. Implementations must
551 not send or accept messages with invalid object paths.
555 The path may be of any length.
560 The path must begin with an ASCII '/' (integer 47) character,
561 and must consist of elements separated by slash characters.
566 Each element must only contain the ASCII characters
572 No element may be the empty string.
577 Multiple '/' characters cannot occur in sequence.
582 A trailing '/' character is not allowed unless the
583 path is the root path (a single '/' character).
592 <sect3 id="message-protocol-marshaling-signature">
593 <title>Valid Signatures</title>
595 An implementation must not send or accept invalid signatures.
596 Valid signatures will conform to the following rules:
600 The signature ends with a nul byte.
605 The signature is a list of single complete types.
606 Arrays must have element types, and structs must
607 have both open and close parentheses.
612 Only type codes and open and close parentheses are
613 allowed in the signature. The <literal>STRUCT</literal> type code
614 is not allowed in signatures, because parentheses
620 The maximum depth of container type nesting is 32 array type
621 codes and 32 open parentheses. This implies that the maximum
622 total depth of recursion is 64, for an "array of array of array
623 of ... struct of struct of struct of ..." where there are 32
629 The maximum length of a signature is 255.
634 Signatures must be nul-terminated.
643 <sect2 id="message-protocol-messages">
644 <title>Message Format</title>
647 A message consists of a header and a body. The header is a block of
648 values with a fixed signature and meaning. The body is a separate block
649 of values, with a signature specified in the header.
653 The length of the header must be a multiple of 8, allowing the body to
654 begin on an 8-byte boundary when storing the entire message in a single
655 buffer. If the header does not naturally end on an 8-byte boundary
656 up to 7 bytes of nul-initialized alignment padding must be added.
660 The message body need not end on an 8-byte boundary.
664 The maximum length of a message, including header, header alignment padding,
665 and body is 2 to the 27th power or 134217728. Implementations must not
666 send or accept messages exceeding this size.
670 The signature of the header is:
674 Written out more readably, this is:
676 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
681 These values have the following meanings:
687 <entry>Description</entry>
692 <entry>1st <literal>BYTE</literal></entry>
693 <entry>Endianness flag; ASCII 'l' for little-endian
694 or ASCII 'B' for big-endian. Both header and body are
695 in this endianness.</entry>
698 <entry>2nd <literal>BYTE</literal></entry>
699 <entry><firstterm>Message type</firstterm>. Unknown types MUST be ignored.
700 Currently-defined types are described below.
704 <entry>3rd <literal>BYTE</literal></entry>
705 <entry>Bitwise OR of flags. Unknown flags
706 MUST be ignored. Currently-defined flags are described below.
710 <entry>4th <literal>BYTE</literal></entry>
711 <entry>Major protocol version of the sending application. If
712 the major protocol version of the receiving application does not
713 match, the applications will not be able to communicate and the
714 D-BUS connection MUST be disconnected. The major protocol
715 version for this version of the specification is 0.
716 FIXME this field is stupid and pointless to put in
721 <entry>1st <literal>UINT32</literal></entry>
722 <entry>Length in bytes of the message body, starting
723 from the end of the header. The header ends after
724 its alignment padding to an 8-boundary.
728 <entry>2nd <literal>UINT32</literal></entry>
729 <entry>The serial of this message, used as a cookie
730 by the sender to identify the reply corresponding
735 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
736 <entry>An array of zero or more <firstterm>header
737 fields</firstterm> where the byte is the field code, and the
738 variant is the field value. The message type determines
739 which fields are required.
747 <firstterm>Message types</firstterm> that can appear in the second byte
753 <entry>Conventional name</entry>
754 <entry>Decimal value</entry>
755 <entry>Description</entry>
760 <entry><literal>INVALID</literal></entry>
762 <entry>This is an invalid type, if seen in a message
763 the connection should be dropped immediately.</entry>
766 <entry><literal>METHOD_CALL</literal></entry>
768 <entry>Method call.</entry>
771 <entry><literal>METHOD_RETURN</literal></entry>
773 <entry>Method reply with returned data.</entry>
776 <entry><literal>ERROR</literal></entry>
778 <entry>Error reply. If the first argument exists and is a
779 string, it is an error message.</entry>
782 <entry><literal>SIGNAL</literal></entry>
784 <entry>Signal emission.</entry>
791 Flags that can appear in the third byte of the header:
796 <entry>Conventional name</entry>
797 <entry>Hex value</entry>
798 <entry>Description</entry>
803 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
805 <entry>This message does not expect method return replies or
806 error replies; the reply can be omitted as an
807 optimization. However, it is compliant with this specification
808 to return the reply despite this flag.</entry>
811 <entry><literal>NO_AUTO_START</literal></entry>
813 <entry>This message should not automatically launch an owner
814 for the destination name.
822 <sect3 id="message-protocol-header-fields">
823 <title>Header Fields</title>
826 The array at the end of the header contains <firstterm>header
827 fields</firstterm>, where each field is a 1-byte field code followed
828 by a field value. A header must contain the required header fields for
829 its message type, and zero or more of any optional header
830 fields. Future versions of this protocol specification may add new
831 fields. Implementations must ignore fields they do not
832 understand. Implementations must not invent their own header fields;
833 only changes to this specification may introduce new header fields.
837 Again, if an implementation sees a header field code that it does not
838 expect, it MUST ignore that field, as it will be part of a new
839 (but compatible) version of this specification. This also applies
840 to known header fields appearing in unexpected messages, for
841 example if a signal has a reply serial that should be ignored
842 even though it has no meaning as of this version of the spec.
846 However, implementations must not send or accept known header fields
847 with the wrong type stored in the field value. So for example
848 a message with an <literal>INTERFACE</literal> field of type <literal>UINT32</literal> would be considered
853 Here are the currently-defined header fields:
858 <entry>Conventional Name</entry>
859 <entry>Decimal Code</entry>
861 <entry>Required In</entry>
862 <entry>Description</entry>
867 <entry><literal>INVALID</literal></entry>
870 <entry>not allowed</entry>
871 <entry>Not a valid field name (error if it appears in a message)</entry>
874 <entry><literal>PATH</literal></entry>
876 <entry><literal>OBJECT_PATH</literal></entry>
877 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
878 <entry>The object to send a call to,
879 or the object a signal is emitted from.
883 <entry><literal>INTERFACE</literal></entry>
885 <entry><literal>STRING</literal></entry>
886 <entry><literal>SIGNAL</literal></entry>
888 The interface to invoke a method call on, or
889 that a signal is emitted from. Optional for
890 method calls, required for signals.
894 <entry><literal>MEMBER</literal></entry>
896 <entry><literal>STRING</literal></entry>
897 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
898 <entry>The member, either the method name or signal name.</entry>
901 <entry><literal>ERROR_NAME</literal></entry>
903 <entry><literal>STRING</literal></entry>
904 <entry><literal>ERROR</literal></entry>
905 <entry>The name of the error that occurred, for errors</entry>
908 <entry><literal>REPLY_SERIAL</literal></entry>
910 <entry><literal>UINT32</literal></entry>
911 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
912 <entry>The serial number of the message this message is a reply
913 to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
916 <entry><literal>DESTINATION</literal></entry>
918 <entry><literal>STRING</literal></entry>
919 <entry>optional</entry>
920 <entry>The name of the connection this message should be routed to.
921 Only used in combination with the message bus, see
922 <xref linkend="message-bus"/>.</entry>
925 <entry><literal>SENDER</literal></entry>
927 <entry><literal>STRING</literal></entry>
928 <entry>optional</entry>
929 <entry>Unique name of the sending connection.
930 The message bus fills in this field so it is reliable; the field is
931 only meaningful in combination with the message bus.</entry>
934 <entry><literal>SIGNATURE</literal></entry>
936 <entry><literal>SIGNATURE</literal></entry>
937 <entry>optional</entry>
938 <entry>The signature of the message body.
939 If omitted, it is assumed to be the
940 empty signature "" (i.e. the body must be 0-length).</entry>
949 <sect2 id="message-protocol-names">
950 <title>Valid Names</title>
952 The various names in D-BUS messages have some restrictions.
955 There is a <firstterm>maximum name length</firstterm>
956 of 255 which applies to bus names, interfaces, and members.
958 <sect3 id="message-protocol-names-interface">
959 <title>Interface names</title>
961 Interfaces have names with type <literal>STRING</literal>, meaning that
962 they must be valid UTF-8. However, there are also some
963 additional restrictions that apply to interface names
966 <listitem><para>They are composed of 1 or more elements separated by
967 a period ('.') character. All elements must contain at least
971 <listitem><para>Each element must only contain the ASCII characters
972 "[A-Z][a-z][0-9]_" and must not begin with a digit.
976 <listitem><para>They must contain at least one '.' (period)
977 character (and thus at least two elements).
980 <listitem><para>They must not begin with a '.' (period) character.</para></listitem>
981 <listitem><para>They must not exceed the maximum name length.</para></listitem>
985 <sect3 id="message-protocol-names-bus">
986 <title>Bus names</title>
988 Bus names have the same restrictions as interface names, with a
989 special exception for unique connection names. A unique name's first
990 element must start with a colon (':') character. After the colon, any
991 characters in "[A-Z][a-z][0-9]_" may appear. Elements after
992 the first must follow the usual rules, except that they may start with
993 a digit. Bus names not starting with a colon have none of these
994 exceptions and follow the same rules as interface names.
997 <sect3 id="message-protocol-names-member">
998 <title>Member names</title>
1000 Member (i.e. method or signal) names:
1002 <listitem><para>Must only contain the ASCII characters
1003 "[A-Z][a-z][0-9]_" and may not begin with a
1004 digit.</para></listitem>
1005 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1006 <listitem><para>Must not exceed the maximum name length.</para></listitem>
1007 <listitem><para>Must be at least 1 byte in length.</para></listitem>
1011 <sect3 id="message-protocol-names-error">
1012 <title>Error names</title>
1014 Error names have the same restrictions as interface names.
1019 <sect2 id="message-protocol-types">
1020 <title>Message Types</title>
1022 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1023 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1024 This section describes these conventions.
1026 <sect3 id="message-protocol-types-method">
1027 <title>Method Calls</title>
1029 Some messages invoke an operation on a remote object. These are
1030 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1031 messages map naturally to methods on objects in a typical program.
1034 A method call message is expected to have a <literal>MEMBER</literal> header field
1035 indicating the name of the method. Optionally, the message has an
1036 <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1037 absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1038 a method with the same name, it is undefined which of the two methods
1039 will be invoked. Implementations may also choose to return an error in
1040 this ambiguous case. However, if a method name is unique
1041 implementations must not require an interface field.
1044 Method call messages also include a <literal>PATH</literal> field
1045 indicating the object to invoke the method on. If the call is passing
1046 through a message bus, the message will also have a
1047 <literal>DESTINATION</literal> field giving the name of the connection
1048 to receive the message.
1051 When an application handles a method call message, it is expected to
1052 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1053 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1054 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1057 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1058 are the return value(s) or "out parameters" of the method call.
1059 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1060 and the call fails; no return value will be provided. It makes
1061 no sense to send multiple replies to the same method call.
1064 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1065 reply is expected, so the caller will know the method
1066 was successfully processed.
1069 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1073 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1074 then as an optimization the application receiving the method
1075 call may choose to omit the reply message (regardless of
1076 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1077 However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1078 flag and reply anyway.
1081 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1082 destination name does not exist then a program to own the destination
1083 name will be started before the message is delivered. The message
1084 will be held until the new program is successfully started or has
1085 failed to start; in case of failure, an error will be returned. This
1086 flag is only relevant in the context of a message bus, it is ignored
1087 during one-to-one communication with no intermediate bus.
1089 <sect4 id="message-protocol-types-method-apis">
1090 <title>Mapping method calls to native APIs</title>
1092 APIs for D-BUS may map method calls to a method call in a specific
1093 programming language, such as C++, or may map a method call written
1094 in an IDL to a D-BUS message.
1097 In APIs of this nature, arguments to a method are often termed "in"
1098 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1099 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1100 "inout" arguments, which are both sent and received, i.e. the caller
1101 passes in a value which is modified. Mapped to D-BUS, an "inout"
1102 argument is equivalent to an "in" argument, followed by an "out"
1103 argument. You can't pass things "by reference" over the wire, so
1104 "inout" is purely an illusion of the in-process API.
1107 Given a method with zero or one return values, followed by zero or more
1108 arguments, where each argument may be "in", "out", or "inout", the
1109 caller constructs a message by appending each "in" or "inout" argument,
1110 in order. "out" arguments are not represented in the caller's message.
1113 The recipient constructs a reply by appending first the return value
1114 if any, then each "out" or "inout" argument, in order.
1115 "in" arguments are not represented in the reply message.
1118 Error replies are normally mapped to exceptions in languages that have
1122 In converting from native APIs to D-BUS, it is perhaps nice to
1123 map D-BUS naming conventions ("FooBar") to native conventions
1124 such as "fooBar" or "foo_bar" automatically. This is OK
1125 as long as you can say that the native API is one that
1126 was specifically written for D-BUS. It makes the most sense
1127 when writing object implementations that will be exported
1128 over the bus. Object proxies used to invoke remote D-BUS
1129 objects probably need the ability to call any D-BUS method,
1130 and thus a magic name mapping like this could be a problem.
1133 This specification doesn't require anything of native API bindings;
1134 the preceding is only a suggested convention for consistency
1140 <sect3 id="message-protocol-types-signal">
1141 <title>Signal Emission</title>
1143 Unlike method calls, signal emissions have no replies.
1144 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1145 It must have three header fields: <literal>PATH</literal> giving the object
1146 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1147 the fully-qualified name of the signal.
1151 <sect3 id="message-protocol-types-errors">
1152 <title>Errors</title>
1154 Messages of type <literal>ERROR</literal> are most commonly replies
1155 to a <literal>METHOD_CALL</literal>, but may be returned in reply
1156 to any kind of message. The message bus for example
1157 will return an <literal>ERROR</literal> in reply to a signal emission if
1158 the bus does not have enough memory to send the signal.
1161 An <literal>ERROR</literal> may have any arguments, but if the first
1162 argument is a <literal>STRING</literal>, it must be an error message.
1163 The error message may be logged or shown to the user
1168 <sect3 id="message-protocol-types-notation">
1169 <title>Notation in this document</title>
1171 This document uses a simple pseudo-IDL to describe particular method
1172 calls and signals. Here is an example of a method call:
1174 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1175 out UINT32 resultcode)
1177 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1178 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1179 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1180 characters so it's known that the last part of the name in
1181 the "IDL" is the member name.
1184 In C++ that might end up looking like this:
1186 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
1187 unsigned int flags);
1189 or equally valid, the return value could be done as an argument:
1191 void org::freedesktop::DBus::StartServiceByName (const char *name,
1193 unsigned int *resultcode);
1195 It's really up to the API designer how they want to make
1196 this look. You could design an API where the namespace wasn't used
1197 in C++, using STL or Qt, using varargs, or whatever you wanted.
1200 Signals are written as follows:
1202 org.freedesktop.DBus.NameLost (STRING name)
1204 Signals don't specify "in" vs. "out" because only
1205 a single direction is possible.
1208 It isn't especially encouraged to use this lame pseudo-IDL in actual
1209 API implementations; you might use the native notation for the
1210 language you're using, or you might use COM or CORBA IDL, for example.
1217 <sect1 id="auth-protocol">
1218 <title>Authentication Protocol</title>
1220 Before the flow of messages begins, two applications must
1221 authenticate. A simple plain-text protocol is used for
1222 authentication; this protocol is a SASL profile, and maps fairly
1223 directly from the SASL specification. The message encoding is
1224 NOT used here, only plain text messages.
1227 In examples, "C:" and "S:" indicate lines sent by the client and
1228 server respectively.
1230 <sect2 id="auth-protocol-overview">
1231 <title>Protocol Overview</title>
1233 The protocol is a line-based protocol, where each line ends with
1234 \r\n. Each line begins with an all-caps ASCII command name containing
1235 only the character range [A-Z], a space, then any arguments for the
1236 command, then the \r\n ending the line. The protocol is
1237 case-sensitive. All bytes must be in the ASCII character set.
1239 Commands from the client to the server are as follows:
1242 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1243 <listitem><para>CANCEL</para></listitem>
1244 <listitem><para>BEGIN</para></listitem>
1245 <listitem><para>DATA <data in hex encoding></para></listitem>
1246 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1249 From server to client are as follows:
1252 <listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
1253 <listitem><para>OK</para></listitem>
1254 <listitem><para>DATA <data in hex encoding></para></listitem>
1255 <listitem><para>ERROR</para></listitem>
1259 <sect2 id="auth-nul-byte">
1260 <title>Special credentials-passing nul byte</title>
1262 Immediately after connecting to the server, the client must send a
1263 single nul byte. This byte may be accompanied by credentials
1264 information on some operating systems that use sendmsg() with
1265 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1266 sockets. However, the nul byte MUST be sent even on other kinds of
1267 socket, and even on operating systems that do not require a byte to be
1268 sent in order to transmit credentials. The text protocol described in
1269 this document begins after the single nul byte. If the first byte
1270 received from the client is not a nul byte, the server may disconnect
1274 A nul byte in any context other than the initial byte is an error;
1275 the protocol is ASCII-only.
1278 The credentials sent along with the nul byte may be used with the
1279 SASL mechanism EXTERNAL.
1282 <sect2 id="auth-command-auth">
1283 <title>AUTH command</title>
1285 If an AUTH command has no arguments, it is a request to list
1286 available mechanisms. The server SHOULD respond with a REJECTED
1287 command listing the mechanisms it understands.
1290 If an AUTH command specifies a mechanism, and the server supports
1291 said mechanism, the server SHOULD begin exchanging SASL
1292 challenge-response data with the client using DATA commands.
1295 If the server does not support the mechanism given in the AUTH
1296 command, it SHOULD send a REJECTED command listing the mechanisms
1300 If the [initial-response] argument is provided, it is intended for
1301 use with mechanisms that have no initial challenge (or an empty
1302 initial challenge), as if it were the argument to an initial DATA
1303 command. If the selected mechanism has an initial challenge, the
1304 server should reject authentication by sending REJECTED.
1307 If authentication succeeds after exchanging DATA commands,
1308 an OK command should be sent to the client.
1311 The first octet received by the client after the \r\n of the OK
1312 command MUST be the first octet of the authenticated/encrypted
1313 stream of D-BUS messages.
1316 The first octet received by the server after the \r\n of the BEGIN
1317 command from the client MUST be the first octet of the
1318 authenticated/encrypted stream of D-BUS messages.
1321 <sect2 id="auth-command-cancel">
1322 <title>CANCEL Command</title>
1324 At any time up to sending the BEGIN command, the client may send a
1325 CANCEL command. On receiving the CANCEL command, the server MUST
1326 send a REJECTED command and abort the current authentication
1330 <sect2 id="auth-command-data">
1331 <title>DATA Command</title>
1333 The DATA command may come from either client or server, and simply
1334 contains a hex-encoded block of data to be interpreted
1335 according to the SASL mechanism in use.
1338 Some SASL mechanisms support sending an "empty string";
1339 FIXME we need some way to do this.
1342 <sect2 id="auth-command-begin">
1343 <title>BEGIN Command</title>
1345 The BEGIN command acknowledges that the client has received an
1346 OK command from the server, and that the stream of messages
1350 The first octet received by the server after the \r\n of the BEGIN
1351 command from the client MUST be the first octet of the
1352 authenticated/encrypted stream of D-BUS messages.
1355 <sect2 id="auth-command-rejected">
1356 <title>REJECTED Command</title>
1358 The REJECTED command indicates that the current authentication
1359 exchange has failed, and further exchange of DATA is inappropriate.
1360 The client would normally try another mechanism, or try providing
1361 different responses to challenges.
1363 Optionally, the REJECTED command has a space-separated list of
1364 available auth mechanisms as arguments. If a server ever provides
1365 a list of supported mechanisms, it MUST provide the same list
1366 each time it sends a REJECTED message. Clients are free to
1367 ignore all lists received after the first.
1370 <sect2 id="auth-command-ok">
1371 <title>OK Command</title>
1373 The OK command indicates that the client has been authenticated,
1374 and that further communication will be a stream of D-BUS messages
1375 (optionally encrypted, as negotiated) rather than this protocol.
1378 The first octet received by the client after the \r\n of the OK
1379 command MUST be the first octet of the authenticated/encrypted
1380 stream of D-BUS messages.
1383 The client MUST respond to the OK command by sending a BEGIN
1384 command, followed by its stream of messages, or by disconnecting.
1385 The server MUST NOT accept additional commands using this protocol
1386 after the OK command has been sent.
1389 <sect2 id="auth-command-error">
1390 <title>ERROR Command</title>
1392 The ERROR command indicates that either server or client did not
1393 know a command, does not accept the given command in the current
1394 context, or did not understand the arguments to the command. This
1395 allows the protocol to be extended; a client or server can send a
1396 command present or permitted only in new protocol versions, and if
1397 an ERROR is received instead of an appropriate response, fall back
1398 to using some other technique.
1401 If an ERROR is sent, the server or client that sent the
1402 error MUST continue as if the command causing the ERROR had never been
1403 received. However, the the server or client receiving the error
1404 should try something other than whatever caused the error;
1405 if only canceling/rejecting the authentication.
1408 If the D-BUS protocol changes incompatibly at some future time,
1409 applications implementing the new protocol would probably be able to
1410 check for support of the new protocol by sending a new command and
1411 receiving an ERROR from applications that don't understand it. Thus the
1412 ERROR feature of the auth protocol is an escape hatch that lets us
1413 negotiate extensions or changes to the D-BUS protocol in the future.
1416 <sect2 id="auth-examples">
1417 <title>Authentication examples</title>
1421 <title>Example of successful magic cookie authentication</title>
1423 (MAGIC_COOKIE is a made up mechanism)
1425 C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1431 <title>Example of finding out mechanisms then picking one</title>
1434 S: REJECTED KERBEROS_V4 SKEY
1435 C: AUTH SKEY 7ab83f32ee
1436 S: DATA 8799cabb2ea93e
1437 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1443 <title>Example of client sends unknown command then falls back to regular auth</title>
1447 C: AUTH MAGIC_COOKIE 3736343435313230333039
1453 <title>Example of server doesn't support initial auth mechanism</title>
1455 C: AUTH MAGIC_COOKIE 3736343435313230333039
1456 S: REJECTED KERBEROS_V4 SKEY
1457 C: AUTH SKEY 7ab83f32ee
1458 S: DATA 8799cabb2ea93e
1459 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1465 <title>Example of wrong password or the like followed by successful retry</title>
1467 C: AUTH MAGIC_COOKIE 3736343435313230333039
1468 S: REJECTED KERBEROS_V4 SKEY
1469 C: AUTH SKEY 7ab83f32ee
1470 S: DATA 8799cabb2ea93e
1471 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1473 C: AUTH SKEY 7ab83f32ee
1474 S: DATA 8799cabb2ea93e
1475 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1481 <title>Example of skey cancelled and restarted</title>
1483 C: AUTH MAGIC_COOKIE 3736343435313230333039
1484 S: REJECTED KERBEROS_V4 SKEY
1485 C: AUTH SKEY 7ab83f32ee
1486 S: DATA 8799cabb2ea93e
1489 C: AUTH SKEY 7ab83f32ee
1490 S: DATA 8799cabb2ea93e
1491 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1498 <sect2 id="auth-states">
1499 <title>Authentication state diagrams</title>
1502 This section documents the auth protocol in terms of
1503 a state machine for the client and the server. This is
1504 probably the most robust way to implement the protocol.
1507 <sect3 id="auth-states-client">
1508 <title>Client states</title>
1511 To more precisely describe the interaction between the
1512 protocol state machine and the authentication mechanisms the
1513 following notation is used: MECH(CHALL) means that the
1514 server challenge CHALL was fed to the mechanism MECH, which
1520 CONTINUE(RESP) means continue the auth conversation
1521 and send RESP as the response to the server;
1527 OK(RESP) means that after sending RESP to the server
1528 the client side of the auth conversation is finished
1529 and the server should return "OK";
1535 ERROR means that CHALL was invalid and could not be
1541 Both RESP and CHALL may be empty.
1545 The Client starts by getting an initial response from the
1546 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1547 the mechanism did not provide an initial response. If the
1548 mechanism returns CONTINUE, the client starts in state
1549 <emphasis>WaitingForData</emphasis>, if the mechanism
1550 returns OK the client starts in state
1551 <emphasis>WaitingForOK</emphasis>.
1555 The client should keep track of available mechanisms and
1556 which it mechanisms it has already attempted. This list is
1557 used to decide which AUTH command to send. When the list is
1558 exhausted, the client should give up and close the
1563 <title><emphasis>WaitingForData</emphasis></title>
1571 MECH(CHALL) returns CONTINUE(RESP) → send
1573 <emphasis>WaitingForData</emphasis>
1577 MECH(CHALL) returns OK(RESP) → send DATA
1578 RESP, goto <emphasis>WaitingForOK</emphasis>
1582 MECH(CHALL) returns ERROR → send ERROR
1583 [msg], goto <emphasis>WaitingForData</emphasis>
1591 Receive REJECTED [mechs] →
1592 send AUTH [next mech], goto
1593 WaitingForData or <emphasis>WaitingForOK</emphasis>
1598 Receive ERROR → send
1600 <emphasis>WaitingForReject</emphasis>
1605 Receive OK → send
1606 BEGIN, terminate auth
1607 conversation, authenticated
1612 Receive anything else → send
1614 <emphasis>WaitingForData</emphasis>
1622 <title><emphasis>WaitingForOK</emphasis></title>
1627 Receive OK → send BEGIN, terminate auth
1628 conversation, <emphasis>authenticated</emphasis>
1633 Receive REJECT [mechs] → send AUTH [next mech],
1634 goto <emphasis>WaitingForData</emphasis> or
1635 <emphasis>WaitingForOK</emphasis>
1641 Receive DATA → send CANCEL, goto
1642 <emphasis>WaitingForReject</emphasis>
1648 Receive ERROR → send CANCEL, goto
1649 <emphasis>WaitingForReject</emphasis>
1655 Receive anything else → send ERROR, goto
1656 <emphasis>WaitingForOK</emphasis>
1664 <title><emphasis>WaitingForReject</emphasis></title>
1669 Receive REJECT [mechs] → send AUTH [next mech],
1670 goto <emphasis>WaitingForData</emphasis> or
1671 <emphasis>WaitingForOK</emphasis>
1677 Receive anything else → terminate auth
1678 conversation, disconnect
1687 <sect3 id="auth-states-server">
1688 <title>Server states</title>
1691 For the server MECH(RESP) means that the client response
1692 RESP was fed to the the mechanism MECH, which returns one of
1697 CONTINUE(CHALL) means continue the auth conversation and
1698 send CHALL as the challenge to the client;
1704 OK means that the client has been successfully
1711 REJECT means that the client failed to authenticate or
1712 there was an error in RESP.
1717 The server starts out in state
1718 <emphasis>WaitingForAuth</emphasis>. If the client is
1719 rejected too many times the server must disconnect the
1724 <title><emphasis>WaitingForAuth</emphasis></title>
1730 Receive AUTH → send REJECTED [mechs], goto
1731 <emphasis>WaitingForAuth</emphasis>
1737 Receive AUTH MECH RESP
1741 MECH not valid mechanism → send REJECTED
1743 <emphasis>WaitingForAuth</emphasis>
1747 MECH(RESP) returns CONTINUE(CHALL) → send
1749 <emphasis>WaitingForData</emphasis>
1753 MECH(RESP) returns OK → send OK, goto
1754 <emphasis>WaitingForBegin</emphasis>
1758 MECH(RESP) returns REJECT → send REJECTED
1760 <emphasis>WaitingForAuth</emphasis>
1768 Receive BEGIN → terminate
1769 auth conversation, disconnect
1775 Receive ERROR → send REJECTED [mechs], goto
1776 <emphasis>WaitingForAuth</emphasis>
1782 Receive anything else → send
1784 <emphasis>WaitingForAuth</emphasis>
1793 <title><emphasis>WaitingForData</emphasis></title>
1801 MECH(RESP) returns CONTINUE(CHALL) → send
1803 <emphasis>WaitingForData</emphasis>
1807 MECH(RESP) returns OK → send OK, goto
1808 <emphasis>WaitingForBegin</emphasis>
1812 MECH(RESP) returns REJECT → send REJECTED
1814 <emphasis>WaitingForAuth</emphasis>
1822 Receive BEGIN → terminate auth conversation,
1829 Receive CANCEL → send REJECTED [mechs], goto
1830 <emphasis>WaitingForAuth</emphasis>
1836 Receive ERROR → send REJECTED [mechs], goto
1837 <emphasis>WaitingForAuth</emphasis>
1843 Receive anything else → send ERROR, goto
1844 <emphasis>WaitingForData</emphasis>
1852 <title><emphasis>WaitingForBegin</emphasis></title>
1857 Receive BEGIN → terminate auth conversation,
1858 client authenticated
1864 Receive CANCEL → send REJECTED [mechs], goto
1865 <emphasis>WaitingForAuth</emphasis>
1871 Receive ERROR → send REJECTED [mechs], goto
1872 <emphasis>WaitingForAuth</emphasis>
1878 Receive anything else → send ERROR, goto
1879 <emphasis>WaitingForBegin</emphasis>
1889 <sect2 id="auth-mechanisms">
1890 <title>Authentication mechanisms</title>
1892 This section describes some new authentication mechanisms.
1893 D-BUS also allows any standard SASL mechanism of course.
1895 <sect3 id="auth-mechanisms-sha">
1896 <title>DBUS_COOKIE_SHA1</title>
1898 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
1899 has the ability to read a private file owned by the user being
1900 authenticated. If the client can prove that it has access to a secret
1901 cookie stored in this file, then the client is authenticated.
1902 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
1906 Authentication proceeds as follows:
1910 The client sends the username it would like to authenticate
1916 The server sends the name of its "cookie context" (see below); a
1917 space character; the integer ID of the secret cookie the client
1918 must demonstrate knowledge of; a space character; then a
1919 hex-encoded randomly-generated challenge string.
1924 The client locates the cookie, and generates its own hex-encoded
1925 randomly-generated challenge string. The client then
1926 concatentates the server's hex-encoded challenge, a ":"
1927 character, its own hex-encoded challenge, another ":" character,
1928 and the hex-encoded cookie. It computes the SHA-1 hash of this
1929 composite string. It sends back to the server the client's
1930 hex-encoded challenge string, a space character, and the SHA-1
1936 The server generates the same concatenated string used by the
1937 client and computes its SHA-1 hash. It compares the hash with
1938 the hash received from the client; if the two hashes match, the
1939 client is authenticated.
1945 Each server has a "cookie context," which is a name that identifies a
1946 set of cookies that apply to that server. A sample context might be
1947 "org_freedesktop_session_bus". Context names must be valid ASCII,
1948 nonzero length, and may not contain the characters slash ("/"),
1949 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
1950 tab ("\t"), or period ("."). There is a default context,
1951 "org_freedesktop_general" that's used by servers that do not specify
1955 Cookies are stored in a user's home directory, in the directory
1956 <filename>~/.dbus-keyrings/</filename>. This directory must
1957 not be readable or writable by other users. If it is,
1958 clients and servers must ignore it. The directory
1959 contains cookie files named after the cookie context.
1962 A cookie file contains one cookie per line. Each line
1963 has three space-separated fields:
1967 The cookie ID number, which must be a non-negative integer and
1968 may not be used twice in the same file.
1973 The cookie's creation time, in UNIX seconds-since-the-epoch
1979 The cookie itself, a hex-encoded random block of bytes. The cookie
1980 may be of any length, though obviously security increases
1981 as the length increases.
1987 Only server processes modify the cookie file.
1988 They must do so with this procedure:
1992 Create a lockfile name by appending ".lock" to the name of the
1993 cookie file. The server should attempt to create this file
1994 using <literal>O_CREAT | O_EXCL</literal>. If file creation
1995 fails, the lock fails. Servers should retry for a reasonable
1996 period of time, then they may choose to delete an existing lock
1997 to keep users from having to manually delete a stale
1998 lock. <footnote><para>Lockfiles are used instead of real file
1999 locking <literal>fcntl()</literal> because real locking
2000 implementations are still flaky on network
2001 filesystems.</para></footnote>
2006 Once the lockfile has been created, the server loads the cookie
2007 file. It should then delete any cookies that are old (the
2008 timeout can be fairly short), or more than a reasonable
2009 time in the future (so that cookies never accidentally
2010 become permanent, if the clock was set far into the future
2011 at some point). If no recent keys remain, the
2012 server may generate a new key.
2017 The pruned and possibly added-to cookie file
2018 must be resaved atomically (using a temporary
2019 file which is rename()'d).
2024 The lock must be dropped by deleting the lockfile.
2030 Clients need not lock the file in order to load it,
2031 because servers are required to save the file atomically.
2036 <sect1 id="addresses">
2037 <title>Server Addresses</title>
2039 Server addresses consist of a transport name followed by a colon, and
2040 then an optional, comma-separated list of keys and values in the form key=value.
2041 [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
2045 <programlisting>unix:path=/tmp/dbus-test</programlisting>
2046 Which is the address to a unix socket with the path /tmp/dbus-test.
2049 [FIXME clarify if attempting to connect to each is a requirement
2050 or just a suggestion]
2051 When connecting to a server, multiple server addresses can be
2052 separated by a semi-colon. The library will then try to connect
2053 to the first address and if that fails, it'll try to connect to
2054 the next one specified, and so forth. For example
2055 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2058 [FIXME we need to specify in detail each transport and its possible arguments]
2059 Current transports include: unix domain sockets (including
2060 abstract namespace on linux), TCP/IP, and a debug/testing transport using
2061 in-process pipes. Future possible transports include one that
2062 tunnels over X11 protocol.
2066 <sect1 id="naming-conventions">
2067 <title>Naming Conventions</title>
2070 D-BUS namespaces are all lowercase and correspond to reversed domain
2071 names, as with Java. e.g. "org.freedesktop"
2074 Interface, signal, method, and property names are "WindowsStyleCaps", note
2075 that the first letter is capitalized, unlike Java.
2078 Object paths are normally all lowercase with underscores used rather than
2083 <sect1 id="standard-interfaces">
2084 <title>Standard Interfaces</title>
2086 See <xref linkend="message-protocol-types-notation"/> for details on
2087 the notation used in this section. There are some standard interfaces
2088 that may be useful across various D-BUS applications.
2090 <sect2 id="standard-interfaces-peer">
2091 <title><literal>org.freedesktop.Peer</literal></title>
2093 The <literal>org.freedesktop.Peer</literal> interface
2096 org.freedesktop.Peer.Ping ()
2100 On receipt of the <literal>METHOD_CALL</literal> message
2101 <literal>org.freedesktop.Peer.Ping</literal>, an application should do
2102 nothing other than reply with a <literal>METHOD_RETURN</literal> as
2103 usual. It does not matter which object path a ping is sent to. The
2104 reference implementation should simply handle this method on behalf of
2105 all objects, though it doesn't yet. (The point is, you're really pinging
2106 the peer process, not a specific object.)
2110 <sect2 id="standard-interfaces-introspectable">
2111 <title><literal>org.freedesktop.Introspectable</literal></title>
2113 This interface has one method:
2115 org.freedesktop.Introspectable.Introspect (out STRING xml_data)
2119 Objects instances may implement
2120 <literal>Introspect</literal> which returns an XML description of
2121 the object, including its interfaces (with signals and methods), objects
2122 below it in the object path tree, and its properties.
2125 <xref linkend="introspection-format"/> describes the format of this XML string.
2128 <sect2 id="standard-interfaces-properties">
2129 <title><literal>org.freedesktop.Properties</literal></title>
2131 Many native APIs will have a concept of object <firstterm>properties</firstterm>
2132 or <firstterm>attributes</firstterm>. These can be exposed via the
2133 <literal>org.freedesktop.Properties</literal> interface.
2137 org.freedesktop.Properties.Get (in STRING interface_name,
2138 in STRING property_name,
2140 org.freedesktop.Properties.Set (in STRING interface_name,
2141 in STRING property_name,
2146 The available properties and whether they are writable can be determined
2147 by calling <literal>org.freedesktop.Introspectable.Introspect</literal>,
2148 see <xref linkend="standard-interfaces-introspectable"/>.
2151 An empty string may be provided for the interface name; in this case,
2152 if there are multiple properties on an object with the same name,
2153 the results are undefined (picking one by according to an arbitrary
2154 deterministic rule, or returning an error, are the reasonable
2160 <sect1 id="introspection-format">
2161 <title>Introspection Data Format</title>
2163 As described in <xref linkend="standard-interfaces-introspectable"/>,
2164 objects may be introspected at runtime, returning an XML string
2165 that describes the object. The same XML format may be used in
2166 other contexts as well, for example as an "IDL" for generating
2167 static language bindings.
2170 Here is an example of introspection data:
2172 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
2173 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
2174 <node name="/org/freedesktop/sample_object">
2175 <interface name="org.freedesktop.SampleInterface">
2176 <method name="Frobate">
2177 <arg name="foo" type="int32" direction="in"/>
2178 <arg name="bar" type="string" direction="out"/>
2180 <signal name="Changed">
2181 <arg name="new_value" type="boolean"/>
2183 <property name="Bar" type="byte" access="readwrite"/>
2185 <node name="child_of_sample_object"/>
2186 <node name="another_child_of_sample_object"/>
2191 A more formal DTD and spec needs writing, but here are some quick notes.
2195 Only the root <node> element can omit the node name, as it's
2196 known to be the object that was introspected. If the root
2197 <node> does have a name attribute, it should be an absolute
2198 object path. If child <node> have object paths, they should be
2204 If a child <node> has any sub-elements, then they
2205 must represent a complete introspection of the child.
2206 If a child <node> is empty, then it may or may
2207 not have sub-elements; the child must be introspected
2208 in order to find out. The intent is that if an object
2209 knows that its children are "fast" to introspect
2210 it can go ahead and return their information, but
2211 otherwise it can omit it.
2216 The direction element on <arg> may be omitted,
2217 in which case it defaults to "in" for method calls
2218 and "out" for signals. Signals only allow "out"
2219 so while direction may be specified, it's pointless.
2224 The possible directions are "in" and "out",
2225 unlike CORBA there is no "inout"
2230 The possible property access flags are
2231 "readwrite", "read", and "write"
2236 The current type="uint32" stuff is totally broken,
2237 instead we have to do full signatures.
2238 However, then this format will suck for human readability.
2239 So, some thinking to do here.
2244 Multiple interfaces can of course be listed for
2250 The method, interface, property, and signal elements may have
2251 an attribute deprecated="yes|no". If the attribute is not
2252 present, the default value for an interface is "no", and
2253 the default value for methods, properties, and signals is
2254 the deprecation status of the interface.
2262 <sect1 id="message-bus">
2263 <title>Message Bus Specification</title>
2264 <sect2 id="message-bus-overview">
2265 <title>Message Bus Overview</title>
2267 The message bus accepts connections from one or more applications.
2268 Once connected, applications can exchange messages with other
2269 applications that are also connected to the bus.
2272 In order to route messages among connections, the message bus keeps a
2273 mapping from names to connections. Each connection has one
2274 unique-for-the-lifetime-of-the-bus name automatically assigned.
2275 Applications may request additional names for a connection. Additional
2276 names are usually "well-known names" such as
2277 "org.freedesktop.TextEditor". When a name is bound to a connection,
2278 that connection is said to <firstterm>own</firstterm> the name.
2281 The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2282 This name routes messages to the bus, allowing applications to make
2283 administrative requests. For example, applications can ask the bus
2284 to assign a name to a connection.
2287 Each name may have <firstterm>queued owners</firstterm>. When an
2288 application requests a name for a connection and the name is already in
2289 use, the bus will optionally add the connection to a queue waiting for
2290 the name. If the current owner of the name disconnects or releases
2291 the name, the next connection in the queue will become the new owner.
2295 This feature causes the right thing to happen if you start two text
2296 editors for example; the first one may request "org.freedesktop.TextEditor",
2297 and the second will be queued as a possible owner of that name. When
2298 the first exits, the second will take over.
2302 Messages may have a <literal>DESTINATION</literal> field (see <xref
2303 linkend="message-protocol-header-fields"/>). If the
2304 <literal>DESTINATION</literal> field is present, it specifies a message
2305 recipient by name. Method calls and replies normally specify this field.
2309 Signals normally do not specify a destination; they are sent to all
2310 applications with <firstterm>message matching rules</firstterm> that
2315 When the message bus receives a method call, if the
2316 <literal>DESTINATION</literal> field is absent, the call is taken to be
2317 a standard one-to-one message and interpreted by the message bus
2318 itself. For example, sending an
2319 <literal>org.freedesktop.Peer.Ping</literal> message with no
2320 <literal>DESTINATION</literal> will cause the message bus itself to
2321 reply to the ping immediately; the message bus will not make this
2322 message visible to other applications.
2326 Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
2327 the ping message were sent with a <literal>DESTINATION</literal> name of
2328 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2329 forwarded, and the Yoyodyne Corporation screensaver application would be
2330 expected to reply to the ping.
2334 <sect2 id="message-bus-names">
2335 <title>Message Bus Names</title>
2337 Each connection has at least one name, assigned at connection time and
2338 returned in response to the
2339 <literal>org.freedesktop.DBus.Hello</literal> method call. This
2340 automatically-assigned name is called the connection's <firstterm>unique
2341 name</firstterm>. Unique names are never reused for two different
2342 connections to the same bus.
2345 Ownership of a unique name is a prerequisite for interaction with
2346 the message bus. It logically follows that the unique name is always
2347 the first name that an application comes to own, and the last
2348 one that it loses ownership of.
2351 Unique connection names must begin with the character ':' (ASCII colon
2352 character); bus names that are not unique names must not begin
2353 with this character. (The bus must reject any attempt by an application
2354 to manually request a name beginning with ':'.) This restriction
2355 categorically prevents "spoofing"; messages sent to a unique name
2356 will always go to the expected connection.
2359 When a connection is closed, all the names that it owns are deleted (or
2360 transferred to the next connection in the queue if any).
2363 A connection can request additional names to be associated with it using
2364 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2365 linkend="message-protocol-names-bus"/> describes the format of a valid
2369 <sect3 id="bus-messages-request-name">
2370 <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2374 UINT32 RequestName (in STRING name, in UINT32 flags)
2381 <entry>Argument</entry>
2383 <entry>Description</entry>
2389 <entry>STRING</entry>
2390 <entry>Name to request</entry>
2394 <entry>UINT32</entry>
2395 <entry>Flags</entry>
2405 <entry>Argument</entry>
2407 <entry>Description</entry>
2413 <entry>UINT32</entry>
2414 <entry>Return value</entry>
2421 This method call should be sent to
2422 <literal>org.freedesktop.DBus</literal> and asks the message bus to
2423 assign the given name to the method caller. The flags argument
2424 contains any of the following values logically ORed together:
2430 <entry>Conventional Name</entry>
2431 <entry>Value</entry>
2432 <entry>Description</entry>
2437 <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2440 If the application succeeds in becoming the owner of the specified name,
2441 then ownership of the name can't be transferred until the application
2442 disconnects. If this flag is not set, then any application trying to become
2443 the owner of the name will succeed and the previous owner will be
2444 sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
2448 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2451 Try to replace the current owner if there is one. If this
2452 flag is not set the application will only become the owner of
2453 the name if there is no current owner.
2460 The return code can be one of the following values:
2466 <entry>Conventional Name</entry>
2467 <entry>Value</entry>
2468 <entry>Description</entry>
2473 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2474 <entry>1</entry> <entry>The caller is now the primary owner of
2475 the name, replacing any previous owner. Either the name had no
2476 owner before, or the caller specified
2477 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2478 specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2481 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2483 <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>
2486 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2488 <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2491 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2493 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2502 <sect2 id="message-bus-routing">
2503 <title>Message Bus Message Routing</title>
2508 <sect2 id="message-bus-starting-services">
2509 <title>Message Bus Starting Services</title>
2511 The message bus can start applications on behalf of other applications.
2512 In CORBA terms, this would be called <firstterm>activation</firstterm>.
2513 An application that can be started in this way is called a
2514 <firstterm>service</firstterm>.
2517 With D-BUS, starting a service is normally done by name. That is,
2518 applications ask the message bus to start some program that will own a
2519 well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2520 This implies a contract documented along with the name
2521 <literal>org.freedesktop.TextEditor</literal> for which objects
2522 the owner of that name will provide, and what interfaces those
2526 To find an executable corresponding to a particular name, the bus daemon
2527 looks for <firstterm>service description files</firstterm>. Service
2528 description files define a mapping from names to executables. Different
2529 kinds of message bus will look for these files in different places, see
2530 <xref linkend="message-bus-types"/>.
2533 [FIXME the file format should be much better specified than "similar to
2534 .desktop entries" esp. since desktop entries are already
2535 badly-specified. ;-)] Service description files have the ".service" file
2536 extension. The message bus will only load service description files
2537 ending with .service; all other files will be ignored. The file format
2538 is similar to that of <ulink
2539 url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2540 entries</ulink>. All service description files must be in UTF-8
2541 encoding. To ensure that there will be no name collisions, service files
2542 must be namespaced using the same mechanism as messages and service
2546 <title>Example service description file</title>
2548 # Sample service description file
2550 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2551 Exec=/usr/libexec/gconfd-2
2556 When an application asks to start a service by name, the bus daemon tries to
2557 find a service that will own that name. It then tries to spawn the
2558 executable associated with it. If this fails, it will report an
2559 error. [FIXME what happens if two .service files offer the same service;
2560 what kind of error is reported, should we have a way for the client to
2564 The executable launched will have the environment variable
2565 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2566 message bus so it can connect and request the appropriate names.
2569 The executable being launched may want to know whether the message bus
2570 starting it is one of the well-known message buses (see <xref
2571 linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
2572 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2573 of the well-known buses. The currently-defined values for this variable
2574 are <literal>system</literal> for the systemwide message bus,
2575 and <literal>session</literal> for the per-login-session message
2576 bus. The new executable must still connect to the address given
2577 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2578 resulting connection is to the well-known bus.
2581 [FIXME there should be a timeout somewhere, either specified
2582 in the .service file, by the client, or just a global value
2583 and if the client being activated fails to connect within that
2584 timeout, an error should be sent back.]
2588 <sect2 id="message-bus-types">
2589 <title>Well-known Message Bus Instances</title>
2591 Two standard message bus instances are defined here, along with how
2592 to locate them and where their service files live.
2594 <sect3 id="message-bus-types-login">
2595 <title>Login session message bus</title>
2597 Each time a user logs in, a <firstterm>login session message
2598 bus</firstterm> may be started. All applications in the user's login
2599 session may interact with one another using this message bus.
2602 The address of the login session message bus is given
2603 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2604 variable. If that variable is not set, applications may
2605 also try to read the address from the X Window System root
2606 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2607 The root window property must have type <literal>STRING</literal>.
2608 The environment variable should have precedence over the
2609 root window property.
2612 [FIXME specify location of .service files, probably using
2613 DESKTOP_DIRS etc. from basedir specification, though login session
2614 bus is not really desktop-specific]
2617 <sect3 id="message-bus-types-system">
2618 <title>System message bus</title>
2620 A computer may have a <firstterm>system message bus</firstterm>,
2621 accessible to all applications on the system. This message bus may be
2622 used to broadcast system events, such as adding new hardware devices,
2623 changes in the printer queue, and so forth.
2626 The address of the system message bus is given
2627 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2628 variable. If that variable is not set, applications should try
2629 to connect to the well-known address
2630 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2633 The D-BUS reference implementation actually honors the
2634 <literal>$(localstatedir)</literal> configure option
2635 for this address, on both client and server side.
2640 [FIXME specify location of system bus .service files]
2645 <sect2 id="message-bus-messages">
2646 <title>Message Bus Messages</title>
2648 The special message bus name <literal>org.freedesktop.DBus</literal>
2649 responds to a number of additional messages.
2652 <sect3 id="bus-messages-hello">
2653 <title><literal>org.freedesktop.DBus.Hello</literal></title>
2664 <entry>Argument</entry>
2666 <entry>Description</entry>
2672 <entry>STRING</entry>
2673 <entry>Unique name assigned to the connection</entry>
2680 Before an application is able to send messages to other applications
2681 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2682 to the message bus to obtain a unique name. If an application without
2683 a unique name tries to send a message to another application, or a
2684 message to the message bus itself that isn't the
2685 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2686 disconnected from the bus.
2689 There is no corresponding "disconnect" request; if a client wishes to
2690 disconnect from the bus, it simply closes the socket (or other
2691 communication channel).
2694 <sect3 id="bus-messages-list-names">
2695 <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2699 ARRAY of STRING ListNames ()
2706 <entry>Argument</entry>
2708 <entry>Description</entry>
2714 <entry>ARRAY of STRING</entry>
2715 <entry>Array of strings where each string is a bus name</entry>
2722 Returns a list of all currently-owned names on the bus.
2725 <sect3 id="bus-messages-name-exists">
2726 <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2730 BOOLEAN NameHasOwner (in STRING name)
2737 <entry>Argument</entry>
2739 <entry>Description</entry>
2745 <entry>STRING</entry>
2746 <entry>Name to check</entry>
2756 <entry>Argument</entry>
2758 <entry>Description</entry>
2764 <entry>BOOLEAN</entry>
2765 <entry>Return value, true if the name exists</entry>
2772 Checks if the specified name exists (currently has an owner).
2776 <sect3 id="bus-messages-name-owner-changed">
2777 <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
2781 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
2788 <entry>Argument</entry>
2790 <entry>Description</entry>
2796 <entry>STRING</entry>
2797 <entry>Name with a new owner</entry>
2801 <entry>STRING</entry>
2802 <entry>Old owner or empty string if none</entry>
2806 <entry>STRING</entry>
2807 <entry>New owner or empty string if none</entry>
2814 This signal indicates that the owner of a name has changed.
2815 It's also the signal to use to detect the appearance of
2816 new names on the bus.
2819 <sect3 id="bus-messages-name-lost">
2820 <title><literal>org.freedesktop.DBus.NameLost</literal></title>
2824 NameLost (STRING name)
2831 <entry>Argument</entry>
2833 <entry>Description</entry>
2839 <entry>STRING</entry>
2840 <entry>Name which was lost</entry>
2847 This signal is sent to a specific application when it loses
2848 ownership of a name.
2852 <sect3 id="bus-messages-name-acquired">
2853 <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
2857 NameAcquired (STRING name)
2864 <entry>Argument</entry>
2866 <entry>Description</entry>
2872 <entry>STRING</entry>
2873 <entry>Name which was acquired</entry>
2880 This signal is sent to a specific application when it gains
2881 ownership of a name.
2885 <sect3 id="bus-messages-start-service-by-name">
2886 <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
2890 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
2897 <entry>Argument</entry>
2899 <entry>Description</entry>
2905 <entry>STRING</entry>
2906 <entry>Name of the service to start</entry>
2910 <entry>UINT32</entry>
2911 <entry>Flags (currently not used)</entry>
2921 <entry>Argument</entry>
2923 <entry>Description</entry>
2929 <entry>UINT32</entry>
2930 <entry>Return value</entry>
2935 Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
2939 The return value can be one of the following values:
2944 <entry>Identifier</entry>
2945 <entry>Value</entry>
2946 <entry>Description</entry>
2951 <entry>DBUS_START_REPLY_SUCCESS</entry>
2953 <entry>The service was successfully started.</entry>
2956 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
2958 <entry>A connection already owns the given name.</entry>
2967 <sect3 id="bus-messages-get-name-owner">
2968 <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
2972 STRING GetNameOwner (in STRING name)
2979 <entry>Argument</entry>
2981 <entry>Description</entry>
2987 <entry>STRING</entry>
2988 <entry>Name to get the owner of</entry>
2998 <entry>Argument</entry>
3000 <entry>Description</entry>
3006 <entry>STRING</entry>
3007 <entry>Return value, a unique connection name</entry>
3012 Returns the unique connection name of the primary owner of the name
3013 given. If the requested name doesn't have an owner, returns a
3014 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
3018 <sect3 id="bus-messages-get-connection-unix-user">
3019 <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
3023 UINT32 GetConnectionUnixUser (in STRING connection_name)
3030 <entry>Argument</entry>
3032 <entry>Description</entry>
3038 <entry>STRING</entry>
3039 <entry>Name of the connection to query</entry>
3049 <entry>Argument</entry>
3051 <entry>Description</entry>
3057 <entry>UINT32</entry>
3058 <entry>unix user id</entry>
3063 Returns the unix uid of the process connected to the server. If unable to
3064 determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
3073 <appendix id="implementation-notes">
3074 <title>Implementation notes</title>
3075 <sect1 id="implementation-notes-subsection">
3083 <glossary><title>Glossary</title>
3085 This glossary defines some of the terms used in this specification.
3088 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
3091 The message bus maintains an association between names and
3092 connections. (Normally, there's one connection per application.) A
3093 bus name is simply an identifier used to locate connections. For
3094 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
3095 name might be used to send a message to a screensaver from Yoyodyne
3096 Corporation. An application is said to <firstterm>own</firstterm> a
3097 name if the message bus has associated the application's connection
3098 with the name. Names may also have <firstterm>queued
3099 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
3100 The bus assigns a unique name to each connection,
3101 see <xref linkend="term-unique-name"/>. Other names
3102 can be thought of as "well-known names" and are
3103 used to find applications that offer specific functionality.
3108 <glossentry id="term-message"><glossterm>Message</glossterm>
3111 A message is the atomic unit of communication via the D-BUS
3112 protocol. It consists of a <firstterm>header</firstterm> and a
3113 <firstterm>body</firstterm>; the body is made up of
3114 <firstterm>arguments</firstterm>.
3119 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
3122 The message bus is a special application that forwards
3123 or routes messages between a group of applications
3124 connected to the message bus. It also manages
3125 <firstterm>names</firstterm> used for routing
3131 <glossentry id="term-name"><glossterm>Name</glossterm>
3134 See <xref linkend="term-bus-name"/>. "Name" may
3135 also be used to refer to some of the other names
3136 in D-BUS, such as interface names.
3141 <glossentry id="namespace"><glossterm>Namespace</glossterm>
3144 Used to prevent collisions when defining new interfaces or bus
3145 names. The convention used is the same one Java uses for defining
3146 classes: a reversed domain name.
3151 <glossentry id="term-object"><glossterm>Object</glossterm>
3154 Each application contains <firstterm>objects</firstterm>, which have
3155 <firstterm>interfaces</firstterm> and
3156 <firstterm>methods</firstterm>. Objects are referred to by a name,
3157 called a <firstterm>path</firstterm>.
3162 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
3165 An application talking directly to another application, without going
3166 through a message bus. One-to-one connections may be "peer to peer" or
3167 "client to server." The D-BUS protocol has no concept of client
3168 vs. server after a connection has authenticated; the flow of messages
3169 is symmetrical (full duplex).
3174 <glossentry id="term-path"><glossterm>Path</glossterm>
3177 Object references (object names) in D-BUS are organized into a
3178 filesystem-style hierarchy, so each object is named by a path. As in
3179 LDAP, there's no difference between "files" and "directories"; a path
3180 can refer to an object, while still having child objects below it.
3185 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
3188 Each bus name has a primary owner; messages sent to the name go to the
3189 primary owner. However, certain names also maintain a queue of
3190 secondary owners "waiting in the wings." If the primary owner releases
3191 the name, then the first secondary owner in the queue automatically
3192 becomes the new owner of the name.
3197 <glossentry id="term-service"><glossterm>Service</glossterm>
3200 A service is an executable that can be launched by the bus daemon.
3201 Services normally guarantee some particular features, for example they
3202 may guarantee that they will request a specific name such as
3203 "org.freedesktop.Screensaver", have a singleton object
3204 "/org/freedesktop/Application", and that object will implement the
3205 interface "org.freedesktop.ScreensaverControl".
3210 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
3213 ".service files" tell the bus about service applications that can be
3214 launched (see <xref linkend="term-service"/>). Most importantly they
3215 provide a mapping from bus names to services that will request those
3216 names when they start up.
3221 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
3224 The special name automatically assigned to each connection by the
3225 message bus. This name will never change owner, and will be unique
3226 (never reused during the lifetime of the message bus).
3227 It will begin with a ':' character.