doc/dbus-specification.xml

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