Debian Codegraph @

doc/dbus-specification.xml

raw
1 <?xml version="1.0" standalone="no" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 [
5 ]>
6 <article id="index">
7 <articleinfo>
8 <title>D-Bus Specification</title>
9 <releaseinfo>Version 0.43</releaseinfo>
10 <date>2024-10-29</date>
11 <authorgroup>
12 <author>
13 <firstname>Havoc</firstname>
14 <surname>Pennington</surname>
15 <affiliation>
16 <orgname>Red Hat, Inc.</orgname>
17 <address>
18 <email>[email protected]</email>
19 </address>
20 </affiliation>
21 </author>
22 <author>
23 <firstname>Anders</firstname>
24 <surname>Carlsson</surname>
25 <affiliation>
26 <orgname>CodeFactory AB</orgname>
27 <address>
28 <email>[email protected]</email>
29 </address>
30 </affiliation>
31 </author>
32 <author>
33 <firstname>Alexander</firstname>
34 <surname>Larsson</surname>
35 <affiliation>
36 <orgname>Red Hat, Inc.</orgname>
37 <address>
38 <email>[email protected]</email>
39 </address>
40 </affiliation>
41 </author>
42 <author>
43 <firstname>Sven</firstname>
44 <surname>Herzberg</surname>
45 <affiliation>
46 <orgname>Imendio AB</orgname>
47 <address>
48 <email>[email protected]</email>
49 </address>
50 </affiliation>
51 </author>
52 <author>
53 <firstname>Simon</firstname>
54 <surname>McVittie</surname>
55 <affiliation>
56 <orgname>Collabora Ltd.</orgname>
57 <address>
58 <email>[email protected]</email>
59 </address>
60 </affiliation>
61 </author>
62 <author>
63 <firstname>David</firstname>
64 <surname>Zeuthen</surname>
65 <affiliation>
66 <address>
67 <email>[email protected]</email>
68 </address>
69 </affiliation>
70 </author>
71 </authorgroup>
72 <revhistory>
73 <revision>
74 <revnumber>latest</revnumber>
75 <date></date>
76 <authorinitials></authorinitials>
77 <revremark>
78 See <ulink url='http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml'>commit log</ulink>
79 </revremark>
80 </revision>
81 <revision>
82 <revnumber>0.43</revnumber>
83 <date>2024-10-29</date>
84 <authorinitials></authorinitials>
85 <revdescription>
86 <itemizedlist>
87 <listitem><simpara>Recommend loading system services from /etc, /run</simpara></listitem>
88 <listitem><simpara>Document the Stats interface</simpara></listitem>
89 <listitem><simpara>Document the Verbose interface</simpara></listitem>
90 </itemizedlist>
91 </revdescription>
92 </revision>
93 <revision>
94 <revnumber>0.42</revnumber>
95 <date>2023-08-21</date>
96 <authorinitials></authorinitials>
97 <revdescription>
98 <itemizedlist>
99 <listitem><simpara>GetConnectionCredentials can return ProcessFD</simpara></listitem>
100 </itemizedlist>
101 </revdescription>
102 </revision>
103 <revision>
104 <revnumber>0.41</revnumber>
105 <date>2023-02-08</date>
106 <authorinitials></authorinitials>
107 <revdescription>
108 <itemizedlist>
109 <listitem><simpara>Clarify intended handling of /run vs. /var/run</simpara></listitem>
110 </itemizedlist>
111 </revdescription>
112 </revision>
113 <revision>
114 <revnumber>0.40</revnumber>
115 <date>2022-10-05</date>
116 <authorinitials></authorinitials>
117 <revdescription>
118 <itemizedlist>
119 <listitem><simpara>Clarify that unix:tmpdir is not required to use an abstract socket on Linux</simpara></listitem>
120 <listitem><simpara>Mention implications of abstract sockets for Linux namespacing</simpara></listitem>
121 </itemizedlist>
122 </revdescription>
123 </revision>
124 <revision>
125 <revnumber>0.39</revnumber>
126 <date>2022-09-22</date>
127 <authorinitials></authorinitials>
128 <revdescription>
129 <itemizedlist>
130 <listitem><simpara>Document a recommendation for IDNs in reversed domain names</simpara></listitem>
131 <listitem><simpara>Clarify documentation regarding AF_UNIX sockets</simpara></listitem>
132 </itemizedlist>
133 </revdescription>
134 </revision>
135 <revision>
136 <revnumber>0.38</revnumber>
137 <date>2022-02-23</date>
138 <authorinitials></authorinitials>
139 <revdescription>
140 <itemizedlist>
141 <listitem><simpara>Add ActivatableServicesChanged signal and feature flag</simpara></listitem>
142 <listitem><simpara><literal>*</literal> is optionally-escaped in addresses</simpara></listitem>
143 </itemizedlist>
144 </revdescription>
145 </revision>
146 <revision>
147 <revnumber>0.37</revnumber>
148 <date>2021-12-17</date>
149 <authorinitials></authorinitials>
150 <revdescription>
151 <itemizedlist>
152 <listitem><simpara>Update recommendations for interoperable DBUS_COOKIE_SHA1 timeouts</simpara></listitem>
153 <listitem><simpara>Clarify padding requirements for arrays and variants</simpara></listitem>
154 <listitem><simpara>Describe where the interoperable machine ID comes from</simpara></listitem>
155 <listitem><simpara>Clarify use of dictionary (array of dict-entry) types</simpara></listitem>
156 </itemizedlist>
157 </revdescription>
158 </revision>
159 <revision>
160 <revnumber>0.36</revnumber>
161 <date>2020-04-21</date>
162 <authorinitials></authorinitials>
163 <revdescription>
164 <itemizedlist>
165 <listitem><simpara>Fix a typo in an annotated hexdump of part of a message</simpara></listitem>
166 </itemizedlist>
167 </revdescription>
168 </revision>
169 <revision>
170 <revnumber>0.35</revnumber>
171 <date>2019-05-13</date>
172 <authorinitials></authorinitials>
173 <revdescription>
174 <itemizedlist>
175 <listitem><simpara>Add UnixGroupIDs to GetConnectionCredentials</simpara></listitem>
176 <listitem><simpara>Avoid redundancy in defining interface name syntax</simpara></listitem>
177 </itemizedlist>
178 </revdescription>
179 </revision>
180 <revision>
181 <revnumber>0.34</revnumber>
182 <date>2018-12-04</date>
183 <authorinitials>pwithnall</authorinitials>
184 <revdescription>
185 <itemizedlist>
186 <listitem><simpara>Correct ObjectManager example AddMatch rule</simpara></listitem>
187 </itemizedlist>
188 </revdescription>
189 </revision>
190 <revision>
191 <revnumber>0.33</revnumber>
192 <date>2018-04-27</date>
193 <authorinitials>smcv</authorinitials>
194 <revdescription>
195 <itemizedlist>
196 <listitem><simpara>Deprecate TCP on Unix</simpara></listitem>
197 <listitem><simpara>Deprecate non-local TCP everywhere</simpara></listitem>
198 </itemizedlist>
199 </revdescription>
200 </revision>
201 <revision>
202 <revnumber>0.32</revnumber>
203 <date>2018-01-30</date>
204 <authorinitials>smcv</authorinitials>
205 <revdescription>
206 <itemizedlist>
207 <listitem><simpara>Deprecate hyphen/minus in bus names, with
208 underscore as the recommended replacement</simpara></listitem>
209 <listitem><simpara>Document the convention for escaping
210 leading digits in interface and bus names
211 (org._7_zip)</simpara></listitem>
212 <listitem><simpara>Recommend using SASL EXTERNAL where
213 possible, or DBUS_COOKIE_SHA1 otherwise</simpara></listitem>
214 <listitem><simpara>Message buses should not accept SASL
215 ANONYMOUS</simpara></listitem>
216 <listitem><simpara>Document the meaning of non-empty SASL
217 authorization identity strings</simpara></listitem>
218 <listitem><simpara>Document the optional argument to SASL
219 ERROR</simpara></listitem>
220 <listitem><simpara>Document who sends each SASL command, and
221 the possible replies</simpara></listitem>
222 <listitem><simpara>Document the authentication states used to
223 negotiate Unix fd-passing</simpara></listitem>
224 <listitem><simpara>Servers that relay messages should remove
225 header fields they do not understand</simpara></listitem>
226 <listitem><simpara>Clarify who controls each header
227 field</simpara></listitem>
228 <listitem><simpara>Document the HeaderFiltering message bus
229 feature flag</simpara></listitem>
230 <listitem><simpara>Non-message-bus servers may use the SENDER
231 and DESTINATION fields</simpara></listitem>
232 </itemizedlist>
233 </revdescription>
234 </revision>
235 <revision>
236 <revnumber>0.31</revnumber>
237 <date>2017-06-29</date>
238 <authorinitials>smcv, TG</authorinitials>
239 <revdescription>
240 <itemizedlist>
241 <listitem><simpara>Don't require implementation-specific search
242 paths to be lowest priority</simpara></listitem>
243 <listitem><simpara>Correct regex syntax for optionally-escaped
244 bytes in addresses so it includes hyphen-minus, forward slash
245 and underscore as intended</simpara></listitem>
246 <listitem><simpara>Describe all message bus methods in the same
247 section</simpara></listitem>
248 <listitem><simpara>Clarify the correct object path for method calls
249 to the message bus</simpara></listitem>
250 <listitem><simpara>Document that the message bus implements
251 Introspectable, Peer and Properties</simpara></listitem>
252 <listitem><simpara>Add new Features and Interfaces properties for
253 message bus feature-discovery</simpara></listitem>
254 <listitem><simpara>Add unix:dir=..., which resembles
255 unix:tmpdir=... but never uses abstract
256 sockets</simpara></listitem>
257 <listitem><simpara>Don't require eavesdrop='true' to be accepted
258 from connections not sufficiently privileged to use it
259 successfully</simpara></listitem>
260 <listitem><simpara>Formally deprecate eavesdropping in favour of
261 BecomeMonitor</simpara></listitem>
262 </itemizedlist>
263 </revdescription>
264 </revision>
265 <revision>
266 <revnumber>0.30</revnumber>
267 <date>2016-11-28</date>
268 <authorinitials>smcv, PW</authorinitials>
269 <revremark>
270 Define the jargon terms service activation and auto-starting more
271 clearly. Document the SystemdService key in service files.
272 Document how AppArmor interacts with service activation, and the
273 new AssumedAppArmorLabel key in service files (dbus-daemon 1.11.8).
274 Clarify intended behaviour of Properties.GetAll.
275 Use versioned interface and bus names in most examples.
276 </revremark>
277 </revision>
278 <revision>
279 <revnumber>0.29</revnumber>
280 <date>2016-10-10</date>
281 <authorinitials>PW</authorinitials>
282 <revremark>
283 Introspection arguments may contain annotations; recommend against
284 using the object path '/'
285 </revremark>
286 </revision>
287 <revision>
288 <revnumber>0.28</revnumber>
289 <date>2016-08-15</date>
290 <authorinitials>PW</authorinitials>
291 <revremark>Clarify serialization</revremark>
292 </revision>
293 <revision>
294 <revnumber>0.27</revnumber>
295 <date>2015-12-02</date>
296 <authorinitials>LU</authorinitials>
297 <revremark>Services should not send unwanted replies</revremark>
298 </revision>
299 <revision>
300 <revnumber>0.26</revnumber>
301 <date>2015-02-19</date>
302 <authorinitials>smcv, rh</authorinitials>
303 <revremark>
304 GetConnectionCredentials can return LinuxSecurityLabel or
305 WindowsSID; add privileged BecomeMonitor method
306 </revremark>
307 </revision>
308 <revision>
309 <revnumber>0.25</revnumber>
310 <date>2014-11-10</date>
311 <authorinitials>smcv, lennart</authorinitials>
312 <revremark>
313 ALLOW_INTERACTIVE_AUTHORIZATION flag, EmitsChangedSignal=const
314 </revremark>
315 </revision>
316 <revision>
317 <revnumber>0.24</revnumber>
318 <date>2014-10-01</date>
319 <authorinitials>SMcV</authorinitials>
320 <revremark>
321 non-method-calls never expect a reply even without NO_REPLY_EXPECTED;
322 document how to quote match rules
323 </revremark>
324 </revision>
325 <revision>
326 <revnumber>0.23</revnumber>
327 <date>2014-01-06</date>
328 <authorinitials>SMcV, CY</authorinitials>
329 <revremark>
330 method call messages with no INTERFACE may be considered an error;
331 document tcp:bind=... and nonce-tcp:bind=...; define listenable
332 and connectable addresses
333 </revremark>
334 </revision>
335 <revision>
336 <revnumber>0.22</revnumber>
337 <date>2013-10-09</date>
338 <authorinitials></authorinitials>
339 <revremark>add GetConnectionCredentials, document
340 GetAtdAuditSessionData, document GetConnectionSELinuxSecurityContext,
341 document and correct .service file syntax and naming
342 </revremark>
343 </revision>
344 <revision>
345 <revnumber>0.21</revnumber>
346 <date>2013-04-25</date>
347 <authorinitials>smcv</authorinitials>
348 <revremark>allow Unicode noncharacters in UTF-8 (Unicode
349 Corrigendum #9)</revremark>
350 </revision>
351 <revision>
352 <revnumber>0.20</revnumber>
353 <date>22 February 2013</date>
354 <authorinitials>smcv, walters</authorinitials>
355 <revremark>reorganise for clarity, remove false claims about
356 basic types, mention /o/fd/DBus</revremark>
357 </revision>
358 <revision>
359 <revnumber>0.19</revnumber>
360 <date>20 February 2012</date>
361 <authorinitials>smcv/lp</authorinitials>
362 <revremark>formally define unique connection names and well-known
363 bus names; document best practices for interface, bus, member and
364 error names, and object paths; document the search path for session
365 and system services on Unix; document the systemd transport</revremark>
366 </revision>
367 <revision>
368 <revnumber>0.18</revnumber>
369 <date>29 July 2011</date>
370 <authorinitials>smcv</authorinitials>
371 <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
372 match keyword; promote type system to a top-level section</revremark>
373 </revision>
374 <revision>
375 <revnumber>0.17</revnumber>
376 <date>1 June 2011</date>
377 <authorinitials>smcv/davidz</authorinitials>
378 <revremark>define ObjectManager; reserve extra pseudo-type-codes used
379 by GVariant</revremark>
380 </revision>
381 <revision>
382 <revnumber>0.16</revnumber>
383 <date>11 April 2011</date>
384 <authorinitials></authorinitials>
385 <revremark>add path_namespace, arg0namespace; argNpath matches object
386 paths</revremark>
387 </revision>
388 <revision>
389 <revnumber>0.15</revnumber>
390 <date>3 November 2010</date>
391 <authorinitials></authorinitials>
392 <revremark></revremark>
393 </revision>
394 <revision>
395 <revnumber>0.14</revnumber>
396 <date>12 May 2010</date>
397 <authorinitials></authorinitials>
398 <revremark></revremark>
399 </revision>
400 <revision>
401 <revnumber>0.13</revnumber>
402 <date>23 Dezember 2009</date>
403 <authorinitials></authorinitials>
404 <revremark></revremark>
405 </revision>
406 <revision>
407 <revnumber>0.12</revnumber>
408 <date>7 November, 2006</date>
409 <authorinitials></authorinitials>
410 <revremark></revremark>
411 </revision>
412 <revision>
413 <revnumber>0.11</revnumber>
414 <date>6 February 2005</date>
415 <authorinitials></authorinitials>
416 <revremark></revremark>
417 </revision>
418 <revision>
419 <revnumber>0.10</revnumber>
420 <date>28 January 2005</date>
421 <authorinitials></authorinitials>
422 <revremark></revremark>
423 </revision>
424 <revision>
425 <revnumber>0.9</revnumber>
426 <date>7 Januar 2005</date>
427 <authorinitials></authorinitials>
428 <revremark></revremark>
429 </revision>
430 <revision>
431 <revnumber>0.8</revnumber>
432 <date>06 September 2003</date>
433 <authorinitials></authorinitials>
434 <revremark>First released document.</revremark>
435 </revision>
436 </revhistory>
437 </articleinfo>
438
439 <sect1 id="introduction">
440 <title>Introduction</title>
441 <para>
442 D-Bus is a system for low-overhead, easy to use
443 interprocess communication (IPC). In more detail:
444 <itemizedlist>
445 <listitem>
446 <para>
447 D-Bus is <emphasis>low-overhead</emphasis> because it uses a
448 binary protocol, and does not have to convert to and from a text
449 format such as XML. Because D-Bus is intended for potentially
450 high-resolution same-machine IPC, not primarily for Internet IPC,
451 this is an interesting optimization. D-Bus is also designed to
452 avoid round trips and allow asynchronous operation, much like
453 the X protocol.
454 </para>
455 </listitem>
456 <listitem>
457 <para>
458 D-Bus is <emphasis>easy to use</emphasis> because it works in terms
459 of <firstterm>messages</firstterm> rather than byte streams, and
460 automatically handles a lot of the hard IPC issues. Also, the D-Bus
461 library is designed to be wrapped in a way that lets developers use
462 their framework's existing object/type system, rather than learning
463 a new one specifically for IPC.
464 </para>
465 </listitem>
466 </itemizedlist>
467 </para>
468
469 <para>
470 The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
471 protocol, specified in <xref linkend="message-protocol"/>. That is, it is
472 a system for one application to talk to a single other
473 application. However, the primary intended application of the protocol is the
474 D-Bus <firstterm>message bus</firstterm>, specified in <xref
475 linkend="message-bus"/>. The message bus is a special application that
476 accepts connections from multiple other applications, and forwards
477 messages among them.
478 </para>
479
480 <para>
481 Uses of D-Bus include notification of system changes (notification of when
482 a camera is plugged in to a computer, or a new version of some software
483 has been installed), or desktop interoperability, for example a file
484 monitoring service or a configuration service.
485 </para>
486
487 <para>
488 D-Bus is designed for two specific use cases:
489 <itemizedlist>
490 <listitem>
491 <para>
492 A "system bus" for notifications from the system to user sessions,
493 and to allow the system to request input from user sessions.
494 </para>
495 </listitem>
496 <listitem>
497 <para>
498 A "session bus" used to implement desktop environments such as
499 GNOME and KDE.
500 </para>
501 </listitem>
502 </itemizedlist>
503 D-Bus is not intended to be a generic IPC system for any possible
504 application, and intentionally omits many features found in other
505 IPC systems for this reason.
506 </para>
507
508 <para>
509 At the same time, the bus daemons offer a number of features not found in
510 other IPC systems, such as single-owner "bus names" (similar to X
511 selections), on-demand startup of services, and security policies.
512 In many ways, these features are the primary motivation for developing
513 D-Bus; other systems would have sufficed if IPC were the only goal.
514 </para>
515
516 <para>
517 D-Bus may turn out to be useful in unanticipated applications, but future
518 versions of this spec and the reference implementation probably will not
519 incorporate features that interfere with the core use cases.
520 </para>
521
522 <para>
523 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
524 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
525 document are to be interpreted as described in RFC 2119. However, the
526 document could use a serious audit to be sure it makes sense to do
527 so. Also, they are not capitalized.
528 </para>
529
530 <sect2 id="stability">
531 <title>Protocol and Specification Stability</title>
532 <para>
533 The D-Bus protocol is frozen (only compatible extensions are allowed) as
534 of November 8, 2006. However, this specification could still use a fair
535 bit of work to make interoperable reimplementation possible without
536 reference to the D-Bus reference implementation. Thus, this
537 specification is not marked 1.0. To mark it 1.0, we'd like to see
538 someone invest significant effort in clarifying the specification
539 language, and growing the specification to cover more aspects of the
540 reference implementation's behavior.
541 </para>
542 <para>
543 Until this work is complete, any attempt to reimplement D-Bus will
544 probably require looking at the reference implementation and/or asking
545 questions on the D-Bus mailing list about intended behavior.
546 Questions on the list are very welcome.
547 </para>
548 <para>
549 Nonetheless, this document should be a useful starting point and is
550 to our knowledge accurate, though incomplete.
551 </para>
552 </sect2>
553
554 </sect1>
555
556 <sect1 id="type-system">
557 <title>Type System</title>
558
559 <para>
560 D-Bus has a type system, in which values of various types can be
561 serialized into a sequence of bytes referred to as the
562 <firstterm>wire format</firstterm> in a standard way.
563 Converting a value from some other representation into the wire
564 format is called <firstterm>marshaling</firstterm> and converting
565 it back from the wire format is <firstterm>unmarshaling</firstterm>.
566 </para>
567
568 <para>
569 The D-Bus protocol does not include type tags in the marshaled data; a
570 block of marshaled values must have a known <firstterm>type
571 signature</firstterm>. The type signature is made up of zero or more
572 <firstterm id="term-single-complete-type">single complete
573 types</firstterm>, each made up of one or more
574 <firstterm>type codes</firstterm>.
575 </para>
576
577 <para>
578 A type code is an ASCII character representing the
579 type of a value. Because ASCII characters are used, the type signature
580 will always form a valid ASCII string. A simple string compare
581 determines whether two type signatures are equivalent.
582 </para>
583
584 <para>
585 A single complete type is a sequence of type codes that fully describes
586 one type: either a basic type, or a single fully-described container type.
587 A single complete type is a basic type code, a variant type code,
588 an array with its element type, or a struct with its fields (all of which
589 are defined below). So the following signatures are not single complete
590 types:
591 <programlisting>
592 "aa"
593 </programlisting>
594 <programlisting>
595 "(ii"
596 </programlisting>
597 <programlisting>
598 "ii)"
599 </programlisting>
600 And the following signatures contain multiple complete types:
601 <programlisting>
602 "ii"
603 </programlisting>
604 <programlisting>
605 "aiai"
606 </programlisting>
607 <programlisting>
608 "(ii)(ii)"
609 </programlisting>
610 Note however that a single complete type may <emphasis>contain</emphasis>
611 multiple other single complete types, by containing a struct or dict
612 entry.
613 </para>
614
615 <sect2 id="basic-types">
616 <title>Basic types</title>
617
618 <para>
619 The simplest type codes are the <firstterm id="term-basic-type">basic
620 types</firstterm>, which are the types whose structure is entirely
621 defined by their 1-character type code. Basic types consist of
622 fixed types and string-like types.
623 </para>
624
625 <para>
626 The <firstterm id="term-fixed-type">fixed types</firstterm>
627 are basic types whose values have a fixed length, namely BYTE,
628 BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length
629 16, 32 or 64 bits.
630 </para>
631
632 <para>
633 As a simple example, the type code for 32-bit integer (<literal>INT32</literal>) is
634 the ASCII character 'i'. So the signature for a block of values
635 containing a single <literal>INT32</literal> would be:
636 <programlisting>
637 "i"
638 </programlisting>
639 A block of values containing two <literal>INT32</literal> would have this signature:
640 <programlisting>
641 "ii"
642 </programlisting>
643 </para>
644
645 <para>
646 The characteristics of the fixed types are listed in this table.
647
648 <informaltable>
649 <tgroup cols="3">
650 <thead>
651 <row>
652 <entry>Conventional name</entry>
653 <entry>ASCII type-code</entry>
654 <entry>Encoding</entry>
655 </row>
656 </thead>
657 <tbody>
658 <row>
659 <entry><literal>BYTE</literal></entry>
660 <entry><literal>y</literal> (121)</entry>
661 <entry>Unsigned 8-bit integer</entry>
662 </row>
663 <row>
664 <entry><literal>BOOLEAN</literal></entry>
665 <entry><literal>b</literal> (98)</entry>
666 <entry>Boolean value: 0 is false, 1 is true, any other value
667 allowed by the marshalling format is invalid</entry>
668 </row>
669 <row>
670 <entry><literal>INT16</literal></entry>
671 <entry><literal>n</literal> (110)</entry>
672 <entry>Signed (two's complement) 16-bit integer</entry>
673 </row>
674 <row>
675 <entry><literal>UINT16</literal></entry>
676 <entry><literal>q</literal> (113)</entry>
677 <entry>Unsigned 16-bit integer</entry>
678 </row>
679 <row>
680 <entry><literal>INT32</literal></entry>
681 <entry><literal>i</literal> (105)</entry>
682 <entry>Signed (two's complement) 32-bit integer</entry>
683 </row>
684 <row>
685 <entry><literal>UINT32</literal></entry>
686 <entry><literal>u</literal> (117)</entry>
687 <entry>Unsigned 32-bit integer</entry>
688 </row>
689 <row>
690 <entry><literal>INT64</literal></entry>
691 <entry><literal>x</literal> (120)</entry>
692 <entry>Signed (two's complement) 64-bit integer
693 (mnemonic: x and t are the first characters in "sixty" not
694 already used for something more common)</entry>
695 </row>
696 <row>
697 <entry><literal>UINT64</literal></entry>
698 <entry><literal>t</literal> (116)</entry>
699 <entry>Unsigned 64-bit integer</entry>
700 </row>
701 <row>
702 <entry><literal>DOUBLE</literal></entry>
703 <entry><literal>d</literal> (100)</entry>
704 <entry>IEEE 754 double-precision floating point</entry>
705 </row>
706 <row>
707 <entry><literal>UNIX_FD</literal></entry>
708 <entry><literal>h</literal> (104)</entry>
709 <entry>Unsigned 32-bit integer representing an index into an
710 out-of-band array of file descriptors, transferred via some
711 platform-specific mechanism (mnemonic: h for handle)</entry>
712 </row>
713 </tbody>
714 </tgroup>
715 </informaltable>
716 </para>
717
718 <para>
719 The <firstterm id="term-string-like-type">string-like types</firstterm>
720 are basic types with a variable length. The value of any string-like
721 type is conceptually 0 or more Unicode codepoints encoded in UTF-8,
722 none of which may be U+0000. The UTF-8 text must be validated
723 strictly: in particular, it must not contain overlong sequences
724 or codepoints above U+10FFFF.
725 </para>
726
727 <para>
728 Since D-Bus Specification version 0.21, in accordance with Unicode
729 Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and
730 U+nFFFF are allowed in UTF-8 strings (but note that older versions of
731 D-Bus rejected these noncharacters).
732 </para>
733
734 <para>
735 The marshalling formats for the string-like types all end with a
736 single zero (NUL) byte, but that byte is not considered to be part of
737 the text.
738 </para>
739
740 <para>
741 The characteristics of the string-like types are listed in this table.
742
743 <informaltable>
744 <tgroup cols="3">
745 <thead>
746 <row>
747 <entry>Conventional name</entry>
748 <entry>ASCII type-code</entry>
749 <entry>Validity constraints</entry>
750 </row>
751 </thead>
752 <tbody>
753 <row>
754 <entry><literal>STRING</literal></entry>
755 <entry><literal>s</literal> (115)</entry>
756 <entry>No extra constraints</entry>
757 </row>
758 <row>
759 <entry><literal>OBJECT_PATH</literal></entry>
760 <entry><literal>o</literal> (111)</entry>
761 <entry>Must be
762 <link linkend="message-protocol-marshaling-object-path">a
763 syntactically valid object path</link></entry>
764 </row>
765 <row>
766 <entry><literal>SIGNATURE</literal></entry>
767 <entry><literal>g</literal> (103)</entry>
768 <entry>Zero or more
769 <firstterm linkend="term-single-complete-type">single
770 complete types</firstterm></entry>
771 </row>
772 </tbody>
773 </tgroup>
774 </informaltable>
775 </para>
776
777 <sect3 id="message-protocol-marshaling-object-path">
778 <title>Valid Object Paths</title>
779
780 <para>
781 An object path is a name used to refer to an object instance.
782 Conceptually, each participant in a D-Bus message exchange may have
783 any number of object instances (think of C++ or Java objects) and each
784 such instance will have a path. Like a filesystem, the object
785 instances in an application form a hierarchical tree.
786 </para>
787
788 <para>
789 Object paths are often namespaced by starting with a reversed
790 domain name and containing an interface version number, in the
791 same way as
792 <link linkend="message-protocol-names-interface">interface
793 names</link> and
794 <link linkend="message-protocol-names-bus">well-known
795 bus names</link>.
796 This makes it possible to implement more than one service, or
797 more than one version of a service, in the same process,
798 even if the services share a connection but cannot otherwise
799 co-operate (for instance, if they are implemented by different
800 plugins).
801 </para>
802
803 <para>
804 Using an object path of <literal>/</literal> is allowed, but
805 recommended against, as it makes versioning of interfaces hard. Any
806 signals emitted from a D-Bus object have the service’s unique bus name
807 associated with them, rather than its well-known name. This means that
808 receipients of the signals must rely entirely on the signal name and
809 object path to work out which interface the signal originated from.
810 </para>
811
812 <para>
813 For instance, if the owner of <literal>example.com</literal> is
814 developing a D-Bus API for a music player, they might use the
815 hierarchy of object paths that start with
816 <literal>/com/example/MusicPlayer1</literal> for its objects.
817 </para>
818
819 <para>
820 The following rules define a valid object path. Implementations must
821 not send or accept messages with invalid object paths.
822 <itemizedlist>
823 <listitem>
824 <para>
825 The path may be of any length.
826 </para>
827 </listitem>
828 <listitem>
829 <para>
830 The path must begin with an ASCII '/' (integer 47) character,
831 and must consist of elements separated by slash characters.
832 </para>
833 </listitem>
834 <listitem>
835 <para>
836 Each element must only contain the ASCII characters
837 "[A-Z][a-z][0-9]_"
838 </para>
839 </listitem>
840 <listitem>
841 <para>
842 No element may be the empty string.
843 </para>
844 </listitem>
845 <listitem>
846 <para>
847 Multiple '/' characters cannot occur in sequence.
848 </para>
849 </listitem>
850 <listitem>
851 <para>
852 A trailing '/' character is not allowed unless the
853 path is the root path (a single '/' character).
854 </para>
855 </listitem>
856 </itemizedlist>
857 </para>
858
859 </sect3>
860
861 <sect3 id="message-protocol-marshaling-signature">
862 <title>Valid Signatures</title>
863 <para>
864 An implementation must not send or accept invalid signatures.
865 Valid signatures will conform to the following rules:
866 <itemizedlist>
867 <listitem>
868 <para>
869 The signature is a list of single complete types.
870 Arrays must have element types, and structs must
871 have both open and close parentheses.
872 </para>
873 </listitem>
874 <listitem>
875 <para>
876 Only type codes, open and close parentheses, and open and
877 close curly brackets are allowed in the signature. The
878 <literal>STRUCT</literal> type code
879 is not allowed in signatures, because parentheses
880 are used instead. Similarly, the
881 <literal>DICT_ENTRY</literal> type code is not allowed in
882 signatures, because curly brackets are used instead.
883 </para>
884 </listitem>
885 <listitem>
886 <para>
887 The maximum depth of container type nesting is 32 array type
888 codes and 32 open parentheses. This implies that the maximum
889 total depth of recursion is 64, for an "array of array of array
890 of ... struct of struct of struct of ..." where there are 32
891 array and 32 struct.
892 </para>
893 </listitem>
894 <listitem>
895 <para>
896 The maximum length of a signature is 255.
897 </para>
898 </listitem>
899 </itemizedlist>
900 </para>
901
902 <para>
903 When signatures appear in messages, the marshalling format
904 guarantees that they will be followed by a nul byte (which can
905 be interpreted as either C-style string termination or the INVALID
906 type-code), but this is not conceptually part of the signature.
907 </para>
908 </sect3>
909
910 </sect2>
911
912 <sect2 id="container-types">
913 <title>Container types</title>
914
915 <para>
916 In addition to basic types, there are four <firstterm>container</firstterm>
917 types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
918 and <literal>DICT_ENTRY</literal>.
919 </para>
920
921 <para>
922 <literal>STRUCT</literal> has a type code, ASCII character 'r', but this type
923 code does not appear in signatures. Instead, ASCII characters
924 '(' and ')' are used to mark the beginning and end of the struct.
925 So for example, a struct containing two integers would have this
926 signature:
927 <programlisting>
928 "(ii)"
929 </programlisting>
930 Structs can be nested, so for example a struct containing
931 an integer and another struct:
932 <programlisting>
933 "(i(ii))"
934 </programlisting>
935 The value block storing that struct would contain three integers; the
936 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
937 "(iii)" or "iii".
938 </para>
939
940 <para>
941 The <literal>STRUCT</literal> type code 'r' is not currently used in the D-Bus protocol,
942 but is useful in code that implements the protocol. This type code
943 is specified to allow such code to interoperate in non-protocol contexts.
944 </para>
945
946 <para>
947 Empty structures are not allowed; there must be at least one
948 type code between the parentheses.
949 </para>
950
951 <para>
952 <literal>ARRAY</literal> has ASCII character 'a' as type code. The array type code must be
953 followed by a <firstterm>single complete type</firstterm>. The single
954 complete type following the array is the type of each array element. So
955 the simple example is:
956 <programlisting>
957 "ai"
958 </programlisting>
959 which is an array of 32-bit integers. But an array can be of any type,
960 such as this array-of-struct-with-two-int32-fields:
961 <programlisting>
962 "a(ii)"
963 </programlisting>
964 Or this array of array of integer:
965 <programlisting>
966 "aai"
967 </programlisting>
968 </para>
969
970 <para>
971 <literal>VARIANT</literal> has ASCII character 'v' as its type code. A marshaled value of
972 type <literal>VARIANT</literal> will have the signature of a single complete type as part
973 of the <emphasis>value</emphasis>. This signature will be followed by a
974 marshaled value of that type.
975 </para>
976
977 <para>
978 Unlike a message signature, the variant signature can
979 contain only a single complete type. So "i", "ai"
980 or "(ii)" is OK, but "ii" is not. Use of variants may not
981 cause a total message depth to be larger than 64, including
982 other container types such as structures.
983 </para>
984
985 <para>
986 A <literal>DICT_ENTRY</literal> works exactly like a struct, but rather
987 than parentheses it uses curly braces, and it has more restrictions.
988 The restrictions are: it occurs only as an array element type; it has
989 exactly two single complete types inside the curly braces; the first
990 single complete type (the "key") must be a basic type rather than a
991 container type. Implementations must not accept dict entries outside of
992 arrays, must not accept dict entries with zero, one, or more than two
993 fields, and must not accept dict entries with non-basic-typed keys. A
994 dict entry is always a key-value pair.
995 </para>
996
997 <para>
998 The first field in the <literal>DICT_ENTRY</literal> is always the key.
999 A message is considered corrupt if the same key occurs twice in the same
1000 array of <literal>DICT_ENTRY</literal>. However, for performance reasons
1001 implementations are not required to reject dicts with duplicate keys.
1002 </para>
1003
1004 <para>
1005 In most languages, an array of dict entry would be represented as a
1006 map, hash table, or dict object.
1007 </para>
1008 </sect2>
1009
1010 <sect2>
1011 <title>Summary of types</title>
1012
1013 <para>
1014 The following table summarizes the D-Bus types.
1015 <informaltable>
1016 <tgroup cols="3">
1017 <thead>
1018 <row>
1019 <entry>Category</entry>
1020 <entry>Conventional Name</entry>
1021 <entry>Code</entry>
1022 <entry>Description</entry>
1023 </row>
1024 </thead>
1025 <tbody>
1026 <row>
1027 <entry>reserved</entry>
1028 <entry><literal>INVALID</literal></entry>
1029 <entry>0 (ASCII NUL)</entry>
1030 <entry>Not a valid type code, used to terminate signatures</entry>
1031 </row><row>
1032 <entry>fixed, basic</entry>
1033 <entry><literal>BYTE</literal></entry>
1034 <entry>121 (ASCII 'y')</entry>
1035 <entry>8-bit unsigned integer</entry>
1036 </row><row>
1037 <entry>fixed, basic</entry>
1038 <entry><literal>BOOLEAN</literal></entry>
1039 <entry>98 (ASCII 'b')</entry>
1040 <entry>Boolean value, 0 is <literal>FALSE</literal> and 1 is <literal>TRUE</literal>. Everything else is invalid.</entry>
1041 </row><row>
1042 <entry>fixed, basic</entry>
1043 <entry><literal>INT16</literal></entry>
1044 <entry>110 (ASCII 'n')</entry>
1045 <entry>16-bit signed integer</entry>
1046 </row><row>
1047 <entry>fixed, basic</entry>
1048 <entry><literal>UINT16</literal></entry>
1049 <entry>113 (ASCII 'q')</entry>
1050 <entry>16-bit unsigned integer</entry>
1051 </row><row>
1052 <entry>fixed, basic</entry>
1053 <entry><literal>INT32</literal></entry>
1054 <entry>105 (ASCII 'i')</entry>
1055 <entry>32-bit signed integer</entry>
1056 </row><row>
1057 <entry>fixed, basic</entry>
1058 <entry><literal>UINT32</literal></entry>
1059 <entry>117 (ASCII 'u')</entry>
1060 <entry>32-bit unsigned integer</entry>
1061 </row><row>
1062 <entry>fixed, basic</entry>
1063 <entry><literal>INT64</literal></entry>
1064 <entry>120 (ASCII 'x')</entry>
1065 <entry>64-bit signed integer</entry>
1066 </row><row>
1067 <entry>fixed, basic</entry>
1068 <entry><literal>UINT64</literal></entry>
1069 <entry>116 (ASCII 't')</entry>
1070 <entry>64-bit unsigned integer</entry>
1071 </row><row>
1072 <entry>fixed, basic</entry>
1073 <entry><literal>DOUBLE</literal></entry>
1074 <entry>100 (ASCII 'd')</entry>
1075 <entry>IEEE 754 double</entry>
1076 </row><row>
1077 <entry>string-like, basic</entry>
1078 <entry><literal>STRING</literal></entry>
1079 <entry>115 (ASCII 's')</entry>
1080 <entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</entry>
1081 </row><row>
1082 <entry>string-like, basic</entry>
1083 <entry><literal>OBJECT_PATH</literal></entry>
1084 <entry>111 (ASCII 'o')</entry>
1085 <entry>Name of an object instance</entry>
1086 </row><row>
1087 <entry>string-like, basic</entry>
1088 <entry><literal>SIGNATURE</literal></entry>
1089 <entry>103 (ASCII 'g')</entry>
1090 <entry>A type signature</entry>
1091 </row><row>
1092 <entry>container</entry>
1093 <entry><literal>ARRAY</literal></entry>
1094 <entry>97 (ASCII 'a')</entry>
1095 <entry>Array</entry>
1096 </row><row>
1097 <entry>container</entry>
1098 <entry><literal>STRUCT</literal></entry>
1099 <entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
1100 <entry>Struct; type code 114 'r' is reserved for use in
1101 bindings and implementations to represent the general
1102 concept of a struct, and must not appear in signatures
1103 used on D-Bus.</entry>
1104 </row><row>
1105 <entry>container</entry>
1106 <entry><literal>VARIANT</literal></entry>
1107 <entry>118 (ASCII 'v') </entry>
1108 <entry>Variant type (the type of the value is part of the value itself)</entry>
1109 </row><row>
1110 <entry>container</entry>
1111 <entry><literal>DICT_ENTRY</literal></entry>
1112 <entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
1113 <entry>Entry in a dict or map (array of key-value pairs).
1114 Type code 101 'e' is reserved for use in bindings and
1115 implementations to represent the general concept of a
1116 dict or dict-entry, and must not appear in signatures
1117 used on D-Bus.</entry>
1118 </row><row>
1119 <entry>fixed, basic</entry>
1120 <entry><literal>UNIX_FD</literal></entry>
1121 <entry>104 (ASCII 'h')</entry>
1122 <entry>Unix file descriptor</entry>
1123 </row>
1124 <row>
1125 <entry>reserved</entry>
1126 <entry>(reserved)</entry>
1127 <entry>109 (ASCII 'm')</entry>
1128 <entry>Reserved for <ulink
1129 url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
1130 'maybe' type compatible with the one in GVariant</ulink>,
1131 and must not appear in signatures used on D-Bus until
1132 specified here</entry>
1133 </row>
1134 <row>
1135 <entry>reserved</entry>
1136 <entry>(reserved)</entry>
1137 <entry>42 (ASCII '*')</entry>
1138 <entry>Reserved for use in bindings/implementations to
1139 represent any <firstterm>single complete type</firstterm>,
1140 and must not appear in signatures used on D-Bus.</entry>
1141 </row>
1142 <row>
1143 <entry>reserved</entry>
1144 <entry>(reserved)</entry>
1145 <entry>63 (ASCII '?')</entry>
1146 <entry>Reserved for use in bindings/implementations to
1147 represent any <firstterm>basic type</firstterm>, and must
1148 not appear in signatures used on D-Bus.</entry>
1149 </row>
1150 <row>
1151 <entry>reserved</entry>
1152 <entry>(reserved)</entry>
1153 <entry>64 (ASCII '@'), 38 (ASCII '&amp;'),
1154 94 (ASCII '^')</entry>
1155 <entry>Reserved for internal use by bindings/implementations,
1156 and must not appear in signatures used on D-Bus.
1157 GVariant uses these type-codes to encode calling
1158 conventions.</entry>
1159 </row>
1160 </tbody>
1161 </tgroup>
1162 </informaltable>
1163 </para>
1164
1165 </sect2>
1166 </sect1>
1167
1168 <sect1 id="message-protocol-marshaling">
1169 <title>Marshaling (Wire Format)</title>
1170
1171 <para>
1172 D-Bus defines a marshalling format for its type system, which is
1173 used in D-Bus messages. This is not the only possible marshalling
1174 format for the type system: for instance, GVariant (part of GLib)
1175 re-uses the D-Bus type system but implements an alternative marshalling
1176 format.
1177 </para>
1178
1179 <sect2>
1180 <title>Byte order and alignment</title>
1181
1182 <para>
1183 Given a type signature, a block of bytes can be converted into typed
1184 values. This section describes the format of the block of bytes. Byte
1185 order and alignment issues are handled uniformly for all D-Bus types.
1186 </para>
1187
1188 <para>
1189 A block of bytes has an associated byte order. The byte order
1190 has to be discovered in some way; for D-Bus messages, the
1191 byte order is part of the message header as described in
1192 <xref linkend="message-protocol-messages"/>. For now, assume
1193 that the byte order is known to be either little endian or big
1194 endian.
1195 </para>
1196
1197 <para>
1198 Each value in a block of bytes is aligned "naturally," for example
1199 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
1200 8-byte boundary. Boundaries are calculated globally, with respect to
1201 the first byte in the message. To properly align a value,
1202 <firstterm>alignment padding</firstterm> may be necessary before the
1203 value. The alignment padding must always
1204 be the minimum required padding to properly align the following value;
1205 and it must always be made up of nul bytes. The alignment padding must
1206 not be left uninitialized (it can't contain garbage), and more padding
1207 than required must not be used.
1208 </para>
1209
1210 <para>
1211 As an exception to natural alignment, <literal>STRUCT</literal> and
1212 <literal>DICT_ENTRY</literal> values are always aligned to an 8-byte
1213 boundary, regardless of the alignments of their contents.
1214 </para>
1215 </sect2>
1216
1217 <sect2>
1218 <title>Marshalling basic types</title>
1219
1220 <para>
1221 To marshal and unmarshal fixed types, you simply read one value
1222 from the data block corresponding to each type code in the signature.
1223 All signed integer values are encoded in two's complement, DOUBLE
1224 values are IEEE 754 double-precision floating-point, and BOOLEAN
1225 values are encoded in 32 bits (of which only the least significant
1226 bit is used).
1227 </para>
1228
1229 <para>
1230 The string-like types (STRING, OBJECT_PATH and SIGNATURE) are all
1231 marshalled as a
1232 fixed-length unsigned integer <varname>n</varname> giving the
1233 length of the variable part, followed by <varname>n</varname>
1234 nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
1235 which is not considered to be part of the text. The alignment
1236 of the string-like type is the same as the alignment of
1237 <varname>n</varname>: any padding required for <varname>n</varname>
1238 appears immediately before <varname>n</varname> itself. There is never
1239 any alignment padding between <varname>n</varname> and the string text,
1240 or between the string text and the trailing nul. The alignment padding
1241 for the next value in the message (if there is one) starts after the
1242 trailing nul.
1243 </para>
1244
1245 <para>
1246 For the STRING and OBJECT_PATH types, <varname>n</varname> is
1247 encoded in 4 bytes (a <literal>UINT32</literal>), leading to 4-byte
1248 alignment. For the SIGNATURE type, <varname>n</varname> is encoded as a
1249 single byte (a <literal>UINT8</literal>). As a result, alignment
1250 padding is never required before a SIGNATURE.
1251 </para>
1252
1253 <para>
1254 For example, if the current position is a multiple of 8 bytes from the
1255 beginning of a little-endian message, strings ‘foo’, ‘+’ and ‘bar’
1256 would be serialized in sequence as follows:
1257
1258 <screen>
1259 <lineannotation>no padding required, we are already at a multiple of 4</lineannotation>
1260 0x03 0x00 0x00 0x00 <lineannotation>length of ‘foo’ = 3</lineannotation>
1261 0x66 0x6f 0x6f <lineannotation>‘foo’</lineannotation>
1262 0x00 <lineannotation>trailing nul</lineannotation>
1263
1264 <lineannotation>no padding required, we are already at a multiple of 4</lineannotation>
1265 0x01 0x00 0x00 0x00 <lineannotation>length of ‘+’ = 1</lineannotation>
1266 0x2b <lineannotation>‘+’</lineannotation>
1267 0x00 <lineannotation>trailing nul</lineannotation>
1268
1269 0x00 0x00 <lineannotation>2 bytes of padding to reach next multiple of 4</lineannotation>
1270 0x03 0x00 0x00 0x00 <lineannotation>length of ‘bar’ = 3</lineannotation>
1271 0x62 0x61 0x72 <lineannotation>‘bar’</lineannotation>
1272 0x00 <lineannotation>trailing nul</lineannotation>
1273 </screen>
1274 </para>
1275 </sect2>
1276
1277 <sect2>
1278 <title>Marshalling containers</title>
1279
1280 <para>
1281 Arrays are marshalled as a <literal>UINT32</literal>
1282 <varname>n</varname> giving the length of the array data in bytes,
1283 followed by alignment padding to the alignment boundary of the array
1284 element type, followed by the <varname>n</varname> bytes of the
1285 array elements marshalled in sequence. <varname>n</varname> does not
1286 include the padding after the length, or any padding after the
1287 last element. i.e. <varname>n</varname> should be divisible by the
1288 number of elements in the array. Note that the alignment padding for the
1289 first element is required even if there is no first element (an
1290 empty array, where <varname>n</varname> is zero).
1291 </para>
1292
1293 <para>
1294 For instance, if the current position in the message is a multiple
1295 of 8 bytes and the byte-order is big-endian, an array containing only
1296 the 64-bit integer 5 would be marshalled as:
1297
1298 <screen>
1299 00 00 00 08 <lineannotation><varname>n</varname> = 8 bytes of data</lineannotation>
1300 00 00 00 00 <lineannotation>padding to 8-byte boundary</lineannotation>
1301 00 00 00 00 00 00 00 05 <lineannotation>first element = 5</lineannotation>
1302 </screen>
1303 </para>
1304
1305 <para>
1306 Arrays have a maximum length defined to be 2 to the 26th power or
1307 67108864 (64 MiB). Implementations must not send or accept arrays
1308 exceeding this length.
1309 </para>
1310
1311 <para>
1312 Structs and dict entries are marshalled in the same way as their
1313 contents, but their alignment is always to an 8-byte boundary,
1314 even if their contents would normally be less strictly aligned.
1315 </para>
1316
1317 <para>
1318 Variants are marshalled as the <literal>SIGNATURE</literal> of
1319 the contents (which must be a single complete type), followed by a
1320 marshalled value with the type given by that signature. The
1321 variant has the same 1-byte alignment as the signature, which means
1322 that alignment padding before a variant is never needed.
1323 Use of variants must not cause a total message depth to be larger
1324 than 64, including other container types such as structures.
1325 (See <link linkend="message-protocol-marshaling-signature">Valid
1326 Signatures</link>.)
1327 </para>
1328
1329 <para>
1330 It should be noted that while a variant itself does not require any
1331 alignment padding, the contained value does need to be padded
1332 according to the alignment rules of its type.
1333 </para>
1334
1335 <para>
1336 For instance, if the current position in the message is at a multiple of
1337 8 bytes and the byte-order is big-endian, a variant containing a 64-bit
1338 integer 5 would be marshalled as:
1339
1340 <screen>
1341 0x01 0x74 0x00 <lineannotation>signature bytes (length = 1, signature = 't' and trailing nul)</lineannotation>
1342 0x00 0x00 0x00 0x00 0x00 <lineannotation>padding to 8-byte boundary</lineannotation>
1343 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x05 <lineannotation>8 bytes of contained value</lineannotation>
1344 </screen>
1345 </para>
1346 </sect2>
1347
1348 <sect2>
1349 <title>Summary of D-Bus marshalling</title>
1350
1351 <para>
1352 Given all this, the types are marshaled on the wire as follows:
1353 <informaltable>
1354 <tgroup cols="3">
1355 <thead>
1356 <row>
1357 <entry>Conventional Name</entry>
1358 <entry>Encoding</entry>
1359 <entry>Alignment</entry>
1360 </row>
1361 </thead>
1362 <tbody>
1363 <row>
1364 <entry><literal>INVALID</literal></entry>
1365 <entry>Not applicable; cannot be marshaled.</entry>
1366 <entry>N/A</entry>
1367 </row><row>
1368 <entry><literal>BYTE</literal></entry>
1369 <entry>A single 8-bit byte.</entry>
1370 <entry>1</entry>
1371 </row><row>
1372 <entry><literal>BOOLEAN</literal></entry>
1373 <entry>As for <literal>UINT32</literal>, but only 0 and 1 are valid values.</entry>
1374 <entry>4</entry>
1375 </row><row>
1376 <entry><literal>INT16</literal></entry>
1377 <entry>16-bit signed integer in the message's byte order.</entry>
1378 <entry>2</entry>
1379 </row><row>
1380 <entry><literal>UINT16</literal></entry>
1381 <entry>16-bit unsigned integer in the message's byte order.</entry>
1382 <entry>2</entry>
1383 </row><row>
1384 <entry><literal>INT32</literal></entry>
1385 <entry>32-bit signed integer in the message's byte order.</entry>
1386 <entry>4</entry>
1387 </row><row>
1388 <entry><literal>UINT32</literal></entry>
1389 <entry>32-bit unsigned integer in the message's byte order.</entry>
1390 <entry>4</entry>
1391 </row><row>
1392 <entry><literal>INT64</literal></entry>
1393 <entry>64-bit signed integer in the message's byte order.</entry>
1394 <entry>8</entry>
1395 </row><row>
1396 <entry><literal>UINT64</literal></entry>
1397 <entry>64-bit unsigned integer in the message's byte order.</entry>
1398 <entry>8</entry>
1399 </row><row>
1400 <entry><literal>DOUBLE</literal></entry>
1401 <entry>64-bit IEEE 754 double in the message's byte order.</entry>
1402 <entry>8</entry>
1403 </row><row>
1404 <entry><literal>STRING</literal></entry>
1405 <entry>A <literal>UINT32</literal> indicating the string's
1406 length in bytes excluding its terminating nul, followed by
1407 non-nul string data of the given length, followed by a terminating nul
1408 byte.
1409 </entry>
1410 <entry>
1411 4 (for the length)
1412 </entry>
1413 </row><row>
1414 <entry><literal>OBJECT_PATH</literal></entry>
1415 <entry>Exactly the same as <literal>STRING</literal> except the
1416 content must be a valid object path (see above).
1417 </entry>
1418 <entry>
1419 4 (for the length)
1420 </entry>
1421 </row><row>
1422 <entry><literal>SIGNATURE</literal></entry>
1423 <entry>The same as <literal>STRING</literal> except the length is a single
1424 byte (thus signatures have a maximum length of 255)
1425 and the content must be a valid signature (see above).
1426 </entry>
1427 <entry>
1428 1
1429 </entry>
1430 </row><row>
1431 <entry><literal>ARRAY</literal></entry>
1432 <entry>
1433 A <literal>UINT32</literal> giving the length of the array data in bytes, followed by
1434 alignment padding to the alignment boundary of the array element type,
1435 followed by each array element.
1436 </entry>
1437 <entry>
1438 4 (for the length)
1439 </entry>
1440 </row><row>
1441 <entry><literal>STRUCT</literal></entry>
1442 <entry>
1443 A struct must start on an 8-byte boundary regardless of the
1444 type of the struct fields. The struct value consists of each
1445 field marshaled in sequence starting from that 8-byte
1446 alignment boundary.
1447 </entry>
1448 <entry>
1449 8
1450 </entry>
1451 </row><row>
1452 <entry><literal>VARIANT</literal></entry>
1453 <entry>
1454 The marshaled <literal>SIGNATURE</literal> of a single
1455 complete type, followed by a marshaled value with the type
1456 given in the signature.
1457 </entry>
1458 <entry>
1459 1 (alignment of the signature)
1460 </entry>
1461 </row><row>
1462 <entry><literal>DICT_ENTRY</literal></entry>
1463 <entry>
1464 Identical to STRUCT.
1465 </entry>
1466 <entry>
1467 8
1468 </entry>
1469 </row><row>
1470 <entry><literal>UNIX_FD</literal></entry>
1471 <entry>32-bit unsigned integer in the message's byte
1472 order. The actual file descriptors need to be
1473 transferred out-of-band via some platform specific
1474 mechanism. On the wire, values of this type store the index to the
1475 file descriptor in the array of file descriptors that
1476 accompany the message.</entry>
1477 <entry>4</entry>
1478 </row>
1479 </tbody>
1480 </tgroup>
1481 </informaltable>
1482 </para>
1483
1484 </sect2>
1485
1486 </sect1>
1487
1488 <sect1 id="message-protocol">
1489 <title>Message Protocol</title>
1490
1491 <para>
1492 A <firstterm>message</firstterm> consists of a
1493 <firstterm>header</firstterm> and a <firstterm>body</firstterm>. If you
1494 think of a message as a package, the header is the address, and the body
1495 contains the package contents. The message delivery system uses the header
1496 information to figure out where to send the message and how to interpret
1497 it; the recipient interprets the body of the message.
1498 </para>
1499
1500 <para>
1501 The body of the message is made up of zero or more
1502 <firstterm>arguments</firstterm>, which are typed values, such as an
1503 integer or a byte array.
1504 </para>
1505
1506 <para>
1507 Both header and body use the D-Bus <link linkend="type-system">type
1508 system</link> and format for serializing data.
1509 </para>
1510
1511 <sect2 id="message-protocol-messages">
1512 <title>Message Format</title>
1513
1514 <para>
1515 A message consists of a header and a body. The header is a block of
1516 values with a fixed signature and meaning. The body is a separate block
1517 of values, with a signature specified in the header.
1518 </para>
1519
1520 <para>
1521 The length of the header must be a multiple of 8, allowing the body to
1522 begin on an 8-byte boundary when storing the entire message in a single
1523 buffer. If the header does not naturally end on an 8-byte boundary
1524 up to 7 bytes of nul-initialized alignment padding must be added.
1525 </para>
1526
1527 <para>
1528 The message body need not end on an 8-byte boundary.
1529 </para>
1530
1531 <para>
1532 The maximum length of a message, including header, header alignment padding,
1533 and body is 2 to the 27th power or 134217728 (128 MiB).
1534 Implementations must not send or accept messages exceeding this size.
1535 </para>
1536
1537 <para>
1538 The signature of the header is:
1539 <programlisting>
1540 "yyyyuua(yv)"
1541 </programlisting>
1542 Written out more readably, this is:
1543 <programlisting>
1544 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
1545 </programlisting>
1546 </para>
1547
1548 <para>
1549 These values have the following meanings:
1550 <informaltable>
1551 <tgroup cols="2">
1552 <thead>
1553 <row>
1554 <entry>Value</entry>
1555 <entry>Description</entry>
1556 </row>
1557 </thead>
1558 <tbody>
1559 <row>
1560 <entry>1st <literal>BYTE</literal></entry>
1561 <entry>Endianness flag; ASCII 'l' for little-endian
1562 or ASCII 'B' for big-endian. Both header and body are
1563 in this endianness.</entry>
1564 </row>
1565 <row>
1566 <entry>2nd <literal>BYTE</literal></entry>
1567 <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
1568 Currently-defined types are described below.
1569 </entry>
1570 </row>
1571 <row>
1572 <entry>3rd <literal>BYTE</literal></entry>
1573 <entry>Bitwise OR of flags. Unknown flags
1574 must be ignored. Currently-defined flags are described below.
1575 </entry>
1576 </row>
1577 <row>
1578 <entry>4th <literal>BYTE</literal></entry>
1579 <entry>Major protocol version of the sending application. If
1580 the major protocol version of the receiving application does not
1581 match, the applications will not be able to communicate and the
1582 D-Bus connection must be disconnected. The major protocol
1583 version for this version of the specification is 1.
1584 </entry>
1585 </row>
1586 <row>
1587 <entry>1st <literal>UINT32</literal></entry>
1588 <entry>Length in bytes of the message body, starting
1589 from the end of the header. The header ends after
1590 its alignment padding to an 8-boundary.
1591 </entry>
1592 </row>
1593 <row>
1594 <entry>2nd <literal>UINT32</literal></entry>
1595 <entry>The serial of this message, used as a cookie
1596 by the sender to identify the reply corresponding
1597 to this request. This must not be zero.
1598 </entry>
1599 </row>
1600 <row>
1601 <entry><literal>ARRAY</literal> of <literal>STRUCT</literal> of (<literal>BYTE</literal>,<literal>VARIANT</literal>)</entry>
1602 <entry>An array of zero or more <firstterm>header
1603 fields</firstterm> where the byte is the field code, and the
1604 variant is the field value. The message type determines
1605 which fields are required.
1606 </entry>
1607 </row>
1608 </tbody>
1609 </tgroup>
1610 </informaltable>
1611 </para>
1612 <para>
1613 <firstterm>Message types</firstterm> that can appear in the second byte
1614 of the header are:
1615 <informaltable>
1616 <tgroup cols="3">
1617 <thead>
1618 <row>
1619 <entry>Conventional name</entry>
1620 <entry>Decimal value</entry>
1621 <entry>Description</entry>
1622 </row>
1623 </thead>
1624 <tbody>
1625 <row>
1626 <entry><literal>INVALID</literal></entry>
1627 <entry>0</entry>
1628 <entry>This is an invalid type.</entry>
1629 </row>
1630 <row>
1631 <entry><literal>METHOD_CALL</literal></entry>
1632 <entry>1</entry>
1633 <entry>Method call. This message type may prompt a
1634 reply.</entry>
1635 </row>
1636 <row>
1637 <entry><literal>METHOD_RETURN</literal></entry>
1638 <entry>2</entry>
1639 <entry>Method reply with returned data.</entry>
1640 </row>
1641 <row>
1642 <entry><literal>ERROR</literal></entry>
1643 <entry>3</entry>
1644 <entry>Error reply. If the first argument exists and is a
1645 string, it is an error message.</entry>
1646 </row>
1647 <row>
1648 <entry><literal>SIGNAL</literal></entry>
1649 <entry>4</entry>
1650 <entry>Signal emission.</entry>
1651 </row>
1652 </tbody>
1653 </tgroup>
1654 </informaltable>
1655 </para>
1656 <para>
1657 Flags that can appear in the third byte of the header:
1658 <informaltable>
1659 <tgroup cols="3">
1660 <thead>
1661 <row>
1662 <entry>Conventional name</entry>
1663 <entry>Hex value</entry>
1664 <entry>Description</entry>
1665 </row>
1666 </thead>
1667 <tbody>
1668 <row>
1669 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
1670 <entry>0x1</entry>
1671 <entry>
1672 <para>
1673 This message does not expect method return replies or
1674 error replies, even if it is of a type that can
1675 have a reply; the reply should be omitted.
1676 </para>
1677 <para>
1678 Note that METHOD_CALL is the only message type currently
1679 defined in this specification that can expect a reply,
1680 so the presence or absence of this flag in the other
1681 three message types that are currently
1682 documented is meaningless: replies to those message
1683 types should not be sent, whether this flag is present
1684 or not.
1685 </para>
1686 </entry>
1687 </row>
1688 <row>
1689 <entry><literal>NO_AUTO_START</literal></entry>
1690 <entry>0x2</entry>
1691 <entry>The bus must not launch an owner
1692 for the destination name in response to this message.
1693 </entry>
1694 </row>
1695 <row>
1696 <entry><literal>ALLOW_INTERACTIVE_AUTHORIZATION</literal></entry>
1697 <entry>0x4</entry>
1698 <entry>
1699 <para>
1700 This flag may be set on a method call message to
1701 inform the receiving side that the caller is prepared
1702 to wait for interactive authorization, which might
1703 take a considerable time to complete. For instance,
1704 if this flag is set, it would be appropriate to
1705 query the user for passwords or confirmation via
1706 Polkit or a similar framework.
1707 </para>
1708 <para>
1709 This flag is only useful when
1710 unprivileged code calls a more privileged method call,
1711 and an authorization framework is deployed that allows
1712 possibly interactive authorization. If no such framework
1713 is deployed it has no effect. This flag should not
1714 be set by default by client implementations. If it is
1715 set, the caller should also set a suitably long timeout
1716 on the method call to make sure the user interaction
1717 may complete. This flag is only valid for method call
1718 messages, and shall be ignored otherwise.
1719 </para>
1720 <para>
1721 Interaction that takes place as a part of the
1722 effect of the method being called is outside the scope
1723 of this flag, even if it could also be characterized
1724 as authentication or authorization. For instance, in
1725 a method call that directs a network management service
1726 to attempt to connect to a virtual private network,
1727 this flag should control how the network management
1728 service makes the decision "is this user allowed to
1729 change system network configuration?", but it should
1730 not affect how or whether the network management
1731 service interacts with the user to obtain the credentials
1732 that are required for access to the VPN.
1733 </para>
1734 <para>
1735 If a this flag is not set on a method call, and a
1736 service determines that the requested operation is
1737 not allowed without interactive authorization, but
1738 could be allowed after successful interactive
1739 authorization, it may return the
1740 <literal>org.freedesktop.DBus.Error.InteractiveAuthorizationRequired</literal>
1741 error.
1742 </para>
1743 <para>
1744 The absence of this flag does not guarantee that
1745 interactive authorization will not be applied, since
1746 existing services that pre-date this flag might
1747 already use interactive authorization. However,
1748 existing D-Bus APIs that will use interactive
1749 authorization should document that the call may take
1750 longer than usual, and new D-Bus APIs should avoid
1751 interactive authorization in the absence of this flag.
1752 </para>
1753 </entry>
1754 </row>
1755 </tbody>
1756 </tgroup>
1757 </informaltable>
1758 </para>
1759
1760 <sect3 id="message-protocol-header-fields">
1761 <title>Header Fields</title>
1762
1763 <para>
1764 The array at the end of the header contains <firstterm>header
1765 fields</firstterm>, where each field is a 1-byte field code followed
1766 by a field value. A header must contain the required header fields for
1767 its message type, and zero or more of any optional header
1768 fields. Future versions of this protocol specification may add new
1769 fields. Implementations must not invent their own header fields;
1770 only changes to this specification may introduce new header fields.
1771 </para>
1772
1773 <para>
1774 If an implementation sees a header field code that it does not
1775 expect, it must accept and ignore that field, as it will be part
1776 of a new
1777 (but compatible) version of this specification. This also applies
1778 to known header fields appearing in unexpected messages, for
1779 example: if a signal has a reply serial it must be ignored
1780 even though it has no meaning as of this version of the spec.
1781 </para>
1782
1783 <para>
1784 However, implementations must not send or accept known header fields
1785 with the wrong type stored in the field value. So for example a
1786 message with an <literal>INTERFACE</literal> field of type
1787 <literal>UINT32</literal> would be considered corrupt.
1788 </para>
1789
1790 <para>
1791 Server implementations that might relay messages from one
1792 mutually-distrustful client to another, such as the message
1793 bus, should remove header fields that the server does not
1794 recognise. However, a client must assume that the server has
1795 not done so, unless it has evidence to the contrary,
1796 such as having checked for the <literal>HeaderFiltering</literal>
1797 <link linkend="message-bus-properties-features">message bus
1798 feature</link>.
1799 </para>
1800
1801 <para>
1802 New header fields controlled by the message bus
1803 (similar to <literal>SENDER</literal>) might be added to this
1804 specification in future. Such message fields should normally
1805 only be added to messages that are going to be delivered to a
1806 client that specifically requested them (for example by calling
1807 some method), and the message bus should remove those header
1808 fields from all other messages that it relays. This design
1809 principle serves two main purposes. One is to avoid unnecessary
1810 memory and throughput overhead when delivering messages to
1811 clients that are not interested in the new header fields.
1812 The other is to give clients a reason to call the method that
1813 requests those messages (otherwise, the clients would not work).
1814 This is desirable because looking at the reply to that method
1815 call is a natural way to check that the message bus guarantees
1816 to filter out faked header fields that might have been sent by
1817 malicious peers.
1818 </para>
1819
1820 <para>
1821 Here are the currently-defined header fields:
1822 <informaltable>
1823 <tgroup cols="5">
1824 <thead>
1825 <row>
1826 <entry>Conventional Name</entry>
1827 <entry>Decimal Code</entry>
1828 <entry>Type</entry>
1829 <entry>Required In</entry>
1830 <entry>Description</entry>
1831 </row>
1832 </thead>
1833 <tbody>
1834 <row>
1835 <entry><literal>INVALID</literal></entry>
1836 <entry>0</entry>
1837 <entry>N/A</entry>
1838 <entry>not allowed</entry>
1839 <entry>Not a valid field name (error if it appears in a message)</entry>
1840 </row>
1841 <row>
1842 <entry><literal>PATH</literal></entry>
1843 <entry>1</entry>
1844 <entry><literal>OBJECT_PATH</literal></entry>
1845 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1846 <entry>The object to send a call to,
1847 or the object a signal is emitted from.
1848 The special path
1849 <literal>/org/freedesktop/DBus/Local</literal> is reserved;
1850 implementations should not send messages with this path,
1851 and the reference implementation of the bus daemon will
1852 disconnect any application that attempts to do so.
1853 This header field is controlled by the message sender.
1854 </entry>
1855 </row>
1856 <row>
1857 <entry><literal>INTERFACE</literal></entry>
1858 <entry>2</entry>
1859 <entry><literal>STRING</literal></entry>
1860 <entry><literal>SIGNAL</literal></entry>
1861 <entry>
1862 The interface to invoke a method call on, or
1863 that a signal is emitted from. Optional for
1864 method calls, required for signals.
1865 The special interface
1866 <literal>org.freedesktop.DBus.Local</literal> is reserved;
1867 implementations should not send messages with this
1868 interface, and the reference implementation of the bus
1869 daemon will disconnect any application that attempts to
1870 do so.
1871 This header field is controlled by the message sender.
1872 </entry>
1873 </row>
1874 <row>
1875 <entry><literal>MEMBER</literal></entry>
1876 <entry>3</entry>
1877 <entry><literal>STRING</literal></entry>
1878 <entry><literal>METHOD_CALL</literal>, <literal>SIGNAL</literal></entry>
1879 <entry>
1880 The member, either the method name or signal name.
1881 This header field is controlled by the message sender.
1882 </entry>
1883 </row>
1884 <row>
1885 <entry><literal>ERROR_NAME</literal></entry>
1886 <entry>4</entry>
1887 <entry><literal>STRING</literal></entry>
1888 <entry><literal>ERROR</literal></entry>
1889 <entry>The name of the error that occurred, for errors</entry>
1890 </row>
1891 <row>
1892 <entry><literal>REPLY_SERIAL</literal></entry>
1893 <entry>5</entry>
1894 <entry><literal>UINT32</literal></entry>
1895 <entry><literal>ERROR</literal>, <literal>METHOD_RETURN</literal></entry>
1896 <entry>
1897 The serial number of the message this message is a reply
1898 to. (The serial number is the second <literal>UINT32</literal>
1899 in the header.)
1900 This header field is controlled by the message sender.
1901 </entry>
1902 </row>
1903 <row>
1904 <entry><literal>DESTINATION</literal></entry>
1905 <entry>6</entry>
1906 <entry><literal>STRING</literal></entry>
1907 <entry>optional</entry>
1908 <entry>
1909 The name of the connection this message is intended for.
1910 This field is usually only meaningful in combination with
1911 the message bus (see <xref linkend="message-bus"/>),
1912 but other servers may define their own meanings for it.
1913 This header field is controlled by the message sender.
1914 </entry>
1915 </row>
1916 <row>
1917 <entry><literal>SENDER</literal></entry>
1918 <entry>7</entry>
1919 <entry><literal>STRING</literal></entry>
1920 <entry>optional</entry>
1921 <entry>Unique name of the sending connection.
1922 This field is usually only meaningful in combination with
1923 the message bus, but other servers may define their own
1924 meanings for it.
1925 On a message bus, this header field is controlled by
1926 the message bus, so it is as reliable and trustworthy
1927 as the message bus itself.
1928 Otherwise, this header field is controlled by the message
1929 sender, unless there is out-of-band information that
1930 indicates otherwise.
1931 </entry>
1932 </row>
1933 <row>
1934 <entry><literal>SIGNATURE</literal></entry>
1935 <entry>8</entry>
1936 <entry><literal>SIGNATURE</literal></entry>
1937 <entry>optional</entry>
1938 <entry>
1939 The signature of the message body.
1940 If omitted, it is assumed to be the
1941 empty signature "" (i.e. the body must be 0-length).
1942 This header field is controlled by the message sender.
1943 </entry>
1944 </row>
1945 <row>
1946 <entry><literal>UNIX_FDS</literal></entry>
1947 <entry>9</entry>
1948 <entry><literal>UINT32</literal></entry>
1949 <entry>optional</entry>
1950 <entry>The number of Unix file descriptors that
1951 accompany the message. If omitted, it is assumed
1952 that no Unix file descriptors accompany the
1953 message. The actual file descriptors need to be
1954 transferred via platform specific mechanism
1955 out-of-band. They must be sent at the same time as
1956 part of the message itself. They may not be sent
1957 before the first byte of the message itself is
1958 transferred or after the last byte of the message
1959 itself.
1960 This header field is controlled by the message sender.
1961 </entry>
1962 </row>
1963 </tbody>
1964 </tgroup>
1965 </informaltable>
1966 </para>
1967 </sect3>
1968 </sect2>
1969
1970 <sect2 id="message-protocol-names">
1971 <title>Valid Names</title>
1972 <para>
1973 The various names in D-Bus messages have some restrictions.
1974 </para>
1975 <para>
1976 There is a <firstterm>maximum name length</firstterm>
1977 of 255 which applies to bus names, interfaces, and members.
1978 </para>
1979 <sect3 id="message-protocol-names-interface">
1980 <title>Interface names</title>
1981 <para>
1982 Interfaces have names with type <literal>STRING</literal>, meaning that
1983 they must be valid UTF-8. However, there are also some
1984 additional restrictions that apply to interface names
1985 specifically:
1986 <itemizedlist>
1987 <listitem><para>Interface names are composed of 2 or more elements separated by
1988 a period ('.') character. All elements must contain at least
1989 one character.
1990 </para>
1991 </listitem>
1992 <listitem><para>Each element must only contain the ASCII characters
1993 "[A-Z][a-z][0-9]_" and must not begin with a digit.
1994 </para>
1995 </listitem>
1996
1997 <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
1998 </itemizedlist>
1999 </para>
2000
2001 <para>
2002 Interface names should start with the reversed DNS domain name of
2003 the author of the interface (in lower-case), like interface names
2004 in Java. It is conventional for the rest of the interface name
2005 to consist of words run together, with initial capital letters
2006 on all words ("CamelCase"). Several levels of hierarchy can be used.
2007 It is also a good idea to include the major version of the interface
2008 in the name, and increment it if incompatible changes are made;
2009 this way, a single object can implement several versions of an
2010 interface in parallel, if necessary.
2011 </para>
2012
2013 <para>
2014 For instance, if the owner of <literal>example.com</literal> is
2015 developing a D-Bus API for a music player, they might define
2016 interfaces called <literal>com.example.MusicPlayer1</literal>,
2017 <literal>com.example.MusicPlayer1.Track</literal> and
2018 <literal>com.example.MusicPlayer1.Seekable</literal>.
2019 </para>
2020
2021 <para>
2022 If the author's DNS domain name contains hyphen/minus characters
2023 ('-'), which are not allowed in D-Bus interface names, they
2024 should be replaced by underscores. If the DNS domain name
2025 contains a digit immediately following a period ('.'), which
2026 is also not allowed in interface names), the interface name
2027 should add an underscore before that digit. For example, if
2028 the owner of 7-zip.org defined an interface for out-of-process
2029 plugins, it might be named <literal>org._7_zip.Plugin</literal>.
2030 </para>
2031
2032 <para>
2033 If the author's DNS domain name is an internationalized domain
2034 name (IDN) such as <literal>δοκιμή.example</literal>,
2035 the ASCII encoding (known as ACE-encoding or Punycode) such as
2036 <literal>xn--jxalpdlp.example</literal>
2037 should be used as a basis for the reversed-domain-name form.
2038 As with any other name, hyphen/minus characters should be
2039 replaced by underscores in the reversed-domain-name form, for
2040 example <literal>example.xn__jxalpdlp.ExampleService1</literal>.
2041 For more information about internationalized domain names, see
2042 <ulink url="https://datatracker.ietf.org/doc/html/rfc5890">RFC
2043 5890 "Internationalized Domain Names for Applications (IDNA):
2044 Definitions and Document Framework"</ulink>.
2045 </para>
2046
2047 <para>
2048 D-Bus does not distinguish between the concepts that would be
2049 called classes and interfaces in Java: either can be identified on
2050 D-Bus by an interface name.
2051 </para>
2052 </sect3>
2053 <sect3 id="message-protocol-names-bus">
2054 <title>Bus names</title>
2055 <para>
2056 Connections have one or more bus names associated with them.
2057 A connection has exactly one bus name that is a <firstterm>unique
2058 connection name</firstterm>. The unique connection name remains
2059 with the connection for its entire lifetime.
2060 A bus name is of type <literal>STRING</literal>,
2061 meaning that it must be valid UTF-8. However, there are also
2062 some additional restrictions that apply to bus names
2063 specifically:
2064 <itemizedlist>
2065 <listitem><para>Bus names that start with a colon (':')
2066 character are unique connection names. Other bus names
2067 are called <firstterm>well-known bus names</firstterm>.
2068 </para>
2069 </listitem>
2070 <listitem><para>Bus names are composed of 1 or more elements separated by
2071 a period ('.') character. All elements must contain at least
2072 one character.
2073 </para>
2074 </listitem>
2075 <listitem><para>Each element must only contain the ASCII characters
2076 "[A-Z][a-z][0-9]_-", with "-" discouraged in new bus
2077 names. Only elements that are part of a unique
2078 connection name may begin with a digit, elements in
2079 other bus names must not begin with a digit.
2080 </para>
2081 </listitem>
2082
2083 <listitem><para>Bus names must contain at least one '.' (period)
2084 character (and thus at least two elements).
2085 </para></listitem>
2086
2087 <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
2088 <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
2089 </itemizedlist>
2090 </para>
2091 <para>
2092 Note that the hyphen ('-') character is allowed in bus names
2093 but not in interface names. It is also problematic or not
2094 allowed in various specifications and APIs that refer to
2095 D-Bus, such as <ulink
2096 url="http://docs.flatpak.org/en/latest/introduction.html#identifiers"
2097 >Flatpak application IDs</ulink>,
2098 <ulink
2099 url="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus"
2100 >the <literal>DBusActivatable</literal> interface in the
2101 Desktop Entry Specification</ulink>, and the convention
2102 that an application's "main" interface and object path
2103 resemble its bus name. To avoid situations that require
2104 special-case handling, it is recommended that new D-Bus names
2105 consistently replace hyphens with underscores.
2106 </para>
2107
2108 <para>
2109 Like <link linkend="message-protocol-names-interface">interface
2110 names</link>, well-known bus names should start with the
2111 reversed DNS domain name of the author of the interface (in
2112 lower-case), and it is conventional for the rest of the well-known
2113 bus name to consist of words run together, with initial
2114 capital letters. As with interface names, including a version
2115 number in well-known bus names is a good idea; it's possible to
2116 have the well-known bus name for more than one version
2117 simultaneously if backwards compatibility is required.
2118 </para>
2119
2120 <para>
2121 As with <link linkend="message-protocol-names-interface">interface
2122 names</link>, if the author's DNS domain name
2123 contains hyphen/minus characters they should be replaced by
2124 underscores, if it contains leading digits they should be
2125 escaped by prepending an underscore, and internationalized
2126 domain names (IDN) need to be encoded in their ASCII form
2127 (ACE-encoding, Punycode) before replacing dashes with underscores.
2128 For example, if the owner
2129 of 7-zip.org used a D-Bus name for an archiving application,
2130 it might be named <literal>org._7_zip.Archiver</literal>,
2131 while the owner of <literal>δοκιμή.example</literal> might
2132 use the name <literal>example.xn__jxalpdlp.ExampleService1</literal>.
2133 </para>
2134
2135 <para>
2136 If a well-known bus name implies the presence of a "main" interface,
2137 that "main" interface is often given the same name as
2138 the well-known bus name, and situated at the corresponding object
2139 path. For instance, if the owner of <literal>example.com</literal>
2140 is developing a D-Bus API for a music player, they might define
2141 that any application that takes the well-known name
2142 <literal>com.example.MusicPlayer1</literal> should have an object
2143 at the object path <literal>/com/example/MusicPlayer1</literal>
2144 which implements the interface
2145 <literal>com.example.MusicPlayer1</literal>.
2146 </para>
2147 </sect3>
2148 <sect3 id="message-protocol-names-member">
2149 <title>Member names</title>
2150 <para>
2151 Member (i.e. method or signal) names:
2152 <itemizedlist>
2153 <listitem><para>Must only contain the ASCII characters
2154 "[A-Z][a-z][0-9]_" and may not begin with a
2155 digit.</para></listitem>
2156 <listitem><para>Must not contain the '.' (period) character.</para></listitem>
2157 <listitem><para>Must not exceed the maximum name length.</para></listitem>
2158 <listitem><para>Must be at least 1 byte in length.</para></listitem>
2159 </itemizedlist>
2160 </para>
2161
2162 <para>
2163 It is conventional for member names on D-Bus to consist of
2164 capitalized words with no punctuation ("camel-case").
2165 Method names should usually be verbs, such as
2166 <literal>GetItems</literal>, and signal names should usually be
2167 a description of an event, such as <literal>ItemsChanged</literal>.
2168 </para>
2169 </sect3>
2170 <sect3 id="message-protocol-names-error">
2171 <title>Error names</title>
2172 <para>
2173 Error names have the same restrictions as interface names.
2174 </para>
2175
2176 <para>
2177 Error names have the same naming conventions as interface
2178 names, and often contain <literal>.Error.</literal>; for instance,
2179 the owner of <literal>example.com</literal> might define the
2180 errors <literal>com.example.MusicPlayer1.Error.FileNotFound</literal>
2181 and <literal>com.example.MusicPlayer1.Error.OutOfMemory</literal>.
2182 The errors defined by D-Bus itself, such as
2183 <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
2184 similar pattern.
2185 </para>
2186 </sect3>
2187 </sect2>
2188
2189 <sect2 id="message-protocol-types">
2190 <title>Message Types</title>
2191 <para>
2192 Each of the message types (<literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>, <literal>ERROR</literal>, and
2193 <literal>SIGNAL</literal>) has its own expected usage conventions and header fields.
2194 This section describes these conventions.
2195 </para>
2196 <sect3 id="message-protocol-types-method">
2197 <title>Method Calls</title>
2198 <para>
2199 Some messages invoke an operation on a remote object. These are
2200 called method call messages and have the type tag <literal>METHOD_CALL</literal>. Such
2201 messages map naturally to methods on objects in a typical program.
2202 </para>
2203 <para>
2204 A method call message is required to have a <literal>MEMBER</literal> header field
2205 indicating the name of the method. Optionally, the message has an
2206 <literal>INTERFACE</literal> field giving the interface the method is a part of.
2207 Including the <literal>INTERFACE</literal> in all method call
2208 messages is strongly recommended.
2209 </para>
2210 <para>
2211 In the absence of an <literal>INTERFACE</literal> field, if two
2212 or more interfaces on the same object have a method with the same
2213 name, it is undefined which of those methods will be invoked.
2214 Implementations may choose to either return an error, or deliver the
2215 message as though it had an arbitrary one of those interfaces.
2216 </para>
2217 <para>
2218 In some situations (such as the well-known system bus), messages
2219 are filtered through an access-control list external to the
2220 remote object implementation. If that filter rejects certain
2221 messages by matching their interface, or accepts only messages
2222 to specific interfaces, it must also reject messages that have no
2223 <literal>INTERFACE</literal>: otherwise, malicious
2224 applications could use this to bypass the filter.
2225 </para>
2226 <para>
2227 Method call messages also include a <literal>PATH</literal> field
2228 indicating the object to invoke the method on. If the call is passing
2229 through a message bus, the message will also have a
2230 <literal>DESTINATION</literal> field giving the name of the connection
2231 to receive the message.
2232 </para>
2233 <para>
2234 When an application handles a method call message, it is required to
2235 return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
2236 indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
2237 reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
2238 </para>
2239 <para>
2240 If the reply has type <literal>METHOD_RETURN</literal>, the arguments to the reply message
2241 are the return value(s) or "out parameters" of the method call.
2242 If the reply has type <literal>ERROR</literal>, then an "exception" has been thrown,
2243 and the call fails; no return value will be provided. It makes
2244 no sense to send multiple replies to the same method call.
2245 </para>
2246 <para>
2247 Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
2248 reply is required, so the caller will know the method
2249 was successfully processed.
2250 </para>
2251 <para>
2252 The <literal>METHOD_RETURN</literal> or <literal>ERROR</literal> reply message must have the <literal>REPLY_SERIAL</literal>
2253 header field.
2254 </para>
2255 <para>
2256 If a <literal>METHOD_CALL</literal> message has the flag <literal>NO_REPLY_EXPECTED</literal>,
2257 then the application receiving the method should not send the reply message (regardless of
2258 whether the reply would have been <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>).
2259 </para>
2260 <para>
2261 Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
2262 destination name does not exist then a program to own the destination
2263 name will be started (activated) before the message is delivered. See
2264 <xref linkend="message-bus-starting-services"/>.
2265 The message
2266 will be held until the new program is successfully started or has
2267 failed to start; in case of failure, an error will be returned. This
2268 flag is only relevant in the context of a message bus, it is ignored
2269 during one-to-one communication with no intermediate bus.
2270 </para>
2271 <sect4 id="message-protocol-types-method-apis">
2272 <title>Mapping method calls to native APIs</title>
2273 <para>
2274 APIs for D-Bus may map method calls to a method call in a specific
2275 programming language, such as C++, or may map a method call written
2276 in an IDL to a D-Bus message.
2277 </para>
2278 <para>
2279 In APIs of this nature, arguments to a method are often termed "in"
2280 (which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
2281 returned in the <literal>METHOD_RETURN</literal>). Some APIs such as CORBA also have
2282 "inout" arguments, which are both sent and received, i.e. the caller
2283 passes in a value which is modified. Mapped to D-Bus, an "inout"
2284 argument is equivalent to an "in" argument, followed by an "out"
2285 argument. You can't pass things "by reference" over the wire, so
2286 "inout" is purely an illusion of the in-process API.
2287 </para>
2288 <para>
2289 Given a method with zero or one return values, followed by zero or more
2290 arguments, where each argument may be "in", "out", or "inout", the
2291 caller constructs a message by appending each "in" or "inout" argument,
2292 in order. "out" arguments are not represented in the caller's message.
2293 </para>
2294 <para>
2295 The recipient constructs a reply by appending first the return value
2296 if any, then each "out" or "inout" argument, in order.
2297 "in" arguments are not represented in the reply message.
2298 </para>
2299 <para>
2300 Error replies are normally mapped to exceptions in languages that have
2301 exceptions.
2302 </para>
2303 <para>
2304 In converting from native APIs to D-Bus, it is perhaps nice to
2305 map D-Bus naming conventions ("FooBar") to native conventions
2306 such as "fooBar" or "foo_bar" automatically. This is OK
2307 as long as you can say that the native API is one that
2308 was specifically written for D-Bus. It makes the most sense
2309 when writing object implementations that will be exported
2310 over the bus. Object proxies used to invoke remote D-Bus
2311 objects probably need the ability to call any D-Bus method,
2312 and thus a magic name mapping like this could be a problem.
2313 </para>
2314 <para>
2315 This specification doesn't require anything of native API bindings;
2316 the preceding is only a suggested convention for consistency
2317 among bindings.
2318 </para>
2319 </sect4>
2320 </sect3>
2321
2322 <sect3 id="message-protocol-types-signal">
2323 <title>Signal Emission</title>
2324 <para>
2325 Unlike method calls, signal emissions have no replies.
2326 A signal emission is simply a single message of type <literal>SIGNAL</literal>.
2327 It must have three header fields: <literal>PATH</literal> giving the object
2328 the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
2329 the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
2330 for signals, though it is optional for method calls.
2331 </para>
2332 </sect3>
2333
2334 <sect3 id="message-protocol-types-errors">
2335 <title>Errors</title>
2336 <para>
2337 Messages of type <literal>ERROR</literal> are most commonly replies
2338 to a <literal>METHOD_CALL</literal>, but may be returned in reply
2339 to any kind of message. The message bus for example
2340 will return an <literal>ERROR</literal> in reply to a signal emission if
2341 the bus does not have enough memory to send the signal.
2342 </para>
2343 <para>
2344 An <literal>ERROR</literal> may have any arguments, but if the first
2345 argument is a <literal>STRING</literal>, it must be an error message.
2346 The error message may be logged or shown to the user
2347 in some way.
2348 </para>
2349 </sect3>
2350
2351 <sect3 id="message-protocol-types-notation">
2352 <title>Notation in this document</title>
2353 <para>
2354 This document uses a simple pseudo-IDL to describe particular method
2355 calls and signals. Here is an example of a method call:
2356 <programlisting>
2357 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
2358 out UINT32 resultcode)
2359 </programlisting>
2360 This means <literal>INTERFACE</literal> = org.freedesktop.DBus, <literal>MEMBER</literal> = StartServiceByName,
2361 <literal>METHOD_CALL</literal> arguments are <literal>STRING</literal> and <literal>UINT32</literal>, <literal>METHOD_RETURN</literal> argument
2362 is <literal>UINT32</literal>. Remember that the <literal>MEMBER</literal> field can't contain any '.' (period)
2363 characters so it's known that the last part of the name in
2364 the "IDL" is the member name.
2365 </para>
2366 <para>
2367 In C++ that might end up looking like this:
2368 <programlisting>
2369 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name,
2370 unsigned int flags);
2371 </programlisting>
2372 or equally valid, the return value could be done as an argument:
2373 <programlisting>
2374 void org::freedesktop::DBus::StartServiceByName (const char *name,
2375 unsigned int flags,
2376 unsigned int *resultcode);
2377 </programlisting>
2378 It's really up to the API designer how they want to make
2379 this look. You could design an API where the namespace wasn't used
2380 in C++, using STL or Qt, using varargs, or whatever you wanted.
2381 </para>
2382 <para>
2383 Signals are written as follows:
2384 <programlisting>
2385 org.freedesktop.DBus.NameLost (STRING name)
2386 </programlisting>
2387 Signals don't specify "in" vs. "out" because only
2388 a single direction is possible.
2389 </para>
2390 <para>
2391 It isn't especially encouraged to use this lame pseudo-IDL in actual
2392 API implementations; you might use the native notation for the
2393 language you're using, or you might use COM or CORBA IDL, for example.
2394 </para>
2395 </sect3>
2396 </sect2>
2397
2398 <sect2 id="message-protocol-handling-invalid">
2399 <title>Invalid Protocol and Spec Extensions</title>
2400
2401 <para>
2402 For security reasons, the D-Bus protocol should be strictly parsed and
2403 validated, with the exception of defined extension points. Any invalid
2404 protocol or spec violations should result in immediately dropping the
2405 connection without notice to the other end. Exceptions should be
2406 carefully considered, e.g. an exception may be warranted for a
2407 well-understood idiosyncrasy of a widely-deployed implementation. In
2408 cases where the other end of a connection is 100% trusted and known to
2409 be friendly, skipping validation for performance reasons could also make
2410 sense in certain cases.
2411 </para>
2412
2413 <para>
2414 Generally speaking violations of the "must" requirements in this spec
2415 should be considered possible attempts to exploit security, and violations
2416 of the "should" suggestions should be considered legitimate (though perhaps
2417 they should generate an error in some cases).
2418 </para>
2419
2420 <para>
2421 The following extension points are built in to D-Bus on purpose and must
2422 not be treated as invalid protocol. The extension points are intended
2423 for use by future versions of this spec, they are not intended for third
2424 parties. At the moment, the only way a third party could extend D-Bus
2425 without breaking interoperability would be to introduce a way to negotiate new
2426 feature support as part of the auth protocol, using EXTENSION_-prefixed
2427 commands. There is not yet a standard way to negotiate features.
2428 <itemizedlist>
2429 <listitem>
2430 <para>
2431 In the authentication protocol (see <xref linkend="auth-protocol"/>) unknown
2432 commands result in an ERROR rather than a disconnect. This enables
2433 future extensions to the protocol. Commands starting with EXTENSION_ are
2434 reserved for third parties.
2435 </para>
2436 </listitem>
2437 <listitem>
2438 <para>
2439 The authentication protocol supports pluggable auth mechanisms.
2440 </para>
2441 </listitem>
2442 <listitem>
2443 <para>
2444 The address format (see <xref linkend="addresses"/>) supports new
2445 kinds of transport.
2446 </para>
2447 </listitem>
2448 <listitem>
2449 <para>
2450 Messages with an unknown type (something other than
2451 <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
2452 <literal>ERROR</literal>, <literal>SIGNAL</literal>) are ignored.
2453 Unknown-type messages must still be well-formed in the same way
2454 as the known messages, however. They still have the normal
2455 header and body.
2456 </para>
2457 </listitem>
2458 <listitem>
2459 <para>
2460 Header fields with an unknown or unexpected field code must be ignored,
2461 though again they must still be well-formed.
2462 </para>
2463 </listitem>
2464 <listitem>
2465 <para>
2466 New standard interfaces (with new methods and signals) can of course be added.
2467 </para>
2468 </listitem>
2469 </itemizedlist>
2470 </para>
2471
2472 </sect2>
2473
2474 </sect1>
2475
2476 <sect1 id="auth-protocol">
2477 <title>Authentication Protocol</title>
2478 <para>
2479 Before the flow of messages begins, two applications must
2480 authenticate. A simple plain-text protocol is used for
2481 authentication; this protocol is a SASL profile, and maps fairly
2482 directly from the SASL specification. The message encoding is
2483 NOT used here, only plain text messages.
2484 </para>
2485 <para>
2486 Using SASL in D-Bus requires that we define the meaning of non-empty
2487 authorization identity strings. When D-Bus is used on Unix platforms,
2488 a non-empty SASL authorization identity represents a Unix user. An
2489 authorization identity consisting entirely of ASCII decimal digits
2490 represents a numeric user ID as defined by POSIX, for example
2491 <literal>0</literal> for the root user or <literal>1000</literal>
2492 for the first user created on many systems. Non-numeric authorization
2493 identities are not required to be accepted or supported, but if used,
2494 they must be interpreted as a login name as found in the
2495 <literal>pw_name</literal> field of POSIX
2496 <literal>struct passwd</literal>, for example
2497 <literal>root</literal>, and normalized to the corresponding
2498 numeric user ID. For best interoperability, clients and servers
2499 should use numeric user IDs.
2500 </para>
2501 <para>
2502 When D-Bus is used on Windows platforms, a non-empty SASL
2503 authorization identity represents a Windows security identifier
2504 (SID) in its string form, for example
2505 <literal>S-1-5-21-3623811015-3361044348-30300820-1013</literal> for
2506 a domain or local computer user or <literal>S-1-5-18</literal> for
2507 the LOCAL_SYSTEM user. The user-facing usernames such as
2508 <literal>Administrator</literal> or <literal>LOCAL_SYSTEM</literal>
2509 are not used in the D-Bus protocol.
2510 </para>
2511 <para>
2512 In examples, "C:" and "S:" indicate lines sent by the client and
2513 server respectively. The client sends the first line, and the
2514 server must respond to each line from the client with a single-line
2515 reply, with one exception: there is no reply to the BEGIN command.
2516 </para>
2517 <sect2 id="auth-protocol-overview">
2518 <title>Protocol Overview</title>
2519 <para>
2520 The protocol is a line-based protocol, where each line ends with
2521 \r\n. Each line begins with an all-caps ASCII command name containing
2522 only the character range [A-Z_], a space, then any arguments for the
2523 command, then the \r\n ending the line. The protocol is
2524 case-sensitive. All bytes must be in the ASCII character set.
2525
2526 Commands from the client to the server are as follows:
2527
2528 <itemizedlist>
2529 <listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
2530 <listitem><para>CANCEL</para></listitem>
2531 <listitem><para>BEGIN</para></listitem>
2532 <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
2533 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
2534 <listitem><para>NEGOTIATE_UNIX_FD</para></listitem>
2535 </itemizedlist>
2536
2537 From server to client are as follows:
2538
2539 <itemizedlist>
2540 <listitem><para>REJECTED &lt;space-separated list of mechanism names&gt;</para></listitem>
2541 <listitem><para>OK &lt;GUID in hex&gt;</para></listitem>
2542 <listitem><para>DATA &lt;data in hex encoding&gt;</para></listitem>
2543 <listitem><para>ERROR [human-readable error explanation]</para></listitem>
2544 <listitem><para>AGREE_UNIX_FD</para></listitem>
2545 </itemizedlist>
2546 </para>
2547 <para>
2548 Unofficial extensions to the command set must begin with the letters
2549 "EXTENSION_", to avoid conflicts with future official commands.
2550 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF".
2551 </para>
2552 </sect2>
2553 <sect2 id="auth-nul-byte">
2554 <title>Special credentials-passing nul byte</title>
2555 <para>
2556 Immediately after connecting to the server, the client must send a
2557 single nul byte. This byte may be accompanied by credentials
2558 information on some operating systems that use sendmsg() with
2559 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain
2560 sockets. However, the nul byte must be sent even on other kinds of
2561 socket, and even on operating systems that do not require a byte to be
2562 sent in order to transmit credentials. The text protocol described in
2563 this document begins after the single nul byte. If the first byte
2564 received from the client is not a nul byte, the server may disconnect
2565 that client.
2566 </para>
2567 <para>
2568 A nul byte in any context other than the initial byte is an error;
2569 the protocol is ASCII-only.
2570 </para>
2571 <para>
2572 The credentials sent along with the nul byte may be used with the
2573 SASL mechanism EXTERNAL.
2574 </para>
2575 </sect2>
2576 <sect2 id="auth-command-auth">
2577 <title>AUTH command</title>
2578 <para>
2579 The AUTH command is sent by the client to the server.
2580 The server replies with DATA, OK or REJECTED.
2581 </para>
2582 <para>
2583 If an AUTH command has no arguments, it is a request to list
2584 available mechanisms. The server must respond with a REJECTED
2585 command listing the mechanisms it understands, or with an error.
2586 </para>
2587 <para>
2588 If an AUTH command specifies a mechanism, and the server supports
2589 said mechanism, the server should begin exchanging SASL
2590 challenge-response data with the client using DATA commands.
2591 </para>
2592 <para>
2593 If the server does not support the mechanism given in the AUTH
2594 command, it must send either a REJECTED command listing the mechanisms
2595 it does support, or an error.
2596 </para>
2597 <para>
2598 If the [initial-response] argument is provided, it is intended for use
2599 with mechanisms that have no initial challenge (or an empty initial
2600 challenge), as if it were the argument to an initial DATA command. If
2601 the selected mechanism has an initial challenge and [initial-response]
2602 was provided, the server should reject authentication by sending
2603 REJECTED.
2604 </para>
2605 <para>
2606 If authentication succeeds after exchanging DATA commands,
2607 an OK command must be sent to the client.
2608 </para>
2609 </sect2>
2610 <sect2 id="auth-command-cancel">
2611 <title>CANCEL Command</title>
2612 <para>
2613 The CANCEL command is sent by the client to the server.
2614 The server replies with REJECTED.
2615 </para>
2616 <para>
2617 At any time up to sending the BEGIN command, the client may send a
2618 CANCEL command. On receiving the CANCEL command, the server must
2619 send a REJECTED command and abort the current authentication
2620 exchange.
2621 </para>
2622 </sect2>
2623 <sect2 id="auth-command-data">
2624 <title>DATA Command</title>
2625 <para>
2626 The DATA command may come from either client or server, and simply
2627 contains a hex-encoded block of data to be interpreted
2628 according to the SASL mechanism in use.
2629 If sent by the client, the server replies with DATA, OK or REJECTED.
2630 </para>
2631 <para>
2632 Some SASL mechanisms support sending an "empty string";
2633 FIXME we need some way to do this.
2634 </para>
2635 </sect2>
2636 <sect2 id="auth-command-begin">
2637 <title>BEGIN Command</title>
2638 <para>
2639 The BEGIN command is sent by the client to the server.
2640 The server does not reply.
2641 </para>
2642 <para>
2643 The BEGIN command acknowledges that the client has received an
2644 OK command from the server and completed any feature negotiation
2645 that it wishes to do, and declares that the stream of messages
2646 is about to begin.
2647 </para>
2648 <para>
2649 The first octet received by the server after the \r\n of the BEGIN
2650 command from the client must be the first octet of the
2651 authenticated/encrypted stream of D-Bus messages.
2652 </para>
2653 <para>
2654 Unlike all other commands, the server does not reply to
2655 the BEGIN command with an authentication command of its own.
2656 After the \r\n of the reply to the command before BEGIN,
2657 the next octet received by the client must be the first octet
2658 of the authenticated/encrypted stream of D-Bus messages.
2659 </para>
2660 </sect2>
2661 <sect2 id="auth-command-rejected">
2662 <title>REJECTED Command</title>
2663 <para>
2664 The REJECTED command is sent by the server to the client.
2665 </para>
2666 <para>
2667 The REJECTED command indicates that the current authentication
2668 exchange has failed, and further exchange of DATA is inappropriate.
2669 The client would normally try another mechanism, or try providing
2670 different responses to challenges.
2671 </para><para>
2672 Optionally, the REJECTED command has a space-separated list of
2673 available auth mechanisms as arguments. If a server ever provides
2674 a list of supported mechanisms, it must provide the same list
2675 each time it sends a REJECTED message. Clients are free to
2676 ignore all lists received after the first.
2677 </para>
2678 </sect2>
2679 <sect2 id="auth-command-ok">
2680 <title>OK Command</title>
2681 <para>
2682 The OK command is sent by the server to the client.
2683 </para>
2684 <para>
2685 The OK command indicates that the client has been
2686 authenticated. The client may now proceed with negotiating
2687 Unix file descriptor passing. To do that it shall send
2688 NEGOTIATE_UNIX_FD to the server.
2689 </para>
2690 <para>
2691 Otherwise, the client must respond to the OK command by
2692 sending a BEGIN command, followed by its stream of messages,
2693 or by disconnecting. The server must not accept additional
2694 commands using this protocol after the BEGIN command has been
2695 received. Further communication will be a stream of D-Bus
2696 messages (optionally encrypted, as negotiated) rather than
2697 this protocol.
2698 </para>
2699 <para>
2700 If there is no negotiation, the first octet received by the client
2701 after the \r\n of the OK command must be the first octet of
2702 the authenticated/encrypted stream of D-Bus messages. If the
2703 client negotiates Unix file descriptor passing, the first
2704 octet received by the client after the \r\n of the AGREE_UNIX_FD
2705 or ERROR reply must be the first octet of the
2706 authenticated/encrypted stream.
2707 </para>
2708 <para>
2709 The OK command has one argument, which is the GUID of the server.
2710 See <xref linkend="addresses"/> for more on server GUIDs.
2711 </para>
2712 </sect2>
2713 <sect2 id="auth-command-error">
2714 <title>ERROR Command</title>
2715 <para>
2716 The ERROR command can be sent in either direction.
2717 If sent by the client, the server replies with REJECTED.
2718 </para>
2719 <para>
2720 The ERROR command indicates that either server or client did not
2721 know a command, does not accept the given command in the current
2722 context, or did not understand the arguments to the command. This
2723 allows the protocol to be extended; a client or server can send a
2724 command present or permitted only in new protocol versions, and if
2725 an ERROR is received instead of an appropriate response, fall back
2726 to using some other technique.
2727 </para>
2728 <para>
2729 If an ERROR is sent, the server or client that sent the
2730 error must continue as if the command causing the ERROR had never been
2731 received. However, the the server or client receiving the error
2732 should try something other than whatever caused the error;
2733 if only canceling/rejecting the authentication.
2734 </para>
2735 <para>
2736 If the D-Bus protocol changes incompatibly at some future time,
2737 applications implementing the new protocol would probably be able to
2738 check for support of the new protocol by sending a new command and
2739 receiving an ERROR from applications that don't understand it. Thus the
2740 ERROR feature of the auth protocol is an escape hatch that lets us
2741 negotiate extensions or changes to the D-Bus protocol in the future.
2742 </para>
2743 </sect2>
2744 <sect2 id="auth-command-negotiate-unix-fd">
2745 <title>NEGOTIATE_UNIX_FD Command</title>
2746 <para>
2747 The NEGOTIATE_UNIX_FD command is sent by the client to the server.
2748 The server replies with AGREE_UNIX_FD or ERROR.
2749 </para>
2750 <para>
2751 The NEGOTIATE_UNIX_FD command indicates that the client
2752 supports Unix file descriptor passing. This command may only
2753 be sent after the connection is authenticated, i.e. after OK
2754 was received by the client. This command may only be sent on
2755 transports that support Unix file descriptor passing.
2756 </para>
2757 <para>
2758 On receiving NEGOTIATE_UNIX_FD the server must respond with
2759 either AGREE_UNIX_FD or ERROR. It shall respond the former if
2760 the transport chosen supports Unix file descriptor passing and
2761 the server supports this feature. It shall respond the latter
2762 if the transport does not support Unix file descriptor
2763 passing, the server does not support this feature, or the
2764 server decides not to enable file descriptor passing due to
2765 security or other reasons.
2766 </para>
2767 </sect2>
2768 <sect2 id="auth-command-agree-unix-fd">
2769 <title>AGREE_UNIX_FD Command</title>
2770 <para>
2771 The AGREE_UNIX_FD command is sent by the server to the client.
2772 </para>
2773 <para>
2774 The AGREE_UNIX_FD command indicates that the server supports
2775 Unix file descriptor passing. This command may only be sent
2776 after the connection is authenticated, and the client sent
2777 NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This
2778 command may only be sent on transports that support Unix file
2779 descriptor passing.
2780 </para>
2781 <para>
2782 On receiving AGREE_UNIX_FD the client must respond with BEGIN,
2783 followed by its stream of messages, or by disconnecting. The
2784 server must not accept additional commands using this protocol
2785 after the BEGIN command has been received. Further
2786 communication will be a stream of D-Bus messages (optionally
2787 encrypted, as negotiated) rather than this protocol.
2788 </para>
2789 </sect2>
2790 <sect2 id="auth-command-future">
2791 <title>Future Extensions</title>
2792 <para>
2793 Future extensions to the authentication and negotiation
2794 protocol are possible. For that new commands may be
2795 introduced. If a client or server receives an unknown command
2796 it shall respond with ERROR and not consider this fatal. New
2797 commands may be introduced both before, and after
2798 authentication, i.e. both before and after the OK command.
2799 </para>
2800 </sect2>
2801 <sect2 id="auth-examples">
2802 <title>Authentication examples</title>
2803
2804 <para>
2805 <figure>
2806 <title>Example of successful EXTERNAL authentication</title>
2807 <programlisting>
2808 31303030 is ASCII decimal "1000" represented in hex, so
2809 the client is authenticating as Unix uid 1000 in this example.
2810
2811 C: AUTH EXTERNAL 31303030
2812 S: OK 1234deadbeef
2813 C: BEGIN
2814 </programlisting>
2815 </figure>
2816 <figure>
2817 <title>Example of finding out mechanisms then picking one</title>
2818 <programlisting>
2819 C: AUTH
2820 S: REJECTED KERBEROS_V4 SKEY
2821 C: AUTH SKEY 7ab83f32ee
2822 S: DATA 8799cabb2ea93e
2823 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2824 S: OK 1234deadbeef
2825 C: BEGIN
2826 </programlisting>
2827 </figure>
2828 <figure>
2829 <title>Example of client sends unknown command then falls back to regular auth</title>
2830 <programlisting>
2831 532d312d352d3138 is the Windows SID "S-1-5-18" in hex,
2832 so the client is authenticating as Windows SID S-1-5-18
2833 in this example.
2834
2835 C: FOOBAR
2836 S: ERROR
2837 C: AUTH EXTERNAL 532d312d352d3138
2838 S: OK 1234deadbeef
2839 C: BEGIN
2840 </programlisting>
2841 </figure>
2842 <figure>
2843 <title>Example of server doesn't support initial auth mechanism</title>
2844 <programlisting>
2845 C: AUTH EXTERNAL
2846 S: REJECTED KERBEROS_V4 SKEY
2847 C: AUTH SKEY 7ab83f32ee
2848 S: DATA 8799cabb2ea93e
2849 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2850 S: OK 1234deadbeef
2851 C: BEGIN
2852 </programlisting>
2853 </figure>
2854 <figure>
2855 <title>Example of wrong password or the like followed by successful retry</title>
2856 <programlisting>
2857 C: AUTH EXTERNAL 736d6376
2858 S: REJECTED KERBEROS_V4 SKEY
2859 C: AUTH SKEY 7ab83f32ee
2860 S: DATA 8799cabb2ea93e
2861 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2862 S: REJECTED
2863 C: AUTH SKEY 7ab83f32ee
2864 S: DATA 8799cabb2ea93e
2865 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2866 S: OK 1234deadbeef
2867 C: BEGIN
2868 </programlisting>
2869 </figure>
2870 <figure>
2871 <title>Example of skey cancelled and restarted</title>
2872 <programlisting>
2873 C: AUTH EXTERNAL 32303438
2874 S: REJECTED KERBEROS_V4 SKEY
2875 C: AUTH SKEY 7ab83f32ee
2876 S: DATA 8799cabb2ea93e
2877 C: CANCEL
2878 S: REJECTED
2879 C: AUTH SKEY 7ab83f32ee
2880 S: DATA 8799cabb2ea93e
2881 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
2882 S: OK 1234deadbeef
2883 C: BEGIN
2884 </programlisting>
2885 </figure>
2886 <figure>
2887 <title>Example of successful EXTERNAL authentication with successful negotiation of Unix FD passing</title>
2888 <programlisting>
2889 C: AUTH EXTERNAL 31303030
2890 S: OK 1234deadbeef
2891 C: NEGOTIATE_UNIX_FD
2892 S: AGREE_UNIX_FD
2893 C: BEGIN
2894 </programlisting>
2895 </figure>
2896 <figure>
2897 <title>Example of successful EXTERNAL authentication with unsuccessful negotiation of Unix FD passing</title>
2898 <programlisting>
2899 C: AUTH EXTERNAL 31303030
2900 S: OK 1234deadbeef
2901 C: NEGOTIATE_UNIX_FD
2902 S: ERROR Not supported on this OS
2903 C: BEGIN
2904 </programlisting>
2905 </figure>
2906 </para>
2907 </sect2>
2908 <sect2 id="auth-states">
2909 <title>Authentication state diagrams</title>
2910
2911 <para>
2912 This section documents the auth protocol in terms of
2913 a state machine for the client and the server. This is
2914 probably the most robust way to implement the protocol.
2915 </para>
2916
2917 <sect3 id="auth-states-client">
2918 <title>Client states</title>
2919
2920 <para>
2921 To more precisely describe the interaction between the
2922 protocol state machine and the authentication mechanisms the
2923 following notation is used: MECH(CHALL) means that the
2924 server challenge CHALL was fed to the mechanism MECH, which
2925 returns one of
2926
2927 <itemizedlist>
2928 <listitem>
2929 <para>
2930 CONTINUE(RESP) means continue the auth conversation
2931 and send RESP as the response to the server;
2932 </para>
2933 </listitem>
2934
2935 <listitem>
2936 <para>
2937 OK(RESP) means that after sending RESP to the server
2938 the client side of the auth conversation is finished
2939 and the server should return "OK";
2940 </para>
2941 </listitem>
2942
2943 <listitem>
2944 <para>
2945 ERROR means that CHALL was invalid and could not be
2946 processed.
2947 </para>
2948 </listitem>
2949 </itemizedlist>
2950
2951 Both RESP and CHALL may be empty.
2952 </para>
2953
2954 <para>
2955 The Client starts by getting an initial response from the
2956 default mechanism and sends AUTH MECH RESP, or AUTH MECH if
2957 the mechanism did not provide an initial response. If the
2958 mechanism returns CONTINUE, the client starts in state
2959 <emphasis>WaitingForData</emphasis>, if the mechanism
2960 returns OK the client starts in state
2961 <emphasis>WaitingForOK</emphasis>.
2962 </para>
2963
2964 <para>
2965 The client should keep track of available mechanisms and
2966 which it mechanisms it has already attempted. This list is
2967 used to decide which AUTH command to send. When the list is
2968 exhausted, the client should give up and close the
2969 connection.
2970 </para>
2971
2972 <formalpara>
2973 <title><emphasis>WaitingForData</emphasis></title>
2974 <para>
2975 <itemizedlist>
2976 <listitem>
2977 <para>
2978 Receive DATA CHALL
2979 <simplelist>
2980 <member>
2981 MECH(CHALL) returns CONTINUE(RESP) &rarr; send
2982 DATA RESP, goto
2983 <emphasis>WaitingForData</emphasis>
2984 </member>
2985
2986 <member>
2987 MECH(CHALL) returns OK(RESP) &rarr; send DATA
2988 RESP, goto <emphasis>WaitingForOK</emphasis>
2989 </member>
2990
2991 <member>
2992 MECH(CHALL) returns ERROR &rarr; send ERROR
2993 [msg], goto <emphasis>WaitingForData</emphasis>
2994 </member>
2995 </simplelist>
2996 </para>
2997 </listitem>
2998
2999 <listitem>
3000 <para>
3001 Receive REJECTED [mechs] &rarr;
3002 send AUTH [next mech], goto
3003 WaitingForData or <emphasis>WaitingForOK</emphasis>
3004 </para>
3005 </listitem>
3006 <listitem>
3007 <para>
3008 Receive ERROR &rarr; send
3009 CANCEL, goto
3010 <emphasis>WaitingForReject</emphasis>
3011 </para>
3012 </listitem>
3013 <listitem>
3014 <para>
3015 Receive OK &rarr; <emphasis>authenticated</emphasis>,
3016 choose one:
3017
3018 <simplelist>
3019 <member>
3020 send NEGOTIATE_UNIX_FD, goto
3021 <emphasis>WaitingForAgreeUnixFD</emphasis>
3022 </member>
3023
3024 <member>
3025 send BEGIN, terminate auth conversation (successfully)
3026 </member>
3027 </simplelist>
3028 </para>
3029 </listitem>
3030 <listitem>
3031 <para>
3032 Receive anything else &rarr; send
3033 ERROR, goto
3034 <emphasis>WaitingForData</emphasis>
3035 </para>
3036 </listitem>
3037 </itemizedlist>
3038 </para>
3039 </formalpara>
3040
3041 <formalpara>
3042 <title><emphasis>WaitingForOK</emphasis></title>
3043 <para>
3044 <itemizedlist>
3045 <listitem>
3046 <para>
3047 Receive OK &rarr; <emphasis>authenticated</emphasis>,
3048 choose one:
3049
3050 <simplelist>
3051 <member>
3052 send NEGOTIATE_UNIX_FD, goto
3053 <emphasis>WaitingForAgreeUnixFD</emphasis>
3054 </member>
3055
3056 <member>
3057 send BEGIN, terminate auth conversation (successfully)
3058 </member>
3059 </simplelist>
3060 </para>
3061 </listitem>
3062 <listitem>
3063 <para>
3064 Receive REJECTED [mechs] &rarr; send AUTH [next mech],
3065 goto <emphasis>WaitingForData</emphasis> or
3066 <emphasis>WaitingForOK</emphasis>
3067 </para>
3068 </listitem>
3069
3070 <listitem>
3071 <para>
3072 Receive DATA &rarr; send CANCEL, goto
3073 <emphasis>WaitingForReject</emphasis>
3074 </para>
3075 </listitem>
3076
3077 <listitem>
3078 <para>
3079 Receive ERROR &rarr; send CANCEL, goto
3080 <emphasis>WaitingForReject</emphasis>
3081 </para>
3082 </listitem>
3083
3084 <listitem>
3085 <para>
3086 Receive anything else &rarr; send ERROR, goto
3087 <emphasis>WaitingForOK</emphasis>
3088 </para>
3089 </listitem>
3090 </itemizedlist>
3091 </para>
3092 </formalpara>
3093
3094 <formalpara>
3095 <title><emphasis>WaitingForReject</emphasis></title>
3096 <para>
3097 <itemizedlist>
3098 <listitem>
3099 <para>
3100 Receive REJECTED [mechs] &rarr; send AUTH [next mech],
3101 goto <emphasis>WaitingForData</emphasis> or
3102 <emphasis>WaitingForOK</emphasis>
3103 </para>
3104 </listitem>
3105
3106 <listitem>
3107 <para>
3108 Receive anything else &rarr; terminate auth
3109 conversation, disconnect
3110 </para>
3111 </listitem>
3112 </itemizedlist>
3113 </para>
3114 </formalpara>
3115
3116 <formalpara>
3117 <title><emphasis>WaitingForAgreeUnixFD</emphasis></title>
3118 <para>
3119 By the time this state is reached, the client has already
3120 been authenticated.
3121 <itemizedlist>
3122 <listitem>
3123 <para>
3124 Receive AGREE_UNIX_FD &rarr; enable Unix fd passing,
3125 send BEGIN, terminate auth conversation (successfully)
3126 </para>
3127 </listitem>
3128
3129 <listitem>
3130 <para>
3131 Receive ERROR &rarr; disable Unix fd passing,
3132 send BEGIN, terminate auth conversation (successfully)
3133 </para>
3134 </listitem>
3135
3136 <listitem>
3137 <para>
3138 Receive anything else &rarr; terminate auth
3139 conversation, disconnect
3140 </para>
3141 </listitem>
3142 </itemizedlist>
3143 </para>
3144 </formalpara>
3145
3146 </sect3>
3147
3148 <sect3 id="auth-states-server">
3149 <title>Server states</title>
3150
3151 <para>
3152 For the server MECH(RESP) means that the client response
3153 RESP was fed to the the mechanism MECH, which returns one of
3154
3155 <itemizedlist>
3156 <listitem>
3157 <para>
3158 CONTINUE(CHALL) means continue the auth conversation and
3159 send CHALL as the challenge to the client;
3160 </para>
3161 </listitem>
3162
3163 <listitem>
3164 <para>
3165 OK means that the client has been successfully
3166 authenticated;
3167 </para>
3168 </listitem>
3169
3170 <listitem>
3171 <para>
3172 REJECTED means that the client failed to authenticate or
3173 there was an error in RESP.
3174 </para>
3175 </listitem>
3176 </itemizedlist>
3177
3178 The server starts out in state
3179 <emphasis>WaitingForAuth</emphasis>. If the client is
3180 rejected too many times the server must disconnect the
3181 client.
3182 </para>
3183
3184 <formalpara>
3185 <title><emphasis>WaitingForAuth</emphasis></title>
3186 <para>
3187 <itemizedlist>
3188
3189 <listitem>
3190 <para>
3191 Receive AUTH &rarr; send REJECTED [mechs], goto
3192 <emphasis>WaitingForAuth</emphasis>
3193 </para>
3194 </listitem>
3195
3196 <listitem>
3197 <para>
3198 Receive AUTH MECH RESP
3199
3200 <simplelist>
3201 <member>
3202 MECH not valid mechanism &rarr; send REJECTED
3203 [mechs], goto
3204 <emphasis>WaitingForAuth</emphasis>
3205 </member>
3206
3207 <member>
3208 MECH(RESP) returns CONTINUE(CHALL) &rarr; send
3209 DATA CHALL, goto
3210 <emphasis>WaitingForData</emphasis>
3211 </member>
3212
3213 <member>
3214 MECH(RESP) returns OK &rarr; send OK, goto
3215 <emphasis>WaitingForBegin</emphasis>
3216 </member>
3217
3218 <member>
3219 MECH(RESP) returns REJECTED &rarr; send REJECTED
3220 [mechs], goto
3221 <emphasis>WaitingForAuth</emphasis>
3222 </member>
3223 </simplelist>
3224 </para>
3225 </listitem>
3226
3227 <listitem>
3228 <para>
3229 Receive BEGIN &rarr; terminate
3230 auth conversation, disconnect
3231 </para>
3232 </listitem>
3233
3234 <listitem>
3235 <para>
3236 Receive ERROR &rarr; send REJECTED [mechs], goto
3237 <emphasis>WaitingForAuth</emphasis>
3238 </para>
3239 </listitem>
3240
3241 <listitem>
3242 <para>
3243 Receive anything else &rarr; send
3244 ERROR, goto
3245 <emphasis>WaitingForAuth</emphasis>
3246 </para>
3247 </listitem>
3248 </itemizedlist>
3249 </para>
3250 </formalpara>
3251
3252
3253 <formalpara>
3254 <title><emphasis>WaitingForData</emphasis></title>
3255 <para>
3256 <itemizedlist>
3257 <listitem>
3258 <para>
3259 Receive DATA RESP
3260 <simplelist>
3261 <member>
3262 MECH(RESP) returns CONTINUE(CHALL) &rarr; send
3263 DATA CHALL, goto
3264 <emphasis>WaitingForData</emphasis>
3265 </member>
3266
3267 <member>
3268 MECH(RESP) returns OK &rarr; send OK, goto
3269 <emphasis>WaitingForBegin</emphasis>
3270 </member>
3271
3272 <member>
3273 MECH(RESP) returns REJECTED &rarr; send REJECTED
3274 [mechs], goto
3275 <emphasis>WaitingForAuth</emphasis>
3276 </member>
3277 </simplelist>
3278 </para>
3279 </listitem>
3280
3281 <listitem>
3282 <para>
3283 Receive BEGIN &rarr; terminate auth conversation,
3284 disconnect
3285 </para>
3286 </listitem>
3287
3288 <listitem>
3289 <para>
3290 Receive CANCEL &rarr; send REJECTED [mechs], goto
3291 <emphasis>WaitingForAuth</emphasis>
3292 </para>
3293 </listitem>
3294
3295 <listitem>
3296 <para>
3297 Receive ERROR &rarr; send REJECTED [mechs], goto
3298 <emphasis>WaitingForAuth</emphasis>
3299 </para>
3300 </listitem>
3301
3302 <listitem>
3303 <para>
3304 Receive anything else &rarr; send ERROR, goto
3305 <emphasis>WaitingForData</emphasis>
3306 </para>
3307 </listitem>
3308 </itemizedlist>
3309 </para>
3310 </formalpara>
3311
3312 <formalpara>
3313 <title><emphasis>WaitingForBegin</emphasis></title>
3314 <para>
3315 <itemizedlist>
3316 <listitem>
3317 <para>
3318 Receive BEGIN &rarr; terminate auth conversation,
3319 client authenticated
3320 </para>
3321 </listitem>
3322
3323 <listitem>
3324 <para>
3325 Receive NEGOTIATE_UNIX_FD &rarr; send AGREE_UNIX_FD
3326 or ERROR, goto <emphasis>WaitingForBegin</emphasis>
3327 </para>
3328 </listitem>
3329
3330 <listitem>
3331 <para>
3332 Receive CANCEL &rarr; send REJECTED [mechs], goto
3333 <emphasis>WaitingForAuth</emphasis>
3334 </para>
3335 </listitem>
3336
3337 <listitem>
3338 <para>
3339 Receive ERROR &rarr; send REJECTED [mechs], goto
3340 <emphasis>WaitingForAuth</emphasis>
3341 </para>
3342 </listitem>
3343
3344 <listitem>
3345 <para>
3346 Receive anything else &rarr; send ERROR, goto
3347 <emphasis>WaitingForBegin</emphasis>
3348 </para>
3349 </listitem>
3350 </itemizedlist>
3351 </para>
3352 </formalpara>
3353
3354 </sect3>
3355
3356 </sect2>
3357 <sect2 id="auth-mechanisms">
3358 <title>Authentication mechanisms</title>
3359 <para>
3360 This section describes some authentication mechanisms that are
3361 often supported by practical D-Bus implementations. The D-Bus
3362 protocol also allows any other standard SASL mechanism, although
3363 implementations of D-Bus often do not.
3364 </para>
3365 <sect3 id="auth-mechanisms-external">
3366 <title>EXTERNAL</title>
3367 <para>
3368 The EXTERNAL mechanism is defined in <ulink
3369 url="https://tools.ietf.org/html/rfc4422#appendix-A">RFC 4422
3370 "Simple Authentication and Security Layer (SASL)", appendix A
3371 "The SASL EXTERNAL Mechanism"</ulink>. This is the recommended
3372 authentication mechanism on platforms where credentials can be
3373 transferred out-of-band, in particular Unix platforms that can
3374 perform credentials-passing over the
3375 <link linkend="transports-unix-domain-sockets-addresses"
3376 >unix: transport</link>.
3377 </para>
3378 <para>
3379 On Unix platforms, interoperable clients should prefer to send
3380 the ASCII decimal string form of the integer Unix user ID as
3381 the authorization identity, for example 1000. When encoded in
3382 hex by the authentication protocol, this will typically result
3383 in a line like <literal>AUTH EXTERNAL 31303030</literal> followed
3384 by \r\n.
3385 </para>
3386 <para>
3387 On Windows platforms, clients that use the EXTERNAL mechanism
3388 should use the Windows security identifier in its string form
3389 as the authorization identity, for example
3390 <literal>S-1-5-21-3623811015-3361044348-30300820-1013</literal> for
3391 a domain or local computer user or <literal>S-1-5-18</literal> for
3392 the LOCAL_SYSTEM user. When encoded in hex by the authentication
3393 protocol, this will typically result in a line like
3394 <literal>AUTH EXTERNAL 532d312d352d3138</literal> followed by
3395 \r\n.
3396 </para>
3397 </sect3>
3398 <sect3 id="auth-mechanisms-sha">
3399 <title>DBUS_COOKIE_SHA1</title>
3400 <para>
3401 DBUS_COOKIE_SHA1 is a D-Bus-specific SASL mechanism. Its
3402 reference implementation is part of the reference implementation
3403 of D-Bus.
3404 </para>
3405 <para>
3406 This mechanism is designed to establish that a client
3407 has the ability to read a private file owned by the user being
3408 authenticated. If the client can prove that it has access to a secret
3409 cookie stored in this file, then the client is authenticated.
3410 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
3411 directory. This is the recommended authentication mechanism
3412 for platforms and configurations where EXTERNAL cannot be used.
3413 </para>
3414 <para>
3415 Throughout this description, "hex encoding" must output the digits
3416 from a to f in lower-case; the digits A to F must not be used
3417 in the DBUS_COOKIE_SHA1 mechanism.
3418 </para>
3419 <para>
3420 Authentication proceeds as follows:
3421 <itemizedlist>
3422 <listitem>
3423 <para>
3424 The client sends the username it would like to authenticate
3425 as, hex-encoded.
3426 </para>
3427 </listitem>
3428 <listitem>
3429 <para>
3430 The server sends the name of its "cookie context" (see below); a
3431 space character; the integer ID of the secret cookie the client
3432 must demonstrate knowledge of; a space character; then a
3433 randomly-generated challenge string, all of this hex-encoded into
3434 one, single string.
3435 </para>
3436 </listitem>
3437 <listitem>
3438 <para>
3439 The client locates the cookie and generates its own
3440 randomly-generated challenge string. The client then concatenates
3441 the server's decoded challenge, a ":" character, its own challenge,
3442 another ":" character, and the cookie. It computes the SHA-1 hash
3443 of this composite string as a hex digest. It concatenates the
3444 client's challenge string, a space character, and the SHA-1 hex
3445 digest, hex-encodes the result and sends it back to the server.
3446 </para>
3447 </listitem>
3448 <listitem>
3449 <para>
3450 The server generates the same concatenated string used by the
3451 client and computes its SHA-1 hash. It compares the hash with
3452 the hash received from the client; if the two hashes match, the
3453 client is authenticated.
3454 </para>
3455 </listitem>
3456 </itemizedlist>
3457 </para>
3458 <para>
3459 Each server has a "cookie context," which is a name that identifies a
3460 set of cookies that apply to that server. A sample context might be
3461 "org_freedesktop_session_bus". Context names must be valid ASCII,
3462 nonzero length, and may not contain the characters slash ("/"),
3463 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"),
3464 tab ("\t"), or period ("."). There is a default context,
3465 "org_freedesktop_general" that's used by servers that do not specify
3466 otherwise.
3467 </para>
3468 <para>
3469 Cookies are stored in a user's home directory, in the directory
3470 <filename>~/.dbus-keyrings/</filename>. This directory must
3471 not be readable or writable by other users. If it is,
3472 clients and servers must ignore it. The directory
3473 contains cookie files named after the cookie context.
3474 </para>
3475 <para>
3476 A cookie file contains one cookie per line. Each line
3477 has three space-separated fields:
3478 <itemizedlist>
3479 <listitem>
3480 <para>
3481 The cookie ID number, which must be a non-negative integer and
3482 may not be used twice in the same file.
3483 </para>
3484 </listitem>
3485 <listitem>
3486 <para>
3487 The cookie's creation time, in UNIX seconds-since-the-epoch
3488 format.
3489 </para>
3490 </listitem>
3491 <listitem>
3492 <para>
3493 The cookie itself, a hex-encoded random block of bytes. The cookie
3494 may be of any length, though obviously security increases
3495 as the length increases.
3496 </para>
3497 </listitem>
3498 </itemizedlist>
3499 </para>
3500 <para>
3501 Only server processes modify the cookie file.
3502 They must do so with this procedure:
3503 <itemizedlist>
3504 <listitem>
3505 <para>
3506 Create a lockfile name by appending ".lock" to the name of the
3507 cookie file. The server should attempt to create this file
3508 using <literal>O_CREAT | O_EXCL</literal>. If file creation
3509 fails, the lock fails. Servers should retry for a reasonable
3510 period of time, then they may choose to delete an existing lock
3511 to keep users from having to manually delete a stale
3512 lock. <footnote><para>Lockfiles are used instead of real file
3513 locking <literal>fcntl()</literal> because real locking
3514 implementations are still flaky on network
3515 filesystems.</para></footnote>
3516 </para>
3517 </listitem>
3518 <listitem>
3519 <para>
3520 Once the lockfile has been created, the server loads the cookie
3521 file. It should then delete any cookies that are old (the
3522 timeout can be fairly short), or more than a reasonable
3523 time in the future (so that cookies never accidentally
3524 become permanent, if the clock was set far into the future
3525 at some point). The reference implementation deletes cookies
3526 that are more than 5 minutes into the future, or more than
3527 7 minutes in the past. For interoperability, using the
3528 same arbitrary times in other implementations is suggested.
3529 </para>
3530 </listitem>
3531 <listitem>
3532 <para>
3533 If no sufficiently recent cookies remain, the server
3534 generates a new cookie. To avoid spurious authentication
3535 failures, cookies that are close to their deletion time
3536 should not be used for new authentication operations.
3537 For example, this avoids a client starting to use a cookie
3538 whose age is 6m59s, and having authentication subsequently
3539 fail because it takes 2 seconds, during which time the
3540 cookie's age became 7m01s, greater than 7 minutes, causing
3541 the server to delete it. The reference implementation
3542 generates a new cookie whenever the most recent cookie is
3543 older than 5 minutes, giving clients at least 2 minutes
3544 to finish authentication. For interoperability, using the
3545 same arbitrary time in other implementations is suggested.
3546 </para>
3547 </listitem>
3548 <listitem>
3549 <para>
3550 The pruned and possibly added-to cookie file
3551 must be resaved atomically (using a temporary
3552 file which is rename()'d).
3553 </para>
3554 </listitem>
3555 <listitem>
3556 <para>
3557 The lock must be dropped by deleting the lockfile.
3558 </para>
3559 </listitem>
3560 </itemizedlist>
3561 </para>
3562 <para>
3563 Clients need not lock the file in order to load it,
3564 because servers are required to save the file atomically.
3565 </para>
3566 </sect3>
3567 <sect3 id="auth-mechanisms-anonymous">
3568 <title>ANONYMOUS</title>
3569 <para>
3570 The ANONYMOUS mechanism is defined in <ulink
3571 url="https://tools.ietf.org/html/rfc4505">RFC 4505 "Anonymous
3572 Simple Authentication and Security Layer (SASL)
3573 Mechanism"</ulink>.
3574 It does not perform any authentication at all, and should not
3575 be accepted by message buses. However, it might sometimes be
3576 useful for non-message-bus uses of D-Bus.
3577 </para>
3578 </sect3>
3579 </sect2>
3580 </sect1>
3581 <sect1 id="addresses">
3582 <title>Server Addresses</title>
3583 <para>
3584 Server addresses consist of a transport name followed by a colon, and
3585 then an optional, comma-separated list of keys and values in the form key=value.
3586 Each value is escaped.
3587 </para>
3588 <para>
3589 For example:
3590 <programlisting>unix:path=/tmp/dbus-test</programlisting>
3591 Which is the address to a unix socket with the path /tmp/dbus-test.
3592 </para>
3593 <para>
3594 Value escaping is similar to URI escaping but simpler.
3595 <itemizedlist>
3596 <listitem>
3597 <para>
3598 The set of optionally-escaped bytes is:
3599 <literal>[-0-9A-Za-z_/.\*]</literal>. To escape, each
3600 <emphasis>byte</emphasis> (note, not character) which is not in the
3601 set of optionally-escaped bytes must be replaced with an ASCII
3602 percent (<literal>%</literal>) and the value of the byte in hex.
3603 The hex value must always be two digits, even if the first digit is
3604 zero. The optionally-escaped bytes may be escaped if desired.
3605 </para>
3606 </listitem>
3607 <listitem>
3608 <para>
3609 To unescape, append each byte in the value; if a byte is an ASCII
3610 percent (<literal>%</literal>) character then append the following
3611 hex value instead. It is an error if a <literal>%</literal> byte
3612 does not have two hex digits following. It is an error if a
3613 non-optionally-escaped byte is seen unescaped.
3614 </para>
3615 </listitem>
3616 </itemizedlist>
3617 The set of optionally-escaped bytes is intended to preserve address
3618 readability and convenience.
3619 </para>
3620
3621 <para>
3622 A server may specify a key-value pair with the key <literal>guid</literal>
3623 and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
3624 describes the format of the <literal>guid</literal> field. If present,
3625 this UUID may be used to distinguish one server address from another. A
3626 server should use a different UUID for each address it listens on. For
3627 example, if a message bus daemon offers both UNIX domain socket and TCP
3628 connections, but treats clients the same regardless of how they connect,
3629 those two connections are equivalent post-connection but should have
3630 distinct UUIDs to distinguish the kinds of connection.
3631 </para>
3632
3633 <para>
3634 The intent of the address UUID feature is to allow a client to avoid
3635 opening multiple identical connections to the same server, by allowing the
3636 client to check whether an address corresponds to an already-existing
3637 connection. Comparing two addresses is insufficient, because addresses
3638 can be recycled by distinct servers, and equivalent addresses may look
3639 different if simply compared as strings (for example, the host in a TCP
3640 address can be given as an IP address or as a hostname).
3641 </para>
3642
3643 <para>
3644 Note that the address key is <literal>guid</literal> even though the
3645 rest of the API and documentation says "UUID," for historical reasons.
3646 </para>
3647
3648 <para>
3649 [FIXME clarify if attempting to connect to each is a requirement
3650 or just a suggestion]
3651 When connecting to a server, multiple server addresses can be
3652 separated by a semi-colon. The library will then try to connect
3653 to the first address and if that fails, it'll try to connect to
3654 the next one specified, and so forth. For example
3655 <programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
3656 </para>
3657
3658 <para>
3659 Some addresses are <firstterm>connectable</firstterm>. A connectable
3660 address is one containing enough information for a client to connect
3661 to it. For instance, <literal>tcp:host=127.0.0.1,port=4242</literal>
3662 is a connectable address. It is not necessarily possible to listen
3663 on every connectable address: for instance, it is not possible to
3664 listen on a <literal>unixexec:</literal> address.
3665 </para>
3666
3667 <para>
3668 Some addresses are <firstterm>listenable</firstterm>. A listenable
3669 address is one containing enough information for a server to listen on
3670 it, producing a connectable address (which may differ from the
3671 original address). Many listenable addresses are not connectable:
3672 for instance, <literal>tcp:host=127.0.0.1</literal>
3673 is listenable, but not connectable (because it does not specify
3674 a port number).
3675 </para>
3676
3677 <para>
3678 Listening on an address that is not connectable will result in a
3679 connectable address that is not the same as the listenable address.
3680 For instance, listening on <literal>tcp:host=127.0.0.1</literal>
3681 might result in the connectable address
3682 <literal>tcp:host=127.0.0.1,port=30958</literal>,
3683 listening on <literal>unix:tmpdir=/tmp</literal>
3684 might result in the connectable address
3685 <literal>unix:abstract=/tmp/dbus-U8OSdmf7</literal>, or
3686 listening on <literal>unix:runtime=yes</literal>
3687 might result in the connectable address
3688 <literal>unix:path=/run/user/1234/bus</literal>.
3689 </para>
3690 </sect1>
3691
3692 <sect1 id="transports">
3693 <title>Transports</title>
3694 <para>
3695 [FIXME we need to specify in detail each transport and its possible arguments]
3696
3697 Current transports include: unix domain sockets (including
3698 abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport
3699 using in-process pipes. Future possible transports include one that
3700 tunnels over X11 protocol.
3701 </para>
3702
3703 <sect2 id="transports-unix-domain-sockets">
3704 <title>Unix Domain Sockets</title>
3705 <para>
3706 Unix domain sockets can be either paths in the file system or on Linux
3707 kernels, they can be abstract which are similar to paths but
3708 do not show up in the file system.
3709 </para>
3710
3711 <para>
3712 When a Unix socket is opened by the D-Bus library, the socket address
3713 length does not include the whole <literal>struct sockaddr_un</literal>,
3714 but only the length of the pathname or abstract string (beside other
3715 fields).
3716 </para>
3717 <para>
3718 They are the recommended transport for D-Bus, either used alone or in
3719 conjunction with <link linkend="transports-systemd">systemd</link> or
3720 <link linkend="transports-launchd">launchd</link> addresses.
3721 </para>
3722 <para>
3723 Unix addresses that specify <literal>path</literal> or
3724 <literal>abstract</literal> are both listenable and connectable.
3725 Unix addresses that specify <literal>tmpdir</literal>
3726 or <literal>dir</literal> are only
3727 listenable: the corresponding connectable address will specify
3728 either <literal>path</literal> or <literal>abstract</literal>.
3729 Similarly, Unix addresses that specify <literal>runtime</literal>
3730 are only listenable, and the corresponding connectable address
3731 will specify <literal>path</literal>.
3732 </para>
3733 <sect3 id="transports-unix-domain-sockets-addresses">
3734 <title>Server Address Format</title>
3735 <para>
3736 Unix domain socket addresses are identified by the "unix:" prefix
3737 and support the following key/value pairs:
3738 </para>
3739 <informaltable>
3740 <tgroup cols="3">
3741 <thead>
3742 <row>
3743 <entry>Name</entry>
3744 <entry>Values</entry>
3745 <entry>Description</entry>
3746 </row>
3747 </thead>
3748 <tbody>
3749 <row>
3750 <entry>path</entry>
3751 <entry>(path)</entry>
3752 <entry>
3753 Path of the unix domain socket.
3754 </entry>
3755 </row>
3756 <row>
3757 <entry>dir</entry>
3758 <entry>(path)</entry>
3759 <entry>
3760 Directory in which a socket file with a random file name
3761 starting with 'dbus-' will be created by the server. This key
3762 can only be used in server addresses, not in client addresses;
3763 the resulting client address will have the "path" key instead.
3764 be set.
3765 </entry>
3766 </row>
3767 <row>
3768 <entry>tmpdir</entry>
3769 <entry>(path)</entry>
3770 <entry>
3771 The same as "dir", except that on platforms with
3772 abstract sockets, the server may attempt to create an
3773 abstract socket whose name starts with this directory instead
3774 of a path-based socket.
3775 The server is not required to create an abstract socket, even
3776 on platforms that support it: treating "tmpdir" as being
3777 equivalent to "dir" is a valid implementation, and recent
3778 versions of the reference implementation of D-Bus do this.
3779 See "abstract", below, for more details of the consequences
3780 of using abstract sockets.
3781 Like "dir", this key can only be used in server
3782 addresses, not in client addresses; the resulting client address
3783 will have the "abstract" or "path" key instead.
3784 </entry>
3785 </row>
3786 <row>
3787 <entry>abstract</entry>
3788 <entry>(string)</entry>
3789 <entry>
3790 Unique string in the abstract namespace, often syntactically
3791 resembling a path but unconnected to the filesystem namespace.
3792 This key is only supported on platforms with abstract Unix
3793 sockets, of which Linux is the only known example.
3794 Implementors should note that on Linux, abstract sockets are
3795 namespaced according to
3796 <ulink url="https://man7.org/linux/man-pages/man7/network_namespaces.7.html"
3797 >network namespaces</ulink>
3798 rather than being part of the filesystem.
3799 This means that abstract sockets are unaffected by mechanisms
3800 like
3801 <ulink url="https://man7.org/linux/man-pages/man2/chroot.2.html"
3802 >chroot(2)</ulink>
3803 and
3804 <ulink url="https://man7.org/linux/man-pages/man7/mount_namespaces.7.html"
3805 >mount namespaces</ulink>,
3806 which can lead to a sandbox escape if a sandboxing
3807 implementation alters the sandboxed process's view of the
3808 filesystem but shares the network namespace with the host.
3809 </entry>
3810 </row>
3811 <row>
3812 <entry>runtime</entry>
3813 <entry><literal>yes</literal></entry>
3814 <entry>If given, This key can only be used in server addresses, not in client addresses. If set, its value must be <literal>yes</literal>. This is typically used in an address string like <literal>unix:runtime=yes;unix:tmpdir=/tmp</literal> so that there can be a fallback if <literal>XDG_RUNTIME_DIR</literal> is not set.</entry>
3815 </row>
3816 </tbody>
3817 </tgroup>
3818 </informaltable>
3819 <para>
3820 Exactly one of the keys <literal>path</literal>,
3821 <literal>abstract</literal>, <literal>runtime</literal>,
3822 <literal>dir</literal> or <literal>tmpdir</literal> must be provided.
3823 </para>
3824 </sect3>
3825 </sect2>
3826 <sect2 id="transports-launchd">
3827 <title>launchd</title>
3828 <para>
3829 launchd is an open-source server management system that replaces init, inetd
3830 and cron on Apple Mac OS X versions 10.4 and above. It provides a common session
3831 bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.
3832 </para>
3833
3834 <para>
3835 launchd allocates a socket and provides it with the unix path through the
3836 DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process
3837 spawned by launchd (or dbus-daemon, if it was started by launchd) can access
3838 it through its environment.
3839 Other processes can query for the launchd socket by executing:
3840 $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET
3841 This is normally done by the D-Bus client library so doesn't have to be done
3842 manually.
3843 </para>
3844 <para>
3845 launchd is not available on Microsoft Windows.
3846 </para>
3847 <para>
3848 launchd addresses are listenable and connectable.
3849 </para>
3850 <sect3 id="transports-launchd-addresses">
3851 <title>Server Address Format</title>
3852 <para>
3853 launchd addresses are identified by the "launchd:" prefix
3854 and support the following key/value pairs:
3855 </para>
3856 <informaltable>
3857 <tgroup cols="3">
3858 <thead>
3859 <row>
3860 <entry>Name</entry>
3861 <entry>Values</entry>
3862 <entry>Description</entry>
3863 </row>
3864 </thead>
3865 <tbody>
3866 <row>
3867 <entry>env</entry>
3868 <entry>(environment variable)</entry>
3869 <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
3870 </row>
3871 </tbody>
3872 </tgroup>
3873 </informaltable>
3874 <para>
3875 The <literal>env</literal> key is required.
3876 </para>
3877 </sect3>
3878 </sect2>
3879 <sect2 id="transports-systemd">
3880 <title>systemd</title>
3881 <para>
3882 systemd is an open-source server management system that
3883 replaces init and inetd on newer Linux systems. It supports
3884 socket activation. The D-Bus systemd transport is used to acquire
3885 socket activation file descriptors from systemd and use them
3886 as D-Bus transport when the current process is spawned by
3887 socket activation from it.
3888 </para>
3889 <para>
3890 The systemd transport accepts only one or more Unix domain or
3891 TCP streams sockets passed in via socket activation. Using
3892 Unix domain sockets is strongly recommended.
3893 </para>
3894 <para>
3895 The systemd transport is not available on non-Linux operating systems.
3896 </para>
3897 <para>
3898 The systemd transport defines no parameter keys.
3899 </para>
3900 <para>
3901 systemd addresses are listenable, but not connectable. The
3902 corresponding connectable address is the <literal>unix</literal>
3903 or <literal>tcp</literal> address of the socket.
3904 </para>
3905 </sect2>
3906 <sect2 id="transports-tcp-sockets">
3907 <title>TCP Sockets</title>
3908 <para>
3909 The tcp transport provides TCP/IP based connections between clients
3910 located on the same or different hosts.
3911 </para>
3912 <para>
3913 Similar to remote X11, the TCP transport has no integrity or
3914 confidentiality protection, so it should normally only be
3915 used across the local loopback interface, for example using an
3916 address like <literal>tcp:host=127.0.0.1</literal> or
3917 <literal>tcp:host=localhost</literal>. In particular,
3918 configuring the well-known system bus or the well-known session
3919 bus to listen on a non-loopback TCP address is insecure.
3920 </para>
3921 <para>
3922 On Windows and most Unix platforms, the TCP stack is unable to transfer
3923 credentials over a TCP connection, so the
3924 <link linkend="auth-mechanisms-external">EXTERNAL</link>
3925 authentication mechanism does not normally work for this transport
3926 (although the reference implementation of D-Bus is able to identify
3927 loopback TCPv4 connections on Windows by their port number,
3928 partially enabling the EXTERNAL mechanism).
3929 The <link linkend="auth-mechanisms-sha">DBUS_COOKIE_SHA1</link>
3930 mechanism is normally used instead.
3931 </para>
3932 <para>
3933 Developers are sometimes tempted to use remote TCP as a debugging
3934 tool. However, if this functionality is left enabled in finished
3935 products, the result will be dangerously insecure. Instead of
3936 using remote TCP, developers should <ulink
3937 url="https://lists.freedesktop.org/archives/dbus/2018-April/017447.html"
3938 >relay connections via Secure Shell or a similar protocol</ulink>.
3939 <!-- TODO: Ideally someone would write a more formal guide to
3940 remote D-Bus debugging, and we could link to that instead -->
3941 </para>
3942 <para>
3943 Remote TCP connections were historically sometimes used to share
3944 a single session bus between login sessions of the same user on
3945 different machines within a trusted local area network, in
3946 conjunction with unencrypted remote X11, a NFS-shared home
3947 directory and NIS (YP) authentication. This is insecure against
3948 an attacker on the same LAN and should be considered strongly
3949 deprecated; more specifically, it is insecure in the same ways
3950 and for the same reasons as unencrypted remote X11 and NFSv2/NFSv3.
3951 The D-Bus maintainers
3952 recommend using a separate session bus per (user, machine) pair,
3953 only accessible from within that machine.
3954 </para>
3955 <para>
3956 All <literal>tcp</literal> addresses are listenable.
3957 <literal>tcp</literal> addresses in which both
3958 <literal>host</literal> and <literal>port</literal> are
3959 specified, and <literal>port</literal> is non-zero,
3960 are also connectable.
3961 </para>
3962 <sect3 id="transports-tcp-sockets-addresses">
3963 <title>Server Address Format</title>
3964 <para>
3965 TCP/IP socket addresses are identified by the "tcp:" prefix
3966 and support the following key/value pairs:
3967 </para>
3968 <informaltable>
3969 <tgroup cols="3">
3970 <thead>
3971 <row>
3972 <entry>Name</entry>
3973 <entry>Values</entry>
3974 <entry>Description</entry>
3975 </row>
3976 </thead>
3977 <tbody>
3978 <row>
3979 <entry>host</entry>
3980 <entry>(string)</entry>
3981 <entry>DNS name or IP address</entry>
3982 </row>
3983 <row>
3984 <entry>bind</entry>
3985 <entry>(string)</entry>
3986 <entry>Used in a listenable address to configure the interface
3987 on which the server will listen: either the IP address of one of
3988 the local machine's interfaces (most commonly <literal>127.0.0.1
3989 </literal>), or a DNS name that resolves to one of those IP
3990 addresses, or '*' to listen on all interfaces simultaneously.
3991 If not specified, the default is the same value as "host".
3992 </entry>
3993 </row>
3994 <row>
3995 <entry>port</entry>
3996 <entry>(number)</entry>
3997 <entry>The tcp port the server will open. A zero value let the server
3998 choose a free port provided from the underlaying operating system.
3999 libdbus is able to retrieve the real used port from the server.
4000 </entry>
4001 </row>
4002 <row>
4003 <entry>family</entry>
4004 <entry>(string)</entry>
4005 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
4006 </row>
4007 </tbody>
4008 </tgroup>
4009 </informaltable>
4010 </sect3>
4011 </sect2>
4012 <sect2 id="transports-nonce-tcp-sockets">
4013 <title>Nonce-authenticated TCP Sockets</title>
4014 <para>
4015 The nonce-tcp transport provides a modified TCP transport using a
4016 simple authentication mechanism, to ensure that only clients with read
4017 access to a certain location in the filesystem can connect to the server.
4018 The server writes a secret, the nonce, to a file and an incoming client
4019 connection is only accepted if the client sends the nonce right after
4020 the connect. The nonce mechanism requires no setup and is orthogonal to
4021 the higher-level authentication mechanisms described in the
4022 Authentication section.
4023 </para>
4024 <para>
4025 The nonce-tcp transport is conceptually similar to a combination
4026 of the <link linkend="auth-mechanisms-sha">DBUS_COOKIE_SHA1</link>
4027 authentication mechanism and the
4028 <link linkend="transports-tcp-sockets">tcp</link> transport,
4029 and appears to have originally been implemented as a result of
4030 a misunderstanding of the SASL authentication mechanisms.
4031 </para>
4032 <para>
4033 Like the ordinary tcp transport, the nonce-tcp transport has no
4034 integrity or confidentiality protection, so it should normally
4035 only be used across the local loopback interface, for example
4036 using an address like <literal>tcp:host=127.0.0.1</literal> or
4037 <literal>tcp:host=localhost</literal>. Other uses are insecure.
4038 See <xref linkend="transports-tcp-sockets"/> for more
4039 information on situations where these transports have been used,
4040 and alternatives to these transports.
4041 </para>
4042
4043 <para>
4044 On start, the server generates a random 16 byte nonce and writes it
4045 to a file in the user's temporary directory. The nonce file location
4046 is published as part of the server's D-Bus address using the
4047 "noncefile" key-value pair.
4048
4049 After an accept, the server reads 16 bytes from the socket. If the
4050 read bytes do not match the nonce stored in the nonce file, the
4051 server MUST immediately drop the connection.
4052 If the nonce match the received byte sequence, the client is accepted
4053 and the transport behaves like an ordinary tcp transport.
4054 </para>
4055 <para>
4056 After a successful connect to the server socket, the client MUST read
4057 the nonce from the file published by the server via the noncefile=
4058 key-value pair and send it over the socket. After that, the
4059 transport behaves like an ordinary tcp transport.
4060 </para>
4061 <para>
4062 All nonce-tcp addresses are listenable. nonce-tcp addresses in which
4063 <literal>host</literal>, <literal>port</literal> and
4064 <literal>noncefile</literal> are all specified,
4065 and <literal>port</literal> is nonzero, are also connectable.
4066 </para>
4067 <sect3 id="transports-nonce-tcp-sockets-addresses">
4068 <title>Server Address Format</title>
4069 <para>
4070 Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix
4071 and support the following key/value pairs:
4072 </para>
4073 <informaltable>
4074 <tgroup cols="3">
4075 <thead>
4076 <row>
4077 <entry>Name</entry>
4078 <entry>Values</entry>
4079 <entry>Description</entry>
4080 </row>
4081 </thead>
4082 <tbody>
4083 <row>
4084 <entry>host</entry>
4085 <entry>(string)</entry>
4086 <entry>DNS name or IP address</entry>
4087 </row>
4088 <row>
4089 <entry>bind</entry>
4090 <entry>(string)</entry>
4091 <entry>The same as for tcp: addresses
4092 </entry>
4093 </row>
4094 <row>
4095 <entry>port</entry>
4096 <entry>(number)</entry>
4097 <entry>The tcp port the server will open. A zero value let the server
4098 choose a free port provided from the underlaying operating system.
4099 libdbus is able to retrieve the real used port from the server.
4100 </entry>
4101 </row>
4102 <row>
4103 <entry>family</entry>
4104 <entry>(string)</entry>
4105 <entry>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</entry>
4106 </row>
4107 <row>
4108 <entry>noncefile</entry>
4109 <entry>(path)</entry>
4110 <entry>File location containing the secret.
4111 This is only meaningful in connectable addresses:
4112 a listening D-Bus server that offers this transport
4113 will always create a new nonce file.</entry>
4114 </row>
4115 </tbody>
4116 </tgroup>
4117 </informaltable>
4118 </sect3>
4119 </sect2>
4120 <sect2 id="transports-exec">
4121 <title>Executed Subprocesses on Unix</title>
4122 <para>
4123 This transport forks off a process and connects its standard
4124 input and standard output with an anonymous Unix domain
4125 socket. This socket is then used for communication by the
4126 transport. This transport may be used to use out-of-process
4127 forwarder programs as basis for the D-Bus protocol.
4128 </para>
4129 <para>
4130 The forked process will inherit the standard error output and
4131 process group from the parent process.
4132 </para>
4133 <para>
4134 Executed subprocesses are not available on Windows.
4135 </para>
4136 <para>
4137 <literal>unixexec</literal> addresses are connectable, but are not
4138 listenable.
4139 </para>
4140 <sect3 id="transports-exec-addresses">
4141 <title>Server Address Format</title>
4142 <para>
4143 Executed subprocess addresses are identified by the "unixexec:" prefix
4144 and support the following key/value pairs:
4145 </para>
4146 <informaltable>
4147 <tgroup cols="3">
4148 <thead>
4149 <row>
4150 <entry>Name</entry>
4151 <entry>Values</entry>
4152 <entry>Description</entry>
4153 </row>
4154 </thead>
4155 <tbody>
4156 <row>
4157 <entry>path</entry>
4158 <entry>(path)</entry>
4159 <entry>Path of the binary to execute, either an absolute
4160 path or a binary name that is searched for in the default
4161 search path of the OS. This corresponds to the first
4162 argument of execlp(). This key is mandatory.</entry>
4163 </row>
4164 <row>
4165 <entry>argv0</entry>
4166 <entry>(string)</entry>
4167 <entry>The program name to use when executing the
4168 binary. If omitted the same value as specified for path=
4169 will be used. This corresponds to the second argument of
4170 execlp().</entry>
4171 </row>
4172 <row>
4173 <entry>argv1, argv2, ...</entry>
4174 <entry>(string)</entry>
4175 <entry>Arguments to pass to the binary. This corresponds
4176 to the third and later arguments of execlp(). If a
4177 specific argvX is not specified no further argvY for Y > X
4178 are taken into account.</entry>
4179 </row>
4180 </tbody>
4181 </tgroup>
4182 </informaltable>
4183 </sect3>
4184 </sect2>
4185 </sect1>
4186 <sect1 id="meta-transports">
4187 <title>Meta Transports</title>
4188 <para>
4189 Meta transports are a kind of transport with special enhancements or
4190 behavior. Currently available meta transports include: autolaunch
4191 </para>
4192
4193 <sect2 id="meta-transports-autolaunch">
4194 <title>Autolaunch</title>
4195 <para>The autolaunch transport provides a way for dbus clients to autodetect
4196 a running dbus session bus and to autolaunch a session bus if not present.
4197 </para>
4198 <para>
4199 On Unix, <literal>autolaunch</literal> addresses are connectable,
4200 but not listenable.
4201 </para>
4202 <para>
4203 On Windows, <literal>autolaunch</literal> addresses are both
4204 connectable and listenable.
4205 </para>
4206
4207 <sect3 id="meta-transports-autolaunch-addresses">
4208 <title>Server Address Format</title>
4209 <para>
4210 Autolaunch addresses uses the "autolaunch:" prefix and support the
4211 following key/value pairs:
4212 </para>
4213 <informaltable>
4214 <tgroup cols="3">
4215 <thead>
4216 <row>
4217 <entry>Name</entry>
4218 <entry>Values</entry>
4219 <entry>Description</entry>
4220 </row>
4221 </thead>
4222 <tbody>
4223 <row>
4224 <entry>scope</entry>
4225 <entry>(string)</entry>
4226 <entry>scope of autolaunch (Windows only)
4227 <itemizedlist>
4228 <listitem>
4229 <para>
4230 "*install-path" - limit session bus to dbus installation path.
4231 The dbus installation path is determined from the location of
4232 the shared dbus library. If the library is located in a 'bin'
4233 subdirectory the installation root is the directory above,
4234 otherwise the directory where the library lives is taken as
4235 installation root.
4236 <programlisting>
4237 &lt;install-root&gt;/bin/[lib]dbus-1.dll
4238 &lt;install-root&gt;/[lib]dbus-1.dll
4239 </programlisting>
4240 </para>
4241 </listitem>
4242 <listitem>
4243 <para>
4244 "*user" - limit session bus to the recent user.
4245 </para>
4246 </listitem>
4247 <listitem>
4248 <para>
4249 other values - specify dedicated session bus like "release",
4250 "debug" or other
4251 </para>
4252 </listitem>
4253 </itemizedlist>
4254 </entry>
4255 </row>
4256 </tbody>
4257 </tgroup>
4258 </informaltable>
4259 </sect3>
4260
4261 <sect3 id="meta-transports-autolaunch-windows-implementation">
4262 <title>Windows implementation</title>
4263 <para>
4264 On start, the server opens a platform specific transport, creates a mutex
4265 and a shared memory section containing the related session bus address.
4266 This mutex will be inspected by the dbus client library to detect a
4267 running dbus session bus. The access to the mutex and the shared memory
4268 section are protected by global locks.
4269 </para>
4270 <para>
4271 In the recent implementation the autolaunch transport uses a tcp transport
4272 on localhost with a port choosen from the operating system. This detail may
4273 change in the future.
4274 </para>
4275 <para>
4276 Disclaimer: The recent implementation is in an early state and may not
4277 work in all cirumstances and/or may have security issues. Because of this
4278 the implementation is not documentated yet.
4279 </para>
4280 </sect3>
4281 </sect2>
4282 </sect1>
4283
4284 <sect1 id="uuids">
4285 <title>UUIDs</title>
4286 <para>
4287 A working D-Bus implementation uses universally-unique IDs in two places.
4288 First, each server address has a UUID identifying the address,
4289 as described in <xref linkend="addresses"/>. Second, each operating
4290 system kernel instance running a D-Bus client or server has a UUID
4291 identifying that kernel, retrieved by invoking the method
4292 org.freedesktop.DBus.Peer.GetMachineId() (see <xref
4293 linkend="standard-interfaces-peer"/>).
4294 </para>
4295 <para>
4296 The term "UUID" in this document is intended literally, i.e. an
4297 identifier that is universally unique. It is not intended to refer to
4298 RFC4122, and in fact the D-Bus UUID is not compatible with that RFC.
4299 </para>
4300 <para>
4301 The UUID must contain 128 bits of data and be hex-encoded. The
4302 hex-encoded string may not contain hyphens or other non-hex-digit
4303 characters, and it must be exactly 32 characters long. To generate a
4304 UUID, the current reference implementation concatenates 96 bits of random
4305 data followed by the 32-bit time in seconds since the UNIX epoch (in big
4306 endian byte order).
4307 </para>
4308 <para>
4309 It would also be acceptable and probably better to simply generate 128
4310 bits of random data, as long as the random number generator is of high
4311 quality. The timestamp could conceivably help if the random bits are not
4312 very random. With a quality random number generator, collisions are
4313 extremely unlikely even with only 96 bits, so it's somewhat academic.
4314 </para>
4315 <para>
4316 Implementations should, however, stick to random data for the first 96 bits
4317 of the UUID.
4318 </para>
4319 </sect1>
4320
4321 <sect1 id="standard-interfaces">
4322 <title>Standard Interfaces</title>
4323 <para>
4324 See <xref linkend="message-protocol-types-notation"/> for details on
4325 the notation used in this section. There are some standard interfaces
4326 that may be useful across various D-Bus applications.
4327 </para>
4328 <sect2 id="standard-interfaces-peer">
4329 <title><literal>org.freedesktop.DBus.Peer</literal></title>
4330 <para>
4331 The <literal>org.freedesktop.DBus.Peer</literal> interface
4332 has two methods:
4333 <programlisting>
4334 org.freedesktop.DBus.Peer.Ping ()
4335 org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
4336 </programlisting>
4337 </para>
4338 <para>
4339 On receipt of the <literal>METHOD_CALL</literal> message
4340 <literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
4341 nothing other than reply with a <literal>METHOD_RETURN</literal> as
4342 usual. It does not matter which object path a ping is sent to. The
4343 reference implementation handles this method automatically.
4344 </para>
4345 <para>
4346 On receipt of the <literal>METHOD_CALL</literal> message
4347 <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
4348 reply with a <literal>METHOD_RETURN</literal> containing a hex-encoded
4349 UUID representing the identity of the machine the process is running on.
4350 This UUID must be the same for all processes on a single system at least
4351 until that system next reboots. It should be the same across reboots
4352 if possible, but this is not always possible to implement and is not
4353 guaranteed.
4354 It does not matter which object path a GetMachineId is sent to. The
4355 reference implementation handles this method automatically.
4356 </para>
4357 <para>
4358 On Unix, implementations should try to read the machine ID from
4359 <literal>/var/lib/dbus/machine-id</literal> and
4360 <literal>/etc/machine-id</literal>. The latter is
4361 <ulink url='https://www.freedesktop.org/software/systemd/man/machine-id.html'>
4362 defined by systemd</ulink>, but systems not using systemd may provide
4363 an equivalent file.
4364 If both exist, they are expected to have the same contents, and if they
4365 differ, the spec does not define which takes precedence (the reference
4366 implementation prefers <literal>/var/lib/dbus/machine-id</literal>,
4367 but sd-bus does not).
4368 </para>
4369 <para>
4370 On Windows, the hardware profile GUID is used as the machine ID,
4371 with the punctuation removed. This can be obtained with the
4372 <ulink url='https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getcurrenthwprofilea'>
4373 <function>GetCurrentHwProfile</function></ulink> function.
4374 </para>
4375 <para>
4376 The UUID is intended to be per-instance-of-the-operating-system, so may represent
4377 a virtual machine running on a hypervisor, rather than a physical machine.
4378 Basically if two processes see the same UUID, they should also see the same
4379 shared memory, UNIX domain sockets, process IDs, and other features that require
4380 a running OS kernel in common between the processes.
4381 </para>
4382 <para>
4383 The UUID is often used where other programs might use a hostname. Hostnames
4384 can change without rebooting, however, or just be "localhost" - so the UUID
4385 is more robust.
4386 </para>
4387 <para>
4388 <xref linkend="uuids"/> explains the format of the UUID.
4389 </para>
4390 </sect2>
4391
4392 <sect2 id="standard-interfaces-introspectable">
4393 <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
4394 <para>
4395 This interface has one method:
4396 <programlisting>
4397 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
4398 </programlisting>
4399 </para>
4400 <para>
4401 Objects instances may implement
4402 <literal>Introspect</literal> which returns an XML description of
4403 the object, including its interfaces (with signals and methods), objects
4404 below it in the object path tree, and its properties.
4405 </para>
4406 <para>
4407 <xref linkend="introspection-format"/> describes the format of this XML string.
4408 </para>
4409 </sect2>
4410 <sect2 id="standard-interfaces-properties">
4411 <title><literal>org.freedesktop.DBus.Properties</literal></title>
4412 <para>
4413 Many native APIs will have a concept of object <firstterm>properties</firstterm>
4414 or <firstterm>attributes</firstterm>. These can be exposed via the
4415 <literal>org.freedesktop.DBus.Properties</literal> interface.
4416 </para>
4417 <para>
4418 <programlisting>
4419 org.freedesktop.DBus.Properties.Get (in STRING interface_name,
4420 in STRING property_name,
4421 out VARIANT value);
4422 org.freedesktop.DBus.Properties.Set (in STRING interface_name,
4423 in STRING property_name,
4424 in VARIANT value);
4425 org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
4426 out ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; props);
4427 </programlisting>
4428 </para>
4429 <para>
4430 It is conventional to give D-Bus properties names consisting of
4431 capitalized words without punctuation ("CamelCase"), like
4432 <link linkend="message-protocol-names-member">member names</link>.
4433 For instance, the GObject property
4434 <literal>connection-status</literal> or the Qt property
4435 <literal>connectionStatus</literal> could be represented on D-Bus
4436 as <literal>ConnectionStatus</literal>.
4437 </para>
4438 <para>
4439 Strictly speaking, D-Bus property names are not required to follow
4440 the same naming restrictions as member names, but D-Bus property
4441 names that would not be valid member names (in particular,
4442 GObject-style dash-separated property names) can cause interoperability
4443 problems and should be avoided.
4444 </para>
4445 <para>
4446 The available properties and whether they are writable can be determined
4447 by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
4448 see <xref linkend="standard-interfaces-introspectable"/>.
4449 </para>
4450 <para>
4451 An empty string may be provided for the interface name; in this case,
4452 if there are multiple properties on an object with the same name,
4453 the results are undefined (picking one by according to an arbitrary
4454 deterministic rule, or returning an error, are the reasonable
4455 possibilities).
4456 </para>
4457 <para>
4458 If <literal>org.freedesktop.DBus.Properties.GetAll</literal> is called
4459 with a valid interface name which contains no properties, an empty array
4460 should be returned. If it is called with a valid interface name for
4461 which some properties are not accessible to the caller (for example, due
4462 to per-property access control implemented in the service), those
4463 properties should be silently omitted from the result array.
4464 If <literal>org.freedesktop.DBus.Properties.Get</literal> is called for
4465 any such properties, an appropriate access control error should be
4466 returned.
4467 </para>
4468 <para>
4469 If one or more properties change on an object, the
4470 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
4471 signal may be emitted (this signal was added in 0.14):
4472 </para>
4473 <para>
4474 <programlisting>
4475 org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
4476 ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; changed_properties,
4477 ARRAY&lt;STRING&gt; invalidated_properties);
4478 </programlisting>
4479 </para>
4480 <para>
4481 where <literal>changed_properties</literal> is a dictionary
4482 containing the changed properties with the new values and
4483 <literal>invalidated_properties</literal> is an array of
4484 properties that changed but the value is not conveyed.
4485 </para>
4486 <para>
4487 Whether the <literal>PropertiesChanged</literal> signal is
4488 supported can be determined by calling
4489 <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
4490 that the signal may be supported for an object but it may
4491 differ how whether and how it is used on a per-property basis
4492 (for e.g. performance or security reasons). Each property (or
4493 the parent interface) must be annotated with the
4494 <literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
4495 annotation to convey this (usually the default value
4496 <literal>true</literal> is sufficient meaning that the
4497 annotation does not need to be used). See <xref
4498 linkend="introspection-format"/> for details on this
4499 annotation.
4500 </para>
4501 </sect2>
4502
4503 <sect2 id="standard-interfaces-objectmanager">
4504 <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
4505 <para>
4506 An API can optionally make use of this interface for one or
4507 more sub-trees of objects. The root of each sub-tree implements
4508 this interface so other applications can get all objects,
4509 interfaces and properties in a single method call. It is
4510 appropriate to use this interface if users of the tree of
4511 objects are expected to be interested in all interfaces of all
4512 objects in the tree; a more granular API should be used if
4513 users of the objects are expected to be interested in a small
4514 subset of the objects, a small subset of their interfaces, or
4515 both.
4516 </para>
4517 <para>
4518 The method that applications can use to get all objects and
4519 properties is <literal>GetManagedObjects</literal>:
4520 </para>
4521 <para>
4522 <programlisting>
4523 org.freedesktop.DBus.ObjectManager.GetManagedObjects (out ARRAY of DICT_ENTRY&lt;OBJPATH,ARRAY of DICT_ENTRY&lt;STRING,ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);
4524 </programlisting>
4525 </para>
4526 <para>
4527 The return value of this method is a dict whose keys are
4528 object paths. All returned object paths are children of the
4529 object path implementing this interface, i.e. their object
4530 paths start with the ObjectManager's object path plus '/'.
4531 </para>
4532 <para>
4533 Each value is a dict whose keys are interfaces names. Each
4534 value in this inner dict is the same dict that would be
4535 returned by the <link
4536 linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
4537 method for that combination of object path and interface. If
4538 an interface has no properties, the empty dict is returned.
4539 </para>
4540 <para>
4541 Changes are emitted using the following two signals:
4542 </para>
4543 <para>
4544 <programlisting>
4545 org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
4546 ARRAY of DICT_ENTRY&lt;STRING,ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;&gt; interfaces_and_properties);
4547 org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
4548 ARRAY&lt;STRING&gt; interfaces);
4549 </programlisting>
4550 </para>
4551 <para>
4552 The <literal>InterfacesAdded</literal> signal is emitted when
4553 either a new object is added or when an existing object gains
4554 one or more interfaces. The
4555 <literal>InterfacesRemoved</literal> signal is emitted
4556 whenever an object is removed or it loses one or more
4557 interfaces. The second parameter of the
4558 <literal>InterfacesAdded</literal> signal contains a dict with
4559 the interfaces and properties (if any) that have been added to
4560 the given object path. Similarly, the second parameter of the
4561 <literal>InterfacesRemoved</literal> signal contains an array
4562 of the interfaces that were removed. Note that changes on
4563 properties on existing interfaces are not reported using this
4564 interface - an application should also monitor the existing <link
4565 linkend="standard-interfaces-properties">PropertiesChanged</link>
4566 signal on each object.
4567 </para>
4568 <para>
4569 Applications SHOULD NOT export objects that are children of an
4570 object (directly or otherwise) implementing this interface but
4571 which are not returned in the reply from the
4572 <literal>GetManagedObjects()</literal> method of this
4573 interface on the given object.
4574 </para>
4575 <para>
4576 The intent of the <literal>ObjectManager</literal> interface
4577 is to make it easy to write a robust client
4578 implementation. The trivial client implementation only needs
4579 to make two method calls:
4580 </para>
4581 <para>
4582 <programlisting>
4583 org.freedesktop.DBus.AddMatch (bus_proxy,
4584 "type='signal',sender='org.example.App2',path_namespace='/org/example/App2'");
4585 objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
4586 </programlisting>
4587 </para>
4588 <para>
4589 on the message bus and the remote application's
4590 <literal>ObjectManager</literal>, respectively. Whenever a new
4591 remote object is created (or an existing object gains a new
4592 interface), the <literal>InterfacesAdded</literal> signal is
4593 emitted, and since this signal contains all properties for the
4594 interfaces, no calls to the
4595 <literal>org.freedesktop.Properties</literal> interface on the
4596 remote object are needed. Additionally, since the initial
4597 <literal>AddMatch()</literal> rule already includes signal
4598 messages from the newly created child object, no new
4599 <literal>AddMatch()</literal> call is needed.
4600 </para>
4601
4602 <para>
4603 <emphasis>
4604 The <literal>org.freedesktop.DBus.ObjectManager</literal>
4605 interface was added in version 0.17 of the D-Bus
4606 specification.
4607 </emphasis>
4608 </para>
4609 </sect2>
4610 </sect1>
4611
4612 <sect1 id="introspection-format">
4613 <title>Introspection Data Format</title>
4614 <para>
4615 As described in <xref linkend="standard-interfaces-introspectable"/>,
4616 objects may be introspected at runtime, returning an XML string
4617 that describes the object. The same XML format may be used in
4618 other contexts as well, for example as an "IDL" for generating
4619 static language bindings.
4620 </para>
4621 <para>
4622 Here is an example of introspection data:
4623 <programlisting>
4624 &lt;!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
4625 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"&gt;
4626 &lt;node name="/com/example/sample_object0"&gt;
4627 &lt;interface name="com.example.SampleInterface0"&gt;
4628 &lt;method name="Frobate"&gt;
4629 &lt;arg name="foo" type="i" direction="in"/&gt;
4630 &lt;arg name="bar" type="s" direction="out"/&gt;
4631 &lt;arg name="baz" type="a{us}" direction="out"/&gt;
4632 &lt;annotation name="org.freedesktop.DBus.Deprecated" value="true"/&gt;
4633 &lt;/method&gt;
4634 &lt;method name="Bazify"&gt;
4635 &lt;arg name="bar" type="(iiu)" direction="in"/&gt;
4636 &lt;arg name="bar" type="v" direction="out"/&gt;
4637 &lt;/method&gt;
4638 &lt;method name="Mogrify"&gt;
4639 &lt;arg name="bar" type="(iiav)" direction="in"/&gt;
4640 &lt;/method&gt;
4641 &lt;signal name="Changed"&gt;
4642 &lt;arg name="new_value" type="b"/&gt;
4643 &lt;/signal&gt;
4644 &lt;property name="Bar" type="y" access="readwrite"/&gt;
4645 &lt;/interface&gt;
4646 &lt;node name="child_of_sample_object"/&gt;
4647 &lt;node name="another_child_of_sample_object"/&gt;
4648 &lt;/node&gt;
4649 </programlisting>
4650 </para>
4651 <para>
4652 A more formal DTD and spec needs writing, but here are some quick notes.
4653 <itemizedlist>
4654 <listitem>
4655 <para>
4656 Only the root &lt;node&gt; element can omit the node name, as it's
4657 known to be the object that was introspected. If the root
4658 &lt;node&gt; does have a name attribute, it must be an absolute
4659 object path. If child &lt;node&gt; have object paths, they must be
4660 relative.
4661 </para>
4662 </listitem>
4663 <listitem>
4664 <para>
4665 If a child &lt;node&gt; has any sub-elements, then they
4666 must represent a complete introspection of the child.
4667 If a child &lt;node&gt; is empty, then it may or may
4668 not have sub-elements; the child must be introspected
4669 in order to find out. The intent is that if an object
4670 knows that its children are "fast" to introspect
4671 it can go ahead and return their information, but
4672 otherwise it can omit it.
4673 </para>
4674 </listitem>
4675 <listitem>
4676 <para>
4677 The direction element on &lt;arg&gt; may be omitted,
4678 in which case it defaults to "in" for method calls
4679 and "out" for signals. Signals only allow "out"
4680 so while direction may be specified, it's pointless.
4681 </para>
4682 </listitem>
4683 <listitem>
4684 <para>
4685 The possible directions are "in" and "out",
4686 unlike CORBA there is no "inout"
4687 </para>
4688 </listitem>
4689 <listitem>
4690 <para>
4691 The possible property access flags are
4692 "readwrite", "read", and "write"
4693 </para>
4694 </listitem>
4695 <listitem>
4696 <para>
4697 Multiple interfaces can of course be listed for
4698 one &lt;node&gt;.
4699 </para>
4700 </listitem>
4701 <listitem>
4702 <para>
4703 The "name" attribute on arguments is optional.
4704 </para>
4705 </listitem>
4706 </itemizedlist>
4707 </para>
4708 <para>
4709 Method, interface, property, signal, and argument elements may have
4710 "annotations", which are generic key/value pairs of metadata.
4711 They are similar conceptually to Java's annotations and C# attributes.
4712 Well-known annotations:
4713 </para>
4714 <informaltable>
4715 <tgroup cols="3">
4716 <thead>
4717 <row>
4718 <entry>Name</entry>
4719 <entry>Values (separated by ,)</entry>
4720 <entry>Description</entry>
4721 </row>
4722 </thead>
4723 <tbody>
4724 <row>
4725 <entry>org.freedesktop.DBus.Deprecated</entry>
4726 <entry>true,false</entry>
4727 <entry>Whether or not the entity is deprecated; defaults to false</entry>
4728 </row>
4729 <row>
4730 <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
4731 <entry>(string)</entry>
4732 <entry>The C symbol; may be used for methods and interfaces</entry>
4733 </row>
4734 <row>
4735 <entry>org.freedesktop.DBus.Method.NoReply</entry>
4736 <entry>true,false</entry>
4737 <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
4738 </row>
4739 <row>
4740 <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
4741 <entry>true,invalidates,const,false</entry>
4742 <entry>
4743 <para>
4744 If set to <literal>false</literal>, the
4745 <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
4746 signal, see <xref
4747 linkend="standard-interfaces-properties"/> is not
4748 guaranteed to be emitted if the property changes.
4749 </para>
4750 <para>
4751 If set to <literal>const</literal> the property never
4752 changes value during the lifetime of the object it
4753 belongs to, and hence the signal is never emitted for
4754 it.
4755 </para>
4756 <para>
4757 If set to <literal>invalidates</literal> the signal
4758 is emitted but the value is not included in the
4759 signal.
4760 </para>
4761 <para>
4762 If set to <literal>true</literal> the signal is
4763 emitted with the value included.
4764 </para>
4765 <para>
4766 The value for the annotation defaults to
4767 <literal>true</literal> if the enclosing interface
4768 element does not specify the annotation. Otherwise it
4769 defaults to the value specified in the enclosing
4770 interface element.
4771 </para>
4772 <para>
4773 This annotation is intended to be used by code
4774 generators to implement client-side caching of
4775 property values. For all properties for which the
4776 annotation is set to <literal>const</literal>,
4777 <literal>invalidates</literal> or
4778 <literal>true</literal> the client may
4779 unconditionally cache the values as the properties
4780 don't change or notifications are generated for them
4781 if they do.
4782 </para>
4783 </entry>
4784 </row>
4785 </tbody>
4786 </tgroup>
4787 </informaltable>
4788 </sect1>
4789 <sect1 id="message-bus">
4790 <title>Message Bus Specification</title>
4791 <sect2 id="message-bus-overview">
4792 <title>Message Bus Overview</title>
4793 <para>
4794 The message bus accepts connections from one or more applications.
4795 Once connected, applications can exchange messages with other
4796 applications that are also connected to the bus.
4797 </para>
4798 <para>
4799 In order to route messages among connections, the message bus keeps a
4800 mapping from names to connections. Each connection has one
4801 unique-for-the-lifetime-of-the-bus name automatically assigned.
4802 Applications may request additional names for a connection. Additional
4803 names are usually "well-known names" such as
4804 "com.example.TextEditor1". When a name is bound to a connection,
4805 that connection is said to <firstterm>own</firstterm> the name.
4806 </para>
4807 <para>
4808 The bus itself owns a special name,
4809 <literal>org.freedesktop.DBus</literal>, with an object
4810 located at <literal>/org/freedesktop/DBus</literal> that
4811 implements the <literal>org.freedesktop.DBus</literal>
4812 interface. This service allows applications to make
4813 administrative requests of the bus itself. For example,
4814 applications can ask the bus to assign a name to a connection.
4815 </para>
4816 <para>
4817 Each name may have <firstterm>queued owners</firstterm>. When an
4818 application requests a name for a connection and the name is already in
4819 use, the bus will optionally add the connection to a queue waiting for
4820 the name. If the current owner of the name disconnects or releases
4821 the name, the next connection in the queue will become the new owner.
4822 </para>
4823
4824 <para>
4825 This feature causes the right thing to happen if you start two text
4826 editors for example; the first one may request "com.example.TextEditor1",
4827 and the second will be queued as a possible owner of that name. When
4828 the first exits, the second will take over.
4829 </para>
4830
4831 <para>
4832 Applications may send <firstterm>unicast messages</firstterm> to
4833 a specific recipient or to the message bus itself, or
4834 <firstterm>broadcast messages</firstterm> to all interested recipients.
4835 See <xref linkend="message-bus-routing"/> for details.
4836 </para>
4837 </sect2>
4838
4839 <sect2 id="message-bus-names">
4840 <title>Message Bus Names</title>
4841 <para>
4842 Each connection has at least one name, assigned at connection time and
4843 returned in response to the
4844 <literal>org.freedesktop.DBus.Hello</literal> method call. This
4845 automatically-assigned name is called the connection's <firstterm>unique
4846 name</firstterm>. Unique names are never reused for two different
4847 connections to the same bus.
4848 </para>
4849 <para>
4850 Ownership of a unique name is a prerequisite for interaction with
4851 the message bus. It logically follows that the unique name is always
4852 the first name that an application comes to own, and the last
4853 one that it loses ownership of.
4854 </para>
4855 <para>
4856 Unique connection names must begin with the character ':' (ASCII colon
4857 character); bus names that are not unique names must not begin
4858 with this character. (The bus must reject any attempt by an application
4859 to manually request a name beginning with ':'.) This restriction
4860 categorically prevents "spoofing"; messages sent to a unique name
4861 will always go to the expected connection.
4862 </para>
4863 <para>
4864 When a connection is closed, all the names that it owns are deleted (or
4865 transferred to the next connection in the queue if any).
4866 </para>
4867 <para>
4868 A connection can request additional names to be associated with it using
4869 the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
4870 linkend="message-protocol-names-bus"/> describes the format of a valid
4871 name. These names can be released again using the
4872 <literal>org.freedesktop.DBus.ReleaseName</literal> message.
4873 </para>
4874 </sect2>
4875
4876 <sect2 id="message-bus-routing">
4877 <title>Message Bus Message Routing</title>
4878
4879 <para>
4880 Messages may have a <literal>DESTINATION</literal> field (see <xref
4881 linkend="message-protocol-header-fields"/>), resulting in a
4882 <firstterm>unicast message</firstterm>. If the
4883 <literal>DESTINATION</literal> field is present, it specifies a message
4884 recipient by name. Method calls and replies normally specify this field.
4885 The message bus must send messages (of any type) with the
4886 <literal>DESTINATION</literal> field set to the specified recipient,
4887 regardless of whether the recipient has set up a match rule matching
4888 the message.
4889 </para>
4890
4891 <para>
4892 When the message bus receives a signal, if the
4893 <literal>DESTINATION</literal> field is absent, it is considered to
4894 be a <firstterm>broadcast signal</firstterm>, and is sent to all
4895 applications with <firstterm>message matching rules</firstterm> that
4896 match the message. Most signal messages are broadcasts, and
4897 no other message types currently defined in this specification
4898 may be broadcast.
4899 </para>
4900
4901 <para>
4902 Unicast signal messages (those with a <literal>DESTINATION</literal>
4903 field) are not commonly used, but they are treated like any unicast
4904 message: they are delivered to the specified receipient,
4905 regardless of its match rules. One use for unicast signals is to
4906 avoid a race condition in which a signal is emitted before the intended
4907 recipient can call <link linkend="bus-messages-add-match">AddMatch</link> to
4908 receive that signal: if the signal is sent directly to that recipient
4909 using a unicast message, it does not need to add a match rule at all,
4910 and there is no race condition. Another use for unicast signals,
4911 on message buses whose security policy prevents eavesdropping, is to
4912 send sensitive information which should only be visible to one
4913 recipient.
4914 </para>
4915
4916 <para>
4917 When the message bus receives a method call, if the
4918 <literal>DESTINATION</literal> field is absent, the call is taken to be
4919 a standard one-to-one message and interpreted by the message bus
4920 itself. For example, sending an
4921 <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
4922 <literal>DESTINATION</literal> will cause the message bus itself to
4923 reply to the ping immediately; the message bus will not make this
4924 message visible to other applications.
4925 </para>
4926
4927 <para>
4928 Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
4929 the ping message were sent with a <literal>DESTINATION</literal> name of
4930 <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
4931 forwarded, and the Yoyodyne Corporation screensaver application would be
4932 expected to reply to the ping.
4933 </para>
4934
4935 <para>
4936 Message bus implementations may impose a security policy which
4937 prevents certain messages from being sent or received.
4938 When a method call message cannot be sent or received due to a security
4939 policy, the message bus should send an error reply, unless the
4940 original message had the <literal>NO_REPLY</literal> flag.
4941 </para>
4942
4943 <sect3 id="message-bus-routing-eavesdropping">
4944 <title>Eavesdropping</title>
4945 <para>
4946 Receiving a unicast message whose <literal>DESTINATION</literal>
4947 indicates a different recipient is called
4948 <firstterm>eavesdropping</firstterm>. On a message bus which acts as
4949 a security boundary (like the standard system bus), the security
4950 policy should usually prevent eavesdropping, since unicast messages
4951 are normally kept private and may contain security-sensitive
4952 information.
4953 </para>
4954
4955 <para>
4956 Eavesdropping interacts poorly with buses with non-trivial
4957 access control restrictions, and is deprecated. The
4958 <literal>BecomeMonitor</literal> method (see
4959 <xref linkend="bus-messages-become-monitor"/>) provides
4960 a preferable way to monitor buses.
4961 </para>
4962
4963 <para>
4964 Eavesdropping is mainly useful for debugging tools, such as
4965 the <literal>dbus-monitor</literal> tool in the reference
4966 implementation of D-Bus. Tools which eavesdrop on the message bus
4967 should be careful to avoid sending a reply or error in response to
4968 messages intended for a different client.
4969 </para>
4970
4971 <para>
4972 Clients may attempt to eavesdrop by adding match rules
4973 (see <xref linkend="message-bus-routing-match-rules"/>) containing
4974 the <literal>eavesdrop='true'</literal> match. For
4975 compatibility with older message bus implementations, if adding such
4976 a match rule results in an error reply, the client may fall back to
4977 adding the same rule with the <literal>eavesdrop</literal> match
4978 omitted.
4979 </para>
4980 </sect3>
4981
4982 <sect3 id="message-bus-routing-match-rules">
4983 <title>Match Rules</title>
4984 <para>
4985 An important part of the message bus routing protocol is match
4986 rules. Match rules describe the messages that should be sent to a
4987 client, based on the contents of the message. Broadcast signals
4988 are only sent to clients which have a suitable match rule: this
4989 avoids waking up client processes to deal with signals that are
4990 not relevant to that client.
4991 </para>
4992 <para>
4993 Messages that list a client as their <literal>DESTINATION</literal>
4994 do not need to match the client's match rules, and are sent to that
4995 client regardless. As a result, match rules are mainly used to
4996 receive a subset of broadcast signals.
4997 </para>
4998 <para>
4999 Match rules can also be used for eavesdropping
5000 (see <xref linkend="message-bus-routing-eavesdropping"/>),
5001 if the security policy of the message bus allows it, but this
5002 usage is deprecated in favour of the <literal>BecomeMonitor</literal>
5003 method (see <xref linkend="bus-messages-become-monitor"/>).
5004 </para>
5005 <para>
5006 Match rules are added using the AddMatch bus method
5007 (see <xref linkend="bus-messages-add-match"/>). Rules are
5008 specified as a string of comma separated key/value pairs.
5009 Excluding a key from the rule indicates a wildcard match.
5010 For instance excluding the the member from a match rule but
5011 adding a sender would let all messages from that sender through.
5012 An example of a complete rule would be
5013 "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
5014 </para>
5015 <para>
5016 Within single quotes (ASCII apostrophe, U+0027), a backslash
5017 (U+005C) represents itself, and an apostrophe ends the quoted
5018 section. Outside single quotes, \' (backslash, apostrophe)
5019 represents an apostrophe, and any backslash not followed by
5020 an apostrophe represents itself. For instance, the match rules
5021 <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
5022 <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
5023 both match messages where the arguments are a 1-character string
5024 containing an apostrophe, a 1-character string containing a
5025 backslash, a 1-character string containing a comma, and a
5026 2-character string containing two backslashes<footnote>
5027 <para>
5028 This idiosyncratic quoting style is based on the rules for
5029 escaping items to appear inside single-quoted strings
5030 in POSIX <literal>/bin/sh</literal>, but please
5031 note that backslashes that are not inside single quotes have
5032 different behaviour. This syntax does not offer any way to
5033 represent an apostrophe inside single quotes (it is necessary
5034 to leave the single-quoted section, backslash-escape the
5035 apostrophe and re-enter single quotes), or to represent a
5036 comma outside single quotes (it is necessary to wrap it in
5037 a single-quoted section).
5038 </para>
5039 </footnote>.
5040 </para>
5041 <para>
5042 The following table describes the keys that can be used to create
5043 a match rule.
5044 <informaltable>
5045 <tgroup cols="3">
5046 <thead>
5047 <row>
5048 <entry>Key</entry>
5049 <entry>Possible Values</entry>
5050 <entry>Description</entry>
5051 </row>
5052 </thead>
5053 <tbody>
5054 <row>
5055 <entry><literal>type</literal></entry>
5056 <entry>'signal', 'method_call', 'method_return', 'error'</entry>
5057 <entry>Match on the message type. An example of a type match is type='signal'</entry>
5058 </row>
5059 <row>
5060 <entry><literal>sender</literal></entry>
5061 <entry>A bus or unique name (see <xref linkend="term-bus-name"/>
5062 and <xref linkend="term-unique-name"/> respectively)
5063 </entry>
5064 <entry>Match messages sent by a particular sender. An example of a sender match
5065 is sender='org.freedesktop.Hal'</entry>
5066 </row>
5067 <row>
5068 <entry><literal>interface</literal></entry>
5069 <entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
5070 <entry>Match messages sent over or to a particular interface. An example of an
5071 interface match is interface='org.freedesktop.Hal.Manager'.
5072 If a message omits the interface header, it must not match any rule
5073 that specifies this key.</entry>
5074 </row>
5075 <row>
5076 <entry><literal>member</literal></entry>
5077 <entry>Any valid method or signal name</entry>
5078 <entry>Matches messages which have the give method or signal name. An example of
5079 a member match is member='NameOwnerChanged'</entry>
5080 </row>
5081 <row>
5082 <entry><literal>path</literal></entry>
5083 <entry>An object path (see <xref linkend="message-protocol-marshaling-object-path"/>)</entry>
5084 <entry>Matches messages which are sent from or to the given object. An example of a
5085 path match is path='/org/freedesktop/Hal/Manager'</entry>
5086 </row>
5087 <row>
5088 <entry><literal>path_namespace</literal></entry>
5089 <entry>An object path</entry>
5090 <entry>
5091 <para>
5092 Matches messages which are sent from or to an
5093 object for which the object path is either the
5094 given value, or that value followed by one or
5095 more path components.
5096 </para>
5097
5098 <para>
5099 For example,
5100 <literal>path_namespace='/com/example/foo'</literal>
5101 would match signals sent by
5102 <literal>/com/example/foo</literal>
5103 or by
5104 <literal>/com/example/foo/bar</literal>,
5105 but not by
5106 <literal>/com/example/foobar</literal>.
5107 </para>
5108
5109 <para>
5110 Using both <literal>path</literal> and
5111 <literal>path_namespace</literal> in the same match
5112 rule is not allowed.
5113 </para>
5114
5115 <para>
5116 <emphasis>
5117 This match key was added in version 0.16 of the
5118 D-Bus specification and implemented by the bus
5119 daemon in dbus 1.5.0 and later.
5120 </emphasis>
5121 </para>
5122 </entry>
5123 </row>
5124 <row>
5125 <entry><literal>destination</literal></entry>
5126 <entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
5127 <entry>Matches messages which are being sent to the given unique name. An
5128 example of a destination match is destination=':1.0'</entry>
5129 </row>
5130 <row>
5131 <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
5132 <entry>Any string</entry>
5133 <entry>Arg matches are special and are used for further restricting the
5134 match based on the arguments in the body of a message. Only arguments of type
5135 STRING can be matched in this way. An example of an argument match
5136 would be arg3='Foo'. Only argument indexes from 0 to 63 should be
5137 accepted.</entry>
5138 </row>
5139 <row>
5140 <entry><literal>arg[0, 1, 2, 3, ...]path</literal></entry>
5141 <entry>Any string</entry>
5142 <entry>
5143 <para>Argument path matches provide a specialised form of wildcard matching for
5144 path-like namespaces. They can match arguments whose type is either STRING or
5145 OBJECT_PATH. As with normal argument matches,
5146 if the argument is exactly equal to the string given in the match
5147 rule then the rule is satisfied. Additionally, there is also a
5148 match when either the string given in the match rule or the
5149 appropriate message argument ends with '/' and is a prefix of the
5150 other. An example argument path match is arg0path='/aa/bb/'. This
5151 would match messages with first arguments of '/', '/aa/',
5152 '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match
5153 messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</para>
5154
5155 <para>This is intended for monitoring “directories” in file system-like
5156 hierarchies, as used in the <citetitle>dconf</citetitle> configuration
5157 system. An application interested in all nodes in a particular hierarchy would
5158 monitor <literal>arg0path='/ca/example/foo/'</literal>. Then the service could
5159 emit a signal with zeroth argument <literal>"/ca/example/foo/bar"</literal> to
5160 represent a modification to the “bar” property, or a signal with zeroth
5161 argument <literal>"/ca/example/"</literal> to represent atomic modification of
5162 many properties within that directory, and the interested application would be
5163 notified in both cases.</para>
5164 <para>
5165 <emphasis>
5166 This match key was added in version 0.12 of the
5167 D-Bus specification, implemented for STRING
5168 arguments by the bus daemon in dbus 1.2.0 and later,
5169 and implemented for OBJECT_PATH arguments in dbus 1.5.0
5170 and later.
5171 </emphasis>
5172 </para>
5173 </entry>
5174 </row>
5175 <row>
5176 <entry><literal>arg0namespace</literal></entry>
5177 <entry>Like a bus name, except that the string is not
5178 required to contain a '.' (period)</entry>
5179 <entry>
5180 <para>Match messages whose first argument is of type STRING, and is a bus name
5181 or interface name within the specified namespace. This is primarily intended
5182 for watching name owner changes for a group of related bus names, rather than
5183 for a single name or all name changes.</para>
5184
5185 <para>Because every valid interface name is also a valid
5186 bus name, this can also be used for messages whose
5187 first argument is an interface name.</para>
5188
5189 <para>For example, the match rule
5190 <literal>member='NameOwnerChanged',arg0namespace='com.example.backend1'</literal>
5191 matches name owner changes for bus names such as
5192 <literal>com.example.backend1.foo</literal>,
5193 <literal>com.example.backend1.foo.bar</literal>, and
5194 <literal>com.example.backend1</literal> itself.</para>
5195
5196 <para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
5197 <para>
5198 <emphasis>
5199 This match key was added in version 0.16 of the
5200 D-Bus specification and implemented by the bus
5201 daemon in dbus 1.5.0 and later.
5202 </emphasis>
5203 </para>
5204 </entry>
5205 </row>
5206 <row>
5207 <entry><literal>eavesdrop</literal></entry>
5208 <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
5209 <entry>
5210 <para>
5211 Since D-Bus 1.5.6, match rules do not
5212 match messages which have a <literal>DESTINATION</literal>
5213 field unless the match rule specifically
5214 requests this
5215 (see <xref linkend="message-bus-routing-eavesdropping"/>)
5216 by specifying <literal>eavesdrop='true'</literal>
5217 in the match rule. <literal>eavesdrop='false'</literal>
5218 restores the default behaviour. Messages are
5219 delivered to their <literal>DESTINATION</literal>
5220 regardless of match rules, so this match does not
5221 affect normal delivery of unicast messages.
5222 In older versions of D-Bus, this match was not allowed
5223 in match rules, and all match rules behaved as if
5224 <literal>eavesdrop='true'</literal> had been used.
5225 </para>
5226 <para>
5227 Use of <literal>eavesdrop='true'</literal> is
5228 deprecated. Monitors should prefer to use the
5229 <literal>BecomeMonitor</literal> method (see
5230 <xref linkend="bus-messages-become-monitor"/>),
5231 which was introduced in version 0.26 of the D-Bus
5232 specification and version 1.9.10 of the reference
5233 dbus-daemon.
5234 </para>
5235 <para>
5236 Message bus implementations may restrict match rules
5237 with <literal>eavesdrop='true'</literal> so that they
5238 can only be added by privileged connections.
5239 </para>
5240 <para>
5241 <emphasis>
5242 This match key was added in version 0.18 of the
5243 D-Bus specification and implemented by the bus
5244 daemon in dbus 1.5.6 and later.
5245 </emphasis>
5246 </para>
5247 </entry>
5248 </row>
5249 </tbody>
5250 </tgroup>
5251 </informaltable>
5252 </para>
5253 </sect3>
5254 </sect2>
5255 <sect2 id="message-bus-starting-services">
5256 <title>Message Bus Starting Services (Activation)</title>
5257 <para>
5258 The message bus can start applications on behalf of other applications.
5259 This is referred to as <firstterm>service activation</firstterm> or
5260 <firstterm>activation</firstterm>.
5261 An application that can be started in this way is called a
5262 <firstterm>service</firstterm> or an
5263 <firstterm>activatable service</firstterm>.
5264 </para>
5265
5266 <para>
5267 <firstterm>Starting a service</firstterm> should be read as synonymous
5268 with service activation.
5269 </para>
5270
5271 <para>
5272 In D-Bus, service activation is normally done by
5273 <firstterm>auto-starting</firstterm>.
5274 In auto-starting, applications send a
5275 message to a particular well-known name, such as
5276 <literal>com.example.TextEditor1</literal>, without specifying the
5277 <literal>NO_AUTO_START</literal> flag in the message header.
5278 If no application on the bus owns the requested name, but the bus
5279 daemon does know how to start an activatable service for that name,
5280 then the bus daemon will start that service, wait for it to request
5281 that name, and deliver the message to it.
5282 </para>
5283
5284 <para>
5285 It is also possible for applications to send an explicit request to
5286 start a service: this is another form of activation, distinct from
5287 auto-starting. See
5288 <xref linkend="bus-messages-start-service-by-name"/> for details.
5289 </para>
5290
5291 <para>
5292 In either case, this implies a contract documented along with the name
5293 <literal>com.example.TextEditor1</literal> for which object
5294 the owner of that name will provide, and what interfaces those
5295 objects will have.
5296 </para>
5297
5298 <para>
5299 To find an executable corresponding to a particular name, the bus daemon
5300 looks for <firstterm>service description files</firstterm>. Service
5301 description files define a mapping from names to executables. Different
5302 kinds of message bus will look for these files in different places, see
5303 <xref linkend="message-bus-types"/>.
5304 </para>
5305 <para>
5306 Service description files have the ".service" file
5307 extension. The message bus will only load service description files
5308 ending with .service; all other files will be ignored. The file format
5309 is similar to that of <ulink
5310 url="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">desktop
5311 entries</ulink>. All service description files must be in UTF-8
5312 encoding. To ensure that there will be no name collisions, service files
5313 must be namespaced using the same mechanism as messages and service
5314 names.
5315 </para>
5316
5317 <para>
5318 On the well-known system bus, the name of a service description file
5319 must be its well-known name plus <literal>.service</literal>,
5320 for instance
5321 <literal>com.example.ConfigurationDatabase1.service</literal>.
5322 </para>
5323
5324 <para>
5325 On the well-known session bus, services should follow the same
5326 service description file naming convention as on the system bus,
5327 but for backwards compatibility they are not required to do so.
5328 </para>
5329
5330 <para>
5331 [FIXME the file format should be much better specified than "similar to
5332 .desktop entries" esp. since desktop entries are already
5333 badly-specified. ;-)]
5334 These sections from the specification apply to service files as well:
5335
5336 <itemizedlist>
5337 <listitem><para>General syntax</para></listitem>
5338 <listitem><para>Comment format</para></listitem>
5339 </itemizedlist>
5340
5341 Service description files must contain a
5342 <literal>D-BUS Service</literal> group with at least the keys
5343 <literal>Name</literal> (the well-known name of the service)
5344 and <literal>Exec</literal> (the command to be executed).
5345
5346 <figure>
5347 <title>Example service description file</title>
5348 <programlisting>
5349 # Sample service description file
5350 [D-BUS Service]
5351 Name=com.example.ConfigurationDatabase1
5352 Exec=/usr/bin/sample-configd
5353 </programlisting>
5354 </figure>
5355 </para>
5356
5357 <para>
5358 Additionally, service description files for the well-known system
5359 bus on Unix must contain a <literal>User</literal> key, whose value
5360 is the name of a user account (e.g. <literal>root</literal>).
5361 The system service will be run as that user.
5362 </para>
5363
5364 <para>
5365 When an application asks to start a service by name, the bus daemon tries to
5366 find a service that will own that name. It then tries to spawn the
5367 executable associated with it. If this fails, it will report an
5368 error.
5369 </para>
5370
5371 <para>
5372 On the well-known system bus, it is not possible for two .service files
5373 in the same directory to offer the same service, because they are
5374 constrained to have names that match the service name.
5375 </para>
5376
5377 <para>
5378 On the well-known session bus, if two .service files in the same
5379 directory offer the same service name, the result is undefined.
5380 Distributors should avoid this situation, for instance by naming
5381 session services' .service files according to their service name.
5382 </para>
5383
5384 <para>
5385 If two .service files in different directories offer the same
5386 service name, the one in the higher-priority directory is used:
5387 for instance, on the system bus, .service files in
5388 /etc/dbus-1/system-services takes precedence over those in
5389 /run/dbus-1/system-services, which in turn take precedence over
5390 those in /usr/local/share/dbus-1/system-services, which in turn take
5391 precedence over those in /usr/share/dbus-1/system-services.
5392 </para>
5393 <para>
5394 The executable launched will have the environment variable
5395 <literal>DBUS_STARTER_ADDRESS</literal> set to the address of the
5396 message bus so it can connect and request the appropriate names.
5397 </para>
5398 <para>
5399 The executable being launched may want to know whether the message bus
5400 starting it is one of the well-known message buses (see <xref
5401 linkend="message-bus-types"/>). To facilitate this, the bus must also set
5402 the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
5403 of the well-known buses. The currently-defined values for this variable
5404 are <literal>system</literal> for the systemwide message bus,
5405 and <literal>session</literal> for the per-login-session message
5406 bus. The new executable must still connect to the address given
5407 in <literal>DBUS_STARTER_ADDRESS</literal>, but may assume that the
5408 resulting connection is to the well-known bus.
5409 </para>
5410 <para>
5411 [FIXME there should be a timeout somewhere, either specified
5412 in the .service file, by the client, or just a global value
5413 and if the client being activated fails to connect within that
5414 timeout, an error should be sent back.]
5415 </para>
5416
5417 <sect3 id="message-bus-starting-services-scope">
5418 <title>Message Bus Service Scope</title>
5419 <para>
5420 The "scope" of a service is its "per-", such as per-session,
5421 per-machine, per-home-directory, or per-display. The reference
5422 implementation doesn't yet support starting services in a different
5423 scope from the message bus itself. So e.g. if you start a service
5424 on the session bus its scope is per-session.
5425 </para>
5426 <para>
5427 We could add an optional scope to a bus name. For example, for
5428 per-(display,session pair), we could have a unique ID for each display
5429 generated automatically at login and set on screen 0 by executing a
5430 special "set display ID" binary. The ID would be stored in a
5431 <literal>_DBUS_DISPLAY_ID</literal> property and would be a string of
5432 random bytes. This ID would then be used to scope names.
5433 Starting/locating a service could be done by ID-name pair rather than
5434 only by name.
5435 </para>
5436 <para>
5437 Contrast this with a per-display scope. To achieve that, we would
5438 want a single bus spanning all sessions using a given display.
5439 So we might set a <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
5440 property on screen 0 of the display, pointing to this bus.
5441 </para>
5442 </sect3>
5443
5444 <sect3 id="message-bus-starting-services-systemd">
5445 <title>systemd Activation</title>
5446
5447 <para>
5448 Service description files may contain a
5449 <literal>SystemdService</literal> key. Its value is the name of a
5450 <ulink
5451 url="https://www.freedesktop.org/wiki/Software/systemd/">systemd</ulink>
5452 service, for example
5453 <literal>dbus-com.example.MyDaemon.service</literal>.
5454 </para>
5455
5456 <para>
5457 If this key is present, the bus daemon may carry out activation for
5458 this D-Bus service by sending a request to systemd asking it to
5459 start the systemd service whose name is the value of
5460 <literal>SystemdService</literal>. For example, the reference
5461 <literal>dbus-daemon</literal> has a
5462 <literal>--systemd-activation</literal> option that enables this
5463 feature, and that option is given when it is started by systemd.
5464 </para>
5465
5466 <para>
5467 On the well-known system bus, it is a common practice to set
5468 <literal>SystemdService</literal> to <literal>dbus-</literal>,
5469 followed by the well-known bus name, followed by
5470 <literal>.service</literal>, then register that name as an alias
5471 for the real systemd service. This allows D-Bus activation of a
5472 service to be enabled or disabled independently of whether the
5473 service is started by systemd during boot.
5474 </para>
5475 </sect3>
5476
5477 <sect3 id="message-bus-starting-services-apparmor">
5478 <title>Mediating Activation with AppArmor</title>
5479
5480 <para>
5481 Please refer to
5482 <ulink url="http://wiki.apparmor.net/index.php/Documentation">AppArmor documentation</ulink>
5483 for general information on AppArmor, and how it mediates D-Bus
5484 messages when used in conjunction with a kernel and
5485 <literal>dbus-daemon</literal> that support this.
5486 </para>
5487
5488 <para>
5489 In recent versions of the reference <literal>dbus-daemon</literal>,
5490 AppArmor policy rules of type <literal>dbus send</literal>
5491 are also used to control auto-starting: if a message is sent to
5492 the well-known name of an activatable service, the
5493 <literal>dbus-daemon</literal> will attempt to determine whether
5494 it would deliver the message to that service
5495 <emphasis>before</emphasis>auto-starting it, by making some
5496 assumptions about the resulting process's credentials.
5497 </para>
5498
5499 <para>
5500 If it does proceed with auto-starting, when the service appears, the
5501 <literal>dbus-daemon</literal> repeats the policy check (with
5502 the service's true credentials, which might not be identical)
5503 before delivering the message. In practice, this second check will
5504 usually be more strict than the first; the first check would only
5505 be more strict if there are "blacklist"-style rules like
5506 <literal>deny dbus send peer=(label=/usr/bin/protected)</literal>
5507 that match on the peer's specific credentials, but AppArmor is
5508 normally used in a "whitelist" style where this does not apply.
5509 </para>
5510
5511 <para>
5512 To support this process, service description files may contain a
5513 <literal>AssumedAppArmorLabel</literal> key. Its value is the name
5514 of an AppArmor label, for example
5515 <literal>/usr/sbin/mydaemon</literal>.
5516 If present, AppArmor mediation of messages that auto-start a
5517 service will decide whether to allow auto-starting to occur based
5518 on the assumption that the activated service will be confined
5519 under the specified label; in particular, rules of the form
5520 <literal>dbus send peer=(label=/usr/sbin/mydaemon)</literal> or
5521 <literal>deny dbus send peer=(label=/usr/sbin/mydaemon)</literal>
5522 will match it, allowing or denying as appropriate
5523 (even if there is in fact no profile of that name loaded).
5524 </para>
5525
5526 <para>
5527 Otherwise, AppArmor mediation of messages that auto-start a
5528 service will decide whether to allow auto-starting to occur
5529 without specifying any particular label. In particular, any rule of
5530 the form <literal>dbus send peer=(label=X)</literal> or
5531 <literal>deny dbus send peer=(label=X)</literal>
5532 (for any value of X, including the special label
5533 <literal>unconfined</literal>) will not influence whether the
5534 auto-start is allowed.
5535 </para>
5536
5537 <para>
5538 Rules of type <literal>dbus receive</literal> are not checked
5539 when deciding whether to allow auto-starting; they are only checked
5540 against the service's profile after the service has started, when
5541 deciding whether to deliver the message that caused the auto-starting
5542 operation.
5543 </para>
5544
5545 <para>
5546 Explicit activation via the
5547 <link linkend="bus-messages-start-service-by-name">StartServiceByName</link>
5548 method call is not currently
5549 affected by this mediation: if a confined process is to be prevented
5550 from starting arbitrary services, then it must not be allowed to call
5551 that method.
5552 </para>
5553 </sect3>
5554 </sect2>
5555
5556 <sect2 id="message-bus-types">
5557 <title>Well-known Message Bus Instances</title>
5558 <para>
5559 Two standard message bus instances are defined here, along with how
5560 to locate them and where their service files live.
5561 </para>
5562 <sect3 id="message-bus-types-login">
5563 <title>Login session message bus</title>
5564 <para>
5565 Each time a user logs in, a <firstterm>login session message
5566 bus</firstterm> may be started. All applications in the user's login
5567 session may interact with one another using this message bus.
5568 </para>
5569 <para>
5570 The address of the login session message bus is given
5571 in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
5572 variable. If that variable is not set, applications may
5573 also try to read the address from the X Window System root
5574 window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
5575 The root window property must have type <literal>STRING</literal>.
5576 The environment variable should have precedence over the
5577 root window property.
5578 </para>
5579 <para>The address of the login session message bus is given in the
5580 <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment variable. If
5581 DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string
5582 "autolaunch:", the system should use platform-specific methods of
5583 locating a running D-Bus session server, or starting one if a running
5584 instance cannot be found. Note that this mechanism is not recommended
5585 for attempting to determine if a daemon is running. It is inherently
5586 racy to attempt to make this determination, since the bus daemon may
5587 be started just before or just after the determination is made.
5588 Therefore, it is recommended that applications do not try to make this
5589 determination for their functionality purposes, and instead they
5590 should attempt to start the server.</para>
5591
5592 <sect4 id="message-bus-types-login-x-windows">
5593 <title>X Windowing System</title>
5594 <para>
5595 For the X Windowing System, the application must locate the
5596 window owner of the selection represented by the atom formed by
5597 concatenating:
5598 <itemizedlist>
5599 <listitem>
5600 <para>the literal string "_DBUS_SESSION_BUS_SELECTION_"</para>
5601 </listitem>
5602
5603 <listitem>
5604 <para>the current user's username</para>
5605 </listitem>
5606
5607 <listitem>
5608 <para>the literal character '_' (underscore)</para>
5609 </listitem>
5610
5611 <listitem>
5612 <para>the machine's ID</para>
5613 </listitem>
5614 </itemizedlist>
5615 </para>
5616
5617 <para>
5618 The following properties are defined for the window that owns
5619 this X selection:
5620 <informaltable frame="all">
5621 <tgroup cols="2">
5622 <tbody>
5623 <row>
5624 <entry>
5625 <para>Atom</para>
5626 </entry>
5627
5628 <entry>
5629 <para>meaning</para>
5630 </entry>
5631 </row>
5632
5633 <row>
5634 <entry>
5635 <para>_DBUS_SESSION_BUS_ADDRESS</para>
5636 </entry>
5637
5638 <entry>
5639 <para>the actual address of the server socket</para>
5640 </entry>
5641 </row>
5642
5643 <row>
5644 <entry>
5645 <para>_DBUS_SESSION_BUS_PID</para>
5646 </entry>
5647
5648 <entry>
5649 <para>the PID of the server process</para>
5650 </entry>
5651 </row>
5652 </tbody>
5653 </tgroup>
5654 </informaltable>
5655 </para>
5656
5657 <para>
5658 At least the _DBUS_SESSION_BUS_ADDRESS property MUST be
5659 present in this window.
5660 </para>
5661
5662 <para>
5663 If the X selection cannot be located or if reading the
5664 properties from the window fails, the implementation MUST conclude
5665 that there is no D-Bus server running and proceed to start a new
5666 server. (See below on concurrency issues)
5667 </para>
5668
5669 <para>
5670 Failure to connect to the D-Bus server address thus obtained
5671 MUST be treated as a fatal connection error and should be reported
5672 to the application.
5673 </para>
5674
5675 <para>
5676 As an alternative, an implementation MAY find the information
5677 in the following file located in the current user's home directory,
5678 in subdirectory .dbus/session-bus/:
5679 <itemizedlist>
5680 <listitem>
5681 <para>the machine's ID</para>
5682 </listitem>
5683
5684 <listitem>
5685 <para>the literal character '-' (dash)</para>
5686 </listitem>
5687
5688 <listitem>
5689 <para>the X display without the screen number, with the
5690 following prefixes removed, if present: ":", "localhost:"
5691 ."localhost.localdomain:". That is, a display of
5692 "localhost:10.0" produces just the number "10"</para>
5693 </listitem>
5694 </itemizedlist>
5695 </para>
5696
5697 <para>
5698 The contents of this file NAME=value assignment pairs and
5699 lines starting with # are comments (no comments are allowed
5700 otherwise). The following variable names are defined:
5701 <informaltable
5702 frame="all">
5703 <tgroup cols="2">
5704 <tbody>
5705 <row>
5706 <entry>
5707 <para>Variable</para>
5708 </entry>
5709
5710 <entry>
5711 <para>meaning</para>
5712 </entry>
5713 </row>
5714
5715 <row>
5716 <entry>
5717 <para>DBUS_SESSION_BUS_ADDRESS</para>
5718 </entry>
5719
5720 <entry>
5721 <para>the actual address of the server socket</para>
5722 </entry>
5723 </row>
5724
5725 <row>
5726 <entry>
5727 <para>DBUS_SESSION_BUS_PID</para>
5728 </entry>
5729
5730 <entry>
5731 <para>the PID of the server process</para>
5732 </entry>
5733 </row>
5734
5735 <row>
5736 <entry>
5737 <para>DBUS_SESSION_BUS_WINDOWID</para>
5738 </entry>
5739
5740 <entry>
5741 <para>the window ID</para>
5742 </entry>
5743 </row>
5744 </tbody>
5745 </tgroup>
5746 </informaltable>
5747 </para>
5748
5749 <para>
5750 At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present
5751 in this file.
5752 </para>
5753
5754 <para>
5755 Failure to open this file MUST be interpreted as absence of a
5756 running server. Therefore, the implementation MUST proceed to
5757 attempting to launch a new bus server if the file cannot be
5758 opened.
5759 </para>
5760
5761 <para>
5762 However, success in opening this file MUST NOT lead to the
5763 conclusion that the server is running. Thus, a failure to connect to
5764 the bus address obtained by the alternative method MUST NOT be
5765 considered a fatal error. If the connection cannot be established,
5766 the implementation MUST proceed to check the X selection settings or
5767 to start the server on its own.
5768 </para>
5769
5770 <para>
5771 If the implementation concludes that the D-Bus server is not
5772 running it MUST attempt to start a new server and it MUST also
5773 ensure that the daemon started as an effect of the "autolaunch"
5774 mechanism provides the lookup mechanisms described above, so
5775 subsequent calls can locate the newly started server. The
5776 implementation MUST also ensure that if two or more concurrent
5777 initiations happen, only one server remains running and all other
5778 initiations are able to obtain the address of this server and
5779 connect to it. In other words, the implementation MUST ensure that
5780 the X selection is not present when it attempts to set it, without
5781 allowing another process to set the selection between the
5782 verification and the setting (e.g., by using XGrabServer /
5783 XungrabServer).
5784 </para>
5785 </sect4>
5786 <sect4>
5787 <title>Finding session services</title>
5788 <para>
5789 On Unix systems, the session bus should search for .service files
5790 in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
5791 by the
5792 <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
5793 Implementations may also search additional locations,
5794 with a higher or lower priority than the XDG directories.
5795 </para>
5796 <para>
5797 As described in the XDG Base Directory Specification, software
5798 packages should install their session .service files to their
5799 configured <literal>${datadir}/dbus-1/services</literal>,
5800 where <literal>${datadir}</literal> is as defined by the GNU
5801 coding standards. System administrators or users can arrange
5802 for these service files to be read by setting XDG_DATA_DIRS or by
5803 symlinking them into the default locations.
5804 </para>
5805 </sect4>
5806 </sect3>
5807 <sect3 id="message-bus-types-system">
5808 <title>System message bus</title>
5809 <para>
5810 A computer may have a <firstterm>system message bus</firstterm>,
5811 accessible to all applications on the system. This message bus may be
5812 used to broadcast system events, such as adding new hardware devices,
5813 changes in the printer queue, and so forth.
5814 </para>
5815 <para>
5816 The address of the system message bus is given
5817 in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
5818 variable. If that variable is not set, applications should try
5819 to connect to the well-known address
5820 <literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
5821 Implementations of the well-known system bus should listen on
5822 an address that will result in that connection being successful.
5823 </para>
5824 <para>
5825 On systems where <filename>/var/run/</filename> is known to be
5826 synonymous with <filename>/run/</filename> (such as most Linux
5827 operating system distributions), implementations might prefer
5828 to make use of that knowledge to connect to or listen on
5829 <literal>unix:path=/run/dbus/system_bus_socket</literal> instead,
5830 which has some minor technical advantages, particularly during
5831 early startup and late shutdown.
5832 </para>
5833 <para>
5834 In practice, implementations of D-Bus often have build-time
5835 configuration options for the system bus address, whose defaults
5836 often depend on other build-time options such as the installation
5837 prefix (in particular, this is the case for dbus, the reference
5838 implementation of D-Bus).
5839 Distributors intending to provide access to the well-known
5840 system bus should verify that they are using an interoperable
5841 address.
5842 </para>
5843 <para>
5844 On Unix systems, the system bus should default to searching
5845 for .service files in
5846 <literal>/etc/dbus-1/system-services</literal>,
5847 <literal>/run/dbus-1/system-services</literal>,
5848 <literal>/usr/local/share/dbus-1/system-services</literal>,
5849 <literal>/usr/share/dbus-1/system-services</literal> and
5850 <literal>/lib/dbus-1/system-services</literal>, with that order
5851 of precedence. It may also search other implementation-specific
5852 locations, but should not vary these locations based on environment
5853 variables.
5854 The directory in <literal>/etc/</literal> is reserved for use by
5855 either the local system administrator,
5856 or an asset manager deploying services that are not part of the OS.
5857 The directory in <literal>/run/</literal> is reserved for ephemeral
5858 services that will disappear after a reboot.
5859 <footnote>
5860 <para>
5861 The system bus is security-sensitive and is typically executed
5862 by an init system with a clean environment. Its launch helper
5863 process is particularly security-sensitive, and specifically
5864 clears its own environment.
5865 </para>
5866 </footnote>
5867 </para>
5868 <para>
5869 Software packages should install their system .service
5870 files to their configured
5871 <literal>${datadir}/dbus-1/system-services</literal>,
5872 where <literal>${datadir}</literal> is as defined by the GNU
5873 coding standards. System administrators can arrange
5874 for these service files to be read by editing the system bus'
5875 configuration file or by symlinking them into the default
5876 locations.
5877 </para>
5878 </sect3>
5879 </sect2>
5880
5881 <sect2 id="message-bus-messages">
5882 <title>Message Bus Interface: <literal>org.freedesktop.DBus</literal></title>
5883 <para>
5884 The special message bus name <literal>org.freedesktop.DBus</literal>
5885 responds to a number of additional messages at the object path
5886 <literal>/org/freedesktop/DBus</literal>,
5887 implementing the <literal>org.freedesktop.DBus</literal> interface.
5888 That object path is also used when emitting signals such as
5889 <link linkend='bus-messages-name-owner-changed'>NameOwnerChanged</link>.
5890 </para>
5891
5892 <para>
5893 For historical reasons, some of the methods in the
5894 <literal>org.freedesktop.DBus</literal> interface are available
5895 on multiple object paths. Message bus implementations should
5896 accept method calls that were added before specification version
5897 0.26 on any object path. Message bus implementations should
5898 not accept newer method calls on unexpected object paths,
5899 and as a security hardening measure, older method calls
5900 that are security-sensitive may be rejected with the error
5901 <literal>org.freedesktop.DBus.Error.AccessDenied</literal> when
5902 called on an unexpected object path. Client software should send
5903 all method calls to <literal>/org/freedesktop/DBus</literal>
5904 instead of relying on this.
5905 </para>
5906
5907 <sect3 id="bus-messages-hello">
5908 <title>Method: <literal>org.freedesktop.DBus.Hello</literal></title>
5909 <para>
5910 As a method:
5911 <programlisting>
5912 STRING Hello ()
5913 </programlisting>
5914 Reply arguments:
5915 <informaltable>
5916 <tgroup cols="3">
5917 <thead>
5918 <row>
5919 <entry>Argument</entry>
5920 <entry>Type</entry>
5921 <entry>Description</entry>
5922 </row>
5923 </thead>
5924 <tbody>
5925 <row>
5926 <entry>0</entry>
5927 <entry>STRING</entry>
5928 <entry>Unique name assigned to the connection</entry>
5929 </row>
5930 </tbody>
5931 </tgroup>
5932 </informaltable>
5933 </para>
5934 <para>
5935 Before an application is able to send messages to other applications
5936 it must send the <literal>org.freedesktop.DBus.Hello</literal> message
5937 to the message bus to obtain a unique name. If an application without
5938 a unique name tries to send a message to another application, or a
5939 message to the message bus itself that isn't the
5940 <literal>org.freedesktop.DBus.Hello</literal> message, it will be
5941 disconnected from the bus.
5942 </para>
5943 <para>
5944 There is no corresponding "disconnect" request; if a client wishes to
5945 disconnect from the bus, it simply closes the socket (or other
5946 communication channel).
5947 </para>
5948 </sect3>
5949
5950 <sect3 id="bus-messages-request-name">
5951 <title>Method: <literal>org.freedesktop.DBus.RequestName</literal></title>
5952 <para>
5953 As a method:
5954 <programlisting>
5955 UINT32 RequestName (in STRING name, in UINT32 flags)
5956 </programlisting>
5957 Message arguments:
5958 <informaltable>
5959 <tgroup cols="3">
5960 <thead>
5961 <row>
5962 <entry>Argument</entry>
5963 <entry>Type</entry>
5964 <entry>Description</entry>
5965 </row>
5966 </thead>
5967 <tbody>
5968 <row>
5969 <entry>0</entry>
5970 <entry>STRING</entry>
5971 <entry>Name to request</entry>
5972 </row>
5973 <row>
5974 <entry>1</entry>
5975 <entry>UINT32</entry>
5976 <entry>Flags</entry>
5977 </row>
5978 </tbody>
5979 </tgroup>
5980 </informaltable>
5981 Reply arguments:
5982 <informaltable>
5983 <tgroup cols="3">
5984 <thead>
5985 <row>
5986 <entry>Argument</entry>
5987 <entry>Type</entry>
5988 <entry>Description</entry>
5989 </row>
5990 </thead>
5991 <tbody>
5992 <row>
5993 <entry>0</entry>
5994 <entry>UINT32</entry>
5995 <entry>Return value</entry>
5996 </row>
5997 </tbody>
5998 </tgroup>
5999 </informaltable>
6000 </para>
6001 <para>
6002 Ask the message bus to assign the given name to the method caller. Each
6003 name maintains a queue of possible owners, where the head of the queue is
6004 the primary or current owner of the name. Each potential owner in the
6005 queue maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
6006 DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName call.
6007 When RequestName is invoked the following occurs:
6008 <itemizedlist>
6009 <listitem>
6010 <para>
6011 If the method caller is currently the primary owner of the name,
6012 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
6013 values are updated with the values from the new RequestName call,
6014 and nothing further happens.
6015 </para>
6016 </listitem>
6017
6018 <listitem>
6019 <para>
6020 If the current primary owner (head of the queue) has
6021 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
6022 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
6023 the caller of RequestName replaces the current primary owner at
6024 the head of the queue and the current primary owner moves to the
6025 second position in the queue. If the caller of RequestName was
6026 in the queue previously its flags are updated with the values from
6027 the new RequestName in addition to moving it to the head of the queue.
6028 </para>
6029 </listitem>
6030
6031 <listitem>
6032 <para>
6033 If replacement is not possible, and the method caller is
6034 currently in the queue but not the primary owner, its flags are
6035 updated with the values from the new RequestName call.
6036 </para>
6037 </listitem>
6038
6039 <listitem>
6040 <para>
6041 If replacement is not possible, and the method caller is
6042 currently not in the queue, the method caller is appended to the
6043 queue.
6044 </para>
6045 </listitem>
6046
6047 <listitem>
6048 <para>
6049 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
6050 set and is not the primary owner, it is removed from the
6051 queue. This can apply to the previous primary owner (if it
6052 was replaced) or the method caller (if it updated the
6053 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
6054 queue, or if it was just added to the queue with that flag set).
6055 </para>
6056 </listitem>
6057 </itemizedlist>
6058 </para>
6059 <para>
6060 Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
6061 queue," even if another application already in the queue had specified
6062 DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner
6063 that does not allow replacement goes away, and the next primary owner
6064 does allow replacement. In this case, queued items that specified
6065 DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
6066 automatically replace the new primary owner. In other words,
6067 DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
6068 time RequestName is called. This is deliberate to avoid an infinite loop
6069 anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
6070 and DBUS_NAME_FLAG_REPLACE_EXISTING.
6071 </para>
6072 <para>
6073 The flags argument contains any of the following values logically ORed
6074 together:
6075
6076 <informaltable>
6077 <tgroup cols="3">
6078 <thead>
6079 <row>
6080 <entry>Conventional Name</entry>
6081 <entry>Value</entry>
6082 <entry>Description</entry>
6083 </row>
6084 </thead>
6085 <tbody>
6086 <row>
6087 <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
6088 <entry>0x1</entry>
6089 <entry>
6090
6091 If an application A specifies this flag and succeeds in
6092 becoming the owner of the name, and another application B
6093 later calls RequestName with the
6094 DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
6095 will lose ownership and receive a
6096 <literal>org.freedesktop.DBus.NameLost</literal> signal, and
6097 application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
6098 is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
6099 is not specified by application B, then application B will not replace
6100 application A as the owner.
6101
6102 </entry>
6103 </row>
6104 <row>
6105 <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
6106 <entry>0x2</entry>
6107 <entry>
6108
6109 Try to replace the current owner if there is one. If this
6110 flag is not set the application will only become the owner of
6111 the name if there is no current owner. If this flag is set,
6112 the application will replace the current owner if
6113 the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
6114
6115 </entry>
6116 </row>
6117 <row>
6118 <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
6119 <entry>0x4</entry>
6120 <entry>
6121
6122 Without this flag, if an application requests a name that is
6123 already owned, the application will be placed in a queue to
6124 own the name when the current owner gives it up. If this
6125 flag is given, the application will not be placed in the
6126 queue, the request for the name will simply fail. This flag
6127 also affects behavior when an application is replaced as
6128 name owner; by default the application moves back into the
6129 waiting queue, unless this flag was provided when the application
6130 became the name owner.
6131
6132 </entry>
6133 </row>
6134 </tbody>
6135 </tgroup>
6136 </informaltable>
6137
6138 The return code can be one of the following values:
6139
6140 <informaltable>
6141 <tgroup cols="3">
6142 <thead>
6143 <row>
6144 <entry>Conventional Name</entry>
6145 <entry>Value</entry>
6146 <entry>Description</entry>
6147 </row>
6148 </thead>
6149 <tbody>
6150 <row>
6151 <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
6152 <entry>1</entry> <entry>The caller is now the primary owner of
6153 the name, replacing any previous owner. Either the name had no
6154 owner before, or the caller specified
6155 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
6156 DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
6157 </row>
6158 <row>
6159 <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
6160 <entry>2</entry>
6161
6162 <entry>The name already had an owner,
6163 DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
6164 the current owner did not specify
6165 DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
6166 application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
6167 </entry>
6168 </row>
6169 <row>
6170 <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
6171 <entry>The name already has an owner,
6172 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
6173 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
6174 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
6175 specified by the requesting application.</entry>
6176 </row>
6177 <row>
6178 <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
6179 <entry>4</entry>
6180 <entry>The application trying to request ownership of a name is already the owner of it.</entry>
6181 </row>
6182 </tbody>
6183 </tgroup>
6184 </informaltable>
6185 </para>
6186 </sect3>
6187
6188 <sect3 id="bus-messages-release-name">
6189 <title>Method: <literal>org.freedesktop.DBus.ReleaseName</literal></title>
6190 <para>
6191 As a method:
6192 <programlisting>
6193 UINT32 ReleaseName (in STRING name)
6194 </programlisting>
6195 Message arguments:
6196 <informaltable>
6197 <tgroup cols="3">
6198 <thead>
6199 <row>
6200 <entry>Argument</entry>
6201 <entry>Type</entry>
6202 <entry>Description</entry>
6203 </row>
6204 </thead>
6205 <tbody>
6206 <row>
6207 <entry>0</entry>
6208 <entry>STRING</entry>
6209 <entry>Name to release</entry>
6210 </row>
6211 </tbody>
6212 </tgroup>
6213 </informaltable>
6214 Reply arguments:
6215 <informaltable>
6216 <tgroup cols="3">
6217 <thead>
6218 <row>
6219 <entry>Argument</entry>
6220 <entry>Type</entry>
6221 <entry>Description</entry>
6222 </row>
6223 </thead>
6224 <tbody>
6225 <row>
6226 <entry>0</entry>
6227 <entry>UINT32</entry>
6228 <entry>Return value</entry>
6229 </row>
6230 </tbody>
6231 </tgroup>
6232 </informaltable>
6233 </para>
6234 <para>
6235 Ask the message bus to release the method caller's claim to the given
6236 name. If the caller is the primary owner, a new primary owner will be
6237 selected from the queue if any other owners are waiting. If the
6238 caller is waiting in the queue for the name, the caller will removed
6239 from the queue and will not be made an owner of the name if it later
6240 becomes available. If there are no other owners in the queue for the
6241 name, it will be removed from the bus entirely.
6242
6243 The return code can be one of the following values:
6244
6245 <informaltable>
6246 <tgroup cols="3">
6247 <thead>
6248 <row>
6249 <entry>Conventional Name</entry>
6250 <entry>Value</entry>
6251 <entry>Description</entry>
6252 </row>
6253 </thead>
6254 <tbody>
6255 <row>
6256 <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
6257 <entry>1</entry> <entry>The caller has released his claim on
6258 the given name. Either the caller was the primary owner of
6259 the name, and the name is now unused or taken by somebody
6260 waiting in the queue for the name, or the caller was waiting
6261 in the queue for the name and has now been removed from the
6262 queue.</entry>
6263 </row>
6264 <row>
6265 <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
6266 <entry>2</entry>
6267 <entry>The given name does not exist on this bus.</entry>
6268 </row>
6269 <row>
6270 <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
6271 <entry>3</entry>
6272 <entry>The caller was not the primary owner of this name,
6273 and was also not waiting in the queue to own this name.</entry>
6274 </row>
6275 </tbody>
6276 </tgroup>
6277 </informaltable>
6278 </para>
6279 </sect3>
6280
6281 <sect3 id="bus-messages-list-queued-owners">
6282 <title>Method: <literal>org.freedesktop.DBus.ListQueuedOwners</literal></title>
6283 <para>
6284 As a method:
6285 <programlisting>
6286 ARRAY of STRING ListQueuedOwners (in STRING name)
6287 </programlisting>
6288 Message arguments:
6289 <informaltable>
6290 <tgroup cols="3">
6291 <thead>
6292 <row>
6293 <entry>Argument</entry>
6294 <entry>Type</entry>
6295 <entry>Description</entry>
6296 </row>
6297 </thead>
6298 <tbody>
6299 <row>
6300 <entry>0</entry>
6301 <entry>STRING</entry>
6302 <entry>The well-known bus name to query, such as
6303 <literal>com.example.cappuccino</literal></entry>
6304 </row>
6305 </tbody>
6306 </tgroup>
6307 </informaltable>
6308 Reply arguments:
6309 <informaltable>
6310 <tgroup cols="3">
6311 <thead>
6312 <row>
6313 <entry>Argument</entry>
6314 <entry>Type</entry>
6315 <entry>Description</entry>
6316 </row>
6317 </thead>
6318 <tbody>
6319 <row>
6320 <entry>0</entry>
6321 <entry>ARRAY of STRING</entry>
6322 <entry>The unique bus names of connections currently queued
6323 for the name</entry>
6324 </row>
6325 </tbody>
6326 </tgroup>
6327 </informaltable>
6328 </para>
6329 <para>
6330 List the connections currently queued for a bus name (see
6331 <xref linkend="term-queued-owner"/>).
6332 </para>
6333 </sect3>
6334
6335 <sect3 id="bus-messages-list-names">
6336 <title>Method: <literal>org.freedesktop.DBus.ListNames</literal></title>
6337 <para>
6338 As a method:
6339 <programlisting>
6340 ARRAY of STRING ListNames ()
6341 </programlisting>
6342 Reply arguments:
6343 <informaltable>
6344 <tgroup cols="3">
6345 <thead>
6346 <row>
6347 <entry>Argument</entry>
6348 <entry>Type</entry>
6349 <entry>Description</entry>
6350 </row>
6351 </thead>
6352 <tbody>
6353 <row>
6354 <entry>0</entry>
6355 <entry>ARRAY of STRING</entry>
6356 <entry>Array of strings where each string is a bus name</entry>
6357 </row>
6358 </tbody>
6359 </tgroup>
6360 </informaltable>
6361 </para>
6362 <para>
6363 Returns a list of all currently-owned names on the bus.
6364 </para>
6365 </sect3>
6366 <sect3 id="bus-messages-list-activatable-names">
6367 <title>Method: <literal>org.freedesktop.DBus.ListActivatableNames</literal></title>
6368 <para>
6369 As a method:
6370 <programlisting>
6371 ARRAY of STRING ListActivatableNames ()
6372 </programlisting>
6373 Reply arguments:
6374 <informaltable>
6375 <tgroup cols="3">
6376 <thead>
6377 <row>
6378 <entry>Argument</entry>
6379 <entry>Type</entry>
6380 <entry>Description</entry>
6381 </row>
6382 </thead>
6383 <tbody>
6384 <row>
6385 <entry>0</entry>
6386 <entry>ARRAY of STRING</entry>
6387 <entry>Array of strings where each string is a bus name</entry>
6388 </row>
6389 </tbody>
6390 </tgroup>
6391 </informaltable>
6392 </para>
6393 <para>
6394 Returns a list of all names that can be activated on the bus.
6395 </para>
6396 </sect3>
6397 <sect3 id="bus-messages-name-exists">
6398 <title>Method: <literal>org.freedesktop.DBus.NameHasOwner</literal></title>
6399 <para>
6400 As a method:
6401 <programlisting>
6402 BOOLEAN NameHasOwner (in STRING name)
6403 </programlisting>
6404 Message arguments:
6405 <informaltable>
6406 <tgroup cols="3">
6407 <thead>
6408 <row>
6409 <entry>Argument</entry>
6410 <entry>Type</entry>
6411 <entry>Description</entry>
6412 </row>
6413 </thead>
6414 <tbody>
6415 <row>
6416 <entry>0</entry>
6417 <entry>STRING</entry>
6418 <entry>Name to check</entry>
6419 </row>
6420 </tbody>
6421 </tgroup>
6422 </informaltable>
6423 Reply arguments:
6424 <informaltable>
6425 <tgroup cols="3">
6426 <thead>
6427 <row>
6428 <entry>Argument</entry>
6429 <entry>Type</entry>
6430 <entry>Description</entry>
6431 </row>
6432 </thead>
6433 <tbody>
6434 <row>
6435 <entry>0</entry>
6436 <entry>BOOLEAN</entry>
6437 <entry>Return value, true if the name exists</entry>
6438 </row>
6439 </tbody>
6440 </tgroup>
6441 </informaltable>
6442 </para>
6443 <para>
6444 Checks if the specified name exists (currently has an owner).
6445 </para>
6446 </sect3>
6447
6448 <sect3 id="bus-messages-name-owner-changed">
6449 <title>Signal: <literal>org.freedesktop.DBus.NameOwnerChanged</literal></title>
6450 <para>
6451 This is a signal:
6452 <programlisting>
6453 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
6454 </programlisting>
6455 Message arguments:
6456 <informaltable>
6457 <tgroup cols="3">
6458 <thead>
6459 <row>
6460 <entry>Argument</entry>
6461 <entry>Type</entry>
6462 <entry>Description</entry>
6463 </row>
6464 </thead>
6465 <tbody>
6466 <row>
6467 <entry>0</entry>
6468 <entry>STRING</entry>
6469 <entry>Name with a new owner</entry>
6470 </row>
6471 <row>
6472 <entry>1</entry>
6473 <entry>STRING</entry>
6474 <entry>Old owner or empty string if none</entry>
6475 </row>
6476 <row>
6477 <entry>2</entry>
6478 <entry>STRING</entry>
6479 <entry>New owner or empty string if none</entry>
6480 </row>
6481 </tbody>
6482 </tgroup>
6483 </informaltable>
6484 </para>
6485 <para>
6486 This signal indicates that the owner of a name has changed.
6487 It's also the signal to use to detect the appearance of
6488 new names on the bus.
6489 </para>
6490 </sect3>
6491 <sect3 id="bus-messages-name-lost">
6492 <title>Signal: <literal>org.freedesktop.DBus.NameLost</literal></title>
6493 <para>
6494 This is a signal:
6495 <programlisting>
6496 NameLost (STRING name)
6497 </programlisting>
6498 Message arguments:
6499 <informaltable>
6500 <tgroup cols="3">
6501 <thead>
6502 <row>
6503 <entry>Argument</entry>
6504 <entry>Type</entry>
6505 <entry>Description</entry>
6506 </row>
6507 </thead>
6508 <tbody>
6509 <row>
6510 <entry>0</entry>
6511 <entry>STRING</entry>
6512 <entry>Name which was lost</entry>
6513 </row>
6514 </tbody>
6515 </tgroup>
6516 </informaltable>
6517 </para>
6518 <para>
6519 This signal is sent to a specific application when it loses
6520 ownership of a name.
6521 </para>
6522 </sect3>
6523
6524 <sect3 id="bus-messages-name-acquired">
6525 <title>Signal: <literal>org.freedesktop.DBus.NameAcquired</literal></title>
6526 <para>
6527 This is a signal:
6528 <programlisting>
6529 NameAcquired (STRING name)
6530 </programlisting>
6531 Message arguments:
6532 <informaltable>
6533 <tgroup cols="3">
6534 <thead>
6535 <row>
6536 <entry>Argument</entry>
6537 <entry>Type</entry>
6538 <entry>Description</entry>
6539 </row>
6540 </thead>
6541 <tbody>
6542 <row>
6543 <entry>0</entry>
6544 <entry>STRING</entry>
6545 <entry>Name which was acquired</entry>
6546 </row>
6547 </tbody>
6548 </tgroup>
6549 </informaltable>
6550 </para>
6551 <para>
6552 This signal is sent to a specific application when it gains
6553 ownership of a name.
6554 </para>
6555 </sect3>
6556
6557 <sect3 id="bus-messages-activatable-services-changed">
6558 <title>Signal: <literal>org.freedesktop.DBus.ActivatableServicesChanged</literal></title>
6559 <para>
6560 This is a signal:
6561 <programlisting>
6562 ActivatableServicesChanged ()
6563 </programlisting>
6564 </para>
6565 <para>
6566 This signal is sent when the list of activatable services,
6567 as returned by ListActivatableNames(), might have changed
6568 (see <xref linkend="bus-messages-list-activatable-names"/>).
6569 Clients that have cached information about the activatable
6570 services should call ListActivatableNames() again to update
6571 their cache.
6572 </para>
6573 <para>
6574 The presence of this signal is indicated by a
6575 bus feature property (for details see
6576 <xref linkend="message-bus-properties-features"/>).
6577 In older implementations that do not have this feature,
6578 there is no way to be informed when the list of activatable
6579 names has changed.
6580 </para>
6581 </sect3>
6582
6583 <sect3 id="bus-messages-start-service-by-name">
6584 <title>Method: <literal>org.freedesktop.DBus.StartServiceByName</literal></title>
6585 <para>
6586 As a method:
6587 <programlisting>
6588 UINT32 StartServiceByName (in STRING name, in UINT32 flags)
6589 </programlisting>
6590 Message arguments:
6591 <informaltable>
6592 <tgroup cols="3">
6593 <thead>
6594 <row>
6595 <entry>Argument</entry>
6596 <entry>Type</entry>
6597 <entry>Description</entry>
6598 </row>
6599 </thead>
6600 <tbody>
6601 <row>
6602 <entry>0</entry>
6603 <entry>STRING</entry>
6604 <entry>Name of the service to start</entry>
6605 </row>
6606 <row>
6607 <entry>1</entry>
6608 <entry>UINT32</entry>
6609 <entry>Flags (currently not used)</entry>
6610 </row>
6611 </tbody>
6612 </tgroup>
6613 </informaltable>
6614 Reply arguments:
6615 <informaltable>
6616 <tgroup cols="3">
6617 <thead>
6618 <row>
6619 <entry>Argument</entry>
6620 <entry>Type</entry>
6621 <entry>Description</entry>
6622 </row>
6623 </thead>
6624 <tbody>
6625 <row>
6626 <entry>0</entry>
6627 <entry>UINT32</entry>
6628 <entry>Return value</entry>
6629 </row>
6630 </tbody>
6631 </tgroup>
6632 </informaltable>
6633 Tries to launch the executable associated with a name (service
6634 activation), as an explicit request. This is an alternative to
6635 relying on auto-starting. For more information on how services
6636 are activated and the difference between auto-starting and explicit
6637 activation, see
6638 <xref linkend="message-bus-starting-services"/>.
6639 </para>
6640 <para>
6641 It is often preferable to carry out auto-starting
6642 instead of calling this method. This is because calling this method
6643 is subject to a
6644 <ulink url="https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use">time-of-check/time-of-use</ulink>
6645 issue: if a caller asks the message bus to start a service so that
6646 the same caller can make follow-up method calls to that service,
6647 the fact that the message bus was able to start the required
6648 service is no guarantee that it will not have crashed or otherwise
6649 exited by the time the caller makes those follow-up method calls.
6650 As a result, calling this method does not remove the need for
6651 the caller to handle errors from method calls. Given that fact,
6652 it is usually simpler to rely on auto-starting, in which the
6653 required service starts as a side-effect of the first method call.
6654 </para>
6655 <para>
6656 The return value can be one of the following values:
6657 <informaltable>
6658 <tgroup cols="3">
6659 <thead>
6660 <row>
6661 <entry>Identifier</entry>
6662 <entry>Value</entry>
6663 <entry>Description</entry>
6664 </row>
6665 </thead>
6666 <tbody>
6667 <row>
6668 <entry>DBUS_START_REPLY_SUCCESS</entry>
6669 <entry>1</entry>
6670 <entry>The service was successfully started.</entry>
6671 </row>
6672 <row>
6673 <entry>DBUS_START_REPLY_ALREADY_RUNNING</entry>
6674 <entry>2</entry>
6675 <entry>A connection already owns the given name.</entry>
6676 </row>
6677 </tbody>
6678 </tgroup>
6679 </informaltable>
6680 </para>
6681
6682 </sect3>
6683
6684 <sect3 id="bus-messages-update-activation-environment">
6685 <title>Method: <literal>org.freedesktop.DBus.UpdateActivationEnvironment</literal></title>
6686 <para>
6687 As a method:
6688 <programlisting>
6689 UpdateActivationEnvironment (in ARRAY of DICT_ENTRY&lt;STRING,STRING&gt; environment)
6690 </programlisting>
6691 Message arguments:
6692 <informaltable>
6693 <tgroup cols="3">
6694 <thead>
6695 <row>
6696 <entry>Argument</entry>
6697 <entry>Type</entry>
6698 <entry>Description</entry>
6699 </row>
6700 </thead>
6701 <tbody>
6702 <row>
6703 <entry>0</entry>
6704 <entry>ARRAY of DICT_ENTRY&lt;STRING,STRING&gt;</entry>
6705 <entry>Environment to add or update</entry>
6706 </row>
6707 </tbody>
6708 </tgroup>
6709 </informaltable>
6710 Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services.
6711 </para>
6712 <para>
6713 Some bus instances, such as the standard system bus, may disable access to this method for some or all callers.
6714 </para>
6715 <para>
6716 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.
6717 </para>
6718
6719 </sect3>
6720
6721 <sect3 id="bus-messages-get-name-owner">
6722 <title>Method: <literal>org.freedesktop.DBus.GetNameOwner</literal></title>
6723 <para>
6724 As a method:
6725 <programlisting>
6726 STRING GetNameOwner (in STRING name)
6727 </programlisting>
6728 Message arguments:
6729 <informaltable>
6730 <tgroup cols="3">
6731 <thead>
6732 <row>
6733 <entry>Argument</entry>
6734 <entry>Type</entry>
6735 <entry>Description</entry>
6736 </row>
6737 </thead>
6738 <tbody>
6739 <row>
6740 <entry>0</entry>
6741 <entry>STRING</entry>
6742 <entry>Name to get the owner of</entry>
6743 </row>
6744 </tbody>
6745 </tgroup>
6746 </informaltable>
6747 Reply arguments:
6748 <informaltable>
6749 <tgroup cols="3">
6750 <thead>
6751 <row>
6752 <entry>Argument</entry>
6753 <entry>Type</entry>
6754 <entry>Description</entry>
6755 </row>
6756 </thead>
6757 <tbody>
6758 <row>
6759 <entry>0</entry>
6760 <entry>STRING</entry>
6761 <entry>Return value, a unique connection name</entry>
6762 </row>
6763 </tbody>
6764 </tgroup>
6765 </informaltable>
6766 Returns the unique connection name of the primary owner of the name
6767 given. If the requested name doesn't have an owner, returns a
6768 <literal>org.freedesktop.DBus.Error.NameHasNoOwner</literal> error.
6769 </para>
6770 </sect3>
6771
6772 <sect3 id="bus-messages-get-connection-unix-user">
6773 <title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixUser</literal></title>
6774 <para>
6775 As a method:
6776 <programlisting>
6777 UINT32 GetConnectionUnixUser (in STRING bus_name)
6778 </programlisting>
6779 Message arguments:
6780 <informaltable>
6781 <tgroup cols="3">
6782 <thead>
6783 <row>
6784 <entry>Argument</entry>
6785 <entry>Type</entry>
6786 <entry>Description</entry>
6787 </row>
6788 </thead>
6789 <tbody>
6790 <row>
6791 <entry>0</entry>
6792 <entry>STRING</entry>
6793 <entry>Unique or well-known bus name of the connection to
6794 query, such as <literal>:12.34</literal> or
6795 <literal>com.example.tea</literal></entry>
6796 </row>
6797 </tbody>
6798 </tgroup>
6799 </informaltable>
6800 Reply arguments:
6801 <informaltable>
6802 <tgroup cols="3">
6803 <thead>
6804 <row>
6805 <entry>Argument</entry>
6806 <entry>Type</entry>
6807 <entry>Description</entry>
6808 </row>
6809 </thead>
6810 <tbody>
6811 <row>
6812 <entry>0</entry>
6813 <entry>UINT32</entry>
6814 <entry>Unix user ID</entry>
6815 </row>
6816 </tbody>
6817 </tgroup>
6818 </informaltable>
6819 Returns the Unix user ID of the process connected to the server. If
6820 unable to determine it (for instance, because the process is not on the
6821 same machine as the bus daemon), an error is returned.
6822 </para>
6823 </sect3>
6824
6825 <sect3 id="bus-messages-get-connection-unix-process-id">
6826 <title>Method: <literal>org.freedesktop.DBus.GetConnectionUnixProcessID</literal></title>
6827 <para>
6828 As a method:
6829 <programlisting>
6830 UINT32 GetConnectionUnixProcessID (in STRING bus_name)
6831 </programlisting>
6832 Message arguments:
6833 <informaltable>
6834 <tgroup cols="3">
6835 <thead>
6836 <row>
6837 <entry>Argument</entry>
6838 <entry>Type</entry>
6839 <entry>Description</entry>
6840 </row>
6841 </thead>
6842 <tbody>
6843 <row>
6844 <entry>0</entry>
6845 <entry>STRING</entry>
6846 <entry>Unique or well-known bus name of the connection to
6847 query, such as <literal>:12.34</literal> or
6848 <literal>com.example.tea</literal></entry>
6849 </row>
6850 </tbody>
6851 </tgroup>
6852 </informaltable>
6853 Reply arguments:
6854 <informaltable>
6855 <tgroup cols="3">
6856 <thead>
6857 <row>
6858 <entry>Argument</entry>
6859 <entry>Type</entry>
6860 <entry>Description</entry>
6861 </row>
6862 </thead>
6863 <tbody>
6864 <row>
6865 <entry>0</entry>
6866 <entry>UINT32</entry>
6867 <entry>Unix process id</entry>
6868 </row>
6869 </tbody>
6870 </tgroup>
6871 </informaltable>
6872 Returns the Unix process ID of the process connected to the server. If
6873 unable to determine it (for instance, because the process is not on the
6874 same machine as the bus daemon), an error is returned.
6875 </para>
6876 </sect3>
6877
6878 <sect3 id="bus-messages-get-connection-credentials">
6879 <title>Method: <literal>org.freedesktop.DBus.GetConnectionCredentials</literal></title>
6880 <para>
6881 As a method:
6882 <programlisting>
6883 ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; GetConnectionCredentials (in STRING bus_name)
6884 </programlisting>
6885 Message arguments:
6886 <informaltable>
6887 <tgroup cols="3">
6888 <thead>
6889 <row>
6890 <entry>Argument</entry>
6891 <entry>Type</entry>
6892 <entry>Description</entry>
6893 </row>
6894 </thead>
6895 <tbody>
6896 <row>
6897 <entry>0</entry>
6898 <entry>STRING</entry>
6899 <entry>Unique or well-known bus name of the connection to
6900 query, such as <literal>:12.34</literal> or
6901 <literal>com.example.tea</literal></entry>
6902 </row>
6903 </tbody>
6904 </tgroup>
6905 </informaltable>
6906 Reply arguments:
6907 <informaltable>
6908 <tgroup cols="3">
6909 <thead>
6910 <row>
6911 <entry>Argument</entry>
6912 <entry>Type</entry>
6913 <entry>Description</entry>
6914 </row>
6915 </thead>
6916 <tbody>
6917 <row>
6918 <entry>0</entry>
6919 <entry>ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;</entry>
6920 <entry>Credentials</entry>
6921 </row>
6922 </tbody>
6923 </tgroup>
6924 </informaltable>
6925 </para>
6926
6927 <para>
6928 Returns as many credentials as possible for the process connected to
6929 the server. If unable to determine certain credentials (for instance,
6930 because the process is not on the same machine as the bus daemon,
6931 or because this version of the bus daemon does not support a
6932 particular security framework), or if the values of those credentials
6933 cannot be represented as documented here, then those credentials
6934 are omitted.
6935 </para>
6936
6937 <para>
6938 Keys in the returned dictionary not containing "." are defined
6939 by this specification. Bus daemon implementors supporting
6940 credentials frameworks not mentioned in this document should either
6941 contribute patches to this specification, or use keys containing
6942 "." and starting with a reversed domain name.
6943 <informaltable>
6944 <tgroup cols="3">
6945 <thead>
6946 <row>
6947 <entry>Key</entry>
6948 <entry>Value type</entry>
6949 <entry>Value</entry>
6950 </row>
6951 </thead>
6952 <tbody>
6953 <row>
6954 <entry>UnixUserID</entry>
6955 <entry>UINT32</entry>
6956 <entry>The numeric Unix user ID, as defined by POSIX</entry>
6957 </row>
6958 <row>
6959 <entry>UnixGroupIDs</entry>
6960 <entry>ARRAY of UINT32</entry>
6961 <entry>The numeric Unix group IDs (including both the primary
6962 group and the supplementary groups), as defined by POSIX, in
6963 numerically sorted order. This array is either complete or
6964 absent: if the message bus is able to determine some but not
6965 all of the caller's groups, or if one of the groups is not
6966 representable in a UINT32, it must not add this credential
6967 to the dictionary.
6968 </entry>
6969 </row>
6970 <row>
6971 <entry>ProcessFD</entry>
6972 <entry>UNIX_FD</entry>
6973 <entry>A file descriptor pinning the process, on platforms
6974 that have this concept. On Linux, the SO_PEERPIDFD socket
6975 option is a suitable implementation. This is safer to use
6976 to identify a process than the <literal>ProcessID</literal>,
6977 as the latter is subject to re-use attacks, while the FD
6978 cannot be recycled. If the original process no longer exists
6979 the FD will no longer be resolvable.</entry>
6980 </row>
6981 <row>
6982 <entry>ProcessID</entry>
6983 <entry>UINT32</entry>
6984 <entry>The numeric process ID, on platforms that have
6985 this concept. On Unix, this is the process ID defined by
6986 POSIX.</entry>
6987 </row>
6988 <row>
6989 <entry>WindowsSID</entry>
6990 <entry>STRING</entry>
6991 <entry>The Windows security identifier in its string form,
6992 e.g. "S-1-5-21-3623811015-3361044348-30300820-1013" for
6993 a domain or local computer user or "S-1-5-18" for the
6994 LOCAL_SYSTEM user</entry>
6995 </row>
6996
6997 <row>
6998 <entry>LinuxSecurityLabel</entry>
6999 <entry>ARRAY of BYTE</entry>
7000 <entry>
7001 <para>On Linux systems, the security label that would result
7002 from the SO_PEERSEC getsockopt call. The array contains
7003 the non-zero bytes of the security label in an unspecified
7004 ASCII-compatible encoding<footnote>
7005 <para>It could be ASCII or UTF-8, but could also be
7006 ISO Latin-1 or any other encoding.</para>
7007 </footnote>, followed by a single zero byte.</para>
7008 <para>
7009 For example, the SELinux context
7010 <literal>system_u:system_r:init_t:s0</literal>
7011 (a string of length 27) would be encoded as 28 bytes
7012 ending with ':', 's', '0', '\x00'.<footnote>
7013 <para>Note that this is not the same as the older
7014 GetConnectionSELinuxContext method, which does
7015 not append the zero byte. Always appending the
7016 zero byte allows callers to read the string
7017 from the message payload without copying.</para>
7018 </footnote>
7019 </para>
7020 <para>
7021 On SELinux systems this is the SELinux context, as output
7022 by <literal>ps -Z</literal> or <literal>ls -Z</literal>.
7023 Typical values might include
7024 <literal>system_u:system_r:init_t:s0</literal>,
7025 <literal>unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023</literal>,
7026 or
7027 <literal>unconfined_u:unconfined_r:chrome_sandbox_t:s0-s0:c0.c1023</literal>.
7028 </para>
7029 <para>
7030 On Smack systems, this is the Smack label.
7031 Typical values might include
7032 <literal>_</literal>, <literal>*</literal>,
7033 <literal>User</literal>, <literal>System</literal>
7034 or <literal>System::Shared</literal>.
7035 </para>
7036 <para>
7037 On AppArmor systems, this is the AppArmor context,
7038 a composite string encoding the AppArmor label (one or more
7039 profiles) and the enforcement mode.
7040 Typical values might include <literal>unconfined</literal>,
7041 <literal>/usr/bin/firefox (enforce)</literal> or
7042 <literal>user1 (complain)</literal>.
7043 </para>
7044 </entry>
7045 </row>
7046
7047 </tbody>
7048 </tgroup>
7049 </informaltable>
7050 </para>
7051
7052 <para>
7053 This method was added in D-Bus 1.7 to reduce the round-trips
7054 required to list a process's credentials. In older versions, calling
7055 this method will fail: applications wishing to support obsolete
7056 message bus versions can recover by using the separate methods such as
7057 <link linkend="bus-messages-get-connection-unix-user">GetConnectionUnixUser</link>
7058 instead.
7059 </para>
7060 </sect3>
7061
7062 <sect3 id="bus-messages-get-adt-audit-session-data">
7063 <title>Method: <literal>org.freedesktop.DBus.GetAdtAuditSessionData</literal></title>
7064 <para>
7065 As a method:
7066 <programlisting>
7067 ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name)
7068 </programlisting>
7069 Message arguments:
7070 <informaltable>
7071 <tgroup cols="3">
7072 <thead>
7073 <row>
7074 <entry>Argument</entry>
7075 <entry>Type</entry>
7076 <entry>Description</entry>
7077 </row>
7078 </thead>
7079 <tbody>
7080 <row>
7081 <entry>0</entry>
7082 <entry>STRING</entry>
7083 <entry>Unique or well-known bus name of the connection to
7084 query, such as <literal>:12.34</literal> or
7085 <literal>com.example.tea</literal></entry>
7086 </row>
7087 </tbody>
7088 </tgroup>
7089 </informaltable>
7090 Reply arguments:
7091 <informaltable>
7092 <tgroup cols="3">
7093 <thead>
7094 <row>
7095 <entry>Argument</entry>
7096 <entry>Type</entry>
7097 <entry>Description</entry>
7098 </row>
7099 </thead>
7100 <tbody>
7101 <row>
7102 <entry>0</entry>
7103 <entry>ARRAY of BYTE</entry>
7104 <entry>auditing data as returned by
7105 adt_export_session_data()</entry>
7106 </row>
7107 </tbody>
7108 </tgroup>
7109 </informaltable>
7110 Returns auditing data used by Solaris ADT, in an unspecified
7111 binary format. If you know what this means, please contribute
7112 documentation via the D-Bus bug tracking system.
7113 This method is on the core DBus interface for historical reasons;
7114 the same information should be made available via the
7115 <link linkend="bus-messages-get-connection-credentials">GetConnectionCredentials</link>
7116 method in future.
7117 </para>
7118 </sect3>
7119
7120 <sect3 id="bus-messages-get-connection-selinux-security-context">
7121 <title>Method: <literal>org.freedesktop.DBus.GetConnectionSELinuxSecurityContext</literal></title>
7122 <para>
7123 As a method:
7124 <programlisting>
7125 ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name)
7126 </programlisting>
7127 Message arguments:
7128 <informaltable>
7129 <tgroup cols="3">
7130 <thead>
7131 <row>
7132 <entry>Argument</entry>
7133 <entry>Type</entry>
7134 <entry>Description</entry>
7135 </row>
7136 </thead>
7137 <tbody>
7138 <row>
7139 <entry>0</entry>
7140 <entry>STRING</entry>
7141 <entry>Unique or well-known bus name of the connection to
7142 query, such as <literal>:12.34</literal> or
7143 <literal>com.example.tea</literal></entry>
7144 </row>
7145 </tbody>
7146 </tgroup>
7147 </informaltable>
7148 Reply arguments:
7149 <informaltable>
7150 <tgroup cols="3">
7151 <thead>
7152 <row>
7153 <entry>Argument</entry>
7154 <entry>Type</entry>
7155 <entry>Description</entry>
7156 </row>
7157 </thead>
7158 <tbody>
7159 <row>
7160 <entry>0</entry>
7161 <entry>ARRAY of BYTE</entry>
7162 <entry>some sort of string of bytes, not necessarily UTF-8,
7163 not including '\0'</entry>
7164 </row>
7165 </tbody>
7166 </tgroup>
7167 </informaltable>
7168 Returns the security context used by SELinux, in an unspecified
7169 format. If you know what this means, please contribute
7170 documentation via the D-Bus bug tracking system.
7171 This method is on the core DBus interface for historical reasons;
7172 the same information should be made available via the
7173 <link linkend="bus-messages-get-connection-credentials">GetConnectionCredentials</link>
7174 method in future.
7175 </para>
7176 </sect3>
7177
7178
7179 <sect3 id="bus-messages-add-match">
7180 <title>Method: <literal>org.freedesktop.DBus.AddMatch</literal></title>
7181 <para>
7182 As a method:
7183 <programlisting>
7184 AddMatch (in STRING rule)
7185 </programlisting>
7186 Message arguments:
7187 <informaltable>
7188 <tgroup cols="3">
7189 <thead>
7190 <row>
7191 <entry>Argument</entry>
7192 <entry>Type</entry>
7193 <entry>Description</entry>
7194 </row>
7195 </thead>
7196 <tbody>
7197 <row>
7198 <entry>0</entry>
7199 <entry>STRING</entry>
7200 <entry>Match rule to add to the connection</entry>
7201 </row>
7202 </tbody>
7203 </tgroup>
7204 </informaltable>
7205 Adds a match rule to match messages going through the message bus (see <xref linkend='message-bus-routing-match-rules'/>).
7206 If the bus does not have enough resources the <literal>org.freedesktop.DBus.Error.OOM</literal>
7207 error is returned.
7208 </para>
7209 </sect3>
7210 <sect3 id="bus-messages-remove-match">
7211 <title>Method: <literal>org.freedesktop.DBus.RemoveMatch</literal></title>
7212 <para>
7213 As a method:
7214 <programlisting>
7215 RemoveMatch (in STRING rule)
7216 </programlisting>
7217 Message arguments:
7218 <informaltable>
7219 <tgroup cols="3">
7220 <thead>
7221 <row>
7222 <entry>Argument</entry>
7223 <entry>Type</entry>
7224 <entry>Description</entry>
7225 </row>
7226 </thead>
7227 <tbody>
7228 <row>
7229 <entry>0</entry>
7230 <entry>STRING</entry>
7231 <entry>Match rule to remove from the connection</entry>
7232 </row>
7233 </tbody>
7234 </tgroup>
7235 </informaltable>
7236 Removes the first rule that matches (see <xref linkend='message-bus-routing-match-rules'/>).
7237 If the rule is not found the <literal>org.freedesktop.DBus.Error.MatchRuleNotFound</literal>
7238 error is returned.
7239 </para>
7240 </sect3>
7241
7242 <sect3 id="bus-messages-get-id">
7243 <title>Method: <literal>org.freedesktop.DBus.GetId</literal></title>
7244 <para>
7245 As a method:
7246 <programlisting>
7247 GetId (out STRING id)
7248 </programlisting>
7249 Reply arguments:
7250 <informaltable>
7251 <tgroup cols="3">
7252 <thead>
7253 <row>
7254 <entry>Argument</entry>
7255 <entry>Type</entry>
7256 <entry>Description</entry>
7257 </row>
7258 </thead>
7259 <tbody>
7260 <row>
7261 <entry>0</entry>
7262 <entry>STRING</entry>
7263 <entry>Unique ID identifying the bus daemon</entry>
7264 </row>
7265 </tbody>
7266 </tgroup>
7267 </informaltable>
7268 Gets the unique ID of the bus. The unique ID here is shared among all addresses the
7269 bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in
7270 <xref linkend="uuids"/>. Each address the bus is listening on also has its own unique
7271 ID, as described in <xref linkend="addresses"/>. The per-bus and per-address IDs are not related.
7272 There is also a per-machine ID, described in <xref linkend="standard-interfaces-peer"/> and returned
7273 by org.freedesktop.DBus.Peer.GetMachineId().
7274 For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session.
7275 </para>
7276 </sect3>
7277
7278 <sect3 id="message-bus-properties-features">
7279 <title>Property: <literal>org.freedesktop.DBus.Features</literal></title>
7280 <para>
7281 As a property:
7282 <programlisting>
7283 Read-only constant ARRAY of STRING Features
7284 </programlisting>
7285 This property lists abstract “features” provided by the message
7286 bus, and can be used by clients to detect the capabilities
7287 of the message bus with which they are communicating.
7288 This property was added in version 1.11.x of the reference
7289 implementation of the message bus.
7290 Like all properties, it is accessed via method calls to the standard
7291 <link linkend="standard-interfaces-properties">Properties</link>
7292 interface.
7293 </para>
7294
7295 <para>
7296 Items in the returned array not containing “.” are defined
7297 by this specification. Bus daemon implementors wishing to advertise
7298 features not mentioned in this document should either contribute
7299 patches to this specification, or use keys containing “.” and
7300 starting with their own reversed domain name, for example
7301 <literal>com.example.MyBus.SubliminalMessages</literal>.
7302 </para>
7303
7304 <para>
7305 The features currently defined in this specification are as follows:
7306 <variablelist>
7307
7308 <varlistentry>
7309 <term><literal>ActivatableServicesChanged</literal></term>
7310 <listitem>
7311 <para>
7312 This message bus emits the <literal>ActivatableServicesChanged</literal>
7313 signal whenever its list of activatable services might have changed
7314 (for details see <xref linkend="bus-messages-activatable-services-changed"/>).
7315 </para>
7316 </listitem>
7317 </varlistentry>
7318
7319 <varlistentry>
7320 <term><literal>AppArmor</literal></term>
7321 <listitem>
7322 <para>
7323 This message bus filters messages via the
7324 <ulink url="http://wiki.apparmor.net/">AppArmor</ulink>
7325 security framework. This feature should only be
7326 advertised if AppArmor mediation is enabled and
7327 active at runtime; merely compiling in support
7328 for AppArmor should not result in this feature being
7329 advertised on message bus instances where it is disabled by
7330 message bus or operating system configuration.
7331 </para>
7332 </listitem>
7333 </varlistentry>
7334
7335 <varlistentry>
7336 <term><literal>HeaderFiltering</literal></term>
7337 <listitem>
7338 <para>
7339 This message bus guarantees that it will remove
7340 header fields that it does not understand when it
7341 relays messages, so that a client receiving a
7342 recently-defined header field that is specified to be
7343 controlled by the message bus can safely assume that
7344 it was in fact set by the message bus. This check is
7345 needed because older message bus implementations did
7346 not guarantee to filter headers in this way, so a
7347 malicious client could send any recently-defined
7348 header field with a crafted value of its choice
7349 through an older message bus that did not understand
7350 that header field.
7351 </para>
7352 </listitem>
7353 </varlistentry>
7354
7355 <varlistentry>
7356 <term><literal>SELinux</literal></term>
7357 <listitem>
7358 <para>
7359 This message bus filters messages via the
7360 <ulink url="https://selinuxproject.org/">SELinux</ulink>
7361 security framework. Similar to <literal>AppArmor</literal>,
7362 this feature should only be advertised if SELinux mediation
7363 is enabled and active at runtime (if SELinux is placed in
7364 permissive mode, that is still considered to be active).
7365 </para>
7366 </listitem>
7367 </varlistentry>
7368
7369 <varlistentry>
7370 <term><literal>SystemdActivation</literal></term>
7371 <listitem>
7372 <para>
7373 When asked to activate a service that has the
7374 <literal>SystemdService</literal> field in its
7375 <filename>.service</filename> file, this message bus will
7376 carry out systemd activation (for details see
7377 <xref linkend="message-bus-starting-services-systemd"/>).
7378 </para>
7379 </listitem>
7380 </varlistentry>
7381
7382 </variablelist>
7383 </para>
7384 </sect3>
7385
7386 <sect3 id="message-bus-properties-interfaces">
7387 <title>Property: <literal>org.freedesktop.DBus.Interfaces</literal></title>
7388 <para>
7389 As a property:
7390 <programlisting>
7391 Read-only constant ARRAY of STRING Interfaces
7392 </programlisting>
7393 This property lists interfaces provided by the
7394 <literal>/org/freedesktop/DBus</literal> object,
7395 and can be used by clients to detect the capabilities
7396 of the message bus with which they are communicating.
7397 Unlike the standard Introspectable interface, querying this
7398 property does not require parsing XML.
7399 This property was added in version 1.11.x of the reference
7400 implementation of the message bus.
7401 Like all properties, it is accessed via method calls to the standard
7402 <link linkend="standard-interfaces-properties">Properties</link>
7403 interface.
7404 </para>
7405
7406 <para>
7407 The standard <literal>org.freedesktop.DBus</literal> and
7408 <literal>org.freedesktop.DBus.Properties</literal> interfaces
7409 are not included in the value of this property, because their
7410 presence can be inferred from the fact that a method call on
7411 <literal>org.freedesktop.DBus.Properties</literal> asking for
7412 properties of <literal>org.freedesktop.DBus</literal> was
7413 successful. The standard <literal>org.freedesktop.DBus.Peer</literal>
7414 and <literal>org.freedesktop.DBus.Introspectable</literal>
7415 interfaces are not included in the value of this property either,
7416 because they do not indicate features of the message bus
7417 implementation.
7418 </para>
7419 </sect3>
7420 </sect2>
7421
7422 <sect2>
7423 <title>Message Bus Introspection</title>
7424 <para>
7425 The message bus should implement the standard
7426 <link linkend="standard-interfaces-introspectable">Introspectable</link>
7427 interface.
7428 </para>
7429 </sect2>
7430
7431 <sect2>
7432 <title>Message Bus as a Peer</title>
7433 <para>
7434 The message bus should implement the standard
7435 <link linkend="standard-interfaces-peer">Peer</link> interface.
7436 Support for the Peer interface was added in version
7437 1.11.x of the reference implementation of the message bus.
7438 </para>
7439 </sect2>
7440
7441 <sect2 id="message-bus-properties">
7442 <title>Message Bus Properties</title>
7443 <para>
7444 The message bus should implement the standard
7445 <link linkend="standard-interfaces-properties">Properties</link>
7446 interface on the object path
7447 <literal>/org/freedesktop/DBus</literal>.
7448 The specific properties to be provided are documented as part of
7449 their respective interfaces.
7450 Support for the Properties interface was added in version
7451 1.11.x of the reference implementation of the message bus.
7452 </para>
7453 </sect2>
7454
7455 <sect2 id="message-bus-monitoring-interface">
7456 <title>Monitoring Interface: <literal>org.freedesktop.DBus.Monitoring</literal></title>
7457 <para>
7458 The special message bus name <literal>org.freedesktop.DBus</literal>
7459 may optionally implement the
7460 <literal>org.freedesktop.DBus.Monitoring</literal> interface on
7461 the object path <literal>/org/freedesktop/DBus</literal>.
7462 </para>
7463
7464 <sect3 id="bus-messages-become-monitor">
7465 <title>Method: <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal></title>
7466 <para>
7467 As a method:
7468 <programlisting>
7469 BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
7470 </programlisting>
7471 Message arguments:
7472 <informaltable>
7473 <tgroup cols="3">
7474 <thead>
7475 <row>
7476 <entry>Argument</entry>
7477 <entry>Type</entry>
7478 <entry>Description</entry>
7479 </row>
7480 </thead>
7481 <tbody>
7482 <row>
7483 <entry>0</entry>
7484 <entry>ARRAY of STRING</entry>
7485 <entry>Match rules to add to the connection</entry>
7486 </row>
7487 <row>
7488 <entry>1</entry>
7489 <entry>UINT32</entry>
7490 <entry>Not used, must be 0</entry>
7491 </row>
7492 </tbody>
7493 </tgroup>
7494 </informaltable>
7495 </para>
7496
7497 <para>
7498 Converts the connection into a <emphasis>monitor
7499 connection</emphasis> which can be used as a debugging/monitoring
7500 tool. Only a user who is privileged on this
7501 bus (by some implementation-specific definition) may create
7502 monitor connections<footnote>
7503 <para>
7504 In the reference implementation,
7505 the default configuration is that each user (identified by
7506 numeric user ID) may monitor their own session bus,
7507 and the root user (user ID zero) may monitor the
7508 system bus.
7509 </para>
7510 </footnote>.
7511 </para>
7512
7513 <para>
7514 Monitor connections lose all their bus names, including the unique
7515 connection name, and all their match rules. Sending messages on a
7516 monitor connection is not allowed: applications should use a private
7517 connection for monitoring.
7518 </para>
7519
7520 <para>
7521 Monitor connections may receive all messages, even messages that
7522 should only have gone to some other connection ("eavesdropping").
7523 The first argument is a list of match rules, which replace any
7524 match rules that were previously active for this connection.
7525 These match rules are always treated as if they contained the
7526 special <literal>eavesdrop='true'</literal> member.
7527 </para>
7528
7529 <para>
7530 As a special case, an empty list of match rules (which would
7531 otherwise match nothing, making the monitor useless) is treated
7532 as a shorthand for matching all messages.
7533 </para>
7534
7535 <para>
7536 The second argument might be used for flags to influence the
7537 behaviour of the monitor connection in future D-Bus versions.
7538 </para>
7539
7540 <para>
7541 Message bus implementations should attempt to minimize the
7542 side-effects of monitoring — in particular, unlike ordinary
7543 eavesdropping, monitoring the system bus does not require the
7544 access control rules to be relaxed, which would change the set
7545 of messages that can be delivered to their (non-monitor)
7546 destinations. However, it is unavoidable that monitoring
7547 will increase the message bus's resource consumption. In
7548 edge cases where there was barely enough time or memory without
7549 monitoring, this might result in message deliveries failing
7550 when they would otherwise have succeeded.
7551 </para>
7552 </sect3>
7553 </sect2>
7554
7555 <sect2 id="message-bus-debug-stats-interface">
7556 <title>Debug Statistics Interface: <literal>org.freedesktop.DBus.Debug.Stats</literal></title>
7557 <para>
7558 The special message bus name <literal>org.freedesktop.DBus</literal>
7559 may optionally implement the
7560 <literal>org.freedesktop.DBus.Debug.Stats</literal> interface on
7561 the object path <literal>/org/freedesktop/DBus</literal>.
7562 This interface provides statistics which might be useful to
7563 investigate performance bottlenecks.
7564 </para>
7565 <para>
7566 In the reference implementation, this interface is an optional
7567 feature, which can be enabled or disabled at compile-time.
7568 On the well-known system bus or other buses that serve more than
7569 one user, access to this interface should normally be restricted to
7570 administrative users, but can be opened up to developers via
7571 configuration if required.
7572 </para>
7573
7574 <sect3 id="bus-messages-get-stats">
7575 <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetStats</literal></title>
7576 <para>
7577 As a method:
7578 <programlisting>
7579 GetStats (out ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; stats)
7580 </programlisting>
7581 Message arguments:
7582 <informaltable>
7583 <tgroup cols="3">
7584 <thead>
7585 <row>
7586 <entry>Argument</entry>
7587 <entry>Type</entry>
7588 <entry>Description</entry>
7589 </row>
7590 </thead>
7591 <tbody>
7592 <row>
7593 <entry>0</entry>
7594 <entry>ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;</entry>
7595 <entry>Statistics</entry>
7596 </row>
7597 </tbody>
7598 </tgroup>
7599 </informaltable>
7600 Get statistics about the message bus itself.
7601 </para>
7602 <para>
7603 The following keys in the result dictionary are defined by
7604 this specification:
7605
7606 <informaltable>
7607 <tgroup cols="3">
7608 <thead>
7609 <row>
7610 <entry>Key</entry>
7611 <entry>Value type</entry>
7612 <entry>Value</entry>
7613 </row>
7614 </thead>
7615 <tbody>
7616
7617 <!-- Basic information -->
7618 <row>
7619 <entry><literal>Serial</literal></entry>
7620 <entry>UINT32</entry>
7621 <entry>A serial number which is incremented with each
7622 call to the <literal>GetStats</literal> method.</entry>
7623 </row>
7624
7625 <!-- Connection count -->
7626 <row>
7627 <entry><literal>ActiveConnections</literal></entry>
7628 <entry>UINT32</entry>
7629 <entry>The number of active connections currently handled
7630 by this message bus.
7631 The exact meaning of an active connection is
7632 implementation-defined: in the reference dbus-daemon,
7633 a connection is considered to be active after it has
7634 successfully called
7635 <link xref="bus-messages-hello">the Hello
7636 method</link>.</entry>
7637 </row>
7638 <row>
7639 <entry><literal>IncompleteConnections</literal></entry>
7640 <entry>UINT32</entry>
7641 <entry>The number of incomplete connections currently handled
7642 by this message bus.
7643 The exact meaning of an incomplete connection is
7644 implementation-defined: in the reference dbus-daemon,
7645 a connection is considered to be incomplete if it is
7646 still carrying out the SASL handshake or if it has not
7647 yet successfully called
7648 <link xref="bus-messages-hello">the Hello
7649 method</link>.</entry>
7650 </row>
7651
7652 <!-- Match rules -->
7653 <row>
7654 <entry><literal>MatchRules</literal></entry>
7655 <entry>UINT32</entry>
7656 <entry>The total number of match rules that are
7657 currently in use.</entry>
7658 </row>
7659 <row>
7660 <entry><literal>PeakMatchRules</literal></entry>
7661 <entry>UINT32</entry>
7662 <entry>The largest total number of match rules that have
7663 been in use at any one time.</entry>
7664 </row>
7665 <row>
7666 <entry><literal>PeakMatchRulesPerConnection</literal></entry>
7667 <entry>UINT32</entry>
7668 <entry>The largest total number of match rules that have
7669 been in use by a single connection at any one time.</entry>
7670 </row>
7671
7672 <!-- Bus names -->
7673 <row>
7674 <entry><literal>BusNames</literal></entry>
7675 <entry>UINT32</entry>
7676 <entry>The total number of unique or well-known bus names
7677 that are currently owned by all connections.</entry>
7678 </row>
7679 <row>
7680 <entry><literal>PeakBusNames</literal></entry>
7681 <entry>UINT32</entry>
7682 <entry>The largest total number of bus names
7683 that have been owned by all connections at any
7684 one time.</entry>
7685 </row>
7686 <row>
7687 <entry><literal>PeakBusNamesPerConnection</literal></entry>
7688 <entry>UINT32</entry>
7689 <entry>The largest total number of bus names
7690 that have been owned by any single connection at any
7691 one time.</entry>
7692 </row>
7693
7694 </tbody>
7695 </tgroup>
7696 </informaltable>
7697 </para>
7698 <para>
7699 All other keys are implementation-specific until or unless they
7700 are standardized in this specification.
7701 The reference dbus-daemon provides additional keys
7702 <literal>ListMemPoolUsedBytes</literal>,
7703 <literal>ListMemPoolCachedBytes</literal>,
7704 <literal>ListMemPoolAllocatedBytes</literal>
7705 with UINT32 values, all of which describe implementation details
7706 of libdbus’ memory management.
7707 </para>
7708 </sect3>
7709
7710 <sect3 id="bus-messages-get-connection-stats">
7711 <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetConnectionStats</literal></title>
7712 <para>
7713 As a method:
7714 <programlisting>
7715 GetConnectionStats (in STRING connection, out ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt; stats)
7716 </programlisting>
7717 Message arguments:
7718 <informaltable>
7719 <tgroup cols="3">
7720 <thead>
7721 <row>
7722 <entry>Argument</entry>
7723 <entry>Type</entry>
7724 <entry>Description</entry>
7725 </row>
7726 </thead>
7727 <tbody>
7728 <row>
7729 <entry>0</entry>
7730 <entry>STRING</entry>
7731 <entry>Unique or well-known name of a connection</entry>
7732 </row>
7733 <row>
7734 <entry>1</entry>
7735 <entry>ARRAY of DICT_ENTRY&lt;STRING,VARIANT&gt;</entry>
7736 <entry>Statistics</entry>
7737 </row>
7738 </tbody>
7739 </tgroup>
7740 </informaltable>
7741 Get statistics about a connection, identified by its unique
7742 connection name or by any well-known bus name for which it is
7743 the primary owner.
7744 This method is not meaningful for the message bus
7745 <literal>org.freedesktop.DBus</literal> itself.
7746 </para>
7747 <para>
7748 The following keys in the result dictionary are defined by
7749 this specification:
7750
7751 <informaltable>
7752 <tgroup cols="3">
7753 <thead>
7754 <row>
7755 <entry>Key</entry>
7756 <entry>Value type</entry>
7757 <entry>Value</entry>
7758 </row>
7759 </thead>
7760 <tbody>
7761
7762 <!-- Basic information -->
7763 <row>
7764 <entry><literal>Serial</literal></entry>
7765 <entry>UINT32</entry>
7766 <entry>A serial number which is incremented with each
7767 call to the <literal>GetConnectionStats</literal>
7768 method.</entry>
7769 </row>
7770 <row>
7771 <entry><literal>UniqueName</literal></entry>
7772 <entry>STRING</entry>
7773 <entry>The connection's unique connection name.
7774 If the first parameter to
7775 <literal>GetConnectionStats</literal> was a unique
7776 name, this will be the same unique name.
7777 If the first parameter was a well-known name, this
7778 is equivalent to the result of calling
7779 <link xref="bus-messages-get-name-owner">GetNameOwner</link>
7780 on that well-known name.</entry>
7781 </row>
7782
7783 <!-- Match rules -->
7784 <row>
7785 <entry><literal>MatchRules</literal></entry>
7786 <entry>UINT32</entry>
7787 <entry>The total number of match rules that are
7788 currently in use by this connection.</entry>
7789 </row>
7790 <row>
7791 <entry><literal>PeakMatchRules</literal></entry>
7792 <entry>UINT32</entry>
7793 <entry>The largest total number of match rules that have
7794 been in use by this connection at any one time.</entry>
7795 </row>
7796
7797 <!-- Bus names -->
7798 <row>
7799 <entry><literal>BusNames</literal></entry>
7800 <entry>UINT32</entry>
7801 <entry>The total number of bus names that are
7802 currently owned by this connection.</entry>
7803 </row>
7804 <row>
7805 <entry><literal>PeakBusNames</literal></entry>
7806 <entry>UINT32</entry>
7807 <entry>The largest total number of bus names
7808 that have been owned by this connection at any
7809 one time.</entry>
7810 </row>
7811
7812 <!-- Incoming queued messages -->
7813 <row>
7814 <entry><literal>IncomingMessages</literal></entry>
7815 <entry>UINT32</entry>
7816 <entry>The total number of messages queued in the message
7817 bus that have been received from this connection and not
7818 yet dispatched.</entry>
7819 </row>
7820 <row>
7821 <entry><literal>IncomingBytes</literal></entry>
7822 <entry>UINT32</entry>
7823 <entry>The total number of bytes in the incoming
7824 messages.</entry>
7825 </row>
7826 <row>
7827 <entry><literal>IncomingFDs</literal></entry>
7828 <entry>UINT32</entry>
7829 <entry>The total number of Unix file descriptors
7830 attached to the incoming messages.</entry>
7831 </row>
7832 <row>
7833 <entry><literal>PeakIncomingBytes</literal></entry>
7834 <entry>UINT32</entry>
7835 <entry>The highest total number of bytes in the incoming
7836 messages at any one time.</entry>
7837 </row>
7838 <row>
7839 <entry><literal>PeakIncomingFDs</literal></entry>
7840 <entry>UINT32</entry>
7841 <entry>The highest total number of Unix file descriptors
7842 attached to the incoming messages at any one time.</entry>
7843 </row>
7844
7845 <!-- Outgoing queued messages -->
7846 <row>
7847 <entry><literal>OutgoingMessages</literal></entry>
7848 <entry>UINT32</entry>
7849 <entry>The total number of messages queued in the message
7850 bus to be delivered to this connection.</entry>
7851 </row>
7852 <row>
7853 <entry><literal>OutgoingBytes</literal></entry>
7854 <entry>UINT32</entry>
7855 <entry>The total number of bytes in the outgoing
7856 messages.</entry>
7857 </row>
7858 <row>
7859 <entry><literal>OutgoingFDs</literal></entry>
7860 <entry>UINT32</entry>
7861 <entry>The total number of Unix file descriptors
7862 attached to the outgoing messages.</entry>
7863 </row>
7864 <row>
7865 <entry><literal>PeakOutgoingBytes</literal></entry>
7866 <entry>UINT32</entry>
7867 <entry>The highest total number of bytes in the outgoing
7868 messages at any one time.</entry>
7869 </row>
7870 <row>
7871 <entry><literal>PeakOutgoingFDs</literal></entry>
7872 <entry>UINT32</entry>
7873 <entry>The highest total number of Unix file descriptors
7874 attached to the outgoing messages at any one time.</entry>
7875 </row>
7876
7877 </tbody>
7878 </tgroup>
7879 </informaltable>
7880 </para>
7881 <para>
7882 All other keys are implementation-specific until or unless they
7883 are standardized in this specification.
7884 </para>
7885 </sect3>
7886
7887 <sect3 id="bus-messages-get-all-match-rules">
7888 <title>Method: <literal>org.freedesktop.DBus.Debug.Stats.GetAllMatchRules</literal></title>
7889 <para>
7890 As a method:
7891 <programlisting>
7892 GetAllMatchRules (out ARRAY of DICT_ENTRY&lt;STRING,ARRAY&lt;STRING&gt;&gt; rules)
7893 </programlisting>
7894 Message arguments:
7895 <informaltable>
7896 <tgroup cols="3">
7897 <thead>
7898 <row>
7899 <entry>Argument</entry>
7900 <entry>Type</entry>
7901 <entry>Description</entry>
7902 </row>
7903 </thead>
7904 <tbody>
7905 <row>
7906 <entry>0</entry>
7907 <entry>ARRAY of DICT_ENTRY&lt;STRING,ARRAY&lt;STRING&gt;&gt;</entry>
7908 <entry>Match rules</entry>
7909 </row>
7910 </tbody>
7911 </tgroup>
7912 </informaltable>
7913 List all of the match rules that are active on this message bus.
7914 The keys in the result dictionary are unique connection names.
7915 The values are lists of match rules registered by that connection,
7916 in an unspecified order.
7917 If a connection has registered the same match rule more than once,
7918 it is unspecified whether duplicate entries appear in the list.
7919 </para>
7920 </sect3>
7921
7922 </sect2>
7923
7924 <sect2 id="message-bus-verbose-interface">
7925 <title>Verbose Interface: <literal>org.freedesktop.DBus.Verbose</literal></title>
7926 <para>
7927 The special message bus name <literal>org.freedesktop.DBus</literal>
7928 may optionally implement the
7929 <literal>org.freedesktop.DBus.Verbose</literal> interface on
7930 the object path <literal>/org/freedesktop/DBus</literal>.
7931 In the reference implementation, this interface is an optional
7932 feature, which can be enabled or disabled at compile-time.
7933 On the well-known system bus or other buses that serve more than
7934 one user, access to this interface should normally be restricted to
7935 administrative users, but can be opened up to developers via
7936 configuration if required.
7937 </para>
7938
7939 <sect3 id="bus-messages-enable-verbose">
7940 <title>Method: <literal>org.freedesktop.DBus.Verbose.EnableVerbose</literal></title>
7941 <para>
7942 As a method:
7943 <programlisting>
7944 EnableVerbose ()
7945 </programlisting>
7946 Start producing verbose debugging messages in an
7947 implementation-specific way.
7948 For example, these messages might go to standard error or to a
7949 system event log.
7950 </para>
7951 </sect3>
7952
7953 <sect3 id="bus-messages-disable-verbose">
7954 <title>Method: <literal>org.freedesktop.DBus.Verbose.DisableVerbose</literal></title>
7955 <para>
7956 As a method:
7957 <programlisting>
7958 DisableVerbose ()
7959 </programlisting>
7960 Stop producing verbose debugging messages.
7961 </para>
7962 </sect3>
7963
7964 </sect2>
7965 </sect1>
7966 <!--
7967 <appendix id="implementation-notes">
7968 <title>Implementation notes</title>
7969 <sect1 id="implementation-notes-subsection">
7970 <title></title>
7971 <para>
7972 </para>
7973 </sect1>
7974 </appendix>
7975 -->
7976
7977 <glossary><title>Glossary</title>
7978 <para>
7979 This glossary defines some of the terms used in this specification.
7980 </para>
7981
7982 <glossentry id="term-bus-name"><glossterm>Bus Name</glossterm>
7983 <glossdef>
7984 <para>
7985 The message bus maintains an association between names and
7986 connections. (Normally, there's one connection per application.) A
7987 bus name is simply an identifier used to locate connections. For
7988 example, the hypothetical <literal>com.yoyodyne.Screensaver</literal>
7989 name might be used to send a message to a screensaver from Yoyodyne
7990 Corporation. An application is said to <firstterm>own</firstterm> a
7991 name if the message bus has associated the application's connection
7992 with the name. Names may also have <firstterm>queued
7993 owners</firstterm> (see <xref linkend="term-queued-owner"/>).
7994 The bus assigns a unique name to each connection,
7995 see <xref linkend="term-unique-name"/>. Other names
7996 can be thought of as "well-known names" and are
7997 used to find applications that offer specific functionality.
7998 </para>
7999
8000 <para>
8001 See <xref linkend="message-protocol-names-bus"/> for details of
8002 the syntax and naming conventions for bus names.
8003 </para>
8004 </glossdef>
8005 </glossentry>
8006
8007 <glossentry id="term-message"><glossterm>Message</glossterm>
8008 <glossdef>
8009 <para>
8010 A message is the atomic unit of communication via the D-Bus
8011 protocol. It consists of a <firstterm>header</firstterm> and a
8012 <firstterm>body</firstterm>; the body is made up of
8013 <firstterm>arguments</firstterm>.
8014 </para>
8015 </glossdef>
8016 </glossentry>
8017
8018 <glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
8019 <glossdef>
8020 <para>
8021 The message bus is a special application that forwards
8022 or routes messages between a group of applications
8023 connected to the message bus. It also manages
8024 <firstterm>names</firstterm> used for routing
8025 messages.
8026 </para>
8027 </glossdef>
8028 </glossentry>
8029
8030 <glossentry id="term-name"><glossterm>Name</glossterm>
8031 <glossdef>
8032 <para>
8033 See <xref linkend="term-bus-name"/>. "Name" may
8034 also be used to refer to some of the other names
8035 in D-Bus, such as interface names.
8036 </para>
8037 </glossdef>
8038 </glossentry>
8039
8040 <glossentry id="namespace"><glossterm>Namespace</glossterm>
8041 <glossdef>
8042 <para>
8043 Used to prevent collisions when defining new interfaces, bus names
8044 etc. The convention used is the same one Java uses for defining
8045 classes: a reversed domain name.
8046 See <xref linkend="message-protocol-names-bus"/>,
8047 <xref linkend="message-protocol-names-interface"/>,
8048 <xref linkend="message-protocol-names-error"/>,
8049 <xref linkend="message-protocol-marshaling-object-path"/>.
8050 </para>
8051 </glossdef>
8052 </glossentry>
8053
8054 <glossentry id="term-object"><glossterm>Object</glossterm>
8055 <glossdef>
8056 <para>
8057 Each application contains <firstterm>objects</firstterm>, which have
8058 <firstterm>interfaces</firstterm> and
8059 <firstterm>methods</firstterm>. Objects are referred to by a name,
8060 called a <firstterm>path</firstterm>.
8061 </para>
8062 </glossdef>
8063 </glossentry>
8064
8065 <glossentry id="one-to-one"><glossterm>One-to-One</glossterm>
8066 <glossdef>
8067 <para>
8068 An application talking directly to another application, without going
8069 through a message bus. One-to-one connections may be "peer to peer" or
8070 "client to server." The D-Bus protocol has no concept of client
8071 vs. server after a connection has authenticated; the flow of messages
8072 is symmetrical (full duplex).
8073 </para>
8074 </glossdef>
8075 </glossentry>
8076
8077 <glossentry id="term-path"><glossterm>Path</glossterm>
8078 <glossdef>
8079 <para>
8080 Object references (object names) in D-Bus are organized into a
8081 filesystem-style hierarchy, so each object is named by a path. As in
8082 LDAP, there's no difference between "files" and "directories"; a path
8083 can refer to an object, while still having child objects below it.
8084 </para>
8085 </glossdef>
8086 </glossentry>
8087
8088 <glossentry id="term-queued-owner"><glossterm>Queued Name Owner</glossterm>
8089 <glossdef>
8090 <para>
8091 Each bus name has a primary owner; messages sent to the name go to the
8092 primary owner. However, certain names also maintain a queue of
8093 secondary owners "waiting in the wings." If the primary owner releases
8094 the name, then the first secondary owner in the queue automatically
8095 becomes the new owner of the name.
8096 </para>
8097 </glossdef>
8098 </glossentry>
8099
8100 <glossentry id="term-service"><glossterm>Service</glossterm>
8101 <glossdef>
8102 <para>
8103 A service is an executable that can be launched by the bus daemon.
8104 Services normally guarantee some particular features, for example they
8105 may guarantee that they will request a specific name such as
8106 "com.example.Screensaver1", have a singleton object
8107 "/com/example/Screensaver1", and that object will implement the
8108 interface "com.example.Screensaver1.Control".
8109 </para>
8110 </glossdef>
8111 </glossentry>
8112
8113 <glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
8114 <glossdef>
8115 <para>
8116 ".service files" tell the bus about service applications that can be
8117 launched (see <xref linkend="term-service"/>). Most importantly they
8118 provide a mapping from bus names to services that will request those
8119 names when they start up.
8120 </para>
8121 </glossdef>
8122 </glossentry>
8123
8124 <glossentry id="term-unique-name"><glossterm>Unique Connection Name</glossterm>
8125 <glossdef>
8126 <para>
8127 The special name automatically assigned to each connection by the
8128 message bus. This name will never change owner, and will be unique
8129 (never reused during the lifetime of the message bus).
8130 It will begin with a ':' character.
8131 </para>
8132 </glossdef>
8133 </glossentry>
8134
8135 </glossary>
8136 </article>