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