doc/dbus-specification.xml

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