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