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