Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 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@pobox.com</email> |
| 20 | </address> |
| 21 | </affiliation> |
| 22 | </author> |
| 23 | <author> |
| 24 | <firstname>Anders</firstname> |
| 25 | <surname>Carlsson</surname> |
| 26 | <affiliation> |
| 27 | <orgname>CodeFactory AB</orgname> |
| 28 | <address> |
| 29 | <email>andersca@codefactory.se</email> |
| 30 | </address> |
| 31 | </affiliation> |
| 32 | </author> |
| 33 | <author> |
| 34 | <firstname>Alexander</firstname> |
| 35 | <surname>Larsson</surname> |
| 36 | <affiliation> |
| 37 | <orgname>Red Hat, Inc.</orgname> |
| 38 | <address> |
| 39 | <email>alexl@redhat.com</email> |
| 40 | </address> |
| 41 | </affiliation> |
| 42 | </author> |
| 43 | </authorgroup> |
| 44 | </articleinfo> |
| 45 | |
| 46 | <sect1 id="introduction"> |
| 47 | <title>Introduction</title> |
| 48 | <para> |
| 49 | D-Bus is a system for low-latency, low-overhead, easy to use |
| 50 | interprocess communication (IPC). In more detail: |
| 51 | <itemizedlist> |
| 52 | <listitem> |
| 53 | <para> |
| 54 | D-Bus is <emphasis>low-latency</emphasis> because it is designed |
| 55 | to avoid round trips and allow asynchronous operation, much like |
| 56 | the X protocol. |
| 57 | </para> |
| 58 | </listitem> |
| 59 | <listitem> |
| 60 | <para> |
| 61 | D-Bus is <emphasis>low-overhead</emphasis> because it uses a |
| 62 | binary protocol, and does not have to convert to and from a text |
| 63 | format such as XML. Because D-Bus is intended for potentially |
| 64 | high-resolution same-machine IPC, not primarily for Internet IPC, |
| 65 | this is an interesting optimization. |
| 66 | </para> |
| 67 | </listitem> |
| 68 | <listitem> |
| 69 | <para> |
| 70 | D-Bus is <emphasis>easy to use</emphasis> because it works in terms |
| 71 | of <firstterm>messages</firstterm> rather than byte streams, and |
| 72 | automatically handles a lot of the hard IPC issues. Also, the D-Bus |
| 73 | library is designed to be wrapped in a way that lets developers use |
| 74 | their framework's existing object/type system, rather than learning |
| 75 | a new one specifically for IPC. |
| 76 | </para> |
| 77 | </listitem> |
| 78 | </itemizedlist> |
| 79 | </para> |
| 80 | |
| 81 | <para> |
| 82 | The base D-Bus protocol is a one-to-one (peer-to-peer or client-server) |
| 83 | protocol, specified in <xref linkend="message-protocol"/>. That is, it is |
| 84 | a system for one application to talk to a single other |
| 85 | application. However, the primary intended application of the protocol is the |
| 86 | D-Bus <firstterm>message bus</firstterm>, specified in <xref |
| 87 | linkend="message-bus"/>. The message bus is a special application that |
| 88 | accepts connections from multiple other applications, and forwards |
| 89 | messages among them. |
| 90 | </para> |
| 91 | |
| 92 | <para> |
| 93 | Uses of D-Bus include notification of system changes (notification of when |
| 94 | a camera is plugged in to a computer, or a new version of some software |
| 95 | has been installed), or desktop interoperability, for example a file |
| 96 | monitoring service or a configuration service. |
| 97 | </para> |
| 98 | |
| 99 | <para> |
| 100 | D-Bus is designed for two specific use cases: |
| 101 | <itemizedlist> |
| 102 | <listitem> |
| 103 | <para> |
| 104 | A "system bus" for notifications from the system to user sessions, |
| 105 | and to allow the system to request input from user sessions. |
| 106 | </para> |
| 107 | </listitem> |
| 108 | <listitem> |
| 109 | <para> |
| 110 | A "session bus" used to implement desktop environments such as |
| 111 | GNOME and KDE. |
| 112 | </para> |
| 113 | </listitem> |
| 114 | </itemizedlist> |
| 115 | D-Bus is not intended to be a generic IPC system for any possible |
| 116 | application, and intentionally omits many features found in other |
| 117 | IPC systems for this reason. |
| 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> |