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