doc/dbus-specification.xml

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