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