Merge branch 'dbus-1.6'
[platform/upstream/dbus.git] / doc / dbus-specification.xml
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"
4 [
5 ]>
6 <article id="index">
7   <articleinfo>
8     <title>D-Bus Specification</title>
9     <releaseinfo>Version 0.19</releaseinfo>
10     <date>2012-02-21</date>
11     <authorgroup>
12       <author>
13         <firstname>Havoc</firstname>
14         <surname>Pennington</surname>
15         <affiliation>
16           <orgname>Red Hat, Inc.</orgname>
17           <address>
18             <email>hp@pobox.com</email>
19           </address>
20         </affiliation>
21       </author>
22       <author>
23         <firstname>Anders</firstname>
24         <surname>Carlsson</surname>
25         <affiliation>
26           <orgname>CodeFactory AB</orgname>
27           <address>
28             <email>andersca@codefactory.se</email>
29           </address>
30         </affiliation>
31       </author>
32       <author>
33         <firstname>Alexander</firstname>
34         <surname>Larsson</surname>
35         <affiliation>
36           <orgname>Red Hat, Inc.</orgname>
37           <address>
38             <email>alexl@redhat.com</email>
39           </address>
40         </affiliation>
41       </author>
42       <author>
43         <firstname>Sven</firstname>
44         <surname>Herzberg</surname>
45         <affiliation>
46           <orgname>Imendio AB</orgname>
47           <address>
48             <email>sven@imendio.com</email>
49           </address>
50         </affiliation>
51       </author>
52       <author>
53         <firstname>Simon</firstname>
54         <surname>McVittie</surname>
55         <affiliation>
56           <orgname>Collabora Ltd.</orgname>
57           <address>
58             <email>simon.mcvittie@collabora.co.uk</email>
59           </address>
60         </affiliation>
61       </author>
62       <author>
63         <firstname>David</firstname>
64         <surname>Zeuthen</surname>
65         <affiliation>
66           <orgname>Red Hat, Inc.</orgname>
67           <address>
68             <email>davidz@redhat.com</email>
69           </address>
70         </affiliation>
71       </author>
72     </authorgroup>
73    <revhistory>
74      <revision>
75        <revnumber>current</revnumber>
76        <date><ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink></date>
77        <authorinitials></authorinitials>
78        <revremark></revremark>
79      </revision>
80      <revision>
81        <revnumber>0.19</revnumber>
82        <date>20 February 2012</date>
83        <authorinitials>smcv/lp</authorinitials>
84        <revremark>formally define unique connection names and well-known
85         bus names; document best practices for interface, bus, member and
86         error names, and object paths; document the search path for session
87         and system services on Unix; document the systemd transport</revremark>
88      </revision>
89      <revision>
90        <revnumber>0.18</revnumber>
91        <date>29 July 2011</date>
92        <authorinitials>smcv</authorinitials>
93        <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
94          match keyword; promote type system to a top-level section</revremark>
95      </revision>
96      <revision>
97        <revnumber>0.17</revnumber>
98        <date>1 June 2011</date>
99        <authorinitials>smcv/davidz</authorinitials>
100        <revremark>define ObjectManager; reserve extra pseudo-type-codes used
101          by GVariant</revremark>
102      </revision>
103      <revision>
104        <revnumber>0.16</revnumber>
105        <date>11 April 2011</date>
106        <authorinitials></authorinitials>
107        <revremark>add path_namespace, arg0namespace; argNpath matches object
108         paths</revremark>
109      </revision>
110      <revision>
111        <revnumber>0.15</revnumber>
112        <date>3 November 2010</date>
113        <authorinitials></authorinitials>
114        <revremark></revremark>
115      </revision>
116      <revision>
117        <revnumber>0.14</revnumber>
118        <date>12 May 2010</date>
119        <authorinitials></authorinitials>
120        <revremark></revremark>
121      </revision>
122      <revision>
123        <revnumber>0.13</revnumber>
124        <date>23 Dezember 2009</date>
125        <authorinitials></authorinitials>
126        <revremark></revremark>
127      </revision>
128      <revision>
129        <revnumber>0.12</revnumber>
130        <date>7 November, 2006</date>
131        <authorinitials></authorinitials>
132        <revremark></revremark>
133      </revision>
134      <revision>
135        <revnumber>0.11</revnumber>
136        <date>6 February 2005</date>
137        <authorinitials></authorinitials>
138        <revremark></revremark>
139      </revision>
140      <revision>
141        <revnumber>0.10</revnumber>
142        <date>28 January 2005</date>
143        <authorinitials></authorinitials>
144        <revremark></revremark>
145      </revision>
146      <revision>
147        <revnumber>0.9</revnumber>
148        <date>7 Januar 2005</date>
149        <authorinitials></authorinitials>
150        <revremark></revremark>
151      </revision>
152      <revision>
153        <revnumber>0.8</revnumber>
154        <date>06 September 2003</date>
155        <authorinitials></authorinitials>
156        <revremark>First released document.</revremark>
157      </revision>
158    </revhistory>
159   </articleinfo>
160
161   <sect1 id="introduction">
162     <title>Introduction</title>
163     <para>
164       D-Bus is a system for low-latency, low-overhead, easy to use
165       interprocess communication (IPC). In more detail:
166       <itemizedlist>
167         <listitem>
168           <para>
169             D-Bus is <emphasis>low-latency</emphasis> because it is designed 
170             to avoid round trips and allow asynchronous operation, much like 
171             the X protocol.
172           </para>
173         </listitem>
174         <listitem>
175           <para>
176             D-Bus is <emphasis>low-overhead</emphasis> because it uses a
177             binary protocol, and does not have to convert to and from a text
178             format such as XML. Because D-Bus is intended for potentially
179             high-resolution same-machine IPC, not primarily for Internet IPC,
180             this is an interesting optimization.
181           </para>
182         </listitem>
183         <listitem>
184           <para>
185             D-Bus is <emphasis>easy to use</emphasis> because it works in terms
186             of <firstterm>messages</firstterm> rather than byte streams, and
187             automatically handles a lot of the hard IPC issues. Also, the D-Bus
188             library is designed to be wrapped in a way that lets developers use
189             their framework's existing object/type system, rather than learning
190             a new one specifically for IPC.
191           </para>
192         </listitem>
193       </itemizedlist>
194     </para>
195
196     <para>
197       The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
198       protocol, specified in <xref linkend="message-protocol"/>. That is, it is
199       a system for one application to talk to a single other
200       application. However, the primary intended application of the protocol is the
201       D-Bus <firstterm>message bus</firstterm>, specified in <xref
202       linkend="message-bus"/>. The message bus is a special application that
203       accepts connections from multiple other applications, and forwards
204       messages among them.
205     </para>
206
207     <para>
208       Uses of D-Bus include notification of system changes (notification of when
209       a camera is plugged in to a computer, or a new version of some software
210       has been installed), or desktop interoperability, for example a file
211       monitoring service or a configuration service.
212     </para>
213
214     <para>
215       D-Bus is designed for two specific use cases:
216       <itemizedlist>
217         <listitem>
218           <para>
219             A "system bus" for notifications from the system to user sessions,
220             and to allow the system to request input from user sessions.
221           </para>
222         </listitem>
223         <listitem>
224           <para>
225             A "session bus" used to implement desktop environments such as 
226             GNOME and KDE.
227           </para>
228         </listitem>
229       </itemizedlist>
230       D-Bus is not intended to be a generic IPC system for any possible 
231       application, and intentionally omits many features found in other 
232       IPC systems for this reason.
233     </para>
234
235     <para>
236       At the same time, the bus daemons offer a number of features not found in
237       other IPC systems, such as single-owner "bus names" (similar to X
238       selections), on-demand startup of services, and security policies.
239       In many ways, these features are the primary motivation for developing 
240       D-Bus; other systems would have sufficed if IPC were the only goal.
241     </para>
242
243     <para>
244       D-Bus may turn out to be useful in unanticipated applications, but future
245       versions of this spec and the reference implementation probably will not
246       incorporate features that interfere with the core use cases.
247     </para>
248
249     <para>
250       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
251       "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
252       document are to be interpreted as described in RFC 2119. However, the
253       document could use a serious audit to be sure it makes sense to do
254       so. Also, they are not capitalized.
255     </para>
256
257     <sect2 id="stability">
258       <title>Protocol and Specification Stability</title>
259       <para>
260         The D-Bus protocol is frozen (only compatible extensions are allowed) as
261         of November 8, 2006.  However, this specification could still use a fair
262         bit of work to make interoperable reimplementation possible without
263         reference to the D-Bus reference implementation. Thus, this
264         specification is not marked 1.0. To mark it 1.0, we'd like to see
265         someone invest significant effort in clarifying the specification
266         language, and growing the specification to cover more aspects of the
267         reference implementation's behavior.
268       </para>
269       <para>
270         Until this work is complete, any attempt to reimplement D-Bus will 
271         probably require looking at the reference implementation and/or asking
272         questions on the D-Bus mailing list about intended behavior. 
273         Questions on the list are very welcome.
274       </para>
275       <para>
276         Nonetheless, this document should be a useful starting point and is 
277         to our knowledge accurate, though incomplete.
278       </para>
279     </sect2>
280     
281   </sect1>
282
283   <sect1 id="type-system">
284     <title>Type System</title>
285
286     <para>
287       D-Bus has a type system, in which values of various types can be
288       serialized into a sequence of bytes referred to as the
289       <firstterm>wire format</firstterm> in a standard way.
290       Converting a value from some other representation into the wire
291       format is called <firstterm>marshaling</firstterm> and converting
292       it back from the wire format is <firstterm>unmarshaling</firstterm>.
293     </para>
294
295     <para>
296       The D-Bus protocol does not include type tags in the marshaled data; a
297       block of marshaled values must have a known <firstterm>type
298         signature</firstterm>. The type signature is made up of zero or more
299       <firstterm id="term-single-complete-type">single complete
300         types</firstterm>, each made up of one or more
301       <firstterm>type codes</firstterm>.
302     </para>
303
304     <para>
305       A type code is an ASCII character representing the
306       type of a value. Because ASCII characters are used, the type signature
307       will always form a valid ASCII string. A simple string compare
308       determines whether two type signatures are equivalent.
309     </para>
310
311     <para>
312       A single complete type is a sequence of type codes that fully describes
313       one type: either a basic type, or a single fully-described container type.
314       A single complete type is a basic type code, a variant type code,
315       an array with its element type, or a struct with its fields (all of which
316       are defined below). So the following signatures are not single complete
317       types:
318       <programlisting>
319         "aa"
320       </programlisting>
321       <programlisting>
322         "(ii"
323       </programlisting>
324       <programlisting>
325         "ii)"
326       </programlisting>
327       And the following signatures contain multiple complete types:
328       <programlisting>
329         "ii"
330       </programlisting>
331       <programlisting>
332         "aiai"
333       </programlisting>
334       <programlisting>
335         "(ii)(ii)"
336       </programlisting>
337       Note however that a single complete type may <emphasis>contain</emphasis>
338       multiple other single complete types, by containing a struct or dict
339       entry.
340     </para>
341
342     <sect2 id="basic-types">
343       <title>Basic types</title>
344
345       <para>
346         The simplest type codes are the <firstterm id="term-basic-type">basic
347           types</firstterm>, which are the types whose structure is entirely
348         defined by their 1-character type code. Basic types consist of
349         fixed types and string-like types.
350       </para>
351
352       <para>
353         The <firstterm id="term-fixed-type">fixed types</firstterm>
354         are basic types whose values have a fixed length, namely BYTE,
355         BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
356         16, 32 or 64 bits.
357       </para>
358
359       <para>
360         As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
361         the ASCII character 'i'. So the signature for a block of values 
362         containing a single <literal>INT32</literal> would be:
363         <programlisting>
364           "i"
365         </programlisting>
366         A block of values containing two <literal>INT32</literal> would have this signature:
367         <programlisting>
368           "ii"
369         </programlisting>        
370       </para>
371
372       <para>
373         The characteristics of the fixed types are listed in this table.
374
375         <informaltable>
376           <tgroup cols="3">
377             <thead>
378               <row>
379                 <entry>Conventional name</entry>
380                 <entry>ASCII type-code</entry>
381                 <entry>Encoding</entry>
382               </row>
383             </thead>
384             <tbody>
385               <row>
386                 <entry><literal>BYTE</literal></entry>
387                 <entry><literal>y</literal> (121)</entry>
388                 <entry>Unsigned 8-bit integer</entry>
389               </row>
390               <row>
391                 <entry><literal>BOOLEAN</literal></entry>
392                 <entry><literal>b</literal> (98)</entry>
393                 <entry>Boolean value: 0 is false, 1 is true, any other value
394                   allowed by the marshalling format is invalid</entry>
395               </row>
396               <row>
397                 <entry><literal>INT16</literal></entry>
398                 <entry><literal>n</literal> (110)</entry>
399                 <entry>Signed (two's complement) 16-bit integer</entry>
400               </row>
401               <row>
402                 <entry><literal>UINT16</literal></entry>
403                 <entry><literal>q</literal> (113)</entry>
404                 <entry>Unsigned 16-bit integer</entry>
405               </row>
406               <row>
407                 <entry><literal>INT32</literal></entry>
408                 <entry><literal>i</literal> (105)</entry>
409                 <entry>Signed (two's complement) 32-bit integer</entry>
410               </row>
411               <row>
412                 <entry><literal>UINT32</literal></entry>
413                 <entry><literal>u</literal> (117)</entry>
414                 <entry>Unsigned 32-bit integer</entry>
415               </row>
416               <row>
417                 <entry><literal>INT64</literal></entry>
418                 <entry><literal>x</literal> (120)</entry>
419                 <entry>Signed (two's complement) 64-bit integer
420                   (mnemonic: x and t are the first characters in "sixty" not
421                   already used for something more common)</entry>
422               </row>
423               <row>
424                 <entry><literal>UINT64</literal></entry>
425                 <entry><literal>t</literal> (116)</entry>
426                 <entry>Unsigned 64-bit integer</entry>
427               </row>
428               <row>
429                 <entry><literal>DOUBLE</literal></entry>
430                 <entry><literal>d</literal> (100)</entry>
431                 <entry>IEEE 754 double-precision floating point</entry>
432               </row>
433               <row>
434                 <entry><literal>UNIX_FD</literal></entry>
435                 <entry><literal>h</literal> (104)</entry>
436                 <entry>Unsigned 32-bit integer representing an index into an
437                   out-of-band array of file descriptors, transferred via some
438                   platform-specific mechanism (mnemonic: h for handle)</entry>
439               </row>
440             </tbody>
441           </tgroup>
442         </informaltable>
443       </para>
444
445       <para>
446         The <firstterm id="term-string-like-type">string-like types</firstterm>
447         are basic types with a variable length. The value of any string-like
448         type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
449         none of which may be U+0000. The UTF-8 text must be validated
450         strictly: in particular, it must not contain overlong sequences,
451         noncharacters such as U+FFFE, or codepoints above U+10FFFF.
452       </para>
453
454       <para>
455         The marshalling formats for the string-like types all end with a
456         single zero (NUL) byte, but that byte is not considered to be part of
457         the text.
458       </para>
459
460       <para>
461         The characteristics of the string-like types are listed in this table.
462
463         <informaltable>
464           <tgroup cols="3">
465             <thead>
466               <row>
467                 <entry>Conventional name</entry>
468                 <entry>ASCII type-code</entry>
469                 <entry>Validity constraints</entry>
470               </row>
471             </thead>
472             <tbody>
473               <row>
474                 <entry><literal>STRING</literal></entry>
475                 <entry><literal>s</literal> (115)</entry>
476                 <entry>No extra constraints</entry>
477               </row>
478               <row>
479                 <entry><literal>OBJECT_PATH</literal></entry>
480                 <entry><literal>o</literal> (111)</entry>
481                 <entry>Must be
482                   <link linkend="message-protocol-marshaling-object-path">a
483                     syntactically valid object path</link></entry>
484               </row>
485               <row>
486                 <entry><literal>SIGNATURE</literal></entry>
487                 <entry><literal>g</literal> (103)</entry>
488                 <entry>Zero or more
489                   <firstterm linkend="term-single-complete-type">single
490                     complete types</firstterm></entry>
491               </row>
492             </tbody>
493           </tgroup>
494         </informaltable>
495       </para>
496
497       <sect3 id="message-protocol-marshaling-object-path">
498         <title>Valid Object Paths</title>
499
500         <para>
501           An object path is a name used to refer to an object instance.
502           Conceptually, each participant in a D-Bus message exchange may have
503           any number of object instances (think of C++ or Java objects) and each
504           such instance will have a path. Like a filesystem, the object
505           instances in an application form a hierarchical tree.
506         </para>
507
508         <para>
509           Object paths are often namespaced by starting with a reversed
510           domain name and containing an interface version number, in the
511           same way as
512           <link linkend="message-protocol-names-interface">interface
513             names</link> and
514           <link linkend="message-protocol-names-bus">well-known
515             bus names</link>.
516           This makes it possible to implement more than one service, or
517           more than one version of a service, in the same process,
518           even if the services share a connection but cannot otherwise
519           co-operate (for instance, if they are implemented by different
520           plugins).
521         </para>
522
523         <para>
524           For instance, if the owner of <literal>example.com</literal> is
525           developing a D-Bus API for a music player, they might use the
526           hierarchy of object paths that start with
527           <literal>/com/example/MusicPlayer1</literal> for its objects.
528         </para>
529
530         <para>
531           The following rules define a valid object path. Implementations must
532           not send or accept messages with invalid object paths.
533           <itemizedlist>
534             <listitem>
535               <para>
536                 The path may be of any length.
537               </para>
538             </listitem>
539             <listitem>
540               <para>
541                 The path must begin with an ASCII '/' (integer 47) character,
542                 and must consist of elements separated by slash characters.
543               </para>
544             </listitem>
545             <listitem>
546               <para>
547                 Each element must only contain the ASCII characters
548                 "[A-Z][a-z][0-9]_"
549               </para>
550             </listitem>
551             <listitem>
552               <para>
553                 No element may be the empty string.
554               </para>
555             </listitem>
556             <listitem>
557               <para>
558                 Multiple '/' characters cannot occur in sequence.
559               </para>
560             </listitem>
561             <listitem>
562               <para>
563                 A trailing '/' character is not allowed unless the
564                 path is the root path (a single '/' character).
565               </para>
566             </listitem>
567           </itemizedlist>
568         </para>
569
570       </sect3>
571
572       <sect3 id="message-protocol-marshaling-signature">
573         <title>Valid Signatures</title>
574         <para>
575           An implementation must not send or accept invalid signatures.
576           Valid signatures will conform to the following rules:
577           <itemizedlist>
578             <listitem>
579               <para>
580                 The signature is a list of single complete types.
581                 Arrays must have element types, and structs must
582                 have both open and close parentheses.
583               </para>
584             </listitem>
585             <listitem>
586               <para>
587                 Only type codes, open and close parentheses, and open and
588                 close curly brackets are allowed in the signature. The
589                 <literal>STRUCT</literal> type code
590                 is not allowed in signatures, because parentheses
591                 are used instead. Similarly, the
592                 <literal>DICT_ENTRY</literal> type code is not allowed in
593                 signatures, because curly brackets are used instead.
594               </para>
595             </listitem>
596             <listitem>
597               <para>
598                 The maximum depth of container type nesting is 32 array type
599                 codes and 32 open parentheses. This implies that the maximum
600                 total depth of recursion is 64, for an "array of array of array
601                 of ... struct of struct of struct of ..."  where there are 32
602                 array and 32 struct.
603               </para>
604             </listitem>
605             <listitem>
606               <para>
607                 The maximum length of a signature is 255.
608               </para>
609             </listitem>
610           </itemizedlist>
611         </para>
612
613         <para>
614           When signatures appear in messages, the marshalling format
615           guarantees that they will be followed by a nul byte (which can
616           be interpreted as either C-style string termination or the INVALID
617           type-code), but this is not conceptually part of the signature.
618         </para>
619       </sect3>
620
621     </sect2>
622
623     <sect2 id="container-types">
624       <title>Container types</title>
625
626       <para>
627         In addition to basic types, there are four <firstterm>container</firstterm> 
628         types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>, 
629         and <literal>DICT_ENTRY</literal>.
630       </para>
631
632       <para>
633         <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type 
634         code does not appear in signatures. Instead, ASCII characters
635         '(' and ')' are used to mark the beginning and end of the struct.
636         So for example, a struct containing two integers would have this 
637         signature:
638         <programlisting>
639           "(ii)"
640         </programlisting>
641         Structs can be nested, so for example a struct containing 
642         an integer and another struct:
643         <programlisting>
644           "(i(ii))"
645         </programlisting>
646         The value block storing that struct would contain three integers; the
647         type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
648         "(iii)" or "iii".
649       </para>
650
651       <para>
652         The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
653         but is useful in code that implements the protocol. This type code 
654         is specified to allow such code to interoperate in non-protocol contexts.
655       </para>
656
657       <para>
658         Empty structures are not allowed; there must be at least one
659         type code between the parentheses.
660       </para>
661
662       <para>
663         <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
664         followed by a <firstterm>single complete type</firstterm>. The single
665         complete type following the array is the type of each array element. So
666         the simple example is:
667         <programlisting>
668           "ai"
669         </programlisting>
670         which is an array of 32-bit integers. But an array can be of any type, 
671         such as this array-of-struct-with-two-int32-fields:
672         <programlisting>
673           "a(ii)"
674         </programlisting>
675         Or this array of array of integer:
676         <programlisting>
677           "aai"
678         </programlisting>
679       </para>
680
681       <para>
682         <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
683         type <literal>VARIANT</literal> will have the signature of a single complete type as part
684         of the <emphasis>value</emphasis>.  This signature will be followed by a
685         marshaled value of that type.
686       </para>
687
688       <para>
689         Unlike a message signature, the variant signature can
690         contain only a single complete type.  So "i", "ai"
691         or "(ii)" is OK, but "ii" is not.  Use of variants may not
692         cause a total message depth to be larger than 64, including
693         other container types such as structures.
694       </para>
695
696       <para>
697         A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
698         than parentheses it uses curly braces, and it has more restrictions.
699         The restrictions are: it occurs only as an array element type; it has
700         exactly two single complete types inside the curly braces; the first
701         single complete type (the "key") must be a basic type rather than a
702         container type. Implementations must not accept dict entries outside of
703         arrays, must not accept dict entries with zero, one, or more than two
704         fields, and must not accept dict entries with non-basic-typed keys. A
705         dict entry is always a key-value pair.
706       </para>
707       
708       <para>
709         The first field in the <literal>DICT_ENTRY</literal> is always the key.
710         A message is considered corrupt if the same key occurs twice in the same
711         array of <literal>DICT_ENTRY</literal>. However, for performance reasons
712         implementations are not required to reject dicts with duplicate keys.
713       </para>
714
715       <para>
716         In most languages, an array of dict entry would be represented as a 
717         map, hash table, or dict object.
718       </para>
719     </sect2>
720
721     <sect2>
722       <title>Summary of types</title>
723
724       <para>
725         The following table summarizes the D-Bus types.
726         <informaltable>
727           <tgroup cols="3">
728             <thead>
729               <row>
730                 <entry>Conventional Name</entry>
731                 <entry>Code</entry>
732                 <entry>Description</entry>
733               </row>
734             </thead>
735             <tbody>
736               <row>
737                 <entry><literal>INVALID</literal></entry>
738                 <entry>0 (ASCII NUL)</entry>
739                 <entry>Not a valid type code, used to terminate signatures</entry>
740               </row><row>
741                 <entry><literal>BYTE</literal></entry>
742                 <entry>121 (ASCII 'y')</entry>
743                 <entry>8-bit unsigned integer</entry>
744               </row><row>
745                 <entry><literal>BOOLEAN</literal></entry>
746                 <entry>98 (ASCII 'b')</entry>
747                 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
748               </row><row>
749                 <entry><literal>INT16</literal></entry>
750                 <entry>110 (ASCII 'n')</entry>
751                 <entry>16-bit signed integer</entry>
752               </row><row>
753                 <entry><literal>UINT16</literal></entry>
754                 <entry>113 (ASCII 'q')</entry>
755                 <entry>16-bit unsigned integer</entry>
756               </row><row>
757                 <entry><literal>INT32</literal></entry>
758                 <entry>105 (ASCII 'i')</entry>
759                 <entry>32-bit signed integer</entry>
760               </row><row>
761                 <entry><literal>UINT32</literal></entry>
762                 <entry>117 (ASCII 'u')</entry>
763                 <entry>32-bit unsigned integer</entry>
764               </row><row>
765                 <entry><literal>INT64</literal></entry>
766                 <entry>120 (ASCII 'x')</entry>
767                 <entry>64-bit signed integer</entry>
768               </row><row>
769                 <entry><literal>UINT64</literal></entry>
770                 <entry>116 (ASCII 't')</entry>
771                 <entry>64-bit unsigned integer</entry>
772               </row><row>
773                 <entry><literal>DOUBLE</literal></entry>
774                 <entry>100 (ASCII 'd')</entry>
775                 <entry>IEEE 754 double</entry>
776               </row><row>
777                 <entry><literal>STRING</literal></entry>
778                 <entry>115 (ASCII 's')</entry>
779                 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
780               </row><row>
781                 <entry><literal>OBJECT_PATH</literal></entry>
782                 <entry>111 (ASCII 'o')</entry>
783                 <entry>Name of an object instance</entry>
784               </row><row>
785                 <entry><literal>SIGNATURE</literal></entry>
786                 <entry>103 (ASCII 'g')</entry>
787                 <entry>A type signature</entry>
788               </row><row>
789                 <entry><literal>ARRAY</literal></entry>
790                 <entry>97 (ASCII 'a')</entry>
791                 <entry>Array</entry>
792               </row><row>
793                 <entry><literal>STRUCT</literal></entry>
794                 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
795                 <entry>Struct; type code 114 'r' is reserved for use in
796                   bindings and implementations to represent the general
797                   concept of a struct, and must not appear in signatures
798                   used on D-Bus.</entry>
799               </row><row>
800                 <entry><literal>VARIANT</literal></entry>
801                 <entry>118 (ASCII 'v') </entry>
802                 <entry>Variant type (the type of the value is part of the value itself)</entry>
803               </row><row>
804                 <entry><literal>DICT_ENTRY</literal></entry>
805                 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
806                 <entry>Entry in a dict or map (array of key-value pairs).
807                   Type code 101 'e' is reserved for use in bindings and
808                   implementations to represent the general concept of a
809                   dict or dict-entry, and must not appear in signatures
810                   used on D-Bus.</entry>
811               </row><row>
812                 <entry><literal>UNIX_FD</literal></entry>
813                 <entry>104 (ASCII 'h')</entry>
814                 <entry>Unix file descriptor</entry>
815               </row>
816               <row>
817                 <entry>(reserved)</entry>
818                 <entry>109 (ASCII 'm')</entry>
819                 <entry>Reserved for <ulink
820                     url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
821                   'maybe' type compatible with the one in GVariant</ulink>,
822                   and must not appear in signatures used on D-Bus until
823                   specified here</entry>
824               </row>
825               <row>
826                 <entry>(reserved)</entry>
827                 <entry>42 (ASCII '*')</entry>
828                 <entry>Reserved for use in bindings/implementations to
829                   represent any <firstterm>single complete type</firstterm>,
830                   and must not appear in signatures used on D-Bus.</entry>
831               </row>
832               <row>
833                 <entry>(reserved)</entry>
834                 <entry>63 (ASCII '?')</entry>
835                 <entry>Reserved for use in bindings/implementations to
836                   represent any <firstterm>basic type</firstterm>, and must
837                   not appear in signatures used on D-Bus.</entry>
838               </row>
839               <row>
840                 <entry>(reserved)</entry>
841                 <entry>64 (ASCII '@'), 38 (ASCII '&amp;'),
842                   94 (ASCII '^')</entry>
843                 <entry>Reserved for internal use by bindings/implementations,
844                   and must not appear in signatures used on D-Bus.
845                   GVariant uses these type-codes to encode calling
846                   conventions.</entry>
847               </row>
848             </tbody>
849           </tgroup>
850         </informaltable>
851       </para>
852
853     </sect2>
854   </sect1>
855
856   <sect1 id="message-protocol-marshaling">
857     <title>Marshaling (Wire Format)</title>
858
859     <para>
860       D-Bus defines a marshalling format for its type system, which is
861       used in D-Bus messages. This is not the only possible marshalling
862       format for the type system: for instance, GVariant (part of GLib)
863       re-uses the D-Bus type system but implements an alternative marshalling
864       format.
865     </para>
866
867     <sect2>
868       <title>Byte order and alignment</title>
869
870       <para>
871         Given a type signature, a block of bytes can be converted into typed
872         values. This section describes the format of the block of bytes.  Byte
873         order and alignment issues are handled uniformly for all D-Bus types.
874       </para>
875
876       <para>
877         A block of bytes has an associated byte order. The byte order
878         has to be discovered in some way; for D-Bus messages, the
879         byte order is part of the message header as described in
880         <xref linkend="message-protocol-messages"/>. For now, assume
881         that the byte order is known to be either little endian or big
882           endian.
883       </para>
884
885       <para>
886         Each value in a block of bytes is aligned "naturally," for example
887         4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
888         8-byte boundary. To properly align a value, <firstterm>alignment
889         padding</firstterm> may be necessary. The alignment padding must always
890         be the minimum required padding to properly align the following value;
891         and it must always be made up of nul bytes. The alignment padding must
892         not be left uninitialized (it can't contain garbage), and more padding
893         than required must not be used.
894       </para>
895
896       <para>
897         As an exception to natural alignment, <literal>STRUCT</literal> and
898         <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
899         boundary, regardless of the alignments of their contents.
900       </para>
901     </sect2>
902
903     <sect2>
904       <title>Marshalling basic types</title>
905
906       <para>
907         To marshal and unmarshal fixed types, you simply read one value
908         from the data block corresponding to each type code in the signature.
909         All signed integer values are encoded in two's complement, DOUBLE
910         values are IEEE 754 double-precision floating-point, and BOOLEAN
911         values are encoded in 32 bits (of which only the least significant
912         bit is used).
913       </para>
914
915       <para>
916         The string-like types are all marshalled as a
917         fixed-length unsigned integer <varname>n</varname> giving the
918         length of the variable part, followed by <varname>n</varname>
919         nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
920         which is not considered to be part of the text. The alignment
921         of the string-like type is the same as the alignment of
922         <varname>n</varname>.
923       </para>
924
925       <para>
926         For the STRING and OBJECT_PATH types, <varname>n</varname> is
927         encoded in 4 bytes, leading to 4-byte alignment.
928         For the SIGNATURE type, <varname>n</varname> is encoded as a single
929         byte. As a result, alignment padding is never required before a
930         SIGNATURE.
931       </para>
932     </sect2>
933
934     <sect2>
935       <title>Marshalling containers</title>
936
937       <para>
938         Arrays are marshalled as a <literal>UINT32</literal>
939         <varname>n</varname> giving the length of the array data in bytes,
940         followed by alignment padding to the alignment boundary of the array
941         element type, followed by the <varname>n</varname> bytes of the
942         array elements marshalled in sequence. <varname>n</varname> does not
943         include the padding after the length, or any padding after the
944         last element.
945       </para>
946
947       <para>
948         For instance, if the current position in the message is a multiple
949         of 8 bytes and the byte-order is big-endian, an array containing only
950         the 64-bit integer 5 would be marshalled as:
951
952         <screen>
953 00 00 00 08               <lineannotation>8 bytes of data</lineannotation>
954 00 00 00 00               <lineannotation>padding to 8-byte boundary</lineannotation>
955 00 00 00 00  00 00 00 05  <lineannotation>first element = 5</lineannotation>
956         </screen>
957       </para>
958
959       <para>
960         Arrays have a maximum length defined to be 2 to the 26th power or
961         67108864. Implementations must not send or accept arrays exceeding this
962         length.
963       </para>
964
965       <para>
966         Structs and dict entries are marshalled in the same way as their
967         contents, but their alignment is always to an 8-byte boundary,
968         even if their contents would normally be less strictly aligned.
969       </para>
970
971       <para>
972         Variants are marshalled as the <literal>SIGNATURE</literal> of
973         the contents (which must be a single complete type), followed by a
974         marshalled value with the type given by that signature. The
975         variant has the same 1-byte alignment as the signature, which means
976         that alignment padding before a variant is never needed.
977         Use of variants may not cause a total message depth to be larger
978         than 64, including other container types such as structures.
979       </para>
980     </sect2>
981
982     <sect2>
983       <title>Summary of D-Bus marshalling</title>
984
985       <para>
986         Given all this, the types are marshaled on the wire as follows:
987         <informaltable>
988           <tgroup cols="3">
989             <thead>
990               <row>
991                 <entry>Conventional Name</entry>
992                 <entry>Encoding</entry>
993                 <entry>Alignment</entry>
994               </row>
995             </thead>
996             <tbody>
997               <row>
998                 <entry><literal>INVALID</literal></entry>
999                 <entry>Not applicable; cannot be marshaled.</entry>
1000                 <entry>N/A</entry>
1001               </row><row>
1002                 <entry><literal>BYTE</literal></entry>
1003                 <entry>A single 8-bit byte.</entry>
1004                 <entry>1</entry>
1005               </row><row>
1006                 <entry><literal>BOOLEAN</literal></entry>
1007                 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
1008                 <entry>4</entry>
1009               </row><row>
1010                 <entry><literal>INT16</literal></entry>
1011                 <entry>16-bit signed integer in the message's byte order.</entry>
1012                 <entry>2</entry>
1013               </row><row>
1014                 <entry><literal>UINT16</literal></entry>
1015                 <entry>16-bit unsigned integer in the message's byte order.</entry>
1016                 <entry>2</entry>
1017               </row><row>
1018                 <entry><literal>INT32</literal></entry>
1019                 <entry>32-bit signed integer in the message's byte order.</entry>
1020                 <entry>4</entry>
1021               </row><row>
1022                 <entry><literal>UINT32</literal></entry>
1023                 <entry>32-bit unsigned integer in the message's byte order.</entry>
1024                 <entry>4</entry>
1025               </row><row>
1026                 <entry><literal>INT64</literal></entry>
1027                 <entry>64-bit signed integer in the message's byte order.</entry>
1028                 <entry>8</entry>
1029               </row><row>
1030                 <entry><literal>UINT64</literal></entry>
1031                 <entry>64-bit unsigned integer in the message's byte order.</entry>
1032                 <entry>8</entry>
1033               </row><row>
1034                 <entry><literal>DOUBLE</literal></entry>
1035                 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
1036                 <entry>8</entry>
1037               </row><row>
1038                 <entry><literal>STRING</literal></entry>
1039                 <entry>A <literal>UINT32</literal> indicating the string's 
1040                   length in bytes excluding its terminating nul, followed by 
1041                   non-nul string data of the given length, followed by a terminating nul 
1042                   byte.
1043                 </entry>
1044                 <entry>
1045                   4 (for the length)
1046                 </entry>
1047               </row><row>
1048                 <entry><literal>OBJECT_PATH</literal></entry>
1049                 <entry>Exactly the same as <literal>STRING</literal> except the 
1050                   content must be a valid object path (see above).
1051                 </entry>
1052                 <entry>
1053                   4 (for the length)
1054                 </entry>
1055               </row><row>
1056                 <entry><literal>SIGNATURE</literal></entry>
1057                 <entry>The same as <literal>STRING</literal> except the length is a single 
1058                   byte (thus signatures have a maximum length of 255)
1059                   and the content must be a valid signature (see above).
1060                 </entry>
1061                 <entry>
1062                   1
1063                 </entry>
1064               </row><row>
1065                 <entry><literal>ARRAY</literal></entry>
1066                 <entry>
1067                   A <literal>UINT32</literal> giving the length of the array data in bytes, followed by 
1068                   alignment padding to the alignment boundary of the array element type,
1069                   followed by each array element.
1070                 </entry>
1071                 <entry>
1072                   4 (for the length)
1073                 </entry>
1074               </row><row>
1075                 <entry><literal>STRUCT</literal></entry>
1076                 <entry>
1077                   A struct must start on an 8-byte boundary regardless of the
1078                   type of the struct fields. The struct value consists of each
1079                   field marshaled in sequence starting from that 8-byte
1080                   alignment boundary.
1081                 </entry>
1082                 <entry>
1083                   8
1084                 </entry>
1085               </row><row>
1086                 <entry><literal>VARIANT</literal></entry>
1087                 <entry>
1088                   The marshaled <literal>SIGNATURE</literal> of a single
1089                   complete type, followed by a marshaled value with the type
1090                   given in the signature.
1091                 </entry>
1092                 <entry>
1093                   1 (alignment of the signature)
1094                 </entry>
1095               </row><row>
1096                 <entry><literal>DICT_ENTRY</literal></entry>
1097                 <entry>
1098                   Identical to STRUCT.
1099                 </entry>
1100                 <entry>
1101                   8
1102                 </entry>
1103               </row><row>
1104                 <entry><literal>UNIX_FD</literal></entry>
1105                 <entry>32-bit unsigned integer in the message's byte
1106                 order. The actual file descriptors need to be
1107                 transferred out-of-band via some platform specific
1108                 mechanism. On the wire, values of this type store the index to the
1109                 file descriptor in the array of file descriptors that
1110                 accompany the message.</entry>
1111                 <entry>4</entry>
1112               </row>
1113             </tbody>
1114           </tgroup>
1115         </informaltable>
1116       </para>
1117
1118     </sect2>
1119
1120   </sect1>
1121
1122   <sect1 id="message-protocol">
1123     <title>Message Protocol</title>
1124
1125     <para>
1126       A <firstterm>message</firstterm> consists of a
1127       <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
1128       think of a message as a package, the header is the address, and the body
1129       contains the package contents. The message delivery system uses the header
1130       information to figure out where to send the message and how to interpret
1131       it; the recipient interprets the body of the message.
1132     </para>
1133     
1134     <para>
1135       The body of the message is made up of zero or more
1136       <firstterm>arguments</firstterm>, which are typed values, such as an
1137       integer or a byte array.
1138     </para>
1139
1140     <para>
1141       Both header and body use the D-Bus <link linkend="type-system">type
1142         system</link> and format for serializing data.
1143     </para>
1144
1145     <sect2 id="message-protocol-messages">
1146       <title>Message Format</title>
1147
1148       <para>
1149         A message consists of a header and a body. The header is a block of
1150         values with a fixed signature and meaning.  The body is a separate block
1151         of values, with a signature specified in the header.
1152       </para>
1153
1154       <para>
1155         The length of the header must be a multiple of 8, allowing the body to
1156         begin on an 8-byte boundary when storing the entire message in a single
1157         buffer. If the header does not naturally end on an 8-byte boundary 
1158         up to 7 bytes of nul-initialized alignment padding must be added.
1159       </para>
1160
1161       <para>
1162         The message body need not end on an 8-byte boundary.
1163       </para>
1164
1165       <para>
1166         The maximum length of a message, including header, header alignment padding, 
1167         and body is 2 to the 27th power or 134217728. Implementations must not 
1168         send or accept messages exceeding this size.
1169       </para>
1170       
1171       <para>
1172         The signature of the header is:
1173         <programlisting>
1174           "yyyyuua(yv)"
1175         </programlisting>
1176         Written out more readably, this is:
1177         <programlisting>
1178           BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
1179         </programlisting>
1180       </para>
1181
1182       <para>
1183         These values have the following meanings:
1184         <informaltable>
1185           <tgroup cols="2">
1186             <thead>
1187               <row>
1188                 <entry>Value</entry>
1189                 <entry>Description</entry>
1190               </row>
1191             </thead>
1192             <tbody>
1193               <row>
1194                 <entry>1st <literal>BYTE</literal></entry>
1195                 <entry>Endianness flag; ASCII 'l' for little-endian 
1196                   or ASCII 'B' for big-endian. Both header and body are 
1197                 in this endianness.</entry>
1198               </row>
1199               <row>
1200                 <entry>2nd <literal>BYTE</literal></entry>
1201                 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored. 
1202                   Currently-defined types are described below.
1203                 </entry>
1204               </row>
1205               <row>
1206                 <entry>3rd <literal>BYTE</literal></entry>
1207                 <entry>Bitwise OR of flags. Unknown flags
1208                   must be ignored. Currently-defined flags are described below.
1209                 </entry>
1210               </row>
1211               <row>
1212                 <entry>4th <literal>BYTE</literal></entry>
1213                 <entry>Major protocol version of the sending application.  If
1214                 the major protocol version of the receiving application does not
1215                 match, the applications will not be able to communicate and the
1216                 D-Bus connection must be disconnected. The major protocol
1217                 version for this version of the specification is 1.
1218                 </entry>
1219               </row>
1220               <row>
1221                 <entry>1st <literal>UINT32</literal></entry>
1222                 <entry>Length in bytes of the message body, starting 
1223                   from the end of the header. The header ends after 
1224                   its alignment padding to an 8-boundary.
1225                 </entry>
1226               </row>
1227               <row>
1228                 <entry>2nd <literal>UINT32</literal></entry>
1229                 <entry>The serial of this message, used as a cookie 
1230                   by the sender to identify the reply corresponding
1231                   to this request. This must not be zero.
1232                 </entry>
1233               </row>      
1234               <row>
1235                 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
1236                 <entry>An array of zero or more <firstterm>header
1237                   fields</firstterm> where the byte is the field code, and the
1238                   variant is the field value. The message type determines 
1239                   which fields are required.
1240                 </entry>
1241               </row>
1242             </tbody>
1243           </tgroup>
1244         </informaltable>
1245       </para>
1246       <para>
1247         <firstterm>Message types</firstterm> that can appear in the second byte
1248         of the header are:
1249         <informaltable>
1250           <tgroup cols="3">
1251             <thead>
1252               <row>
1253                 <entry>Conventional name</entry>
1254                 <entry>Decimal value</entry>
1255                 <entry>Description</entry>
1256               </row>
1257             </thead>
1258             <tbody>
1259               <row>
1260                 <entry><literal>INVALID</literal></entry>
1261                 <entry>0</entry>
1262                 <entry>This is an invalid type.</entry>
1263               </row>
1264               <row>
1265                 <entry><literal>METHOD_CALL</literal></entry>
1266                 <entry>1</entry>
1267                 <entry>Method call.</entry>
1268               </row>
1269               <row>
1270                 <entry><literal>METHOD_RETURN</literal></entry>
1271                 <entry>2</entry>
1272                 <entry>Method reply with returned data.</entry>
1273               </row>
1274               <row>
1275                 <entry><literal>ERROR</literal></entry>
1276                 <entry>3</entry>
1277                 <entry>Error reply. If the first argument exists and is a
1278                 string, it is an error message.</entry>
1279               </row>
1280               <row>
1281                 <entry><literal>SIGNAL</literal></entry>
1282                 <entry>4</entry>
1283                 <entry>Signal emission.</entry>
1284               </row>
1285             </tbody>
1286           </tgroup>
1287         </informaltable>
1288       </para>
1289       <para>
1290         Flags that can appear in the third byte of the header:
1291         <informaltable>
1292           <tgroup cols="3">
1293             <thead>
1294               <row>
1295                 <entry>Conventional name</entry>
1296                 <entry>Hex value</entry>
1297                 <entry>Description</entry>
1298               </row>
1299             </thead>
1300             <tbody>
1301               <row>
1302                 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
1303                 <entry>0x1</entry>
1304                 <entry>This message does not expect method return replies or
1305                 error replies; the reply can be omitted as an
1306                 optimization. However, it is compliant with this specification
1307                 to return the reply despite this flag and the only harm 
1308                   from doing so is extra network traffic.
1309                 </entry>
1310               </row>
1311               <row>
1312                 <entry><literal>NO_AUTO_START</literal></entry>
1313                 <entry>0x2</entry>
1314                 <entry>The bus must not launch an owner
1315                   for the destination name in response to this message.
1316                 </entry>
1317               </row>
1318             </tbody>
1319           </tgroup>
1320         </informaltable>
1321       </para>
1322
1323       <sect3 id="message-protocol-header-fields">
1324         <title>Header Fields</title>
1325
1326         <para>
1327           The array at the end of the header contains <firstterm>header
1328           fields</firstterm>, where each field is a 1-byte field code followed
1329           by a field value. A header must contain the required header fields for
1330           its message type, and zero or more of any optional header
1331           fields. Future versions of this protocol specification may add new
1332           fields. Implementations must ignore fields they do not
1333           understand. Implementations must not invent their own header fields;
1334           only changes to this specification may introduce new header fields.
1335         </para>
1336
1337         <para>
1338           Again, if an implementation sees a header field code that it does not
1339           expect, it must ignore that field, as it will be part of a new
1340           (but compatible) version of this specification. This also applies 
1341           to known header fields appearing in unexpected messages, for 
1342           example: if a signal has a reply serial it must be ignored
1343           even though it has no meaning as of this version of the spec.
1344         </para>
1345
1346         <para>
1347           However, implementations must not send or accept known header fields
1348           with the wrong type stored in the field value. So for example a
1349           message with an <literal>INTERFACE</literal> field of type
1350           <literal>UINT32</literal> would be considered corrupt.
1351         </para>
1352
1353         <para>
1354           Here are the currently-defined header fields:
1355           <informaltable>
1356             <tgroup cols="5">
1357               <thead>
1358                 <row>
1359                   <entry>Conventional Name</entry>
1360                   <entry>Decimal Code</entry>
1361                   <entry>Type</entry>
1362                   <entry>Required In</entry>
1363                   <entry>Description</entry>
1364                 </row>
1365               </thead>
1366               <tbody>
1367                 <row>
1368                   <entry><literal>INVALID</literal></entry>
1369                   <entry>0</entry>
1370                   <entry>N/A</entry>
1371                   <entry>not allowed</entry>
1372                   <entry>Not a valid field name (error if it appears in a message)</entry>
1373                 </row>
1374                 <row>
1375                   <entry><literal>PATH</literal></entry>
1376                   <entry>1</entry>
1377                   <entry><literal>OBJECT_PATH</literal></entry>
1378                   <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1379                   <entry>The object to send a call to,
1380                     or the object a signal is emitted from.
1381                     The special path
1382                     <literal>/org/freedesktop/DBus/Local</literal> is reserved;
1383                     implementations should not send messages with this path,
1384                     and the reference implementation of the bus daemon will
1385                     disconnect any application that attempts to do so.
1386                   </entry>
1387                 </row>
1388                 <row>
1389                   <entry><literal>INTERFACE</literal></entry>
1390                   <entry>2</entry>
1391                   <entry><literal>STRING</literal></entry>
1392                   <entry><literal>SIGNAL</literal></entry>
1393                   <entry>
1394                     The interface to invoke a method call on, or 
1395                     that a signal is emitted from. Optional for 
1396                     method calls, required for signals.
1397                     The special interface
1398                     <literal>org.freedesktop.DBus.Local</literal> is reserved;
1399                     implementations should not send messages with this
1400                     interface, and the reference implementation of the bus
1401                     daemon will disconnect any application that attempts to
1402                     do so.
1403                   </entry>
1404                 </row>
1405                 <row>
1406                   <entry><literal>MEMBER</literal></entry>
1407                   <entry>3</entry>
1408                   <entry><literal>STRING</literal></entry>
1409                   <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1410                   <entry>The member, either the method name or signal name.</entry>
1411                 </row>
1412                 <row>
1413                   <entry><literal>ERROR_NAME</literal></entry>
1414                   <entry>4</entry>
1415                   <entry><literal>STRING</literal></entry>
1416                   <entry><literal>ERROR</literal></entry>
1417                   <entry>The name of the error that occurred, for errors</entry>
1418                 </row>
1419                 <row>
1420                   <entry><literal>REPLY_SERIAL</literal></entry>
1421                   <entry>5</entry>
1422                   <entry><literal>UINT32</literal></entry>
1423                   <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
1424                   <entry>The serial number of the message this message is a reply
1425                     to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
1426                 </row>
1427                 <row>
1428                   <entry><literal>DESTINATION</literal></entry>
1429                   <entry>6</entry>
1430                   <entry><literal>STRING</literal></entry>
1431                   <entry>optional</entry>
1432                   <entry>The name of the connection this message is intended for.
1433                     Only used in combination with the message bus, see 
1434                     <xref linkend="message-bus"/>.</entry>
1435                 </row>
1436                 <row>
1437                   <entry><literal>SENDER</literal></entry>
1438                   <entry>7</entry>
1439                   <entry><literal>STRING</literal></entry>
1440                   <entry>optional</entry>
1441                   <entry>Unique name of the sending connection.
1442                     The message bus fills in this field so it is reliable; the field is
1443                     only meaningful in combination with the message bus.</entry>
1444                 </row>
1445                 <row>
1446                   <entry><literal>SIGNATURE</literal></entry>
1447                   <entry>8</entry>
1448                   <entry><literal>SIGNATURE</literal></entry>
1449                   <entry>optional</entry>
1450                   <entry>The signature of the message body.
1451                   If omitted, it is assumed to be the 
1452                   empty signature "" (i.e. the body must be 0-length).</entry>
1453                 </row>
1454                 <row>
1455                   <entry><literal>UNIX_FDS</literal></entry>
1456                   <entry>9</entry>
1457                   <entry><literal>UINT32</literal></entry>
1458                   <entry>optional</entry>
1459                   <entry>The number of Unix file descriptors that
1460                   accompany the message.  If omitted, it is assumed
1461                   that no Unix file descriptors accompany the
1462                   message. The actual file descriptors need to be
1463                   transferred via platform specific mechanism
1464                   out-of-band. They must be sent at the same time as
1465                   part of the message itself. They may not be sent
1466                   before the first byte of the message itself is
1467                   transferred or after the last byte of the message
1468                   itself.</entry>
1469                 </row>
1470               </tbody>
1471             </tgroup>
1472           </informaltable>
1473         </para>
1474       </sect3>
1475     </sect2>
1476
1477     <sect2 id="message-protocol-names">
1478       <title>Valid Names</title>
1479       <para>
1480         The various names in D-Bus messages have some restrictions.
1481       </para>
1482       <para>
1483         There is a <firstterm>maximum name length</firstterm> 
1484         of 255 which applies to bus names, interfaces, and members. 
1485       </para>
1486       <sect3 id="message-protocol-names-interface">
1487         <title>Interface names</title>
1488         <para>
1489           Interfaces have names with type <literal>STRING</literal>, meaning that 
1490           they must be valid UTF-8. However, there are also some 
1491           additional restrictions that apply to interface names 
1492           specifically:
1493           <itemizedlist>
1494             <listitem><para>Interface names are composed of 1 or more elements separated by
1495                 a period ('.') character. All elements must contain at least 
1496                 one character.
1497                 </para>
1498             </listitem>
1499             <listitem><para>Each element must only contain the ASCII characters 
1500                 "[A-Z][a-z][0-9]_" and must not begin with a digit.
1501                 </para>
1502             </listitem>
1503
1504             <listitem><para>Interface names must contain at least one '.' (period)
1505               character (and thus at least two elements).
1506               </para></listitem>
1507
1508             <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
1509             <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
1510           </itemizedlist>
1511         </para>
1512
1513         <para>
1514           Interface names should start with the reversed DNS domain name of
1515           the author of the interface (in lower-case), like interface names
1516           in Java. It is conventional for the rest of the interface name
1517           to consist of words run together, with initial capital letters
1518           on all words ("CamelCase"). Several levels of hierarchy can be used.
1519           It is also a good idea to include the major version of the interface
1520           in the name, and increment it if incompatible changes are made;
1521           this way, a single object can implement several versions of an
1522           interface in parallel, if necessary.
1523         </para>
1524
1525         <para>
1526           For instance, if the owner of <literal>example.com</literal> is
1527           developing a D-Bus API for a music player, they might define
1528           interfaces called <literal>com.example.MusicPlayer1</literal>,
1529           <literal>com.example.MusicPlayer1.Track</literal> and
1530           <literal>com.example.MusicPlayer1.Seekable</literal>.
1531         </para>
1532
1533         <para>
1534           D-Bus does not distinguish between the concepts that would be
1535           called classes and interfaces in Java: either can be identified on
1536           D-Bus by an interface name.
1537         </para>
1538       </sect3>
1539       <sect3 id="message-protocol-names-bus">
1540         <title>Bus names</title>
1541         <para>
1542           Connections have one or more bus names associated with them.
1543           A connection has exactly one bus name that is a <firstterm>unique
1544             connection name</firstterm>. The unique connection name remains
1545           with the connection for its entire lifetime.
1546           A bus name is of type <literal>STRING</literal>,
1547           meaning that it must be valid UTF-8. However, there are also
1548           some additional restrictions that apply to bus names 
1549           specifically:
1550           <itemizedlist>
1551             <listitem><para>Bus names that start with a colon (':')
1552                 character are unique connection names. Other bus names
1553                 are called <firstterm>well-known bus names</firstterm>.
1554                 </para>
1555             </listitem>
1556             <listitem><para>Bus names are composed of 1 or more elements separated by
1557                 a period ('.') character. All elements must contain at least 
1558                 one character.
1559                 </para>
1560             </listitem>
1561             <listitem><para>Each element must only contain the ASCII characters 
1562                 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique
1563                 connection name may begin with a digit, elements in
1564                 other bus names must not begin with a digit.
1565                 </para>
1566             </listitem>
1567
1568             <listitem><para>Bus names must contain at least one '.' (period)
1569               character (and thus at least two elements).
1570               </para></listitem>
1571
1572             <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
1573             <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
1574           </itemizedlist>
1575         </para>
1576         <para>
1577           Note that the hyphen ('-') character is allowed in bus names but
1578           not in interface names.
1579         </para>
1580
1581         <para>
1582           Like <link linkend="message-protocol-names-interface">interface
1583             names</link>, well-known bus names should start with the
1584           reversed DNS domain name of the author of the interface (in
1585           lower-case), and it is conventional for the rest of the well-known
1586           bus name to consist of words run together, with initial
1587           capital letters. As with interface names, including a version
1588           number in well-known bus names is a good idea; it's possible to
1589           have the well-known bus name for more than one version
1590           simultaneously if backwards compatibility is required.
1591         </para>
1592
1593         <para>
1594           If a well-known bus name implies the presence of a "main" interface,
1595           that "main" interface is often given the same name as
1596           the well-known bus name, and situated at the corresponding object
1597           path. For instance, if the owner of <literal>example.com</literal>
1598           is developing a D-Bus API for a music player, they might define
1599           that any application that takes the well-known name
1600           <literal>com.example.MusicPlayer1</literal> should have an object
1601           at the object path <literal>/com/example/MusicPlayer1</literal>
1602           which implements the interface
1603           <literal>com.example.MusicPlayer1</literal>.
1604         </para>
1605       </sect3>
1606       <sect3 id="message-protocol-names-member">
1607         <title>Member names</title>
1608         <para>
1609           Member (i.e. method or signal) names:
1610           <itemizedlist>
1611             <listitem><para>Must only contain the ASCII characters
1612                 "[A-Z][a-z][0-9]_" and may not begin with a
1613                 digit.</para></listitem>
1614             <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1615             <listitem><para>Must not exceed the maximum name length.</para></listitem>
1616             <listitem><para>Must be at least 1 byte in length.</para></listitem>
1617           </itemizedlist>
1618         </para>
1619
1620         <para>
1621           It is conventional for member names on D-Bus to consist of
1622           capitalized words with no punctuation ("camel-case").
1623           Method names should usually be verbs, such as
1624           <literal>GetItems</literal>, and signal names should usually be
1625           a description of an event, such as <literal>ItemsChanged</literal>.
1626         </para>
1627       </sect3>
1628       <sect3 id="message-protocol-names-error">
1629         <title>Error names</title>
1630         <para>
1631           Error names have the same restrictions as interface names.
1632         </para>
1633
1634         <para>
1635           Error names have the same naming conventions as interface
1636           names, and often contain <literal>.Error.</literal>; for instance,
1637           the owner of <literal>example.com</literal> might define the
1638           errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
1639           and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
1640           The errors defined by D-Bus itself, such as
1641           <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
1642           similar pattern.
1643         </para>
1644       </sect3>
1645     </sect2>
1646
1647     <sect2 id="message-protocol-types">
1648       <title>Message Types</title>
1649       <para>
1650         Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1651         <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1652         This section describes these conventions.
1653       </para>
1654       <sect3 id="message-protocol-types-method">
1655         <title>Method Calls</title>
1656         <para>
1657           Some messages invoke an operation on a remote object.  These are
1658           called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1659           messages map naturally to methods on objects in a typical program.
1660         </para>
1661         <para>
1662           A method call message is required to have a <literal>MEMBER</literal> header field
1663           indicating the name of the method. Optionally, the message has an
1664           <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1665           absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1666           a method with the same name, it is undefined which of the two methods
1667           will be invoked. Implementations may also choose to return an error in
1668           this ambiguous case. However, if a method name is unique
1669           implementations must not require an interface field.
1670         </para>
1671         <para>
1672           Method call messages also include a <literal>PATH</literal> field
1673           indicating the object to invoke the method on. If the call is passing
1674           through a message bus, the message will also have a
1675           <literal>DESTINATION</literal> field giving the name of the connection
1676           to receive the message.
1677         </para>
1678         <para>
1679           When an application handles a method call message, it is required to
1680           return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1681           indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1682           reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1683         </para>
1684         <para>
1685           If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message 
1686           are the return value(s) or "out parameters" of the method call. 
1687           If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown, 
1688           and the call fails; no return value will be provided. It makes 
1689           no sense to send multiple replies to the same method call.
1690         </para>
1691         <para>
1692           Even if a method call has no return values, a <literal>METHOD_RETURN</literal> 
1693           reply is required, so the caller will know the method 
1694           was successfully processed.
1695         </para>
1696         <para>
1697           The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal> 
1698           header field.
1699         </para>
1700         <para>
1701           If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>, 
1702           then as an optimization the application receiving the method 
1703           call may choose to omit the reply message (regardless of 
1704           whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>). 
1705           However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1706           flag and reply anyway.
1707         </para>
1708         <para>
1709           Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1710           destination name does not exist then a program to own the destination
1711           name will be started before the message is delivered.  The message
1712           will be held until the new program is successfully started or has
1713           failed to start; in case of failure, an error will be returned. This
1714           flag is only relevant in the context of a message bus, it is ignored
1715           during one-to-one communication with no intermediate bus.
1716         </para>
1717         <sect4 id="message-protocol-types-method-apis">
1718           <title>Mapping method calls to native APIs</title>
1719           <para>
1720             APIs for D-Bus may map method calls to a method call in a specific
1721             programming language, such as C++, or may map a method call written
1722             in an IDL to a D-Bus message.
1723           </para>
1724           <para>
1725             In APIs of this nature, arguments to a method are often termed "in"
1726             (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1727             returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1728             "inout" arguments, which are both sent and received, i.e. the caller
1729             passes in a value which is modified. Mapped to D-Bus, an "inout"
1730             argument is equivalent to an "in" argument, followed by an "out"
1731             argument. You can't pass things "by reference" over the wire, so
1732             "inout" is purely an illusion of the in-process API.
1733           </para>
1734           <para>
1735             Given a method with zero or one return values, followed by zero or more
1736             arguments, where each argument may be "in", "out", or "inout", the
1737             caller constructs a message by appending each "in" or "inout" argument,
1738             in order. "out" arguments are not represented in the caller's message.
1739           </para>
1740           <para>
1741             The recipient constructs a reply by appending first the return value 
1742             if any, then each "out" or "inout" argument, in order. 
1743             "in" arguments are not represented in the reply message.
1744           </para>
1745           <para>
1746             Error replies are normally mapped to exceptions in languages that have
1747             exceptions.
1748           </para>
1749           <para>
1750             In converting from native APIs to D-Bus, it is perhaps nice to 
1751             map D-Bus naming conventions ("FooBar") to native conventions 
1752             such as "fooBar" or "foo_bar" automatically. This is OK 
1753             as long as you can say that the native API is one that 
1754             was specifically written for D-Bus. It makes the most sense
1755             when writing object implementations that will be exported 
1756             over the bus. Object proxies used to invoke remote D-Bus 
1757             objects probably need the ability to call any D-Bus method,
1758             and thus a magic name mapping like this could be a problem.
1759           </para>
1760           <para>
1761             This specification doesn't require anything of native API bindings;
1762             the preceding is only a suggested convention for consistency 
1763             among bindings.
1764           </para>
1765         </sect4>
1766       </sect3>
1767
1768       <sect3 id="message-protocol-types-signal">
1769         <title>Signal Emission</title>
1770         <para>
1771           Unlike method calls, signal emissions have no replies. 
1772           A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1773           It must have three header fields: <literal>PATH</literal> giving the object 
1774           the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1775           the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
1776           for signals, though it is optional for method calls.
1777         </para>
1778       </sect3>
1779
1780       <sect3 id="message-protocol-types-errors">
1781         <title>Errors</title>
1782         <para>
1783           Messages of type <literal>ERROR</literal> are most commonly replies 
1784           to a <literal>METHOD_CALL</literal>, but may be returned in reply 
1785           to any kind of message. The message bus for example
1786           will return an <literal>ERROR</literal> in reply to a signal emission if 
1787           the bus does not have enough memory to send the signal.
1788         </para>
1789         <para>
1790           An <literal>ERROR</literal> may have any arguments, but if the first 
1791           argument is a <literal>STRING</literal>, it must be an error message.
1792           The error message may be logged or shown to the user
1793           in some way.
1794         </para>
1795       </sect3>
1796
1797       <sect3 id="message-protocol-types-notation">
1798         <title>Notation in this document</title>
1799         <para>
1800           This document uses a simple pseudo-IDL to describe particular method 
1801           calls and signals. Here is an example of a method call:
1802           <programlisting>
1803             org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1804                                                      out UINT32 resultcode)
1805           </programlisting>
1806           This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName, 
1807           <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1808           is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1809           characters so it's known that the last part of the name in
1810           the "IDL" is the member name.
1811         </para>
1812         <para>
1813           In C++ that might end up looking like this:
1814           <programlisting>
1815             unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
1816                                                                      unsigned int flags);
1817           </programlisting>
1818           or equally valid, the return value could be done as an argument:
1819           <programlisting>
1820             void org::freedesktop::DBus::StartServiceByName (const char   *name, 
1821                                                              unsigned int  flags,
1822                                                              unsigned int *resultcode);
1823           </programlisting>
1824           It's really up to the API designer how they want to make 
1825           this look. You could design an API where the namespace wasn't used 
1826           in C++, using STL or Qt, using varargs, or whatever you wanted.
1827         </para>
1828         <para>
1829           Signals are written as follows:
1830           <programlisting>
1831             org.freedesktop.DBus.NameLost (STRING name)
1832           </programlisting>
1833           Signals don't specify "in" vs. "out" because only 
1834           a single direction is possible.
1835         </para>
1836         <para>
1837           It isn't especially encouraged to use this lame pseudo-IDL in actual
1838           API implementations; you might use the native notation for the
1839           language you're using, or you might use COM or CORBA IDL, for example.
1840         </para>
1841       </sect3>
1842     </sect2>
1843
1844     <sect2 id="message-protocol-handling-invalid">
1845       <title>Invalid Protocol and Spec Extensions</title>
1846       
1847       <para>
1848         For security reasons, the D-Bus protocol should be strictly parsed and
1849         validated, with the exception of defined extension points. Any invalid
1850         protocol or spec violations should result in immediately dropping the
1851         connection without notice to the other end. Exceptions should be
1852         carefully considered, e.g. an exception may be warranted for a
1853         well-understood idiosyncrasy of a widely-deployed implementation.  In
1854         cases where the other end of a connection is 100% trusted and known to
1855         be friendly, skipping validation for performance reasons could also make
1856         sense in certain cases.
1857       </para>
1858
1859       <para>
1860         Generally speaking violations of the "must" requirements in this spec 
1861         should be considered possible attempts to exploit security, and violations 
1862         of the "should" suggestions should be considered legitimate (though perhaps
1863         they should generate an error in some cases).
1864       </para>
1865
1866       <para>
1867         The following extension points are built in to D-Bus on purpose and must
1868         not be treated as invalid protocol. The extension points are intended
1869         for use by future versions of this spec, they are not intended for third
1870         parties.  At the moment, the only way a third party could extend D-Bus
1871         without breaking interoperability would be to introduce a way to negotiate new
1872         feature support as part of the auth protocol, using EXTENSION_-prefixed
1873         commands. There is not yet a standard way to negotiate features.
1874         <itemizedlist>
1875           <listitem>
1876             <para>
1877               In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown 
1878                 commands result in an ERROR rather than a disconnect. This enables 
1879                 future extensions to the protocol. Commands starting with EXTENSION_ are 
1880                 reserved for third parties.
1881             </para>
1882           </listitem>
1883           <listitem>
1884             <para>
1885               The authentication protocol supports pluggable auth mechanisms.
1886             </para>
1887           </listitem>
1888           <listitem>
1889             <para>
1890               The address format (see <xref linkend="addresses"/>) supports new
1891               kinds of transport.
1892             </para>
1893           </listitem>
1894           <listitem>
1895             <para>
1896               Messages with an unknown type (something other than
1897               <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
1898               <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored. 
1899               Unknown-type messages must still be well-formed in the same way 
1900               as the known messages, however. They still have the normal 
1901               header and body.
1902             </para>
1903           </listitem>
1904           <listitem>
1905             <para>
1906               Header fields with an unknown or unexpected field code must be ignored, 
1907               though again they must still be well-formed.
1908             </para>
1909           </listitem>
1910           <listitem>
1911             <para>
1912               New standard interfaces (with new methods and signals) can of course be added.
1913             </para>
1914           </listitem>
1915         </itemizedlist>
1916       </para>
1917
1918     </sect2>
1919
1920   </sect1>
1921
1922   <sect1 id="auth-protocol">
1923     <title>Authentication Protocol</title>
1924     <para>
1925       Before the flow of messages begins, two applications must
1926       authenticate. A simple plain-text protocol is used for
1927       authentication; this protocol is a SASL profile, and maps fairly
1928       directly from the SASL specification. The message encoding is
1929       NOT used here, only plain text messages.
1930     </para>
1931     <para>
1932       In examples, "C:" and "S:" indicate lines sent by the client and
1933       server respectively.
1934     </para>
1935     <sect2 id="auth-protocol-overview">
1936       <title>Protocol Overview</title>
1937       <para>
1938         The protocol is a line-based protocol, where each line ends with
1939         \r\n. Each line begins with an all-caps ASCII command name containing
1940         only the character range [A-Z_], a space, then any arguments for the
1941         command, then the \r\n ending the line. The protocol is
1942         case-sensitive. All bytes must be in the ASCII character set.
1943
1944         Commands from the client to the server are as follows:
1945
1946         <itemizedlist>
1947           <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1948           <listitem><para>CANCEL</para></listitem>
1949           <listitem><para>BEGIN</para></listitem>
1950           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1951           <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1952           <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
1953         </itemizedlist>
1954
1955         From server to client are as follows:
1956
1957         <itemizedlist>
1958           <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
1959           <listitem><para>OK &lt;GUID in hex&gt;</para></listitem>
1960           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1961           <listitem><para>ERROR</para></listitem>
1962           <listitem><para>AGREE_UNIX_FD</para></listitem>
1963         </itemizedlist>
1964       </para>
1965       <para>
1966         Unofficial extensions to the command set must begin with the letters 
1967         "EXTENSION_", to avoid conflicts with future official commands.
1968         For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
1969       </para>
1970     </sect2>
1971     <sect2 id="auth-nul-byte">
1972       <title>Special credentials-passing nul byte</title>
1973       <para>
1974         Immediately after connecting to the server, the client must send a
1975         single nul byte. This byte may be accompanied by credentials
1976         information on some operating systems that use sendmsg() with
1977         SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1978         sockets. However, the nul byte must be sent even on other kinds of
1979         socket, and even on operating systems that do not require a byte to be
1980         sent in order to transmit credentials. The text protocol described in
1981         this document begins after the single nul byte. If the first byte
1982         received from the client is not a nul byte, the server may disconnect 
1983         that client.
1984       </para>
1985       <para>
1986         A nul byte in any context other than the initial byte is an error; 
1987         the protocol is ASCII-only.
1988       </para>
1989       <para>
1990         The credentials sent along with the nul byte may be used with the 
1991         SASL mechanism EXTERNAL.
1992       </para>
1993     </sect2>
1994     <sect2 id="auth-command-auth">
1995       <title>AUTH command</title>
1996       <para>
1997         If an AUTH command has no arguments, it is a request to list
1998         available mechanisms. The server must respond with a REJECTED
1999         command listing the mechanisms it understands, or with an error.
2000       </para>
2001       <para>
2002         If an AUTH command specifies a mechanism, and the server supports
2003         said mechanism, the server should begin exchanging SASL
2004         challenge-response data with the client using DATA commands.
2005       </para>
2006       <para>
2007         If the server does not support the mechanism given in the AUTH
2008         command, it must send either a REJECTED command listing the mechanisms
2009         it does support, or an error.
2010       </para>
2011       <para>
2012         If the [initial-response] argument is provided, it is intended for use
2013         with mechanisms that have no initial challenge (or an empty initial
2014         challenge), as if it were the argument to an initial DATA command. If
2015         the selected mechanism has an initial challenge and [initial-response]
2016         was provided, the server should reject authentication by sending
2017         REJECTED.
2018       </para>
2019       <para>
2020         If authentication succeeds after exchanging DATA commands, 
2021         an OK command must be sent to the client.
2022       </para>
2023       <para>
2024         The first octet received by the server after the \r\n of the BEGIN
2025         command from the client must be the first octet of the
2026         authenticated/encrypted stream of D-Bus messages.
2027       </para>
2028       <para>
2029         If BEGIN is received by the server, the first octet received
2030         by the client after the \r\n of the OK command must be the
2031         first octet of the authenticated/encrypted stream of D-Bus
2032         messages.
2033       </para>
2034     </sect2>
2035     <sect2 id="auth-command-cancel">
2036       <title>CANCEL Command</title>
2037       <para>
2038         At any time up to sending the BEGIN command, the client may send a
2039         CANCEL command. On receiving the CANCEL command, the server must
2040         send a REJECTED command and abort the current authentication
2041         exchange.
2042       </para>
2043     </sect2>
2044     <sect2 id="auth-command-data">
2045       <title>DATA Command</title>
2046       <para>
2047         The DATA command may come from either client or server, and simply 
2048         contains a hex-encoded block of data to be interpreted 
2049         according to the SASL mechanism in use.
2050       </para>
2051       <para>
2052         Some SASL mechanisms support sending an "empty string"; 
2053         FIXME we need some way to do this.
2054       </para>
2055     </sect2>
2056     <sect2 id="auth-command-begin">
2057       <title>BEGIN Command</title>
2058       <para>
2059         The BEGIN command acknowledges that the client has received an 
2060         OK command from the server, and that the stream of messages
2061         is about to begin. 
2062       </para>
2063       <para>
2064         The first octet received by the server after the \r\n of the BEGIN
2065         command from the client must be the first octet of the
2066         authenticated/encrypted stream of D-Bus messages.
2067       </para>
2068     </sect2>
2069     <sect2 id="auth-command-rejected">
2070       <title>REJECTED Command</title>
2071       <para>
2072         The REJECTED command indicates that the current authentication
2073         exchange has failed, and further exchange of DATA is inappropriate.
2074         The client would normally try another mechanism, or try providing
2075         different responses to challenges.
2076       </para><para>
2077         Optionally, the REJECTED command has a space-separated list of
2078         available auth mechanisms as arguments. If a server ever provides
2079         a list of supported mechanisms, it must provide the same list 
2080         each time it sends a REJECTED message. Clients are free to 
2081         ignore all lists received after the first.
2082       </para>
2083     </sect2>
2084     <sect2 id="auth-command-ok">
2085       <title>OK Command</title>
2086       <para>
2087         The OK command indicates that the client has been
2088         authenticated. The client may now proceed with negotiating
2089         Unix file descriptor passing. To do that it shall send
2090         NEGOTIATE_UNIX_FD to the server.
2091       </para>
2092       <para>
2093         Otherwise, the client must respond to the OK command by
2094         sending a BEGIN command, followed by its stream of messages,
2095         or by disconnecting.  The server must not accept additional
2096         commands using this protocol after the BEGIN command has been
2097         received. Further communication will be a stream of D-Bus
2098         messages (optionally encrypted, as negotiated) rather than
2099         this protocol.
2100       </para>
2101       <para>
2102         If a client sends BEGIN the first octet received by the client
2103         after the \r\n of the OK command must be the first octet of
2104         the authenticated/encrypted stream of D-Bus messages.
2105       </para>
2106       <para>
2107         The OK command has one argument, which is the GUID of the server.
2108         See <xref linkend="addresses"/> for more on server GUIDs.
2109       </para>
2110     </sect2>
2111     <sect2 id="auth-command-error">
2112       <title>ERROR Command</title>
2113       <para>
2114         The ERROR command indicates that either server or client did not
2115         know a command, does not accept the given command in the current
2116         context, or did not understand the arguments to the command. This
2117         allows the protocol to be extended; a client or server can send a
2118         command present or permitted only in new protocol versions, and if
2119         an ERROR is received instead of an appropriate response, fall back
2120         to using some other technique.
2121       </para>
2122       <para>
2123         If an ERROR is sent, the server or client that sent the
2124         error must continue as if the command causing the ERROR had never been
2125         received. However, the the server or client receiving the error 
2126         should try something other than whatever caused the error; 
2127         if only canceling/rejecting the authentication.
2128       </para>
2129       <para>
2130         If the D-Bus protocol changes incompatibly at some future time,
2131         applications implementing the new protocol would probably be able to
2132         check for support of the new protocol by sending a new command and
2133         receiving an ERROR from applications that don't understand it. Thus the
2134         ERROR feature of the auth protocol is an escape hatch that lets us
2135         negotiate extensions or changes to the D-Bus protocol in the future.
2136       </para>
2137     </sect2>
2138     <sect2 id="auth-command-negotiate-unix-fd">
2139       <title>NEGOTIATE_UNIX_FD Command</title>
2140       <para>
2141         The NEGOTIATE_UNIX_FD command indicates that the client
2142         supports Unix file descriptor passing. This command may only
2143         be sent after the connection is authenticated, i.e. after OK
2144         was received by the client. This command may only be sent on
2145         transports that support Unix file descriptor passing.
2146       </para>
2147       <para>
2148         On receiving NEGOTIATE_UNIX_FD the server must respond with
2149         either AGREE_UNIX_FD or ERROR. It shall respond the former if
2150         the transport chosen supports Unix file descriptor passing and
2151         the server supports this feature. It shall respond the latter
2152         if the transport does not support Unix file descriptor
2153         passing, the server does not support this feature, or the
2154         server decides not to enable file descriptor passing due to
2155         security or other reasons.
2156       </para>
2157     </sect2>
2158     <sect2 id="auth-command-agree-unix-fd">
2159       <title>AGREE_UNIX_FD Command</title>
2160       <para>
2161         The AGREE_UNIX_FD command indicates that the server supports
2162         Unix file descriptor passing. This command may only be sent
2163         after the connection is authenticated, and the client sent
2164         NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
2165         command may only be sent on transports that support Unix file
2166         descriptor passing.
2167       </para>
2168       <para>
2169         On receiving AGREE_UNIX_FD the client must respond with BEGIN,
2170         followed by its stream of messages, or by disconnecting.  The
2171         server must not accept additional commands using this protocol
2172         after the BEGIN command has been received. Further
2173         communication will be a stream of D-Bus messages (optionally
2174         encrypted, as negotiated) rather than this protocol.
2175       </para>
2176     </sect2>
2177     <sect2 id="auth-command-future">
2178       <title>Future Extensions</title>
2179       <para>
2180         Future extensions to the authentication and negotiation
2181         protocol are possible. For that new commands may be
2182         introduced. If a client or server receives an unknown command
2183         it shall respond with ERROR and not consider this fatal. New
2184         commands may be introduced both before, and after
2185         authentication, i.e. both before and after the OK command.
2186       </para>
2187     </sect2>
2188     <sect2 id="auth-examples">
2189       <title>Authentication examples</title>
2190       
2191       <para>
2192         <figure>
2193           <title>Example of successful magic cookie authentication</title>
2194           <programlisting>
2195             (MAGIC_COOKIE is a made up mechanism)
2196
2197             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2198             S: OK 1234deadbeef
2199             C: BEGIN
2200           </programlisting>
2201         </figure>
2202         <figure>
2203           <title>Example of finding out mechanisms then picking one</title>
2204           <programlisting>
2205             C: AUTH
2206             S: REJECTED KERBEROS_V4 SKEY
2207             C: AUTH SKEY 7ab83f32ee
2208             S: DATA 8799cabb2ea93e
2209             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2210             S: OK 1234deadbeef
2211             C: BEGIN
2212           </programlisting>
2213         </figure>
2214         <figure>
2215           <title>Example of client sends unknown command then falls back to regular auth</title>
2216           <programlisting>
2217             C: FOOBAR
2218             S: ERROR
2219             C: AUTH MAGIC_COOKIE 3736343435313230333039
2220             S: OK 1234deadbeef
2221             C: BEGIN
2222           </programlisting>
2223         </figure>
2224         <figure>
2225           <title>Example of server doesn't support initial auth mechanism</title>
2226           <programlisting>
2227             C: AUTH MAGIC_COOKIE 3736343435313230333039
2228             S: REJECTED KERBEROS_V4 SKEY
2229             C: AUTH SKEY 7ab83f32ee
2230             S: DATA 8799cabb2ea93e
2231             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2232             S: OK 1234deadbeef
2233             C: BEGIN
2234           </programlisting>
2235         </figure>
2236         <figure>
2237           <title>Example of wrong password or the like followed by successful retry</title>
2238           <programlisting>
2239             C: AUTH MAGIC_COOKIE 3736343435313230333039
2240             S: REJECTED KERBEROS_V4 SKEY
2241             C: AUTH SKEY 7ab83f32ee
2242             S: DATA 8799cabb2ea93e
2243             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2244             S: REJECTED
2245             C: AUTH SKEY 7ab83f32ee
2246             S: DATA 8799cabb2ea93e
2247             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2248             S: OK 1234deadbeef
2249             C: BEGIN
2250           </programlisting>
2251         </figure>
2252         <figure>
2253           <title>Example of skey cancelled and restarted</title>
2254           <programlisting>
2255             C: AUTH MAGIC_COOKIE 3736343435313230333039
2256             S: REJECTED KERBEROS_V4 SKEY
2257             C: AUTH SKEY 7ab83f32ee
2258             S: DATA 8799cabb2ea93e
2259             C: CANCEL
2260             S: REJECTED
2261             C: AUTH SKEY 7ab83f32ee
2262             S: DATA 8799cabb2ea93e
2263             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2264             S: OK 1234deadbeef
2265             C: BEGIN
2266           </programlisting>
2267         </figure>
2268         <figure>
2269           <title>Example of successful magic cookie authentication with successful negotiation of Unix FD passing</title>
2270           <programlisting>
2271             (MAGIC_COOKIE is a made up mechanism)
2272
2273             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2274             S: OK 1234deadbeef
2275             C: NEGOTIATE_UNIX_FD
2276             S: AGREE_UNIX_FD
2277             C: BEGIN
2278           </programlisting>
2279         </figure>
2280         <figure>
2281           <title>Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</title>
2282           <programlisting>
2283             (MAGIC_COOKIE is a made up mechanism)
2284
2285             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
2286             S: OK 1234deadbeef
2287             C: NEGOTIATE_UNIX_FD
2288             S: ERROR
2289             C: BEGIN
2290           </programlisting>
2291         </figure>
2292       </para>
2293     </sect2>
2294     <sect2 id="auth-states">
2295       <title>Authentication state diagrams</title>
2296       
2297       <para>
2298         This section documents the auth protocol in terms of 
2299         a state machine for the client and the server. This is 
2300         probably the most robust way to implement the protocol.
2301       </para>
2302
2303       <sect3 id="auth-states-client">
2304         <title>Client states</title>
2305         
2306         <para>
2307           To more precisely describe the interaction between the
2308           protocol state machine and the authentication mechanisms the
2309           following notation is used: MECH(CHALL) means that the
2310           server challenge CHALL was fed to the mechanism MECH, which
2311           returns one of
2312
2313           <itemizedlist>
2314             <listitem>
2315               <para>
2316                 CONTINUE(RESP) means continue the auth conversation
2317                 and send RESP as the response to the server;
2318               </para>
2319             </listitem>
2320
2321             <listitem>
2322               <para>
2323                 OK(RESP) means that after sending RESP to the server
2324                 the client side of the auth conversation is finished
2325                 and the server should return "OK";
2326               </para>
2327             </listitem>
2328
2329             <listitem>
2330               <para>
2331                 ERROR means that CHALL was invalid and could not be
2332                 processed.
2333               </para>
2334             </listitem>
2335           </itemizedlist>
2336           
2337           Both RESP and CHALL may be empty.
2338         </para>
2339         
2340         <para>
2341           The Client starts by getting an initial response from the
2342           default mechanism and sends AUTH MECH RESP, or AUTH MECH if
2343           the mechanism did not provide an initial response.  If the
2344           mechanism returns CONTINUE, the client starts in state
2345           <emphasis>WaitingForData</emphasis>, if the mechanism
2346           returns OK the client starts in state
2347           <emphasis>WaitingForOK</emphasis>.
2348         </para>
2349         
2350         <para>
2351           The client should keep track of available mechanisms and
2352           which it mechanisms it has already attempted. This list is
2353           used to decide which AUTH command to send. When the list is
2354           exhausted, the client should give up and close the
2355           connection.
2356         </para>
2357
2358         <formalpara>
2359           <title><emphasis>WaitingForData</emphasis></title>
2360           <para>
2361             <itemizedlist>
2362               <listitem>
2363                 <para>
2364                   Receive DATA CHALL
2365                   <simplelist>
2366                     <member>
2367                       MECH(CHALL) returns CONTINUE(RESP) &rarr; send
2368                       DATA RESP, goto
2369                       <emphasis>WaitingForData</emphasis>
2370                     </member>
2371
2372                     <member>
2373                       MECH(CHALL) returns OK(RESP) &rarr; send DATA
2374                       RESP, goto <emphasis>WaitingForOK</emphasis>
2375                     </member>
2376
2377                     <member>
2378                       MECH(CHALL) returns ERROR &rarr; send ERROR
2379                       [msg], goto <emphasis>WaitingForData</emphasis>
2380                     </member>
2381                   </simplelist>
2382                 </para>
2383               </listitem>
2384
2385               <listitem>
2386                 <para>
2387                   Receive REJECTED [mechs] &rarr;
2388                   send AUTH [next mech], goto
2389                   WaitingForData or <emphasis>WaitingForOK</emphasis>
2390                 </para>
2391               </listitem>
2392               <listitem>
2393                 <para>
2394                   Receive ERROR &rarr; send
2395                   CANCEL, goto
2396                   <emphasis>WaitingForReject</emphasis>
2397                 </para>
2398               </listitem>
2399               <listitem>
2400                 <para>
2401                   Receive OK &rarr; send
2402                   BEGIN, terminate auth
2403                   conversation, authenticated
2404                 </para>
2405               </listitem>
2406               <listitem>
2407                 <para>
2408                   Receive anything else &rarr; send
2409                   ERROR, goto
2410                   <emphasis>WaitingForData</emphasis>
2411                 </para>
2412               </listitem>
2413             </itemizedlist>
2414           </para>
2415         </formalpara>
2416
2417         <formalpara>
2418           <title><emphasis>WaitingForOK</emphasis></title>
2419           <para>
2420             <itemizedlist>
2421               <listitem>
2422                 <para>
2423                   Receive OK &rarr; send BEGIN, terminate auth
2424                   conversation, <emphasis>authenticated</emphasis>
2425                 </para>
2426               </listitem>
2427               <listitem>
2428                 <para>
2429                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
2430                   goto <emphasis>WaitingForData</emphasis> or
2431                   <emphasis>WaitingForOK</emphasis>
2432                 </para>
2433               </listitem>
2434
2435               <listitem>
2436                 <para>
2437                   Receive DATA &rarr; send CANCEL, goto
2438                   <emphasis>WaitingForReject</emphasis>
2439                 </para>
2440               </listitem>
2441
2442               <listitem>
2443                 <para>
2444                   Receive ERROR &rarr; send CANCEL, goto
2445                   <emphasis>WaitingForReject</emphasis>
2446                 </para>
2447               </listitem>
2448
2449               <listitem>
2450                 <para>
2451                   Receive anything else &rarr; send ERROR, goto
2452                   <emphasis>WaitingForOK</emphasis>
2453                 </para>
2454               </listitem>
2455             </itemizedlist>
2456           </para>
2457         </formalpara>
2458
2459         <formalpara>
2460           <title><emphasis>WaitingForReject</emphasis></title>
2461           <para>
2462             <itemizedlist>
2463               <listitem>
2464                 <para>
2465                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
2466                   goto <emphasis>WaitingForData</emphasis> or
2467                   <emphasis>WaitingForOK</emphasis>
2468                 </para>
2469               </listitem>
2470
2471               <listitem>
2472                 <para>
2473                   Receive anything else &rarr; terminate auth
2474                   conversation, disconnect
2475                 </para>
2476               </listitem>
2477             </itemizedlist>
2478           </para>
2479         </formalpara>
2480
2481       </sect3>
2482
2483       <sect3 id="auth-states-server">
2484         <title>Server states</title>
2485  
2486         <para>
2487           For the server MECH(RESP) means that the client response
2488           RESP was fed to the the mechanism MECH, which returns one of
2489
2490           <itemizedlist>
2491             <listitem>
2492               <para>
2493                 CONTINUE(CHALL) means continue the auth conversation and
2494                 send CHALL as the challenge to the client;
2495               </para>
2496             </listitem>
2497
2498             <listitem>
2499               <para>
2500                 OK means that the client has been successfully
2501                 authenticated;
2502               </para>
2503             </listitem>
2504
2505             <listitem>
2506               <para>
2507                 REJECT means that the client failed to authenticate or
2508                 there was an error in RESP.
2509               </para>
2510             </listitem>
2511           </itemizedlist>
2512
2513           The server starts out in state
2514           <emphasis>WaitingForAuth</emphasis>.  If the client is
2515           rejected too many times the server must disconnect the
2516           client.
2517         </para>
2518
2519         <formalpara>
2520           <title><emphasis>WaitingForAuth</emphasis></title>
2521           <para>
2522             <itemizedlist>
2523
2524               <listitem>
2525                 <para>
2526                   Receive AUTH &rarr; send REJECTED [mechs], goto
2527                   <emphasis>WaitingForAuth</emphasis>
2528                 </para>
2529               </listitem>
2530
2531               <listitem>
2532                 <para>
2533                   Receive AUTH MECH RESP
2534
2535                   <simplelist>
2536                     <member>
2537                       MECH not valid mechanism &rarr; send REJECTED
2538                       [mechs], goto
2539                       <emphasis>WaitingForAuth</emphasis>
2540                     </member>
2541
2542                     <member>
2543                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
2544                       DATA CHALL, goto
2545                       <emphasis>WaitingForData</emphasis>
2546                     </member>
2547
2548                     <member>
2549                       MECH(RESP) returns OK &rarr; send OK, goto
2550                       <emphasis>WaitingForBegin</emphasis>
2551                     </member>
2552
2553                     <member>
2554                       MECH(RESP) returns REJECT &rarr; send REJECTED
2555                       [mechs], goto
2556                       <emphasis>WaitingForAuth</emphasis>
2557                     </member>
2558                   </simplelist>
2559                 </para>
2560               </listitem>
2561
2562               <listitem>
2563                 <para>
2564                   Receive BEGIN &rarr; terminate
2565                   auth conversation, disconnect
2566                 </para>
2567               </listitem>
2568
2569               <listitem>
2570                 <para>
2571                   Receive ERROR &rarr; send REJECTED [mechs], goto
2572                   <emphasis>WaitingForAuth</emphasis>
2573                 </para>
2574               </listitem>
2575
2576               <listitem>
2577                 <para>
2578                   Receive anything else &rarr; send
2579                   ERROR, goto
2580                   <emphasis>WaitingForAuth</emphasis>
2581                 </para>
2582               </listitem>
2583             </itemizedlist>
2584           </para>
2585         </formalpara>
2586
2587        
2588         <formalpara>
2589           <title><emphasis>WaitingForData</emphasis></title>
2590           <para>
2591             <itemizedlist>
2592               <listitem>
2593                 <para>
2594                   Receive DATA RESP
2595                   <simplelist>
2596                     <member>
2597                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
2598                       DATA CHALL, goto
2599                       <emphasis>WaitingForData</emphasis>
2600                     </member>
2601
2602                     <member>
2603                       MECH(RESP) returns OK &rarr; send OK, goto
2604                       <emphasis>WaitingForBegin</emphasis>
2605                     </member>
2606
2607                     <member>
2608                       MECH(RESP) returns REJECT &rarr; send REJECTED
2609                       [mechs], goto
2610                       <emphasis>WaitingForAuth</emphasis>
2611                     </member>
2612                   </simplelist>
2613                 </para>
2614               </listitem>
2615
2616               <listitem>
2617                 <para>
2618                   Receive BEGIN &rarr; terminate auth conversation,
2619                   disconnect
2620                 </para>
2621               </listitem>
2622
2623               <listitem>
2624                 <para>
2625                   Receive CANCEL &rarr; send REJECTED [mechs], goto
2626                   <emphasis>WaitingForAuth</emphasis>
2627                 </para>
2628               </listitem>
2629
2630               <listitem>
2631                 <para>
2632                   Receive ERROR &rarr; send REJECTED [mechs], goto
2633                   <emphasis>WaitingForAuth</emphasis>
2634                 </para>
2635               </listitem>
2636
2637               <listitem>
2638                 <para>
2639                   Receive anything else &rarr; send ERROR, goto
2640                   <emphasis>WaitingForData</emphasis>
2641                 </para>
2642               </listitem>
2643             </itemizedlist>
2644           </para>
2645         </formalpara>
2646
2647         <formalpara>
2648           <title><emphasis>WaitingForBegin</emphasis></title>
2649           <para>
2650             <itemizedlist>
2651               <listitem>
2652                 <para>
2653                   Receive BEGIN &rarr; terminate auth conversation,
2654                   client authenticated
2655                 </para>
2656               </listitem>
2657
2658               <listitem>
2659                 <para>
2660                   Receive CANCEL &rarr; send REJECTED [mechs], goto
2661                   <emphasis>WaitingForAuth</emphasis>
2662                 </para>
2663               </listitem>
2664
2665               <listitem>
2666                 <para>
2667                   Receive ERROR &rarr; send REJECTED [mechs], goto
2668                   <emphasis>WaitingForAuth</emphasis>
2669                 </para>
2670               </listitem>
2671
2672               <listitem>
2673                 <para>
2674                   Receive anything else &rarr; send ERROR, goto
2675                   <emphasis>WaitingForBegin</emphasis>
2676                 </para>
2677               </listitem>
2678             </itemizedlist>
2679           </para>
2680         </formalpara>
2681
2682       </sect3>
2683       
2684     </sect2>
2685     <sect2 id="auth-mechanisms">
2686       <title>Authentication mechanisms</title>
2687       <para>
2688         This section describes some new authentication mechanisms.
2689         D-Bus also allows any standard SASL mechanism of course.
2690       </para>
2691       <sect3 id="auth-mechanisms-sha">
2692         <title>DBUS_COOKIE_SHA1</title>
2693         <para>
2694           The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
2695           has the ability to read a private file owned by the user being
2696           authenticated. If the client can prove that it has access to a secret
2697           cookie stored in this file, then the client is authenticated. 
2698           Thus the security of DBUS_COOKIE_SHA1 depends on a secure home 
2699           directory.
2700         </para>
2701         <para>
2702           Throughout this description, "hex encoding" must output the digits
2703           from a to f in lower-case; the digits A to F must not be used
2704           in the DBUS_COOKIE_SHA1 mechanism.
2705         </para>
2706         <para>
2707           Authentication proceeds as follows:
2708           <itemizedlist>
2709             <listitem>
2710               <para>
2711                 The client sends the username it would like to authenticate 
2712                 as, hex-encoded.
2713               </para>
2714             </listitem>
2715             <listitem>
2716               <para>
2717                 The server sends the name of its "cookie context" (see below); a
2718                 space character; the integer ID of the secret cookie the client
2719                 must demonstrate knowledge of; a space character; then a
2720                 randomly-generated challenge string, all of this hex-encoded into
2721                 one, single string.
2722               </para>
2723             </listitem>
2724             <listitem>
2725               <para>
2726                 The client locates the cookie and generates its own
2727                 randomly-generated challenge string. The client then concatenates
2728                 the server's decoded challenge, a ":" character, its own challenge,
2729                 another ":" character, and the cookie. It computes the SHA-1 hash
2730                 of this composite string as a hex digest. It concatenates the
2731                 client's challenge string, a space character, and the SHA-1 hex
2732                 digest, hex-encodes the result and sends it back to the server.
2733               </para>
2734             </listitem>
2735             <listitem>
2736               <para>
2737                 The server generates the same concatenated string used by the
2738                 client and computes its SHA-1 hash. It compares the hash with
2739                 the hash received from the client; if the two hashes match, the
2740                 client is authenticated.
2741               </para>
2742             </listitem>
2743           </itemizedlist>
2744         </para>
2745         <para>
2746           Each server has a "cookie context," which is a name that identifies a
2747           set of cookies that apply to that server. A sample context might be
2748           "org_freedesktop_session_bus". Context names must be valid ASCII,
2749           nonzero length, and may not contain the characters slash ("/"),
2750           backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
2751           tab ("\t"), or period ("."). There is a default context,
2752           "org_freedesktop_general" that's used by servers that do not specify
2753           otherwise.
2754         </para>
2755         <para>
2756           Cookies are stored in a user's home directory, in the directory
2757           <filename>~/.dbus-keyrings/</filename>. This directory must 
2758           not be readable or writable by other users. If it is, 
2759           clients and servers must ignore it. The directory 
2760           contains cookie files named after the cookie context.
2761         </para>
2762         <para>
2763           A cookie file contains one cookie per line. Each line 
2764           has three space-separated fields:
2765           <itemizedlist>
2766             <listitem>
2767               <para>
2768                 The cookie ID number, which must be a non-negative integer and
2769                 may not be used twice in the same file.
2770               </para>
2771             </listitem>
2772             <listitem>
2773               <para>
2774                 The cookie's creation time, in UNIX seconds-since-the-epoch
2775                 format.
2776               </para>
2777             </listitem>
2778             <listitem>
2779               <para>
2780                 The cookie itself, a hex-encoded random block of bytes. The cookie
2781                 may be of any length, though obviously security increases 
2782                 as the length increases.
2783               </para>
2784             </listitem>
2785           </itemizedlist>
2786         </para>
2787         <para>
2788           Only server processes modify the cookie file.
2789           They must do so with this procedure:
2790           <itemizedlist>
2791             <listitem>
2792               <para>
2793                 Create a lockfile name by appending ".lock" to the name of the
2794                 cookie file.  The server should attempt to create this file
2795                 using <literal>O_CREAT | O_EXCL</literal>.  If file creation
2796                 fails, the lock fails. Servers should retry for a reasonable
2797                 period of time, then they may choose to delete an existing lock
2798                 to keep users from having to manually delete a stale
2799                 lock. <footnote><para>Lockfiles are used instead of real file
2800                 locking <literal>fcntl()</literal> because real locking
2801                 implementations are still flaky on network
2802                 filesystems.</para></footnote>
2803               </para>
2804             </listitem>
2805             <listitem>
2806               <para>
2807                 Once the lockfile has been created, the server loads the cookie
2808                 file. It should then delete any cookies that are old (the
2809                 timeout can be fairly short), or more than a reasonable
2810                 time in the future (so that cookies never accidentally 
2811                 become permanent, if the clock was set far into the future 
2812                 at some point). If no recent keys remain, the 
2813                 server may generate a new key.
2814               </para>
2815             </listitem>
2816             <listitem>
2817               <para>
2818                 The pruned and possibly added-to cookie file 
2819                 must be resaved atomically (using a temporary 
2820                 file which is rename()'d).
2821               </para>
2822             </listitem>
2823             <listitem>
2824               <para>
2825                 The lock must be dropped by deleting the lockfile.
2826               </para>
2827             </listitem>
2828           </itemizedlist>
2829         </para>
2830         <para>
2831           Clients need not lock the file in order to load it, 
2832           because servers are required to save the file atomically.          
2833         </para>
2834       </sect3>
2835     </sect2>
2836   </sect1>
2837   <sect1 id="addresses">
2838     <title>Server Addresses</title>
2839     <para>
2840       Server addresses consist of a transport name followed by a colon, and
2841       then an optional, comma-separated list of keys and values in the form key=value.
2842       Each value is escaped.
2843     </para>
2844     <para>
2845       For example: 
2846       <programlisting>unix:path=/tmp/dbus-test</programlisting>
2847       Which is the address to a unix socket with the path /tmp/dbus-test.
2848     </para>
2849     <para>
2850       Value escaping is similar to URI escaping but simpler.
2851       <itemizedlist>
2852         <listitem>
2853           <para>
2854             The set of optionally-escaped bytes is:
2855             <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
2856             <emphasis>byte</emphasis> (note, not character) which is not in the
2857             set of optionally-escaped bytes must be replaced with an ASCII
2858             percent (<literal>%</literal>) and the value of the byte in hex.
2859             The hex value must always be two digits, even if the first digit is
2860             zero. The optionally-escaped bytes may be escaped if desired.
2861           </para>
2862         </listitem>
2863         <listitem>
2864           <para>
2865             To unescape, append each byte in the value; if a byte is an ASCII
2866             percent (<literal>%</literal>) character then append the following
2867             hex value instead. It is an error if a <literal>%</literal> byte
2868             does not have two hex digits following. It is an error if a
2869             non-optionally-escaped byte is seen unescaped.
2870           </para>
2871         </listitem>
2872       </itemizedlist>
2873       The set of optionally-escaped bytes is intended to preserve address 
2874       readability and convenience.
2875     </para>
2876
2877     <para>
2878       A server may specify a key-value pair with the key <literal>guid</literal>
2879       and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
2880       describes the format of the <literal>guid</literal> field.  If present,
2881       this UUID may be used to distinguish one server address from another. A
2882       server should use a different UUID for each address it listens on. For
2883       example, if a message bus daemon offers both UNIX domain socket and TCP
2884       connections, but treats clients the same regardless of how they connect,
2885       those two connections are equivalent post-connection but should have
2886       distinct UUIDs to distinguish the kinds of connection.
2887     </para>
2888     
2889     <para>
2890       The intent of the address UUID feature is to allow a client to avoid
2891       opening multiple identical connections to the same server, by allowing the
2892       client to check whether an address corresponds to an already-existing
2893       connection.  Comparing two addresses is insufficient, because addresses
2894       can be recycled by distinct servers, and equivalent addresses may look
2895       different if simply compared as strings (for example, the host in a TCP
2896       address can be given as an IP address or as a hostname).
2897     </para>
2898
2899     <para>
2900       Note that the address key is <literal>guid</literal> even though the 
2901       rest of the API and documentation says "UUID," for historical reasons.
2902     </para>
2903
2904     <para>
2905       [FIXME clarify if attempting to connect to each is a requirement 
2906       or just a suggestion]
2907       When connecting to a server, multiple server addresses can be
2908       separated by a semi-colon. The library will then try to connect
2909       to the first address and if that fails, it'll try to connect to
2910       the next one specified, and so forth. For example
2911       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2912     </para>
2913
2914   </sect1>
2915   
2916   <sect1 id="transports">
2917     <title>Transports</title>
2918     <para>
2919       [FIXME we need to specify in detail each transport and its possible arguments]
2920     
2921       Current transports include: unix domain sockets (including 
2922       abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
2923       using in-process pipes. Future possible transports include one that
2924       tunnels over X11 protocol.
2925     </para>
2926   
2927     <sect2 id="transports-unix-domain-sockets">
2928       <title>Unix Domain Sockets</title>
2929       <para>
2930         Unix domain sockets can be either paths in the file system or on Linux 
2931         kernels, they can be abstract which are similar to paths but
2932         do not show up in the file system.  
2933       </para>
2934
2935       <para>
2936         When a socket is opened by the D-Bus library it truncates the path 
2937         name right before the first trailing Nul byte.  This is true for both
2938         normal paths and abstract paths.  Note that this is a departure from
2939         previous versions of D-Bus that would create sockets with a fixed 
2940         length path name.  Names which were shorter than the fixed length
2941         would be padded by Nul bytes.
2942       </para>
2943       <para>
2944         Unix domain sockets are not available on Windows.
2945       </para>
2946       <sect3 id="transports-unix-domain-sockets-addresses">
2947         <title>Server Address Format</title>
2948         <para> 
2949           Unix domain socket addresses are identified by the "unix:" prefix 
2950           and support the following key/value pairs:
2951         </para>
2952         <informaltable>
2953          <tgroup cols="3">
2954           <thead>
2955            <row>
2956             <entry>Name</entry>
2957             <entry>Values</entry>
2958             <entry>Description</entry>
2959            </row>
2960           </thead>
2961           <tbody>
2962            <row>
2963             <entry>path</entry>
2964             <entry>(path)</entry>
2965             <entry>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</entry>
2966           </row>
2967           <row>
2968             <entry>tmpdir</entry>
2969             <entry>(path)</entry>
2970             <entry>temporary directory in which a socket file with a random file name starting with 'dbus-' will be created by the server. This key can only be used in server addresses, not in client addresses. If set, the "path" and "abstract" key must not be set.</entry>
2971           </row>
2972           <row>
2973             <entry>abstract</entry>
2974             <entry>(string)</entry>
2975             <entry>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</entry>
2976           </row>
2977         </tbody>
2978         </tgroup>
2979        </informaltable>
2980       </sect3>
2981     </sect2>
2982     <sect2 id="transports-launchd">
2983       <title>launchd</title>
2984       <para>
2985         launchd is an open-source server management system that replaces init, inetd
2986         and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
2987         bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
2988       </para>
2989
2990       <para>
2991         launchd allocates a socket and provides it with the unix path through the
2992         DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
2993         spawned by launchd (or dbus-daemon, if it was started by launchd) can access
2994         it through its environment.
2995         Other processes can query for the launchd socket by executing:
2996         $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
2997         This is normally done by the D-Bus client library so doesn't have to be done
2998         manually.
2999       </para>
3000       <para>
3001         launchd is not available on Microsoft Windows.
3002       </para>
3003       <sect3 id="transports-launchd-addresses">
3004         <title>Server Address Format</title>
3005         <para>
3006           launchd addresses are identified by the "launchd:" prefix
3007           and support the following key/value pairs:
3008         </para>
3009         <informaltable>
3010          <tgroup cols="3">
3011           <thead>
3012            <row>
3013             <entry>Name</entry>
3014             <entry>Values</entry>
3015             <entry>Description</entry>
3016            </row>
3017           </thead>
3018           <tbody>
3019            <row>
3020             <entry>env</entry>
3021             <entry>(environment variable)</entry>
3022             <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
3023           </row>
3024         </tbody>
3025         </tgroup>
3026        </informaltable>
3027       </sect3>
3028     </sect2>
3029     <sect2 id="transports-systemd">
3030       <title>systemd</title>
3031       <para>
3032         systemd is an open-source server management system that
3033         replaces init and inetd on newer Linux systems. It supports
3034         socket activation. The D-Bus systemd transport is used to acquire
3035         socket activation file descriptors from systemd and use them
3036         as D-Bus transport when the current process is spawned by
3037         socket activation from it.
3038       </para>
3039       <para>
3040         The systemd transport accepts only one or more Unix domain or
3041         TCP streams sockets passed in via socket activation.
3042       </para>
3043       <para>
3044         The systemd transport is not available on non-Linux operating systems.
3045       </para>
3046       <para>
3047         The systemd transport defines no parameter keys.
3048       </para>
3049     </sect2>
3050     <sect2 id="transports-tcp-sockets">
3051       <title>TCP Sockets</title>
3052       <para>
3053         The tcp transport provides TCP/IP based connections between clients
3054         located on the same or different hosts. 
3055       </para>
3056       <para>
3057         Using tcp transport without any additional secure authentification mechanismus 
3058         over a network is unsecure. 
3059       </para>
3060       <para>  
3061         Windows notes: Because of the tcp stack on Windows does not provide sending
3062         credentials over a tcp connection, the EXTERNAL authentification 
3063         mechanismus does not work. 
3064       </para>
3065       <sect3 id="transports-tcp-sockets-addresses">
3066         <title>Server Address Format</title>
3067         <para> 
3068          TCP/IP socket addresses are identified by the "tcp:" prefix 
3069          and support the following key/value pairs:
3070         </para>
3071         <informaltable>
3072          <tgroup cols="3">
3073           <thead>
3074            <row>
3075             <entry>Name</entry>
3076             <entry>Values</entry>
3077             <entry>Description</entry>
3078            </row>
3079           </thead>
3080           <tbody>
3081            <row>
3082             <entry>host</entry>
3083             <entry>(string)</entry>
3084             <entry>dns name or ip address</entry>
3085           </row>
3086           <row>
3087            <entry>port</entry>
3088            <entry>(number)</entry>
3089            <entry>The tcp port the server will open. A zero value let the server 
3090             choose a free port provided from the underlaying operating system. 
3091             libdbus is able to retrieve the real used port from the server.  
3092            </entry>
3093           </row>
3094           <row>
3095            <entry>family</entry>
3096            <entry>(string)</entry>
3097            <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3098           </row>
3099          </tbody>
3100         </tgroup>
3101        </informaltable>
3102       </sect3>
3103     </sect2>
3104     <sect2 id="transports-nonce-tcp-sockets">
3105       <title>Nonce-secured TCP Sockets</title>
3106       <para>
3107         The nonce-tcp transport provides a secured TCP transport, using a
3108         simple authentication mechanism to ensure that only clients with read
3109         access to a certain location in the filesystem can connect to the server.
3110         The server writes a secret, the nonce, to a file and an incoming client
3111         connection is only accepted if the client sends the nonce right after
3112         the connect. The nonce mechanism requires no setup and is orthogonal to
3113         the higher-level authentication mechanisms described in the
3114         Authentication section.
3115       </para>
3116
3117       <para>
3118         On start, the server generates a random 16 byte nonce and writes it
3119         to a file in the user's temporary directory. The nonce file location
3120         is published as part of the server's D-Bus address using the
3121         "noncefile" key-value pair.
3122
3123         After an accept, the server reads 16 bytes from the socket. If the
3124         read bytes do not match the nonce stored in the nonce file, the
3125         server MUST immediately drop the connection.
3126         If the nonce match the received byte sequence, the client is accepted
3127         and the transport behaves like an unsecured tcp transport.
3128       </para>
3129       <para>
3130         After a successful connect to the server socket, the client MUST read
3131         the nonce from the file published by the server via the noncefile=
3132         key-value pair and send it over the socket. After that, the
3133         transport behaves like an unsecured tcp transport.
3134       </para>
3135       <sect3 id="transports-nonce-tcp-sockets-addresses">
3136         <title>Server Address Format</title>
3137         <para> 
3138          Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix 
3139          and support the following key/value pairs:
3140         </para>
3141         <informaltable>
3142          <tgroup cols="3">
3143           <thead>
3144            <row>
3145             <entry>Name</entry>
3146             <entry>Values</entry>
3147             <entry>Description</entry>
3148            </row>
3149           </thead>
3150           <tbody>
3151            <row>
3152             <entry>host</entry>
3153             <entry>(string)</entry>
3154             <entry>dns name or ip address</entry>
3155           </row>
3156           <row>
3157            <entry>port</entry>
3158            <entry>(number)</entry>
3159            <entry>The tcp port the server will open. A zero value let the server 
3160             choose a free port provided from the underlaying operating system. 
3161             libdbus is able to retrieve the real used port from the server.  
3162            </entry>
3163           </row>
3164           <row>
3165            <entry>family</entry>
3166            <entry>(string)</entry>
3167            <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
3168           </row>
3169           <row>
3170            <entry>noncefile</entry>
3171            <entry>(path)</entry>
3172            <entry>file location containing the secret</entry>
3173           </row>
3174          </tbody>
3175         </tgroup>
3176        </informaltable>
3177       </sect3>
3178     </sect2>
3179     <sect2 id="transports-exec">
3180       <title>Executed Subprocesses on Unix</title>
3181       <para>
3182         This transport forks off a process and connects its standard
3183         input and standard output with an anonymous Unix domain
3184         socket. This socket is then used for communication by the
3185         transport. This transport may be used to use out-of-process
3186         forwarder programs as basis for the D-Bus protocol.
3187       </para>
3188       <para>
3189         The forked process will inherit the standard error output and
3190         process group from the parent process.
3191       </para>
3192       <para>
3193         Executed subprocesses are not available on Windows.
3194       </para>
3195       <sect3 id="transports-exec-addresses">
3196         <title>Server Address Format</title>
3197         <para>
3198           Executed subprocess addresses are identified by the "unixexec:" prefix
3199           and support the following key/value pairs:
3200         </para>
3201         <informaltable>
3202          <tgroup cols="3">
3203           <thead>
3204            <row>
3205             <entry>Name</entry>
3206             <entry>Values</entry>
3207             <entry>Description</entry>
3208            </row>
3209           </thead>
3210           <tbody>
3211            <row>
3212             <entry>path</entry>
3213             <entry>(path)</entry>
3214             <entry>Path of the binary to execute, either an absolute
3215             path or a binary name that is searched for in the default
3216             search path of the OS. This corresponds to the first
3217             argument of execlp(). This key is mandatory.</entry>
3218           </row>
3219           <row>
3220             <entry>argv0</entry>
3221             <entry>(string)</entry>
3222             <entry>The program name to use when executing the
3223             binary. If omitted the same value as specified for path=
3224             will be used. This corresponds to the second argument of
3225             execlp().</entry>
3226           </row>
3227           <row>
3228             <entry>argv1, argv2, ...</entry>
3229             <entry>(string)</entry>
3230             <entry>Arguments to pass to the binary. This corresponds
3231             to the third and later arguments of execlp(). If a
3232             specific argvX is not specified no further argvY for Y > X
3233             are taken into account.</entry>
3234           </row>
3235         </tbody>
3236         </tgroup>
3237        </informaltable>
3238       </sect3>
3239     </sect2>
3240    </sect1>
3241    <sect1 id="meta-transports">
3242     <title>Meta Transports</title>
3243     <para>
3244       Meta transports are a kind of transport with special enhancements or
3245       behavior. Currently available meta transports include: autolaunch
3246     </para>
3247
3248     <sect2 id="meta-transports-autolaunch">
3249      <title>Autolaunch</title>
3250      <para>The autolaunch transport provides a way for dbus clients to autodetect
3251        a running dbus session bus and to autolaunch a session bus if not present.
3252      </para>
3253      <sect3 id="meta-transports-autolaunch-addresses">
3254        <title>Server Address Format</title>
3255        <para>
3256          Autolaunch addresses uses the "autolaunch:" prefix and support the
3257          following key/value pairs:
3258        </para>
3259        <informaltable>
3260         <tgroup cols="3">
3261          <thead>
3262           <row>
3263            <entry>Name</entry>
3264            <entry>Values</entry>
3265            <entry>Description</entry>
3266           </row>
3267          </thead>
3268          <tbody>
3269           <row>
3270            <entry>scope</entry>
3271            <entry>(string)</entry>
3272            <entry>scope of autolaunch (Windows only)
3273             <itemizedlist>
3274              <listitem>
3275               <para>
3276                "*install-path" - limit session bus to dbus installation path.
3277                The dbus installation path is determined from the location of
3278                the shared dbus library. If the library is located in a 'bin'
3279                subdirectory the installation root is the directory above,
3280                otherwise the directory where the library lives is taken as
3281                installation root.
3282                <programlisting>
3283                    &lt;install-root&gt;/bin/[lib]dbus-1.dll
3284                    &lt;install-root&gt;/[lib]dbus-1.dll
3285                </programlisting>
3286               </para>
3287              </listitem>
3288              <listitem>
3289               <para>
3290                "*user" - limit session bus to the recent user.
3291               </para>
3292              </listitem>
3293              <listitem>
3294               <para>
3295                other values - specify dedicated session bus like "release",
3296                "debug" or other
3297               </para>
3298              </listitem>
3299             </itemizedlist>
3300            </entry>
3301          </row>
3302         </tbody>
3303        </tgroup>
3304       </informaltable>
3305      </sect3>
3306
3307      <sect3 id="meta-transports-autolaunch-windows-implementation">
3308       <title>Windows implementation</title>
3309       <para>
3310         On start, the server opens a platform specific transport, creates a mutex
3311         and a shared memory section containing the related session bus address.
3312         This mutex will be inspected by the dbus client library to detect a
3313         running dbus session bus. The access to the mutex and the shared memory
3314         section are protected by global locks.
3315       </para>
3316       <para>
3317        In the recent implementation the autolaunch transport uses a tcp transport
3318        on localhost with a port choosen from the operating system. This detail may
3319        change in the future.
3320       </para>
3321       <para>
3322         Disclaimer: The recent implementation is in an early state and may not
3323         work in all cirumstances and/or may have security issues. Because of this
3324         the implementation is not documentated yet.
3325       </para>
3326      </sect3>
3327     </sect2>
3328    </sect1>
3329
3330   <sect1 id="uuids">
3331     <title>UUIDs</title>
3332     <para>
3333       A working D-Bus implementation uses universally-unique IDs in two places.
3334       First, each server address has a UUID identifying the address, 
3335       as described in <xref linkend="addresses"/>. Second, each operating
3336       system kernel instance running a D-Bus client or server has a UUID
3337       identifying that kernel, retrieved by invoking the method
3338       org.freedesktop.DBus.Peer.GetMachineId() (see <xref
3339       linkend="standard-interfaces-peer"/>).
3340     </para>
3341     <para>
3342       The term "UUID" in this document is intended literally, i.e. an
3343       identifier that is universally unique. It is not intended to refer to
3344       RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
3345     </para>
3346     <para>
3347       The UUID must contain 128 bits of data and be hex-encoded.  The
3348       hex-encoded string may not contain hyphens or other non-hex-digit
3349       characters, and it must be exactly 32 characters long.  To generate a
3350       UUID, the current reference implementation concatenates 96 bits of random
3351       data followed by the 32-bit time in seconds since the UNIX epoch (in big
3352       endian byte order).
3353     </para>
3354     <para>
3355       It would also be acceptable and probably better to simply generate 128
3356       bits of random data, as long as the random number generator is of high
3357       quality. The timestamp could conceivably help if the random bits are not
3358       very random. With a quality random number generator, collisions are
3359       extremely unlikely even with only 96 bits, so it's somewhat academic.
3360     </para>
3361     <para>
3362       Implementations should, however, stick to random data for the first 96 bits
3363       of the UUID.
3364     </para>
3365   </sect1>
3366     
3367   <sect1 id="standard-interfaces">
3368     <title>Standard Interfaces</title>
3369     <para>
3370       See <xref linkend="message-protocol-types-notation"/> for details on 
3371        the notation used in this section. There are some standard interfaces
3372       that may be useful across various D-Bus applications.
3373     </para>
3374     <sect2 id="standard-interfaces-peer">
3375       <title><literal>org.freedesktop.DBus.Peer</literal></title>
3376       <para>
3377         The <literal>org.freedesktop.DBus.Peer</literal> interface 
3378         has two methods:
3379         <programlisting>
3380           org.freedesktop.DBus.Peer.Ping ()
3381           org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
3382         </programlisting>
3383       </para>
3384       <para>
3385         On receipt of the <literal>METHOD_CALL</literal> message
3386         <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
3387         nothing other than reply with a <literal>METHOD_RETURN</literal> as
3388         usual.  It does not matter which object path a ping is sent to.  The
3389         reference implementation handles this method automatically.
3390       </para>
3391       <para>
3392         On receipt of the <literal>METHOD_CALL</literal> message
3393         <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should 
3394         reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded 
3395         UUID representing the identity of the machine the process is running on.
3396         This UUID must be the same for all processes on a single system at least
3397         until that system next reboots. It should be the same across reboots 
3398         if possible, but this is not always possible to implement and is not 
3399         guaranteed.
3400         It does not matter which object path a GetMachineId is sent to.  The
3401         reference implementation handles this method automatically.
3402       </para>
3403       <para>
3404         The UUID is intended to be per-instance-of-the-operating-system, so may represent
3405         a virtual machine running on a hypervisor, rather than a physical machine.
3406         Basically if two processes see the same UUID, they should also see the same
3407         shared memory, UNIX domain sockets, process IDs, and other features that require 
3408         a running OS kernel in common between the processes.
3409       </para>
3410       <para>
3411         The UUID is often used where other programs might use a hostname. Hostnames 
3412         can change without rebooting, however, or just be "localhost" - so the UUID
3413         is more robust.
3414       </para>
3415       <para>
3416         <xref linkend="uuids"/> explains the format of the UUID.
3417       </para>
3418     </sect2>
3419
3420     <sect2 id="standard-interfaces-introspectable">
3421       <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
3422       <para>
3423         This interface has one method:
3424         <programlisting>
3425           org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
3426         </programlisting>
3427       </para>
3428       <para>
3429         Objects instances may implement
3430         <literal>Introspect</literal> which returns an XML description of
3431         the object, including its interfaces (with signals and methods), objects
3432         below it in the object path tree, and its properties.
3433       </para>
3434       <para>
3435         <xref linkend="introspection-format"/> describes the format of this XML string.
3436       </para>
3437     </sect2>
3438     <sect2 id="standard-interfaces-properties">
3439       <title><literal>org.freedesktop.DBus.Properties</literal></title>
3440       <para>
3441         Many native APIs will have a concept of object <firstterm>properties</firstterm> 
3442         or <firstterm>attributes</firstterm>. These can be exposed via the 
3443         <literal>org.freedesktop.DBus.Properties</literal> interface.
3444       </para>
3445       <para>
3446         <programlisting>
3447               org.freedesktop.DBus.Properties.Get (in STRING interface_name,
3448                                                    in STRING property_name,
3449                                                    out VARIANT value);
3450               org.freedesktop.DBus.Properties.Set (in STRING interface_name,
3451                                                    in STRING property_name,
3452                                                    in VARIANT value);
3453               org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
3454                                                       out DICT&lt;STRING,VARIANT&gt; props);
3455         </programlisting>
3456       </para>
3457       <para>
3458         It is conventional to give D-Bus properties names consisting of
3459         capitalized words without punctuation ("CamelCase"), like
3460         <link linkend="message-protocol-names-member">member names</link>.
3461         For instance, the GObject property
3462         <literal>connection-status</literal> or the Qt property
3463         <literal>connectionStatus</literal> could be represented on D-Bus
3464         as <literal>ConnectionStatus</literal>.
3465       </para>
3466       <para>
3467         Strictly speaking, D-Bus property names are not required to follow
3468         the same naming restrictions as member names, but D-Bus property
3469         names that would not be valid member names (in particular,
3470         GObject-style dash-separated property names) can cause interoperability
3471         problems and should be avoided.
3472       </para>
3473       <para>
3474         The available properties and whether they are writable can be determined
3475         by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
3476         see <xref linkend="standard-interfaces-introspectable"/>.
3477       </para>
3478       <para>
3479         An empty string may be provided for the interface name; in this case, 
3480         if there are multiple properties on an object with the same name, 
3481         the results are undefined (picking one by according to an arbitrary 
3482         deterministic rule, or returning an error, are the reasonable 
3483         possibilities).
3484       </para>
3485       <para>
3486         If one or more properties change on an object, the
3487         <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3488         signal may be emitted (this signal was added in 0.14):
3489       </para>
3490       <para>
3491         <programlisting>
3492               org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
3493                                                                  DICT&lt;STRING,VARIANT&gt; changed_properties,
3494                                                                  ARRAY&lt;STRING&gt; invalidated_properties);
3495         </programlisting>
3496       </para>
3497       <para>
3498         where <literal>changed_properties</literal> is a dictionary
3499         containing the changed properties with the new values and
3500         <literal>invalidated_properties</literal> is an array of
3501         properties that changed but the value is not conveyed.
3502       </para>
3503       <para>
3504         Whether the <literal>PropertiesChanged</literal> signal is
3505         supported can be determined by calling
3506         <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
3507         that the signal may be supported for an object but it may
3508         differ how whether and how it is used on a per-property basis
3509         (for e.g. performance or security reasons). Each property (or
3510         the parent interface) must be annotated with the
3511         <literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
3512         annotation to convey this (usually the default value
3513         <literal>true</literal> is sufficient meaning that the
3514         annotation does not need to be used). See <xref
3515         linkend="introspection-format"/> for details on this
3516         annotation.
3517       </para>
3518     </sect2>
3519
3520     <sect2 id="standard-interfaces-objectmanager">
3521       <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
3522       <para>
3523         An API can optionally make use of this interface for one or
3524         more sub-trees of objects. The root of each sub-tree implements
3525         this interface so other applications can get all objects,
3526         interfaces and properties in a single method call.  It is
3527         appropriate to use this interface if users of the tree of
3528         objects are expected to be interested in all interfaces of all
3529         objects in the tree; a more granular API should be used if
3530         users of the objects are expected to be interested in a small
3531         subset of the objects, a small subset of their interfaces, or
3532         both.
3533       </para>
3534       <para>
3535         The method that applications can use to get all objects and
3536         properties is <literal>GetManagedObjects</literal>:
3537       </para>
3538       <para>
3539         <programlisting>
3540           org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT&lt;OBJPATH,DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);
3541         </programlisting>
3542       </para>
3543       <para>
3544         The return value of this method is a dict whose keys are
3545         object paths. All returned object paths are children of the
3546         object path implementing this interface, i.e. their object
3547         paths start with the ObjectManager's object path plus '/'.
3548       </para>
3549       <para>
3550         Each value is a dict whose keys are interfaces names.  Each
3551         value in this inner dict is the same dict that would be
3552         returned by the <link
3553         linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
3554         method for that combination of object path and interface. If
3555         an interface has no properties, the empty dict is returned.
3556       </para>
3557       <para>
3558         Changes are emitted using the following two signals:
3559       </para>
3560       <para>
3561         <programlisting>
3562           org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
3563                                                               DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt; interfaces_and_properties);
3564           org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
3565                                                                 ARRAY&lt;STRING&gt; interfaces);
3566         </programlisting>
3567       </para>
3568       <para>
3569         The <literal>InterfacesAdded</literal> signal is emitted when
3570         either a new object is added or when an existing object gains
3571         one or more interfaces. The
3572         <literal>InterfacesRemoved</literal> signal is emitted
3573         whenever an object is removed or it loses one or more
3574         interfaces. The second parameter of the
3575         <literal>InterfacesAdded</literal> signal contains a dict with
3576         the interfaces and properties (if any) that have been added to
3577         the given object path. Similarly, the second parameter of the
3578         <literal>InterfacesRemoved</literal> signal contains an array
3579         of the interfaces that were removed. Note that changes on
3580         properties on existing interfaces are not reported using this
3581         interface - an application should also monitor the existing <link
3582         linkend="standard-interfaces-properties">PropertiesChanged</link>
3583         signal on each object.
3584       </para>
3585       <para>
3586         Applications SHOULD NOT export objects that are children of an
3587         object (directly or otherwise) implementing this interface but
3588         which are not returned in the reply from the
3589         <literal>GetManagedObjects()</literal> method of this
3590         interface on the given object.
3591       </para>
3592       <para>
3593         The intent of the <literal>ObjectManager</literal> interface
3594         is to make it easy to write a robust client
3595         implementation. The trivial client implementation only needs
3596         to make two method calls:
3597       </para>
3598       <para>
3599         <programlisting>
3600           org.freedesktop.DBus.AddMatch (bus_proxy,
3601                                          "type='signal',name='org.example.App',path_namespace='/org/example/App'");
3602           objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
3603         </programlisting>
3604       </para>
3605       <para>
3606         on the message bus and the remote application's
3607         <literal>ObjectManager</literal>, respectively. Whenever a new
3608         remote object is created (or an existing object gains a new
3609         interface), the <literal>InterfacesAdded</literal> signal is
3610         emitted, and since this signal contains all properties for the
3611         interfaces, no calls to the
3612         <literal>org.freedesktop.Properties</literal> interface on the
3613         remote object are needed. Additionally, since the initial
3614         <literal>AddMatch()</literal> rule already includes signal
3615         messages from the newly created child object, no new
3616         <literal>AddMatch()</literal> call is needed.
3617       </para>
3618
3619       <para>
3620         <emphasis>
3621           The <literal>org.freedesktop.DBus.ObjectManager</literal>
3622           interface was added in version 0.17 of the D-Bus
3623           specification.
3624         </emphasis>
3625       </para>
3626     </sect2>
3627   </sect1>
3628
3629   <sect1 id="introspection-format">
3630     <title>Introspection Data Format</title>
3631     <para>
3632       As described in <xref linkend="standard-interfaces-introspectable"/>, 
3633       objects may be introspected at runtime, returning an XML string 
3634       that describes the object. The same XML format may be used in 
3635       other contexts as well, for example as an "IDL" for generating 
3636       static language bindings.
3637     </para>
3638     <para>
3639       Here is an example of introspection data:
3640       <programlisting>
3641         &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
3642          "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
3643         &lt;node name="/org/freedesktop/sample_object"&gt;
3644           &lt;interface name="org.freedesktop.SampleInterface"&gt;
3645             &lt;method name="Frobate"&gt;
3646               &lt;arg name="foo" type="i" direction="in"/&gt;
3647               &lt;arg name="bar" type="s" direction="out"/&gt;
3648               &lt;arg name="baz" type="a{us}" direction="out"/&gt;
3649               &lt;annotation name="org.freedesktop.DBus.Deprecated" value="true"/&gt;
3650             &lt;/method&gt;
3651             &lt;method name="Bazify"&gt;
3652               &lt;arg name="bar" type="(iiu)" direction="in"/&gt;
3653               &lt;arg name="bar" type="v" direction="out"/&gt;
3654             &lt;/method&gt;
3655             &lt;method name="Mogrify"&gt;
3656               &lt;arg name="bar" type="(iiav)" direction="in"/&gt;
3657             &lt;/method&gt;
3658             &lt;signal name="Changed"&gt;
3659               &lt;arg name="new_value" type="b"/&gt;
3660             &lt;/signal&gt;
3661             &lt;property name="Bar" type="y" access="readwrite"/&gt;
3662           &lt;/interface&gt;
3663           &lt;node name="child_of_sample_object"/&gt;
3664           &lt;node name="another_child_of_sample_object"/&gt;
3665        &lt;/node&gt;
3666       </programlisting>
3667     </para>
3668     <para>
3669       A more formal DTD and spec needs writing, but here are some quick notes.
3670       <itemizedlist>
3671         <listitem>
3672           <para>
3673             Only the root &lt;node&gt; element can omit the node name, as it's
3674             known to be the object that was introspected.  If the root
3675             &lt;node&gt; does have a name attribute, it must be an absolute
3676             object path. If child &lt;node&gt; have object paths, they must be
3677             relative.
3678           </para>
3679         </listitem>
3680         <listitem>
3681           <para>
3682             If a child &lt;node&gt; has any sub-elements, then they 
3683             must represent a complete introspection of the child.
3684             If a child &lt;node&gt; is empty, then it may or may 
3685             not have sub-elements; the child must be introspected
3686             in order to find out. The intent is that if an object 
3687             knows that its children are "fast" to introspect
3688             it can go ahead and return their information, but 
3689             otherwise it can omit it.
3690           </para>
3691         </listitem>
3692         <listitem>
3693           <para>
3694             The direction element on &lt;arg&gt; may be omitted, 
3695             in which case it defaults to "in" for method calls 
3696             and "out" for signals. Signals only allow "out" 
3697             so while direction may be specified, it's pointless.
3698           </para>
3699         </listitem>
3700         <listitem>
3701           <para>
3702             The possible directions are "in" and "out", 
3703             unlike CORBA there is no "inout"
3704           </para>
3705         </listitem>
3706         <listitem>
3707           <para>
3708             The possible property access flags are 
3709             "readwrite", "read", and "write"
3710           </para>
3711         </listitem>
3712         <listitem>
3713           <para>
3714             Multiple interfaces can of course be listed for 
3715             one &lt;node&gt;.
3716           </para>
3717         </listitem>
3718         <listitem>
3719           <para>
3720             The "name" attribute on arguments is optional.
3721           </para>
3722         </listitem>
3723       </itemizedlist>
3724     </para>
3725     <para>
3726         Method, interface, property, and signal elements may have
3727         "annotations", which are generic key/value pairs of metadata.
3728         They are similar conceptually to Java's annotations and C# attributes.
3729         Well-known annotations:
3730      </para>
3731      <informaltable>
3732        <tgroup cols="3">
3733          <thead>
3734            <row>
3735              <entry>Name</entry>
3736              <entry>Values (separated by ,)</entry>
3737              <entry>Description</entry>
3738            </row>
3739          </thead>
3740          <tbody>
3741            <row>
3742              <entry>org.freedesktop.DBus.Deprecated</entry>
3743              <entry>true,false</entry>
3744              <entry>Whether or not the entity is deprecated; defaults to false</entry>
3745            </row>
3746            <row>
3747              <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
3748              <entry>(string)</entry>
3749              <entry>The C symbol; may be used for methods and interfaces</entry>
3750            </row>
3751            <row>
3752              <entry>org.freedesktop.DBus.Method.NoReply</entry>
3753              <entry>true,false</entry>
3754              <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
3755            </row>
3756            <row>
3757              <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
3758              <entry>true,invalidates,false</entry>
3759              <entry>
3760                <para>
3761                  If set to <literal>false</literal>, the
3762                  <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
3763                  signal, see <xref
3764                  linkend="standard-interfaces-properties"/> is not
3765                  guaranteed to be emitted if the property changes.
3766                </para>
3767                <para>
3768                  If set to <literal>invalidates</literal> the signal
3769                  is emitted but the value is not included in the
3770                  signal.
3771                </para>
3772                <para>
3773                  If set to <literal>true</literal> the signal is
3774                  emitted with the value included.
3775                </para>
3776                <para>
3777                  The value for the annotation defaults to
3778                  <literal>true</literal> if the enclosing interface
3779                  element does not specify the annotation. Otherwise it
3780                  defaults to the value specified in the enclosing
3781                  interface element.
3782                </para>
3783              </entry>
3784            </row>
3785          </tbody>
3786        </tgroup>
3787      </informaltable>
3788   </sect1>
3789   <sect1 id="message-bus">
3790     <title>Message Bus Specification</title>
3791     <sect2 id="message-bus-overview">
3792       <title>Message Bus Overview</title>
3793       <para>
3794         The message bus accepts connections from one or more applications. 
3795         Once connected, applications can exchange messages with other 
3796         applications that are also connected to the bus.
3797       </para>
3798       <para>
3799         In order to route messages among connections, the message bus keeps a
3800         mapping from names to connections. Each connection has one
3801         unique-for-the-lifetime-of-the-bus name automatically assigned.
3802         Applications may request additional names for a connection. Additional
3803         names are usually "well-known names" such as
3804         "org.freedesktop.TextEditor". When a name is bound to a connection,
3805         that connection is said to <firstterm>own</firstterm> the name.
3806       </para>
3807       <para>
3808         The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>. 
3809         This name routes messages to the bus, allowing applications to make 
3810         administrative requests. For example, applications can ask the bus 
3811         to assign a name to a connection.
3812       </para>
3813       <para>
3814         Each name may have <firstterm>queued owners</firstterm>.  When an
3815         application requests a name for a connection and the name is already in
3816         use, the bus will optionally add the connection to a queue waiting for 
3817         the name. If the current owner of the name disconnects or releases
3818         the name, the next connection in the queue will become the new owner.
3819       </para>
3820
3821       <para>
3822         This feature causes the right thing to happen if you start two text
3823         editors for example; the first one may request "org.freedesktop.TextEditor", 
3824         and the second will be queued as a possible owner of that name. When 
3825         the first exits, the second will take over.
3826       </para>
3827
3828       <para>
3829         Applications may send <firstterm>unicast messages</firstterm> to
3830         a specific recipient or to the message bus itself, or
3831         <firstterm>broadcast messages</firstterm> to all interested recipients.
3832         See <xref linkend="message-bus-routing"/> for details.
3833       </para>
3834     </sect2>
3835
3836     <sect2 id="message-bus-names">
3837       <title>Message Bus Names</title>
3838       <para>
3839         Each connection has at least one name, assigned at connection time and
3840         returned in response to the
3841         <literal>org.freedesktop.DBus.Hello</literal> method call.  This
3842         automatically-assigned name is called the connection's <firstterm>unique
3843         name</firstterm>.  Unique names are never reused for two different
3844         connections to the same bus.
3845       </para>
3846       <para>
3847         Ownership of a unique name is a prerequisite for interaction with 
3848         the message bus. It logically follows that the unique name is always 
3849         the first name that an application comes to own, and the last 
3850         one that it loses ownership of.
3851       </para>
3852       <para>
3853         Unique connection names must begin with the character ':' (ASCII colon
3854         character); bus names that are not unique names must not begin
3855         with this character. (The bus must reject any attempt by an application
3856         to manually request a name beginning with ':'.) This restriction
3857         categorically prevents "spoofing"; messages sent to a unique name
3858         will always go to the expected connection.
3859       </para>
3860       <para>
3861         When a connection is closed, all the names that it owns are deleted (or
3862         transferred to the next connection in the queue if any).
3863       </para>
3864       <para>
3865         A connection can request additional names to be associated with it using
3866         the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
3867         linkend="message-protocol-names-bus"/> describes the format of a valid
3868         name. These names can be released again using the
3869         <literal>org.freedesktop.DBus.ReleaseName</literal> message.
3870       </para>
3871
3872       <sect3 id="bus-messages-request-name">
3873         <title><literal>org.freedesktop.DBus.RequestName</literal></title>
3874         <para>
3875           As a method:
3876           <programlisting>
3877             UINT32 RequestName (in STRING name, in UINT32 flags)
3878           </programlisting>
3879           Message arguments:
3880           <informaltable>
3881             <tgroup cols="3">
3882               <thead>
3883                 <row>
3884                   <entry>Argument</entry>
3885                   <entry>Type</entry>
3886                   <entry>Description</entry>
3887                 </row>
3888               </thead>
3889               <tbody>
3890                 <row>
3891                   <entry>0</entry>
3892                   <entry>STRING</entry>
3893                   <entry>Name to request</entry>
3894                 </row>
3895                 <row>
3896                   <entry>1</entry>
3897                   <entry>UINT32</entry>
3898                   <entry>Flags</entry>
3899                 </row>
3900               </tbody>
3901             </tgroup>
3902           </informaltable>
3903           Reply arguments:
3904           <informaltable>
3905             <tgroup cols="3">
3906               <thead>
3907                 <row>
3908                   <entry>Argument</entry>
3909                   <entry>Type</entry>
3910                   <entry>Description</entry>
3911                 </row>
3912               </thead>
3913               <tbody>
3914                 <row>
3915                   <entry>0</entry>
3916                   <entry>UINT32</entry>
3917                   <entry>Return value</entry>
3918                 </row>
3919               </tbody>
3920             </tgroup>
3921           </informaltable>
3922         </para>
3923         <para>
3924           This method call should be sent to
3925           <literal>org.freedesktop.DBus</literal> and asks the message bus to
3926           assign the given name to the method caller. Each name maintains a
3927           queue of possible owners, where the head of the queue is the primary
3928           or current owner of the name. Each potential owner in the queue
3929           maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
3930           DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
3931           call.  When RequestName is invoked the following occurs:
3932           <itemizedlist>
3933             <listitem>
3934               <para>
3935                 If the method caller is currently the primary owner of the name,
3936                 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
3937                 values are updated with the values from the new RequestName call, 
3938                 and nothing further happens.
3939               </para>
3940             </listitem>
3941
3942             <listitem>
3943               <para>
3944                 If the current primary owner (head of the queue) has
3945                 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
3946                 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
3947                 the caller of RequestName replaces the current primary owner at
3948                 the head of the queue and the current primary owner moves to the
3949                 second position in the queue. If the caller of RequestName was 
3950                 in the queue previously its flags are updated with the values from 
3951                 the new RequestName in addition to moving it to the head of the queue.
3952               </para>
3953             </listitem>
3954
3955             <listitem>
3956               <para>
3957                 If replacement is not possible, and the method caller is
3958                 currently in the queue but not the primary owner, its flags are
3959                 updated with the values from the new RequestName call.
3960               </para>
3961             </listitem>
3962
3963             <listitem>
3964               <para>
3965                 If replacement is not possible, and the method caller is
3966                 currently not in the queue, the method caller is appended to the
3967                 queue.
3968               </para>
3969             </listitem>
3970
3971             <listitem>
3972               <para>
3973                 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
3974                 set and is not the primary owner, it is removed from the
3975                 queue. This can apply to the previous primary owner (if it
3976                 was replaced) or the method caller (if it updated the
3977                 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
3978                 queue, or if it was just added to the queue with that flag set).
3979               </para>
3980             </listitem>
3981           </itemizedlist>
3982         </para>
3983         <para>
3984           Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
3985           queue," even if another application already in the queue had specified
3986           DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
3987           that does not allow replacement goes away, and the next primary owner
3988           does allow replacement. In this case, queued items that specified
3989           DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
3990           automatically replace the new primary owner. In other words,
3991           DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
3992           time RequestName is called. This is deliberate to avoid an infinite loop
3993           anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT 
3994           and DBUS_NAME_FLAG_REPLACE_EXISTING.
3995         </para>
3996         <para>
3997           The flags argument contains any of the following values logically ORed
3998           together:
3999
4000           <informaltable>
4001             <tgroup cols="3">
4002               <thead>
4003                 <row>
4004                   <entry>Conventional Name</entry>
4005                   <entry>Value</entry>
4006                   <entry>Description</entry>
4007                 </row>
4008               </thead>
4009               <tbody>
4010                 <row>
4011                   <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
4012                   <entry>0x1</entry>
4013                   <entry>
4014
4015                     If an application A specifies this flag and succeeds in
4016                     becoming the owner of the name, and another application B
4017                     later calls RequestName with the
4018                     DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
4019                     will lose ownership and receive a
4020                     <literal>org.freedesktop.DBus.NameLost</literal> signal, and
4021                     application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
4022                     is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
4023                     is not specified by application B, then application B will not replace
4024                     application A as the owner.
4025
4026                   </entry>
4027                 </row>
4028                 <row>
4029                   <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
4030                   <entry>0x2</entry>
4031                   <entry>
4032
4033                     Try to replace the current owner if there is one. If this
4034                     flag is not set the application will only become the owner of
4035                     the name if there is no current owner. If this flag is set,
4036                     the application will replace the current owner if
4037                     the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
4038
4039                   </entry>
4040                 </row>
4041                 <row>
4042                   <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
4043                   <entry>0x4</entry>
4044                   <entry>
4045
4046                     Without this flag, if an application requests a name that is
4047                     already owned, the application will be placed in a queue to
4048                     own the name when the current owner gives it up. If this
4049                     flag is given, the application will not be placed in the
4050                     queue, the request for the name will simply fail.  This flag
4051                     also affects behavior when an application is replaced as
4052                     name owner; by default the application moves back into the
4053                     waiting queue, unless this flag was provided when the application
4054                     became the name owner.
4055
4056                   </entry>
4057                 </row>
4058               </tbody>
4059             </tgroup>
4060           </informaltable>
4061
4062           The return code can be one of the following values:
4063
4064           <informaltable>
4065             <tgroup cols="3">
4066               <thead>
4067                 <row>
4068                   <entry>Conventional Name</entry>
4069                   <entry>Value</entry>
4070                   <entry>Description</entry>
4071                 </row>
4072               </thead>
4073               <tbody>
4074                 <row>
4075                   <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
4076                   <entry>1</entry> <entry>The caller is now the primary owner of
4077                   the name, replacing any previous owner. Either the name had no
4078                   owner before, or the caller specified
4079                   DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
4080                   DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
4081                 </row>
4082                 <row>
4083                   <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
4084                   <entry>2</entry>
4085
4086                   <entry>The name already had an owner,
4087                     DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
4088                     the current owner did not specify
4089                     DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
4090                     application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
4091                     </entry>
4092                 </row>
4093                 <row>
4094                   <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
4095                   <entry>The name already has an owner,
4096                   DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
4097                   DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
4098                   current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
4099                   specified by the requesting application.</entry>
4100                 </row>
4101                 <row>
4102                   <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
4103                   <entry>4</entry>
4104                   <entry>The application trying to request ownership of a name is already the owner of it.</entry>
4105                 </row>
4106               </tbody>
4107             </tgroup>
4108           </informaltable>
4109         </para>
4110        </sect3>
4111
4112        <sect3 id="bus-messages-release-name">
4113         <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
4114         <para>
4115           As a method:
4116           <programlisting>
4117             UINT32 ReleaseName (in STRING name)
4118           </programlisting>
4119           Message arguments:
4120           <informaltable>
4121             <tgroup cols="3">
4122               <thead>
4123                 <row>
4124                   <entry>Argument</entry>
4125                   <entry>Type</entry>
4126                   <entry>Description</entry>
4127                 </row>
4128               </thead>
4129               <tbody>
4130                 <row>
4131                   <entry>0</entry>
4132                   <entry>STRING</entry>
4133                   <entry>Name to release</entry>
4134                 </row>
4135               </tbody>
4136             </tgroup>
4137           </informaltable>
4138           Reply arguments:
4139           <informaltable>
4140             <tgroup cols="3">
4141               <thead>
4142                 <row>
4143                   <entry>Argument</entry>
4144                   <entry>Type</entry>
4145                   <entry>Description</entry>
4146                 </row>
4147               </thead>
4148               <tbody>
4149                 <row>
4150                   <entry>0</entry>
4151                   <entry>UINT32</entry>
4152                   <entry>Return value</entry>
4153                 </row>
4154               </tbody>
4155             </tgroup>
4156           </informaltable>
4157         </para>
4158         <para>
4159           This method call should be sent to
4160           <literal>org.freedesktop.DBus</literal> and asks the message bus to
4161           release the method caller's claim to the given name. If the caller is
4162           the primary owner, a new primary owner will be selected from the
4163           queue if any other owners are waiting. If the caller is waiting in
4164           the queue for the name, the caller will removed from the queue and
4165           will not be made an owner of the name if it later becomes available.
4166           If there are no other owners in the queue for the name, it will be
4167           removed from the bus entirely.
4168
4169           The return code can be one of the following values:
4170
4171           <informaltable>
4172             <tgroup cols="3">
4173               <thead>
4174                 <row>
4175                   <entry>Conventional Name</entry>
4176                   <entry>Value</entry>
4177                   <entry>Description</entry>
4178                 </row>
4179               </thead>
4180               <tbody>
4181                 <row>
4182                   <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
4183                   <entry>1</entry> <entry>The caller has released his claim on
4184                   the given name. Either the caller was the primary owner of
4185                   the name, and the name is now unused or taken by somebody
4186                   waiting in the queue for the name, or the caller was waiting
4187                   in the queue for the name and has now been removed from the
4188                   queue.</entry>
4189                 </row>
4190                 <row>
4191                   <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
4192                   <entry>2</entry>
4193                   <entry>The given name does not exist on this bus.</entry>
4194                 </row>
4195                 <row>
4196                   <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
4197                   <entry>3</entry>
4198                   <entry>The caller was not the primary owner of this name,
4199                   and was also not waiting in the queue to own this name.</entry>
4200                 </row>
4201               </tbody>
4202             </tgroup>
4203           </informaltable>
4204         </para>
4205        </sect3>
4206
4207        <sect3 id="bus-messages-list-queued-owners">
4208         <title><literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
4209         <para>
4210           As a method:
4211           <programlisting>
4212             ARRAY of STRING ListQueuedOwners (in STRING name)
4213           </programlisting>
4214           Message arguments:
4215           <informaltable>
4216             <tgroup cols="3">
4217               <thead>
4218                 <row>
4219                   <entry>Argument</entry>
4220                   <entry>Type</entry>
4221                   <entry>Description</entry>
4222                 </row>
4223               </thead>
4224               <tbody>
4225                 <row>
4226                   <entry>0</entry>
4227                   <entry>STRING</entry>
4228                   <entry>The well-known bus name to query, such as
4229                     <literal>com.example.cappuccino</literal></entry>
4230                 </row>
4231               </tbody>
4232             </tgroup>
4233           </informaltable>
4234           Reply arguments:
4235           <informaltable>
4236             <tgroup cols="3">
4237               <thead>
4238                 <row>
4239                   <entry>Argument</entry>
4240                   <entry>Type</entry>
4241                   <entry>Description</entry>
4242                 </row>
4243               </thead>
4244               <tbody>
4245                 <row>
4246                   <entry>0</entry>
4247                   <entry>ARRAY of STRING</entry>
4248                   <entry>The unique bus names of connections currently queued
4249                     for the name</entry>
4250                 </row>
4251               </tbody>
4252             </tgroup>
4253           </informaltable>
4254         </para>
4255         <para>
4256           This method call should be sent to
4257           <literal>org.freedesktop.DBus</literal> and lists the connections
4258           currently queued for a bus name (see
4259           <xref linkend="term-queued-owner"/>).
4260         </para>
4261        </sect3>
4262     </sect2>
4263
4264     <sect2 id="message-bus-routing">
4265       <title>Message Bus Message Routing</title>
4266
4267       <para>
4268         Messages may have a <literal>DESTINATION</literal> field (see <xref
4269           linkend="message-protocol-header-fields"/>), resulting in a
4270         <firstterm>unicast message</firstterm>.  If the
4271         <literal>DESTINATION</literal> field is present, it specifies a message
4272         recipient by name. Method calls and replies normally specify this field.
4273         The message bus must send messages (of any type) with the
4274         <literal>DESTINATION</literal> field set to the specified recipient,
4275         regardless of whether the recipient has set up a match rule matching
4276         the message.
4277       </para>
4278
4279       <para>
4280         When the message bus receives a signal, if the
4281         <literal>DESTINATION</literal> field is absent, it is considered to
4282         be a <firstterm>broadcast signal</firstterm>, and is sent to all
4283         applications with <firstterm>message matching rules</firstterm> that
4284         match the message. Most signal messages are broadcasts.
4285       </para>
4286
4287       <para>
4288         Unicast signal messages (those with a <literal>DESTINATION</literal>
4289         field) are not commonly used, but they are treated like any unicast
4290         message: they are delivered to the specified receipient,
4291         regardless of its match rules.  One use for unicast signals is to
4292         avoid a race condition in which a signal is emitted before the intended
4293         recipient can call <xref linkend="bus-messages-add-match"/> to
4294         receive that signal: if the signal is sent directly to that recipient
4295         using a unicast message, it does not need to add a match rule at all,
4296         and there is no race condition.  Another use for unicast signals,
4297         on message buses whose security policy prevents eavesdropping, is to
4298         send sensitive information which should only be visible to one
4299         recipient.
4300       </para>
4301
4302       <para>
4303         When the message bus receives a method call, if the
4304         <literal>DESTINATION</literal> field is absent, the call is taken to be
4305         a standard one-to-one message and interpreted by the message bus
4306         itself. For example, sending an
4307         <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
4308         <literal>DESTINATION</literal> will cause the message bus itself to
4309         reply to the ping immediately; the message bus will not make this
4310         message visible to other applications.
4311       </para>
4312
4313       <para>
4314         Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
4315         the ping message were sent with a <literal>DESTINATION</literal> name of
4316         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
4317         forwarded, and the Yoyodyne Corporation screensaver application would be
4318         expected to reply to the ping.
4319       </para>
4320
4321       <para>
4322         Message bus implementations may impose a security policy which
4323         prevents certain messages from being sent or received.
4324         When a message cannot be sent or received due to a security
4325         policy, the message bus should send an error reply, unless the
4326         original message had the <literal>NO_REPLY</literal> flag.
4327       </para>
4328
4329       <sect3 id="message-bus-routing-eavesdropping">
4330         <title>Eavesdropping</title>
4331         <para>
4332           Receiving a unicast message whose <literal>DESTINATION</literal>
4333           indicates a different recipient is called
4334           <firstterm>eavesdropping</firstterm>. On a message bus which acts as
4335           a security boundary (like the standard system bus), the security
4336           policy should usually prevent eavesdropping, since unicast messages
4337           are normally kept private and may contain security-sensitive
4338           information.
4339         </para>
4340
4341         <para>
4342           Eavesdropping is mainly useful for debugging tools, such as
4343           the <literal>dbus-monitor</literal> tool in the reference
4344           implementation of D-Bus. Tools which eavesdrop on the message bus
4345           should be careful to avoid sending a reply or error in response to
4346           messages intended for a different client.
4347         </para>
4348
4349         <para>
4350           Clients may attempt to eavesdrop by adding match rules
4351           (see <xref linkend="message-bus-routing-match-rules"/>) containing
4352           the <literal>eavesdrop='true'</literal> match. If the message bus'
4353           security policy does not allow eavesdropping, the match rule can
4354           still be added, but will not have any practical effect. For
4355           compatibility with older message bus implementations, if adding such
4356           a match rule results in an error reply, the client may fall back to
4357           adding the same rule with the <literal>eavesdrop</literal> match
4358           omitted.
4359         </para>
4360       </sect3>
4361
4362       <sect3 id="message-bus-routing-match-rules">
4363         <title>Match Rules</title>
4364         <para>
4365           An important part of the message bus routing protocol is match
4366           rules. Match rules describe the messages that should be sent to a
4367           client, based on the contents of the message.  Broadcast signals
4368           are only sent to clients which have a suitable match rule: this
4369           avoids waking up client processes to deal with signals that are
4370           not relevant to that client.
4371         </para>
4372         <para>
4373           Messages that list a client as their <literal>DESTINATION</literal>
4374           do not need to match the client's match rules, and are sent to that
4375           client regardless. As a result, match rules are mainly used to
4376           receive a subset of broadcast signals.
4377         </para>
4378         <para>
4379           Match rules can also be used for eavesdropping
4380           (see <xref linkend="message-bus-routing-eavesdropping"/>),
4381           if the security policy of the message bus allows it.
4382         </para>
4383         <para>
4384           Match rules are added using the AddMatch bus method 
4385           (see <xref linkend="bus-messages-add-match"/>).  Rules are
4386           specified as a string of comma separated key/value pairs. 
4387           Excluding a key from the rule indicates a wildcard match.  
4388           For instance excluding the the member from a match rule but 
4389           adding a sender would let all messages from that sender through.
4390           An example of a complete rule would be 
4391           "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
4392         </para>
4393         <para>
4394           The following table describes the keys that can be used to create 
4395           a match rule:
4396           The following table summarizes the D-Bus types.
4397           <informaltable>
4398             <tgroup cols="3">
4399               <thead>
4400                 <row>
4401                   <entry>Key</entry>
4402                   <entry>Possible Values</entry>
4403                   <entry>Description</entry>
4404                 </row>
4405               </thead>
4406               <tbody>
4407                 <row>
4408                   <entry><literal>type</literal></entry>
4409                   <entry>'signal', 'method_call', 'method_return', 'error'</entry>
4410                   <entry>Match on the message type.  An example of a type match is type='signal'</entry>
4411                 </row>
4412                 <row>
4413                   <entry><literal>sender</literal></entry>
4414                   <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
4415                   and <xref linkend="term-unique-name"/> respectively)
4416                   </entry>
4417                   <entry>Match messages sent by a particular sender.  An example of a sender match
4418                   is sender='org.freedesktop.Hal'</entry>
4419                 </row>
4420                 <row>
4421                   <entry><literal>interface</literal></entry>
4422                   <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
4423                   <entry>Match messages sent over or to a particular interface.  An example of an
4424                   interface match is interface='org.freedesktop.Hal.Manager'.
4425                   If a message omits the interface header, it must not match any rule 
4426                   that specifies this key.</entry>
4427                 </row>
4428                 <row>
4429                   <entry><literal>member</literal></entry>
4430                   <entry>Any valid method or signal name</entry>
4431                   <entry>Matches messages which have the give method or signal name. An example of
4432                   a member match is member='NameOwnerChanged'</entry>
4433                 </row>
4434                 <row>
4435                   <entry><literal>path</literal></entry>
4436                   <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
4437                   <entry>Matches messages which are sent from or to the given object. An example of a
4438                   path match is path='/org/freedesktop/Hal/Manager'</entry>
4439                 </row>
4440                 <row>
4441                   <entry><literal>path_namespace</literal></entry>
4442                   <entry>An object path</entry>
4443                   <entry>
4444                     <para>
4445                       Matches messages which are sent from or to an
4446                       object for which the object path is either the
4447                       given value, or that value followed by one or
4448                       more path components.
4449                     </para>
4450
4451                     <para>
4452                       For example,
4453                       <literal>path_namespace='/com/example/foo'</literal>
4454                       would match signals sent by
4455                       <literal>/com/example/foo</literal>
4456                       or by
4457                       <literal>/com/example/foo/bar</literal>,
4458                       but not by
4459                       <literal>/com/example/foobar</literal>.
4460                     </para>
4461
4462                     <para>
4463                       Using both <literal>path</literal> and
4464                       <literal>path_namespace</literal> in the same match
4465                       rule is not allowed.
4466                     </para>
4467
4468                     <para>
4469                       <emphasis>
4470                         This match key was added in version 0.16 of the
4471                         D-Bus specification and implemented by the bus
4472                         daemon in dbus 1.5.0 and later.
4473                       </emphasis>
4474                     </para>
4475                 </entry>
4476                 </row>
4477                 <row>
4478                   <entry><literal>destination</literal></entry>
4479                   <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
4480                   <entry>Matches messages which are being sent to the given unique name. An
4481                   example of a destination match is destination=':1.0'</entry>
4482                 </row>
4483                 <row>
4484                   <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
4485                   <entry>Any string</entry>
4486                   <entry>Arg matches are special and are used for further restricting the 
4487                   match based on the arguments in the body of a message. Only arguments of type
4488                   STRING can be matched in this way. An example of an argument match 
4489                   would be arg3='Foo'. Only argument indexes from 0 to 63 should be 
4490                   accepted.</entry>
4491                 </row>
4492                 <row>
4493                   <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
4494                   <entry>Any string</entry>
4495                   <entry>
4496                     <para>Argument path matches provide a specialised form of wildcard matching for
4497                       path-like namespaces. They can match arguments whose type is either STRING or
4498                       OBJECT_PATH. As with normal argument matches,
4499                       if the argument is exactly equal to the string given in the match
4500                       rule then the rule is satisfied. Additionally, there is also a
4501                       match when either the string given in the match rule or the
4502                       appropriate message argument ends with '/' and is a prefix of the
4503                       other. An example argument path match is arg0path='/aa/bb/'. This
4504                       would match messages with first arguments of '/', '/aa/',
4505                       '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
4506                       messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
4507
4508                     <para>This is intended for monitoring “directories” in file system-like
4509                       hierarchies, as used in the <citetitle>dconf</citetitle> configuration
4510                       system. An application interested in all nodes in a particular hierarchy would
4511                       monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
4512                       emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
4513                       represent a modification to the “bar” property, or a signal with zeroth
4514                       argument <literal>"/ca/example/"</literal> to represent atomic modification of
4515                       many properties within that directory, and the interested application would be
4516                       notified in both cases.</para>
4517                     <para>
4518                       <emphasis>
4519                         This match key was added in version 0.12 of the
4520                         D-Bus specification, implemented for STRING
4521                         arguments by the bus daemon in dbus 1.2.0 and later,
4522                         and implemented for OBJECT_PATH arguments in dbus 1.5.0
4523                         and later.
4524                       </emphasis>
4525                     </para>
4526                   </entry>
4527                 </row>
4528                 <row>
4529                   <entry><literal>arg0namespace</literal></entry>
4530                   <entry>Like a bus name, except that the string is not
4531                     required to contain a '.' (period)</entry>
4532                   <entry>
4533                     <para>Match messages whose first argument is of type STRING, and is a bus name
4534                       or interface name within the specified namespace. This is primarily intended
4535                       for watching name owner changes for a group of related bus names, rather than
4536                       for a single name or all name changes.</para>
4537
4538                     <para>Because every valid interface name is also a valid
4539                       bus name, this can also be used for messages whose
4540                       first argument is an interface name.</para>
4541
4542                     <para>For example, the match rule
4543                       <literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
4544                       matches name owner changes for bus names such as
4545                       <literal>com.example.backend.foo</literal>,
4546                       <literal>com.example.backend.foo.bar</literal>, and
4547                       <literal>com.example.backend</literal> itself.</para>
4548
4549                     <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
4550                     <para>
4551                       <emphasis>
4552                         This match key was added in version 0.16 of the
4553                         D-Bus specification and implemented by the bus
4554                         daemon in dbus 1.5.0 and later.
4555                       </emphasis>
4556                     </para>
4557                   </entry>
4558                 </row>
4559                 <row>
4560                   <entry><literal>eavesdrop</literal></entry>
4561                   <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
4562                   <entry>Since D-Bus 1.5.6, match rules do not
4563                     match messages which have a <literal>DESTINATION</literal>
4564                     field unless the match rule specifically
4565                     requests this
4566                     (see <xref linkend="message-bus-routing-eavesdropping"/>)
4567                     by specifying <literal>eavesdrop='true'</literal>
4568                     in the match rule.  <literal>eavesdrop='false'</literal>
4569                     restores the default behaviour. Messages are
4570                     delivered to their <literal>DESTINATION</literal>
4571                     regardless of match rules, so this match does not
4572                     affect normal delivery of unicast messages.
4573                     If the message bus has a security policy which forbids
4574                     eavesdropping, this match may still be used without error,
4575                     but will not have any practical effect.
4576                     In older versions of D-Bus, this match was not allowed
4577                     in match rules, and all match rules behaved as if
4578                     <literal>eavesdrop='true'</literal> had been used.
4579                   </entry>
4580                 </row>
4581               </tbody>
4582             </tgroup>
4583           </informaltable>
4584         </para>
4585       </sect3>
4586     </sect2>
4587     <sect2 id="message-bus-starting-services">
4588       <title>Message Bus Starting Services</title>
4589       <para>
4590         The message bus can start applications on behalf of other applications.
4591         In CORBA terms, this would be called <firstterm>activation</firstterm>.
4592         An application that can be started in this way is called a
4593         <firstterm>service</firstterm>.
4594       </para>
4595       <para>
4596         With D-Bus, starting a service is normally done by name. That is,
4597         applications ask the message bus to start some program that will own a
4598         well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
4599         This implies a contract documented along with the name 
4600         <literal>org.freedesktop.TextEditor</literal> for which objects 
4601         the owner of that name will provide, and what interfaces those 
4602         objects will have.
4603       </para>
4604       <para>
4605         To find an executable corresponding to a particular name, the bus daemon
4606         looks for <firstterm>service description files</firstterm>.  Service
4607         description files define a mapping from names to executables. Different
4608         kinds of message bus will look for these files in different places, see
4609         <xref linkend="message-bus-types"/>.
4610       </para>
4611       <para>
4612         Service description files have the ".service" file
4613         extension. The message bus will only load service description files
4614         ending with .service; all other files will be ignored.  The file format
4615         is similar to that of <ulink
4616         url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
4617         entries</ulink>. All service description files must be in UTF-8
4618         encoding. To ensure that there will be no name collisions, service files
4619         must be namespaced using the same mechanism as messages and service
4620         names.
4621       </para>
4622
4623       <para>
4624         [FIXME the file format should be much better specified than "similar to
4625         .desktop entries" esp. since desktop entries are already
4626         badly-specified. ;-)]
4627         These sections from the specification apply to service files as well:
4628
4629         <itemizedlist>
4630           <listitem><para>General syntax</para></listitem>
4631           <listitem><para>Comment format</para></listitem>
4632         </itemizedlist>
4633
4634         <figure>
4635           <title>Example service description file</title>
4636           <programlisting>
4637             # Sample service description file
4638             [D-BUS Service]
4639             Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
4640             Exec=/usr/libexec/gconfd-2
4641           </programlisting>
4642         </figure>
4643       </para>
4644       <para>
4645         When an application asks to start a service by name, the bus daemon tries to
4646         find a service that will own that name. It then tries to spawn the
4647         executable associated with it. If this fails, it will report an
4648         error. [FIXME what happens if two .service files offer the same service;
4649         what kind of error is reported, should we have a way for the client to
4650         choose one?]
4651       </para>
4652       <para>
4653         The executable launched will have the environment variable
4654         <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
4655         message bus so it can connect and request the appropriate names.
4656       </para>
4657       <para>
4658         The executable being launched may want to know whether the message bus
4659         starting it is one of the well-known message buses (see <xref
4660         linkend="message-bus-types"/>). To facilitate this, the bus must also set
4661         the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
4662         of the well-known buses. The currently-defined values for this variable
4663         are <literal>system</literal> for the systemwide message bus,
4664         and <literal>session</literal> for the per-login-session message
4665         bus. The new executable must still connect to the address given
4666         in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
4667         resulting connection is to the well-known bus.
4668       </para>
4669       <para>
4670         [FIXME there should be a timeout somewhere, either specified
4671         in the .service file, by the client, or just a global value
4672         and if the client being activated fails to connect within that
4673         timeout, an error should be sent back.]
4674       </para>
4675
4676       <sect3 id="message-bus-starting-services-scope">
4677         <title>Message Bus Service Scope</title>
4678         <para>
4679           The "scope" of a service is its "per-", such as per-session,
4680           per-machine, per-home-directory, or per-display. The reference
4681           implementation doesn't yet support starting services in a different
4682           scope from the message bus itself. So e.g. if you start a service
4683           on the session bus its scope is per-session.
4684         </para>
4685         <para>
4686           We could add an optional scope to a bus name. For example, for
4687           per-(display,session pair), we could have a unique ID for each display
4688           generated automatically at login and set on screen 0 by executing a
4689           special "set display ID" binary. The ID would be stored in a
4690           <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
4691           random bytes. This ID would then be used to scope names.
4692           Starting/locating a service could be done by ID-name pair rather than
4693           only by name.
4694         </para>
4695         <para>
4696           Contrast this with a per-display scope. To achieve that, we would 
4697           want a single bus spanning all sessions using a given display.
4698           So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal> 
4699           property on screen 0 of the display, pointing to this bus.
4700         </para>
4701       </sect3>
4702     </sect2>
4703
4704     <sect2 id="message-bus-types">
4705       <title>Well-known Message Bus Instances</title>
4706       <para>
4707         Two standard message bus instances are defined here, along with how 
4708         to locate them and where their service files live.
4709       </para>
4710       <sect3 id="message-bus-types-login">
4711         <title>Login session message bus</title>
4712         <para>
4713           Each time a user logs in, a <firstterm>login session message
4714             bus</firstterm> may be started. All applications in the user's login
4715           session may interact with one another using this message bus.
4716         </para>
4717         <para>
4718           The address of the login session message bus is given 
4719           in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment 
4720           variable. If that variable is not set, applications may 
4721           also try to read the address from the X Window System root 
4722           window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
4723           The root window property must have type <literal>STRING</literal>.
4724           The environment variable should have precedence over the 
4725           root window property.
4726         </para>
4727         <para>The address of the login session message bus is given in the
4728         <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment variable. If
4729         DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string
4730         "autolaunch:", the system should use platform-specific methods of
4731         locating a running D-Bus session server, or starting one if a running
4732         instance cannot be found. Note that this mechanism is not recommended
4733         for attempting to determine if a daemon is running. It is inherently
4734         racy to attempt to make this determination, since the bus daemon may
4735         be started just before or just after the determination is made.
4736         Therefore, it is recommended that applications do not try to make this
4737         determination for their functionality purposes, and instead they
4738         should attempt to start the server.</para>
4739
4740         <sect4 id="message-bus-types-login-x-windows">
4741           <title>X Windowing System</title>
4742           <para>
4743             For the X Windowing System, the application must locate the
4744             window owner of the selection represented by the atom formed by
4745             concatenating:
4746             <itemizedlist>
4747               <listitem>
4748                 <para>the literal string "_DBUS_SESSION_BUS_SELECTION_"</para>
4749               </listitem>
4750
4751               <listitem>
4752                 <para>the current user's username</para>
4753               </listitem>
4754
4755               <listitem>
4756                 <para>the literal character '_' (underscore)</para>
4757               </listitem>
4758
4759               <listitem>
4760                 <para>the machine's ID</para>
4761               </listitem>
4762             </itemizedlist>
4763           </para>
4764
4765           <para>
4766             The following properties are defined for the window that owns
4767             this X selection:
4768             <informaltable frame="all">
4769               <tgroup cols="2">
4770                 <tbody>
4771                   <row>
4772                     <entry>
4773                       <para>Atom</para>
4774                     </entry>
4775
4776                     <entry>
4777                       <para>meaning</para>
4778                     </entry>
4779                   </row>
4780
4781                   <row>
4782                     <entry>
4783                       <para>_DBUS_SESSION_BUS_ADDRESS</para>
4784                     </entry>
4785
4786                     <entry>
4787                       <para>the actual address of the server socket</para>
4788                     </entry>
4789                   </row>
4790
4791                   <row>
4792                     <entry>
4793                       <para>_DBUS_SESSION_BUS_PID</para>
4794                     </entry>
4795
4796                     <entry>
4797                       <para>the PID of the server process</para>
4798                     </entry>
4799                   </row>
4800                 </tbody>
4801               </tgroup>
4802             </informaltable>
4803           </para>
4804
4805           <para>
4806             At least the _DBUS_SESSION_BUS_ADDRESS property MUST be
4807             present in this window.
4808           </para>
4809
4810           <para>
4811             If the X selection cannot be located or if reading the
4812             properties from the window fails, the implementation MUST conclude
4813             that there is no D-Bus server running and proceed to start a new
4814             server. (See below on concurrency issues)
4815           </para>
4816
4817           <para>
4818             Failure to connect to the D-Bus server address thus obtained
4819             MUST be treated as a fatal connection error and should be reported
4820             to the application.
4821           </para>
4822
4823           <para>
4824             As an alternative, an implementation MAY find the information
4825             in the following file located in the current user's home directory,
4826             in subdirectory .dbus/session-bus/:
4827             <itemizedlist>
4828               <listitem>
4829                 <para>the machine's ID</para>
4830               </listitem>
4831
4832               <listitem>
4833                 <para>the literal character '-' (dash)</para>
4834               </listitem>
4835
4836               <listitem>
4837                 <para>the X display without the screen number, with the
4838                 following prefixes removed, if present: ":", "localhost:"
4839                 ."localhost.localdomain:". That is, a display of
4840                 "localhost:10.0" produces just the number "10"</para>
4841               </listitem>
4842             </itemizedlist>
4843           </para>
4844
4845           <para>
4846             The contents of this file NAME=value assignment pairs and
4847             lines starting with # are comments (no comments are allowed
4848             otherwise). The following variable names are defined:
4849             <informaltable
4850               frame="all">
4851               <tgroup cols="2">
4852                 <tbody>
4853                   <row>
4854                     <entry>
4855                       <para>Variable</para>
4856                     </entry>
4857
4858                     <entry>
4859                       <para>meaning</para>
4860                     </entry>
4861                   </row>
4862
4863                   <row>
4864                     <entry>
4865                       <para>DBUS_SESSION_BUS_ADDRESS</para>
4866                     </entry>
4867
4868                     <entry>
4869                       <para>the actual address of the server socket</para>
4870                     </entry>
4871                   </row>
4872
4873                   <row>
4874                     <entry>
4875                       <para>DBUS_SESSION_BUS_PID</para>
4876                     </entry>
4877
4878                     <entry>
4879                       <para>the PID of the server process</para>
4880                     </entry>
4881                   </row>
4882
4883                   <row>
4884                     <entry>
4885                       <para>DBUS_SESSION_BUS_WINDOWID</para>
4886                     </entry>
4887
4888                     <entry>
4889                       <para>the window ID</para>
4890                     </entry>
4891                   </row>
4892                 </tbody>
4893               </tgroup>
4894             </informaltable>
4895           </para>
4896
4897           <para>
4898             At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
4899             in this file.
4900           </para>
4901
4902           <para>
4903             Failure to open this file MUST be interpreted as absence of a
4904             running server. Therefore, the implementation MUST proceed to
4905             attempting to launch a new bus server if the file cannot be
4906             opened.
4907           </para>
4908
4909           <para>
4910             However, success in opening this file MUST NOT lead to the
4911             conclusion that the server is running. Thus, a failure to connect to
4912             the bus address obtained by the alternative method MUST NOT be
4913             considered a fatal error. If the connection cannot be established,
4914             the implementation MUST proceed to check the X selection settings or
4915             to start the server on its own.
4916           </para>
4917
4918           <para>
4919             If the implementation concludes that the D-Bus server is not
4920             running it MUST attempt to start a new server and it MUST also
4921             ensure that the daemon started as an effect of the "autolaunch"
4922             mechanism provides the lookup mechanisms described above, so
4923             subsequent calls can locate the newly started server. The
4924             implementation MUST also ensure that if two or more concurrent
4925             initiations happen, only one server remains running and all other
4926             initiations are able to obtain the address of this server and
4927             connect to it. In other words, the implementation MUST ensure that
4928             the X selection is not present when it attempts to set it, without
4929             allowing another process to set the selection between the
4930             verification and the setting (e.g., by using XGrabServer /
4931             XungrabServer).
4932           </para>
4933         </sect4>
4934         <sect4>
4935           <title></title>
4936           <para>
4937             On Unix systems, the session bus should search for .service files
4938             in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
4939             by the
4940             <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
4941             Implementations may also search additional locations, which
4942             should be searched with lower priority than anything in
4943             XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
4944             for example, the reference implementation also
4945             looks in <literal>${datadir}/dbus-1/services</literal> as
4946             set at compile time.
4947           </para>
4948           <para>
4949             As described in the XDG Base Directory Specification, software
4950             packages should install their session .service files to their
4951             configured <literal>${datadir}/dbus-1/services</literal>,
4952             where <literal>${datadir}</literal> is as defined by the GNU
4953             coding standards. System administrators or users can arrange
4954             for these service files to be read by setting XDG_DATA_DIRS or by
4955             symlinking them into the default locations.
4956           </para>
4957         </sect4>
4958       </sect3>
4959       <sect3 id="message-bus-types-system">
4960         <title>System message bus</title>
4961         <para>
4962           A computer may have a <firstterm>system message bus</firstterm>,
4963           accessible to all applications on the system. This message bus may be
4964           used to broadcast system events, such as adding new hardware devices, 
4965           changes in the printer queue, and so forth.
4966         </para>
4967         <para>
4968           The address of the system message bus is given 
4969           in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment 
4970           variable. If that variable is not set, applications should try 
4971           to connect to the well-known address
4972           <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
4973           <footnote>
4974             <para>
4975               The D-Bus reference implementation actually honors the 
4976               <literal>$(localstatedir)</literal> configure option 
4977               for this address, on both client and server side.
4978             </para>
4979           </footnote>
4980         </para>
4981         <para>
4982           On Unix systems, the system bus should default to searching
4983           for .service files in
4984           <literal>/usr/local/share/dbus-1/system-services</literal>,
4985           <literal>/usr/share/dbus-1/system-services</literal> and
4986           <literal>/lib/dbus-1/system-services</literal>, with that order
4987           of precedence. It may also search other implementation-specific
4988           locations, but should not vary these locations based on environment
4989           variables.
4990           <footnote>
4991             <para>
4992               The system bus is security-sensitive and is typically executed
4993               by an init system with a clean environment. Its launch helper
4994               process is particularly security-sensitive, and specifically
4995               clears its own environment.
4996             </para>
4997           </footnote>
4998         </para>
4999         <para>
5000           Software packages should install their system .service
5001           files to their configured
5002           <literal>${datadir}/dbus-1/system-services</literal>,
5003           where <literal>${datadir}</literal> is as defined by the GNU
5004           coding standards. System administrators can arrange
5005           for these service files to be read by editing the system bus'
5006           configuration file or by symlinking them into the default
5007           locations.
5008         </para>
5009       </sect3>
5010     </sect2>
5011
5012     <sect2 id="message-bus-messages">
5013       <title>Message Bus Messages</title>
5014       <para>
5015         The special message bus name <literal>org.freedesktop.DBus</literal>
5016         responds to a number of additional messages.
5017       </para>
5018
5019       <sect3 id="bus-messages-hello">
5020         <title><literal>org.freedesktop.DBus.Hello</literal></title>
5021         <para>
5022           As a method:
5023           <programlisting>
5024             STRING Hello ()
5025           </programlisting>
5026           Reply arguments:
5027           <informaltable>
5028             <tgroup cols="3">
5029               <thead>
5030                 <row>
5031                   <entry>Argument</entry>
5032                   <entry>Type</entry>
5033                   <entry>Description</entry>
5034                 </row>
5035               </thead>
5036               <tbody>
5037                 <row>
5038                   <entry>0</entry>
5039                   <entry>STRING</entry>
5040                   <entry>Unique name assigned to the connection</entry>
5041                 </row>
5042               </tbody>
5043             </tgroup>
5044           </informaltable>
5045         </para>
5046         <para>
5047           Before an application is able to send messages to other applications
5048           it must send the <literal>org.freedesktop.DBus.Hello</literal> message
5049           to the message bus to obtain a unique name. If an application without
5050           a unique name tries to send a message to another application, or a
5051           message to the message bus itself that isn't the
5052           <literal>org.freedesktop.DBus.Hello</literal> message, it will be
5053           disconnected from the bus.
5054         </para>
5055         <para>
5056           There is no corresponding "disconnect" request; if a client wishes to
5057           disconnect from the bus, it simply closes the socket (or other 
5058           communication channel).
5059         </para>
5060       </sect3>
5061       <sect3 id="bus-messages-list-names">
5062         <title><literal>org.freedesktop.DBus.ListNames</literal></title>
5063         <para>
5064           As a method:
5065           <programlisting>
5066             ARRAY of STRING ListNames ()
5067           </programlisting>
5068           Reply arguments:
5069           <informaltable>
5070             <tgroup cols="3">
5071               <thead>
5072                 <row>
5073                   <entry>Argument</entry>
5074                   <entry>Type</entry>
5075                   <entry>Description</entry>
5076                 </row>
5077               </thead>
5078               <tbody>
5079                 <row>
5080                   <entry>0</entry>
5081                   <entry>ARRAY of STRING</entry>
5082                   <entry>Array of strings where each string is a bus name</entry>
5083                 </row>
5084               </tbody>
5085             </tgroup>
5086           </informaltable>
5087         </para>
5088         <para>
5089           Returns a list of all currently-owned names on the bus.
5090         </para>
5091       </sect3>
5092       <sect3 id="bus-messages-list-activatable-names">
5093         <title><literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
5094         <para>
5095           As a method:
5096           <programlisting>
5097             ARRAY of STRING ListActivatableNames ()
5098           </programlisting>
5099           Reply arguments:
5100           <informaltable>
5101             <tgroup cols="3">
5102               <thead>
5103                 <row>
5104                   <entry>Argument</entry>
5105                   <entry>Type</entry>
5106                   <entry>Description</entry>
5107                 </row>
5108               </thead>
5109               <tbody>
5110                 <row>
5111                   <entry>0</entry>
5112                   <entry>ARRAY of STRING</entry>
5113                   <entry>Array of strings where each string is a bus name</entry>
5114                 </row>
5115               </tbody>
5116             </tgroup>
5117           </informaltable>
5118         </para>
5119         <para>
5120           Returns a list of all names that can be activated on the bus.
5121         </para>
5122       </sect3>
5123       <sect3 id="bus-messages-name-exists">
5124         <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
5125         <para>
5126           As a method:
5127           <programlisting>
5128             BOOLEAN NameHasOwner (in STRING name)
5129           </programlisting>
5130           Message arguments:
5131           <informaltable>
5132             <tgroup cols="3">
5133               <thead>
5134                 <row>
5135                   <entry>Argument</entry>
5136                   <entry>Type</entry>
5137                   <entry>Description</entry>
5138                 </row>
5139               </thead>
5140               <tbody>
5141                 <row>
5142                   <entry>0</entry>
5143                   <entry>STRING</entry>
5144                   <entry>Name to check</entry>
5145                 </row>
5146               </tbody>
5147             </tgroup>
5148           </informaltable>
5149           Reply arguments:
5150           <informaltable>
5151             <tgroup cols="3">
5152               <thead>
5153                 <row>
5154                   <entry>Argument</entry>
5155                   <entry>Type</entry>
5156                   <entry>Description</entry>
5157                 </row>
5158               </thead>
5159               <tbody>
5160                 <row>
5161                   <entry>0</entry>
5162                   <entry>BOOLEAN</entry>
5163                   <entry>Return value, true if the name exists</entry>
5164                 </row>
5165               </tbody>
5166             </tgroup>
5167           </informaltable>
5168         </para>
5169         <para>
5170           Checks if the specified name exists (currently has an owner).
5171         </para>
5172       </sect3>
5173
5174       <sect3 id="bus-messages-name-owner-changed">
5175         <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
5176         <para>
5177           This is a signal:
5178           <programlisting>
5179             NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
5180           </programlisting>
5181           Message arguments:
5182           <informaltable>
5183             <tgroup cols="3">
5184               <thead>
5185                 <row>
5186                   <entry>Argument</entry>
5187                   <entry>Type</entry>
5188                   <entry>Description</entry>
5189                 </row>
5190               </thead>
5191               <tbody>
5192                 <row>
5193                   <entry>0</entry>
5194                   <entry>STRING</entry>
5195                   <entry>Name with a new owner</entry>
5196                 </row>
5197                 <row>
5198                   <entry>1</entry>
5199                   <entry>STRING</entry>
5200                   <entry>Old owner or empty string if none</entry>
5201                 </row>
5202                 <row>
5203                   <entry>2</entry>
5204                   <entry>STRING</entry>
5205                   <entry>New owner or empty string if none</entry>
5206                 </row>
5207               </tbody>
5208             </tgroup>
5209           </informaltable>
5210         </para>
5211         <para>
5212           This signal indicates that the owner of a name has changed.
5213           It's also the signal to use to detect the appearance of 
5214           new names on the bus.
5215         </para>
5216       </sect3>
5217       <sect3 id="bus-messages-name-lost">
5218         <title><literal>org.freedesktop.DBus.NameLost</literal></title>
5219         <para>
5220           This is a signal:
5221           <programlisting>
5222             NameLost (STRING name)
5223           </programlisting>
5224           Message arguments:
5225           <informaltable>
5226             <tgroup cols="3">
5227               <thead>
5228                 <row>
5229                   <entry>Argument</entry>
5230                   <entry>Type</entry>
5231                   <entry>Description</entry>
5232                 </row>
5233               </thead>
5234               <tbody>
5235                 <row>
5236                   <entry>0</entry>
5237                   <entry>STRING</entry>
5238                   <entry>Name which was lost</entry>
5239                 </row>
5240               </tbody>
5241             </tgroup>
5242           </informaltable>
5243         </para>
5244         <para>
5245           This signal is sent to a specific application when it loses
5246           ownership of a name.
5247         </para>
5248       </sect3>
5249
5250       <sect3 id="bus-messages-name-acquired">
5251         <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
5252         <para>
5253           This is a signal:
5254           <programlisting>
5255             NameAcquired (STRING name)
5256           </programlisting>
5257           Message arguments:
5258           <informaltable>
5259             <tgroup cols="3">
5260               <thead>
5261                 <row>
5262                   <entry>Argument</entry>
5263                   <entry>Type</entry>
5264                   <entry>Description</entry>
5265                 </row>
5266               </thead>
5267               <tbody>
5268                 <row>
5269                   <entry>0</entry>
5270                   <entry>STRING</entry>
5271                   <entry>Name which was acquired</entry>
5272                 </row>
5273               </tbody>
5274             </tgroup>
5275           </informaltable>
5276         </para>
5277         <para>
5278           This signal is sent to a specific application when it gains
5279           ownership of a name.
5280         </para>
5281       </sect3>
5282
5283       <sect3 id="bus-messages-start-service-by-name">
5284         <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
5285         <para>
5286           As a method:
5287           <programlisting>
5288             UINT32 StartServiceByName (in STRING name, in UINT32 flags)
5289           </programlisting>
5290           Message arguments:
5291           <informaltable>
5292             <tgroup cols="3">
5293               <thead>
5294                 <row>
5295                   <entry>Argument</entry>
5296                   <entry>Type</entry>
5297                   <entry>Description</entry>
5298                 </row>
5299               </thead>
5300               <tbody>
5301                 <row>
5302                   <entry>0</entry>
5303                   <entry>STRING</entry>
5304                   <entry>Name of the service to start</entry>
5305                 </row>
5306                 <row>
5307                   <entry>1</entry>
5308                   <entry>UINT32</entry>
5309                   <entry>Flags (currently not used)</entry>
5310                 </row>
5311               </tbody>
5312             </tgroup>
5313           </informaltable>
5314         Reply arguments:
5315         <informaltable>
5316           <tgroup cols="3">
5317             <thead>
5318               <row>
5319                 <entry>Argument</entry>
5320                 <entry>Type</entry>
5321                 <entry>Description</entry>
5322               </row>
5323             </thead>
5324             <tbody>
5325               <row>
5326                 <entry>0</entry>
5327                 <entry>UINT32</entry>
5328                 <entry>Return value</entry>
5329               </row>
5330             </tbody>
5331           </tgroup>
5332         </informaltable>
5333           Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
5334
5335         </para>
5336         <para>
5337           The return value can be one of the following values:
5338           <informaltable>
5339             <tgroup cols="3">
5340               <thead>
5341                 <row>
5342                   <entry>Identifier</entry>
5343                   <entry>Value</entry>
5344                   <entry>Description</entry>
5345                 </row>
5346               </thead>
5347               <tbody>
5348                 <row>
5349                   <entry>DBUS_START_REPLY_SUCCESS</entry>
5350                   <entry>1</entry>
5351                   <entry>The service was successfully started.</entry>
5352                 </row>
5353                 <row>
5354                   <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
5355                   <entry>2</entry>
5356                   <entry>A connection already owns the given name.</entry>
5357                 </row>
5358               </tbody>
5359              </tgroup>
5360            </informaltable>
5361         </para>
5362
5363       </sect3>
5364
5365       <sect3 id="bus-messages-update-activation-environment">
5366         <title><literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
5367         <para>
5368           As a method:
5369           <programlisting>
5370             UpdateActivationEnvironment (in ARRAY of DICT&lt;STRING,STRING&gt; environment)
5371           </programlisting>
5372           Message arguments:
5373           <informaltable>
5374             <tgroup cols="3">
5375               <thead>
5376                 <row>
5377                   <entry>Argument</entry>
5378                   <entry>Type</entry>
5379                   <entry>Description</entry>
5380                 </row>
5381               </thead>
5382               <tbody>
5383                 <row>
5384                   <entry>0</entry>
5385                   <entry>ARRAY of DICT&lt;STRING,STRING&gt;</entry>
5386                   <entry>Environment to add or update</entry>
5387                 </row>
5388               </tbody>
5389             </tgroup>
5390             </informaltable>
5391             Normally, session bus activated services inherit the environment of the bus daemon.  This method adds to or modifies that environment when activating services.
5392         </para>
5393         <para>
5394           Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.
5395         </para>
5396         <para>
5397           Note, both the environment variable names and values must be valid UTF-8.  There's no way to update the activation environment with data that is invalid UTF-8.
5398         </para>
5399
5400       </sect3>
5401
5402       <sect3 id="bus-messages-get-name-owner">
5403         <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
5404         <para>
5405           As a method:
5406           <programlisting>
5407             STRING GetNameOwner (in STRING name)
5408           </programlisting>
5409           Message arguments:
5410           <informaltable>
5411             <tgroup cols="3">
5412               <thead>
5413                 <row>
5414                   <entry>Argument</entry>
5415                   <entry>Type</entry>
5416                   <entry>Description</entry>
5417                 </row>
5418               </thead>
5419               <tbody>
5420                 <row>
5421                   <entry>0</entry>
5422                   <entry>STRING</entry>
5423                   <entry>Name to get the owner of</entry>
5424                 </row>
5425               </tbody>
5426             </tgroup>
5427           </informaltable>
5428         Reply arguments:
5429         <informaltable>
5430           <tgroup cols="3">
5431             <thead>
5432               <row>
5433                 <entry>Argument</entry>
5434                 <entry>Type</entry>
5435                 <entry>Description</entry>
5436               </row>
5437             </thead>
5438             <tbody>
5439               <row>
5440                 <entry>0</entry>
5441                 <entry>STRING</entry>
5442                 <entry>Return value, a unique connection name</entry>
5443               </row>
5444             </tbody>
5445           </tgroup>
5446         </informaltable>
5447         Returns the unique connection name of the primary owner of the name
5448         given. If the requested name doesn't have an owner, returns a
5449         <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
5450        </para>
5451       </sect3>
5452
5453       <sect3 id="bus-messages-get-connection-unix-user">
5454         <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
5455         <para>
5456           As a method:
5457           <programlisting>
5458             UINT32 GetConnectionUnixUser (in STRING bus_name)
5459           </programlisting>
5460           Message arguments:
5461           <informaltable>
5462             <tgroup cols="3">
5463               <thead>
5464                 <row>
5465                   <entry>Argument</entry>
5466                   <entry>Type</entry>
5467                   <entry>Description</entry>
5468                 </row>
5469               </thead>
5470               <tbody>
5471                 <row>
5472                   <entry>0</entry>
5473                   <entry>STRING</entry>
5474                   <entry>Unique or well-known bus name of the connection to
5475                     query, such as <literal>:12.34</literal> or
5476                     <literal>com.example.tea</literal></entry>
5477                 </row>
5478               </tbody>
5479             </tgroup>
5480           </informaltable>
5481         Reply arguments:
5482         <informaltable>
5483           <tgroup cols="3">
5484             <thead>
5485               <row>
5486                 <entry>Argument</entry>
5487                 <entry>Type</entry>
5488                 <entry>Description</entry>
5489               </row>
5490             </thead>
5491             <tbody>
5492               <row>
5493                 <entry>0</entry>
5494                 <entry>UINT32</entry>
5495                 <entry>Unix user ID</entry>
5496               </row>
5497             </tbody>
5498           </tgroup>
5499         </informaltable>
5500         Returns the Unix user ID of the process connected to the server. If
5501         unable to determine it (for instance, because the process is not on the
5502         same machine as the bus daemon), an error is returned.
5503        </para>
5504       </sect3>
5505
5506       <sect3 id="bus-messages-get-connection-unix-process-id">
5507         <title><literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
5508         <para>
5509           As a method:
5510           <programlisting>
5511             UINT32 GetConnectionUnixProcessID (in STRING bus_name)
5512           </programlisting>
5513           Message arguments:
5514           <informaltable>
5515             <tgroup cols="3">
5516               <thead>
5517                 <row>
5518                   <entry>Argument</entry>
5519                   <entry>Type</entry>
5520                   <entry>Description</entry>
5521                 </row>
5522               </thead>
5523               <tbody>
5524                 <row>
5525                   <entry>0</entry>
5526                   <entry>STRING</entry>
5527                   <entry>Unique or well-known bus name of the connection to
5528                     query, such as <literal>:12.34</literal> or
5529                     <literal>com.example.tea</literal></entry>
5530                 </row>
5531               </tbody>
5532             </tgroup>
5533           </informaltable>
5534         Reply arguments:
5535         <informaltable>
5536           <tgroup cols="3">
5537             <thead>
5538               <row>
5539                 <entry>Argument</entry>
5540                 <entry>Type</entry>
5541                 <entry>Description</entry>
5542               </row>
5543             </thead>
5544             <tbody>
5545               <row>
5546                 <entry>0</entry>
5547                 <entry>UINT32</entry>
5548                 <entry>Unix process id</entry>
5549               </row>
5550             </tbody>
5551           </tgroup>
5552         </informaltable>
5553         Returns the Unix process ID of the process connected to the server. If
5554         unable to determine it (for instance, because the process is not on the
5555         same machine as the bus daemon), an error is returned.
5556        </para>
5557       </sect3>
5558
5559       <sect3 id="bus-messages-add-match">
5560         <title><literal>org.freedesktop.DBus.AddMatch</literal></title>
5561         <para>
5562           As a method:
5563           <programlisting>
5564             AddMatch (in STRING rule)
5565           </programlisting>
5566           Message arguments:
5567           <informaltable>
5568             <tgroup cols="3">
5569               <thead>
5570                 <row>
5571                   <entry>Argument</entry>
5572                   <entry>Type</entry>
5573                   <entry>Description</entry>
5574                 </row>
5575               </thead>
5576               <tbody>
5577                 <row>
5578                   <entry>0</entry>
5579                   <entry>STRING</entry>
5580                   <entry>Match rule to add to the connection</entry>
5581                 </row>
5582               </tbody>
5583             </tgroup>
5584           </informaltable>
5585         Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>). 
5586         If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
5587         error is returned.
5588        </para>
5589       </sect3>
5590       <sect3 id="bus-messages-remove-match">
5591         <title><literal>org.freedesktop.DBus.RemoveMatch</literal></title>
5592         <para>
5593           As a method:
5594           <programlisting>
5595             RemoveMatch (in STRING rule)
5596           </programlisting>
5597           Message arguments:
5598           <informaltable>
5599             <tgroup cols="3">
5600               <thead>
5601                 <row>
5602                   <entry>Argument</entry>
5603                   <entry>Type</entry>
5604                   <entry>Description</entry>
5605                 </row>
5606               </thead>
5607               <tbody>
5608                 <row>
5609                   <entry>0</entry>
5610                   <entry>STRING</entry>
5611                   <entry>Match rule to remove from the connection</entry>
5612                 </row>
5613               </tbody>
5614             </tgroup>
5615           </informaltable>
5616         Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>). 
5617         If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
5618         error is returned.
5619        </para>
5620       </sect3>
5621
5622       <sect3 id="bus-messages-get-id">
5623         <title><literal>org.freedesktop.DBus.GetId</literal></title>
5624         <para>
5625           As a method:
5626           <programlisting>
5627             GetId (out STRING id)
5628           </programlisting>
5629         Reply arguments:
5630         <informaltable>
5631           <tgroup cols="3">
5632             <thead>
5633               <row>
5634                 <entry>Argument</entry>
5635                 <entry>Type</entry>
5636                 <entry>Description</entry>
5637               </row>
5638             </thead>
5639             <tbody>
5640               <row>
5641                 <entry>0</entry>
5642                 <entry>STRING</entry>
5643                 <entry>Unique ID identifying the bus daemon</entry>
5644               </row>
5645             </tbody>
5646           </tgroup>
5647         </informaltable>
5648         Gets the unique ID of the bus. The unique ID here is shared among all addresses the 
5649         bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in 
5650         <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique 
5651         ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
5652         There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
5653         by org.freedesktop.DBus.Peer.GetMachineId().
5654         For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
5655         </para>
5656       </sect3>
5657
5658     </sect2>
5659
5660   </sect1>
5661 <!--
5662   <appendix id="implementation-notes">
5663     <title>Implementation notes</title>
5664     <sect1 id="implementation-notes-subsection">
5665       <title></title>
5666       <para>
5667       </para>
5668     </sect1>
5669   </appendix>
5670 -->
5671
5672   <glossary><title>Glossary</title>
5673     <para>
5674       This glossary defines some of the terms used in this specification.
5675     </para>
5676
5677     <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
5678       <glossdef>
5679         <para>
5680           The message bus maintains an association between names and
5681           connections. (Normally, there's one connection per application.)  A
5682           bus name is simply an identifier used to locate connections. For
5683           example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
5684           name might be used to send a message to a screensaver from Yoyodyne
5685           Corporation.  An application is said to <firstterm>own</firstterm> a
5686           name if the message bus has associated the application's connection
5687           with the name.  Names may also have <firstterm>queued
5688           owners</firstterm> (see <xref linkend="term-queued-owner"/>).
5689             The bus assigns a unique name to each connection, 
5690             see <xref linkend="term-unique-name"/>. Other names 
5691               can be thought of as "well-known names" and are 
5692               used to find applications that offer specific functionality.
5693         </para>
5694
5695         <para>
5696           See <xref linkend="message-protocol-names-bus"/> for details of
5697           the syntax and naming conventions for bus names.
5698         </para>
5699       </glossdef>
5700     </glossentry>
5701       
5702     <glossentry id="term-message"><glossterm>Message</glossterm>
5703       <glossdef>
5704         <para>
5705           A message is the atomic unit of communication via the D-Bus
5706           protocol. It consists of a <firstterm>header</firstterm> and a
5707           <firstterm>body</firstterm>; the body is made up of
5708           <firstterm>arguments</firstterm>.
5709         </para>
5710       </glossdef>
5711     </glossentry>
5712
5713     <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
5714       <glossdef>
5715         <para>
5716           The message bus is a special application that forwards 
5717           or routes messages between a group of applications
5718           connected to the message bus. It also manages 
5719           <firstterm>names</firstterm> used for routing
5720           messages.
5721         </para>
5722       </glossdef>
5723     </glossentry>
5724
5725     <glossentry id="term-name"><glossterm>Name</glossterm>
5726       <glossdef>
5727         <para>
5728           See <xref linkend="term-bus-name"/>. "Name" may 
5729             also be used to refer to some of the other names
5730             in D-Bus, such as interface names.
5731         </para>
5732       </glossdef>
5733     </glossentry>
5734
5735     <glossentry id="namespace"><glossterm>Namespace</glossterm>
5736       <glossdef>
5737         <para>
5738           Used to prevent collisions when defining new interfaces, bus names
5739           etc. The convention used is the same one Java uses for defining
5740           classes: a reversed domain name.
5741           See <xref linkend="message-protocol-names-bus"/>,
5742           <xref linkend="message-protocol-names-interface"/>,
5743           <xref linkend="message-protocol-names-error"/>,
5744           <xref linkend="message-protocol-marshaling-object-path"/>.
5745         </para>
5746       </glossdef>
5747     </glossentry>
5748
5749     <glossentry id="term-object"><glossterm>Object</glossterm>
5750       <glossdef>
5751         <para>
5752           Each application contains <firstterm>objects</firstterm>, which have
5753           <firstterm>interfaces</firstterm> and
5754           <firstterm>methods</firstterm>. Objects are referred to by a name,
5755           called a <firstterm>path</firstterm>.
5756         </para>
5757       </glossdef>
5758     </glossentry>
5759
5760     <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
5761       <glossdef>
5762         <para>
5763           An application talking directly to another application, without going
5764           through a message bus. One-to-one connections may be "peer to peer" or
5765           "client to server." The D-Bus protocol has no concept of client
5766           vs. server after a connection has authenticated; the flow of messages
5767           is symmetrical (full duplex).
5768         </para>
5769       </glossdef>
5770     </glossentry>
5771
5772     <glossentry id="term-path"><glossterm>Path</glossterm>
5773       <glossdef>
5774         <para>
5775           Object references (object names) in D-Bus are organized into a
5776           filesystem-style hierarchy, so each object is named by a path. As in
5777           LDAP, there's no difference between "files" and "directories"; a path
5778           can refer to an object, while still having child objects below it.
5779         </para>
5780       </glossdef>
5781     </glossentry>
5782
5783     <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
5784       <glossdef>
5785         <para>
5786           Each bus name has a primary owner; messages sent to the name go to the
5787           primary owner. However, certain names also maintain a queue of
5788           secondary owners "waiting in the wings." If the primary owner releases
5789           the name, then the first secondary owner in the queue automatically
5790           becomes the new owner of the name.
5791         </para>
5792       </glossdef>
5793     </glossentry>
5794
5795     <glossentry id="term-service"><glossterm>Service</glossterm>
5796       <glossdef>
5797         <para>
5798           A service is an executable that can be launched by the bus daemon.
5799           Services normally guarantee some particular features, for example they
5800           may guarantee that they will request a specific name such as
5801           "org.freedesktop.Screensaver", have a singleton object
5802           "/org/freedesktop/Application", and that object will implement the
5803           interface "org.freedesktop.ScreensaverControl".
5804         </para>
5805       </glossdef>
5806     </glossentry>
5807
5808     <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
5809       <glossdef>
5810         <para>
5811           ".service files" tell the bus about service applications that can be
5812           launched (see <xref linkend="term-service"/>). Most importantly they
5813           provide a mapping from bus names to services that will request those
5814             names when they start up.
5815         </para>
5816       </glossdef>
5817     </glossentry>
5818
5819     <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
5820       <glossdef>
5821         <para>
5822           The special name automatically assigned to each connection by the
5823           message bus. This name will never change owner, and will be unique
5824           (never reused during the lifetime of the message bus).
5825           It will begin with a ':' character.
5826         </para>
5827       </glossdef>
5828     </glossentry>
5829
5830   </glossary>
5831 </article>