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
   7 <article id="index">
   8   <articleinfo>
   9     <title>D-BUS Specification</title>
  10     <releaseinfo>Version 0.10</releaseinfo>
  11     <date>28 January 2005</date>
  12     <authorgroup>
  13       <author>
  14         <firstname>Havoc</firstname>
  15         <surname>Pennington</surname>
  16         <affiliation>
  17           <orgname>Red Hat, Inc.</orgname>
  18           <address>
  19             <email>hp@pobox.com</email>
  20           </address>
  21         </affiliation>
  22       </author>
  23       <author>
  24         <firstname>Anders</firstname>
  25         <surname>Carlsson</surname>
  26         <affiliation>
  27           <orgname>CodeFactory AB</orgname>
  28           <address>
  29             <email>andersca@codefactory.se</email>
  30           </address>
  31         </affiliation>
  32       </author>
  33       <author>
  34         <firstname>Alexander</firstname>
  35         <surname>Larsson</surname>
  36         <affiliation>
  37           <orgname>Red Hat, Inc.</orgname>
  38           <address>
  39             <email>alexl@redhat.com</email>
  40           </address>
  41         </affiliation>
  42       </author>
  43     </authorgroup>
  44   </articleinfo>
  45
  46   <sect1 id="introduction">
  47     <title>Introduction</title>
  48     <para>
  49       D-BUS is a system for low-latency, low-overhead, easy to use
  50       interprocess communication (IPC). In more detail:
  51       <itemizedlist>
  52         <listitem>
  53           <para>
  54             D-BUS is <emphasis>low-latency</emphasis> because it is designed
  55             to avoid round trips and allow asynchronous operation, much like
  56             the X protocol.
  57           </para>
  58         </listitem>
  59         <listitem>
  60           <para>
  61             D-BUS is <emphasis>low-overhead</emphasis> because it uses a
  62             binary protocol, and does not have to convert to and from a text
  63             format such as XML. Because D-BUS is intended for potentially
  64             high-resolution same-machine IPC, not primarily for Internet IPC,
  65             this is an interesting optimization.
  66           </para>
  67         </listitem>
  68         <listitem>
  69           <para>
  70             D-BUS is <emphasis>easy to use</emphasis> because it works in terms
  71             of <firstterm>messages</firstterm> rather than byte streams, and
  72             automatically handles a lot of the hard IPC issues. Also, the D-BUS
  73             library is designed to be wrapped in a way that lets developers use
  74             their framework's existing object/type system, rather than learning
  75             a new one specifically for IPC.
  76           </para>
  77         </listitem>
  78       </itemizedlist>
  79     </para>
  80
  81     <para>
  82       The base D-BUS protocol is a one-to-one (peer-to-peer or client-server)
  83       protocol, specified in <xref linkend="message-protocol"/>. That is, it is
  84       a system for one application to talk to a single other
  85       application. However, the primary intended application of the protocol is the
  86       D-BUS <firstterm>message bus</firstterm>, specified in <xref
  87       linkend="message-bus"/>. The message bus is a special application that
  88       accepts connections from multiple other applications, and forwards
  89       messages among them.
  90     </para>
  91
  92     <para>
  93       Uses of D-BUS include notification of system changes (notification of when
  94       a camera is plugged in to a computer, or a new version of some software
  95       has been installed), or desktop interoperability, for example a file
  96       monitoring service or a configuration service.
  97     </para>
  98
  99     <para>
 100       D-BUS is designed for two specific use cases:
 101       <itemizedlist>
 102         <listitem>
 103           <para>
 104             A "system bus" for notifications from the system to user sessions,
 105             and to allow the system to request input from user sessions.
 106           </para>
 107         </listitem>
 108         <listitem>
 109           <para>
 110             A "session bus" used to implement desktop environments such as
 111             GNOME and KDE.
 112           </para>
 113         </listitem>
 114       </itemizedlist>
 115       D-BUS is not intended to be a generic IPC system for any possible
 116       application, and intentionally omits many features found in other
 117       IPC systems for this reason. D-BUS may turn out to be useful
 118       in unanticipated applications, but future versions of this
 119       spec and the reference implementation probably will not
 120       incorporate features that interfere with the core use cases.
 121     </para>
 122
 123   </sect1>
 124
 125   <sect1 id="message-protocol">
 126     <title>Message Protocol</title>
 127
 128     <para>
 129       A <firstterm>message</firstterm> consists of a
 130       <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
 131       think of a message as a package, the header is the address, and the body
 132       contains the package contents. The message delivery system uses the header
 133       information to figure out where to send the message and how to interpret
 134       it; the recipient inteprets the body of the message.
 135     </para>
 136
 137     <para>
 138       The body of the message is made up of zero or more
 139       <firstterm>arguments</firstterm>, which are typed values, such as an
 140       integer or a byte array.
 141     </para>
 142
 143     <para>
 144       Both header and body use the same type system and format for
 145       serializing data. Each type of value has a wire format.
 146       Converting a value from some other representation into the wire
 147       format is called <firstterm>marshaling</firstterm> and converting
 148       it back from the wire format is <firstterm>unmarshaling</firstterm>.
 149     </para>
 150
 151     <sect2 id="message-protocol-signatures">
 152       <title>Type Signatures</title>
 153
 154       <para>
 155         The D-BUS protocol does not include type tags in the marshaled data; a
 156         block of marshaled values must have a known <firstterm>type
 157         signature</firstterm>.  The type signature is made up of <firstterm>type
 158         codes</firstterm>. A type code is an ASCII character representing the
 159         type of a value. Because ASCII characters are used, the type signature
 160         will always form a valid ASCII string. A simple string compare
 161         determines whether two type signatures are equivalent.
 162       </para>
 163
 164       <para>
 165         As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
 166         the ASCII character 'i'. So the signature for a block of values
 167         containing a single <literal>INT32</literal> would be:
 168         <programlisting>
 169           "i"
 170         </programlisting>
 171         A block of values containing two <literal>INT32</literal> would have this signature:
 172         <programlisting>
 173           "ii"
 174         </programlisting>
 175       </para>
 176
 177       <para>
 178         All <firstterm>basic</firstterm> types work like
 179         <literal>INT32</literal> in this example. To marshal and unmarshal
 180         basic types, you simply read one value from the data
 181         block corresponding to each type code in the signature.
 182         In addition to basic types, there are three <firstterm>container</firstterm>
 183         types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, and <literal>VARIANT</literal>.
 184       </para>
 185
 186       <para>
 187         <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
 188         code does not appear in signatures. Instead, ASCII characters
 189         '(' and ')' are used to mark the beginning and end of the struct.
 190         So for example, a struct containing two integers would have this
 191         signature:
 192         <programlisting>
 193           "(ii)"
 194         </programlisting>
 195         Structs can be nested, so for example a struct containing
 196         an integer and another struct:
 197         <programlisting>
 198           "(i(ii))"
 199         </programlisting>
 200         The value block storing that struct would contain three integers; the
 201         type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
 202         "(iii)" or "iii".
 203       </para>
 204
 205       <para>
 206         The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
 207         but is useful in code that implements the protocol. This type code
 208         is specified to allow such code to interoperate in non-protocol contexts.
 209       </para>
 210
 211       <para>
 212         <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
 213         followed by a <firstterm>single complete type</firstterm>. The single
 214         complete type following the array is the type of each array element. So
 215         the simple example is:
 216         <programlisting>
 217           "ai"
 218         </programlisting>
 219         which is an array of 32-bit integers. But an array can be of any type,
 220         such as this array-of-struct-with-two-int32-fields:
 221         <programlisting>
 222           "a(ii)"
 223         </programlisting>
 224         Or this array of array of integer:
 225         <programlisting>
 226           "aai"
 227         </programlisting>
 228       </para>
 229
 230       <para>
 231         The phrase <firstterm>single complete type</firstterm> deserves some
 232         definition. A single complete type is a basic type code, a variant type code,
 233         an array with its element type, or a struct with its fields.
 234         So the following signatures are not single complete types:
 235         <programlisting>
 236           "aa"
 237         </programlisting>
 238         <programlisting>
 239           "(ii"
 240         </programlisting>
 241         <programlisting>
 242           "ii)"
 243         </programlisting>
 244         And the following signatures contain multiple complete types:
 245         <programlisting>
 246           "ii"
 247         </programlisting>
 248         <programlisting>
 249           "aiai"
 250         </programlisting>
 251         <programlisting>
 252           "(ii)(ii)"
 253         </programlisting>
 254         Note however that a single complete type may <emphasis>contain</emphasis>
 255         multiple other single complete types.
 256       </para>
 257
 258       <para>
 259         <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
 260         type <literal>VARIANT</literal> will have the signature of a single complete type as part
 261         of the <emphasis>value</emphasis>.  This signature will be followed by a
 262         marshaled value of that type.
 263       </para>
 264
 265       <para>
 266         A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
 267         than parentheses it uses curly braces, and it has more restrictions.
 268         The restrictions are: it occurs only as an array element type; and it
 269         has exactly two single complete types inside the curly
 270         braces. Implementations must not accept dict entries outside of arrays,
 271         and must not accept dict entries with zero, one, or more than two
 272         fields. A dict entry is always a key-value pair.
 273       </para>
 274
 275       <para>
 276         The first field in the <literal>DICT_ENTRY</literal> is always the key.
 277         A message is considered corrupt if the same key occurs twice in the same
 278         array of <literal>DICT_ENTRY</literal>. However, for performance reasons
 279         implementations are not required to reject dicts with duplicate keys.
 280       </para>
 281
 282       <para>
 283         In most languages, an array of dict entry would be represented as a
 284         map, hash table, or dict object.
 285       </para>
 286
 287       <para>
 288         The following table summarizes the D-BUS types.
 289         <informaltable>
 290           <tgroup cols="3">
 291             <thead>
 292               <row>
 293                 <entry>Conventional Name</entry>
 294                 <entry>Code</entry>
 295                 <entry>Description</entry>
 296               </row>
 297             </thead>
 298             <tbody>
 299               <row>
 300                 <entry><literal>INVALID</literal></entry>
 301                 <entry>0 (ASCII NUL)</entry>
 302                 <entry>Not a valid type code, used to terminate signatures</entry>
 303               </row><row>
 304                 <entry><literal>BYTE</literal></entry>
 305                 <entry>121 (ASCII 'y')</entry>
 306                 <entry>8-bit unsigned integer</entry>
 307               </row><row>
 308                 <entry><literal>BOOLEAN</literal></entry>
 309                 <entry>98 (ASCII 'b')</entry>
 310                 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
 311               </row><row>
 312                 <entry><literal>INT16</literal></entry>
 313                 <entry>110 (ASCII 'n')</entry>
 314                 <entry>16-bit signed integer</entry>
 315               </row><row>
 316                 <entry><literal>UINT16</literal></entry>
 317                 <entry>113 (ASCII 'q')</entry>
 318                 <entry>16-bit unsigned integer</entry>
 319               </row><row>
 320                 <entry><literal>INT32</literal></entry>
 321                 <entry>105 (ASCII 'i')</entry>
 322                 <entry>32-bit signed integer</entry>
 323               </row><row>
 324                 <entry><literal>UINT32</literal></entry>
 325                 <entry>117 (ASCII 'u')</entry>
 326                 <entry>32-bit unsigned integer</entry>
 327               </row><row>
 328                 <entry><literal>INT64</literal></entry>
 329                 <entry>120 (ASCII 'x')</entry>
 330                 <entry>64-bit signed integer</entry>
 331               </row><row>
 332                 <entry><literal>UINT64</literal></entry>
 333                 <entry>116 (ASCII 't')</entry>
 334                 <entry>64-bit unsigned integer</entry>
 335               </row><row>
 336                 <entry><literal>DOUBLE</literal></entry>
 337                 <entry>100 (ASCII 'd')</entry>
 338                 <entry>IEEE 754 double</entry>
 339               </row><row>
 340                 <entry><literal>STRING</literal></entry>
 341                 <entry>115 (ASCII 's')</entry>
 342                 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated.</entry>
 343               </row><row>
 344                 <entry><literal>OBJECT_PATH</literal></entry>
 345                 <entry>111 (ASCII 'o')</entry>
 346                 <entry>Name of an object instance</entry>
 347               </row><row>
 348                 <entry><literal>SIGNATURE</literal></entry>
 349                 <entry>103 (ASCII 'g')</entry>
 350                 <entry>A type signature</entry>
 351               </row><row>
 352                 <entry><literal>ARRAY</literal></entry>
 353                 <entry>97 (ASCII 'a')</entry>
 354                 <entry>Array</entry>
 355               </row><row>
 356                 <entry><literal>STRUCT</literal></entry>
 357                 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
 358                 <entry>Struct</entry>
 359               </row><row>
 360                 <entry><literal>VARIANT</literal></entry>
 361                 <entry>118 (ASCII 'v') </entry>
 362                 <entry>Variant type (the type of the value is part of the value itself)</entry>
 363               </row><row>
 364                 <entry><literal>DICT_ENTRY</literal></entry>
 365                 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
 366                 <entry>Entry in a dict or map (array of key-value pairs)</entry>
 367               </row>
 368             </tbody>
 369           </tgroup>
 370         </informaltable>
 371       </para>
 372
 373     </sect2>
 374
 375     <sect2 id="message-protocol-marshaling">
 376       <title>Marshaling (Wire Format)</title>
 377
 378       <para>
 379         Given a type signature, a block of bytes can be converted into typed
 380         values. This section describes the format of the block of bytes.  Byte
 381         order and alignment issues are handled uniformly for all D-BUS types.
 382       </para>
 383
 384       <para>
 385         A block of bytes has an associated byte order. The byte order
 386         has to be discovered in some way; for D-BUS messages, the
 387         byte order is part of the message header as described in
 388         <xref linkend="message-protocol-messages"/>. For now, assume
 389         that the byte order is known to be either little endian or big
 390           endian.
 391       </para>
 392
 393       <para>
 394         Each value in a block of bytes is aligned "naturally," for example
 395         4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
 396         8-byte boundary. To properly align a value, <firstterm>alignment
 397         padding</firstterm> may be necessary. The alignment padding must always
 398         be the minimum required padding to properly align the following value;
 399         and it must always be made up of nul bytes. The alignment padding must
 400         not be left uninitialized (it can't contain garbage), and more padding
 401         than required must not be used.
 402       </para>
 403
 404       <para>
 405         Given all this, the types are marshaled on the wire as follows:
 406         <informaltable>
 407           <tgroup cols="3">
 408             <thead>
 409               <row>
 410                 <entry>Conventional Name</entry>
 411                 <entry>Encoding</entry>
 412                 <entry>Alignment</entry>
 413               </row>
 414             </thead>
 415             <tbody>
 416               <row>
 417                 <entry><literal>INVALID</literal></entry>
 418                 <entry>Not applicable; cannot be marshaled.</entry>
 419                 <entry>N/A</entry>
 420               </row><row>
 421                 <entry><literal>BYTE</literal></entry>
 422                 <entry>A single 8-bit byte.</entry>
 423                 <entry>1</entry>
 424               </row><row>
 425                 <entry><literal>BOOLEAN</literal></entry>
 426                 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
 427                 <entry>4</entry>
 428               </row><row>
 429                 <entry><literal>INT16</literal></entry>
 430                 <entry>16-bit signed integer in the message's byte order.</entry>
 431                 <entry>2</entry>
 432               </row><row>
 433                 <entry><literal>UINT16</literal></entry>
 434                 <entry>16-bit unsigned integer in the message's byte order.</entry>
 435                 <entry>2</entry>
 436               </row><row>
 437                 <entry><literal>INT32</literal></entry>
 438                 <entry>32-bit signed integer in the message's byte order.</entry>
 439                 <entry>4</entry>
 440               </row><row>
 441                 <entry><literal>UINT32</literal></entry>
 442                 <entry>32-bit unsigned integer in the message's byte order.</entry>
 443                 <entry>4</entry>
 444               </row><row>
 445                 <entry><literal>INT64</literal></entry>
 446                 <entry>64-bit signed integer in the message's byte order.</entry>
 447                 <entry>8</entry>
 448               </row><row>
 449                 <entry><literal>UINT64</literal></entry>
 450                 <entry>64-bit unsigned integer in the message's byte order.</entry>
 451                 <entry>8</entry>
 452               </row><row>
 453                 <entry><literal>DOUBLE</literal></entry>
 454                 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
 455                 <entry>8</entry>
 456               </row><row>
 457                 <entry><literal>STRING</literal></entry>
 458                 <entry>A <literal>UINT32</literal> indicating the string's
 459                   length in bytes excluding its terminating nul, followed by
 460                   string data of the given length, followed by a terminating nul
 461                   byte.
 462                 </entry>
 463                 <entry>
 464                   4 (for the length)
 465                 </entry>
 466               </row><row>
 467                 <entry><literal>OBJECT_PATH</literal></entry>
 468                 <entry>Exactly the same as <literal>STRING</literal> except the
 469                   content must be a valid object path (see below).
 470                 </entry>
 471                 <entry>
 472                   4 (for the length)
 473                 </entry>
 474               </row><row>
 475                 <entry><literal>SIGNATURE</literal></entry>
 476                 <entry>The same as <literal>STRING</literal> except the length is a single
 477                   byte (thus signatures have a maximum length of 255)
 478                   and the content must be a valid signature (see below).
 479                 </entry>
 480                 <entry>
 481                   1
 482                 </entry>
 483               </row><row>
 484                 <entry><literal>ARRAY</literal></entry>
 485                 <entry>
 486                   A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
 487                   alignment padding to the alignment boundary of the array element type,
 488                   followed by each array element. The array length is from the
 489                   end of the alignment padding to the end of the last element,
 490                   i.e. it does not include the padding after the length,
 491                   or any padding after the last element.
 492                   Arrays have a maximum length defined to be 2 to the 26th power or
 493                   67108864. Implementations must not send or accept arrays exceeding this
 494                   length.
 495                 </entry>
 496                 <entry>
 497                   4 (for the length)
 498                 </entry>
 499               </row><row>
 500                 <entry><literal>STRUCT</literal></entry>
 501                 <entry>
 502                   A struct must start on an 8-byte boundary regardless of the
 503                   type of the struct fields. The struct value consists of each
 504                   field marshaled in sequence starting from that 8-byte
 505                   alignment boundary.
 506                 </entry>
 507                 <entry>
 508                   8
 509                 </entry>
 510               </row><row>
 511                 <entry><literal>VARIANT</literal></entry>
 512                 <entry>
 513                   A variant type has a marshaled <literal>SIGNATURE</literal>
 514                   followed by a marshaled value with the type
 515                   given in the signature.
 516                   Unlike a message signature, the variant signature
 517                   can contain only a single complete type.
 518                   So "i" is OK, "ii" is not.
 519                 </entry>
 520                 <entry>
 521                   1 (alignment of the signature)
 522                 </entry>
 523               </row><row>
 524                 <entry><literal>DICT_ENTRY</literal></entry>
 525                 <entry>
 526                   Identical to STRUCT.
 527                 </entry>
 528                 <entry>
 529                   8
 530                 </entry>
 531               </row>
 532             </tbody>
 533           </tgroup>
 534         </informaltable>
 535       </para>
 536
 537       <sect3 id="message-protocol-marshaling-object-path">
 538         <title>Valid Object Paths</title>
 539
 540         <para>
 541           An object path is a name used to refer to an object instance.
 542           Conceptually, each participant in a D-BUS message exchange may have
 543           any number of object instances (think of C++ or Java objects) and each
 544           such instance will have a path. Like a filesystem, the object
 545           instances in an application form a hierarchical tree.
 546         </para>
 547
 548         <para>
 549           The following rules define a valid object path. Implementations must
 550           not send or accept messages with invalid object paths.
 551           <itemizedlist>
 552             <listitem>
 553               <para>
 554                 The path may be of any length.
 555               </para>
 556             </listitem>
 557             <listitem>
 558               <para>
 559                 The path must begin with an ASCII '/' (integer 47) character,
 560                 and must consist of elements separated by slash characters.
 561               </para>
 562             </listitem>
 563             <listitem>
 564               <para>
 565                 Each element must only contain the ASCII characters
 566                 "[A-Z][a-z][0-9]_"
 567               </para>
 568             </listitem>
 569             <listitem>
 570               <para>
 571                 No element may be the empty string.
 572               </para>
 573             </listitem>
 574             <listitem>
 575               <para>
 576                 Multiple '/' characters cannot occur in sequence.
 577               </para>
 578             </listitem>
 579             <listitem>
 580               <para>
 581                 A trailing '/' character is not allowed unless the
 582                 path is the root path (a single '/' character).
 583               </para>
 584             </listitem>
 585           </itemizedlist>
 586         </para>
 587
 588       </sect3>
 589
 590
 591       <sect3 id="message-protocol-marshaling-signature">
 592         <title>Valid Signatures</title>
 593         <para>
 594           An implementation must not send or accept invalid signatures.
 595           Valid signatures will conform to the following rules:
 596           <itemizedlist>
 597             <listitem>
 598               <para>
 599                 The signature ends with a nul byte.
 600               </para>
 601             </listitem>
 602             <listitem>
 603               <para>
 604                 The signature is a list of single complete types.
 605                 Arrays must have element types, and structs must
 606                 have both open and close parentheses.
 607               </para>
 608             </listitem>
 609             <listitem>
 610               <para>
 611                 Only type codes and open and close parentheses are
 612                 allowed in the signature. The <literal>STRUCT</literal> type code
 613                 is not allowed in signatures, because parentheses
 614                 are used instead.
 615               </para>
 616             </listitem>
 617             <listitem>
 618               <para>
 619                 The maximum depth of container type nesting is 32 array type
 620                 codes and 32 open parentheses. This implies that the maximum
 621                 total depth of recursion is 64, for an "array of array of array
 622                 of ... struct of struct of struct of ..."  where there are 32
 623                 array and 32 struct.
 624               </para>
 625             </listitem>
 626             <listitem>
 627               <para>
 628                 The maximum length of a signature is 255.
 629               </para>
 630             </listitem>
 631             <listitem>
 632               <para>
 633                 Signatures must be nul-terminated.
 634               </para>
 635             </listitem>
 636           </itemizedlist>
 637         </para>
 638       </sect3>
 639
 640     </sect2>
 641
 642     <sect2 id="message-protocol-messages">
 643       <title>Message Format</title>
 644
 645       <para>
 646         A message consists of a header and a body. The header is a block of
 647         values with a fixed signature and meaning.  The body is a separate block
 648         of values, with a signature specified in the header.
 649       </para>
 650
 651       <para>
 652         The length of the header must be a multiple of 8, allowing the body to
 653         begin on an 8-byte boundary when storing the entire message in a single
 654         buffer. If the header does not naturally end on an 8-byte boundary
 655         up to 7 bytes of nul-initialized alignment padding must be added.
 656       </para>
 657
 658       <para>
 659         The message body need not end on an 8-byte boundary.
 660       </para>
 661
 662       <para>
 663         The maximum length of a message, including header, header alignment padding,
 664         and body is 2 to the 27th power or 134217728. Implementations must not
 665         send or accept messages exceeding this size.
 666       </para>
 667
 668       <para>
 669         The signature of the header is:
 670         <programlisting>
 671           "yyyyuua(yv)"
 672         </programlisting>
 673         Written out more readably, this is:
 674         <programlisting>
 675           BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
 676         </programlisting>
 677       </para>
 678
 679       <para>
 680         These values have the following meanings:
 681         <informaltable>
 682           <tgroup cols="2">
 683             <thead>
 684               <row>
 685                 <entry>Value</entry>
 686                 <entry>Description</entry>
 687               </row>
 688             </thead>
 689             <tbody>
 690               <row>
 691                 <entry>1st <literal>BYTE</literal></entry>
 692                 <entry>Endianness flag; ASCII 'l' for little-endian
 693                   or ASCII 'B' for big-endian. Both header and body are
 694                 in this endianness.</entry>
 695               </row>
 696               <row>
 697                 <entry>2nd <literal>BYTE</literal></entry>
 698                 <entry><firstterm>Message type</firstterm>. Unknown types MUST be ignored.
 699                   Currently-defined types are described below.
 700                 </entry>
 701               </row>
 702               <row>
 703                 <entry>3rd <literal>BYTE</literal></entry>
 704                 <entry>Bitwise OR of flags. Unknown flags
 705                   MUST be ignored. Currently-defined flags are described below.
 706                 </entry>
 707               </row>
 708               <row>
 709                 <entry>4th <literal>BYTE</literal></entry>
 710                 <entry>Major protocol version of the sending application.  If
 711                 the major protocol version of the receiving application does not
 712                 match, the applications will not be able to communicate and the
 713                 D-BUS connection MUST be disconnected. The major protocol
 714                 version for this version of the specification is 0.
 715                   FIXME this field is stupid and pointless to put in
 716                   every message.
 717                 </entry>
 718               </row>
 719               <row>
 720                 <entry>1st <literal>UINT32</literal></entry>
 721                 <entry>Length in bytes of the message body, starting
 722                   from the end of the header. The header ends after
 723                   its alignment padding to an 8-boundary.
 724                 </entry>
 725               </row>
 726               <row>
 727                 <entry>2nd <literal>UINT32</literal></entry>
 728                 <entry>The serial of this message, used as a cookie
 729                   by the sender to identify the reply corresponding
 730                   to this request.
 731                 </entry>
 732               </row>
 733               <row>
 734                 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
 735                 <entry>An array of zero or more <firstterm>header
 736                   fields</firstterm> where the byte is the field code, and the
 737                   variant is the field value. The message type determines
 738                   which fields are required.
 739                 </entry>
 740               </row>
 741             </tbody>
 742           </tgroup>
 743         </informaltable>
 744       </para>
 745       <para>
 746         <firstterm>Message types</firstterm> that can appear in the second byte
 747         of the header are:
 748         <informaltable>
 749           <tgroup cols="3">
 750             <thead>
 751               <row>
 752                 <entry>Conventional name</entry>
 753                 <entry>Decimal value</entry>
 754                 <entry>Description</entry>
 755               </row>
 756             </thead>
 757             <tbody>
 758               <row>
 759                 <entry><literal>INVALID</literal></entry>
 760                 <entry>0</entry>
 761                 <entry>This is an invalid type, if seen in a message
 762                   the connection should be dropped immediately.</entry>
 763               </row>
 764               <row>
 765                 <entry><literal>METHOD_CALL</literal></entry>
 766                 <entry>1</entry>
 767                 <entry>Method call.</entry>
 768               </row>
 769               <row>
 770                 <entry><literal>METHOD_RETURN</literal></entry>
 771                 <entry>2</entry>
 772                 <entry>Method reply with returned data.</entry>
 773               </row>
 774               <row>
 775                 <entry><literal>ERROR</literal></entry>
 776                 <entry>3</entry>
 777                 <entry>Error reply. If the first argument exists and is a
 778                 string, it is an error message.</entry>
 779               </row>
 780               <row>
 781                 <entry><literal>SIGNAL</literal></entry>
 782                 <entry>4</entry>
 783                 <entry>Signal emission.</entry>
 784               </row>
 785             </tbody>
 786           </tgroup>
 787         </informaltable>
 788       </para>
 789       <para>
 790         Flags that can appear in the third byte of the header:
 791         <informaltable>
 792           <tgroup cols="3">
 793             <thead>
 794               <row>
 795                 <entry>Conventional name</entry>
 796                 <entry>Hex value</entry>
 797                 <entry>Description</entry>
 798               </row>
 799             </thead>
 800             <tbody>
 801               <row>
 802                 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
 803                 <entry>0x1</entry>
 804                 <entry>This message does not expect method return replies or
 805                 error replies; the reply can be omitted as an
 806                 optimization. However, it is compliant with this specification
 807                 to return the reply despite this flag.</entry>
 808               </row>
 809               <row>
 810                 <entry><literal>NO_AUTO_START</literal></entry>
 811                 <entry>0x2</entry>
 812                 <entry>This message should not automatically launch an owner
 813                   for the destination name.
 814                 </entry>
 815               </row>
 816             </tbody>
 817           </tgroup>
 818         </informaltable>
 819       </para>
 820
 821       <sect3 id="message-protocol-header-fields">
 822         <title>Header Fields</title>
 823
 824         <para>
 825           The array at the end of the header contains <firstterm>header
 826           fields</firstterm>, where each field is a 1-byte field code followed
 827           by a field value. A header must contain the required header fields for
 828           its message type, and zero or more of any optional header
 829           fields. Future versions of this protocol specification may add new
 830           fields. Implementations must ignore fields they do not
 831           understand. Implementations must not invent their own header fields;
 832           only changes to this specification may introduce new header fields.
 833         </para>
 834
 835         <para>
 836           Again, if an implementation sees a header field code that it does not
 837           expect, it MUST ignore that field, as it will be part of a new
 838           (but compatible) version of this specification. This also applies
 839           to known header fields appearing in unexpected messages, for
 840           example if a signal has a reply serial that should be ignored
 841           even though it has no meaning as of this version of the spec.
 842         </para>
 843
 844         <para>
 845           However, implementations must not send or accept known header fields
 846           with the wrong type stored in the field value. So for example
 847           a message with an <literal>INTERFACE</literal> field of type <literal>UINT32</literal> would be considered
 848           corrupt.
 849         </para>
 850
 851         <para>
 852           Here are the currently-defined header fields:
 853           <informaltable>
 854             <tgroup cols="5">
 855               <thead>
 856                 <row>
 857                   <entry>Conventional Name</entry>
 858                   <entry>Decimal Code</entry>
 859                   <entry>Type</entry>
 860                   <entry>Required In</entry>
 861                   <entry>Description</entry>
 862                 </row>
 863               </thead>
 864               <tbody>
 865                 <row>
 866                   <entry><literal>INVALID</literal></entry>
 867                   <entry>0</entry>
 868                   <entry>N/A</entry>
 869                   <entry>not allowed</entry>
 870                   <entry>Not a valid field name (error if it appears in a message)</entry>
 871                 </row>
 872                 <row>
 873                   <entry><literal>PATH</literal></entry>
 874                   <entry>1</entry>
 875                   <entry><literal>OBJECT_PATH</literal></entry>
 876                   <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
 877                   <entry>The object to send a call to,
 878                     or the object a signal is emitted from.
 879                   </entry>
 880                 </row>
 881                 <row>
 882                   <entry><literal>INTERFACE</literal></entry>
 883                   <entry>2</entry>
 884                   <entry><literal>STRING</literal></entry>
 885                   <entry><literal>SIGNAL</literal></entry>
 886                   <entry>
 887                     The interface to invoke a method call on, or
 888                     that a signal is emitted from. Optional for
 889                     method calls, required for signals.
 890                   </entry>
 891                 </row>
 892                 <row>
 893                   <entry><literal>MEMBER</literal></entry>
 894                   <entry>3</entry>
 895                   <entry><literal>STRING</literal></entry>
 896                   <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
 897                   <entry>The member, either the method name or signal name.</entry>
 898                 </row>
 899                 <row>
 900                   <entry><literal>ERROR_NAME</literal></entry>
 901                   <entry>4</entry>
 902                   <entry><literal>STRING</literal></entry>
 903                   <entry><literal>ERROR</literal></entry>
 904                   <entry>The name of the error that occurred, for errors</entry>
 905                 </row>
 906                 <row>
 907                   <entry><literal>REPLY_SERIAL</literal></entry>
 908                   <entry>5</entry>
 909                   <entry><literal>UINT32</literal></entry>
 910                   <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
 911                   <entry>The serial number of the message this message is a reply
 912                     to. (The serial number is the second <literal>UINT32</literal> in the header.)</entry>
 913                 </row>
 914                 <row>
 915                   <entry><literal>DESTINATION</literal></entry>
 916                   <entry>6</entry>
 917                   <entry><literal>STRING</literal></entry>
 918                   <entry>optional</entry>
 919                   <entry>The name of the connection this message should be routed to.
 920                     Only used in combination with the message bus, see
 921                     <xref linkend="message-bus"/>.</entry>
 922                 </row>
 923                 <row>
 924                   <entry><literal>SENDER</literal></entry>
 925                   <entry>7</entry>
 926                   <entry><literal>STRING</literal></entry>
 927                   <entry>optional</entry>
 928                   <entry>Unique name of the sending connection.
 929                     The message bus fills in this field so it is reliable; the field is
 930                     only meaningful in combination with the message bus.</entry>
 931                 </row>
 932                 <row>
 933                   <entry><literal>SIGNATURE</literal></entry>
 934                   <entry>8</entry>
 935                   <entry><literal>SIGNATURE</literal></entry>
 936                   <entry>optional</entry>
 937                   <entry>The signature of the message body.
 938                   If omitted, it is assumed to be the
 939                   empty signature "" (i.e. the body must be 0-length).</entry>
 940                 </row>
 941               </tbody>
 942             </tgroup>
 943           </informaltable>
 944         </para>
 945       </sect3>
 946     </sect2>
 947
 948     <sect2 id="message-protocol-names">
 949       <title>Valid Names</title>
 950       <para>
 951         The various names in D-BUS messages have some restrictions.
 952       </para>
 953       <para>
 954         There is a <firstterm>maximum name length</firstterm>
 955         of 255 which applies to bus names, interfaces, and members.
 956       </para>
 957       <sect3 id="message-protocol-names-interface">
 958         <title>Interface names</title>
 959         <para>
 960           Interfaces have names with type <literal>STRING</literal>, meaning that
 961           they must be valid UTF-8. However, there are also some
 962           additional restrictions that apply to interface names
 963           specifically:
 964           <itemizedlist>
 965             <listitem><para>They are composed of 1 or more elements separated by
 966                 a period ('.') character. All elements must contain at least
 967                 one character.
 968                 </para>
 969             </listitem>
 970             <listitem><para>Each element must only contain the ASCII characters
 971                 "[A-Z][a-z][0-9]_" and must not begin with a digit.
 972                 </para>
 973             </listitem>
 974
 975             <listitem><para>They must contain at least one '.' (period)
 976               character (and thus at least two elements).
 977               </para></listitem>
 978
 979             <listitem><para>They must not begin with a '.' (period) character.</para></listitem>
 980             <listitem><para>They must not exceed the maximum name length.</para></listitem>
 981           </itemizedlist>
 982         </para>
 983       </sect3>
 984       <sect3 id="message-protocol-names-bus">
 985         <title>Bus names</title>
 986         <para>
 987           Bus names have the same restrictions as interface names, with a
 988           special exception for unique connection names. A unique name's first
 989           element must start with a colon (':') character. After the colon, any
 990           characters in "[A-Z][a-z][0-9]_" may appear. Elements after
 991           the first must follow the usual rules, except that they may start with
 992           a digit. Bus names not starting with a colon have none of these
 993           exceptions and follow the same rules as interface names.
 994         </para>
 995       </sect3>
 996       <sect3 id="message-protocol-names-member">
 997         <title>Member names</title>
 998         <para>
 999           Member (i.e. method or signal) names:
1000           <itemizedlist>
1001             <listitem><para>Must only contain the ASCII characters
1002                 "[A-Z][a-z][0-9]_" and may not begin with a
1003                 digit.</para></listitem>
1004             <listitem><para>Must not contain the '.' (period) character.</para></listitem>
1005             <listitem><para>Must not exceed the maximum name length.</para></listitem>
1006             <listitem><para>Must be at least 1 byte in length.</para></listitem>
1007           </itemizedlist>
1008         </para>
1009       </sect3>
1010       <sect3 id="message-protocol-names-error">
1011         <title>Error names</title>
1012         <para>
1013           Error names have the same restrictions as interface names.
1014         </para>
1015       </sect3>
1016     </sect2>
1017
1018     <sect2 id="message-protocol-types">
1019       <title>Message Types</title>
1020       <para>
1021         Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
1022         <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
1023         This section describes these conventions.
1024       </para>
1025       <sect3 id="message-protocol-types-method">
1026         <title>Method Calls</title>
1027         <para>
1028           Some messages invoke an operation on a remote object.  These are
1029           called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
1030           messages map naturally to methods on objects in a typical program.
1031         </para>
1032         <para>
1033           A method call message is expected to have a <literal>MEMBER</literal> header field
1034           indicating the name of the method. Optionally, the message has an
1035           <literal>INTERFACE</literal> field giving the interface the method is a part of. In the
1036           absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
1037           a method with the same name, it is undefined which of the two methods
1038           will be invoked. Implementations may also choose to return an error in
1039           this ambiguous case. However, if a method name is unique
1040           implementations must not require an interface field.
1041         </para>
1042         <para>
1043           Method call messages also include a <literal>PATH</literal> field
1044           indicating the object to invoke the method on. If the call is passing
1045           through a message bus, the message will also have a
1046           <literal>DESTINATION</literal> field giving the name of the connection
1047           to receive the message.
1048         </para>
1049         <para>
1050           When an application handles a method call message, it is expected to
1051           return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
1052           indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
1053           reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
1054         </para>
1055         <para>
1056           If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
1057           are the return value(s) or "out parameters" of the method call.
1058           If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
1059           and the call fails; no return value will be provided. It makes
1060           no sense to send multiple replies to the same method call.
1061         </para>
1062         <para>
1063           Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
1064           reply is expected, so the caller will know the method
1065           was successfully processed.
1066         </para>
1067         <para>
1068           The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
1069           header field.
1070         </para>
1071         <para>
1072           If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
1073           then as an optimization the application receiving the method
1074           call may choose to omit the reply message (regardless of
1075           whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
1076           However, it is also acceptable to ignore the <literal>NO_REPLY_EXPECTED</literal>
1077           flag and reply anyway.
1078         </para>
1079         <para>
1080           Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
1081           destination name does not exist then a program to own the destination
1082           name will be started before the message is delivered.  The message
1083           will be held until the new program is successfully started or has
1084           failed to start; in case of failure, an error will be returned. This
1085           flag is only relevant in the context of a message bus, it is ignored
1086           during one-to-one communication with no intermediate bus.
1087         </para>
1088         <sect4 id="message-protocol-types-method-apis">
1089           <title>Mapping method calls to native APIs</title>
1090           <para>
1091             APIs for D-BUS may map method calls to a method call in a specific
1092             programming language, such as C++, or may map a method call written
1093             in an IDL to a D-BUS message.
1094           </para>
1095           <para>
1096             In APIs of this nature, arguments to a method are often termed "in"
1097             (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
1098             returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
1099             "inout" arguments, which are both sent and received, i.e. the caller
1100             passes in a value which is modified. Mapped to D-BUS, an "inout"
1101             argument is equivalent to an "in" argument, followed by an "out"
1102             argument. You can't pass things "by reference" over the wire, so
1103             "inout" is purely an illusion of the in-process API.
1104           </para>
1105           <para>
1106             Given a method with zero or one return values, followed by zero or more
1107             arguments, where each argument may be "in", "out", or "inout", the
1108             caller constructs a message by appending each "in" or "inout" argument,
1109             in order. "out" arguments are not represented in the caller's message.
1110           </para>
1111           <para>
1112             The recipient constructs a reply by appending first the return value
1113             if any, then each "out" or "inout" argument, in order.
1114             "in" arguments are not represented in the reply message.
1115           </para>
1116           <para>
1117             Error replies are normally mapped to exceptions in languages that have
1118             exceptions.
1119           </para>
1120           <para>
1121             This specification doesn't require anything of native API bindings;
1122             the preceding is only a suggested convention for consistency
1123             among bindings.
1124           </para>
1125         </sect4>
1126
1127       </sect3>
1128
1129       <sect3 id="message-protocol-types-signal">
1130         <title>Signal Emission</title>
1131         <para>
1132           Unlike method calls, signal emissions have no replies.
1133           A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1134           It must have three header fields: <literal>PATH</literal> giving the object
1135           the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1136           the fully-qualified name of the signal.
1137         </para>
1138       </sect3>
1139
1140       <sect3 id="message-protocol-types-errors">
1141         <title>Errors</title>
1142         <para>
1143           Messages of type <literal>ERROR</literal> are most commonly replies
1144           to a <literal>METHOD_CALL</literal>, but may be returned in reply
1145           to any kind of message. The message bus for example
1146           will return an <literal>ERROR</literal> in reply to a signal emission if
1147           the bus does not have enough memory to send the signal.
1148         </para>
1149         <para>
1150           An <literal>ERROR</literal> may have any arguments, but if the first
1151           argument is a <literal>STRING</literal>, it must be an error message.
1152           The error message may be logged or shown to the user
1153           in some way.
1154         </para>
1155       </sect3>
1156
1157       <sect3 id="message-protocol-types-notation">
1158         <title>Notation in this document</title>
1159         <para>
1160           This document uses a simple pseudo-IDL to describe particular method
1161           calls and signals. Here is an example of a method call:
1162           <programlisting>
1163             org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1164                                                      out UINT32 resultcode)
1165           </programlisting>
1166           This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1167           <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1168           is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1169           characters so it's known that the last part of the name in
1170           the "IDL" is the member name.
1171         </para>
1172         <para>
1173           In C++ that might end up looking like this:
1174           <programlisting>
1175             unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
1176                                                                      unsigned int flags);
1177           </programlisting>
1178           or equally valid, the return value could be done as an argument:
1179           <programlisting>
1180             void org::freedesktop::DBus::StartServiceByName (const char   *name,
1181                                                              unsigned int  flags,
1182                                                              unsigned int *resultcode);
1183           </programlisting>
1184           It's really up to the API designer how they want to make
1185           this look. You could design an API where the namespace wasn't used
1186           in C++, using STL or Qt, using varargs, or whatever you wanted.
1187         </para>
1188         <para>
1189           Signals are written as follows:
1190           <programlisting>
1191             org.freedesktop.DBus.NameLost (STRING name)
1192           </programlisting>
1193           Signals don't specify "in" vs. "out" because only
1194           a single direction is possible.
1195         </para>
1196         <para>
1197           It isn't especially encouraged to use this lame pseudo-IDL in actual
1198           API implementations; you might use the native notation for the
1199           language you're using, or you might use COM or CORBA IDL, for example.
1200         </para>
1201       </sect3>
1202     </sect2>
1203
1204   </sect1>
1205
1206   <sect1 id="auth-protocol">
1207     <title>Authentication Protocol</title>
1208     <para>
1209       Before the flow of messages begins, two applications must
1210       authenticate. A simple plain-text protocol is used for
1211       authentication; this protocol is a SASL profile, and maps fairly
1212       directly from the SASL specification. The message encoding is
1213       NOT used here, only plain text messages.
1214     </para>
1215     <para>
1216       In examples, "C:" and "S:" indicate lines sent by the client and
1217       server respectively.
1218     </para>
1219     <sect2 id="auth-protocol-overview">
1220       <title>Protocol Overview</title>
1221       <para>
1222         The protocol is a line-based protocol, where each line ends with
1223         \r\n. Each line begins with an all-caps ASCII command name containing
1224         only the character range [A-Z], a space, then any arguments for the
1225         command, then the \r\n ending the line. The protocol is
1226         case-sensitive. All bytes must be in the ASCII character set.
1227
1228         Commands from the client to the server are as follows:
1229
1230         <itemizedlist>
1231           <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1232           <listitem><para>CANCEL</para></listitem>
1233           <listitem><para>BEGIN</para></listitem>
1234           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1235           <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1236         </itemizedlist>
1237
1238         From server to client are as follows:
1239
1240         <itemizedlist>
1241           <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
1242           <listitem><para>OK</para></listitem>
1243           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1244           <listitem><para>ERROR</para></listitem>
1245         </itemizedlist>
1246       </para>
1247     </sect2>
1248     <sect2 id="auth-nul-byte">
1249       <title>Special credentials-passing nul byte</title>
1250       <para>
1251         Immediately after connecting to the server, the client must send a
1252         single nul byte. This byte may be accompanied by credentials
1253         information on some operating systems that use sendmsg() with
1254         SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1255         sockets. However, the nul byte MUST be sent even on other kinds of
1256         socket, and even on operating systems that do not require a byte to be
1257         sent in order to transmit credentials. The text protocol described in
1258         this document begins after the single nul byte. If the first byte
1259         received from the client is not a nul byte, the server may disconnect
1260         that client.
1261       </para>
1262       <para>
1263         A nul byte in any context other than the initial byte is an error;
1264         the protocol is ASCII-only.
1265       </para>
1266       <para>
1267         The credentials sent along with the nul byte may be used with the
1268         SASL mechanism EXTERNAL.
1269       </para>
1270     </sect2>
1271     <sect2 id="auth-command-auth">
1272       <title>AUTH command</title>
1273       <para>
1274         If an AUTH command has no arguments, it is a request to list
1275         available mechanisms. The server SHOULD respond with a REJECTED
1276         command listing the mechanisms it understands.
1277       </para>
1278       <para>
1279         If an AUTH command specifies a mechanism, and the server supports
1280         said mechanism, the server SHOULD begin exchanging SASL
1281         challenge-response data with the client using DATA commands.
1282       </para>
1283       <para>
1284         If the server does not support the mechanism given in the AUTH
1285         command, it SHOULD send a REJECTED command listing the mechanisms
1286         it does support.
1287       </para>
1288       <para>
1289         If the [initial-response] argument is provided, it is intended for
1290         use with mechanisms that have no initial challenge (or an empty
1291         initial challenge), as if it were the argument to an initial DATA
1292         command. If the selected mechanism has an initial challenge, the
1293         server should reject authentication by sending REJECTED.
1294       </para>
1295       <para>
1296         If authentication succeeds after exchanging DATA commands,
1297         an OK command should be sent to the client.
1298       </para>
1299       <para>
1300         The first octet received by the client after the \r\n of the OK
1301         command MUST be the first octet of the authenticated/encrypted
1302         stream of D-BUS messages.
1303       </para>
1304       <para>
1305         The first octet received by the server after the \r\n of the BEGIN
1306         command from the client MUST be the first octet of the
1307         authenticated/encrypted stream of D-BUS messages.
1308       </para>
1309     </sect2>
1310     <sect2 id="auth-command-cancel">
1311       <title>CANCEL Command</title>
1312       <para>
1313         At any time up to sending the BEGIN command, the client may send a
1314         CANCEL command. On receiving the CANCEL command, the server MUST
1315         send a REJECTED command and abort the current authentication
1316         exchange.
1317       </para>
1318     </sect2>
1319     <sect2 id="auth-command-data">
1320       <title>DATA Command</title>
1321       <para>
1322         The DATA command may come from either client or server, and simply
1323         contains a hex-encoded block of data to be interpreted
1324         according to the SASL mechanism in use.
1325       </para>
1326       <para>
1327         Some SASL mechanisms support sending an "empty string";
1328         FIXME we need some way to do this.
1329       </para>
1330     </sect2>
1331     <sect2 id="auth-command-begin">
1332       <title>BEGIN Command</title>
1333       <para>
1334         The BEGIN command acknowledges that the client has received an
1335         OK command from the server, and that the stream of messages
1336         is about to begin.
1337       </para>
1338       <para>
1339         The first octet received by the server after the \r\n of the BEGIN
1340         command from the client MUST be the first octet of the
1341         authenticated/encrypted stream of D-BUS messages.
1342       </para>
1343     </sect2>
1344     <sect2 id="auth-command-rejected">
1345       <title>REJECTED Command</title>
1346       <para>
1347         The REJECTED command indicates that the current authentication
1348         exchange has failed, and further exchange of DATA is inappropriate.
1349         The client would normally try another mechanism, or try providing
1350         different responses to challenges.
1351       </para><para>
1352         Optionally, the REJECTED command has a space-separated list of
1353         available auth mechanisms as arguments. If a server ever provides
1354         a list of supported mechanisms, it MUST provide the same list
1355         each time it sends a REJECTED message. Clients are free to
1356         ignore all lists received after the first.
1357       </para>
1358     </sect2>
1359     <sect2 id="auth-command-ok">
1360       <title>OK Command</title>
1361       <para>
1362         The OK command indicates that the client has been authenticated,
1363         and that further communication will be a stream of D-BUS messages
1364         (optionally encrypted, as negotiated) rather than this protocol.
1365       </para>
1366       <para>
1367         The first octet received by the client after the \r\n of the OK
1368         command MUST be the first octet of the authenticated/encrypted
1369         stream of D-BUS messages.
1370       </para>
1371       <para>
1372         The client MUST respond to the OK command by sending a BEGIN
1373         command, followed by its stream of messages, or by disconnecting.
1374         The server MUST NOT accept additional commands using this protocol
1375         after the OK command has been sent.
1376       </para>
1377     </sect2>
1378     <sect2 id="auth-command-error">
1379       <title>ERROR Command</title>
1380       <para>
1381         The ERROR command indicates that either server or client did not
1382         know a command, does not accept the given command in the current
1383         context, or did not understand the arguments to the command. This
1384         allows the protocol to be extended; a client or server can send a
1385         command present or permitted only in new protocol versions, and if
1386         an ERROR is received instead of an appropriate response, fall back
1387         to using some other technique.
1388       </para>
1389       <para>
1390         If an ERROR is sent, the server or client that sent the
1391         error MUST continue as if the command causing the ERROR had never been
1392         received. However, the the server or client receiving the error
1393         should try something other than whatever caused the error;
1394         if only canceling/rejecting the authentication.
1395       </para>
1396     </sect2>
1397     <sect2 id="auth-examples">
1398       <title>Authentication examples</title>
1399
1400       <para>
1401         <figure>
1402           <title>Example of successful magic cookie authentication</title>
1403           <programlisting>
1404             (MAGIC_COOKIE is a made up mechanism)
1405
1406             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1407             S: OK
1408             C: BEGIN
1409           </programlisting>
1410         </figure>
1411         <figure>
1412           <title>Example of finding out mechanisms then picking one</title>
1413           <programlisting>
1414             C: AUTH
1415             S: REJECTED KERBEROS_V4 SKEY
1416             C: AUTH SKEY 7ab83f32ee
1417             S: DATA 8799cabb2ea93e
1418             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1419             S: OK
1420             C: BEGIN
1421           </programlisting>
1422         </figure>
1423         <figure>
1424           <title>Example of client sends unknown command then falls back to regular auth</title>
1425           <programlisting>
1426             C: FOOBAR
1427             S: ERROR
1428             C: AUTH MAGIC_COOKIE 3736343435313230333039
1429             S: OK
1430             C: BEGIN
1431           </programlisting>
1432         </figure>
1433         <figure>
1434           <title>Example of server doesn't support initial auth mechanism</title>
1435           <programlisting>
1436             C: AUTH MAGIC_COOKIE 3736343435313230333039
1437             S: REJECTED KERBEROS_V4 SKEY
1438             C: AUTH SKEY 7ab83f32ee
1439             S: DATA 8799cabb2ea93e
1440             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1441             S: OK
1442             C: BEGIN
1443           </programlisting>
1444         </figure>
1445         <figure>
1446           <title>Example of wrong password or the like followed by successful retry</title>
1447           <programlisting>
1448             C: AUTH MAGIC_COOKIE 3736343435313230333039
1449             S: REJECTED KERBEROS_V4 SKEY
1450             C: AUTH SKEY 7ab83f32ee
1451             S: DATA 8799cabb2ea93e
1452             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1453             S: REJECTED
1454             C: AUTH SKEY 7ab83f32ee
1455             S: DATA 8799cabb2ea93e
1456             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1457             S: OK
1458             C: BEGIN
1459           </programlisting>
1460         </figure>
1461         <figure>
1462           <title>Example of skey cancelled and restarted</title>
1463           <programlisting>
1464             C: AUTH MAGIC_COOKIE 3736343435313230333039
1465             S: REJECTED KERBEROS_V4 SKEY
1466             C: AUTH SKEY 7ab83f32ee
1467             S: DATA 8799cabb2ea93e
1468             C: CANCEL
1469             S: REJECTED
1470             C: AUTH SKEY 7ab83f32ee
1471             S: DATA 8799cabb2ea93e
1472             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1473             S: OK
1474             C: BEGIN
1475           </programlisting>
1476         </figure>
1477       </para>
1478     </sect2>
1479     <sect2 id="auth-states">
1480       <title>Authentication state diagrams</title>
1481
1482       <para>
1483         This section documents the auth protocol in terms of
1484         a state machine for the client and the server. This is
1485         probably the most robust way to implement the protocol.
1486       </para>
1487
1488       <sect3 id="auth-states-client">
1489         <title>Client states</title>
1490
1491         <para>
1492           To more precisely describe the interaction between the
1493           protocol state machine and the authentication mechanisms the
1494           following notation is used: MECH(CHALL) means that the
1495           server challenge CHALL was fed to the mechanism MECH, which
1496           returns one of
1497
1498           <itemizedlist>
1499             <listitem>
1500               <para>
1501                 CONTINUE(RESP) means continue the auth conversation
1502                 and send RESP as the response to the server;
1503               </para>
1504             </listitem>
1505
1506             <listitem>
1507               <para>
1508                 OK(RESP) means that after sending RESP to the server
1509                 the client side of the auth conversation is finished
1510                 and the server should return "OK";
1511               </para>
1512             </listitem>
1513
1514             <listitem>
1515               <para>
1516                 ERROR means that CHALL was invalid and could not be
1517                 processed.
1518               </para>
1519             </listitem>
1520           </itemizedlist>
1521
1522           Both RESP and CHALL may be empty.
1523         </para>
1524
1525         <para>
1526           The Client starts by getting an initial response from the
1527           default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1528           the mechanism did not provide an initial response.  If the
1529           mechanism returns CONTINUE, the client starts in state
1530           <emphasis>WaitingForData</emphasis>, if the mechanism
1531           returns OK the client starts in state
1532           <emphasis>WaitingForOK</emphasis>.
1533         </para>
1534
1535         <para>
1536           The client should keep track of available mechanisms and
1537           which it mechanisms it has already attempted. This list is
1538           used to decide which AUTH command to send. When the list is
1539           exhausted, the client should give up and close the
1540           connection.
1541         </para>
1542
1543         <formalpara>
1544           <title><emphasis>WaitingForData</emphasis></title>
1545           <para>
1546             <itemizedlist>
1547               <listitem>
1548                 <para>
1549                   Receive DATA CHALL
1550                   <simplelist>
1551                     <member>
1552                       MECH(CHALL) returns CONTINUE(RESP) &rarr; send
1553                       DATA RESP, goto
1554                       <emphasis>WaitingForData</emphasis>
1555                     </member>
1556
1557                     <member>
1558                       MECH(CHALL) returns OK(RESP) &rarr; send DATA
1559                       RESP, goto <emphasis>WaitingForOK</emphasis>
1560                     </member>
1561
1562                     <member>
1563                       MECH(CHALL) returns ERROR &rarr; send ERROR
1564                       [msg], goto <emphasis>WaitingForData</emphasis>
1565                     </member>
1566                   </simplelist>
1567                 </para>
1568               </listitem>
1569
1570               <listitem>
1571                 <para>
1572                   Receive REJECTED [mechs] &rarr;
1573                   send AUTH [next mech], goto
1574                   WaitingForData or <emphasis>WaitingForOK</emphasis>
1575                 </para>
1576               </listitem>
1577               <listitem>
1578                 <para>
1579                   Receive ERROR &rarr; send
1580                   CANCEL, goto
1581                   <emphasis>WaitingForReject</emphasis>
1582                 </para>
1583               </listitem>
1584               <listitem>
1585                 <para>
1586                   Receive OK &rarr; send
1587                   BEGIN, terminate auth
1588                   conversation, authenticated
1589                 </para>
1590               </listitem>
1591               <listitem>
1592                 <para>
1593                   Receive anything else &rarr; send
1594                   ERROR, goto
1595                   <emphasis>WaitingForData</emphasis>
1596                 </para>
1597               </listitem>
1598             </itemizedlist>
1599           </para>
1600         </formalpara>
1601
1602         <formalpara>
1603           <title><emphasis>WaitingForOK</emphasis></title>
1604           <para>
1605             <itemizedlist>
1606               <listitem>
1607                 <para>
1608                   Receive OK &rarr; send BEGIN, terminate auth
1609                   conversation, <emphasis>authenticated</emphasis>
1610                 </para>
1611               </listitem>
1612               <listitem>
1613                 <para>
1614                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1615                   goto <emphasis>WaitingForData</emphasis> or
1616                   <emphasis>WaitingForOK</emphasis>
1617                 </para>
1618               </listitem>
1619
1620               <listitem>
1621                 <para>
1622                   Receive DATA &rarr; send CANCEL, goto
1623                   <emphasis>WaitingForReject</emphasis>
1624                 </para>
1625               </listitem>
1626
1627               <listitem>
1628                 <para>
1629                   Receive ERROR &rarr; send CANCEL, goto
1630                   <emphasis>WaitingForReject</emphasis>
1631                 </para>
1632               </listitem>
1633
1634               <listitem>
1635                 <para>
1636                   Receive anything else &rarr; send ERROR, goto
1637                   <emphasis>WaitingForOK</emphasis>
1638                 </para>
1639               </listitem>
1640             </itemizedlist>
1641           </para>
1642         </formalpara>
1643
1644         <formalpara>
1645           <title><emphasis>WaitingForReject</emphasis></title>
1646           <para>
1647             <itemizedlist>
1648               <listitem>
1649                 <para>
1650                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1651                   goto <emphasis>WaitingForData</emphasis> or
1652                   <emphasis>WaitingForOK</emphasis>
1653                 </para>
1654               </listitem>
1655
1656               <listitem>
1657                 <para>
1658                   Receive anything else &rarr; terminate auth
1659                   conversation, disconnect
1660                 </para>
1661               </listitem>
1662             </itemizedlist>
1663           </para>
1664         </formalpara>
1665
1666       </sect3>
1667
1668       <sect3 id="auth-states-server">
1669         <title>Server states</title>
1670
1671         <para>
1672           For the server MECH(RESP) means that the client response
1673           RESP was fed to the the mechanism MECH, which returns one of
1674
1675           <itemizedlist>
1676             <listitem>
1677               <para>
1678                 CONTINUE(CHALL) means continue the auth conversation and
1679                 send CHALL as the challenge to the client;
1680               </para>
1681             </listitem>
1682
1683             <listitem>
1684               <para>
1685                 OK means that the client has been successfully
1686                 authenticated;
1687               </para>
1688             </listitem>
1689
1690             <listitem>
1691               <para>
1692                 REJECT means that the client failed to authenticate or
1693                 there was an error in RESP.
1694               </para>
1695             </listitem>
1696           </itemizedlist>
1697
1698           The server starts out in state
1699           <emphasis>WaitingForAuth</emphasis>.  If the client is
1700           rejected too many times the server must disconnect the
1701           client.
1702         </para>
1703
1704         <formalpara>
1705           <title><emphasis>WaitingForAuth</emphasis></title>
1706           <para>
1707             <itemizedlist>
1708
1709               <listitem>
1710                 <para>
1711                   Receive AUTH &rarr; send REJECTED [mechs], goto
1712                   <emphasis>WaitingForAuth</emphasis>
1713                 </para>
1714               </listitem>
1715
1716               <listitem>
1717                 <para>
1718                   Receive AUTH MECH RESP
1719
1720                   <simplelist>
1721                     <member>
1722                       MECH not valid mechanism &rarr; send REJECTED
1723                       [mechs], goto
1724                       <emphasis>WaitingForAuth</emphasis>
1725                     </member>
1726
1727                     <member>
1728                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1729                       DATA CHALL, goto
1730                       <emphasis>WaitingForData</emphasis>
1731                     </member>
1732
1733                     <member>
1734                       MECH(RESP) returns OK &rarr; send OK, goto
1735                       <emphasis>WaitingForBegin</emphasis>
1736                     </member>
1737
1738                     <member>
1739                       MECH(RESP) returns REJECT &rarr; send REJECTED
1740                       [mechs], goto
1741                       <emphasis>WaitingForAuth</emphasis>
1742                     </member>
1743                   </simplelist>
1744                 </para>
1745               </listitem>
1746
1747               <listitem>
1748                 <para>
1749                   Receive BEGIN &rarr; terminate
1750                   auth conversation, disconnect
1751                 </para>
1752               </listitem>
1753
1754               <listitem>
1755                 <para>
1756                   Receive ERROR &rarr; send REJECTED [mechs], goto
1757                   <emphasis>WaitingForAuth</emphasis>
1758                 </para>
1759               </listitem>
1760
1761               <listitem>
1762                 <para>
1763                   Receive anything else &rarr; send
1764                   ERROR, goto
1765                   <emphasis>WaitingForAuth</emphasis>
1766                 </para>
1767               </listitem>
1768             </itemizedlist>
1769           </para>
1770         </formalpara>
1771
1772
1773         <formalpara>
1774           <title><emphasis>WaitingForData</emphasis></title>
1775           <para>
1776             <itemizedlist>
1777               <listitem>
1778                 <para>
1779                   Receive DATA RESP
1780                   <simplelist>
1781                     <member>
1782                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1783                       DATA CHALL, goto
1784                       <emphasis>WaitingForData</emphasis>
1785                     </member>
1786
1787                     <member>
1788                       MECH(RESP) returns OK &rarr; send OK, goto
1789                       <emphasis>WaitingForBegin</emphasis>
1790                     </member>
1791
1792                     <member>
1793                       MECH(RESP) returns REJECT &rarr; send REJECTED
1794                       [mechs], goto
1795                       <emphasis>WaitingForAuth</emphasis>
1796                     </member>
1797                   </simplelist>
1798                 </para>
1799               </listitem>
1800
1801               <listitem>
1802                 <para>
1803                   Receive BEGIN &rarr; terminate auth conversation,
1804                   disconnect
1805                 </para>
1806               </listitem>
1807
1808               <listitem>
1809                 <para>
1810                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1811                   <emphasis>WaitingForAuth</emphasis>
1812                 </para>
1813               </listitem>
1814
1815               <listitem>
1816                 <para>
1817                   Receive ERROR &rarr; send REJECTED [mechs], goto
1818                   <emphasis>WaitingForAuth</emphasis>
1819                 </para>
1820               </listitem>
1821
1822               <listitem>
1823                 <para>
1824                   Receive anything else &rarr; send ERROR, goto
1825                   <emphasis>WaitingForData</emphasis>
1826                 </para>
1827               </listitem>
1828             </itemizedlist>
1829           </para>
1830         </formalpara>
1831
1832         <formalpara>
1833           <title><emphasis>WaitingForBegin</emphasis></title>
1834           <para>
1835             <itemizedlist>
1836               <listitem>
1837                 <para>
1838                   Receive BEGIN &rarr; terminate auth conversation,
1839                   client authenticated
1840                 </para>
1841               </listitem>
1842
1843               <listitem>
1844                 <para>
1845                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1846                   <emphasis>WaitingForAuth</emphasis>
1847                 </para>
1848               </listitem>
1849
1850               <listitem>
1851                 <para>
1852                   Receive ERROR &rarr; send REJECTED [mechs], goto
1853                   <emphasis>WaitingForAuth</emphasis>
1854                 </para>
1855               </listitem>
1856
1857               <listitem>
1858                 <para>
1859                   Receive anything else &rarr; send ERROR, goto
1860                   <emphasis>WaitingForBegin</emphasis>
1861                 </para>
1862               </listitem>
1863             </itemizedlist>
1864           </para>
1865         </formalpara>
1866
1867       </sect3>
1868
1869     </sect2>
1870     <sect2 id="auth-mechanisms">
1871       <title>Authentication mechanisms</title>
1872       <para>
1873         This section describes some new authentication mechanisms.
1874         D-BUS also allows any standard SASL mechanism of course.
1875       </para>
1876       <sect3 id="auth-mechanisms-sha">
1877         <title>DBUS_COOKIE_SHA1</title>
1878         <para>
1879           The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
1880           has the ability to read a private file owned by the user being
1881           authenticated. If the client can prove that it has access to a secret
1882           cookie stored in this file, then the client is authenticated.
1883           Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
1884           directory.
1885         </para>
1886         <para>
1887           Authentication proceeds as follows:
1888           <itemizedlist>
1889             <listitem>
1890               <para>
1891                 The client sends the username it would like to authenticate
1892                 as.
1893               </para>
1894             </listitem>
1895             <listitem>
1896               <para>
1897                 The server sends the name of its "cookie context" (see below); a
1898                 space character; the integer ID of the secret cookie the client
1899                 must demonstrate knowledge of; a space character; then a
1900                 hex-encoded randomly-generated challenge string.
1901               </para>
1902             </listitem>
1903             <listitem>
1904               <para>
1905                 The client locates the cookie, and generates its own hex-encoded
1906                 randomly-generated challenge string.  The client then
1907                 concatentates the server's hex-encoded challenge, a ":"
1908                 character, its own hex-encoded challenge, another ":" character,
1909                 and the hex-encoded cookie.  It computes the SHA-1 hash of this
1910                 composite string.  It sends back to the server the client's
1911                 hex-encoded challenge string, a space character, and the SHA-1
1912                 hash.
1913               </para>
1914             </listitem>
1915             <listitem>
1916               <para>
1917                 The server generates the same concatenated string used by the
1918                 client and computes its SHA-1 hash. It compares the hash with
1919                 the hash received from the client; if the two hashes match, the
1920                 client is authenticated.
1921               </para>
1922             </listitem>
1923           </itemizedlist>
1924         </para>
1925         <para>
1926           Each server has a "cookie context," which is a name that identifies a
1927           set of cookies that apply to that server. A sample context might be
1928           "org_freedesktop_session_bus". Context names must be valid ASCII,
1929           nonzero length, and may not contain the characters slash ("/"),
1930           backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
1931           tab ("\t"), or period ("."). There is a default context,
1932           "org_freedesktop_global" that's used by servers that do not specify
1933           otherwise.
1934         </para>
1935         <para>
1936           Cookies are stored in a user's home directory, in the directory
1937           <filename>~/.dbus-keyrings/</filename>. This directory must
1938           not be readable or writable by other users. If it is,
1939           clients and servers must ignore it. The directory
1940           contains cookie files named after the cookie context.
1941         </para>
1942         <para>
1943           A cookie file contains one cookie per line. Each line
1944           has three space-separated fields:
1945           <itemizedlist>
1946             <listitem>
1947               <para>
1948                 The cookie ID number, which must be a non-negative integer and
1949                 may not be used twice in the same file.
1950               </para>
1951             </listitem>
1952             <listitem>
1953               <para>
1954                 The cookie's creation time, in UNIX seconds-since-the-epoch
1955                 format.
1956               </para>
1957             </listitem>
1958             <listitem>
1959               <para>
1960                 The cookie itself, a hex-encoded random block of bytes.
1961               </para>
1962             </listitem>
1963           </itemizedlist>
1964         </para>
1965         <para>
1966           Only server processes modify the cookie file.
1967           They must do so with this procedure:
1968           <itemizedlist>
1969             <listitem>
1970               <para>
1971                 Create a lockfile name by appending ".lock" to the name of the
1972                 cookie file.  The server should attempt to create this file
1973                 using <literal>O_CREAT | O_EXCL</literal>.  If file creation
1974                 fails, the lock fails. Servers should retry for a reasonable
1975                 period of time, then they may choose to delete an existing lock
1976                 to keep users from having to manually delete a stale
1977                 lock. <footnote><para>Lockfiles are used instead of real file
1978                 locking <literal>fcntl()</literal> because real locking
1979                 implementations are still flaky on network
1980                 filesystems.</para></footnote>
1981               </para>
1982             </listitem>
1983             <listitem>
1984               <para>
1985                 Once the lockfile has been created, the server loads the cookie
1986                 file. It should then delete any cookies that are old (the
1987                 timeout can be fairly short), or more than a reasonable
1988                 time in the future (so that cookies never accidentally
1989                 become permanent, if the clock was set far into the future
1990                 at some point). If no recent keys remain, the
1991                 server may generate a new key.
1992               </para>
1993             </listitem>
1994             <listitem>
1995               <para>
1996                 The pruned and possibly added-to cookie file
1997                 must be resaved atomically (using a temporary
1998                 file which is rename()'d).
1999               </para>
2000             </listitem>
2001             <listitem>
2002               <para>
2003                 The lock must be dropped by deleting the lockfile.
2004               </para>
2005             </listitem>
2006           </itemizedlist>
2007         </para>
2008         <para>
2009           Clients need not lock the file in order to load it,
2010           because servers are required to save the file atomically.
2011         </para>
2012       </sect3>
2013     </sect2>
2014   </sect1>
2015   <sect1 id="addresses">
2016     <title>Server Addresses</title>
2017     <para>
2018       Server addresses consist of a transport name followed by a colon, and
2019       then an optional, comma-separated list of keys and values in the form key=value.
2020       [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
2021     </para>
2022     <para>
2023       For example:
2024       <programlisting>unix:path=/tmp/dbus-test</programlisting>
2025       Which is the address to a unix socket with the path /tmp/dbus-test.
2026     </para>
2027     <para>
2028       [FIXME clarify if attempting to connect to each is a requirement
2029       or just a suggestion]
2030       When connecting to a server, multiple server addresses can be
2031       separated by a semi-colon. The library will then try to connect
2032       to the first address and if that fails, it'll try to connect to
2033       the next one specified, and so forth. For example
2034       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2035     </para>
2036     <para>
2037       [FIXME we need to specify in detail each transport and its possible arguments]
2038       Current transports include: unix domain sockets (including
2039       abstract namespace on linux), TCP/IP, and a debug/testing transport using
2040       in-process pipes. Future possible transports include one that
2041       tunnels over X11 protocol.
2042     </para>
2043   </sect1>
2044
2045   <sect1 id="standard-messages">
2046     <title>Standard One-to-One Messages</title>
2047     <para>
2048       See <xref linkend="message-protocol-types-notation"/> for details on
2049        the notation used in this section.
2050     </para>
2051     <sect2 id="standard-messages-ping">
2052       <title><literal>org.freedesktop.Peer.Ping</literal></title>
2053       <para>
2054         <programlisting>
2055           org.freedesktop.Peer.Ping ()
2056         </programlisting>
2057       </para>
2058       <para>
2059         On receipt of the <literal>METHOD_CALL</literal>
2060         message <literal>org.freedesktop.Peer.Ping</literal>, an application
2061         should do nothing other than reply with a <literal>METHOD_RETURN</literal> as usual.
2062       </para>
2063     </sect2>
2064
2065   </sect1>
2066
2067   <sect1 id="message-bus">
2068     <title>Message Bus Specification</title>
2069     <sect2 id="message-bus-overview">
2070       <title>Message Bus Overview</title>
2071       <para>
2072         The message bus accepts connections from one or more applications.
2073         Once connected, applications can exchange messages with other
2074         applications that are also connected to the bus.
2075       </para>
2076       <para>
2077         In order to route messages among connections, the message bus keeps a
2078         mapping from names to connections. Each connection has one
2079         unique-for-the-lifetime-of-the-bus name automatically assigned.
2080         Applications may request additional names for a connection. Additional
2081         names are usually "well-known names" such as
2082         "org.freedesktop.TextEditor". When a name is bound to a connection,
2083         that connection is said to <firstterm>own</firstterm> the name.
2084       </para>
2085       <para>
2086         The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2087         This name routes messages to the bus, allowing applications to make
2088         administrative requests. For example, applications can ask the bus
2089         to assign a name to a connection.
2090       </para>
2091       <para>
2092         Each name may have <firstterm>queued owners</firstterm>.  When an
2093         application requests a name for a connection and the name is already in
2094         use, the bus will optionally add the connection to a queue waiting for
2095         the name. If the current owner of the name disconnects or releases
2096         the name, the next connection in the queue will become the new owner.
2097       </para>
2098
2099       <para>
2100         This feature causes the right thing to happen if you start two text
2101         editors for example; the first one may request "org.freedesktop.TextEditor",
2102         and the second will be queued as a possible owner of that name. When
2103         the first exits, the second will take over.
2104       </para>
2105
2106       <para>
2107         Messages may have a <literal>DESTINATION</literal> field (see <xref
2108         linkend="message-protocol-header-fields"/>).  If the
2109         <literal>DESTINATION</literal> field is present, it specifies a message
2110         recipient by name. Method calls and replies normally specify this field.
2111       </para>
2112
2113       <para>
2114         Signals normally do not specify a destination; they are sent to all
2115         applications with <firstterm>message matching rules</firstterm> that
2116         match the message.
2117       </para>
2118
2119       <para>
2120         When the message bus receives a method call, if the
2121         <literal>DESTINATION</literal> field is absent, the call is taken to be
2122         a standard one-to-one message and interpreted by the message bus
2123         itself. For example, sending an
2124         <literal>org.freedesktop.Peer.Ping</literal> message with no
2125         <literal>DESTINATION</literal> will cause the message bus itself to
2126         reply to the ping immediately; the message bus will not make this
2127         message visible to other applications.
2128       </para>
2129
2130       <para>
2131         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
2132         the ping message were sent with a <literal>DESTINATION</literal> name of
2133         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2134         forwarded, and the Yoyodyne Corporation screensaver application would be
2135         expected to reply to the ping.
2136       </para>
2137     </sect2>
2138
2139     <sect2 id="message-bus-names">
2140       <title>Message Bus Names</title>
2141       <para>
2142         Each connection has at least one name, assigned at connection time and
2143         returned in response to the
2144         <literal>org.freedesktop.DBus.Hello</literal> method call.  This
2145         automatically-assigned name is called the connection's <firstterm>unique
2146         name</firstterm>.  Unique names are never reused for two different
2147         connections to the same bus.
2148       </para>
2149       <para>
2150         Ownership of a unique name is a prerequisite for interaction with
2151         the message bus. It logically follows that the unique name is always
2152         the first name that an application comes to own, and the last
2153         one that it loses ownership of.
2154       </para>
2155       <para>
2156         Unique connection names must begin with the character ':' (ASCII colon
2157         character); bus names that are not unique names must not begin
2158         with this character. (The bus must reject any attempt by an application
2159         to manually request a name beginning with ':'.) This restriction
2160         categorically prevents "spoofing"; messages sent to a unique name
2161         will always go to the expected connection.
2162       </para>
2163       <para>
2164         When a connection is closed, all the names that it owns are deleted (or
2165         transferred to the next connection in the queue if any).
2166       </para>
2167       <para>
2168         A connection can request additional names to be associated with it using
2169         the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2170         linkend="message-protocol-names-bus"/> describes the format of a valid
2171         name.
2172       </para>
2173
2174       <sect3 id="bus-messages-request-name">
2175         <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2176         <para>
2177           As a method:
2178           <programlisting>
2179             UINT32 RequestName (in STRING name, in UINT32 flags)
2180           </programlisting>
2181           Message arguments:
2182           <informaltable>
2183             <tgroup cols="3">
2184               <thead>
2185                 <row>
2186                   <entry>Argument</entry>
2187                   <entry>Type</entry>
2188                   <entry>Description</entry>
2189                 </row>
2190               </thead>
2191               <tbody>
2192                 <row>
2193                   <entry>0</entry>
2194                   <entry>STRING</entry>
2195                   <entry>Name to request</entry>
2196                 </row>
2197                 <row>
2198                   <entry>1</entry>
2199                   <entry>UINT32</entry>
2200                   <entry>Flags</entry>
2201                 </row>
2202               </tbody>
2203             </tgroup>
2204           </informaltable>
2205           Reply arguments:
2206           <informaltable>
2207             <tgroup cols="3">
2208               <thead>
2209                 <row>
2210                   <entry>Argument</entry>
2211                   <entry>Type</entry>
2212                   <entry>Description</entry>
2213                 </row>
2214               </thead>
2215               <tbody>
2216                 <row>
2217                   <entry>0</entry>
2218                   <entry>UINT32</entry>
2219                   <entry>Return value</entry>
2220                 </row>
2221               </tbody>
2222             </tgroup>
2223           </informaltable>
2224         </para>
2225         <para>
2226           This method call should be sent to
2227           <literal>org.freedesktop.DBus</literal> and asks the message bus to
2228           assign the given name to the method caller.  The flags argument
2229           contains any of the following values logically ORed together:
2230
2231           <informaltable>
2232             <tgroup cols="3">
2233               <thead>
2234                 <row>
2235                   <entry>Conventional Name</entry>
2236                   <entry>Value</entry>
2237                   <entry>Description</entry>
2238                 </row>
2239               </thead>
2240               <tbody>
2241                 <row>
2242                   <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2243                   <entry>0x1</entry>
2244                   <entry>
2245                     If the application succeeds in becoming the owner of the specified name,
2246                     then ownership of the name can't be transferred until the application
2247                     disconnects. If this flag is not set, then any application trying to become
2248                     the owner of the name will succeed and the previous owner will be
2249                     sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
2250                   </entry>
2251                 </row>
2252                 <row>
2253                   <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2254                   <entry>0x2</entry>
2255                   <entry>
2256                     Try to replace the current owner if there is one. If this
2257                     flag is not set the application will only become the owner of
2258                     the name if there is no current owner.
2259                   </entry>
2260                 </row>
2261               </tbody>
2262             </tgroup>
2263           </informaltable>
2264
2265           The return code can be one of the following values:
2266
2267           <informaltable>
2268             <tgroup cols="3">
2269               <thead>
2270                 <row>
2271                   <entry>Conventional Name</entry>
2272                   <entry>Value</entry>
2273                   <entry>Description</entry>
2274                 </row>
2275               </thead>
2276               <tbody>
2277                 <row>
2278                   <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2279                   <entry>1</entry> <entry>The caller is now the primary owner of
2280                   the name, replacing any previous owner. Either the name had no
2281                   owner before, or the caller specified
2282                   DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2283                   specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2284                 </row>
2285                 <row>
2286                   <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2287                   <entry>2</entry>
2288                   <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2289                 </row>
2290                 <row>
2291                   <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2292                   <entry>3</entry>
2293                   <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2294                 </row>
2295                 <row>
2296                   <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2297                   <entry>4</entry>
2298                   <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2299                 </row>
2300               </tbody>
2301             </tgroup>
2302           </informaltable>
2303         </para>
2304       </sect3>
2305     </sect2>
2306
2307     <sect2 id="message-bus-routing">
2308       <title>Message Bus Message Routing</title>
2309       <para>
2310         FIXME
2311       </para>
2312     </sect2>
2313     <sect2 id="message-bus-starting-services">
2314       <title>Message Bus Starting Services</title>
2315       <para>
2316         The message bus can start applications on behalf of other applications.
2317         In CORBA terms, this would be called <firstterm>activation</firstterm>.
2318         An application that can be started in this way is called a
2319         <firstterm>service</firstterm>.
2320       </para>
2321       <para>
2322         With D-BUS, starting a service is normally done by name. That is,
2323         applications ask the message bus to start some program that will own a
2324         well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2325         This implies a contract documented along with the name
2326         <literal>org.freedesktop.TextEditor</literal> for which objects
2327         the owner of that name will provide, and what interfaces those
2328         objects will have.
2329       </para>
2330       <para>
2331         To find an executable corresponding to a particular name, the bus daemon
2332         looks for <firstterm>service description files</firstterm>.  Service
2333         description files define a mapping from names to executables. Different
2334         kinds of message bus will look for these files in different places, see
2335         <xref linkend="message-bus-types"/>.
2336       </para>
2337       <para>
2338         [FIXME the file format should be much better specified than "similar to
2339         .desktop entries" esp. since desktop entries are already
2340         badly-specified. ;-)] Service description files have the ".service" file
2341         extension. The message bus will only load service description files
2342         ending with .service; all other files will be ignored.  The file format
2343         is similar to that of <ulink
2344         url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2345         entries</ulink>. All service description files must be in UTF-8
2346         encoding. To ensure that there will be no name collisions, service files
2347         must be namespaced using the same mechanism as messages and service
2348         names.
2349
2350         <figure>
2351           <title>Example service description file</title>
2352           <programlisting>
2353             # Sample service description file
2354             [D-BUS Service]
2355             Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2356             Exec=/usr/libexec/gconfd-2
2357           </programlisting>
2358         </figure>
2359       </para>
2360       <para>
2361         When an application asks to start a service by name, the bus daemon tries to
2362         find a service that will own that name. It then tries to spawn the
2363         executable associated with it. If this fails, it will report an
2364         error. [FIXME what happens if two .service files offer the same service;
2365         what kind of error is reported, should we have a way for the client to
2366         choose one?]
2367       </para>
2368       <para>
2369         The executable launched will have the environment variable
2370         <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2371         message bus so it can connect and request the appropriate names.
2372       </para>
2373       <para>
2374         The executable being launched may want to know whether the message bus
2375         starting it is one of the well-known message buses (see <xref
2376         linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
2377         the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2378         of the well-known buses. The currently-defined values for this variable
2379         are <literal>system</literal> for the systemwide message bus,
2380         and <literal>session</literal> for the per-login-session message
2381         bus. The new executable must still connect to the address given
2382         in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2383         resulting connection is to the well-known bus.
2384       </para>
2385       <para>
2386         [FIXME there should be a timeout somewhere, either specified
2387         in the .service file, by the client, or just a global value
2388         and if the client being activated fails to connect within that
2389         timeout, an error should be sent back.]
2390       </para>
2391     </sect2>
2392
2393     <sect2 id="message-bus-types">
2394       <title>Well-known Message Bus Instances</title>
2395       <para>
2396         Two standard message bus instances are defined here, along with how
2397         to locate them and where their service files live.
2398       </para>
2399       <sect3 id="message-bus-types-login">
2400         <title>Login session message bus</title>
2401         <para>
2402           Each time a user logs in, a <firstterm>login session message
2403             bus</firstterm> may be started. All applications in the user's login
2404           session may interact with one another using this message bus.
2405         </para>
2406         <para>
2407           The address of the login session message bus is given
2408           in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2409           variable. If that variable is not set, applications may
2410           also try to read the address from the X Window System root
2411           window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2412           The root window property must have type <literal>STRING</literal>.
2413           The environment variable should have precedence over the
2414           root window property.
2415         </para>
2416         <para>
2417           [FIXME specify location of .service files, probably using
2418           DESKTOP_DIRS etc. from basedir specification, though login session
2419           bus is not really desktop-specific]
2420         </para>
2421       </sect3>
2422       <sect3 id="message-bus-types-system">
2423         <title>System message bus</title>
2424         <para>
2425           A computer may have a <firstterm>system message bus</firstterm>,
2426           accessible to all applications on the system. This message bus may be
2427           used to broadcast system events, such as adding new hardware devices,
2428           changes in the printer queue, and so forth.
2429         </para>
2430         <para>
2431           The address of the system message bus is given
2432           in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2433           variable. If that variable is not set, applications should try
2434           to connect to the well-known address
2435           <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2436           <footnote>
2437             <para>
2438               The D-BUS reference implementation actually honors the
2439               <literal>$(localstatedir)</literal> configure option
2440               for this address, on both client and server side.
2441             </para>
2442           </footnote>
2443         </para>
2444         <para>
2445           [FIXME specify location of system bus .service files]
2446         </para>
2447       </sect3>
2448     </sect2>
2449
2450     <sect2 id="message-bus-messages">
2451       <title>Message Bus Messages</title>
2452       <para>
2453         The special message bus name <literal>org.freedesktop.DBus</literal>
2454         responds to a number of additional messages.
2455       </para>
2456
2457       <sect3 id="bus-messages-hello">
2458         <title><literal>org.freedesktop.DBus.Hello</literal></title>
2459         <para>
2460           As a method:
2461           <programlisting>
2462             STRING Hello ()
2463           </programlisting>
2464           Reply arguments:
2465           <informaltable>
2466             <tgroup cols="3">
2467               <thead>
2468                 <row>
2469                   <entry>Argument</entry>
2470                   <entry>Type</entry>
2471                   <entry>Description</entry>
2472                 </row>
2473               </thead>
2474               <tbody>
2475                 <row>
2476                   <entry>0</entry>
2477                   <entry>STRING</entry>
2478                   <entry>Unique name assigned to the connection</entry>
2479                 </row>
2480               </tbody>
2481             </tgroup>
2482           </informaltable>
2483         </para>
2484         <para>
2485           Before an application is able to send messages to other applications
2486           it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2487           to the message bus to obtain a unique name. If an application without
2488           a unique name tries to send a message to another application, or a
2489           message to the message bus itself that isn't the
2490           <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2491           disconnected from the bus.
2492         </para>
2493         <para>
2494           There is no corresponding "disconnect" request; if a client wishes to
2495           disconnect from the bus, it simply closes the socket (or other
2496           communication channel).
2497         </para>
2498       </sect3>
2499       <sect3 id="bus-messages-list-names">
2500         <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2501         <para>
2502           As a method:
2503           <programlisting>
2504             ARRAY of STRING ListNames ()
2505           </programlisting>
2506           Reply arguments:
2507           <informaltable>
2508             <tgroup cols="3">
2509               <thead>
2510                 <row>
2511                   <entry>Argument</entry>
2512                   <entry>Type</entry>
2513                   <entry>Description</entry>
2514                 </row>
2515               </thead>
2516               <tbody>
2517                 <row>
2518                   <entry>0</entry>
2519                   <entry>ARRAY of STRING</entry>
2520                   <entry>Array of strings where each string is a bus name</entry>
2521                 </row>
2522               </tbody>
2523             </tgroup>
2524           </informaltable>
2525         </para>
2526         <para>
2527           Returns a list of all currently-owned names on the bus.
2528         </para>
2529       </sect3>
2530       <sect3 id="bus-messages-name-exists">
2531         <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2532         <para>
2533           As a method:
2534           <programlisting>
2535             BOOLEAN NameHasOwner (in STRING name)
2536           </programlisting>
2537           Message arguments:
2538           <informaltable>
2539             <tgroup cols="3">
2540               <thead>
2541                 <row>
2542                   <entry>Argument</entry>
2543                   <entry>Type</entry>
2544                   <entry>Description</entry>
2545                 </row>
2546               </thead>
2547               <tbody>
2548                 <row>
2549                   <entry>0</entry>
2550                   <entry>STRING</entry>
2551                   <entry>Name to check</entry>
2552                 </row>
2553               </tbody>
2554             </tgroup>
2555           </informaltable>
2556           Reply arguments:
2557           <informaltable>
2558             <tgroup cols="3">
2559               <thead>
2560                 <row>
2561                   <entry>Argument</entry>
2562                   <entry>Type</entry>
2563                   <entry>Description</entry>
2564                 </row>
2565               </thead>
2566               <tbody>
2567                 <row>
2568                   <entry>0</entry>
2569                   <entry>BOOLEAN</entry>
2570                   <entry>Return value, true if the name exists</entry>
2571                 </row>
2572               </tbody>
2573             </tgroup>
2574           </informaltable>
2575         </para>
2576         <para>
2577           Checks if the specified name exists (currently has an owner).
2578         </para>
2579       </sect3>
2580
2581       <sect3 id="bus-messages-name-owner-changed">
2582         <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
2583         <para>
2584           This is a signal:
2585           <programlisting>
2586             NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
2587           </programlisting>
2588           Message arguments:
2589           <informaltable>
2590             <tgroup cols="3">
2591               <thead>
2592                 <row>
2593                   <entry>Argument</entry>
2594                   <entry>Type</entry>
2595                   <entry>Description</entry>
2596                 </row>
2597               </thead>
2598               <tbody>
2599                 <row>
2600                   <entry>0</entry>
2601                   <entry>STRING</entry>
2602                   <entry>Name with a new owner</entry>
2603                 </row>
2604                 <row>
2605                   <entry>1</entry>
2606                   <entry>STRING</entry>
2607                   <entry>Old owner or empty string if none</entry>
2608                 </row>
2609                 <row>
2610                   <entry>2</entry>
2611                   <entry>STRING</entry>
2612                   <entry>New owner or empty string if none</entry>
2613                 </row>
2614               </tbody>
2615             </tgroup>
2616           </informaltable>
2617         </para>
2618         <para>
2619           This signal indicates that the owner of a name has changed.
2620           It's also the signal to use to detect the appearance of
2621           new names on the bus.
2622         </para>
2623       </sect3>
2624       <sect3 id="bus-messages-name-lost">
2625         <title><literal>org.freedesktop.DBus.NameLost</literal></title>
2626         <para>
2627           This is a signal:
2628           <programlisting>
2629             NameLost (STRING name)
2630           </programlisting>
2631           Message arguments:
2632           <informaltable>
2633             <tgroup cols="3">
2634               <thead>
2635                 <row>
2636                   <entry>Argument</entry>
2637                   <entry>Type</entry>
2638                   <entry>Description</entry>
2639                 </row>
2640               </thead>
2641               <tbody>
2642                 <row>
2643                   <entry>0</entry>
2644                   <entry>STRING</entry>
2645                   <entry>Name which was lost</entry>
2646                 </row>
2647               </tbody>
2648             </tgroup>
2649           </informaltable>
2650         </para>
2651         <para>
2652           This signal is sent to a specific application when it loses
2653           ownership of a name.
2654         </para>
2655       </sect3>
2656
2657       <sect3 id="bus-messages-name-acquired">
2658         <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
2659         <para>
2660           This is a signal:
2661           <programlisting>
2662             NameAcquired (STRING name)
2663           </programlisting>
2664           Message arguments:
2665           <informaltable>
2666             <tgroup cols="3">
2667               <thead>
2668                 <row>
2669                   <entry>Argument</entry>
2670                   <entry>Type</entry>
2671                   <entry>Description</entry>
2672                 </row>
2673               </thead>
2674               <tbody>
2675                 <row>
2676                   <entry>0</entry>
2677                   <entry>STRING</entry>
2678                   <entry>Name which was acquired</entry>
2679                 </row>
2680               </tbody>
2681             </tgroup>
2682           </informaltable>
2683         </para>
2684         <para>
2685           This signal is sent to a specific application when it gains
2686           ownership of a name.
2687         </para>
2688       </sect3>
2689
2690       <sect3 id="bus-messages-start-service-by-name">
2691         <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
2692         <para>
2693           As a method:
2694           <programlisting>
2695             UINT32 StartServiceByName (in STRING name, in UINT32 flags)
2696           </programlisting>
2697           Message arguments:
2698           <informaltable>
2699             <tgroup cols="3">
2700               <thead>
2701                 <row>
2702                   <entry>Argument</entry>
2703                   <entry>Type</entry>
2704                   <entry>Description</entry>
2705                 </row>
2706               </thead>
2707               <tbody>
2708                 <row>
2709                   <entry>0</entry>
2710                   <entry>STRING</entry>
2711                   <entry>Name of the service to start</entry>
2712                 </row>
2713                 <row>
2714                   <entry>1</entry>
2715                   <entry>UINT32</entry>
2716                   <entry>Flags (currently not used)</entry>
2717                 </row>
2718               </tbody>
2719             </tgroup>
2720           </informaltable>
2721         Reply arguments:
2722         <informaltable>
2723           <tgroup cols="3">
2724             <thead>
2725               <row>
2726                 <entry>Argument</entry>
2727                 <entry>Type</entry>
2728                 <entry>Description</entry>
2729               </row>
2730             </thead>
2731             <tbody>
2732               <row>
2733                 <entry>0</entry>
2734                 <entry>UINT32</entry>
2735                 <entry>Return value</entry>
2736               </row>
2737             </tbody>
2738           </tgroup>
2739         </informaltable>
2740           Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
2741
2742         </para>
2743         <para>
2744           The return value can be one of the following values:
2745           <informaltable>
2746             <tgroup cols="3">
2747               <thead>
2748                 <row>
2749                   <entry>Identifier</entry>
2750                   <entry>Value</entry>
2751                   <entry>Description</entry>
2752                 </row>
2753               </thead>
2754               <tbody>
2755                 <row>
2756                   <entry>DBUS_START_REPLY_SUCCESS</entry>
2757                   <entry>1</entry>
2758                   <entry>The service was successfully started.</entry>
2759                 </row>
2760                 <row>
2761                   <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
2762                   <entry>2</entry>
2763                   <entry>A connection already owns the given name.</entry>
2764                 </row>
2765               </tbody>
2766              </tgroup>
2767            </informaltable>
2768         </para>
2769
2770       </sect3>
2771
2772       <sect3 id="bus-messages-get-name-owner">
2773         <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
2774         <para>
2775           As a method:
2776           <programlisting>
2777             STRING GetNameOwner (in STRING name)
2778           </programlisting>
2779           Message arguments:
2780           <informaltable>
2781             <tgroup cols="3">
2782               <thead>
2783                 <row>
2784                   <entry>Argument</entry>
2785                   <entry>Type</entry>
2786                   <entry>Description</entry>
2787                 </row>
2788               </thead>
2789               <tbody>
2790                 <row>
2791                   <entry>0</entry>
2792                   <entry>STRING</entry>
2793                   <entry>Name to get the owner of</entry>
2794                 </row>
2795               </tbody>
2796             </tgroup>
2797           </informaltable>
2798         Reply arguments:
2799         <informaltable>
2800           <tgroup cols="3">
2801             <thead>
2802               <row>
2803                 <entry>Argument</entry>
2804                 <entry>Type</entry>
2805                 <entry>Description</entry>
2806               </row>
2807             </thead>
2808             <tbody>
2809               <row>
2810                 <entry>0</entry>
2811                 <entry>STRING</entry>
2812                 <entry>Return value, a unique connection name</entry>
2813               </row>
2814             </tbody>
2815           </tgroup>
2816         </informaltable>
2817         Returns the unique connection name of the primary owner of the name
2818         given. If the requested name doesn't have an owner, returns a
2819         <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
2820        </para>
2821       </sect3>
2822
2823       <sect3 id="bus-messages-get-connection-unix-user">
2824         <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
2825         <para>
2826           As a method:
2827           <programlisting>
2828             UINT32 GetConnectionUnixUser (in STRING connection_name)
2829           </programlisting>
2830           Message arguments:
2831           <informaltable>
2832             <tgroup cols="3">
2833               <thead>
2834                 <row>
2835                   <entry>Argument</entry>
2836                   <entry>Type</entry>
2837                   <entry>Description</entry>
2838                 </row>
2839               </thead>
2840               <tbody>
2841                 <row>
2842                   <entry>0</entry>
2843                   <entry>STRING</entry>
2844                   <entry>Name of the connection to query</entry>
2845                 </row>
2846               </tbody>
2847             </tgroup>
2848           </informaltable>
2849         Reply arguments:
2850         <informaltable>
2851           <tgroup cols="3">
2852             <thead>
2853               <row>
2854                 <entry>Argument</entry>
2855                 <entry>Type</entry>
2856                 <entry>Description</entry>
2857               </row>
2858             </thead>
2859             <tbody>
2860               <row>
2861                 <entry>0</entry>
2862                 <entry>UINT32</entry>
2863                 <entry>unix user id</entry>
2864               </row>
2865             </tbody>
2866           </tgroup>
2867         </informaltable>
2868         Returns the unix uid of the process connected to the server. If unable to
2869         determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
2870         error is returned.
2871        </para>
2872       </sect3>
2873
2874     </sect2>
2875
2876   </sect1>
2877 <!--
2878   <appendix id="implementation-notes">
2879     <title>Implementation notes</title>
2880     <sect1 id="implementation-notes-subsection">
2881       <title></title>
2882       <para>
2883       </para>
2884     </sect1>
2885   </appendix>
2886 -->
2887
2888   <glossary><title>Glossary</title>
2889     <para>
2890       This glossary defines some of the terms used in this specification.
2891     </para>
2892
2893     <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
2894       <glossdef>
2895         <para>
2896           The message bus maintains an association between names and
2897           connections. (Normally, there's one connection per application.)  A
2898           bus name is simply an identifier used to locate connections. For
2899           example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
2900           name might be used to send a message to a screensaver from Yoyodyne
2901           Corporation.  An application is said to <firstterm>own</firstterm> a
2902           name if the message bus has associated the application's connection
2903           with the name.  Names may also have <firstterm>queued
2904           owners</firstterm> (see <xref linkend="term-queued-owner"/>).
2905             The bus assigns a unique name to each connection,
2906             see <xref linkend="term-unique-name"/>. Other names
2907               can be thought of as "well-known names" and are
2908               used to find applications that offer specific functionality.
2909         </para>
2910       </glossdef>
2911     </glossentry>
2912
2913     <glossentry id="term-message"><glossterm>Message</glossterm>
2914       <glossdef>
2915         <para>
2916           A message is the atomic unit of communication via the D-BUS
2917           protocol. It consists of a <firstterm>header</firstterm> and a
2918           <firstterm>body</firstterm>; the body is made up of
2919           <firstterm>arguments</firstterm>.
2920         </para>
2921       </glossdef>
2922     </glossentry>
2923
2924     <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
2925       <glossdef>
2926         <para>
2927           The message bus is a special application that forwards
2928           or routes messages between a group of applications
2929           connected to the message bus. It also manages
2930           <firstterm>names</firstterm> used for routing
2931           messages.
2932         </para>
2933       </glossdef>
2934     </glossentry>
2935
2936     <glossentry id="term-name"><glossterm>Name</glossterm>
2937       <glossdef>
2938         <para>
2939           See <xref linkend="term-bus-name"/>. "Name" may
2940             also be used to refer to some of the other names
2941             in D-BUS, such as interface names.
2942         </para>
2943       </glossdef>
2944     </glossentry>
2945
2946     <glossentry id="namespace"><glossterm>Namespace</glossterm>
2947       <glossdef>
2948         <para>
2949           Used to prevent collisions when defining new interfaces or bus
2950           names. The convention used is the same one Java uses for defining
2951           classes: a reversed domain name.
2952         </para>
2953       </glossdef>
2954     </glossentry>
2955
2956     <glossentry id="term-object"><glossterm>Object</glossterm>
2957       <glossdef>
2958         <para>
2959           Each application contains <firstterm>objects</firstterm>, which have
2960           <firstterm>interfaces</firstterm> and
2961           <firstterm>methods</firstterm>. Objects are referred to by a name,
2962           called a <firstterm>path</firstterm>.
2963         </para>
2964       </glossdef>
2965     </glossentry>
2966
2967     <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
2968       <glossdef>
2969         <para>
2970           An application talking directly to another application, without going
2971           through a message bus. One-to-one connections may be "peer to peer" or
2972           "client to server." The D-BUS protocol has no concept of client
2973           vs. server after a connection has authenticated; the flow of messages
2974           is symmetrical (full duplex).
2975         </para>
2976       </glossdef>
2977     </glossentry>
2978
2979     <glossentry id="term-path"><glossterm>Path</glossterm>
2980       <glossdef>
2981         <para>
2982           Object references (object names) in D-BUS are organized into a
2983           filesystem-style hierarchy, so each object is named by a path. As in
2984           LDAP, there's no difference between "files" and "directories"; a path
2985           can refer to an object, while still having child objects below it.
2986         </para>
2987       </glossdef>
2988     </glossentry>
2989
2990     <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
2991       <glossdef>
2992         <para>
2993           Each bus name has a primary owner; messages sent to the name go to the
2994           primary owner. However, certain names also maintain a queue of
2995           secondary owners "waiting in the wings." If the primary owner releases
2996           the name, then the first secondary owner in the queue automatically
2997           becomes the new owner of the name.
2998         </para>
2999       </glossdef>
3000     </glossentry>
3001
3002     <glossentry id="term-service"><glossterm>Service</glossterm>
3003       <glossdef>
3004         <para>
3005           A service is an executable that can be launched by the bus daemon.
3006           Services normally guarantee some particular features, for example they
3007           may guarantee that they will request a specific name such as
3008           "org.freedesktop.Screensaver", have a singleton object
3009           "/org/freedesktop/Application", and that object will implement the
3010           interface "org.freedesktop.ScreensaverControl".
3011         </para>
3012       </glossdef>
3013     </glossentry>
3014
3015     <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
3016       <glossdef>
3017         <para>
3018           ".service files" tell the bus about service applications that can be
3019           launched (see <xref linkend="term-service"/>). Most importantly they
3020           provide a mapping from bus names to services that will request those
3021             names when they start up.
3022         </para>
3023       </glossdef>
3024     </glossentry>
3025
3026     <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
3027       <glossdef>
3028         <para>
3029           The special name automatically assigned to each connection by the
3030           message bus. This name will never change owner, and will be unique
3031           (never reused during the lifetime of the message bus).
3032           It will begin with a ':' character.
3033         </para>
3034       </glossdef>
3035     </glossentry>
3036
3037   </glossary>
3038 </article>
3039