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       <para>
1398         If the D-BUS protocol changes incompatibly at some future time,
1399         applications implementing the new protocol would probably be able to
1400         check for support of the new protocol by sending a new command and
1401         receiving an ERROR from applications that don't understand it. Thus the
1402         ERROR feature of the auth protocol is an escape hatch that lets us
1403         negotiate extensions or changes to the D-BUS protocol in the future.
1404       </para>
1405     </sect2>
1406     <sect2 id="auth-examples">
1407       <title>Authentication examples</title>
1408
1409       <para>
1410         <figure>
1411           <title>Example of successful magic cookie authentication</title>
1412           <programlisting>
1413             (MAGIC_COOKIE is a made up mechanism)
1414
1415             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1416             S: OK
1417             C: BEGIN
1418           </programlisting>
1419         </figure>
1420         <figure>
1421           <title>Example of finding out mechanisms then picking one</title>
1422           <programlisting>
1423             C: AUTH
1424             S: REJECTED KERBEROS_V4 SKEY
1425             C: AUTH SKEY 7ab83f32ee
1426             S: DATA 8799cabb2ea93e
1427             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1428             S: OK
1429             C: BEGIN
1430           </programlisting>
1431         </figure>
1432         <figure>
1433           <title>Example of client sends unknown command then falls back to regular auth</title>
1434           <programlisting>
1435             C: FOOBAR
1436             S: ERROR
1437             C: AUTH MAGIC_COOKIE 3736343435313230333039
1438             S: OK
1439             C: BEGIN
1440           </programlisting>
1441         </figure>
1442         <figure>
1443           <title>Example of server doesn't support initial auth mechanism</title>
1444           <programlisting>
1445             C: AUTH MAGIC_COOKIE 3736343435313230333039
1446             S: REJECTED KERBEROS_V4 SKEY
1447             C: AUTH SKEY 7ab83f32ee
1448             S: DATA 8799cabb2ea93e
1449             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1450             S: OK
1451             C: BEGIN
1452           </programlisting>
1453         </figure>
1454         <figure>
1455           <title>Example of wrong password or the like followed by successful retry</title>
1456           <programlisting>
1457             C: AUTH MAGIC_COOKIE 3736343435313230333039
1458             S: REJECTED KERBEROS_V4 SKEY
1459             C: AUTH SKEY 7ab83f32ee
1460             S: DATA 8799cabb2ea93e
1461             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1462             S: REJECTED
1463             C: AUTH SKEY 7ab83f32ee
1464             S: DATA 8799cabb2ea93e
1465             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1466             S: OK
1467             C: BEGIN
1468           </programlisting>
1469         </figure>
1470         <figure>
1471           <title>Example of skey cancelled and restarted</title>
1472           <programlisting>
1473             C: AUTH MAGIC_COOKIE 3736343435313230333039
1474             S: REJECTED KERBEROS_V4 SKEY
1475             C: AUTH SKEY 7ab83f32ee
1476             S: DATA 8799cabb2ea93e
1477             C: CANCEL
1478             S: REJECTED
1479             C: AUTH SKEY 7ab83f32ee
1480             S: DATA 8799cabb2ea93e
1481             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1482             S: OK
1483             C: BEGIN
1484           </programlisting>
1485         </figure>
1486       </para>
1487     </sect2>
1488     <sect2 id="auth-states">
1489       <title>Authentication state diagrams</title>
1490
1491       <para>
1492         This section documents the auth protocol in terms of
1493         a state machine for the client and the server. This is
1494         probably the most robust way to implement the protocol.
1495       </para>
1496
1497       <sect3 id="auth-states-client">
1498         <title>Client states</title>
1499
1500         <para>
1501           To more precisely describe the interaction between the
1502           protocol state machine and the authentication mechanisms the
1503           following notation is used: MECH(CHALL) means that the
1504           server challenge CHALL was fed to the mechanism MECH, which
1505           returns one of
1506
1507           <itemizedlist>
1508             <listitem>
1509               <para>
1510                 CONTINUE(RESP) means continue the auth conversation
1511                 and send RESP as the response to the server;
1512               </para>
1513             </listitem>
1514
1515             <listitem>
1516               <para>
1517                 OK(RESP) means that after sending RESP to the server
1518                 the client side of the auth conversation is finished
1519                 and the server should return "OK";
1520               </para>
1521             </listitem>
1522
1523             <listitem>
1524               <para>
1525                 ERROR means that CHALL was invalid and could not be
1526                 processed.
1527               </para>
1528             </listitem>
1529           </itemizedlist>
1530
1531           Both RESP and CHALL may be empty.
1532         </para>
1533
1534         <para>
1535           The Client starts by getting an initial response from the
1536           default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1537           the mechanism did not provide an initial response.  If the
1538           mechanism returns CONTINUE, the client starts in state
1539           <emphasis>WaitingForData</emphasis>, if the mechanism
1540           returns OK the client starts in state
1541           <emphasis>WaitingForOK</emphasis>.
1542         </para>
1543
1544         <para>
1545           The client should keep track of available mechanisms and
1546           which it mechanisms it has already attempted. This list is
1547           used to decide which AUTH command to send. When the list is
1548           exhausted, the client should give up and close the
1549           connection.
1550         </para>
1551
1552         <formalpara>
1553           <title><emphasis>WaitingForData</emphasis></title>
1554           <para>
1555             <itemizedlist>
1556               <listitem>
1557                 <para>
1558                   Receive DATA CHALL
1559                   <simplelist>
1560                     <member>
1561                       MECH(CHALL) returns CONTINUE(RESP) &rarr; send
1562                       DATA RESP, goto
1563                       <emphasis>WaitingForData</emphasis>
1564                     </member>
1565
1566                     <member>
1567                       MECH(CHALL) returns OK(RESP) &rarr; send DATA
1568                       RESP, goto <emphasis>WaitingForOK</emphasis>
1569                     </member>
1570
1571                     <member>
1572                       MECH(CHALL) returns ERROR &rarr; send ERROR
1573                       [msg], goto <emphasis>WaitingForData</emphasis>
1574                     </member>
1575                   </simplelist>
1576                 </para>
1577               </listitem>
1578
1579               <listitem>
1580                 <para>
1581                   Receive REJECTED [mechs] &rarr;
1582                   send AUTH [next mech], goto
1583                   WaitingForData or <emphasis>WaitingForOK</emphasis>
1584                 </para>
1585               </listitem>
1586               <listitem>
1587                 <para>
1588                   Receive ERROR &rarr; send
1589                   CANCEL, goto
1590                   <emphasis>WaitingForReject</emphasis>
1591                 </para>
1592               </listitem>
1593               <listitem>
1594                 <para>
1595                   Receive OK &rarr; send
1596                   BEGIN, terminate auth
1597                   conversation, authenticated
1598                 </para>
1599               </listitem>
1600               <listitem>
1601                 <para>
1602                   Receive anything else &rarr; send
1603                   ERROR, goto
1604                   <emphasis>WaitingForData</emphasis>
1605                 </para>
1606               </listitem>
1607             </itemizedlist>
1608           </para>
1609         </formalpara>
1610
1611         <formalpara>
1612           <title><emphasis>WaitingForOK</emphasis></title>
1613           <para>
1614             <itemizedlist>
1615               <listitem>
1616                 <para>
1617                   Receive OK &rarr; send BEGIN, terminate auth
1618                   conversation, <emphasis>authenticated</emphasis>
1619                 </para>
1620               </listitem>
1621               <listitem>
1622                 <para>
1623                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1624                   goto <emphasis>WaitingForData</emphasis> or
1625                   <emphasis>WaitingForOK</emphasis>
1626                 </para>
1627               </listitem>
1628
1629               <listitem>
1630                 <para>
1631                   Receive DATA &rarr; send CANCEL, goto
1632                   <emphasis>WaitingForReject</emphasis>
1633                 </para>
1634               </listitem>
1635
1636               <listitem>
1637                 <para>
1638                   Receive ERROR &rarr; send CANCEL, goto
1639                   <emphasis>WaitingForReject</emphasis>
1640                 </para>
1641               </listitem>
1642
1643               <listitem>
1644                 <para>
1645                   Receive anything else &rarr; send ERROR, goto
1646                   <emphasis>WaitingForOK</emphasis>
1647                 </para>
1648               </listitem>
1649             </itemizedlist>
1650           </para>
1651         </formalpara>
1652
1653         <formalpara>
1654           <title><emphasis>WaitingForReject</emphasis></title>
1655           <para>
1656             <itemizedlist>
1657               <listitem>
1658                 <para>
1659                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1660                   goto <emphasis>WaitingForData</emphasis> or
1661                   <emphasis>WaitingForOK</emphasis>
1662                 </para>
1663               </listitem>
1664
1665               <listitem>
1666                 <para>
1667                   Receive anything else &rarr; terminate auth
1668                   conversation, disconnect
1669                 </para>
1670               </listitem>
1671             </itemizedlist>
1672           </para>
1673         </formalpara>
1674
1675       </sect3>
1676
1677       <sect3 id="auth-states-server">
1678         <title>Server states</title>
1679
1680         <para>
1681           For the server MECH(RESP) means that the client response
1682           RESP was fed to the the mechanism MECH, which returns one of
1683
1684           <itemizedlist>
1685             <listitem>
1686               <para>
1687                 CONTINUE(CHALL) means continue the auth conversation and
1688                 send CHALL as the challenge to the client;
1689               </para>
1690             </listitem>
1691
1692             <listitem>
1693               <para>
1694                 OK means that the client has been successfully
1695                 authenticated;
1696               </para>
1697             </listitem>
1698
1699             <listitem>
1700               <para>
1701                 REJECT means that the client failed to authenticate or
1702                 there was an error in RESP.
1703               </para>
1704             </listitem>
1705           </itemizedlist>
1706
1707           The server starts out in state
1708           <emphasis>WaitingForAuth</emphasis>.  If the client is
1709           rejected too many times the server must disconnect the
1710           client.
1711         </para>
1712
1713         <formalpara>
1714           <title><emphasis>WaitingForAuth</emphasis></title>
1715           <para>
1716             <itemizedlist>
1717
1718               <listitem>
1719                 <para>
1720                   Receive AUTH &rarr; send REJECTED [mechs], goto
1721                   <emphasis>WaitingForAuth</emphasis>
1722                 </para>
1723               </listitem>
1724
1725               <listitem>
1726                 <para>
1727                   Receive AUTH MECH RESP
1728
1729                   <simplelist>
1730                     <member>
1731                       MECH not valid mechanism &rarr; send REJECTED
1732                       [mechs], goto
1733                       <emphasis>WaitingForAuth</emphasis>
1734                     </member>
1735
1736                     <member>
1737                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1738                       DATA CHALL, goto
1739                       <emphasis>WaitingForData</emphasis>
1740                     </member>
1741
1742                     <member>
1743                       MECH(RESP) returns OK &rarr; send OK, goto
1744                       <emphasis>WaitingForBegin</emphasis>
1745                     </member>
1746
1747                     <member>
1748                       MECH(RESP) returns REJECT &rarr; send REJECTED
1749                       [mechs], goto
1750                       <emphasis>WaitingForAuth</emphasis>
1751                     </member>
1752                   </simplelist>
1753                 </para>
1754               </listitem>
1755
1756               <listitem>
1757                 <para>
1758                   Receive BEGIN &rarr; terminate
1759                   auth conversation, disconnect
1760                 </para>
1761               </listitem>
1762
1763               <listitem>
1764                 <para>
1765                   Receive ERROR &rarr; send REJECTED [mechs], goto
1766                   <emphasis>WaitingForAuth</emphasis>
1767                 </para>
1768               </listitem>
1769
1770               <listitem>
1771                 <para>
1772                   Receive anything else &rarr; send
1773                   ERROR, goto
1774                   <emphasis>WaitingForAuth</emphasis>
1775                 </para>
1776               </listitem>
1777             </itemizedlist>
1778           </para>
1779         </formalpara>
1780
1781
1782         <formalpara>
1783           <title><emphasis>WaitingForData</emphasis></title>
1784           <para>
1785             <itemizedlist>
1786               <listitem>
1787                 <para>
1788                   Receive DATA RESP
1789                   <simplelist>
1790                     <member>
1791                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1792                       DATA CHALL, goto
1793                       <emphasis>WaitingForData</emphasis>
1794                     </member>
1795
1796                     <member>
1797                       MECH(RESP) returns OK &rarr; send OK, goto
1798                       <emphasis>WaitingForBegin</emphasis>
1799                     </member>
1800
1801                     <member>
1802                       MECH(RESP) returns REJECT &rarr; send REJECTED
1803                       [mechs], goto
1804                       <emphasis>WaitingForAuth</emphasis>
1805                     </member>
1806                   </simplelist>
1807                 </para>
1808               </listitem>
1809
1810               <listitem>
1811                 <para>
1812                   Receive BEGIN &rarr; terminate auth conversation,
1813                   disconnect
1814                 </para>
1815               </listitem>
1816
1817               <listitem>
1818                 <para>
1819                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1820                   <emphasis>WaitingForAuth</emphasis>
1821                 </para>
1822               </listitem>
1823
1824               <listitem>
1825                 <para>
1826                   Receive ERROR &rarr; send REJECTED [mechs], goto
1827                   <emphasis>WaitingForAuth</emphasis>
1828                 </para>
1829               </listitem>
1830
1831               <listitem>
1832                 <para>
1833                   Receive anything else &rarr; send ERROR, goto
1834                   <emphasis>WaitingForData</emphasis>
1835                 </para>
1836               </listitem>
1837             </itemizedlist>
1838           </para>
1839         </formalpara>
1840
1841         <formalpara>
1842           <title><emphasis>WaitingForBegin</emphasis></title>
1843           <para>
1844             <itemizedlist>
1845               <listitem>
1846                 <para>
1847                   Receive BEGIN &rarr; terminate auth conversation,
1848                   client authenticated
1849                 </para>
1850               </listitem>
1851
1852               <listitem>
1853                 <para>
1854                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1855                   <emphasis>WaitingForAuth</emphasis>
1856                 </para>
1857               </listitem>
1858
1859               <listitem>
1860                 <para>
1861                   Receive ERROR &rarr; send REJECTED [mechs], goto
1862                   <emphasis>WaitingForAuth</emphasis>
1863                 </para>
1864               </listitem>
1865
1866               <listitem>
1867                 <para>
1868                   Receive anything else &rarr; send ERROR, goto
1869                   <emphasis>WaitingForBegin</emphasis>
1870                 </para>
1871               </listitem>
1872             </itemizedlist>
1873           </para>
1874         </formalpara>
1875
1876       </sect3>
1877
1878     </sect2>
1879     <sect2 id="auth-mechanisms">
1880       <title>Authentication mechanisms</title>
1881       <para>
1882         This section describes some new authentication mechanisms.
1883         D-BUS also allows any standard SASL mechanism of course.
1884       </para>
1885       <sect3 id="auth-mechanisms-sha">
1886         <title>DBUS_COOKIE_SHA1</title>
1887         <para>
1888           The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
1889           has the ability to read a private file owned by the user being
1890           authenticated. If the client can prove that it has access to a secret
1891           cookie stored in this file, then the client is authenticated.
1892           Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
1893           directory.
1894         </para>
1895         <para>
1896           Authentication proceeds as follows:
1897           <itemizedlist>
1898             <listitem>
1899               <para>
1900                 The client sends the username it would like to authenticate
1901                 as.
1902               </para>
1903             </listitem>
1904             <listitem>
1905               <para>
1906                 The server sends the name of its "cookie context" (see below); a
1907                 space character; the integer ID of the secret cookie the client
1908                 must demonstrate knowledge of; a space character; then a
1909                 hex-encoded randomly-generated challenge string.
1910               </para>
1911             </listitem>
1912             <listitem>
1913               <para>
1914                 The client locates the cookie, and generates its own hex-encoded
1915                 randomly-generated challenge string.  The client then
1916                 concatentates the server's hex-encoded challenge, a ":"
1917                 character, its own hex-encoded challenge, another ":" character,
1918                 and the hex-encoded cookie.  It computes the SHA-1 hash of this
1919                 composite string.  It sends back to the server the client's
1920                 hex-encoded challenge string, a space character, and the SHA-1
1921                 hash.
1922               </para>
1923             </listitem>
1924             <listitem>
1925               <para>
1926                 The server generates the same concatenated string used by the
1927                 client and computes its SHA-1 hash. It compares the hash with
1928                 the hash received from the client; if the two hashes match, the
1929                 client is authenticated.
1930               </para>
1931             </listitem>
1932           </itemizedlist>
1933         </para>
1934         <para>
1935           Each server has a "cookie context," which is a name that identifies a
1936           set of cookies that apply to that server. A sample context might be
1937           "org_freedesktop_session_bus". Context names must be valid ASCII,
1938           nonzero length, and may not contain the characters slash ("/"),
1939           backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
1940           tab ("\t"), or period ("."). There is a default context,
1941           "org_freedesktop_general" that's used by servers that do not specify
1942           otherwise.
1943         </para>
1944         <para>
1945           Cookies are stored in a user's home directory, in the directory
1946           <filename>~/.dbus-keyrings/</filename>. This directory must
1947           not be readable or writable by other users. If it is,
1948           clients and servers must ignore it. The directory
1949           contains cookie files named after the cookie context.
1950         </para>
1951         <para>
1952           A cookie file contains one cookie per line. Each line
1953           has three space-separated fields:
1954           <itemizedlist>
1955             <listitem>
1956               <para>
1957                 The cookie ID number, which must be a non-negative integer and
1958                 may not be used twice in the same file.
1959               </para>
1960             </listitem>
1961             <listitem>
1962               <para>
1963                 The cookie's creation time, in UNIX seconds-since-the-epoch
1964                 format.
1965               </para>
1966             </listitem>
1967             <listitem>
1968               <para>
1969                 The cookie itself, a hex-encoded random block of bytes. The cookie
1970                 may be of any length, though obviously security increases
1971                 as the length increases.
1972               </para>
1973             </listitem>
1974           </itemizedlist>
1975         </para>
1976         <para>
1977           Only server processes modify the cookie file.
1978           They must do so with this procedure:
1979           <itemizedlist>
1980             <listitem>
1981               <para>
1982                 Create a lockfile name by appending ".lock" to the name of the
1983                 cookie file.  The server should attempt to create this file
1984                 using <literal>O_CREAT | O_EXCL</literal>.  If file creation
1985                 fails, the lock fails. Servers should retry for a reasonable
1986                 period of time, then they may choose to delete an existing lock
1987                 to keep users from having to manually delete a stale
1988                 lock. <footnote><para>Lockfiles are used instead of real file
1989                 locking <literal>fcntl()</literal> because real locking
1990                 implementations are still flaky on network
1991                 filesystems.</para></footnote>
1992               </para>
1993             </listitem>
1994             <listitem>
1995               <para>
1996                 Once the lockfile has been created, the server loads the cookie
1997                 file. It should then delete any cookies that are old (the
1998                 timeout can be fairly short), or more than a reasonable
1999                 time in the future (so that cookies never accidentally
2000                 become permanent, if the clock was set far into the future
2001                 at some point). If no recent keys remain, the
2002                 server may generate a new key.
2003               </para>
2004             </listitem>
2005             <listitem>
2006               <para>
2007                 The pruned and possibly added-to cookie file
2008                 must be resaved atomically (using a temporary
2009                 file which is rename()'d).
2010               </para>
2011             </listitem>
2012             <listitem>
2013               <para>
2014                 The lock must be dropped by deleting the lockfile.
2015               </para>
2016             </listitem>
2017           </itemizedlist>
2018         </para>
2019         <para>
2020           Clients need not lock the file in order to load it,
2021           because servers are required to save the file atomically.
2022         </para>
2023       </sect3>
2024     </sect2>
2025   </sect1>
2026   <sect1 id="addresses">
2027     <title>Server Addresses</title>
2028     <para>
2029       Server addresses consist of a transport name followed by a colon, and
2030       then an optional, comma-separated list of keys and values in the form key=value.
2031       [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
2032     </para>
2033     <para>
2034       For example:
2035       <programlisting>unix:path=/tmp/dbus-test</programlisting>
2036       Which is the address to a unix socket with the path /tmp/dbus-test.
2037     </para>
2038     <para>
2039       [FIXME clarify if attempting to connect to each is a requirement
2040       or just a suggestion]
2041       When connecting to a server, multiple server addresses can be
2042       separated by a semi-colon. The library will then try to connect
2043       to the first address and if that fails, it'll try to connect to
2044       the next one specified, and so forth. For example
2045       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2046     </para>
2047     <para>
2048       [FIXME we need to specify in detail each transport and its possible arguments]
2049       Current transports include: unix domain sockets (including
2050       abstract namespace on linux), TCP/IP, and a debug/testing transport using
2051       in-process pipes. Future possible transports include one that
2052       tunnels over X11 protocol.
2053     </para>
2054   </sect1>
2055
2056   <sect1 id="standard-messages">
2057     <title>Standard One-to-One Messages</title>
2058     <para>
2059       See <xref linkend="message-protocol-types-notation"/> for details on
2060        the notation used in this section.
2061     </para>
2062     <sect2 id="standard-messages-ping">
2063       <title><literal>org.freedesktop.Peer.Ping</literal></title>
2064       <para>
2065         <programlisting>
2066           org.freedesktop.Peer.Ping ()
2067         </programlisting>
2068       </para>
2069       <para>
2070         On receipt of the <literal>METHOD_CALL</literal>
2071         message <literal>org.freedesktop.Peer.Ping</literal>, an application
2072         should do nothing other than reply with a <literal>METHOD_RETURN</literal> as usual.
2073       </para>
2074     </sect2>
2075
2076   </sect1>
2077
2078   <sect1 id="message-bus">
2079     <title>Message Bus Specification</title>
2080     <sect2 id="message-bus-overview">
2081       <title>Message Bus Overview</title>
2082       <para>
2083         The message bus accepts connections from one or more applications.
2084         Once connected, applications can exchange messages with other
2085         applications that are also connected to the bus.
2086       </para>
2087       <para>
2088         In order to route messages among connections, the message bus keeps a
2089         mapping from names to connections. Each connection has one
2090         unique-for-the-lifetime-of-the-bus name automatically assigned.
2091         Applications may request additional names for a connection. Additional
2092         names are usually "well-known names" such as
2093         "org.freedesktop.TextEditor". When a name is bound to a connection,
2094         that connection is said to <firstterm>own</firstterm> the name.
2095       </para>
2096       <para>
2097         The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2098         This name routes messages to the bus, allowing applications to make
2099         administrative requests. For example, applications can ask the bus
2100         to assign a name to a connection.
2101       </para>
2102       <para>
2103         Each name may have <firstterm>queued owners</firstterm>.  When an
2104         application requests a name for a connection and the name is already in
2105         use, the bus will optionally add the connection to a queue waiting for
2106         the name. If the current owner of the name disconnects or releases
2107         the name, the next connection in the queue will become the new owner.
2108       </para>
2109
2110       <para>
2111         This feature causes the right thing to happen if you start two text
2112         editors for example; the first one may request "org.freedesktop.TextEditor",
2113         and the second will be queued as a possible owner of that name. When
2114         the first exits, the second will take over.
2115       </para>
2116
2117       <para>
2118         Messages may have a <literal>DESTINATION</literal> field (see <xref
2119         linkend="message-protocol-header-fields"/>).  If the
2120         <literal>DESTINATION</literal> field is present, it specifies a message
2121         recipient by name. Method calls and replies normally specify this field.
2122       </para>
2123
2124       <para>
2125         Signals normally do not specify a destination; they are sent to all
2126         applications with <firstterm>message matching rules</firstterm> that
2127         match the message.
2128       </para>
2129
2130       <para>
2131         When the message bus receives a method call, if the
2132         <literal>DESTINATION</literal> field is absent, the call is taken to be
2133         a standard one-to-one message and interpreted by the message bus
2134         itself. For example, sending an
2135         <literal>org.freedesktop.Peer.Ping</literal> message with no
2136         <literal>DESTINATION</literal> will cause the message bus itself to
2137         reply to the ping immediately; the message bus will not make this
2138         message visible to other applications.
2139       </para>
2140
2141       <para>
2142         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
2143         the ping message were sent with a <literal>DESTINATION</literal> name of
2144         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2145         forwarded, and the Yoyodyne Corporation screensaver application would be
2146         expected to reply to the ping.
2147       </para>
2148     </sect2>
2149
2150     <sect2 id="message-bus-names">
2151       <title>Message Bus Names</title>
2152       <para>
2153         Each connection has at least one name, assigned at connection time and
2154         returned in response to the
2155         <literal>org.freedesktop.DBus.Hello</literal> method call.  This
2156         automatically-assigned name is called the connection's <firstterm>unique
2157         name</firstterm>.  Unique names are never reused for two different
2158         connections to the same bus.
2159       </para>
2160       <para>
2161         Ownership of a unique name is a prerequisite for interaction with
2162         the message bus. It logically follows that the unique name is always
2163         the first name that an application comes to own, and the last
2164         one that it loses ownership of.
2165       </para>
2166       <para>
2167         Unique connection names must begin with the character ':' (ASCII colon
2168         character); bus names that are not unique names must not begin
2169         with this character. (The bus must reject any attempt by an application
2170         to manually request a name beginning with ':'.) This restriction
2171         categorically prevents "spoofing"; messages sent to a unique name
2172         will always go to the expected connection.
2173       </para>
2174       <para>
2175         When a connection is closed, all the names that it owns are deleted (or
2176         transferred to the next connection in the queue if any).
2177       </para>
2178       <para>
2179         A connection can request additional names to be associated with it using
2180         the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2181         linkend="message-protocol-names-bus"/> describes the format of a valid
2182         name.
2183       </para>
2184
2185       <sect3 id="bus-messages-request-name">
2186         <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2187         <para>
2188           As a method:
2189           <programlisting>
2190             UINT32 RequestName (in STRING name, in UINT32 flags)
2191           </programlisting>
2192           Message arguments:
2193           <informaltable>
2194             <tgroup cols="3">
2195               <thead>
2196                 <row>
2197                   <entry>Argument</entry>
2198                   <entry>Type</entry>
2199                   <entry>Description</entry>
2200                 </row>
2201               </thead>
2202               <tbody>
2203                 <row>
2204                   <entry>0</entry>
2205                   <entry>STRING</entry>
2206                   <entry>Name to request</entry>
2207                 </row>
2208                 <row>
2209                   <entry>1</entry>
2210                   <entry>UINT32</entry>
2211                   <entry>Flags</entry>
2212                 </row>
2213               </tbody>
2214             </tgroup>
2215           </informaltable>
2216           Reply arguments:
2217           <informaltable>
2218             <tgroup cols="3">
2219               <thead>
2220                 <row>
2221                   <entry>Argument</entry>
2222                   <entry>Type</entry>
2223                   <entry>Description</entry>
2224                 </row>
2225               </thead>
2226               <tbody>
2227                 <row>
2228                   <entry>0</entry>
2229                   <entry>UINT32</entry>
2230                   <entry>Return value</entry>
2231                 </row>
2232               </tbody>
2233             </tgroup>
2234           </informaltable>
2235         </para>
2236         <para>
2237           This method call should be sent to
2238           <literal>org.freedesktop.DBus</literal> and asks the message bus to
2239           assign the given name to the method caller.  The flags argument
2240           contains any of the following values logically ORed together:
2241
2242           <informaltable>
2243             <tgroup cols="3">
2244               <thead>
2245                 <row>
2246                   <entry>Conventional Name</entry>
2247                   <entry>Value</entry>
2248                   <entry>Description</entry>
2249                 </row>
2250               </thead>
2251               <tbody>
2252                 <row>
2253                   <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2254                   <entry>0x1</entry>
2255                   <entry>
2256                     If the application succeeds in becoming the owner of the specified name,
2257                     then ownership of the name can't be transferred until the application
2258                     disconnects. If this flag is not set, then any application trying to become
2259                     the owner of the name will succeed and the previous owner will be
2260                     sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
2261                   </entry>
2262                 </row>
2263                 <row>
2264                   <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2265                   <entry>0x2</entry>
2266                   <entry>
2267                     Try to replace the current owner if there is one. If this
2268                     flag is not set the application will only become the owner of
2269                     the name if there is no current owner.
2270                   </entry>
2271                 </row>
2272               </tbody>
2273             </tgroup>
2274           </informaltable>
2275
2276           The return code can be one of the following values:
2277
2278           <informaltable>
2279             <tgroup cols="3">
2280               <thead>
2281                 <row>
2282                   <entry>Conventional Name</entry>
2283                   <entry>Value</entry>
2284                   <entry>Description</entry>
2285                 </row>
2286               </thead>
2287               <tbody>
2288                 <row>
2289                   <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2290                   <entry>1</entry> <entry>The caller is now the primary owner of
2291                   the name, replacing any previous owner. Either the name had no
2292                   owner before, or the caller specified
2293                   DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2294                   specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2295                 </row>
2296                 <row>
2297                   <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2298                   <entry>2</entry>
2299                   <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>
2300                 </row>
2301                 <row>
2302                   <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2303                   <entry>3</entry>
2304                   <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2305                 </row>
2306                 <row>
2307                   <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2308                   <entry>4</entry>
2309                   <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2310                 </row>
2311               </tbody>
2312             </tgroup>
2313           </informaltable>
2314         </para>
2315       </sect3>
2316     </sect2>
2317
2318     <sect2 id="message-bus-routing">
2319       <title>Message Bus Message Routing</title>
2320       <para>
2321         FIXME
2322       </para>
2323     </sect2>
2324     <sect2 id="message-bus-starting-services">
2325       <title>Message Bus Starting Services</title>
2326       <para>
2327         The message bus can start applications on behalf of other applications.
2328         In CORBA terms, this would be called <firstterm>activation</firstterm>.
2329         An application that can be started in this way is called a
2330         <firstterm>service</firstterm>.
2331       </para>
2332       <para>
2333         With D-BUS, starting a service is normally done by name. That is,
2334         applications ask the message bus to start some program that will own a
2335         well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2336         This implies a contract documented along with the name
2337         <literal>org.freedesktop.TextEditor</literal> for which objects
2338         the owner of that name will provide, and what interfaces those
2339         objects will have.
2340       </para>
2341       <para>
2342         To find an executable corresponding to a particular name, the bus daemon
2343         looks for <firstterm>service description files</firstterm>.  Service
2344         description files define a mapping from names to executables. Different
2345         kinds of message bus will look for these files in different places, see
2346         <xref linkend="message-bus-types"/>.
2347       </para>
2348       <para>
2349         [FIXME the file format should be much better specified than "similar to
2350         .desktop entries" esp. since desktop entries are already
2351         badly-specified. ;-)] Service description files have the ".service" file
2352         extension. The message bus will only load service description files
2353         ending with .service; all other files will be ignored.  The file format
2354         is similar to that of <ulink
2355         url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2356         entries</ulink>. All service description files must be in UTF-8
2357         encoding. To ensure that there will be no name collisions, service files
2358         must be namespaced using the same mechanism as messages and service
2359         names.
2360
2361         <figure>
2362           <title>Example service description file</title>
2363           <programlisting>
2364             # Sample service description file
2365             [D-BUS Service]
2366             Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2367             Exec=/usr/libexec/gconfd-2
2368           </programlisting>
2369         </figure>
2370       </para>
2371       <para>
2372         When an application asks to start a service by name, the bus daemon tries to
2373         find a service that will own that name. It then tries to spawn the
2374         executable associated with it. If this fails, it will report an
2375         error. [FIXME what happens if two .service files offer the same service;
2376         what kind of error is reported, should we have a way for the client to
2377         choose one?]
2378       </para>
2379       <para>
2380         The executable launched will have the environment variable
2381         <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2382         message bus so it can connect and request the appropriate names.
2383       </para>
2384       <para>
2385         The executable being launched may want to know whether the message bus
2386         starting it is one of the well-known message buses (see <xref
2387         linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
2388         the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2389         of the well-known buses. The currently-defined values for this variable
2390         are <literal>system</literal> for the systemwide message bus,
2391         and <literal>session</literal> for the per-login-session message
2392         bus. The new executable must still connect to the address given
2393         in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2394         resulting connection is to the well-known bus.
2395       </para>
2396       <para>
2397         [FIXME there should be a timeout somewhere, either specified
2398         in the .service file, by the client, or just a global value
2399         and if the client being activated fails to connect within that
2400         timeout, an error should be sent back.]
2401       </para>
2402     </sect2>
2403
2404     <sect2 id="message-bus-types">
2405       <title>Well-known Message Bus Instances</title>
2406       <para>
2407         Two standard message bus instances are defined here, along with how
2408         to locate them and where their service files live.
2409       </para>
2410       <sect3 id="message-bus-types-login">
2411         <title>Login session message bus</title>
2412         <para>
2413           Each time a user logs in, a <firstterm>login session message
2414             bus</firstterm> may be started. All applications in the user's login
2415           session may interact with one another using this message bus.
2416         </para>
2417         <para>
2418           The address of the login session message bus is given
2419           in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2420           variable. If that variable is not set, applications may
2421           also try to read the address from the X Window System root
2422           window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2423           The root window property must have type <literal>STRING</literal>.
2424           The environment variable should have precedence over the
2425           root window property.
2426         </para>
2427         <para>
2428           [FIXME specify location of .service files, probably using
2429           DESKTOP_DIRS etc. from basedir specification, though login session
2430           bus is not really desktop-specific]
2431         </para>
2432       </sect3>
2433       <sect3 id="message-bus-types-system">
2434         <title>System message bus</title>
2435         <para>
2436           A computer may have a <firstterm>system message bus</firstterm>,
2437           accessible to all applications on the system. This message bus may be
2438           used to broadcast system events, such as adding new hardware devices,
2439           changes in the printer queue, and so forth.
2440         </para>
2441         <para>
2442           The address of the system message bus is given
2443           in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2444           variable. If that variable is not set, applications should try
2445           to connect to the well-known address
2446           <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2447           <footnote>
2448             <para>
2449               The D-BUS reference implementation actually honors the
2450               <literal>$(localstatedir)</literal> configure option
2451               for this address, on both client and server side.
2452             </para>
2453           </footnote>
2454         </para>
2455         <para>
2456           [FIXME specify location of system bus .service files]
2457         </para>
2458       </sect3>
2459     </sect2>
2460
2461     <sect2 id="message-bus-messages">
2462       <title>Message Bus Messages</title>
2463       <para>
2464         The special message bus name <literal>org.freedesktop.DBus</literal>
2465         responds to a number of additional messages.
2466       </para>
2467
2468       <sect3 id="bus-messages-hello">
2469         <title><literal>org.freedesktop.DBus.Hello</literal></title>
2470         <para>
2471           As a method:
2472           <programlisting>
2473             STRING Hello ()
2474           </programlisting>
2475           Reply arguments:
2476           <informaltable>
2477             <tgroup cols="3">
2478               <thead>
2479                 <row>
2480                   <entry>Argument</entry>
2481                   <entry>Type</entry>
2482                   <entry>Description</entry>
2483                 </row>
2484               </thead>
2485               <tbody>
2486                 <row>
2487                   <entry>0</entry>
2488                   <entry>STRING</entry>
2489                   <entry>Unique name assigned to the connection</entry>
2490                 </row>
2491               </tbody>
2492             </tgroup>
2493           </informaltable>
2494         </para>
2495         <para>
2496           Before an application is able to send messages to other applications
2497           it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2498           to the message bus to obtain a unique name. If an application without
2499           a unique name tries to send a message to another application, or a
2500           message to the message bus itself that isn't the
2501           <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2502           disconnected from the bus.
2503         </para>
2504         <para>
2505           There is no corresponding "disconnect" request; if a client wishes to
2506           disconnect from the bus, it simply closes the socket (or other
2507           communication channel).
2508         </para>
2509       </sect3>
2510       <sect3 id="bus-messages-list-names">
2511         <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2512         <para>
2513           As a method:
2514           <programlisting>
2515             ARRAY of STRING ListNames ()
2516           </programlisting>
2517           Reply arguments:
2518           <informaltable>
2519             <tgroup cols="3">
2520               <thead>
2521                 <row>
2522                   <entry>Argument</entry>
2523                   <entry>Type</entry>
2524                   <entry>Description</entry>
2525                 </row>
2526               </thead>
2527               <tbody>
2528                 <row>
2529                   <entry>0</entry>
2530                   <entry>ARRAY of STRING</entry>
2531                   <entry>Array of strings where each string is a bus name</entry>
2532                 </row>
2533               </tbody>
2534             </tgroup>
2535           </informaltable>
2536         </para>
2537         <para>
2538           Returns a list of all currently-owned names on the bus.
2539         </para>
2540       </sect3>
2541       <sect3 id="bus-messages-name-exists">
2542         <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2543         <para>
2544           As a method:
2545           <programlisting>
2546             BOOLEAN NameHasOwner (in STRING name)
2547           </programlisting>
2548           Message arguments:
2549           <informaltable>
2550             <tgroup cols="3">
2551               <thead>
2552                 <row>
2553                   <entry>Argument</entry>
2554                   <entry>Type</entry>
2555                   <entry>Description</entry>
2556                 </row>
2557               </thead>
2558               <tbody>
2559                 <row>
2560                   <entry>0</entry>
2561                   <entry>STRING</entry>
2562                   <entry>Name to check</entry>
2563                 </row>
2564               </tbody>
2565             </tgroup>
2566           </informaltable>
2567           Reply arguments:
2568           <informaltable>
2569             <tgroup cols="3">
2570               <thead>
2571                 <row>
2572                   <entry>Argument</entry>
2573                   <entry>Type</entry>
2574                   <entry>Description</entry>
2575                 </row>
2576               </thead>
2577               <tbody>
2578                 <row>
2579                   <entry>0</entry>
2580                   <entry>BOOLEAN</entry>
2581                   <entry>Return value, true if the name exists</entry>
2582                 </row>
2583               </tbody>
2584             </tgroup>
2585           </informaltable>
2586         </para>
2587         <para>
2588           Checks if the specified name exists (currently has an owner).
2589         </para>
2590       </sect3>
2591
2592       <sect3 id="bus-messages-name-owner-changed">
2593         <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
2594         <para>
2595           This is a signal:
2596           <programlisting>
2597             NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
2598           </programlisting>
2599           Message arguments:
2600           <informaltable>
2601             <tgroup cols="3">
2602               <thead>
2603                 <row>
2604                   <entry>Argument</entry>
2605                   <entry>Type</entry>
2606                   <entry>Description</entry>
2607                 </row>
2608               </thead>
2609               <tbody>
2610                 <row>
2611                   <entry>0</entry>
2612                   <entry>STRING</entry>
2613                   <entry>Name with a new owner</entry>
2614                 </row>
2615                 <row>
2616                   <entry>1</entry>
2617                   <entry>STRING</entry>
2618                   <entry>Old owner or empty string if none</entry>
2619                 </row>
2620                 <row>
2621                   <entry>2</entry>
2622                   <entry>STRING</entry>
2623                   <entry>New owner or empty string if none</entry>
2624                 </row>
2625               </tbody>
2626             </tgroup>
2627           </informaltable>
2628         </para>
2629         <para>
2630           This signal indicates that the owner of a name has changed.
2631           It's also the signal to use to detect the appearance of
2632           new names on the bus.
2633         </para>
2634       </sect3>
2635       <sect3 id="bus-messages-name-lost">
2636         <title><literal>org.freedesktop.DBus.NameLost</literal></title>
2637         <para>
2638           This is a signal:
2639           <programlisting>
2640             NameLost (STRING name)
2641           </programlisting>
2642           Message arguments:
2643           <informaltable>
2644             <tgroup cols="3">
2645               <thead>
2646                 <row>
2647                   <entry>Argument</entry>
2648                   <entry>Type</entry>
2649                   <entry>Description</entry>
2650                 </row>
2651               </thead>
2652               <tbody>
2653                 <row>
2654                   <entry>0</entry>
2655                   <entry>STRING</entry>
2656                   <entry>Name which was lost</entry>
2657                 </row>
2658               </tbody>
2659             </tgroup>
2660           </informaltable>
2661         </para>
2662         <para>
2663           This signal is sent to a specific application when it loses
2664           ownership of a name.
2665         </para>
2666       </sect3>
2667
2668       <sect3 id="bus-messages-name-acquired">
2669         <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
2670         <para>
2671           This is a signal:
2672           <programlisting>
2673             NameAcquired (STRING name)
2674           </programlisting>
2675           Message arguments:
2676           <informaltable>
2677             <tgroup cols="3">
2678               <thead>
2679                 <row>
2680                   <entry>Argument</entry>
2681                   <entry>Type</entry>
2682                   <entry>Description</entry>
2683                 </row>
2684               </thead>
2685               <tbody>
2686                 <row>
2687                   <entry>0</entry>
2688                   <entry>STRING</entry>
2689                   <entry>Name which was acquired</entry>
2690                 </row>
2691               </tbody>
2692             </tgroup>
2693           </informaltable>
2694         </para>
2695         <para>
2696           This signal is sent to a specific application when it gains
2697           ownership of a name.
2698         </para>
2699       </sect3>
2700
2701       <sect3 id="bus-messages-start-service-by-name">
2702         <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
2703         <para>
2704           As a method:
2705           <programlisting>
2706             UINT32 StartServiceByName (in STRING name, in UINT32 flags)
2707           </programlisting>
2708           Message arguments:
2709           <informaltable>
2710             <tgroup cols="3">
2711               <thead>
2712                 <row>
2713                   <entry>Argument</entry>
2714                   <entry>Type</entry>
2715                   <entry>Description</entry>
2716                 </row>
2717               </thead>
2718               <tbody>
2719                 <row>
2720                   <entry>0</entry>
2721                   <entry>STRING</entry>
2722                   <entry>Name of the service to start</entry>
2723                 </row>
2724                 <row>
2725                   <entry>1</entry>
2726                   <entry>UINT32</entry>
2727                   <entry>Flags (currently not used)</entry>
2728                 </row>
2729               </tbody>
2730             </tgroup>
2731           </informaltable>
2732         Reply arguments:
2733         <informaltable>
2734           <tgroup cols="3">
2735             <thead>
2736               <row>
2737                 <entry>Argument</entry>
2738                 <entry>Type</entry>
2739                 <entry>Description</entry>
2740               </row>
2741             </thead>
2742             <tbody>
2743               <row>
2744                 <entry>0</entry>
2745                 <entry>UINT32</entry>
2746                 <entry>Return value</entry>
2747               </row>
2748             </tbody>
2749           </tgroup>
2750         </informaltable>
2751           Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
2752
2753         </para>
2754         <para>
2755           The return value can be one of the following values:
2756           <informaltable>
2757             <tgroup cols="3">
2758               <thead>
2759                 <row>
2760                   <entry>Identifier</entry>
2761                   <entry>Value</entry>
2762                   <entry>Description</entry>
2763                 </row>
2764               </thead>
2765               <tbody>
2766                 <row>
2767                   <entry>DBUS_START_REPLY_SUCCESS</entry>
2768                   <entry>1</entry>
2769                   <entry>The service was successfully started.</entry>
2770                 </row>
2771                 <row>
2772                   <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
2773                   <entry>2</entry>
2774                   <entry>A connection already owns the given name.</entry>
2775                 </row>
2776               </tbody>
2777              </tgroup>
2778            </informaltable>
2779         </para>
2780
2781       </sect3>
2782
2783       <sect3 id="bus-messages-get-name-owner">
2784         <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
2785         <para>
2786           As a method:
2787           <programlisting>
2788             STRING GetNameOwner (in STRING name)
2789           </programlisting>
2790           Message arguments:
2791           <informaltable>
2792             <tgroup cols="3">
2793               <thead>
2794                 <row>
2795                   <entry>Argument</entry>
2796                   <entry>Type</entry>
2797                   <entry>Description</entry>
2798                 </row>
2799               </thead>
2800               <tbody>
2801                 <row>
2802                   <entry>0</entry>
2803                   <entry>STRING</entry>
2804                   <entry>Name to get the owner of</entry>
2805                 </row>
2806               </tbody>
2807             </tgroup>
2808           </informaltable>
2809         Reply arguments:
2810         <informaltable>
2811           <tgroup cols="3">
2812             <thead>
2813               <row>
2814                 <entry>Argument</entry>
2815                 <entry>Type</entry>
2816                 <entry>Description</entry>
2817               </row>
2818             </thead>
2819             <tbody>
2820               <row>
2821                 <entry>0</entry>
2822                 <entry>STRING</entry>
2823                 <entry>Return value, a unique connection name</entry>
2824               </row>
2825             </tbody>
2826           </tgroup>
2827         </informaltable>
2828         Returns the unique connection name of the primary owner of the name
2829         given. If the requested name doesn't have an owner, returns a
2830         <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
2831        </para>
2832       </sect3>
2833
2834       <sect3 id="bus-messages-get-connection-unix-user">
2835         <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
2836         <para>
2837           As a method:
2838           <programlisting>
2839             UINT32 GetConnectionUnixUser (in STRING connection_name)
2840           </programlisting>
2841           Message arguments:
2842           <informaltable>
2843             <tgroup cols="3">
2844               <thead>
2845                 <row>
2846                   <entry>Argument</entry>
2847                   <entry>Type</entry>
2848                   <entry>Description</entry>
2849                 </row>
2850               </thead>
2851               <tbody>
2852                 <row>
2853                   <entry>0</entry>
2854                   <entry>STRING</entry>
2855                   <entry>Name of the connection to query</entry>
2856                 </row>
2857               </tbody>
2858             </tgroup>
2859           </informaltable>
2860         Reply arguments:
2861         <informaltable>
2862           <tgroup cols="3">
2863             <thead>
2864               <row>
2865                 <entry>Argument</entry>
2866                 <entry>Type</entry>
2867                 <entry>Description</entry>
2868               </row>
2869             </thead>
2870             <tbody>
2871               <row>
2872                 <entry>0</entry>
2873                 <entry>UINT32</entry>
2874                 <entry>unix user id</entry>
2875               </row>
2876             </tbody>
2877           </tgroup>
2878         </informaltable>
2879         Returns the unix uid of the process connected to the server. If unable to
2880         determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
2881         error is returned.
2882        </para>
2883       </sect3>
2884
2885     </sect2>
2886
2887   </sect1>
2888 <!--
2889   <appendix id="implementation-notes">
2890     <title>Implementation notes</title>
2891     <sect1 id="implementation-notes-subsection">
2892       <title></title>
2893       <para>
2894       </para>
2895     </sect1>
2896   </appendix>
2897 -->
2898
2899   <glossary><title>Glossary</title>
2900     <para>
2901       This glossary defines some of the terms used in this specification.
2902     </para>
2903
2904     <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
2905       <glossdef>
2906         <para>
2907           The message bus maintains an association between names and
2908           connections. (Normally, there's one connection per application.)  A
2909           bus name is simply an identifier used to locate connections. For
2910           example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
2911           name might be used to send a message to a screensaver from Yoyodyne
2912           Corporation.  An application is said to <firstterm>own</firstterm> a
2913           name if the message bus has associated the application's connection
2914           with the name.  Names may also have <firstterm>queued
2915           owners</firstterm> (see <xref linkend="term-queued-owner"/>).
2916             The bus assigns a unique name to each connection,
2917             see <xref linkend="term-unique-name"/>. Other names
2918               can be thought of as "well-known names" and are
2919               used to find applications that offer specific functionality.
2920         </para>
2921       </glossdef>
2922     </glossentry>
2923
2924     <glossentry id="term-message"><glossterm>Message</glossterm>
2925       <glossdef>
2926         <para>
2927           A message is the atomic unit of communication via the D-BUS
2928           protocol. It consists of a <firstterm>header</firstterm> and a
2929           <firstterm>body</firstterm>; the body is made up of
2930           <firstterm>arguments</firstterm>.
2931         </para>
2932       </glossdef>
2933     </glossentry>
2934
2935     <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
2936       <glossdef>
2937         <para>
2938           The message bus is a special application that forwards
2939           or routes messages between a group of applications
2940           connected to the message bus. It also manages
2941           <firstterm>names</firstterm> used for routing
2942           messages.
2943         </para>
2944       </glossdef>
2945     </glossentry>
2946
2947     <glossentry id="term-name"><glossterm>Name</glossterm>
2948       <glossdef>
2949         <para>
2950           See <xref linkend="term-bus-name"/>. "Name" may
2951             also be used to refer to some of the other names
2952             in D-BUS, such as interface names.
2953         </para>
2954       </glossdef>
2955     </glossentry>
2956
2957     <glossentry id="namespace"><glossterm>Namespace</glossterm>
2958       <glossdef>
2959         <para>
2960           Used to prevent collisions when defining new interfaces or bus
2961           names. The convention used is the same one Java uses for defining
2962           classes: a reversed domain name.
2963         </para>
2964       </glossdef>
2965     </glossentry>
2966
2967     <glossentry id="term-object"><glossterm>Object</glossterm>
2968       <glossdef>
2969         <para>
2970           Each application contains <firstterm>objects</firstterm>, which have
2971           <firstterm>interfaces</firstterm> and
2972           <firstterm>methods</firstterm>. Objects are referred to by a name,
2973           called a <firstterm>path</firstterm>.
2974         </para>
2975       </glossdef>
2976     </glossentry>
2977
2978     <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
2979       <glossdef>
2980         <para>
2981           An application talking directly to another application, without going
2982           through a message bus. One-to-one connections may be "peer to peer" or
2983           "client to server." The D-BUS protocol has no concept of client
2984           vs. server after a connection has authenticated; the flow of messages
2985           is symmetrical (full duplex).
2986         </para>
2987       </glossdef>
2988     </glossentry>
2989
2990     <glossentry id="term-path"><glossterm>Path</glossterm>
2991       <glossdef>
2992         <para>
2993           Object references (object names) in D-BUS are organized into a
2994           filesystem-style hierarchy, so each object is named by a path. As in
2995           LDAP, there's no difference between "files" and "directories"; a path
2996           can refer to an object, while still having child objects below it.
2997         </para>
2998       </glossdef>
2999     </glossentry>
3000
3001     <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
3002       <glossdef>
3003         <para>
3004           Each bus name has a primary owner; messages sent to the name go to the
3005           primary owner. However, certain names also maintain a queue of
3006           secondary owners "waiting in the wings." If the primary owner releases
3007           the name, then the first secondary owner in the queue automatically
3008           becomes the new owner of the name.
3009         </para>
3010       </glossdef>
3011     </glossentry>
3012
3013     <glossentry id="term-service"><glossterm>Service</glossterm>
3014       <glossdef>
3015         <para>
3016           A service is an executable that can be launched by the bus daemon.
3017           Services normally guarantee some particular features, for example they
3018           may guarantee that they will request a specific name such as
3019           "org.freedesktop.Screensaver", have a singleton object
3020           "/org/freedesktop/Application", and that object will implement the
3021           interface "org.freedesktop.ScreensaverControl".
3022         </para>
3023       </glossdef>
3024     </glossentry>
3025
3026     <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
3027       <glossdef>
3028         <para>
3029           ".service files" tell the bus about service applications that can be
3030           launched (see <xref linkend="term-service"/>). Most importantly they
3031           provide a mapping from bus names to services that will request those
3032             names when they start up.
3033         </para>
3034       </glossdef>
3035     </glossentry>
3036
3037     <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
3038       <glossdef>
3039         <para>
3040           The special name automatically assigned to each connection by the
3041           message bus. This name will never change owner, and will be unique
3042           (never reused during the lifetime of the message bus).
3043           It will begin with a ':' character.
3044         </para>
3045       </glossdef>
3046     </glossentry>
3047
3048   </glossary>
3049 </article>
3050