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             In converting from native APIs to D-BUS, it is perhaps nice to
1123             map D-BUS naming conventions ("FooBar") to native conventions
1124             such as "fooBar" or "foo_bar" automatically. This is OK
1125             as long as you can say that the native API is one that
1126             was specifically written for D-BUS. It makes the most sense
1127             when writing object implementations that will be exported
1128             over the bus. Object proxies used to invoke remote D-BUS
1129             objects probably need the ability to call any D-BUS method,
1130             and thus a magic name mapping like this could be a problem.
1131           </para>
1132           <para>
1133             This specification doesn't require anything of native API bindings;
1134             the preceding is only a suggested convention for consistency
1135             among bindings.
1136           </para>
1137         </sect4>
1138       </sect3>
1139
1140       <sect3 id="message-protocol-types-signal">
1141         <title>Signal Emission</title>
1142         <para>
1143           Unlike method calls, signal emissions have no replies.
1144           A signal emission is simply a single message of type <literal>SIGNAL</literal>.
1145           It must have three header fields: <literal>PATH</literal> giving the object
1146           the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
1147           the fully-qualified name of the signal.
1148         </para>
1149       </sect3>
1150
1151       <sect3 id="message-protocol-types-errors">
1152         <title>Errors</title>
1153         <para>
1154           Messages of type <literal>ERROR</literal> are most commonly replies
1155           to a <literal>METHOD_CALL</literal>, but may be returned in reply
1156           to any kind of message. The message bus for example
1157           will return an <literal>ERROR</literal> in reply to a signal emission if
1158           the bus does not have enough memory to send the signal.
1159         </para>
1160         <para>
1161           An <literal>ERROR</literal> may have any arguments, but if the first
1162           argument is a <literal>STRING</literal>, it must be an error message.
1163           The error message may be logged or shown to the user
1164           in some way.
1165         </para>
1166       </sect3>
1167
1168       <sect3 id="message-protocol-types-notation">
1169         <title>Notation in this document</title>
1170         <para>
1171           This document uses a simple pseudo-IDL to describe particular method
1172           calls and signals. Here is an example of a method call:
1173           <programlisting>
1174             org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
1175                                                      out UINT32 resultcode)
1176           </programlisting>
1177           This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
1178           <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
1179           is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
1180           characters so it's known that the last part of the name in
1181           the "IDL" is the member name.
1182         </para>
1183         <para>
1184           In C++ that might end up looking like this:
1185           <programlisting>
1186             unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
1187                                                                      unsigned int flags);
1188           </programlisting>
1189           or equally valid, the return value could be done as an argument:
1190           <programlisting>
1191             void org::freedesktop::DBus::StartServiceByName (const char   *name,
1192                                                              unsigned int  flags,
1193                                                              unsigned int *resultcode);
1194           </programlisting>
1195           It's really up to the API designer how they want to make
1196           this look. You could design an API where the namespace wasn't used
1197           in C++, using STL or Qt, using varargs, or whatever you wanted.
1198         </para>
1199         <para>
1200           Signals are written as follows:
1201           <programlisting>
1202             org.freedesktop.DBus.NameLost (STRING name)
1203           </programlisting>
1204           Signals don't specify "in" vs. "out" because only
1205           a single direction is possible.
1206         </para>
1207         <para>
1208           It isn't especially encouraged to use this lame pseudo-IDL in actual
1209           API implementations; you might use the native notation for the
1210           language you're using, or you might use COM or CORBA IDL, for example.
1211         </para>
1212       </sect3>
1213     </sect2>
1214
1215   </sect1>
1216
1217   <sect1 id="auth-protocol">
1218     <title>Authentication Protocol</title>
1219     <para>
1220       Before the flow of messages begins, two applications must
1221       authenticate. A simple plain-text protocol is used for
1222       authentication; this protocol is a SASL profile, and maps fairly
1223       directly from the SASL specification. The message encoding is
1224       NOT used here, only plain text messages.
1225     </para>
1226     <para>
1227       In examples, "C:" and "S:" indicate lines sent by the client and
1228       server respectively.
1229     </para>
1230     <sect2 id="auth-protocol-overview">
1231       <title>Protocol Overview</title>
1232       <para>
1233         The protocol is a line-based protocol, where each line ends with
1234         \r\n. Each line begins with an all-caps ASCII command name containing
1235         only the character range [A-Z], a space, then any arguments for the
1236         command, then the \r\n ending the line. The protocol is
1237         case-sensitive. All bytes must be in the ASCII character set.
1238
1239         Commands from the client to the server are as follows:
1240
1241         <itemizedlist>
1242           <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
1243           <listitem><para>CANCEL</para></listitem>
1244           <listitem><para>BEGIN</para></listitem>
1245           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1246           <listitem><para>ERROR [human-readable error explanation]</para></listitem>
1247         </itemizedlist>
1248
1249         From server to client are as follows:
1250
1251         <itemizedlist>
1252           <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
1253           <listitem><para>OK</para></listitem>
1254           <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
1255           <listitem><para>ERROR</para></listitem>
1256         </itemizedlist>
1257       </para>
1258     </sect2>
1259     <sect2 id="auth-nul-byte">
1260       <title>Special credentials-passing nul byte</title>
1261       <para>
1262         Immediately after connecting to the server, the client must send a
1263         single nul byte. This byte may be accompanied by credentials
1264         information on some operating systems that use sendmsg() with
1265         SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
1266         sockets. However, the nul byte MUST be sent even on other kinds of
1267         socket, and even on operating systems that do not require a byte to be
1268         sent in order to transmit credentials. The text protocol described in
1269         this document begins after the single nul byte. If the first byte
1270         received from the client is not a nul byte, the server may disconnect
1271         that client.
1272       </para>
1273       <para>
1274         A nul byte in any context other than the initial byte is an error;
1275         the protocol is ASCII-only.
1276       </para>
1277       <para>
1278         The credentials sent along with the nul byte may be used with the
1279         SASL mechanism EXTERNAL.
1280       </para>
1281     </sect2>
1282     <sect2 id="auth-command-auth">
1283       <title>AUTH command</title>
1284       <para>
1285         If an AUTH command has no arguments, it is a request to list
1286         available mechanisms. The server SHOULD respond with a REJECTED
1287         command listing the mechanisms it understands.
1288       </para>
1289       <para>
1290         If an AUTH command specifies a mechanism, and the server supports
1291         said mechanism, the server SHOULD begin exchanging SASL
1292         challenge-response data with the client using DATA commands.
1293       </para>
1294       <para>
1295         If the server does not support the mechanism given in the AUTH
1296         command, it SHOULD send a REJECTED command listing the mechanisms
1297         it does support.
1298       </para>
1299       <para>
1300         If the [initial-response] argument is provided, it is intended for
1301         use with mechanisms that have no initial challenge (or an empty
1302         initial challenge), as if it were the argument to an initial DATA
1303         command. If the selected mechanism has an initial challenge, the
1304         server should reject authentication by sending REJECTED.
1305       </para>
1306       <para>
1307         If authentication succeeds after exchanging DATA commands,
1308         an OK command should be sent to the client.
1309       </para>
1310       <para>
1311         The first octet received by the client after the \r\n of the OK
1312         command MUST be the first octet of the authenticated/encrypted
1313         stream of D-BUS messages.
1314       </para>
1315       <para>
1316         The first octet received by the server after the \r\n of the BEGIN
1317         command from the client MUST be the first octet of the
1318         authenticated/encrypted stream of D-BUS messages.
1319       </para>
1320     </sect2>
1321     <sect2 id="auth-command-cancel">
1322       <title>CANCEL Command</title>
1323       <para>
1324         At any time up to sending the BEGIN command, the client may send a
1325         CANCEL command. On receiving the CANCEL command, the server MUST
1326         send a REJECTED command and abort the current authentication
1327         exchange.
1328       </para>
1329     </sect2>
1330     <sect2 id="auth-command-data">
1331       <title>DATA Command</title>
1332       <para>
1333         The DATA command may come from either client or server, and simply
1334         contains a hex-encoded block of data to be interpreted
1335         according to the SASL mechanism in use.
1336       </para>
1337       <para>
1338         Some SASL mechanisms support sending an "empty string";
1339         FIXME we need some way to do this.
1340       </para>
1341     </sect2>
1342     <sect2 id="auth-command-begin">
1343       <title>BEGIN Command</title>
1344       <para>
1345         The BEGIN command acknowledges that the client has received an
1346         OK command from the server, and that the stream of messages
1347         is about to begin.
1348       </para>
1349       <para>
1350         The first octet received by the server after the \r\n of the BEGIN
1351         command from the client MUST be the first octet of the
1352         authenticated/encrypted stream of D-BUS messages.
1353       </para>
1354     </sect2>
1355     <sect2 id="auth-command-rejected">
1356       <title>REJECTED Command</title>
1357       <para>
1358         The REJECTED command indicates that the current authentication
1359         exchange has failed, and further exchange of DATA is inappropriate.
1360         The client would normally try another mechanism, or try providing
1361         different responses to challenges.
1362       </para><para>
1363         Optionally, the REJECTED command has a space-separated list of
1364         available auth mechanisms as arguments. If a server ever provides
1365         a list of supported mechanisms, it MUST provide the same list
1366         each time it sends a REJECTED message. Clients are free to
1367         ignore all lists received after the first.
1368       </para>
1369     </sect2>
1370     <sect2 id="auth-command-ok">
1371       <title>OK Command</title>
1372       <para>
1373         The OK command indicates that the client has been authenticated,
1374         and that further communication will be a stream of D-BUS messages
1375         (optionally encrypted, as negotiated) rather than this protocol.
1376       </para>
1377       <para>
1378         The first octet received by the client after the \r\n of the OK
1379         command MUST be the first octet of the authenticated/encrypted
1380         stream of D-BUS messages.
1381       </para>
1382       <para>
1383         The client MUST respond to the OK command by sending a BEGIN
1384         command, followed by its stream of messages, or by disconnecting.
1385         The server MUST NOT accept additional commands using this protocol
1386         after the OK command has been sent.
1387       </para>
1388     </sect2>
1389     <sect2 id="auth-command-error">
1390       <title>ERROR Command</title>
1391       <para>
1392         The ERROR command indicates that either server or client did not
1393         know a command, does not accept the given command in the current
1394         context, or did not understand the arguments to the command. This
1395         allows the protocol to be extended; a client or server can send a
1396         command present or permitted only in new protocol versions, and if
1397         an ERROR is received instead of an appropriate response, fall back
1398         to using some other technique.
1399       </para>
1400       <para>
1401         If an ERROR is sent, the server or client that sent the
1402         error MUST continue as if the command causing the ERROR had never been
1403         received. However, the the server or client receiving the error
1404         should try something other than whatever caused the error;
1405         if only canceling/rejecting the authentication.
1406       </para>
1407       <para>
1408         If the D-BUS protocol changes incompatibly at some future time,
1409         applications implementing the new protocol would probably be able to
1410         check for support of the new protocol by sending a new command and
1411         receiving an ERROR from applications that don't understand it. Thus the
1412         ERROR feature of the auth protocol is an escape hatch that lets us
1413         negotiate extensions or changes to the D-BUS protocol in the future.
1414       </para>
1415     </sect2>
1416     <sect2 id="auth-examples">
1417       <title>Authentication examples</title>
1418
1419       <para>
1420         <figure>
1421           <title>Example of successful magic cookie authentication</title>
1422           <programlisting>
1423             (MAGIC_COOKIE is a made up mechanism)
1424
1425             C: AUTH MAGIC_COOKIE 3138363935333137393635383634
1426             S: OK
1427             C: BEGIN
1428           </programlisting>
1429         </figure>
1430         <figure>
1431           <title>Example of finding out mechanisms then picking one</title>
1432           <programlisting>
1433             C: AUTH
1434             S: REJECTED KERBEROS_V4 SKEY
1435             C: AUTH SKEY 7ab83f32ee
1436             S: DATA 8799cabb2ea93e
1437             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1438             S: OK
1439             C: BEGIN
1440           </programlisting>
1441         </figure>
1442         <figure>
1443           <title>Example of client sends unknown command then falls back to regular auth</title>
1444           <programlisting>
1445             C: FOOBAR
1446             S: ERROR
1447             C: AUTH MAGIC_COOKIE 3736343435313230333039
1448             S: OK
1449             C: BEGIN
1450           </programlisting>
1451         </figure>
1452         <figure>
1453           <title>Example of server doesn't support initial auth mechanism</title>
1454           <programlisting>
1455             C: AUTH MAGIC_COOKIE 3736343435313230333039
1456             S: REJECTED KERBEROS_V4 SKEY
1457             C: AUTH SKEY 7ab83f32ee
1458             S: DATA 8799cabb2ea93e
1459             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1460             S: OK
1461             C: BEGIN
1462           </programlisting>
1463         </figure>
1464         <figure>
1465           <title>Example of wrong password or the like followed by successful retry</title>
1466           <programlisting>
1467             C: AUTH MAGIC_COOKIE 3736343435313230333039
1468             S: REJECTED KERBEROS_V4 SKEY
1469             C: AUTH SKEY 7ab83f32ee
1470             S: DATA 8799cabb2ea93e
1471             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1472             S: REJECTED
1473             C: AUTH SKEY 7ab83f32ee
1474             S: DATA 8799cabb2ea93e
1475             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1476             S: OK
1477             C: BEGIN
1478           </programlisting>
1479         </figure>
1480         <figure>
1481           <title>Example of skey cancelled and restarted</title>
1482           <programlisting>
1483             C: AUTH MAGIC_COOKIE 3736343435313230333039
1484             S: REJECTED KERBEROS_V4 SKEY
1485             C: AUTH SKEY 7ab83f32ee
1486             S: DATA 8799cabb2ea93e
1487             C: CANCEL
1488             S: REJECTED
1489             C: AUTH SKEY 7ab83f32ee
1490             S: DATA 8799cabb2ea93e
1491             C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
1492             S: OK
1493             C: BEGIN
1494           </programlisting>
1495         </figure>
1496       </para>
1497     </sect2>
1498     <sect2 id="auth-states">
1499       <title>Authentication state diagrams</title>
1500
1501       <para>
1502         This section documents the auth protocol in terms of
1503         a state machine for the client and the server. This is
1504         probably the most robust way to implement the protocol.
1505       </para>
1506
1507       <sect3 id="auth-states-client">
1508         <title>Client states</title>
1509
1510         <para>
1511           To more precisely describe the interaction between the
1512           protocol state machine and the authentication mechanisms the
1513           following notation is used: MECH(CHALL) means that the
1514           server challenge CHALL was fed to the mechanism MECH, which
1515           returns one of
1516
1517           <itemizedlist>
1518             <listitem>
1519               <para>
1520                 CONTINUE(RESP) means continue the auth conversation
1521                 and send RESP as the response to the server;
1522               </para>
1523             </listitem>
1524
1525             <listitem>
1526               <para>
1527                 OK(RESP) means that after sending RESP to the server
1528                 the client side of the auth conversation is finished
1529                 and the server should return "OK";
1530               </para>
1531             </listitem>
1532
1533             <listitem>
1534               <para>
1535                 ERROR means that CHALL was invalid and could not be
1536                 processed.
1537               </para>
1538             </listitem>
1539           </itemizedlist>
1540
1541           Both RESP and CHALL may be empty.
1542         </para>
1543
1544         <para>
1545           The Client starts by getting an initial response from the
1546           default mechanism and sends AUTH MECH RESP, or AUTH MECH if
1547           the mechanism did not provide an initial response.  If the
1548           mechanism returns CONTINUE, the client starts in state
1549           <emphasis>WaitingForData</emphasis>, if the mechanism
1550           returns OK the client starts in state
1551           <emphasis>WaitingForOK</emphasis>.
1552         </para>
1553
1554         <para>
1555           The client should keep track of available mechanisms and
1556           which it mechanisms it has already attempted. This list is
1557           used to decide which AUTH command to send. When the list is
1558           exhausted, the client should give up and close the
1559           connection.
1560         </para>
1561
1562         <formalpara>
1563           <title><emphasis>WaitingForData</emphasis></title>
1564           <para>
1565             <itemizedlist>
1566               <listitem>
1567                 <para>
1568                   Receive DATA CHALL
1569                   <simplelist>
1570                     <member>
1571                       MECH(CHALL) returns CONTINUE(RESP) &rarr; send
1572                       DATA RESP, goto
1573                       <emphasis>WaitingForData</emphasis>
1574                     </member>
1575
1576                     <member>
1577                       MECH(CHALL) returns OK(RESP) &rarr; send DATA
1578                       RESP, goto <emphasis>WaitingForOK</emphasis>
1579                     </member>
1580
1581                     <member>
1582                       MECH(CHALL) returns ERROR &rarr; send ERROR
1583                       [msg], goto <emphasis>WaitingForData</emphasis>
1584                     </member>
1585                   </simplelist>
1586                 </para>
1587               </listitem>
1588
1589               <listitem>
1590                 <para>
1591                   Receive REJECTED [mechs] &rarr;
1592                   send AUTH [next mech], goto
1593                   WaitingForData or <emphasis>WaitingForOK</emphasis>
1594                 </para>
1595               </listitem>
1596               <listitem>
1597                 <para>
1598                   Receive ERROR &rarr; send
1599                   CANCEL, goto
1600                   <emphasis>WaitingForReject</emphasis>
1601                 </para>
1602               </listitem>
1603               <listitem>
1604                 <para>
1605                   Receive OK &rarr; send
1606                   BEGIN, terminate auth
1607                   conversation, authenticated
1608                 </para>
1609               </listitem>
1610               <listitem>
1611                 <para>
1612                   Receive anything else &rarr; send
1613                   ERROR, goto
1614                   <emphasis>WaitingForData</emphasis>
1615                 </para>
1616               </listitem>
1617             </itemizedlist>
1618           </para>
1619         </formalpara>
1620
1621         <formalpara>
1622           <title><emphasis>WaitingForOK</emphasis></title>
1623           <para>
1624             <itemizedlist>
1625               <listitem>
1626                 <para>
1627                   Receive OK &rarr; send BEGIN, terminate auth
1628                   conversation, <emphasis>authenticated</emphasis>
1629                 </para>
1630               </listitem>
1631               <listitem>
1632                 <para>
1633                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1634                   goto <emphasis>WaitingForData</emphasis> or
1635                   <emphasis>WaitingForOK</emphasis>
1636                 </para>
1637               </listitem>
1638
1639               <listitem>
1640                 <para>
1641                   Receive DATA &rarr; send CANCEL, goto
1642                   <emphasis>WaitingForReject</emphasis>
1643                 </para>
1644               </listitem>
1645
1646               <listitem>
1647                 <para>
1648                   Receive ERROR &rarr; send CANCEL, goto
1649                   <emphasis>WaitingForReject</emphasis>
1650                 </para>
1651               </listitem>
1652
1653               <listitem>
1654                 <para>
1655                   Receive anything else &rarr; send ERROR, goto
1656                   <emphasis>WaitingForOK</emphasis>
1657                 </para>
1658               </listitem>
1659             </itemizedlist>
1660           </para>
1661         </formalpara>
1662
1663         <formalpara>
1664           <title><emphasis>WaitingForReject</emphasis></title>
1665           <para>
1666             <itemizedlist>
1667               <listitem>
1668                 <para>
1669                   Receive REJECT [mechs] &rarr; send AUTH [next mech],
1670                   goto <emphasis>WaitingForData</emphasis> or
1671                   <emphasis>WaitingForOK</emphasis>
1672                 </para>
1673               </listitem>
1674
1675               <listitem>
1676                 <para>
1677                   Receive anything else &rarr; terminate auth
1678                   conversation, disconnect
1679                 </para>
1680               </listitem>
1681             </itemizedlist>
1682           </para>
1683         </formalpara>
1684
1685       </sect3>
1686
1687       <sect3 id="auth-states-server">
1688         <title>Server states</title>
1689
1690         <para>
1691           For the server MECH(RESP) means that the client response
1692           RESP was fed to the the mechanism MECH, which returns one of
1693
1694           <itemizedlist>
1695             <listitem>
1696               <para>
1697                 CONTINUE(CHALL) means continue the auth conversation and
1698                 send CHALL as the challenge to the client;
1699               </para>
1700             </listitem>
1701
1702             <listitem>
1703               <para>
1704                 OK means that the client has been successfully
1705                 authenticated;
1706               </para>
1707             </listitem>
1708
1709             <listitem>
1710               <para>
1711                 REJECT means that the client failed to authenticate or
1712                 there was an error in RESP.
1713               </para>
1714             </listitem>
1715           </itemizedlist>
1716
1717           The server starts out in state
1718           <emphasis>WaitingForAuth</emphasis>.  If the client is
1719           rejected too many times the server must disconnect the
1720           client.
1721         </para>
1722
1723         <formalpara>
1724           <title><emphasis>WaitingForAuth</emphasis></title>
1725           <para>
1726             <itemizedlist>
1727
1728               <listitem>
1729                 <para>
1730                   Receive AUTH &rarr; send REJECTED [mechs], goto
1731                   <emphasis>WaitingForAuth</emphasis>
1732                 </para>
1733               </listitem>
1734
1735               <listitem>
1736                 <para>
1737                   Receive AUTH MECH RESP
1738
1739                   <simplelist>
1740                     <member>
1741                       MECH not valid mechanism &rarr; send REJECTED
1742                       [mechs], goto
1743                       <emphasis>WaitingForAuth</emphasis>
1744                     </member>
1745
1746                     <member>
1747                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1748                       DATA CHALL, goto
1749                       <emphasis>WaitingForData</emphasis>
1750                     </member>
1751
1752                     <member>
1753                       MECH(RESP) returns OK &rarr; send OK, goto
1754                       <emphasis>WaitingForBegin</emphasis>
1755                     </member>
1756
1757                     <member>
1758                       MECH(RESP) returns REJECT &rarr; send REJECTED
1759                       [mechs], goto
1760                       <emphasis>WaitingForAuth</emphasis>
1761                     </member>
1762                   </simplelist>
1763                 </para>
1764               </listitem>
1765
1766               <listitem>
1767                 <para>
1768                   Receive BEGIN &rarr; terminate
1769                   auth conversation, disconnect
1770                 </para>
1771               </listitem>
1772
1773               <listitem>
1774                 <para>
1775                   Receive ERROR &rarr; send REJECTED [mechs], goto
1776                   <emphasis>WaitingForAuth</emphasis>
1777                 </para>
1778               </listitem>
1779
1780               <listitem>
1781                 <para>
1782                   Receive anything else &rarr; send
1783                   ERROR, goto
1784                   <emphasis>WaitingForAuth</emphasis>
1785                 </para>
1786               </listitem>
1787             </itemizedlist>
1788           </para>
1789         </formalpara>
1790
1791
1792         <formalpara>
1793           <title><emphasis>WaitingForData</emphasis></title>
1794           <para>
1795             <itemizedlist>
1796               <listitem>
1797                 <para>
1798                   Receive DATA RESP
1799                   <simplelist>
1800                     <member>
1801                       MECH(RESP) returns CONTINUE(CHALL) &rarr; send
1802                       DATA CHALL, goto
1803                       <emphasis>WaitingForData</emphasis>
1804                     </member>
1805
1806                     <member>
1807                       MECH(RESP) returns OK &rarr; send OK, goto
1808                       <emphasis>WaitingForBegin</emphasis>
1809                     </member>
1810
1811                     <member>
1812                       MECH(RESP) returns REJECT &rarr; send REJECTED
1813                       [mechs], goto
1814                       <emphasis>WaitingForAuth</emphasis>
1815                     </member>
1816                   </simplelist>
1817                 </para>
1818               </listitem>
1819
1820               <listitem>
1821                 <para>
1822                   Receive BEGIN &rarr; terminate auth conversation,
1823                   disconnect
1824                 </para>
1825               </listitem>
1826
1827               <listitem>
1828                 <para>
1829                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1830                   <emphasis>WaitingForAuth</emphasis>
1831                 </para>
1832               </listitem>
1833
1834               <listitem>
1835                 <para>
1836                   Receive ERROR &rarr; send REJECTED [mechs], goto
1837                   <emphasis>WaitingForAuth</emphasis>
1838                 </para>
1839               </listitem>
1840
1841               <listitem>
1842                 <para>
1843                   Receive anything else &rarr; send ERROR, goto
1844                   <emphasis>WaitingForData</emphasis>
1845                 </para>
1846               </listitem>
1847             </itemizedlist>
1848           </para>
1849         </formalpara>
1850
1851         <formalpara>
1852           <title><emphasis>WaitingForBegin</emphasis></title>
1853           <para>
1854             <itemizedlist>
1855               <listitem>
1856                 <para>
1857                   Receive BEGIN &rarr; terminate auth conversation,
1858                   client authenticated
1859                 </para>
1860               </listitem>
1861
1862               <listitem>
1863                 <para>
1864                   Receive CANCEL &rarr; send REJECTED [mechs], goto
1865                   <emphasis>WaitingForAuth</emphasis>
1866                 </para>
1867               </listitem>
1868
1869               <listitem>
1870                 <para>
1871                   Receive ERROR &rarr; send REJECTED [mechs], goto
1872                   <emphasis>WaitingForAuth</emphasis>
1873                 </para>
1874               </listitem>
1875
1876               <listitem>
1877                 <para>
1878                   Receive anything else &rarr; send ERROR, goto
1879                   <emphasis>WaitingForBegin</emphasis>
1880                 </para>
1881               </listitem>
1882             </itemizedlist>
1883           </para>
1884         </formalpara>
1885
1886       </sect3>
1887
1888     </sect2>
1889     <sect2 id="auth-mechanisms">
1890       <title>Authentication mechanisms</title>
1891       <para>
1892         This section describes some new authentication mechanisms.
1893         D-BUS also allows any standard SASL mechanism of course.
1894       </para>
1895       <sect3 id="auth-mechanisms-sha">
1896         <title>DBUS_COOKIE_SHA1</title>
1897         <para>
1898           The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
1899           has the ability to read a private file owned by the user being
1900           authenticated. If the client can prove that it has access to a secret
1901           cookie stored in this file, then the client is authenticated.
1902           Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
1903           directory.
1904         </para>
1905         <para>
1906           Authentication proceeds as follows:
1907           <itemizedlist>
1908             <listitem>
1909               <para>
1910                 The client sends the username it would like to authenticate
1911                 as.
1912               </para>
1913             </listitem>
1914             <listitem>
1915               <para>
1916                 The server sends the name of its "cookie context" (see below); a
1917                 space character; the integer ID of the secret cookie the client
1918                 must demonstrate knowledge of; a space character; then a
1919                 hex-encoded randomly-generated challenge string.
1920               </para>
1921             </listitem>
1922             <listitem>
1923               <para>
1924                 The client locates the cookie, and generates its own hex-encoded
1925                 randomly-generated challenge string.  The client then
1926                 concatentates the server's hex-encoded challenge, a ":"
1927                 character, its own hex-encoded challenge, another ":" character,
1928                 and the hex-encoded cookie.  It computes the SHA-1 hash of this
1929                 composite string.  It sends back to the server the client's
1930                 hex-encoded challenge string, a space character, and the SHA-1
1931                 hash.
1932               </para>
1933             </listitem>
1934             <listitem>
1935               <para>
1936                 The server generates the same concatenated string used by the
1937                 client and computes its SHA-1 hash. It compares the hash with
1938                 the hash received from the client; if the two hashes match, the
1939                 client is authenticated.
1940               </para>
1941             </listitem>
1942           </itemizedlist>
1943         </para>
1944         <para>
1945           Each server has a "cookie context," which is a name that identifies a
1946           set of cookies that apply to that server. A sample context might be
1947           "org_freedesktop_session_bus". Context names must be valid ASCII,
1948           nonzero length, and may not contain the characters slash ("/"),
1949           backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
1950           tab ("\t"), or period ("."). There is a default context,
1951           "org_freedesktop_general" that's used by servers that do not specify
1952           otherwise.
1953         </para>
1954         <para>
1955           Cookies are stored in a user's home directory, in the directory
1956           <filename>~/.dbus-keyrings/</filename>. This directory must
1957           not be readable or writable by other users. If it is,
1958           clients and servers must ignore it. The directory
1959           contains cookie files named after the cookie context.
1960         </para>
1961         <para>
1962           A cookie file contains one cookie per line. Each line
1963           has three space-separated fields:
1964           <itemizedlist>
1965             <listitem>
1966               <para>
1967                 The cookie ID number, which must be a non-negative integer and
1968                 may not be used twice in the same file.
1969               </para>
1970             </listitem>
1971             <listitem>
1972               <para>
1973                 The cookie's creation time, in UNIX seconds-since-the-epoch
1974                 format.
1975               </para>
1976             </listitem>
1977             <listitem>
1978               <para>
1979                 The cookie itself, a hex-encoded random block of bytes. The cookie
1980                 may be of any length, though obviously security increases
1981                 as the length increases.
1982               </para>
1983             </listitem>
1984           </itemizedlist>
1985         </para>
1986         <para>
1987           Only server processes modify the cookie file.
1988           They must do so with this procedure:
1989           <itemizedlist>
1990             <listitem>
1991               <para>
1992                 Create a lockfile name by appending ".lock" to the name of the
1993                 cookie file.  The server should attempt to create this file
1994                 using <literal>O_CREAT | O_EXCL</literal>.  If file creation
1995                 fails, the lock fails. Servers should retry for a reasonable
1996                 period of time, then they may choose to delete an existing lock
1997                 to keep users from having to manually delete a stale
1998                 lock. <footnote><para>Lockfiles are used instead of real file
1999                 locking <literal>fcntl()</literal> because real locking
2000                 implementations are still flaky on network
2001                 filesystems.</para></footnote>
2002               </para>
2003             </listitem>
2004             <listitem>
2005               <para>
2006                 Once the lockfile has been created, the server loads the cookie
2007                 file. It should then delete any cookies that are old (the
2008                 timeout can be fairly short), or more than a reasonable
2009                 time in the future (so that cookies never accidentally
2010                 become permanent, if the clock was set far into the future
2011                 at some point). If no recent keys remain, the
2012                 server may generate a new key.
2013               </para>
2014             </listitem>
2015             <listitem>
2016               <para>
2017                 The pruned and possibly added-to cookie file
2018                 must be resaved atomically (using a temporary
2019                 file which is rename()'d).
2020               </para>
2021             </listitem>
2022             <listitem>
2023               <para>
2024                 The lock must be dropped by deleting the lockfile.
2025               </para>
2026             </listitem>
2027           </itemizedlist>
2028         </para>
2029         <para>
2030           Clients need not lock the file in order to load it,
2031           because servers are required to save the file atomically.
2032         </para>
2033       </sect3>
2034     </sect2>
2035   </sect1>
2036   <sect1 id="addresses">
2037     <title>Server Addresses</title>
2038     <para>
2039       Server addresses consist of a transport name followed by a colon, and
2040       then an optional, comma-separated list of keys and values in the form key=value.
2041       [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
2042     </para>
2043     <para>
2044       For example:
2045       <programlisting>unix:path=/tmp/dbus-test</programlisting>
2046       Which is the address to a unix socket with the path /tmp/dbus-test.
2047     </para>
2048     <para>
2049       [FIXME clarify if attempting to connect to each is a requirement
2050       or just a suggestion]
2051       When connecting to a server, multiple server addresses can be
2052       separated by a semi-colon. The library will then try to connect
2053       to the first address and if that fails, it'll try to connect to
2054       the next one specified, and so forth. For example
2055       <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
2056     </para>
2057     <para>
2058       [FIXME we need to specify in detail each transport and its possible arguments]
2059       Current transports include: unix domain sockets (including
2060       abstract namespace on linux), TCP/IP, and a debug/testing transport using
2061       in-process pipes. Future possible transports include one that
2062       tunnels over X11 protocol.
2063     </para>
2064   </sect1>
2065
2066   <sect1 id="naming-conventions">
2067     <title>Naming Conventions</title>
2068
2069     <para>
2070       D-BUS namespaces are all lowercase and correspond to reversed domain
2071       names, as with Java. e.g. "org.freedesktop"
2072     </para>
2073     <para>
2074       Interface, signal, method, and property names are "WindowsStyleCaps", note
2075       that the first letter is capitalized, unlike Java.
2076     </para>
2077     <para>
2078       Object paths are normally all lowercase with underscores used rather than
2079       hyphens.
2080     </para>
2081   </sect1>
2082
2083   <sect1 id="standard-interfaces">
2084     <title>Standard Interfaces</title>
2085     <para>
2086       See <xref linkend="message-protocol-types-notation"/> for details on
2087        the notation used in this section. There are some standard interfaces
2088       that may be useful across various D-BUS applications.
2089     </para>
2090     <sect2 id="standard-interfaces-peer">
2091       <title><literal>org.freedesktop.Peer</literal></title>
2092       <para>
2093         The <literal>org.freedesktop.Peer</literal> interface
2094         has one method:
2095         <programlisting>
2096           org.freedesktop.Peer.Ping ()
2097         </programlisting>
2098       </para>
2099       <para>
2100         On receipt of the <literal>METHOD_CALL</literal> message
2101         <literal>org.freedesktop.Peer.Ping</literal>, an application should do
2102         nothing other than reply with a <literal>METHOD_RETURN</literal> as
2103         usual.  It does not matter which object path a ping is sent to.  The
2104         reference implementation should simply handle this method on behalf of
2105         all objects, though it doesn't yet. (The point is, you're really pinging
2106         the peer process, not a specific object.)
2107       </para>
2108     </sect2>
2109
2110     <sect2 id="standard-interfaces-introspectable">
2111       <title><literal>org.freedesktop.Introspectable</literal></title>
2112       <para>
2113         This interface has one method:
2114         <programlisting>
2115           org.freedesktop.Introspectable.Introspect (out STRING xml_data)
2116         </programlisting>
2117       </para>
2118       <para>
2119         Objects instances may implement
2120         <literal>Introspect</literal> which returns an XML description of
2121         the object, including its interfaces (with signals and methods), objects
2122         below it in the object path tree, and its properties.
2123       </para>
2124       <para>
2125         <xref linkend="introspection-format"/> describes the format of this XML string.
2126       </para>
2127     </sect2>
2128     <sect2 id="standard-interfaces-properties">
2129       <title><literal>org.freedesktop.Properties</literal></title>
2130       <para>
2131         Many native APIs will have a concept of object <firstterm>properties</firstterm>
2132         or <firstterm>attributes</firstterm>. These can be exposed via the
2133         <literal>org.freedesktop.Properties</literal> interface.
2134       </para>
2135       <para>
2136         <programlisting>
2137               org.freedesktop.Properties.Get (in STRING interface_name,
2138                                               in STRING property_name,
2139                                               out VARIANT value);
2140               org.freedesktop.Properties.Set (in STRING interface_name,
2141                                               in STRING property_name,
2142                                               in VARIANT value);
2143         </programlisting>
2144       </para>
2145       <para>
2146         The available properties and whether they are writable can be determined
2147         by calling <literal>org.freedesktop.Introspectable.Introspect</literal>,
2148         see <xref linkend="standard-interfaces-introspectable"/>.
2149       </para>
2150       <para>
2151         An empty string may be provided for the interface name; in this case,
2152         if there are multiple properties on an object with the same name,
2153         the results are undefined (picking one by according to an arbitrary
2154         deterministic rule, or returning an error, are the reasonable
2155         possibilities).
2156       </para>
2157     </sect2>
2158   </sect1>
2159
2160   <sect1 id="introspection-format">
2161     <title>Introspection Data Format</title>
2162     <para>
2163       As described in <xref linkend="standard-interfaces-introspectable"/>,
2164       objects may be introspected at runtime, returning an XML string
2165       that describes the object. The same XML format may be used in
2166       other contexts as well, for example as an "IDL" for generating
2167       static language bindings.
2168     </para>
2169     <para>
2170       Here is an example of introspection data:
2171       <programlisting>
2172         &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
2173          "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
2174         &lt;node name="/org/freedesktop/sample_object"&gt;
2175           &lt;interface name="org.freedesktop.SampleInterface"&gt;
2176             &lt;method name="Frobate"&gt;
2177               &lt;arg name="foo" type="int32" direction="in"/&gt;
2178               &lt;arg name="bar" type="string" direction="out"/&gt;
2179             &lt;/method&gt;
2180             &lt;signal name="Changed"&gt;
2181               &lt;arg name="new_value" type="boolean"/&gt;
2182             &lt;/signal&gt;
2183             &lt;property name="Bar" type="byte" access="readwrite"/&gt;
2184           &lt;/interface&gt;
2185           &lt;node name="child_of_sample_object"/&gt;
2186           &lt;node name="another_child_of_sample_object"/&gt;
2187        &lt;/node&gt;
2188       </programlisting>
2189     </para>
2190     <para>
2191       A more formal DTD and spec needs writing, but here are some quick notes.
2192       <itemizedlist>
2193         <listitem>
2194           <para>
2195             Only the root &lt;node&gt; element can omit the node name, as it's
2196             known to be the object that was introspected.  If the root
2197             &lt;node&gt; does have a name attribute, it should be an absolute
2198             object path. If child &lt;node&gt; have object paths, they should be
2199             relative.
2200           </para>
2201         </listitem>
2202         <listitem>
2203           <para>
2204             If a child &lt;node&gt; has any sub-elements, then they
2205             must represent a complete introspection of the child.
2206             If a child &lt;node&gt; is empty, then it may or may
2207             not have sub-elements; the child must be introspected
2208             in order to find out. The intent is that if an object
2209             knows that its children are "fast" to introspect
2210             it can go ahead and return their information, but
2211             otherwise it can omit it.
2212           </para>
2213         </listitem>
2214         <listitem>
2215           <para>
2216             The direction element on &lt;arg&gt; may be omitted,
2217             in which case it defaults to "in" for method calls
2218             and "out" for signals. Signals only allow "out"
2219             so while direction may be specified, it's pointless.
2220           </para>
2221         </listitem>
2222         <listitem>
2223           <para>
2224             The possible directions are "in" and "out",
2225             unlike CORBA there is no "inout"
2226           </para>
2227         </listitem>
2228         <listitem>
2229           <para>
2230             The possible property access flags are
2231             "readwrite", "read", and "write"
2232           </para>
2233         </listitem>
2234         <listitem>
2235           <para>
2236             The current type="uint32" stuff is totally broken,
2237             instead we have to do full signatures.
2238             However, then this format will suck for human readability.
2239             So, some thinking to do here.
2240           </para>
2241         </listitem>
2242         <listitem>
2243           <para>
2244             Multiple interfaces can of course be listed for
2245             one &lt;node&gt;.
2246           </para>
2247         </listitem>
2248         <listitem>
2249           <para>
2250             The method, interface, property, and signal elements may have
2251             an attribute deprecated="yes|no". If the attribute is not
2252             present, the default value for an interface is "no", and
2253             the default value for methods, properties, and signals is
2254             the deprecation status of the interface.
2255           </para>
2256         </listitem>
2257       </itemizedlist>
2258     </para>
2259
2260   </sect1>
2261
2262   <sect1 id="message-bus">
2263     <title>Message Bus Specification</title>
2264     <sect2 id="message-bus-overview">
2265       <title>Message Bus Overview</title>
2266       <para>
2267         The message bus accepts connections from one or more applications.
2268         Once connected, applications can exchange messages with other
2269         applications that are also connected to the bus.
2270       </para>
2271       <para>
2272         In order to route messages among connections, the message bus keeps a
2273         mapping from names to connections. Each connection has one
2274         unique-for-the-lifetime-of-the-bus name automatically assigned.
2275         Applications may request additional names for a connection. Additional
2276         names are usually "well-known names" such as
2277         "org.freedesktop.TextEditor". When a name is bound to a connection,
2278         that connection is said to <firstterm>own</firstterm> the name.
2279       </para>
2280       <para>
2281         The bus itself owns a special name, <literal>org.freedesktop.DBus</literal>.
2282         This name routes messages to the bus, allowing applications to make
2283         administrative requests. For example, applications can ask the bus
2284         to assign a name to a connection.
2285       </para>
2286       <para>
2287         Each name may have <firstterm>queued owners</firstterm>.  When an
2288         application requests a name for a connection and the name is already in
2289         use, the bus will optionally add the connection to a queue waiting for
2290         the name. If the current owner of the name disconnects or releases
2291         the name, the next connection in the queue will become the new owner.
2292       </para>
2293
2294       <para>
2295         This feature causes the right thing to happen if you start two text
2296         editors for example; the first one may request "org.freedesktop.TextEditor",
2297         and the second will be queued as a possible owner of that name. When
2298         the first exits, the second will take over.
2299       </para>
2300
2301       <para>
2302         Messages may have a <literal>DESTINATION</literal> field (see <xref
2303         linkend="message-protocol-header-fields"/>).  If the
2304         <literal>DESTINATION</literal> field is present, it specifies a message
2305         recipient by name. Method calls and replies normally specify this field.
2306       </para>
2307
2308       <para>
2309         Signals normally do not specify a destination; they are sent to all
2310         applications with <firstterm>message matching rules</firstterm> that
2311         match the message.
2312       </para>
2313
2314       <para>
2315         When the message bus receives a method call, if the
2316         <literal>DESTINATION</literal> field is absent, the call is taken to be
2317         a standard one-to-one message and interpreted by the message bus
2318         itself. For example, sending an
2319         <literal>org.freedesktop.Peer.Ping</literal> message with no
2320         <literal>DESTINATION</literal> will cause the message bus itself to
2321         reply to the ping immediately; the message bus will not make this
2322         message visible to other applications.
2323       </para>
2324
2325       <para>
2326         Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
2327         the ping message were sent with a <literal>DESTINATION</literal> name of
2328         <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
2329         forwarded, and the Yoyodyne Corporation screensaver application would be
2330         expected to reply to the ping.
2331       </para>
2332     </sect2>
2333
2334     <sect2 id="message-bus-names">
2335       <title>Message Bus Names</title>
2336       <para>
2337         Each connection has at least one name, assigned at connection time and
2338         returned in response to the
2339         <literal>org.freedesktop.DBus.Hello</literal> method call.  This
2340         automatically-assigned name is called the connection's <firstterm>unique
2341         name</firstterm>.  Unique names are never reused for two different
2342         connections to the same bus.
2343       </para>
2344       <para>
2345         Ownership of a unique name is a prerequisite for interaction with
2346         the message bus. It logically follows that the unique name is always
2347         the first name that an application comes to own, and the last
2348         one that it loses ownership of.
2349       </para>
2350       <para>
2351         Unique connection names must begin with the character ':' (ASCII colon
2352         character); bus names that are not unique names must not begin
2353         with this character. (The bus must reject any attempt by an application
2354         to manually request a name beginning with ':'.) This restriction
2355         categorically prevents "spoofing"; messages sent to a unique name
2356         will always go to the expected connection.
2357       </para>
2358       <para>
2359         When a connection is closed, all the names that it owns are deleted (or
2360         transferred to the next connection in the queue if any).
2361       </para>
2362       <para>
2363         A connection can request additional names to be associated with it using
2364         the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
2365         linkend="message-protocol-names-bus"/> describes the format of a valid
2366         name.
2367       </para>
2368
2369       <sect3 id="bus-messages-request-name">
2370         <title><literal>org.freedesktop.DBus.RequestName</literal></title>
2371         <para>
2372           As a method:
2373           <programlisting>
2374             UINT32 RequestName (in STRING name, in UINT32 flags)
2375           </programlisting>
2376           Message arguments:
2377           <informaltable>
2378             <tgroup cols="3">
2379               <thead>
2380                 <row>
2381                   <entry>Argument</entry>
2382                   <entry>Type</entry>
2383                   <entry>Description</entry>
2384                 </row>
2385               </thead>
2386               <tbody>
2387                 <row>
2388                   <entry>0</entry>
2389                   <entry>STRING</entry>
2390                   <entry>Name to request</entry>
2391                 </row>
2392                 <row>
2393                   <entry>1</entry>
2394                   <entry>UINT32</entry>
2395                   <entry>Flags</entry>
2396                 </row>
2397               </tbody>
2398             </tgroup>
2399           </informaltable>
2400           Reply arguments:
2401           <informaltable>
2402             <tgroup cols="3">
2403               <thead>
2404                 <row>
2405                   <entry>Argument</entry>
2406                   <entry>Type</entry>
2407                   <entry>Description</entry>
2408                 </row>
2409               </thead>
2410               <tbody>
2411                 <row>
2412                   <entry>0</entry>
2413                   <entry>UINT32</entry>
2414                   <entry>Return value</entry>
2415                 </row>
2416               </tbody>
2417             </tgroup>
2418           </informaltable>
2419         </para>
2420         <para>
2421           This method call should be sent to
2422           <literal>org.freedesktop.DBus</literal> and asks the message bus to
2423           assign the given name to the method caller.  The flags argument
2424           contains any of the following values logically ORed together:
2425
2426           <informaltable>
2427             <tgroup cols="3">
2428               <thead>
2429                 <row>
2430                   <entry>Conventional Name</entry>
2431                   <entry>Value</entry>
2432                   <entry>Description</entry>
2433                 </row>
2434               </thead>
2435               <tbody>
2436                 <row>
2437                   <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
2438                   <entry>0x1</entry>
2439                   <entry>
2440                     If the application succeeds in becoming the owner of the specified name,
2441                     then ownership of the name can't be transferred until the application
2442                     disconnects. If this flag is not set, then any application trying to become
2443                     the owner of the name will succeed and the previous owner will be
2444                     sent a <literal>org.freedesktop.DBus.NameLost</literal> signal.
2445                   </entry>
2446                 </row>
2447                 <row>
2448                   <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
2449                   <entry>0x2</entry>
2450                   <entry>
2451                     Try to replace the current owner if there is one. If this
2452                     flag is not set the application will only become the owner of
2453                     the name if there is no current owner.
2454                   </entry>
2455                 </row>
2456               </tbody>
2457             </tgroup>
2458           </informaltable>
2459
2460           The return code can be one of the following values:
2461
2462           <informaltable>
2463             <tgroup cols="3">
2464               <thead>
2465                 <row>
2466                   <entry>Conventional Name</entry>
2467                   <entry>Value</entry>
2468                   <entry>Description</entry>
2469                 </row>
2470               </thead>
2471               <tbody>
2472                 <row>
2473                   <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
2474                   <entry>1</entry> <entry>The caller is now the primary owner of
2475                   the name, replacing any previous owner. Either the name had no
2476                   owner before, or the caller specified
2477                   DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner did not
2478                   specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2479                 </row>
2480                 <row>
2481                   <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
2482                   <entry>2</entry>
2483                   <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
2484                 </row>
2485                 <row>
2486                   <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
2487                   <entry>3</entry>
2488                   <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
2489                 </row>
2490                 <row>
2491                   <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
2492                   <entry>4</entry>
2493                   <entry>The application trying to request ownership of a name is already the owner of it.</entry>
2494                 </row>
2495               </tbody>
2496             </tgroup>
2497           </informaltable>
2498         </para>
2499       </sect3>
2500     </sect2>
2501
2502     <sect2 id="message-bus-routing">
2503       <title>Message Bus Message Routing</title>
2504       <para>
2505         FIXME
2506       </para>
2507     </sect2>
2508     <sect2 id="message-bus-starting-services">
2509       <title>Message Bus Starting Services</title>
2510       <para>
2511         The message bus can start applications on behalf of other applications.
2512         In CORBA terms, this would be called <firstterm>activation</firstterm>.
2513         An application that can be started in this way is called a
2514         <firstterm>service</firstterm>.
2515       </para>
2516       <para>
2517         With D-BUS, starting a service is normally done by name. That is,
2518         applications ask the message bus to start some program that will own a
2519         well-known name, such as <literal>org.freedesktop.TextEditor</literal>.
2520         This implies a contract documented along with the name
2521         <literal>org.freedesktop.TextEditor</literal> for which objects
2522         the owner of that name will provide, and what interfaces those
2523         objects will have.
2524       </para>
2525       <para>
2526         To find an executable corresponding to a particular name, the bus daemon
2527         looks for <firstterm>service description files</firstterm>.  Service
2528         description files define a mapping from names to executables. Different
2529         kinds of message bus will look for these files in different places, see
2530         <xref linkend="message-bus-types"/>.
2531       </para>
2532       <para>
2533         [FIXME the file format should be much better specified than "similar to
2534         .desktop entries" esp. since desktop entries are already
2535         badly-specified. ;-)] Service description files have the ".service" file
2536         extension. The message bus will only load service description files
2537         ending with .service; all other files will be ignored.  The file format
2538         is similar to that of <ulink
2539         url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
2540         entries</ulink>. All service description files must be in UTF-8
2541         encoding. To ensure that there will be no name collisions, service files
2542         must be namespaced using the same mechanism as messages and service
2543         names.
2544
2545         <figure>
2546           <title>Example service description file</title>
2547           <programlisting>
2548             # Sample service description file
2549             [D-BUS Service]
2550             Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
2551             Exec=/usr/libexec/gconfd-2
2552           </programlisting>
2553         </figure>
2554       </para>
2555       <para>
2556         When an application asks to start a service by name, the bus daemon tries to
2557         find a service that will own that name. It then tries to spawn the
2558         executable associated with it. If this fails, it will report an
2559         error. [FIXME what happens if two .service files offer the same service;
2560         what kind of error is reported, should we have a way for the client to
2561         choose one?]
2562       </para>
2563       <para>
2564         The executable launched will have the environment variable
2565         <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
2566         message bus so it can connect and request the appropriate names.
2567       </para>
2568       <para>
2569         The executable being launched may want to know whether the message bus
2570         starting it is one of the well-known message buses (see <xref
2571         linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
2572         the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
2573         of the well-known buses. The currently-defined values for this variable
2574         are <literal>system</literal> for the systemwide message bus,
2575         and <literal>session</literal> for the per-login-session message
2576         bus. The new executable must still connect to the address given
2577         in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
2578         resulting connection is to the well-known bus.
2579       </para>
2580       <para>
2581         [FIXME there should be a timeout somewhere, either specified
2582         in the .service file, by the client, or just a global value
2583         and if the client being activated fails to connect within that
2584         timeout, an error should be sent back.]
2585       </para>
2586     </sect2>
2587
2588     <sect2 id="message-bus-types">
2589       <title>Well-known Message Bus Instances</title>
2590       <para>
2591         Two standard message bus instances are defined here, along with how
2592         to locate them and where their service files live.
2593       </para>
2594       <sect3 id="message-bus-types-login">
2595         <title>Login session message bus</title>
2596         <para>
2597           Each time a user logs in, a <firstterm>login session message
2598             bus</firstterm> may be started. All applications in the user's login
2599           session may interact with one another using this message bus.
2600         </para>
2601         <para>
2602           The address of the login session message bus is given
2603           in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
2604           variable. If that variable is not set, applications may
2605           also try to read the address from the X Window System root
2606           window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
2607           The root window property must have type <literal>STRING</literal>.
2608           The environment variable should have precedence over the
2609           root window property.
2610         </para>
2611         <para>
2612           [FIXME specify location of .service files, probably using
2613           DESKTOP_DIRS etc. from basedir specification, though login session
2614           bus is not really desktop-specific]
2615         </para>
2616       </sect3>
2617       <sect3 id="message-bus-types-system">
2618         <title>System message bus</title>
2619         <para>
2620           A computer may have a <firstterm>system message bus</firstterm>,
2621           accessible to all applications on the system. This message bus may be
2622           used to broadcast system events, such as adding new hardware devices,
2623           changes in the printer queue, and so forth.
2624         </para>
2625         <para>
2626           The address of the system message bus is given
2627           in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
2628           variable. If that variable is not set, applications should try
2629           to connect to the well-known address
2630           <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
2631           <footnote>
2632             <para>
2633               The D-BUS reference implementation actually honors the
2634               <literal>$(localstatedir)</literal> configure option
2635               for this address, on both client and server side.
2636             </para>
2637           </footnote>
2638         </para>
2639         <para>
2640           [FIXME specify location of system bus .service files]
2641         </para>
2642       </sect3>
2643     </sect2>
2644
2645     <sect2 id="message-bus-messages">
2646       <title>Message Bus Messages</title>
2647       <para>
2648         The special message bus name <literal>org.freedesktop.DBus</literal>
2649         responds to a number of additional messages.
2650       </para>
2651
2652       <sect3 id="bus-messages-hello">
2653         <title><literal>org.freedesktop.DBus.Hello</literal></title>
2654         <para>
2655           As a method:
2656           <programlisting>
2657             STRING Hello ()
2658           </programlisting>
2659           Reply arguments:
2660           <informaltable>
2661             <tgroup cols="3">
2662               <thead>
2663                 <row>
2664                   <entry>Argument</entry>
2665                   <entry>Type</entry>
2666                   <entry>Description</entry>
2667                 </row>
2668               </thead>
2669               <tbody>
2670                 <row>
2671                   <entry>0</entry>
2672                   <entry>STRING</entry>
2673                   <entry>Unique name assigned to the connection</entry>
2674                 </row>
2675               </tbody>
2676             </tgroup>
2677           </informaltable>
2678         </para>
2679         <para>
2680           Before an application is able to send messages to other applications
2681           it must send the <literal>org.freedesktop.DBus.Hello</literal> message
2682           to the message bus to obtain a unique name. If an application without
2683           a unique name tries to send a message to another application, or a
2684           message to the message bus itself that isn't the
2685           <literal>org.freedesktop.DBus.Hello</literal> message, it will be
2686           disconnected from the bus.
2687         </para>
2688         <para>
2689           There is no corresponding "disconnect" request; if a client wishes to
2690           disconnect from the bus, it simply closes the socket (or other
2691           communication channel).
2692         </para>
2693       </sect3>
2694       <sect3 id="bus-messages-list-names">
2695         <title><literal>org.freedesktop.DBus.ListNames</literal></title>
2696         <para>
2697           As a method:
2698           <programlisting>
2699             ARRAY of STRING ListNames ()
2700           </programlisting>
2701           Reply arguments:
2702           <informaltable>
2703             <tgroup cols="3">
2704               <thead>
2705                 <row>
2706                   <entry>Argument</entry>
2707                   <entry>Type</entry>
2708                   <entry>Description</entry>
2709                 </row>
2710               </thead>
2711               <tbody>
2712                 <row>
2713                   <entry>0</entry>
2714                   <entry>ARRAY of STRING</entry>
2715                   <entry>Array of strings where each string is a bus name</entry>
2716                 </row>
2717               </tbody>
2718             </tgroup>
2719           </informaltable>
2720         </para>
2721         <para>
2722           Returns a list of all currently-owned names on the bus.
2723         </para>
2724       </sect3>
2725       <sect3 id="bus-messages-name-exists">
2726         <title><literal>org.freedesktop.DBus.NameHasOwner</literal></title>
2727         <para>
2728           As a method:
2729           <programlisting>
2730             BOOLEAN NameHasOwner (in STRING name)
2731           </programlisting>
2732           Message 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>STRING</entry>
2746                   <entry>Name to check</entry>
2747                 </row>
2748               </tbody>
2749             </tgroup>
2750           </informaltable>
2751           Reply arguments:
2752           <informaltable>
2753             <tgroup cols="3">
2754               <thead>
2755                 <row>
2756                   <entry>Argument</entry>
2757                   <entry>Type</entry>
2758                   <entry>Description</entry>
2759                 </row>
2760               </thead>
2761               <tbody>
2762                 <row>
2763                   <entry>0</entry>
2764                   <entry>BOOLEAN</entry>
2765                   <entry>Return value, true if the name exists</entry>
2766                 </row>
2767               </tbody>
2768             </tgroup>
2769           </informaltable>
2770         </para>
2771         <para>
2772           Checks if the specified name exists (currently has an owner).
2773         </para>
2774       </sect3>
2775
2776       <sect3 id="bus-messages-name-owner-changed">
2777         <title><literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
2778         <para>
2779           This is a signal:
2780           <programlisting>
2781             NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
2782           </programlisting>
2783           Message arguments:
2784           <informaltable>
2785             <tgroup cols="3">
2786               <thead>
2787                 <row>
2788                   <entry>Argument</entry>
2789                   <entry>Type</entry>
2790                   <entry>Description</entry>
2791                 </row>
2792               </thead>
2793               <tbody>
2794                 <row>
2795                   <entry>0</entry>
2796                   <entry>STRING</entry>
2797                   <entry>Name with a new owner</entry>
2798                 </row>
2799                 <row>
2800                   <entry>1</entry>
2801                   <entry>STRING</entry>
2802                   <entry>Old owner or empty string if none</entry>
2803                 </row>
2804                 <row>
2805                   <entry>2</entry>
2806                   <entry>STRING</entry>
2807                   <entry>New owner or empty string if none</entry>
2808                 </row>
2809               </tbody>
2810             </tgroup>
2811           </informaltable>
2812         </para>
2813         <para>
2814           This signal indicates that the owner of a name has changed.
2815           It's also the signal to use to detect the appearance of
2816           new names on the bus.
2817         </para>
2818       </sect3>
2819       <sect3 id="bus-messages-name-lost">
2820         <title><literal>org.freedesktop.DBus.NameLost</literal></title>
2821         <para>
2822           This is a signal:
2823           <programlisting>
2824             NameLost (STRING name)
2825           </programlisting>
2826           Message arguments:
2827           <informaltable>
2828             <tgroup cols="3">
2829               <thead>
2830                 <row>
2831                   <entry>Argument</entry>
2832                   <entry>Type</entry>
2833                   <entry>Description</entry>
2834                 </row>
2835               </thead>
2836               <tbody>
2837                 <row>
2838                   <entry>0</entry>
2839                   <entry>STRING</entry>
2840                   <entry>Name which was lost</entry>
2841                 </row>
2842               </tbody>
2843             </tgroup>
2844           </informaltable>
2845         </para>
2846         <para>
2847           This signal is sent to a specific application when it loses
2848           ownership of a name.
2849         </para>
2850       </sect3>
2851
2852       <sect3 id="bus-messages-name-acquired">
2853         <title><literal>org.freedesktop.DBus.NameAcquired</literal></title>
2854         <para>
2855           This is a signal:
2856           <programlisting>
2857             NameAcquired (STRING name)
2858           </programlisting>
2859           Message arguments:
2860           <informaltable>
2861             <tgroup cols="3">
2862               <thead>
2863                 <row>
2864                   <entry>Argument</entry>
2865                   <entry>Type</entry>
2866                   <entry>Description</entry>
2867                 </row>
2868               </thead>
2869               <tbody>
2870                 <row>
2871                   <entry>0</entry>
2872                   <entry>STRING</entry>
2873                   <entry>Name which was acquired</entry>
2874                 </row>
2875               </tbody>
2876             </tgroup>
2877           </informaltable>
2878         </para>
2879         <para>
2880           This signal is sent to a specific application when it gains
2881           ownership of a name.
2882         </para>
2883       </sect3>
2884
2885       <sect3 id="bus-messages-start-service-by-name">
2886         <title><literal>org.freedesktop.DBus.StartServiceByName</literal></title>
2887         <para>
2888           As a method:
2889           <programlisting>
2890             UINT32 StartServiceByName (in STRING name, in UINT32 flags)
2891           </programlisting>
2892           Message arguments:
2893           <informaltable>
2894             <tgroup cols="3">
2895               <thead>
2896                 <row>
2897                   <entry>Argument</entry>
2898                   <entry>Type</entry>
2899                   <entry>Description</entry>
2900                 </row>
2901               </thead>
2902               <tbody>
2903                 <row>
2904                   <entry>0</entry>
2905                   <entry>STRING</entry>
2906                   <entry>Name of the service to start</entry>
2907                 </row>
2908                 <row>
2909                   <entry>1</entry>
2910                   <entry>UINT32</entry>
2911                   <entry>Flags (currently not used)</entry>
2912                 </row>
2913               </tbody>
2914             </tgroup>
2915           </informaltable>
2916         Reply arguments:
2917         <informaltable>
2918           <tgroup cols="3">
2919             <thead>
2920               <row>
2921                 <entry>Argument</entry>
2922                 <entry>Type</entry>
2923                 <entry>Description</entry>
2924               </row>
2925             </thead>
2926             <tbody>
2927               <row>
2928                 <entry>0</entry>
2929                 <entry>UINT32</entry>
2930                 <entry>Return value</entry>
2931               </row>
2932             </tbody>
2933           </tgroup>
2934         </informaltable>
2935           Tries to launch the executable associated with a name. For more information, see <xref linkend="message-bus-starting-services"/>.
2936
2937         </para>
2938         <para>
2939           The return value can be one of the following values:
2940           <informaltable>
2941             <tgroup cols="3">
2942               <thead>
2943                 <row>
2944                   <entry>Identifier</entry>
2945                   <entry>Value</entry>
2946                   <entry>Description</entry>
2947                 </row>
2948               </thead>
2949               <tbody>
2950                 <row>
2951                   <entry>DBUS_START_REPLY_SUCCESS</entry>
2952                   <entry>1</entry>
2953                   <entry>The service was successfully started.</entry>
2954                 </row>
2955                 <row>
2956                   <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
2957                   <entry>2</entry>
2958                   <entry>A connection already owns the given name.</entry>
2959                 </row>
2960               </tbody>
2961              </tgroup>
2962            </informaltable>
2963         </para>
2964
2965       </sect3>
2966
2967       <sect3 id="bus-messages-get-name-owner">
2968         <title><literal>org.freedesktop.DBus.GetNameOwner</literal></title>
2969         <para>
2970           As a method:
2971           <programlisting>
2972             STRING GetNameOwner (in STRING name)
2973           </programlisting>
2974           Message arguments:
2975           <informaltable>
2976             <tgroup cols="3">
2977               <thead>
2978                 <row>
2979                   <entry>Argument</entry>
2980                   <entry>Type</entry>
2981                   <entry>Description</entry>
2982                 </row>
2983               </thead>
2984               <tbody>
2985                 <row>
2986                   <entry>0</entry>
2987                   <entry>STRING</entry>
2988                   <entry>Name to get the owner of</entry>
2989                 </row>
2990               </tbody>
2991             </tgroup>
2992           </informaltable>
2993         Reply arguments:
2994         <informaltable>
2995           <tgroup cols="3">
2996             <thead>
2997               <row>
2998                 <entry>Argument</entry>
2999                 <entry>Type</entry>
3000                 <entry>Description</entry>
3001               </row>
3002             </thead>
3003             <tbody>
3004               <row>
3005                 <entry>0</entry>
3006                 <entry>STRING</entry>
3007                 <entry>Return value, a unique connection name</entry>
3008               </row>
3009             </tbody>
3010           </tgroup>
3011         </informaltable>
3012         Returns the unique connection name of the primary owner of the name
3013         given. If the requested name doesn't have an owner, returns a
3014         <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
3015        </para>
3016       </sect3>
3017
3018       <sect3 id="bus-messages-get-connection-unix-user">
3019         <title><literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
3020         <para>
3021           As a method:
3022           <programlisting>
3023             UINT32 GetConnectionUnixUser (in STRING connection_name)
3024           </programlisting>
3025           Message arguments:
3026           <informaltable>
3027             <tgroup cols="3">
3028               <thead>
3029                 <row>
3030                   <entry>Argument</entry>
3031                   <entry>Type</entry>
3032                   <entry>Description</entry>
3033                 </row>
3034               </thead>
3035               <tbody>
3036                 <row>
3037                   <entry>0</entry>
3038                   <entry>STRING</entry>
3039                   <entry>Name of the connection to query</entry>
3040                 </row>
3041               </tbody>
3042             </tgroup>
3043           </informaltable>
3044         Reply arguments:
3045         <informaltable>
3046           <tgroup cols="3">
3047             <thead>
3048               <row>
3049                 <entry>Argument</entry>
3050                 <entry>Type</entry>
3051                 <entry>Description</entry>
3052               </row>
3053             </thead>
3054             <tbody>
3055               <row>
3056                 <entry>0</entry>
3057                 <entry>UINT32</entry>
3058                 <entry>unix user id</entry>
3059               </row>
3060             </tbody>
3061           </tgroup>
3062         </informaltable>
3063         Returns the unix uid of the process connected to the server. If unable to
3064         determine it, a <literal>org.freedesktop.DBus.Error.Failed</literal>
3065         error is returned.
3066        </para>
3067       </sect3>
3068
3069     </sect2>
3070
3071   </sect1>
3072 <!--
3073   <appendix id="implementation-notes">
3074     <title>Implementation notes</title>
3075     <sect1 id="implementation-notes-subsection">
3076       <title></title>
3077       <para>
3078       </para>
3079     </sect1>
3080   </appendix>
3081 -->
3082
3083   <glossary><title>Glossary</title>
3084     <para>
3085       This glossary defines some of the terms used in this specification.
3086     </para>
3087
3088     <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
3089       <glossdef>
3090         <para>
3091           The message bus maintains an association between names and
3092           connections. (Normally, there's one connection per application.)  A
3093           bus name is simply an identifier used to locate connections. For
3094           example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
3095           name might be used to send a message to a screensaver from Yoyodyne
3096           Corporation.  An application is said to <firstterm>own</firstterm> a
3097           name if the message bus has associated the application's connection
3098           with the name.  Names may also have <firstterm>queued
3099           owners</firstterm> (see <xref linkend="term-queued-owner"/>).
3100             The bus assigns a unique name to each connection,
3101             see <xref linkend="term-unique-name"/>. Other names
3102               can be thought of as "well-known names" and are
3103               used to find applications that offer specific functionality.
3104         </para>
3105       </glossdef>
3106     </glossentry>
3107
3108     <glossentry id="term-message"><glossterm>Message</glossterm>
3109       <glossdef>
3110         <para>
3111           A message is the atomic unit of communication via the D-BUS
3112           protocol. It consists of a <firstterm>header</firstterm> and a
3113           <firstterm>body</firstterm>; the body is made up of
3114           <firstterm>arguments</firstterm>.
3115         </para>
3116       </glossdef>
3117     </glossentry>
3118
3119     <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
3120       <glossdef>
3121         <para>
3122           The message bus is a special application that forwards
3123           or routes messages between a group of applications
3124           connected to the message bus. It also manages
3125           <firstterm>names</firstterm> used for routing
3126           messages.
3127         </para>
3128       </glossdef>
3129     </glossentry>
3130
3131     <glossentry id="term-name"><glossterm>Name</glossterm>
3132       <glossdef>
3133         <para>
3134           See <xref linkend="term-bus-name"/>. "Name" may
3135             also be used to refer to some of the other names
3136             in D-BUS, such as interface names.
3137         </para>
3138       </glossdef>
3139     </glossentry>
3140
3141     <glossentry id="namespace"><glossterm>Namespace</glossterm>
3142       <glossdef>
3143         <para>
3144           Used to prevent collisions when defining new interfaces or bus
3145           names. The convention used is the same one Java uses for defining
3146           classes: a reversed domain name.
3147         </para>
3148       </glossdef>
3149     </glossentry>
3150
3151     <glossentry id="term-object"><glossterm>Object</glossterm>
3152       <glossdef>
3153         <para>
3154           Each application contains <firstterm>objects</firstterm>, which have
3155           <firstterm>interfaces</firstterm> and
3156           <firstterm>methods</firstterm>. Objects are referred to by a name,
3157           called a <firstterm>path</firstterm>.
3158         </para>
3159       </glossdef>
3160     </glossentry>
3161
3162     <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
3163       <glossdef>
3164         <para>
3165           An application talking directly to another application, without going
3166           through a message bus. One-to-one connections may be "peer to peer" or
3167           "client to server." The D-BUS protocol has no concept of client
3168           vs. server after a connection has authenticated; the flow of messages
3169           is symmetrical (full duplex).
3170         </para>
3171       </glossdef>
3172     </glossentry>
3173
3174     <glossentry id="term-path"><glossterm>Path</glossterm>
3175       <glossdef>
3176         <para>
3177           Object references (object names) in D-BUS are organized into a
3178           filesystem-style hierarchy, so each object is named by a path. As in
3179           LDAP, there's no difference between "files" and "directories"; a path
3180           can refer to an object, while still having child objects below it.
3181         </para>
3182       </glossdef>
3183     </glossentry>
3184
3185     <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
3186       <glossdef>
3187         <para>
3188           Each bus name has a primary owner; messages sent to the name go to the
3189           primary owner. However, certain names also maintain a queue of
3190           secondary owners "waiting in the wings." If the primary owner releases
3191           the name, then the first secondary owner in the queue automatically
3192           becomes the new owner of the name.
3193         </para>
3194       </glossdef>
3195     </glossentry>
3196
3197     <glossentry id="term-service"><glossterm>Service</glossterm>
3198       <glossdef>
3199         <para>
3200           A service is an executable that can be launched by the bus daemon.
3201           Services normally guarantee some particular features, for example they
3202           may guarantee that they will request a specific name such as
3203           "org.freedesktop.Screensaver", have a singleton object
3204           "/org/freedesktop/Application", and that object will implement the
3205           interface "org.freedesktop.ScreensaverControl".
3206         </para>
3207       </glossdef>
3208     </glossentry>
3209
3210     <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
3211       <glossdef>
3212         <para>
3213           ".service files" tell the bus about service applications that can be
3214           launched (see <xref linkend="term-service"/>). Most importantly they
3215           provide a mapping from bus names to services that will request those
3216             names when they start up.
3217         </para>
3218       </glossdef>
3219     </glossentry>
3220
3221     <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
3222       <glossdef>
3223         <para>
3224           The special name automatically assigned to each connection by the
3225           message bus. This name will never change owner, and will be unique
3226           (never reused during the lifetime of the message bus).
3227           It will begin with a ':' character.
3228         </para>
3229       </glossdef>
3230     </glossentry>
3231
3232   </glossary>
3233 </article>
3234