1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D-Bus Specification</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="D-Bus Specification"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>D-Bus Specification</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Havoc</span> <span class="surname">Pennington</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br> 2 ����<code class="email"><<a class="email" href="mailto:hp@pobox.com">hp@pobox.com</a>></code><br> 3 ��</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Anders</span> <span class="surname">Carlsson</span></h3><div class="affiliation"><span class="orgname">CodeFactory AB<br></span><div class="address"><p><br> 4������������<code class="email"><<a class="email" href="mailto:andersca@codefactory.se">andersca@codefactory.se</a>></code><br> 5����������</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Alexander</span> <span class="surname">Larsson</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br> 6������������<code class="email"><<a class="email" href="mailto:alexl@redhat.com">alexl@redhat.com</a>></code><br> 7����������</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Sven</span> <span class="surname">Herzberg</span></h3><div class="affiliation"><span class="orgname">Imendio AB<br></span><div class="address"><p><br> 8������������<code class="email"><<a class="email" href="mailto:sven@imendio.com">sven@imendio.com</a>></code><br> 9����������</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Simon</span> <span class="surname">McVittie</span></h3><div class="affiliation"><span class="orgname">Collabora Ltd.<br></span><div class="address"><p><br> 10������������<code class="email"><<a class="email" href="mailto:simon.mcvittie@collabora.co.uk">simon.mcvittie@collabora.co.uk</a>></code><br> 11����������</p></div></div></div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Zeuthen</span></h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><p><br> 12������������<code class="email"><<a class="email" href="mailto:davidz@redhat.com">davidz@redhat.com</a>></code><br> 13����������</p></div></div></div></div></div><div><p class="releaseinfo">Version 0.19</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="3"><b>Revision History</b></th></tr><tr><td align="left">Revision current</td><td align="left"><a class="ulink" href="http://cgit.freedesktop.org/dbus/dbus/log/doc/dbus-specification.xml" target="_top">commit log</a></td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.19</td><td align="left">20 February 2012</td><td align="left">smcv/lp</td></tr><tr><td align="left" colspan="3">formally define unique connection names and well-known 14 bus names; document best practices for interface, bus, member and 15 error names, and object paths; document the search path for session 16 and system services on Unix; document the systemd transport</td></tr><tr><td align="left">Revision 0.18</td><td align="left">29 July 2011</td><td align="left">smcv</td></tr><tr><td align="left" colspan="3">define eavesdropping, unicast, broadcast; add eavesdrop 17 match keyword; promote type system to a top-level section</td></tr><tr><td align="left">Revision 0.17</td><td align="left">1 June 2011</td><td align="left">smcv/davidz</td></tr><tr><td align="left" colspan="3">define ObjectManager; reserve extra pseudo-type-codes used 18 by GVariant</td></tr><tr><td align="left">Revision 0.16</td><td align="left">11 April 2011</td><td align="left"></td></tr><tr><td align="left" colspan="3">add path_namespace, arg0namespace; argNpath matches object 19 paths</td></tr><tr><td align="left">Revision 0.15</td><td align="left">3 November 2010</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.14</td><td align="left">12 May 2010</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.13</td><td align="left">23 Dezember 2009</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.12</td><td align="left">7 November, 2006</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.11</td><td align="left">6 February 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.10</td><td align="left">28 January 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.9</td><td align="left">7 Januar 2005</td><td align="left"></td></tr><tr><td align="left" colspan="3"></td></tr><tr><td align="left">Revision 0.8</td><td align="left">06 September 2003</td><td align="left"></td></tr><tr><td align="left" colspan="3">First released document.</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#introduction">Introduction</a></span></dt><dd><dl><dt><span class="sect2"><a href="#stability">Protocol and Specification Stability</a></span></dt></dl></dd><dt><span class="sect1"><a href="#type-system">Type System</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-protocol-signatures">Type Signatures</a></span></dt><dt><span class="sect2"><a href="#message-protocol-marshaling">Marshaling (Wire Format)</a></span></dt></dl></dd><dt><span class="sect1"><a href="#message-protocol">Message Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-protocol-messages">Message Format</a></span></dt><dt><span class="sect2"><a href="#message-protocol-names">Valid Names</a></span></dt><dt><span class="sect2"><a href="#message-protocol-types">Message Types</a></span></dt><dt><span class="sect2"><a href="#message-protocol-handling-invalid">Invalid Protocol and Spec Extensions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#auth-protocol">Authentication Protocol</a></span></dt><dd><dl><dt><span class="sect2"><a href="#auth-protocol-overview">Protocol Overview</a></span></dt><dt><span class="sect2"><a href="#auth-nul-byte">Special credentials-passing nul byte</a></span></dt><dt><span class="sect2"><a href="#auth-command-auth">AUTH command</a></span></dt><dt><span class="sect2"><a href="#auth-command-cancel">CANCEL Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-data">DATA Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-begin">BEGIN Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-rejected">REJECTED Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-ok">OK Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-error">ERROR Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-negotiate-unix-fd">NEGOTIATE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-agree-unix-fd">AGREE_UNIX_FD Command</a></span></dt><dt><span class="sect2"><a href="#auth-command-future">Future Extensions</a></span></dt><dt><span class="sect2"><a href="#auth-examples">Authentication examples</a></span></dt><dt><span class="sect2"><a href="#auth-states">Authentication state diagrams</a></span></dt><dt><span class="sect2"><a href="#auth-mechanisms">Authentication mechanisms</a></span></dt></dl></dd><dt><span class="sect1"><a href="#addresses">Server Addresses</a></span></dt><dt><span class="sect1"><a href="#transports">Transports</a></span></dt><dd><dl><dt><span class="sect2"><a href="#transports-unix-domain-sockets">Unix Domain Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-launchd">launchd</a></span></dt><dt><span class="sect2"><a href="#transports-systemd">systemd</a></span></dt><dt><span class="sect2"><a href="#transports-tcp-sockets">TCP Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-nonce-tcp-sockets">Nonce-secured TCP Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-exec">Executed Subprocesses on Unix</a></span></dt></dl></dd><dt><span class="sect1"><a href="#meta-transports">Meta Transports</a></span></dt><dd><dl><dt><span class="sect2"><a href="#meta-transports-autolaunch">Autolaunch</a></span></dt></dl></dd><dt><span class="sect1"><a href="#uuids">UUIDs</a></span></dt><dt><span class="sect1"><a href="#standard-interfaces">Standard Interfaces</a></span></dt><dd><dl><dt><span class="sect2"><a href="#standard-interfaces-peer"><code class="literal">org.freedesktop.DBus.Peer</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-introspectable"><code class="literal">org.freedesktop.DBus.Introspectable</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-properties"><code class="literal">org.freedesktop.DBus.Properties</code></a></span></dt><dt><span class="sect2"><a href="#standard-interfaces-objectmanager"><code class="literal">org.freedesktop.DBus.ObjectManager</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="#introspection-format">Introspection Data Format</a></span></dt><dt><span class="sect1"><a href="#message-bus">Message Bus Specification</a></span></dt><dd><dl><dt><span class="sect2"><a href="#message-bus-overview">Message Bus Overview</a></span></dt><dt><span class="sect2"><a href="#message-bus-names">Message Bus Names</a></span></dt><dt><span class="sect2"><a href="#message-bus-routing">Message Bus Message Routing</a></span></dt><dt><span class="sect2"><a href="#message-bus-starting-services">Message Bus Starting Services</a></span></dt><dt><span class="sect2"><a href="#message-bus-types">Well-known Message Bus Instances</a></span></dt><dt><span class="sect2"><a href="#message-bus-messages">Message Bus Messages</a></span></dt></dl></dd><dt><span class="glossary"><a href="#idp5904720">Glossary</a></span></dt></dl></div><div class="sect1" title="Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div></div><p> 20 D-Bus is a system for low-latency, low-overhead, easy to use 21 interprocess communication (IPC). In more detail: 22 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 23 D-Bus is <span class="emphasis"><em>low-latency</em></span> because it is designed 24 to avoid round trips and allow asynchronous operation, much like 25 the X protocol. 26 </p></li><li class="listitem"><p> 27 D-Bus is <span class="emphasis"><em>low-overhead</em></span> because it uses a 28 binary protocol, and does not have to convert to and from a text 29 format such as XML. Because D-Bus is intended for potentially 30 high-resolution same-machine IPC, not primarily for Internet IPC, 31 this is an interesting optimization. 32 </p></li><li class="listitem"><p> 33 D-Bus is <span class="emphasis"><em>easy to use</em></span> because it works in terms 34 of <em class="firstterm">messages</em> rather than byte streams, and 35 automatically handles a lot of the hard IPC issues. Also, the D-Bus 36 library is designed to be wrapped in a way that lets developers use 37 their framework's existing object/type system, rather than learning 38 a new one specifically for IPC. 39 </p></li></ul></div><p> 40 </p><p> 41 The base D-Bus protocol is a one-to-one (peer-to-peer or client-server) 42 protocol, specified in <a class="xref" href="#message-protocol" title="Message Protocol">the section called “Message Protocol”</a>. That is, it is 43 a system for one application to talk to a single other 44 application. However, the primary intended application of the protocol is the 45 D-Bus <em class="firstterm">message bus</em>, specified in <a class="xref" href="#message-bus" title="Message Bus Specification">the section called “Message Bus Specification”</a>. The message bus is a special application that 46 accepts connections from multiple other applications, and forwards 47 messages among them. 48 </p><p> 49 Uses of D-Bus include notification of system changes (notification of when 50 a camera is plugged in to a computer, or a new version of some software 51 has been installed), or desktop interoperability, for example a file 52 monitoring service or a configuration service. 53 </p><p> 54 D-Bus is designed for two specific use cases: 55 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 56 A "system bus" for notifications from the system to user sessions, 57 and to allow the system to request input from user sessions. 58 </p></li><li class="listitem"><p> 59 A "session bus" used to implement desktop environments such as 60 GNOME and KDE. 61 </p></li></ul></div><p> 62 D-Bus is not intended to be a generic IPC system for any possible 63 application, and intentionally omits many features found in other 64 IPC systems for this reason. 65 </p><p> 66 At the same time, the bus daemons offer a number of features not found in 67 other IPC systems, such as single-owner "bus names" (similar to X 68 selections), on-demand startup of services, and security policies. 69 In many ways, these features are the primary motivation for developing 70 D-Bus; other systems would have sufficed if IPC were the only goal. 71 </p><p> 72 D-Bus may turn out to be useful in unanticipated applications, but future 73 versions of this spec and the reference implementation probably will not 74 incorporate features that interfere with the core use cases. 75 </p><p> 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in RFC 2119. However, the 79 document could use a serious audit to be sure it makes sense to do 80 so. Also, they are not capitalized. 81 </p><div class="sect2" title="Protocol and Specification Stability"><div class="titlepage"><div><div><h3 class="title"><a name="stability"></a>Protocol and Specification Stability</h3></div></div></div><p> 82 The D-Bus protocol is frozen (only compatible extensions are allowed) as 83 of November 8, 2006. However, this specification could still use a fair 84 bit of work to make interoperable reimplementation possible without 85 reference to the D-Bus reference implementation. Thus, this 86 specification is not marked 1.0. To mark it 1.0, we'd like to see 87 someone invest significant effort in clarifying the specification 88 language, and growing the specification to cover more aspects of the 89 reference implementation's behavior. 90 </p><p> 91 Until this work is complete, any attempt to reimplement D-Bus will 92 probably require looking at the reference implementation and/or asking 93 questions on the D-Bus mailing list about intended behavior. 94 Questions on the list are very welcome. 95 </p><p> 96 Nonetheless, this document should be a useful starting point and is 97 to our knowledge accurate, though incomplete. 98 </p></div></div><div class="sect1" title="Type System"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="type-system"></a>Type System</h2></div></div></div><p> 99 D-Bus has a type system, in which values of various types can be 100 serialized into a sequence of bytes referred to as the 101 <em class="firstterm">wire format</em> in a standard way. 102 Converting a value from some other representation into the wire 103 format is called <em class="firstterm">marshaling</em> and converting 104 it back from the wire format is <em class="firstterm">unmarshaling</em>. 105 </p><div class="sect2" title="Type Signatures"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-signatures"></a>Type Signatures</h3></div></div></div><p> 106 The D-Bus protocol does not include type tags in the marshaled data; a 107 block of marshaled values must have a known <em class="firstterm">type 108 signature</em>. The type signature is made up of <em class="firstterm">type 109 codes</em>. A type code is an ASCII character representing the 110 type of a value. Because ASCII characters are used, the type signature 111 will always form a valid ASCII string. A simple string compare 112 determines whether two type signatures are equivalent. 113 </p><p> 114 As a simple example, the type code for 32-bit integer (<code class="literal">INT32</code>) is 115 the ASCII character 'i'. So the signature for a block of values 116 containing a single <code class="literal">INT32</code> would be: 117 </p><pre class="programlisting"> 118 "i" 119 </pre><p> 120 A block of values containing two <code class="literal">INT32</code> would have this signature: 121 </p><pre class="programlisting"> 122 "ii" 123 </pre><p> 124 </p><p> 125 All <em class="firstterm">basic</em> types work like 126 <code class="literal">INT32</code> in this example. To marshal and unmarshal 127 basic types, you simply read one value from the data 128 block corresponding to each type code in the signature. 129 In addition to basic types, there are four <em class="firstterm">container</em> 130 types: <code class="literal">STRUCT</code>, <code class="literal">ARRAY</code>, <code class="literal">VARIANT</code>, 131 and <code class="literal">DICT_ENTRY</code>. 132 </p><p> 133 <code class="literal">STRUCT</code> has a type code, ASCII character 'r', but this type 134 code does not appear in signatures. Instead, ASCII characters 135 '(' and ')' are used to mark the beginning and end of the struct. 136 So for example, a struct containing two integers would have this 137 signature: 138 </p><pre class="programlisting"> 139 "(ii)" 140 </pre><p> 141 Structs can be nested, so for example a struct containing 142 an integer and another struct: 143 </p><pre class="programlisting"> 144 "(i(ii))" 145 </pre><p> 146 The value block storing that struct would contain three integers; the 147 type signature allows you to distinguish "(i(ii))" from "((ii)i)" or 148 "(iii)" or "iii". 149 </p><p> 150 The <code class="literal">STRUCT</code> type code 'r' is not currently used in the D-Bus protocol, 151 but is useful in code that implements the protocol. This type code 152 is specified to allow such code to interoperate in non-protocol contexts. 153 </p><p> 154 Empty structures are not allowed; there must be at least one 155 type code between the parentheses. 156 </p><p> 157 <code class="literal">ARRAY</code> has ASCII character 'a' as type code. The array type code must be 158 followed by a <em class="firstterm">single complete type</em>. The single 159 complete type following the array is the type of each array element. So 160 the simple example is: 161 </p><pre class="programlisting"> 162 "ai" 163 </pre><p> 164 which is an array of 32-bit integers. But an array can be of any type, 165 such as this array-of-struct-with-two-int32-fields: 166 </p><pre class="programlisting"> 167 "a(ii)" 168 </pre><p> 169 Or this array of array of integer: 170 </p><pre class="programlisting"> 171 "aai" 172 </pre><p> 173 </p><p> 174 The phrase <em class="firstterm">single complete type</em> deserves some 175 definition. A single complete type is a basic type code, a variant type code, 176 an array with its element type, or a struct with its fields. 177 So the following signatures are not single complete types: 178 </p><pre class="programlisting"> 179 "aa" 180 </pre><p> 181 </p><pre class="programlisting"> 182 "(ii" 183 </pre><p> 184 </p><pre class="programlisting"> 185 "ii)" 186 </pre><p> 187 And the following signatures contain multiple complete types: 188 </p><pre class="programlisting"> 189 "ii" 190 </pre><p> 191 </p><pre class="programlisting"> 192 "aiai" 193 </pre><p> 194 </p><pre class="programlisting"> 195 "(ii)(ii)" 196 </pre><p> 197 Note however that a single complete type may <span class="emphasis"><em>contain</em></span> 198 multiple other single complete types. 199 </p><p> 200 <code class="literal">VARIANT</code> has ASCII character 'v' as its type code. A marshaled value of 201 type <code class="literal">VARIANT</code> will have the signature of a single complete type as part 202 of the <span class="emphasis"><em>value</em></span>. This signature will be followed by a 203 marshaled value of that type. 204 </p><p> 205 A <code class="literal">DICT_ENTRY</code> works exactly like a struct, but rather 206 than parentheses it uses curly braces, and it has more restrictions. 207 The restrictions are: it occurs only as an array element type; it has 208 exactly two single complete types inside the curly braces; the first 209 single complete type (the "key") must be a basic type rather than a 210 container type. Implementations must not accept dict entries outside of 211 arrays, must not accept dict entries with zero, one, or more than two 212 fields, and must not accept dict entries with non-basic-typed keys. A 213 dict entry is always a key-value pair. 214 </p><p> 215 The first field in the <code class="literal">DICT_ENTRY</code> is always the key. 216 A message is considered corrupt if the same key occurs twice in the same 217 array of <code class="literal">DICT_ENTRY</code>. However, for performance reasons 218 implementations are not required to reject dicts with duplicate keys. 219 </p><p> 220 In most languages, an array of dict entry would be represented as a 221 map, hash table, or dict object. 222 </p><p> 223 The following table summarizes the D-Bus types. 224 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Code</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">INVALID</code></td><td>0 (ASCII NUL)</td><td>Not a valid type code, used to terminate signatures</td></tr><tr><td><code class="literal">BYTE</code></td><td>121 (ASCII 'y')</td><td>8-bit unsigned integer</td></tr><tr><td><code class="literal">BOOLEAN</code></td><td>98 (ASCII 'b')</td><td>Boolean value, 0 is <code class="literal">FALSE</code> and 1 is <code class="literal">TRUE</code>. Everything else is invalid.</td></tr><tr><td><code class="literal">INT16</code></td><td>110 (ASCII 'n')</td><td>16-bit signed integer</td></tr><tr><td><code class="literal">UINT16</code></td><td>113 (ASCII 'q')</td><td>16-bit unsigned integer</td></tr><tr><td><code class="literal">INT32</code></td><td>105 (ASCII 'i')</td><td>32-bit signed integer</td></tr><tr><td><code class="literal">UINT32</code></td><td>117 (ASCII 'u')</td><td>32-bit unsigned integer</td></tr><tr><td><code class="literal">INT64</code></td><td>120 (ASCII 'x')</td><td>64-bit signed integer</td></tr><tr><td><code class="literal">UINT64</code></td><td>116 (ASCII 't')</td><td>64-bit unsigned integer</td></tr><tr><td><code class="literal">DOUBLE</code></td><td>100 (ASCII 'd')</td><td>IEEE 754 double</td></tr><tr><td><code class="literal">STRING</code></td><td>115 (ASCII 's')</td><td>UTF-8 string (<span class="emphasis"><em>must</em></span> be valid UTF-8). Must be nul terminated and contain no other nul bytes.</td></tr><tr><td><code class="literal">OBJECT_PATH</code></td><td>111 (ASCII 'o')</td><td>Name of an object instance</td></tr><tr><td><code class="literal">SIGNATURE</code></td><td>103 (ASCII 'g')</td><td>A type signature</td></tr><tr><td><code class="literal">ARRAY</code></td><td>97 (ASCII 'a')</td><td>Array</td></tr><tr><td><code class="literal">STRUCT</code></td><td>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</td><td>Struct; type code 114 'r' is reserved for use in 225 bindings and implementations to represent the general 226 concept of a struct, and must not appear in signatures 227 used on D-Bus.</td></tr><tr><td><code class="literal">VARIANT</code></td><td>118 (ASCII 'v') </td><td>Variant type (the type of the value is part of the value itself)</td></tr><tr><td><code class="literal">DICT_ENTRY</code></td><td>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </td><td>Entry in a dict or map (array of key-value pairs). 228 Type code 101 'e' is reserved for use in bindings and 229 implementations to represent the general concept of a 230 dict or dict-entry, and must not appear in signatures 231 used on D-Bus.</td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>104 (ASCII 'h')</td><td>Unix file descriptor</td></tr><tr><td>(reserved)</td><td>109 (ASCII 'm')</td><td>Reserved for <a class="ulink" href="https://bugs.freedesktop.org/show_bug.cgi?id=27857" target="_top">a 232 'maybe' type compatible with the one in GVariant</a>, 233 and must not appear in signatures used on D-Bus until 234 specified here</td></tr><tr><td>(reserved)</td><td>42 (ASCII '*')</td><td>Reserved for use in bindings/implementations to 235 represent any <em class="firstterm">single complete type</em>, 236 and must not appear in signatures used on D-Bus.</td></tr><tr><td>(reserved)</td><td>63 (ASCII '?')</td><td>Reserved for use in bindings/implementations to 237 represent any <em class="firstterm">basic type</em>, and must 238 not appear in signatures used on D-Bus.</td></tr><tr><td>(reserved)</td><td>64 (ASCII '@'), 38 (ASCII '&'), 239 94 (ASCII '^')</td><td>Reserved for internal use by bindings/implementations, 240 and must not appear in signatures used on D-Bus. 241 GVariant uses these type-codes to encode calling 242 conventions.</td></tr></tbody></table></div><p> 243 </p></div><div class="sect2" title="Marshaling (Wire Format)"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-marshaling"></a>Marshaling (Wire Format)</h3></div></div></div><p> 244 Given a type signature, a block of bytes can be converted into typed 245 values. This section describes the format of the block of bytes. Byte 246 order and alignment issues are handled uniformly for all D-Bus types. 247 </p><p> 248 A block of bytes has an associated byte order. The byte order 249 has to be discovered in some way; for D-Bus messages, the 250 byte order is part of the message header as described in 251 <a class="xref" href="#message-protocol-messages" title="Message Format">the section called “Message Format”</a>. For now, assume 252 that the byte order is known to be either little endian or big 253 endian. 254 </p><p> 255 Each value in a block of bytes is aligned "naturally," for example 256 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an 257 8-byte boundary. To properly align a value, <em class="firstterm">alignment 258 padding</em> may be necessary. The alignment padding must always 259 be the minimum required padding to properly align the following value; 260 and it must always be made up of nul bytes. The alignment padding must 261 not be left uninitialized (it can't contain garbage), and more padding 262 than required must not be used. 263 </p><p> 264 Given all this, the types are marshaled on the wire as follows: 265 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Encoding</th><th>Alignment</th></tr></thead><tbody><tr><td><code class="literal">INVALID</code></td><td>Not applicable; cannot be marshaled.</td><td>N/A</td></tr><tr><td><code class="literal">BYTE</code></td><td>A single 8-bit byte.</td><td>1</td></tr><tr><td><code class="literal">BOOLEAN</code></td><td>As for <code class="literal">UINT32</code>, but only 0 and 1 are valid values.</td><td>4</td></tr><tr><td><code class="literal">INT16</code></td><td>16-bit signed integer in the message's byte order.</td><td>2</td></tr><tr><td><code class="literal">UINT16</code></td><td>16-bit unsigned integer in the message's byte order.</td><td>2</td></tr><tr><td><code class="literal">INT32</code></td><td>32-bit signed integer in the message's byte order.</td><td>4</td></tr><tr><td><code class="literal">UINT32</code></td><td>32-bit unsigned integer in the message's byte order.</td><td>4</td></tr><tr><td><code class="literal">INT64</code></td><td>64-bit signed integer in the message's byte order.</td><td>8</td></tr><tr><td><code class="literal">UINT64</code></td><td>64-bit unsigned integer in the message's byte order.</td><td>8</td></tr><tr><td><code class="literal">DOUBLE</code></td><td>64-bit IEEE 754 double in the message's byte order.</td><td>8</td></tr><tr><td><code class="literal">STRING</code></td><td>A <code class="literal">UINT32</code> indicating the string's 266 length in bytes excluding its terminating nul, followed by 267 non-nul string data of the given length, followed by a terminating nul 268 byte. 269 </td><td> 270 4 (for the length) 271 </td></tr><tr><td><code class="literal">OBJECT_PATH</code></td><td>Exactly the same as <code class="literal">STRING</code> except the 272 content must be a valid object path (see below). 273 </td><td> 274 4 (for the length) 275 </td></tr><tr><td><code class="literal">SIGNATURE</code></td><td>The same as <code class="literal">STRING</code> except the length is a single 276 byte (thus signatures have a maximum length of 255) 277 and the content must be a valid signature (see below). 278 </td><td> 279 1 280 </td></tr><tr><td><code class="literal">ARRAY</code></td><td> 281 A <code class="literal">UINT32</code> giving the length of the array data in bytes, followed by 282 alignment padding to the alignment boundary of the array element type, 283 followed by each array element. The array length is from the 284 end of the alignment padding to the end of the last element, 285 i.e. it does not include the padding after the length, 286 or any padding after the last element. 287 Arrays have a maximum length defined to be 2 to the 26th power or 288 67108864. Implementations must not send or accept arrays exceeding this 289 length. 290 </td><td> 291 4 (for the length) 292 </td></tr><tr><td><code class="literal">STRUCT</code></td><td> 293 A struct must start on an 8-byte boundary regardless of the 294 type of the struct fields. The struct value consists of each 295 field marshaled in sequence starting from that 8-byte 296 alignment boundary. 297 </td><td> 298 8 299 </td></tr><tr><td><code class="literal">VARIANT</code></td><td> 300 A variant type has a marshaled 301 <code class="literal">SIGNATURE</code> followed by a marshaled 302 value with the type given in the signature. Unlike 303 a message signature, the variant signature can 304 contain only a single complete type. So "i", "ai" 305 or "(ii)" is OK, but "ii" is not. Use of variants may not 306 cause a total message depth to be larger than 64, including 307 other container types such as structures. 308 </td><td> 309 1 (alignment of the signature) 310 </td></tr><tr><td><code class="literal">DICT_ENTRY</code></td><td> 311 Identical to STRUCT. 312 </td><td> 313 8 314 </td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>32-bit unsigned integer in the message's byte 315 order. The actual file descriptors need to be 316 transferred out-of-band via some platform specific 317 mechanism. On the wire, values of this type store the index to the 318 file descriptor in the array of file descriptors that 319 accompany the message.</td><td>4</td></tr></tbody></table></div><p> 320 </p><div class="sect3" title="Valid Object Paths"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-object-path"></a>Valid Object Paths</h4></div></div></div><p> 321 An object path is a name used to refer to an object instance. 322 Conceptually, each participant in a D-Bus message exchange may have 323 any number of object instances (think of C++ or Java objects) and each 324 such instance will have a path. Like a filesystem, the object 325 instances in an application form a hierarchical tree. 326 </p><p> 327 The following rules define a valid object path. Implementations must 328 not send or accept messages with invalid object paths. 329 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 330 The path may be of any length. 331 </p></li><li class="listitem"><p> 332 The path must begin with an ASCII '/' (integer 47) character, 333 and must consist of elements separated by slash characters. 334 </p></li><li class="listitem"><p> 335 Each element must only contain the ASCII characters 336 "[A-Z][a-z][0-9]_" 337 </p></li><li class="listitem"><p> 338 No element may be the empty string. 339 </p></li><li class="listitem"><p> 340 Multiple '/' characters cannot occur in sequence. 341 </p></li><li class="listitem"><p> 342 A trailing '/' character is not allowed unless the 343 path is the root path (a single '/' character). 344 </p></li></ul></div><p> 345 </p><p> 346 Object paths are often namespaced by starting with a reversed 347 domain name and containing an interface version number, in the 348 same way as 349 <a class="link" href="#message-protocol-names-interface" title="Interface names">interface 350 names</a> and 351 <a class="link" href="#message-protocol-names-bus" title="Bus names">well-known 352 bus names</a>. 353 This makes it possible to implement more than one service, or 354 more than one version of a service, in the same process, 355 even if the services share a connection but cannot otherwise 356 co-operate (for instance, if they are implemented by different 357 plugins). 358 </p><p> 359 For instance, if the owner of <code class="literal">example.com</code> is 360 developing a D-Bus API for a music player, they might use the 361 hierarchy of object paths that start with 362 <code class="literal">/com/example/MusicPlayer1</code> for its objects. 363 </p></div><div class="sect3" title="Valid Signatures"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-marshaling-signature"></a>Valid Signatures</h4></div></div></div><p> 364 An implementation must not send or accept invalid signatures. 365 Valid signatures will conform to the following rules: 366 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 367 The signature ends with a nul byte. 368 </p></li><li class="listitem"><p> 369 The signature is a list of single complete types. 370 Arrays must have element types, and structs must 371 have both open and close parentheses. 372 </p></li><li class="listitem"><p> 373 Only type codes and open and close parentheses are 374 allowed in the signature. The <code class="literal">STRUCT</code> type code 375 is not allowed in signatures, because parentheses 376 are used instead. 377 </p></li><li class="listitem"><p> 378 The maximum depth of container type nesting is 32 array type 379 codes and 32 open parentheses. This implies that the maximum 380 total depth of recursion is 64, for an "array of array of array 381 of ... struct of struct of struct of ..." where there are 32 382 array and 32 struct. 383 </p></li><li class="listitem"><p> 384 The maximum length of a signature is 255. 385 </p></li><li class="listitem"><p> 386 Signatures must be nul-terminated. 387 </p></li></ul></div><p> 388 </p></div></div></div><div class="sect1" title="Message Protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="message-protocol"></a>Message Protocol</h2></div></div></div><p> 389 A <em class="firstterm">message</em> consists of a 390 <em class="firstterm">header</em> and a <em class="firstterm">body</em>. If you 391 think of a message as a package, the header is the address, and the body 392 contains the package contents. The message delivery system uses the header 393 information to figure out where to send the message and how to interpret 394 it; the recipient interprets the body of the message. 395 </p><p> 396 The body of the message is made up of zero or more 397 <em class="firstterm">arguments</em>, which are typed values, such as an 398 integer or a byte array. 399 </p><p> 400 Both header and body use the D-Bus <a class="link" href="#type-system" title="Type System">type 401 system</a> and format for serializing data. 402 </p><div class="sect2" title="Message Format"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-messages"></a>Message Format</h3></div></div></div><p> 403 A message consists of a header and a body. The header is a block of 404 values with a fixed signature and meaning. The body is a separate block 405 of values, with a signature specified in the header. 406 </p><p> 407 The length of the header must be a multiple of 8, allowing the body to 408 begin on an 8-byte boundary when storing the entire message in a single 409 buffer. If the header does not naturally end on an 8-byte boundary 410 up to 7 bytes of nul-initialized alignment padding must be added. 411 </p><p> 412 The message body need not end on an 8-byte boundary. 413 </p><p> 414 The maximum length of a message, including header, header alignment padding, 415 and body is 2 to the 27th power or 134217728. Implementations must not 416 send or accept messages exceeding this size. 417 </p><p> 418 The signature of the header is: 419 </p><pre class="programlisting"> 420 "yyyyuua(yv)" 421 </pre><p> 422 Written out more readably, this is: 423 </p><pre class="programlisting"> 424 BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT) 425 </pre><p> 426 </p><p> 427 These values have the following meanings: 428 </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>1st <code class="literal">BYTE</code></td><td>Endianness flag; ASCII 'l' for little-endian 429 or ASCII 'B' for big-endian. Both header and body are 430 in this endianness.</td></tr><tr><td>2nd <code class="literal">BYTE</code></td><td><em class="firstterm">Message type</em>. Unknown types must be ignored. 431 Currently-defined types are described below. 432 </td></tr><tr><td>3rd <code class="literal">BYTE</code></td><td>Bitwise OR of flags. Unknown flags 433 must be ignored. Currently-defined flags are described below. 434 </td></tr><tr><td>4th <code class="literal">BYTE</code></td><td>Major protocol version of the sending application. If 435 the major protocol version of the receiving application does not 436 match, the applications will not be able to communicate and the 437 D-Bus connection must be disconnected. The major protocol 438 version for this version of the specification is 1. 439 </td></tr><tr><td>1st <code class="literal">UINT32</code></td><td>Length in bytes of the message body, starting 440 from the end of the header. The header ends after 441 its alignment padding to an 8-boundary. 442 </td></tr><tr><td>2nd <code class="literal">UINT32</code></td><td>The serial of this message, used as a cookie 443 by the sender to identify the reply corresponding 444 to this request. This must not be zero. 445 </td></tr><tr><td><code class="literal">ARRAY</code> of <code class="literal">STRUCT</code> of (<code class="literal">BYTE</code>,<code class="literal">VARIANT</code>)</td><td>An array of zero or more <em class="firstterm">header 446 fields</em> where the byte is the field code, and the 447 variant is the field value. The message type determines 448 which fields are required. 449 </td></tr></tbody></table></div><p> 450 </p><p> 451 <em class="firstterm">Message types</em> that can appear in the second byte 452 of the header are: 453 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional name</th><th>Decimal value</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">INVALID</code></td><td>0</td><td>This is an invalid type.</td></tr><tr><td><code class="literal">METHOD_CALL</code></td><td>1</td><td>Method call.</td></tr><tr><td><code class="literal">METHOD_RETURN</code></td><td>2</td><td>Method reply with returned data.</td></tr><tr><td><code class="literal">ERROR</code></td><td>3</td><td>Error reply. If the first argument exists and is a 454 string, it is an error message.</td></tr><tr><td><code class="literal">SIGNAL</code></td><td>4</td><td>Signal emission.</td></tr></tbody></table></div><p> 455 </p><p> 456 Flags that can appear in the third byte of the header: 457 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional name</th><th>Hex value</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">NO_REPLY_EXPECTED</code></td><td>0x1</td><td>This message does not expect method return replies or 458 error replies; the reply can be omitted as an 459 optimization. However, it is compliant with this specification 460 to return the reply despite this flag and the only harm 461 from doing so is extra network traffic. 462 </td></tr><tr><td><code class="literal">NO_AUTO_START</code></td><td>0x2</td><td>The bus must not launch an owner 463 for the destination name in response to this message. 464 </td></tr></tbody></table></div><p> 465 </p><div class="sect3" title="Header Fields"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-header-fields"></a>Header Fields</h4></div></div></div><p> 466 The array at the end of the header contains <em class="firstterm">header 467 fields</em>, where each field is a 1-byte field code followed 468 by a field value. A header must contain the required header fields for 469 its message type, and zero or more of any optional header 470 fields. Future versions of this protocol specification may add new 471 fields. Implementations must ignore fields they do not 472 understand. Implementations must not invent their own header fields; 473 only changes to this specification may introduce new header fields. 474 </p><p> 475 Again, if an implementation sees a header field code that it does not 476 expect, it must ignore that field, as it will be part of a new 477 (but compatible) version of this specification. This also applies 478 to known header fields appearing in unexpected messages, for 479 example: if a signal has a reply serial it must be ignored 480 even though it has no meaning as of this version of the spec. 481 </p><p> 482 However, implementations must not send or accept known header fields 483 with the wrong type stored in the field value. So for example a 484 message with an <code class="literal">INTERFACE</code> field of type 485 <code class="literal">UINT32</code> would be considered corrupt. 486 </p><p> 487 Here are the currently-defined header fields: 488 </p><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Decimal Code</th><th>Type</th><th>Required In</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">INVALID</code></td><td>0</td><td>N/A</td><td>not allowed</td><td>Not a valid field name (error if it appears in a message)</td></tr><tr><td><code class="literal">PATH</code></td><td>1</td><td><code class="literal">OBJECT_PATH</code></td><td><code class="literal">METHOD_CALL</code>, <code class="literal">SIGNAL</code></td><td>The object to send a call to, 489 or the object a signal is emitted from. 490 The special path 491 <code class="literal">/org/freedesktop/DBus/Local</code> is reserved; 492 implementations should not send messages with this path, 493 and the reference implementation of the bus daemon will 494 disconnect any application that attempts to do so. 495 </td></tr><tr><td><code class="literal">INTERFACE</code></td><td>2</td><td><code class="literal">STRING</code></td><td><code class="literal">SIGNAL</code></td><td> 496 The interface to invoke a method call on, or 497 that a signal is emitted from. Optional for 498 method calls, required for signals. 499 The special interface 500 <code class="literal">org.freedesktop.DBus.Local</code> is reserved; 501 implementations should not send messages with this 502 interface, and the reference implementation of the bus 503 daemon will disconnect any application that attempts to 504 do so. 505 </td></tr><tr><td><code class="literal">MEMBER</code></td><td>3</td><td><code class="literal">STRING</code></td><td><code class="literal">METHOD_CALL</code>, <code class="literal">SIGNAL</code></td><td>The member, either the method name or signal name.</td></tr><tr><td><code class="literal">ERROR_NAME</code></td><td>4</td><td><code class="literal">STRING</code></td><td><code class="literal">ERROR</code></td><td>The name of the error that occurred, for errors</td></tr><tr><td><code class="literal">REPLY_SERIAL</code></td><td>5</td><td><code class="literal">UINT32</code></td><td><code class="literal">ERROR</code>, <code class="literal">METHOD_RETURN</code></td><td>The serial number of the message this message is a reply 506 to. (The serial number is the second <code class="literal">UINT32</code> in the header.)</td></tr><tr><td><code class="literal">DESTINATION</code></td><td>6</td><td><code class="literal">STRING</code></td><td>optional</td><td>The name of the connection this message is intended for. 507 Only used in combination with the message bus, see 508 <a class="xref" href="#message-bus" title="Message Bus Specification">the section called “Message Bus Specification”</a>.</td></tr><tr><td><code class="literal">SENDER</code></td><td>7</td><td><code class="literal">STRING</code></td><td>optional</td><td>Unique name of the sending connection. 509 The message bus fills in this field so it is reliable; the field is 510 only meaningful in combination with the message bus.</td></tr><tr><td><code class="literal">SIGNATURE</code></td><td>8</td><td><code class="literal">SIGNATURE</code></td><td>optional</td><td>The signature of the message body. 511 If omitted, it is assumed to be the 512 empty signature "" (i.e. the body must be 0-length).</td></tr><tr><td><code class="literal">UNIX_FDS</code></td><td>9</td><td><code class="literal">UINT32</code></td><td>optional</td><td>The number of Unix file descriptors that 513 accompany the message. If omitted, it is assumed 514 that no Unix file descriptors accompany the 515 message. The actual file descriptors need to be 516 transferred via platform specific mechanism 517 out-of-band. They must be sent at the same time as 518 part of the message itself. They may not be sent 519 before the first byte of the message itself is 520 transferred or after the last byte of the message 521 itself.</td></tr></tbody></table></div><p> 522 </p></div></div><div class="sect2" title="Valid Names"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-names"></a>Valid Names</h3></div></div></div><p> 523 The various names in D-Bus messages have some restrictions. 524 </p><p> 525 There is a <em class="firstterm">maximum name length</em> 526 of 255 which applies to bus names, interfaces, and members. 527 </p><div class="sect3" title="Interface names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-interface"></a>Interface names</h4></div></div></div><p> 528 Interfaces have names with type <code class="literal">STRING</code>, meaning that 529 they must be valid UTF-8. However, there are also some 530 additional restrictions that apply to interface names 531 specifically: 532 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Interface names are composed of 1 or more elements separated by 533 a period ('.') character. All elements must contain at least 534 one character. 535 </p></li><li class="listitem"><p>Each element must only contain the ASCII characters 536 "[A-Z][a-z][0-9]_" and must not begin with a digit. 537 </p></li><li class="listitem"><p>Interface names must contain at least one '.' (period) 538 character (and thus at least two elements). 539 </p></li><li class="listitem"><p>Interface names must not begin with a '.' (period) character.</p></li><li class="listitem"><p>Interface names must not exceed the maximum name length.</p></li></ul></div><p> 540 </p><p> 541 Interface names should start with the reversed DNS domain name of 542 the author of the interface (in lower-case), like interface names 543 in Java. It is conventional for the rest of the interface name 544 to consist of words run together, with initial capital letters 545 on all words ("CamelCase"). Several levels of hierarchy can be used. 546 It is also a good idea to include the major version of the interface 547 in the name, and increment it if incompatible changes are made; 548 this way, a single object can implement several versions of an 549 interface in parallel, if necessary. 550 </p><p> 551 For instance, if the owner of <code class="literal">example.com</code> is 552 developing a D-Bus API for a music player, they might define 553 interfaces called <code class="literal">com.example.MusicPlayer1</code>, 554 <code class="literal">com.example.MusicPlayer1.Track</code> and 555 <code class="literal">com.example.MusicPlayer1.Seekable</code>. 556 </p><p> 557 D-Bus does not distinguish between the concepts that would be 558 called classes and interfaces in Java: either can be identified on 559 D-Bus by an interface name. 560 </p></div><div class="sect3" title="Bus names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-bus"></a>Bus names</h4></div></div></div><p> 561 Connections have one or more bus names associated with them. 562 A connection has exactly one bus name that is a <em class="firstterm">unique 563 connection name</em>. The unique connection name remains 564 with the connection for its entire lifetime. 565 A bus name is of type <code class="literal">STRING</code>, 566 meaning that it must be valid UTF-8. However, there are also 567 some additional restrictions that apply to bus names 568 specifically: 569 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bus names that start with a colon (':') 570 character are unique connection names. Other bus names 571 are called <em class="firstterm">well-known bus names</em>. 572 </p></li><li class="listitem"><p>Bus names are composed of 1 or more elements separated by 573 a period ('.') character. All elements must contain at least 574 one character. 575 </p></li><li class="listitem"><p>Each element must only contain the ASCII characters 576 "[A-Z][a-z][0-9]_-". Only elements that are part of a unique 577 connection name may begin with a digit, elements in 578 other bus names must not begin with a digit. 579 </p></li><li class="listitem"><p>Bus names must contain at least one '.' (period) 580 character (and thus at least two elements). 581 </p></li><li class="listitem"><p>Bus names must not begin with a '.' (period) character.</p></li><li class="listitem"><p>Bus names must not exceed the maximum name length.</p></li></ul></div><p> 582 </p><p> 583 Note that the hyphen ('-') character is allowed in bus names but 584 not in interface names. 585 </p><p> 586 Like <a class="link" href="#message-protocol-names-interface" title="Interface names">interface 587 names</a>, well-known bus names should start with the 588 reversed DNS domain name of the author of the interface (in 589 lower-case), and it is conventional for the rest of the well-known 590 bus name to consist of words run together, with initial 591 capital letters. As with interface names, including a version 592 number in well-known bus names is a good idea; it's possible to 593 have the well-known bus name for more than one version 594 simultaneously if backwards compatibility is required. 595 </p><p> 596 If a well-known bus name implies the presence of a "main" interface, 597 that "main" interface is often given the same name as 598 the well-known bus name, and situated at the corresponding object 599 path. For instance, if the owner of <code class="literal">example.com</code> 600 is developing a D-Bus API for a music player, they might define 601 that any application that takes the well-known name 602 <code class="literal">com.example.MusicPlayer1</code> should have an object 603 at the object path <code class="literal">/com/example/MusicPlayer1</code> 604 which implements the interface 605 <code class="literal">com.example.MusicPlayer1</code>. 606 </p></div><div class="sect3" title="Member names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-member"></a>Member names</h4></div></div></div><p> 607 Member (i.e. method or signal) names: 608 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Must only contain the ASCII characters 609 "[A-Z][a-z][0-9]_" and may not begin with a 610 digit.</p></li><li class="listitem"><p>Must not contain the '.' (period) character.</p></li><li class="listitem"><p>Must not exceed the maximum name length.</p></li><li class="listitem"><p>Must be at least 1 byte in length.</p></li></ul></div><p> 611 </p><p> 612 It is conventional for member names on D-Bus to consist of 613 capitalized words with no punctuation ("camel-case"). 614 Method names should usually be verbs, such as 615 <code class="literal">GetItems</code>, and signal names should usually be 616 a description of an event, such as <code class="literal">ItemsChanged</code>. 617 </p></div><div class="sect3" title="Error names"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-names-error"></a>Error names</h4></div></div></div><p> 618 Error names have the same restrictions as interface names. 619 </p><p> 620 Error names have the same naming conventions as interface 621 names, and often contain <code class="literal">.Error.</code>; for instance, 622 the owner of <code class="literal">example.com</code> might define the 623 errors <code class="literal">com.example.MusicPlayer.Error.FileNotFound</code> 624 and <code class="literal">com.example.MusicPlayer.Error.OutOfMemory</code>. 625 The errors defined by D-Bus itself, such as 626 <code class="literal">org.freedesktop.DBus.Error.Failed</code>, follow a 627 similar pattern. 628 </p></div></div><div class="sect2" title="Message Types"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-types"></a>Message Types</h3></div></div></div><p> 629 Each of the message types (<code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>, <code class="literal">ERROR</code>, and 630 <code class="literal">SIGNAL</code>) has its own expected usage conventions and header fields. 631 This section describes these conventions. 632 </p><div class="sect3" title="Method Calls"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-method"></a>Method Calls</h4></div></div></div><p> 633 Some messages invoke an operation on a remote object. These are 634 called method call messages and have the type tag <code class="literal">METHOD_CALL</code>. Such 635 messages map naturally to methods on objects in a typical program. 636 </p><p> 637 A method call message is required to have a <code class="literal">MEMBER</code> header field 638 indicating the name of the method. Optionally, the message has an 639 <code class="literal">INTERFACE</code> field giving the interface the method is a part of. In the 640 absence of an <code class="literal">INTERFACE</code> field, if two interfaces on the same object have 641 a method with the same name, it is undefined which of the two methods 642 will be invoked. Implementations may also choose to return an error in 643 this ambiguous case. However, if a method name is unique 644 implementations must not require an interface field. 645 </p><p> 646 Method call messages also include a <code class="literal">PATH</code> field 647 indicating the object to invoke the method on. If the call is passing 648 through a message bus, the message will also have a 649 <code class="literal">DESTINATION</code> field giving the name of the connection 650 to receive the message. 651 </p><p> 652 When an application handles a method call message, it is required to 653 return a reply. The reply is identified by a <code class="literal">REPLY_SERIAL</code> header field 654 indicating the serial number of the <code class="literal">METHOD_CALL</code> being replied to. The 655 reply can have one of two types; either <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code>. 656 </p><p> 657 If the reply has type <code class="literal">METHOD_RETURN</code>, the arguments to the reply message 658 are the return value(s) or "out parameters" of the method call. 659 If the reply has type <code class="literal">ERROR</code>, then an "exception" has been thrown, 660 and the call fails; no return value will be provided. It makes 661 no sense to send multiple replies to the same method call. 662 </p><p> 663 Even if a method call has no return values, a <code class="literal">METHOD_RETURN</code> 664 reply is required, so the caller will know the method 665 was successfully processed. 666 </p><p> 667 The <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code> reply message must have the <code class="literal">REPLY_SERIAL</code> 668 header field. 669 </p><p> 670 If a <code class="literal">METHOD_CALL</code> message has the flag <code class="literal">NO_REPLY_EXPECTED</code>, 671 then as an optimization the application receiving the method 672 call may choose to omit the reply message (regardless of 673 whether the reply would have been <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code>). 674 However, it is also acceptable to ignore the <code class="literal">NO_REPLY_EXPECTED</code> 675 flag and reply anyway. 676 </p><p> 677 Unless a message has the flag <code class="literal">NO_AUTO_START</code>, if the 678 destination name does not exist then a program to own the destination 679 name will be started before the message is delivered. The message 680 will be held until the new program is successfully started or has 681 failed to start; in case of failure, an error will be returned. This 682 flag is only relevant in the context of a message bus, it is ignored 683 during one-to-one communication with no intermediate bus. 684 </p><div class="sect4" title="Mapping method calls to native APIs"><div class="titlepage"><div><div><h5 class="title"><a name="message-protocol-types-method-apis"></a>Mapping method calls to native APIs</h5></div></div></div><p> 685 APIs for D-Bus may map method calls to a method call in a specific 686 programming language, such as C++, or may map a method call written 687 in an IDL to a D-Bus message. 688 </p><p> 689 In APIs of this nature, arguments to a method are often termed "in" 690 (which implies sent in the <code class="literal">METHOD_CALL</code>), or "out" (which implies 691 returned in the <code class="literal">METHOD_RETURN</code>). Some APIs such as CORBA also have 692 "inout" arguments, which are both sent and received, i.e. the caller 693 passes in a value which is modified. Mapped to D-Bus, an "inout" 694 argument is equivalent to an "in" argument, followed by an "out" 695 argument. You can't pass things "by reference" over the wire, so 696 "inout" is purely an illusion of the in-process API. 697 </p><p> 698 Given a method with zero or one return values, followed by zero or more 699 arguments, where each argument may be "in", "out", or "inout", the 700 caller constructs a message by appending each "in" or "inout" argument, 701 in order. "out" arguments are not represented in the caller's message. 702 </p><p> 703 The recipient constructs a reply by appending first the return value 704 if any, then each "out" or "inout" argument, in order. 705 "in" arguments are not represented in the reply message. 706 </p><p> 707 Error replies are normally mapped to exceptions in languages that have 708 exceptions. 709 </p><p> 710 In converting from native APIs to D-Bus, it is perhaps nice to 711 map D-Bus naming conventions ("FooBar") to native conventions 712 such as "fooBar" or "foo_bar" automatically. This is OK 713 as long as you can say that the native API is one that 714 was specifically written for D-Bus. It makes the most sense 715 when writing object implementations that will be exported 716 over the bus. Object proxies used to invoke remote D-Bus 717 objects probably need the ability to call any D-Bus method, 718 and thus a magic name mapping like this could be a problem. 719 </p><p> 720 This specification doesn't require anything of native API bindings; 721 the preceding is only a suggested convention for consistency 722 among bindings. 723 </p></div></div><div class="sect3" title="Signal Emission"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-signal"></a>Signal Emission</h4></div></div></div><p> 724 Unlike method calls, signal emissions have no replies. 725 A signal emission is simply a single message of type <code class="literal">SIGNAL</code>. 726 It must have three header fields: <code class="literal">PATH</code> giving the object 727 the signal was emitted from, plus <code class="literal">INTERFACE</code> and <code class="literal">MEMBER</code> giving 728 the fully-qualified name of the signal. The <code class="literal">INTERFACE</code> header is required 729 for signals, though it is optional for method calls. 730 </p></div><div class="sect3" title="Errors"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-errors"></a>Errors</h4></div></div></div><p> 731 Messages of type <code class="literal">ERROR</code> are most commonly replies 732 to a <code class="literal">METHOD_CALL</code>, but may be returned in reply 733 to any kind of message. The message bus for example 734 will return an <code class="literal">ERROR</code> in reply to a signal emission if 735 the bus does not have enough memory to send the signal. 736 </p><p> 737 An <code class="literal">ERROR</code> may have any arguments, but if the first 738 argument is a <code class="literal">STRING</code>, it must be an error message. 739 The error message may be logged or shown to the user 740 in some way. 741 </p></div><div class="sect3" title="Notation in this document"><div class="titlepage"><div><div><h4 class="title"><a name="message-protocol-types-notation"></a>Notation in this document</h4></div></div></div><p> 742 This document uses a simple pseudo-IDL to describe particular method 743 calls and signals. Here is an example of a method call: 744 </p><pre class="programlisting"> 745 org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags, 746 out UINT32 resultcode) 747 </pre><p> 748 This means <code class="literal">INTERFACE</code> = org.freedesktop.DBus, <code class="literal">MEMBER</code> = StartServiceByName, 749 <code class="literal">METHOD_CALL</code> arguments are <code class="literal">STRING</code> and <code class="literal">UINT32</code>, <code class="literal">METHOD_RETURN</code> argument 750 is <code class="literal">UINT32</code>. Remember that the <code class="literal">MEMBER</code> field can't contain any '.' (period) 751 characters so it's known that the last part of the name in 752 the "IDL" is the member name. 753 </p><p> 754 In C++ that might end up looking like this: 755 </p><pre class="programlisting"> 756 unsigned int org::freedesktop::DBus::StartServiceByName (const char *name, 757 unsigned int flags); 758 </pre><p> 759 or equally valid, the return value could be done as an argument: 760 </p><pre class="programlisting"> 761 void org::freedesktop::DBus::StartServiceByName (const char *name, 762 unsigned int flags, 763 unsigned int *resultcode); 764 </pre><p> 765 It's really up to the API designer how they want to make 766 this look. You could design an API where the namespace wasn't used 767 in C++, using STL or Qt, using varargs, or whatever you wanted. 768 </p><p> 769 Signals are written as follows: 770 </p><pre class="programlisting"> 771 org.freedesktop.DBus.NameLost (STRING name) 772 </pre><p> 773 Signals don't specify "in" vs. "out" because only 774 a single direction is possible. 775 </p><p> 776 It isn't especially encouraged to use this lame pseudo-IDL in actual 777 API implementations; you might use the native notation for the 778 language you're using, or you might use COM or CORBA IDL, for example. 779 </p></div></div><div class="sect2" title="Invalid Protocol and Spec Extensions"><div class="titlepage"><div><div><h3 class="title"><a name="message-protocol-handling-invalid"></a>Invalid Protocol and Spec Extensions</h3></div></div></div><p> 780 For security reasons, the D-Bus protocol should be strictly parsed and 781 validated, with the exception of defined extension points. Any invalid 782 protocol or spec violations should result in immediately dropping the 783 connection without notice to the other end. Exceptions should be 784 carefully considered, e.g. an exception may be warranted for a 785 well-understood idiosyncrasy of a widely-deployed implementation. In 786 cases where the other end of a connection is 100% trusted and known to 787 be friendly, skipping validation for performance reasons could also make 788 sense in certain cases. 789 </p><p> 790 Generally speaking violations of the "must" requirements in this spec 791 should be considered possible attempts to exploit security, and violations 792 of the "should" suggestions should be considered legitimate (though perhaps 793 they should generate an error in some cases). 794 </p><p> 795 The following extension points are built in to D-Bus on purpose and must 796 not be treated as invalid protocol. The extension points are intended 797 for use by future versions of this spec, they are not intended for third 798 parties. At the moment, the only way a third party could extend D-Bus 799 without breaking interoperability would be to introduce a way to negotiate new 800 feature support as part of the auth protocol, using EXTENSION_-prefixed 801 commands. There is not yet a standard way to negotiate features. 802 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 803 In the authentication protocol (see <a class="xref" href="#auth-protocol" title="Authentication Protocol">the section called “Authentication Protocol”</a>) unknown 804 commands result in an ERROR rather than a disconnect. This enables 805 future extensions to the protocol. Commands starting with EXTENSION_ are 806 reserved for third parties. 807 </p></li><li class="listitem"><p> 808 The authentication protocol supports pluggable auth mechanisms. 809 </p></li><li class="listitem"><p> 810 The address format (see <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>) supports new 811 kinds of transport. 812 </p></li><li class="listitem"><p> 813 Messages with an unknown type (something other than 814 <code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>, 815 <code class="literal">ERROR</code>, <code class="literal">SIGNAL</code>) are ignored. 816 Unknown-type messages must still be well-formed in the same way 817 as the known messages, however. They still have the normal 818 header and body. 819 </p></li><li class="listitem"><p> 820 Header fields with an unknown or unexpected field code must be ignored, 821 though again they must still be well-formed. 822 </p></li><li class="listitem"><p> 823 New standard interfaces (with new methods and signals) can of course be added. 824 </p></li></ul></div><p> 825 </p></div></div><div class="sect1" title="Authentication Protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="auth-protocol"></a>Authentication Protocol</h2></div></div></div><p> 826 Before the flow of messages begins, two applications must 827 authenticate. A simple plain-text protocol is used for 828 authentication; this protocol is a SASL profile, and maps fairly 829 directly from the SASL specification. The message encoding is 830 NOT used here, only plain text messages. 831 </p><p> 832 In examples, "C:" and "S:" indicate lines sent by the client and 833 server respectively. 834 </p><div class="sect2" title="Protocol Overview"><div class="titlepage"><div><div><h3 class="title"><a name="auth-protocol-overview"></a>Protocol Overview</h3></div></div></div><p> 835 The protocol is a line-based protocol, where each line ends with 836 \r\n. Each line begins with an all-caps ASCII command name containing 837 only the character range [A-Z_], a space, then any arguments for the 838 command, then the \r\n ending the line. The protocol is 839 case-sensitive. All bytes must be in the ASCII character set. 840 841 Commands from the client to the server are as follows: 842 843 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>AUTH [mechanism] [initial-response]</p></li><li class="listitem"><p>CANCEL</p></li><li class="listitem"><p>BEGIN</p></li><li class="listitem"><p>DATA <data in hex encoding></p></li><li class="listitem"><p>ERROR [human-readable error explanation]</p></li><li class="listitem"><p>NEGOTIATE_UNIX_FD</p></li></ul></div><p> 844 845 From server to client are as follows: 846 847 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>REJECTED <space-separated list of mechanism names></p></li><li class="listitem"><p>OK <GUID in hex></p></li><li class="listitem"><p>DATA <data in hex encoding></p></li><li class="listitem"><p>ERROR</p></li><li class="listitem"><p>AGREE_UNIX_FD</p></li></ul></div><p> 848 </p><p> 849 Unofficial extensions to the command set must begin with the letters 850 "EXTENSION_", to avoid conflicts with future official commands. 851 For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF". 852 </p></div><div class="sect2" title="Special credentials-passing nul byte"><div class="titlepage"><div><div><h3 class="title"><a name="auth-nul-byte"></a>Special credentials-passing nul byte</h3></div></div></div><p> 853 Immediately after connecting to the server, the client must send a 854 single nul byte. This byte may be accompanied by credentials 855 information on some operating systems that use sendmsg() with 856 SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain 857 sockets. However, the nul byte must be sent even on other kinds of 858 socket, and even on operating systems that do not require a byte to be 859 sent in order to transmit credentials. The text protocol described in 860 this document begins after the single nul byte. If the first byte 861 received from the client is not a nul byte, the server may disconnect 862 that client. 863 </p><p> 864 A nul byte in any context other than the initial byte is an error; 865 the protocol is ASCII-only. 866 </p><p> 867 The credentials sent along with the nul byte may be used with the 868 SASL mechanism EXTERNAL. 869 </p></div><div class="sect2" title="AUTH command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-auth"></a>AUTH command</h3></div></div></div><p> 870 If an AUTH command has no arguments, it is a request to list 871 available mechanisms. The server must respond with a REJECTED 872 command listing the mechanisms it understands, or with an error. 873 </p><p> 874 If an AUTH command specifies a mechanism, and the server supports 875 said mechanism, the server should begin exchanging SASL 876 challenge-response data with the client using DATA commands. 877 </p><p> 878 If the server does not support the mechanism given in the AUTH 879 command, it must send either a REJECTED command listing the mechanisms 880 it does support, or an error. 881 </p><p> 882 If the [initial-response] argument is provided, it is intended for use 883 with mechanisms that have no initial challenge (or an empty initial 884 challenge), as if it were the argument to an initial DATA command. If 885 the selected mechanism has an initial challenge and [initial-response] 886 was provided, the server should reject authentication by sending 887 REJECTED. 888 </p><p> 889 If authentication succeeds after exchanging DATA commands, 890 an OK command must be sent to the client. 891 </p><p> 892 The first octet received by the server after the \r\n of the BEGIN 893 command from the client must be the first octet of the 894 authenticated/encrypted stream of D-Bus messages. 895 </p><p> 896 If BEGIN is received by the server, the first octet received 897 by the client after the \r\n of the OK command must be the 898 first octet of the authenticated/encrypted stream of D-Bus 899 messages. 900 </p></div><div class="sect2" title="CANCEL Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-cancel"></a>CANCEL Command</h3></div></div></div><p> 901 At any time up to sending the BEGIN command, the client may send a 902 CANCEL command. On receiving the CANCEL command, the server must 903 send a REJECTED command and abort the current authentication 904 exchange. 905 </p></div><div class="sect2" title="DATA Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-data"></a>DATA Command</h3></div></div></div><p> 906 The DATA command may come from either client or server, and simply 907 contains a hex-encoded block of data to be interpreted 908 according to the SASL mechanism in use. 909 </p><p> 910 Some SASL mechanisms support sending an "empty string"; 911 FIXME we need some way to do this. 912 </p></div><div class="sect2" title="BEGIN Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-begin"></a>BEGIN Command</h3></div></div></div><p> 913 The BEGIN command acknowledges that the client has received an 914 OK command from the server, and that the stream of messages 915 is about to begin. 916 </p><p> 917 The first octet received by the server after the \r\n of the BEGIN 918 command from the client must be the first octet of the 919 authenticated/encrypted stream of D-Bus messages. 920 </p></div><div class="sect2" title="REJECTED Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-rejected"></a>REJECTED Command</h3></div></div></div><p> 921 The REJECTED command indicates that the current authentication 922 exchange has failed, and further exchange of DATA is inappropriate. 923 The client would normally try another mechanism, or try providing 924 different responses to challenges. 925 </p><p> 926 Optionally, the REJECTED command has a space-separated list of 927 available auth mechanisms as arguments. If a server ever provides 928 a list of supported mechanisms, it must provide the same list 929 each time it sends a REJECTED message. Clients are free to 930 ignore all lists received after the first. 931 </p></div><div class="sect2" title="OK Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-ok"></a>OK Command</h3></div></div></div><p> 932 The OK command indicates that the client has been 933 authenticated. The client may now proceed with negotiating 934 Unix file descriptor passing. To do that it shall send 935 NEGOTIATE_UNIX_FD to the server. 936 </p><p> 937 Otherwise, the client must respond to the OK command by 938 sending a BEGIN command, followed by its stream of messages, 939 or by disconnecting. The server must not accept additional 940 commands using this protocol after the BEGIN command has been 941 received. Further communication will be a stream of D-Bus 942 messages (optionally encrypted, as negotiated) rather than 943 this protocol. 944 </p><p> 945 If a client sends BEGIN the first octet received by the client 946 after the \r\n of the OK command must be the first octet of 947 the authenticated/encrypted stream of D-Bus messages. 948 </p><p> 949 The OK command has one argument, which is the GUID of the server. 950 See <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a> for more on server GUIDs. 951 </p></div><div class="sect2" title="ERROR Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-error"></a>ERROR Command</h3></div></div></div><p> 952 The ERROR command indicates that either server or client did not 953 know a command, does not accept the given command in the current 954 context, or did not understand the arguments to the command. This 955 allows the protocol to be extended; a client or server can send a 956 command present or permitted only in new protocol versions, and if 957 an ERROR is received instead of an appropriate response, fall back 958 to using some other technique. 959 </p><p> 960 If an ERROR is sent, the server or client that sent the 961 error must continue as if the command causing the ERROR had never been 962 received. However, the the server or client receiving the error 963 should try something other than whatever caused the error; 964 if only canceling/rejecting the authentication. 965 </p><p> 966 If the D-Bus protocol changes incompatibly at some future time, 967 applications implementing the new protocol would probably be able to 968 check for support of the new protocol by sending a new command and 969 receiving an ERROR from applications that don't understand it. Thus the 970 ERROR feature of the auth protocol is an escape hatch that lets us 971 negotiate extensions or changes to the D-Bus protocol in the future. 972 </p></div><div class="sect2" title="NEGOTIATE_UNIX_FD Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-negotiate-unix-fd"></a>NEGOTIATE_UNIX_FD Command</h3></div></div></div><p> 973 The NEGOTIATE_UNIX_FD command indicates that the client 974 supports Unix file descriptor passing. This command may only 975 be sent after the connection is authenticated, i.e. after OK 976 was received by the client. This command may only be sent on 977 transports that support Unix file descriptor passing. 978 </p><p> 979 On receiving NEGOTIATE_UNIX_FD the server must respond with 980 either AGREE_UNIX_FD or ERROR. It shall respond the former if 981 the transport chosen supports Unix file descriptor passing and 982 the server supports this feature. It shall respond the latter 983 if the transport does not support Unix file descriptor 984 passing, the server does not support this feature, or the 985 server decides not to enable file descriptor passing due to 986 security or other reasons. 987 </p></div><div class="sect2" title="AGREE_UNIX_FD Command"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-agree-unix-fd"></a>AGREE_UNIX_FD Command</h3></div></div></div><p> 988 The AGREE_UNIX_FD command indicates that the server supports 989 Unix file descriptor passing. This command may only be sent 990 after the connection is authenticated, and the client sent 991 NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This 992 command may only be sent on transports that support Unix file 993 descriptor passing. 994 </p><p> 995 On receiving AGREE_UNIX_FD the client must respond with BEGIN, 996 followed by its stream of messages, or by disconnecting. The 997 server must not accept additional commands using this protocol 998 after the BEGIN command has been received. Further 999 communication will be a stream of D-Bus messages (optionally 1000 encrypted, as negotiated) rather than this protocol. 1001 </p></div><div class="sect2" title="Future Extensions"><div class="titlepage"><div><div><h3 class="title"><a name="auth-command-future"></a>Future Extensions</h3></div></div></div><p> 1002 Future extensions to the authentication and negotiation 1003 protocol are possible. For that new commands may be 1004 introduced. If a client or server receives an unknown command 1005 it shall respond with ERROR and not consider this fatal. New 1006 commands may be introduced both before, and after 1007 authentication, i.e. both before and after the OK command. 1008 </p></div><div class="sect2" title="Authentication examples"><div class="titlepage"><div><div><h3 class="title"><a name="auth-examples"></a>Authentication examples</h3></div></div></div><p> 1009 </p><div class="figure"><a name="idp5181008"></a><p class="title"><b>Figure�1.�Example of successful magic cookie authentication</b></p><div class="figure-contents"><pre class="programlisting"> 1010 (MAGIC_COOKIE is a made up mechanism) 1011 1012 C: AUTH MAGIC_COOKIE 3138363935333137393635383634 1013 S: OK 1234deadbeef 1014 C: BEGIN 1015 </pre></div></div><p><br class="figure-break"> 1016 </p><div class="figure"><a name="idp5182832"></a><p class="title"><b>Figure�2.�Example of finding out mechanisms then picking one</b></p><div class="figure-contents"><pre class="programlisting"> 1017 C: AUTH 1018 S: REJECTED KERBEROS_V4 SKEY 1019 C: AUTH SKEY 7ab83f32ee 1020 S: DATA 8799cabb2ea93e 1021 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f 1022 S: OK 1234deadbeef 1023 C: BEGIN 1024 </pre></div></div><p><br class="figure-break"> 1025 </p><div class="figure"><a name="idp5184736"></a><p class="title"><b>Figure�3.�Example of client sends unknown command then falls back to regular auth</b></p><div class="figure-contents"><pre class="programlisting"> 1026 C: FOOBAR 1027 S: ERROR 1028 C: AUTH MAGIC_COOKIE 3736343435313230333039 1029 S: OK 1234deadbeef 1030 C: BEGIN 1031 </pre></div></div><p><br class="figure-break"> 1032 </p><div class="figure"><a name="idp5186624"></a><p class="title"><b>Figure�4.�Example of server doesn't support initial auth mechanism</b></p><div class="figure-contents"><pre class="programlisting"> 1033 C: AUTH MAGIC_COOKIE 3736343435313230333039 1034 S: REJECTED KERBEROS_V4 SKEY 1035 C: AUTH SKEY 7ab83f32ee 1036 S: DATA 8799cabb2ea93e 1037 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f 1038 S: OK 1234deadbeef 1039 C: BEGIN 1040 </pre></div></div><p><br class="figure-break"> 1041 </p><div class="figure"><a name="idp5188640"></a><p class="title"><b>Figure�5.�Example of wrong password or the like followed by successful retry</b></p><div class="figure-contents"><pre class="programlisting"> 1042 C: AUTH MAGIC_COOKIE 3736343435313230333039 1043 S: REJECTED KERBEROS_V4 SKEY 1044 C: AUTH SKEY 7ab83f32ee 1045 S: DATA 8799cabb2ea93e 1046 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f 1047 S: REJECTED 1048 C: AUTH SKEY 7ab83f32ee 1049 S: DATA 8799cabb2ea93e 1050 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f 1051 S: OK 1234deadbeef 1052 C: BEGIN 1053 </pre></div></div><p><br class="figure-break"> 1054 </p><div class="figure"><a name="idp5190816"></a><p class="title"><b>Figure�6.�Example of skey cancelled and restarted</b></p><div class="figure-contents"><pre class="programlisting"> 1055 C: AUTH MAGIC_COOKIE 3736343435313230333039 1056 S: REJECTED KERBEROS_V4 SKEY 1057 C: AUTH SKEY 7ab83f32ee 1058 S: DATA 8799cabb2ea93e 1059 C: CANCEL 1060 S: REJECTED 1061 C: AUTH SKEY 7ab83f32ee 1062 S: DATA 8799cabb2ea93e 1063 C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f 1064 S: OK 1234deadbeef 1065 C: BEGIN 1066 </pre></div></div><p><br class="figure-break"> 1067 </p><div class="figure"><a name="idp5192880"></a><p class="title"><b>Figure�7.�Example of successful magic cookie authentication with successful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting"> 1068 (MAGIC_COOKIE is a made up mechanism) 1069 1070 C: AUTH MAGIC_COOKIE 3138363935333137393635383634 1071 S: OK 1234deadbeef 1072 C: NEGOTIATE_UNIX_FD 1073 S: AGREE_UNIX_FD 1074 C: BEGIN 1075 </pre></div></div><p><br class="figure-break"> 1076 </p><div class="figure"><a name="idp5194880"></a><p class="title"><b>Figure�8.�Example of successful magic cookie authentication with unsuccessful negotiation of Unix FD passing</b></p><div class="figure-contents"><pre class="programlisting"> 1077 (MAGIC_COOKIE is a made up mechanism) 1078 1079 C: AUTH MAGIC_COOKIE 3138363935333137393635383634 1080 S: OK 1234deadbeef 1081 C: NEGOTIATE_UNIX_FD 1082 S: ERROR 1083 C: BEGIN 1084 </pre></div></div><p><br class="figure-break"> 1085 </p></div><div class="sect2" title="Authentication state diagrams"><div class="titlepage"><div><div><h3 class="title"><a name="auth-states"></a>Authentication state diagrams</h3></div></div></div><p> 1086 This section documents the auth protocol in terms of 1087 a state machine for the client and the server. This is 1088 probably the most robust way to implement the protocol. 1089 </p><div class="sect3" title="Client states"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-client"></a>Client states</h4></div></div></div><p> 1090 To more precisely describe the interaction between the 1091 protocol state machine and the authentication mechanisms the 1092 following notation is used: MECH(CHALL) means that the 1093 server challenge CHALL was fed to the mechanism MECH, which 1094 returns one of 1095 1096 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1097 CONTINUE(RESP) means continue the auth conversation 1098 and send RESP as the response to the server; 1099 </p></li><li class="listitem"><p> 1100 OK(RESP) means that after sending RESP to the server 1101 the client side of the auth conversation is finished 1102 and the server should return "OK"; 1103 </p></li><li class="listitem"><p> 1104 ERROR means that CHALL was invalid and could not be 1105 processed. 1106 </p></li></ul></div><p> 1107 1108 Both RESP and CHALL may be empty. 1109 </p><p> 1110 The Client starts by getting an initial response from the 1111 default mechanism and sends AUTH MECH RESP, or AUTH MECH if 1112 the mechanism did not provide an initial response. If the 1113 mechanism returns CONTINUE, the client starts in state 1114 <span class="emphasis"><em>WaitingForData</em></span>, if the mechanism 1115 returns OK the client starts in state 1116 <span class="emphasis"><em>WaitingForOK</em></span>. 1117 </p><p> 1118 The client should keep track of available mechanisms and 1119 which it mechanisms it has already attempted. This list is 1120 used to decide which AUTH command to send. When the list is 1121 exhausted, the client should give up and close the 1122 connection. 1123 </p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>.�</b> 1124 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1125 Receive DATA CHALL 1126 </p><table border="0" summary="Simple list" class="simplelist"><tr><td> 1127 MECH(CHALL) returns CONTINUE(RESP) → send 1128 DATA RESP, goto 1129 <span class="emphasis"><em>WaitingForData</em></span> 1130 </td></tr><tr><td> 1131 MECH(CHALL) returns OK(RESP) → send DATA 1132 RESP, goto <span class="emphasis"><em>WaitingForOK</em></span> 1133 </td></tr><tr><td> 1134 MECH(CHALL) returns ERROR → send ERROR 1135 [msg], goto <span class="emphasis"><em>WaitingForData</em></span> 1136 </td></tr></table><p> 1137 </p></li><li class="listitem"><p> 1138 Receive REJECTED [mechs] → 1139 send AUTH [next mech], goto 1140 WaitingForData or <span class="emphasis"><em>WaitingForOK</em></span> 1141 </p></li><li class="listitem"><p> 1142 Receive ERROR → send 1143 CANCEL, goto 1144 <span class="emphasis"><em>WaitingForReject</em></span> 1145 </p></li><li class="listitem"><p> 1146 Receive OK → send 1147 BEGIN, terminate auth 1148 conversation, authenticated 1149 </p></li><li class="listitem"><p> 1150 Receive anything else → send 1151 ERROR, goto 1152 <span class="emphasis"><em>WaitingForData</em></span> 1153 </p></li></ul></div><p title="WaitingForData"> 1154 </p><p title="WaitingForOK"><b><span class="emphasis"><em>WaitingForOK</em></span>.�</b> 1155 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1156 Receive OK → send BEGIN, terminate auth 1157 conversation, <span class="emphasis"><em>authenticated</em></span> 1158 </p></li><li class="listitem"><p> 1159 Receive REJECT [mechs] → send AUTH [next mech], 1160 goto <span class="emphasis"><em>WaitingForData</em></span> or 1161 <span class="emphasis"><em>WaitingForOK</em></span> 1162 </p></li><li class="listitem"><p> 1163 Receive DATA → send CANCEL, goto 1164 <span class="emphasis"><em>WaitingForReject</em></span> 1165 </p></li><li class="listitem"><p> 1166 Receive ERROR → send CANCEL, goto 1167 <span class="emphasis"><em>WaitingForReject</em></span> 1168 </p></li><li class="listitem"><p> 1169 Receive anything else → send ERROR, goto 1170 <span class="emphasis"><em>WaitingForOK</em></span> 1171 </p></li></ul></div><p title="WaitingForOK"> 1172 </p><p title="WaitingForReject"><b><span class="emphasis"><em>WaitingForReject</em></span>.�</b> 1173 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1174 Receive REJECT [mechs] → send AUTH [next mech], 1175 goto <span class="emphasis"><em>WaitingForData</em></span> or 1176 <span class="emphasis"><em>WaitingForOK</em></span> 1177 </p></li><li class="listitem"><p> 1178 Receive anything else → terminate auth 1179 conversation, disconnect 1180 </p></li></ul></div><p title="WaitingForReject"> 1181 </p></div><div class="sect3" title="Server states"><div class="titlepage"><div><div><h4 class="title"><a name="auth-states-server"></a>Server states</h4></div></div></div><p> 1182 For the server MECH(RESP) means that the client response 1183 RESP was fed to the the mechanism MECH, which returns one of 1184 1185 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1186 CONTINUE(CHALL) means continue the auth conversation and 1187 send CHALL as the challenge to the client; 1188 </p></li><li class="listitem"><p> 1189 OK means that the client has been successfully 1190 authenticated; 1191 </p></li><li class="listitem"><p> 1192 REJECT means that the client failed to authenticate or 1193 there was an error in RESP. 1194 </p></li></ul></div><p> 1195 1196 The server starts out in state 1197 <span class="emphasis"><em>WaitingForAuth</em></span>. If the client is 1198 rejected too many times the server must disconnect the 1199 client. 1200 </p><p title="WaitingForAuth"><b><span class="emphasis"><em>WaitingForAuth</em></span>.�</b> 1201 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1202 Receive AUTH → send REJECTED [mechs], goto 1203 <span class="emphasis"><em>WaitingForAuth</em></span> 1204 </p></li><li class="listitem"><p> 1205 Receive AUTH MECH RESP 1206 1207 </p><table border="0" summary="Simple list" class="simplelist"><tr><td> 1208 MECH not valid mechanism → send REJECTED 1209 [mechs], goto 1210 <span class="emphasis"><em>WaitingForAuth</em></span> 1211 </td></tr><tr><td> 1212 MECH(RESP) returns CONTINUE(CHALL) → send 1213 DATA CHALL, goto 1214 <span class="emphasis"><em>WaitingForData</em></span> 1215 </td></tr><tr><td> 1216 MECH(RESP) returns OK → send OK, goto 1217 <span class="emphasis"><em>WaitingForBegin</em></span> 1218 </td></tr><tr><td> 1219 MECH(RESP) returns REJECT → send REJECTED 1220 [mechs], goto 1221 <span class="emphasis"><em>WaitingForAuth</em></span> 1222 </td></tr></table><p> 1223 </p></li><li class="listitem"><p> 1224 Receive BEGIN → terminate 1225 auth conversation, disconnect 1226 </p></li><li class="listitem"><p> 1227 Receive ERROR → send REJECTED [mechs], goto 1228 <span class="emphasis"><em>WaitingForAuth</em></span> 1229 </p></li><li class="listitem"><p> 1230 Receive anything else → send 1231 ERROR, goto 1232 <span class="emphasis"><em>WaitingForAuth</em></span> 1233 </p></li></ul></div><p title="WaitingForAuth"> 1234 </p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>.�</b> 1235 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1236 Receive DATA RESP 1237 </p><table border="0" summary="Simple list" class="simplelist"><tr><td> 1238 MECH(RESP) returns CONTINUE(CHALL) → send 1239 DATA CHALL, goto 1240 <span class="emphasis"><em>WaitingForData</em></span> 1241 </td></tr><tr><td> 1242 MECH(RESP) returns OK → send OK, goto 1243 <span class="emphasis"><em>WaitingForBegin</em></span> 1244 </td></tr><tr><td> 1245 MECH(RESP) returns REJECT → send REJECTED 1246 [mechs], goto 1247 <span class="emphasis"><em>WaitingForAuth</em></span> 1248 </td></tr></table><p> 1249 </p></li><li class="listitem"><p> 1250 Receive BEGIN → terminate auth conversation, 1251 disconnect 1252 </p></li><li class="listitem"><p> 1253 Receive CANCEL → send REJECTED [mechs], goto 1254 <span class="emphasis"><em>WaitingForAuth</em></span> 1255 </p></li><li class="listitem"><p> 1256 Receive ERROR → send REJECTED [mechs], goto 1257 <span class="emphasis"><em>WaitingForAuth</em></span> 1258 </p></li><li class="listitem"><p> 1259 Receive anything else → send ERROR, goto 1260 <span class="emphasis"><em>WaitingForData</em></span> 1261 </p></li></ul></div><p title="WaitingForData"> 1262 </p><p title="WaitingForBegin"><b><span class="emphasis"><em>WaitingForBegin</em></span>.�</b> 1263 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1264 Receive BEGIN → terminate auth conversation, 1265 client authenticated 1266 </p></li><li class="listitem"><p> 1267 Receive CANCEL → send REJECTED [mechs], goto 1268 <span class="emphasis"><em>WaitingForAuth</em></span> 1269 </p></li><li class="listitem"><p> 1270 Receive ERROR → send REJECTED [mechs], goto 1271 <span class="emphasis"><em>WaitingForAuth</em></span> 1272 </p></li><li class="listitem"><p> 1273 Receive anything else → send ERROR, goto 1274 <span class="emphasis"><em>WaitingForBegin</em></span> 1275 </p></li></ul></div><p title="WaitingForBegin"> 1276 </p></div></div><div class="sect2" title="Authentication mechanisms"><div class="titlepage"><div><div><h3 class="title"><a name="auth-mechanisms"></a>Authentication mechanisms</h3></div></div></div><p> 1277 This section describes some new authentication mechanisms. 1278 D-Bus also allows any standard SASL mechanism of course. 1279 </p><div class="sect3" title="DBUS_COOKIE_SHA1"><div class="titlepage"><div><div><h4 class="title"><a name="auth-mechanisms-sha"></a>DBUS_COOKIE_SHA1</h4></div></div></div><p> 1280 The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client 1281 has the ability to read a private file owned by the user being 1282 authenticated. If the client can prove that it has access to a secret 1283 cookie stored in this file, then the client is authenticated. 1284 Thus the security of DBUS_COOKIE_SHA1 depends on a secure home 1285 directory. 1286 </p><p> 1287 Throughout this description, "hex encoding" must output the digits 1288 from a to f in lower-case; the digits A to F must not be used 1289 in the DBUS_COOKIE_SHA1 mechanism. 1290 </p><p> 1291 Authentication proceeds as follows: 1292 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1293 The client sends the username it would like to authenticate 1294 as, hex-encoded. 1295 </p></li><li class="listitem"><p> 1296 The server sends the name of its "cookie context" (see below); a 1297 space character; the integer ID of the secret cookie the client 1298 must demonstrate knowledge of; a space character; then a 1299 randomly-generated challenge string, all of this hex-encoded into 1300 one, single string. 1301 </p></li><li class="listitem"><p> 1302 The client locates the cookie and generates its own 1303 randomly-generated challenge string. The client then concatenates 1304 the server's decoded challenge, a ":" character, its own challenge, 1305 another ":" character, and the cookie. It computes the SHA-1 hash 1306 of this composite string as a hex digest. It concatenates the 1307 client's challenge string, a space character, and the SHA-1 hex 1308 digest, hex-encodes the result and sends it back to the server. 1309 </p></li><li class="listitem"><p> 1310 The server generates the same concatenated string used by the 1311 client and computes its SHA-1 hash. It compares the hash with 1312 the hash received from the client; if the two hashes match, the 1313 client is authenticated. 1314 </p></li></ul></div><p> 1315 </p><p> 1316 Each server has a "cookie context," which is a name that identifies a 1317 set of cookies that apply to that server. A sample context might be 1318 "org_freedesktop_session_bus". Context names must be valid ASCII, 1319 nonzero length, and may not contain the characters slash ("/"), 1320 backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"), 1321 tab ("\t"), or period ("."). There is a default context, 1322 "org_freedesktop_general" that's used by servers that do not specify 1323 otherwise. 1324 </p><p> 1325 Cookies are stored in a user's home directory, in the directory 1326 <code class="filename">~/.dbus-keyrings/</code>. This directory must 1327 not be readable or writable by other users. If it is, 1328 clients and servers must ignore it. The directory 1329 contains cookie files named after the cookie context. 1330 </p><p> 1331 A cookie file contains one cookie per line. Each line 1332 has three space-separated fields: 1333 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1334 The cookie ID number, which must be a non-negative integer and 1335 may not be used twice in the same file. 1336 </p></li><li class="listitem"><p> 1337 The cookie's creation time, in UNIX seconds-since-the-epoch 1338 format. 1339 </p></li><li class="listitem"><p> 1340 The cookie itself, a hex-encoded random block of bytes. The cookie 1341 may be of any length, though obviously security increases 1342 as the length increases. 1343 </p></li></ul></div><p> 1344 </p><p> 1345 Only server processes modify the cookie file. 1346 They must do so with this procedure: 1347 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1348 Create a lockfile name by appending ".lock" to the name of the 1349 cookie file. The server should attempt to create this file 1350 using <code class="literal">O_CREAT | O_EXCL</code>. If file creation 1351 fails, the lock fails. Servers should retry for a reasonable 1352 period of time, then they may choose to delete an existing lock 1353 to keep users from having to manually delete a stale 1354 lock. <sup>[<a name="idp5281040" href="#ftn.idp5281040" class="footnote">1</a>]</sup> 1355 </p></li><li class="listitem"><p> 1356 Once the lockfile has been created, the server loads the cookie 1357 file. It should then delete any cookies that are old (the 1358 timeout can be fairly short), or more than a reasonable 1359 time in the future (so that cookies never accidentally 1360 become permanent, if the clock was set far into the future 1361 at some point). If no recent keys remain, the 1362 server may generate a new key. 1363 </p></li><li class="listitem"><p> 1364 The pruned and possibly added-to cookie file 1365 must be resaved atomically (using a temporary 1366 file which is rename()'d). 1367 </p></li><li class="listitem"><p> 1368 The lock must be dropped by deleting the lockfile. 1369 </p></li></ul></div><p> 1370 </p><p> 1371 Clients need not lock the file in order to load it, 1372 because servers are required to save the file atomically. 1373 </p></div></div></div><div class="sect1" title="Server Addresses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="addresses"></a>Server Addresses</h2></div></div></div><p> 1374 Server addresses consist of a transport name followed by a colon, and 1375 then an optional, comma-separated list of keys and values in the form key=value. 1376 Each value is escaped. 1377 </p><p> 1378 For example: 1379 </p><pre class="programlisting">unix:path=/tmp/dbus-test</pre><p> 1380 Which is the address to a unix socket with the path /tmp/dbus-test. 1381 </p><p> 1382 Value escaping is similar to URI escaping but simpler. 1383 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1384 The set of optionally-escaped bytes is: 1385 <code class="literal">[0-9A-Za-z_-/.\]</code>. To escape, each 1386 <span class="emphasis"><em>byte</em></span> (note, not character) which is not in the 1387 set of optionally-escaped bytes must be replaced with an ASCII 1388 percent (<code class="literal">%</code>) and the value of the byte in hex. 1389 The hex value must always be two digits, even if the first digit is 1390 zero. The optionally-escaped bytes may be escaped if desired. 1391 </p></li><li class="listitem"><p> 1392 To unescape, append each byte in the value; if a byte is an ASCII 1393 percent (<code class="literal">%</code>) character then append the following 1394 hex value instead. It is an error if a <code class="literal">%</code> byte 1395 does not have two hex digits following. It is an error if a 1396 non-optionally-escaped byte is seen unescaped. 1397 </p></li></ul></div><p> 1398 The set of optionally-escaped bytes is intended to preserve address 1399 readability and convenience. 1400 </p><p> 1401 A server may specify a key-value pair with the key <code class="literal">guid</code> 1402 and the value a hex-encoded 16-byte sequence. <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a> 1403 describes the format of the <code class="literal">guid</code> field. If present, 1404 this UUID may be used to distinguish one server address from another. A 1405 server should use a different UUID for each address it listens on. For 1406 example, if a message bus daemon offers both UNIX domain socket and TCP 1407 connections, but treats clients the same regardless of how they connect, 1408 those two connections are equivalent post-connection but should have 1409 distinct UUIDs to distinguish the kinds of connection. 1410 </p><p> 1411 The intent of the address UUID feature is to allow a client to avoid 1412 opening multiple identical connections to the same server, by allowing the 1413 client to check whether an address corresponds to an already-existing 1414 connection. Comparing two addresses is insufficient, because addresses 1415 can be recycled by distinct servers, and equivalent addresses may look 1416 different if simply compared as strings (for example, the host in a TCP 1417 address can be given as an IP address or as a hostname). 1418 </p><p> 1419 Note that the address key is <code class="literal">guid</code> even though the 1420 rest of the API and documentation says "UUID," for historical reasons. 1421 </p><p> 1422 [FIXME clarify if attempting to connect to each is a requirement 1423 or just a suggestion] 1424 When connecting to a server, multiple server addresses can be 1425 separated by a semi-colon. The library will then try to connect 1426 to the first address and if that fails, it'll try to connect to 1427 the next one specified, and so forth. For example 1428 </p><pre class="programlisting">unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</pre><p> 1429 </p></div><div class="sect1" title="Transports"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="transports"></a>Transports</h2></div></div></div><p> 1430 [FIXME we need to specify in detail each transport and its possible arguments] 1431 1432 Current transports include: unix domain sockets (including 1433 abstract namespace on linux), launchd, systemd, TCP/IP, an executed subprocess and a debug/testing transport 1434 using in-process pipes. Future possible transports include one that 1435 tunnels over X11 protocol. 1436 </p><div class="sect2" title="Unix Domain Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-unix-domain-sockets"></a>Unix Domain Sockets</h3></div></div></div><p> 1437 Unix domain sockets can be either paths in the file system or on Linux 1438 kernels, they can be abstract which are similar to paths but 1439 do not show up in the file system. 1440 </p><p> 1441 When a socket is opened by the D-Bus library it truncates the path 1442 name right before the first trailing Nul byte. This is true for both 1443 normal paths and abstract paths. Note that this is a departure from 1444 previous versions of D-Bus that would create sockets with a fixed 1445 length path name. Names which were shorter than the fixed length 1446 would be padded by Nul bytes. 1447 </p><p> 1448 Unix domain sockets are not available on Windows. 1449 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-unix-domain-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 1450 Unix domain socket addresses are identified by the "unix:" prefix 1451 and support the following key/value pairs: 1452 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td>(path)</td><td>path of the unix domain socket. If set, the "tmpdir" and "abstract" key must not be set.</td></tr><tr><td>tmpdir</td><td>(path)</td><td>temporary directory in which a socket file with a random file name starting with 'dbus-' will be created by the server. This key can only be used in server addresses, not in client addresses. If set, the "path" and "abstract" key must not be set.</td></tr><tr><td>abstract</td><td>(string)</td><td>unique string (path) in the abstract namespace. If set, the "path" or "tempdir" key must not be set.</td></tr></tbody></table></div></div></div><div class="sect2" title="launchd"><div class="titlepage"><div><div><h3 class="title"><a name="transports-launchd"></a>launchd</h3></div></div></div><p> 1453 launchd is an open-source server management system that replaces init, inetd 1454 and cron on Apple Mac OS X versions 10.4 and above. It provides a common session 1455 bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX. 1456 </p><p> 1457 launchd allocates a socket and provides it with the unix path through the 1458 DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process 1459 spawned by launchd (or dbus-daemon, if it was started by launchd) can access 1460 it through its environment. 1461 Other processes can query for the launchd socket by executing: 1462 $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET 1463 This is normally done by the D-Bus client library so doesn't have to be done 1464 manually. 1465 </p><p> 1466 launchd is not available on Microsoft Windows. 1467 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-launchd-addresses"></a>Server Address Format</h4></div></div></div><p> 1468 launchd addresses are identified by the "launchd:" prefix 1469 and support the following key/value pairs: 1470 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>env</td><td>(environment variable)</td><td>path of the unix domain socket for the launchd created dbus-daemon.</td></tr></tbody></table></div></div></div><div class="sect2" title="systemd"><div class="titlepage"><div><div><h3 class="title"><a name="transports-systemd"></a>systemd</h3></div></div></div><p> 1471 systemd is an open-source server management system that 1472 replaces init and inetd on newer Linux systems. It supports 1473 socket activation. The D-Bus systemd transport is used to acquire 1474 socket activation file descriptors from systemd and use them 1475 as D-Bus transport when the current process is spawned by 1476 socket activation from it. 1477 </p><p> 1478 The systemd transport accepts only one or more Unix domain or 1479 TCP streams sockets passed in via socket activation. 1480 </p><p> 1481 The systemd transport is not available on non-Linux operating systems. 1482 </p><p> 1483 The systemd transport defines no parameter keys. 1484 </p></div><div class="sect2" title="TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-tcp-sockets"></a>TCP Sockets</h3></div></div></div><p> 1485 The tcp transport provides TCP/IP based connections between clients 1486 located on the same or different hosts. 1487 </p><p> 1488 Using tcp transport without any additional secure authentification mechanismus 1489 over a network is unsecure. 1490 </p><p> 1491 Windows notes: Because of the tcp stack on Windows does not provide sending 1492 credentials over a tcp connection, the EXTERNAL authentification 1493 mechanismus does not work. 1494 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-tcp-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 1495 TCP/IP socket addresses are identified by the "tcp:" prefix 1496 and support the following key/value pairs: 1497 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>(string)</td><td>dns name or ip address</td></tr><tr><td>port</td><td>(number)</td><td>The tcp port the server will open. A zero value let the server 1498 choose a free port provided from the underlaying operating system. 1499 libdbus is able to retrieve the real used port from the server. 1500 </td></tr><tr><td>family</td><td>(string)</td><td>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</td></tr></tbody></table></div></div></div><div class="sect2" title="Nonce-secured TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-nonce-tcp-sockets"></a>Nonce-secured TCP Sockets</h3></div></div></div><p> 1501 The nonce-tcp transport provides a secured TCP transport, using a 1502 simple authentication mechanism to ensure that only clients with read 1503 access to a certain location in the filesystem can connect to the server. 1504 The server writes a secret, the nonce, to a file and an incoming client 1505 connection is only accepted if the client sends the nonce right after 1506 the connect. The nonce mechanism requires no setup and is orthogonal to 1507 the higher-level authentication mechanisms described in the 1508 Authentication section. 1509 </p><p> 1510 On start, the server generates a random 16 byte nonce and writes it 1511 to a file in the user's temporary directory. The nonce file location 1512 is published as part of the server's D-Bus address using the 1513 "noncefile" key-value pair. 1514 1515 After an accept, the server reads 16 bytes from the socket. If the 1516 read bytes do not match the nonce stored in the nonce file, the 1517 server MUST immediately drop the connection. 1518 If the nonce match the received byte sequence, the client is accepted 1519 and the transport behaves like an unsecured tcp transport. 1520 </p><p> 1521 After a successful connect to the server socket, the client MUST read 1522 the nonce from the file published by the server via the noncefile= 1523 key-value pair and send it over the socket. After that, the 1524 transport behaves like an unsecured tcp transport. 1525 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-nonce-tcp-sockets-addresses"></a>Server Address Format</h4></div></div></div><p> 1526 Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix 1527 and support the following key/value pairs: 1528 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>host</td><td>(string)</td><td>dns name or ip address</td></tr><tr><td>port</td><td>(number)</td><td>The tcp port the server will open. A zero value let the server 1529 choose a free port provided from the underlaying operating system. 1530 libdbus is able to retrieve the real used port from the server. 1531 </td></tr><tr><td>family</td><td>(string)</td><td>If set, provide the type of socket family either "ipv4" or "ipv6". If unset, the family is unspecified.</td></tr><tr><td>noncefile</td><td>(path)</td><td>file location containing the secret</td></tr></tbody></table></div></div></div><div class="sect2" title="Executed Subprocesses on Unix"><div class="titlepage"><div><div><h3 class="title"><a name="transports-exec"></a>Executed Subprocesses on Unix</h3></div></div></div><p> 1532 This transport forks off a process and connects its standard 1533 input and standard output with an anonymous Unix domain 1534 socket. This socket is then used for communication by the 1535 transport. This transport may be used to use out-of-process 1536 forwarder programs as basis for the D-Bus protocol. 1537 </p><p> 1538 The forked process will inherit the standard error output and 1539 process group from the parent process. 1540 </p><p> 1541 Executed subprocesses are not available on Windows. 1542 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="transports-exec-addresses"></a>Server Address Format</h4></div></div></div><p> 1543 Executed subprocess addresses are identified by the "unixexec:" prefix 1544 and support the following key/value pairs: 1545 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td>(path)</td><td>Path of the binary to execute, either an absolute 1546 path or a binary name that is searched for in the default 1547 search path of the OS. This corresponds to the first 1548 argument of execlp(). This key is mandatory.</td></tr><tr><td>argv0</td><td>(string)</td><td>The program name to use when executing the 1549 binary. If omitted the same value as specified for path= 1550 will be used. This corresponds to the second argument of 1551 execlp().</td></tr><tr><td>argv1, argv2, ...</td><td>(string)</td><td>Arguments to pass to the binary. This corresponds 1552 to the third and later arguments of execlp(). If a 1553 specific argvX is not specified no further argvY for Y > X 1554 are taken into account.</td></tr></tbody></table></div></div></div></div><div class="sect1" title="Meta Transports"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="meta-transports"></a>Meta Transports</h2></div></div></div><p> 1555 Meta transports are a kind of transport with special enhancements or 1556 behavior. Currently available meta transports include: autolaunch 1557 </p><div class="sect2" title="Autolaunch"><div class="titlepage"><div><div><h3 class="title"><a name="meta-transports-autolaunch"></a>Autolaunch</h3></div></div></div><p>The autolaunch transport provides a way for dbus clients to autodetect 1558 a running dbus session bus and to autolaunch a session bus if not present. 1559 </p><div class="sect3" title="Server Address Format"><div class="titlepage"><div><div><h4 class="title"><a name="meta-transports-autolaunch-addresses"></a>Server Address Format</h4></div></div></div><p> 1560 Autolaunch addresses uses the "autolaunch:" prefix and support the 1561 following key/value pairs: 1562 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>scope</td><td>(string)</td><td>scope of autolaunch (Windows only) 1563 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1564 "*install-path" - limit session bus to dbus installation path. 1565 The dbus installation path is determined from the location of 1566 the shared dbus library. If the library is located in a 'bin' 1567 subdirectory the installation root is the directory above, 1568 otherwise the directory where the library lives is taken as 1569 installation root. 1570 </p><pre class="programlisting"> 1571 <install-root>/bin/[lib]dbus-1.dll 1572 <install-root>/[lib]dbus-1.dll 1573 </pre><p> 1574 </p></li><li class="listitem"><p> 1575 "*user" - limit session bus to the recent user. 1576 </p></li><li class="listitem"><p> 1577 other values - specify dedicated session bus like "release", 1578 "debug" or other 1579 </p></li></ul></div> 1580 </td></tr></tbody></table></div></div><div class="sect3" title="Windows implementation"><div class="titlepage"><div><div><h4 class="title"><a name="meta-transports-autolaunch-windows-implementation"></a>Windows implementation</h4></div></div></div><p> 1581 On start, the server opens a platform specific transport, creates a mutex 1582 and a shared memory section containing the related session bus address. 1583 This mutex will be inspected by the dbus client library to detect a 1584 running dbus session bus. The access to the mutex and the shared memory 1585 section are protected by global locks. 1586 </p><p> 1587 In the recent implementation the autolaunch transport uses a tcp transport 1588 on localhost with a port choosen from the operating system. This detail may 1589 change in the future. 1590 </p><p> 1591 Disclaimer: The recent implementation is in an early state and may not 1592 work in all cirumstances and/or may have security issues. Because of this 1593 the implementation is not documentated yet. 1594 </p></div></div></div><div class="sect1" title="UUIDs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="uuids"></a>UUIDs</h2></div></div></div><p> 1595 A working D-Bus implementation uses universally-unique IDs in two places. 1596 First, each server address has a UUID identifying the address, 1597 as described in <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>. Second, each operating 1598 system kernel instance running a D-Bus client or server has a UUID 1599 identifying that kernel, retrieved by invoking the method 1600 org.freedesktop.DBus.Peer.GetMachineId() (see <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “<code class="literal">org.freedesktop.DBus.Peer</code>”</a>). 1601 </p><p> 1602 The term "UUID" in this document is intended literally, i.e. an 1603 identifier that is universally unique. It is not intended to refer to 1604 RFC4122, and in fact the D-Bus UUID is not compatible with that RFC. 1605 </p><p> 1606 The UUID must contain 128 bits of data and be hex-encoded. The 1607 hex-encoded string may not contain hyphens or other non-hex-digit 1608 characters, and it must be exactly 32 characters long. To generate a 1609 UUID, the current reference implementation concatenates 96 bits of random 1610 data followed by the 32-bit time in seconds since the UNIX epoch (in big 1611 endian byte order). 1612 </p><p> 1613 It would also be acceptable and probably better to simply generate 128 1614 bits of random data, as long as the random number generator is of high 1615 quality. The timestamp could conceivably help if the random bits are not 1616 very random. With a quality random number generator, collisions are 1617 extremely unlikely even with only 96 bits, so it's somewhat academic. 1618 </p><p> 1619 Implementations should, however, stick to random data for the first 96 bits 1620 of the UUID. 1621 </p></div><div class="sect1" title="Standard Interfaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="standard-interfaces"></a>Standard Interfaces</h2></div></div></div><p> 1622 See <a class="xref" href="#message-protocol-types-notation" title="Notation in this document">the section called “Notation in this document”</a> for details on 1623 the notation used in this section. There are some standard interfaces 1624 that may be useful across various D-Bus applications. 1625 </p><div class="sect2" title="org.freedesktop.DBus.Peer"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-peer"></a><code class="literal">org.freedesktop.DBus.Peer</code></h3></div></div></div><p> 1626 The <code class="literal">org.freedesktop.DBus.Peer</code> interface 1627 has two methods: 1628 </p><pre class="programlisting"> 1629 org.freedesktop.DBus.Peer.Ping () 1630 org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid) 1631 </pre><p> 1632 </p><p> 1633 On receipt of the <code class="literal">METHOD_CALL</code> message 1634 <code class="literal">org.freedesktop.DBus.Peer.Ping</code>, an application should do 1635 nothing other than reply with a <code class="literal">METHOD_RETURN</code> as 1636 usual. It does not matter which object path a ping is sent to. The 1637 reference implementation handles this method automatically. 1638 </p><p> 1639 On receipt of the <code class="literal">METHOD_CALL</code> message 1640 <code class="literal">org.freedesktop.DBus.Peer.GetMachineId</code>, an application should 1641 reply with a <code class="literal">METHOD_RETURN</code> containing a hex-encoded 1642 UUID representing the identity of the machine the process is running on. 1643 This UUID must be the same for all processes on a single system at least 1644 until that system next reboots. It should be the same across reboots 1645 if possible, but this is not always possible to implement and is not 1646 guaranteed. 1647 It does not matter which object path a GetMachineId is sent to. The 1648 reference implementation handles this method automatically. 1649 </p><p> 1650 The UUID is intended to be per-instance-of-the-operating-system, so may represent 1651 a virtual machine running on a hypervisor, rather than a physical machine. 1652 Basically if two processes see the same UUID, they should also see the same 1653 shared memory, UNIX domain sockets, process IDs, and other features that require 1654 a running OS kernel in common between the processes. 1655 </p><p> 1656 The UUID is often used where other programs might use a hostname. Hostnames 1657 can change without rebooting, however, or just be "localhost" - so the UUID 1658 is more robust. 1659 </p><p> 1660 <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a> explains the format of the UUID. 1661 </p></div><div class="sect2" title="org.freedesktop.DBus.Introspectable"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-introspectable"></a><code class="literal">org.freedesktop.DBus.Introspectable</code></h3></div></div></div><p> 1662 This interface has one method: 1663 </p><pre class="programlisting"> 1664 org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data) 1665 </pre><p> 1666 </p><p> 1667 Objects instances may implement 1668 <code class="literal">Introspect</code> which returns an XML description of 1669 the object, including its interfaces (with signals and methods), objects 1670 below it in the object path tree, and its properties. 1671 </p><p> 1672 <a class="xref" href="#introspection-format" title="Introspection Data Format">the section called “Introspection Data Format”</a> describes the format of this XML string. 1673 </p></div><div class="sect2" title="org.freedesktop.DBus.Properties"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-properties"></a><code class="literal">org.freedesktop.DBus.Properties</code></h3></div></div></div><p> 1674 Many native APIs will have a concept of object <em class="firstterm">properties</em> 1675 or <em class="firstterm">attributes</em>. These can be exposed via the 1676 <code class="literal">org.freedesktop.DBus.Properties</code> interface. 1677 </p><p> 1678 </p><pre class="programlisting"> 1679 org.freedesktop.DBus.Properties.Get (in STRING interface_name, 1680 in STRING property_name, 1681 out VARIANT value); 1682 org.freedesktop.DBus.Properties.Set (in STRING interface_name, 1683 in STRING property_name, 1684 in VARIANT value); 1685 org.freedesktop.DBus.Properties.GetAll (in STRING interface_name, 1686 out DICT<STRING,VARIANT> props); 1687 </pre><p> 1688 </p><p> 1689 It is conventional to give D-Bus properties names consisting of 1690 capitalized words without punctuation ("CamelCase"), like 1691 <a class="link" href="#message-protocol-names-member" title="Member names">member names</a>. 1692 For instance, the GObject property 1693 <code class="literal">connection-status</code> or the Qt property 1694 <code class="literal">connectionStatus</code> could be represented on D-Bus 1695 as <code class="literal">ConnectionStatus</code>. 1696 </p><p> 1697 Strictly speaking, D-Bus property names are not required to follow 1698 the same naming restrictions as member names, but D-Bus property 1699 names that would not be valid member names (in particular, 1700 GObject-style dash-separated property names) can cause interoperability 1701 problems and should be avoided. 1702 </p><p> 1703 The available properties and whether they are writable can be determined 1704 by calling <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>, 1705 see <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “<code class="literal">org.freedesktop.DBus.Introspectable</code>”</a>. 1706 </p><p> 1707 An empty string may be provided for the interface name; in this case, 1708 if there are multiple properties on an object with the same name, 1709 the results are undefined (picking one by according to an arbitrary 1710 deterministic rule, or returning an error, are the reasonable 1711 possibilities). 1712 </p><p> 1713 If one or more properties change on an object, the 1714 <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code> 1715 signal may be emitted (this signal was added in 0.14): 1716 </p><p> 1717 </p><pre class="programlisting"> 1718 org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name, 1719 DICT<STRING,VARIANT> changed_properties, 1720 ARRAY<STRING> invalidated_properties); 1721 </pre><p> 1722 </p><p> 1723 where <code class="literal">changed_properties</code> is a dictionary 1724 containing the changed properties with the new values and 1725 <code class="literal">invalidated_properties</code> is an array of 1726 properties that changed but the value is not conveyed. 1727 </p><p> 1728 Whether the <code class="literal">PropertiesChanged</code> signal is 1729 supported can be determined by calling 1730 <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>. Note 1731 that the signal may be supported for an object but it may 1732 differ how whether and how it is used on a per-property basis 1733 (for e.g. performance or security reasons). Each property (or 1734 the parent interface) must be annotated with the 1735 <code class="literal">org.freedesktop.DBus.Property.EmitsChangedSignal</code> 1736 annotation to convey this (usually the default value 1737 <code class="literal">true</code> is sufficient meaning that the 1738 annotation does not need to be used). See <a class="xref" href="#introspection-format" title="Introspection Data Format">the section called “Introspection Data Format”</a> for details on this 1739 annotation. 1740 </p></div><div class="sect2" title="org.freedesktop.DBus.ObjectManager"><div class="titlepage"><div><div><h3 class="title"><a name="standard-interfaces-objectmanager"></a><code class="literal">org.freedesktop.DBus.ObjectManager</code></h3></div></div></div><p> 1741 An API can optionally make use of this interface for one or 1742 more sub-trees of objects. The root of each sub-tree implements 1743 this interface so other applications can get all objects, 1744 interfaces and properties in a single method call. It is 1745 appropriate to use this interface if users of the tree of 1746 objects are expected to be interested in all interfaces of all 1747 objects in the tree; a more granular API should be used if 1748 users of the objects are expected to be interested in a small 1749 subset of the objects, a small subset of their interfaces, or 1750 both. 1751 </p><p> 1752 The method that applications can use to get all objects and 1753 properties is <code class="literal">GetManagedObjects</code>: 1754 </p><p> 1755 </p><pre class="programlisting"> 1756 org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties); 1757 </pre><p> 1758 </p><p> 1759 The return value of this method is a dict whose keys are 1760 object paths. All returned object paths are children of the 1761 object path implementing this interface, i.e. their object 1762 paths start with the ObjectManager's object path plus '/'. 1763 </p><p> 1764 Each value is a dict whose keys are interfaces names. Each 1765 value in this inner dict is the same dict that would be 1766 returned by the <a class="link" href="#standard-interfaces-properties" title="org.freedesktop.DBus.Properties">org.freedesktop.DBus.Properties.GetAll()</a> 1767 method for that combination of object path and interface. If 1768 an interface has no properties, the empty dict is returned. 1769 </p><p> 1770 Changes are emitted using the following two signals: 1771 </p><p> 1772 </p><pre class="programlisting"> 1773 org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path, 1774 DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties); 1775 org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path, 1776 ARRAY<STRING> interfaces); 1777 </pre><p> 1778 </p><p> 1779 The <code class="literal">InterfacesAdded</code> signal is emitted when 1780 either a new object is added or when an existing object gains 1781 one or more interfaces. The 1782 <code class="literal">InterfacesRemoved</code> signal is emitted 1783 whenever an object is removed or it loses one or more 1784 interfaces. The second parameter of the 1785 <code class="literal">InterfacesAdded</code> signal contains a dict with 1786 the interfaces and properties (if any) that have been added to 1787 the given object path. Similarly, the second parameter of the 1788 <code class="literal">InterfacesRemoved</code> signal contains an array 1789 of the interfaces that were removed. Note that changes on 1790 properties on existing interfaces are not reported using this 1791 interface - an application should also monitor the existing <a class="link" href="#standard-interfaces-properties" title="org.freedesktop.DBus.Properties">PropertiesChanged</a> 1792 signal on each object. 1793 </p><p> 1794 Applications SHOULD NOT export objects that are children of an 1795 object (directly or otherwise) implementing this interface but 1796 which are not returned in the reply from the 1797 <code class="literal">GetManagedObjects()</code> method of this 1798 interface on the given object. 1799 </p><p> 1800 The intent of the <code class="literal">ObjectManager</code> interface 1801 is to make it easy to write a robust client 1802 implementation. The trivial client implementation only needs 1803 to make two method calls: 1804 </p><p> 1805 </p><pre class="programlisting"> 1806 org.freedesktop.DBus.AddMatch (bus_proxy, 1807 "type='signal',name='org.example.App',path_namespace='/org/example/App'"); 1808 objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy); 1809 </pre><p> 1810 </p><p> 1811 on the message bus and the remote application's 1812 <code class="literal">ObjectManager</code>, respectively. Whenever a new 1813 remote object is created (or an existing object gains a new 1814 interface), the <code class="literal">InterfacesAdded</code> signal is 1815 emitted, and since this signal contains all properties for the 1816 interfaces, no calls to the 1817 <code class="literal">org.freedesktop.Properties</code> interface on the 1818 remote object are needed. Additionally, since the initial 1819 <code class="literal">AddMatch()</code> rule already includes signal 1820 messages from the newly created child object, no new 1821 <code class="literal">AddMatch()</code> call is needed. 1822 </p><p> 1823 <span class="emphasis"><em> 1824 The <code class="literal">org.freedesktop.DBus.ObjectManager</code> 1825 interface was added in version 0.17 of the D-Bus 1826 specification. 1827 </em></span> 1828 </p></div></div><div class="sect1" title="Introspection Data Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introspection-format"></a>Introspection Data Format</h2></div></div></div><p> 1829 As described in <a class="xref" href="#standard-interfaces-introspectable" title="org.freedesktop.DBus.Introspectable">the section called “<code class="literal">org.freedesktop.DBus.Introspectable</code>”</a>, 1830 objects may be introspected at runtime, returning an XML string 1831 that describes the object. The same XML format may be used in 1832 other contexts as well, for example as an "IDL" for generating 1833 static language bindings. 1834 </p><p> 1835 Here is an example of introspection data: 1836 </p><pre class="programlisting"> 1837 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" 1838 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> 1839 <node name="/org/freedesktop/sample_object"> 1840 <interface name="org.freedesktop.SampleInterface"> 1841 <method name="Frobate"> 1842 <arg name="foo" type="i" direction="in"/> 1843 <arg name="bar" type="s" direction="out"/> 1844 <arg name="baz" type="a{us}" direction="out"/> 1845 <annotation name="org.freedesktop.DBus.Deprecated" value="true"/> 1846 </method> 1847 <method name="Bazify"> 1848 <arg name="bar" type="(iiu)" direction="in"/> 1849 <arg name="bar" type="v" direction="out"/> 1850 </method> 1851 <method name="Mogrify"> 1852 <arg name="bar" type="(iiav)" direction="in"/> 1853 </method> 1854 <signal name="Changed"> 1855 <arg name="new_value" type="b"/> 1856 </signal> 1857 <property name="Bar" type="y" access="readwrite"/> 1858 </interface> 1859 <node name="child_of_sample_object"/> 1860 <node name="another_child_of_sample_object"/> 1861 </node> 1862 </pre><p> 1863 </p><p> 1864 A more formal DTD and spec needs writing, but here are some quick notes. 1865 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 1866 Only the root <node> element can omit the node name, as it's 1867 known to be the object that was introspected. If the root 1868 <node> does have a name attribute, it must be an absolute 1869 object path. If child <node> have object paths, they must be 1870 relative. 1871 </p></li><li class="listitem"><p> 1872 If a child <node> has any sub-elements, then they 1873 must represent a complete introspection of the child. 1874 If a child <node> is empty, then it may or may 1875 not have sub-elements; the child must be introspected 1876 in order to find out. The intent is that if an object 1877 knows that its children are "fast" to introspect 1878 it can go ahead and return their information, but 1879 otherwise it can omit it. 1880 </p></li><li class="listitem"><p> 1881 The direction element on <arg> may be omitted, 1882 in which case it defaults to "in" for method calls 1883 and "out" for signals. Signals only allow "out" 1884 so while direction may be specified, it's pointless. 1885 </p></li><li class="listitem"><p> 1886 The possible directions are "in" and "out", 1887 unlike CORBA there is no "inout" 1888 </p></li><li class="listitem"><p> 1889 The possible property access flags are 1890 "readwrite", "read", and "write" 1891 </p></li><li class="listitem"><p> 1892 Multiple interfaces can of course be listed for 1893 one <node>. 1894 </p></li><li class="listitem"><p> 1895 The "name" attribute on arguments is optional. 1896 </p></li></ul></div><p> 1897 </p><p> 1898 Method, interface, property, and signal elements may have 1899 "annotations", which are generic key/value pairs of metadata. 1900 They are similar conceptually to Java's annotations and C# attributes. 1901 Well-known annotations: 1902 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Values (separated by ,)</th><th>Description</th></tr></thead><tbody><tr><td>org.freedesktop.DBus.Deprecated</td><td>true,false</td><td>Whether or not the entity is deprecated; defaults to false</td></tr><tr><td>org.freedesktop.DBus.GLib.CSymbol</td><td>(string)</td><td>The C symbol; may be used for methods and interfaces</td></tr><tr><td>org.freedesktop.DBus.Method.NoReply</td><td>true,false</td><td>If set, don't expect a reply to the method call; defaults to false.</td></tr><tr><td>org.freedesktop.DBus.Property.EmitsChangedSignal</td><td>true,invalidates,false</td><td> 1903 <p> 1904 If set to <code class="literal">false</code>, the 1905 <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code> 1906 signal, see <a class="xref" href="#standard-interfaces-properties" title="org.freedesktop.DBus.Properties">the section called “<code class="literal">org.freedesktop.DBus.Properties</code>”</a> is not 1907 guaranteed to be emitted if the property changes. 1908 </p> 1909 <p> 1910 If set to <code class="literal">invalidates</code> the signal 1911 is emitted but the value is not included in the 1912 signal. 1913 </p> 1914 <p> 1915 If set to <code class="literal">true</code> the signal is 1916 emitted with the value included. 1917 </p> 1918 <p> 1919 The value for the annotation defaults to 1920 <code class="literal">true</code> if the enclosing interface 1921 element does not specify the annotation. Otherwise it 1922 defaults to the value specified in the enclosing 1923 interface element. 1924 </p> 1925 </td></tr></tbody></table></div></div><div class="sect1" title="Message Bus Specification"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="message-bus"></a>Message Bus Specification</h2></div></div></div><div class="sect2" title="Message Bus Overview"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-overview"></a>Message Bus Overview</h3></div></div></div><p> 1926 The message bus accepts connections from one or more applications. 1927 Once connected, applications can exchange messages with other 1928 applications that are also connected to the bus. 1929 </p><p> 1930 In order to route messages among connections, the message bus keeps a 1931 mapping from names to connections. Each connection has one 1932 unique-for-the-lifetime-of-the-bus name automatically assigned. 1933 Applications may request additional names for a connection. Additional 1934 names are usually "well-known names" such as 1935 "org.freedesktop.TextEditor". When a name is bound to a connection, 1936 that connection is said to <em class="firstterm">own</em> the name. 1937 </p><p> 1938 The bus itself owns a special name, <code class="literal">org.freedesktop.DBus</code>. 1939 This name routes messages to the bus, allowing applications to make 1940 administrative requests. For example, applications can ask the bus 1941 to assign a name to a connection. 1942 </p><p> 1943 Each name may have <em class="firstterm">queued owners</em>. When an 1944 application requests a name for a connection and the name is already in 1945 use, the bus will optionally add the connection to a queue waiting for 1946 the name. If the current owner of the name disconnects or releases 1947 the name, the next connection in the queue will become the new owner. 1948 </p><p> 1949 This feature causes the right thing to happen if you start two text 1950 editors for example; the first one may request "org.freedesktop.TextEditor", 1951 and the second will be queued as a possible owner of that name. When 1952 the first exits, the second will take over. 1953 </p><p> 1954 Applications may send <em class="firstterm">unicast messages</em> to 1955 a specific recipient or to the message bus itself, or 1956 <em class="firstterm">broadcast messages</em> to all interested recipients. 1957 See <a class="xref" href="#message-bus-routing" title="Message Bus Message Routing">the section called “Message Bus Message Routing”</a> for details. 1958 </p></div><div class="sect2" title="Message Bus Names"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-names"></a>Message Bus Names</h3></div></div></div><p> 1959 Each connection has at least one name, assigned at connection time and 1960 returned in response to the 1961 <code class="literal">org.freedesktop.DBus.Hello</code> method call. This 1962 automatically-assigned name is called the connection's <em class="firstterm">unique 1963 name</em>. Unique names are never reused for two different 1964 connections to the same bus. 1965 </p><p> 1966 Ownership of a unique name is a prerequisite for interaction with 1967 the message bus. It logically follows that the unique name is always 1968 the first name that an application comes to own, and the last 1969 one that it loses ownership of. 1970 </p><p> 1971 Unique connection names must begin with the character ':' (ASCII colon 1972 character); bus names that are not unique names must not begin 1973 with this character. (The bus must reject any attempt by an application 1974 to manually request a name beginning with ':'.) This restriction 1975 categorically prevents "spoofing"; messages sent to a unique name 1976 will always go to the expected connection. 1977 </p><p> 1978 When a connection is closed, all the names that it owns are deleted (or 1979 transferred to the next connection in the queue if any). 1980 </p><p> 1981 A connection can request additional names to be associated with it using 1982 the <code class="literal">org.freedesktop.DBus.RequestName</code> message. <a class="xref" href="#message-protocol-names-bus" title="Bus names">the section called “Bus names”</a> describes the format of a valid 1983 name. These names can be released again using the 1984 <code class="literal">org.freedesktop.DBus.ReleaseName</code> message. 1985 </p><div class="sect3" title="org.freedesktop.DBus.RequestName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-request-name"></a><code class="literal">org.freedesktop.DBus.RequestName</code></h4></div></div></div><p> 1986 As a method: 1987 </p><pre class="programlisting"> 1988 UINT32 RequestName (in STRING name, in UINT32 flags) 1989 </pre><p> 1990 Message arguments: 1991 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name to request</td></tr><tr><td>1</td><td>UINT32</td><td>Flags</td></tr></tbody></table></div><p> 1992 Reply arguments: 1993 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Return value</td></tr></tbody></table></div><p> 1994 </p><p> 1995 This method call should be sent to 1996 <code class="literal">org.freedesktop.DBus</code> and asks the message bus to 1997 assign the given name to the method caller. Each name maintains a 1998 queue of possible owners, where the head of the queue is the primary 1999 or current owner of the name. Each potential owner in the queue 2000 maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and 2001 DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName 2002 call. When RequestName is invoked the following occurs: 2003 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> 2004 If the method caller is currently the primary owner of the name, 2005 the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE 2006 values are updated with the values from the new RequestName call, 2007 and nothing further happens. 2008 </p></li><li class="listitem"><p> 2009 If the current primary owner (head of the queue) has 2010 DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName 2011 invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then 2012 the caller of RequestName replaces the current primary owner at 2013 the head of the queue and the current primary owner moves to the 2014 second position in the queue. If the caller of RequestName was 2015 in the queue previously its flags are updated with the values from 2016 the new RequestName in addition to moving it to the head of the queue. 2017 </p></li><li class="listitem"><p> 2018 If replacement is not possible, and the method caller is 2019 currently in the queue but not the primary owner, its flags are 2020 updated with the values from the new RequestName call. 2021 </p></li><li class="listitem"><p> 2022 If replacement is not possible, and the method caller is 2023 currently not in the queue, the method caller is appended to the 2024 queue. 2025 </p></li><li class="listitem"><p> 2026 If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE 2027 set and is not the primary owner, it is removed from the 2028 queue. This can apply to the previous primary owner (if it 2029 was replaced) or the method caller (if it updated the 2030 DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the 2031 queue, or if it was just added to the queue with that flag set). 2032 </p></li></ul></div><p> 2033 </p><p> 2034 Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the 2035 queue," even if another application already in the queue had specified 2036 DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner 2037 that does not allow replacement goes away, and the next primary owner 2038 does allow replacement. In this case, queued items that specified 2039 DBUS_NAME_FLAG_REPLACE_EXISTING <span class="emphasis"><em>do not</em></span> 2040 automatically replace the new primary owner. In other words, 2041 DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the 2042 time RequestName is called. This is deliberate to avoid an infinite loop 2043 anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT 2044 and DBUS_NAME_FLAG_REPLACE_EXISTING. 2045 </p><p> 2046 The flags argument contains any of the following values logically ORed 2047 together: 2048 2049 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</td><td>0x1</td><td> 2050 2051 If an application A specifies this flag and succeeds in 2052 becoming the owner of the name, and another application B 2053 later calls RequestName with the 2054 DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A 2055 will lose ownership and receive a 2056 <code class="literal">org.freedesktop.DBus.NameLost</code> signal, and 2057 application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT 2058 is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING 2059 is not specified by application B, then application B will not replace 2060 application A as the owner. 2061 2062 </td></tr><tr><td>DBUS_NAME_FLAG_REPLACE_EXISTING</td><td>0x2</td><td> 2063 2064 Try to replace the current owner if there is one. If this 2065 flag is not set the application will only become the owner of 2066 the name if there is no current owner. If this flag is set, 2067 the application will replace the current owner if 2068 the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT. 2069 2070 </td></tr><tr><td>DBUS_NAME_FLAG_DO_NOT_QUEUE</td><td>0x4</td><td> 2071 2072 Without this flag, if an application requests a name that is 2073 already owned, the application will be placed in a queue to 2074 own the name when the current owner gives it up. If this 2075 flag is given, the application will not be placed in the 2076 queue, the request for the name will simply fail. This flag 2077 also affects behavior when an application is replaced as 2078 name owner; by default the application moves back into the 2079 waiting queue, unless this flag was provided when the application 2080 became the name owner. 2081 2082 </td></tr></tbody></table></div><p> 2083 2084 The return code can be one of the following values: 2085 2086 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</td><td>1</td><td>The caller is now the primary owner of 2087 the name, replacing any previous owner. Either the name had no 2088 owner before, or the caller specified 2089 DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified 2090 DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</td></tr><tr><td>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</td><td>2</td><td>The name already had an owner, 2091 DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either 2092 the current owner did not specify 2093 DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting 2094 application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING. 2095 </td></tr><tr><td>DBUS_REQUEST_NAME_REPLY_EXISTS</td><td>3</td><td>The name already has an owner, 2096 DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either 2097 DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the 2098 current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not 2099 specified by the requesting application.</td></tr><tr><td>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</td><td>4</td><td>The application trying to request ownership of a name is already the owner of it.</td></tr></tbody></table></div><p> 2100 </p></div><div class="sect3" title="org.freedesktop.DBus.ReleaseName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-release-name"></a><code class="literal">org.freedesktop.DBus.ReleaseName</code></h4></div></div></div><p> 2101 As a method: 2102 </p><pre class="programlisting"> 2103 UINT32 ReleaseName (in STRING name) 2104 </pre><p> 2105 Message arguments: 2106 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name to release</td></tr></tbody></table></div><p> 2107 Reply arguments: 2108 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Return value</td></tr></tbody></table></div><p> 2109 </p><p> 2110 This method call should be sent to 2111 <code class="literal">org.freedesktop.DBus</code> and asks the message bus to 2112 release the method caller's claim to the given name. If the caller is 2113 the primary owner, a new primary owner will be selected from the 2114 queue if any other owners are waiting. If the caller is waiting in 2115 the queue for the name, the caller will removed from the queue and 2116 will not be made an owner of the name if it later becomes available. 2117 If there are no other owners in the queue for the name, it will be 2118 removed from the bus entirely. 2119 2120 The return code can be one of the following values: 2121 2122 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Conventional Name</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>DBUS_RELEASE_NAME_REPLY_RELEASED</td><td>1</td><td>The caller has released his claim on 2123 the given name. Either the caller was the primary owner of 2124 the name, and the name is now unused or taken by somebody 2125 waiting in the queue for the name, or the caller was waiting 2126 in the queue for the name and has now been removed from the 2127 queue.</td></tr><tr><td>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</td><td>2</td><td>The given name does not exist on this bus.</td></tr><tr><td>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</td><td>3</td><td>The caller was not the primary owner of this name, 2128 and was also not waiting in the queue to own this name.</td></tr></tbody></table></div><p> 2129 </p></div><div class="sect3" title="org.freedesktop.DBus.ListQueuedOwners"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-queued-owners"></a><code class="literal">org.freedesktop.DBus.ListQueuedOwners</code></h4></div></div></div><p> 2130 As a method: 2131 </p><pre class="programlisting"> 2132 ARRAY of STRING ListQueuedOwners (in STRING name) 2133 </pre><p> 2134 Message arguments: 2135 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>The well-known bus name to query, such as 2136 <code class="literal">com.example.cappuccino</code></td></tr></tbody></table></div><p> 2137 Reply arguments: 2138 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>ARRAY of STRING</td><td>The unique bus names of connections currently queued 2139 for the name</td></tr></tbody></table></div><p> 2140 </p><p> 2141 This method call should be sent to 2142 <code class="literal">org.freedesktop.DBus</code> and lists the connections 2143 currently queued for a bus name (see 2144 <a class="xref" href="#term-queued-owner" title="Queued Name Owner">Queued Name Owner</a>). 2145 </p></div></div><div class="sect2" title="Message Bus Message Routing"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-routing"></a>Message Bus Message Routing</h3></div></div></div><p> 2146 Messages may have a <code class="literal">DESTINATION</code> field (see <a class="xref" href="#message-protocol-header-fields" title="Header Fields">the section called “Header Fields”</a>), resulting in a 2147 <em class="firstterm">unicast message</em>. If the 2148 <code class="literal">DESTINATION</code> field is present, it specifies a message 2149 recipient by name. Method calls and replies normally specify this field. 2150 The message bus must send messages (of any type) with the 2151 <code class="literal">DESTINATION</code> field set to the specified recipient, 2152 regardless of whether the recipient has set up a match rule matching 2153 the message. 2154 </p><p> 2155 When the message bus receives a signal, if the 2156 <code class="literal">DESTINATION</code> field is absent, it is considered to 2157 be a <em class="firstterm">broadcast signal</em>, and is sent to all 2158 applications with <em class="firstterm">message matching rules</em> that 2159 match the message. Most signal messages are broadcasts. 2160 </p><p> 2161 Unicast signal messages (those with a <code class="literal">DESTINATION</code> 2162 field) are not commonly used, but they are treated like any unicast 2163 message: they are delivered to the specified receipient, 2164 regardless of its match rules. One use for unicast signals is to 2165 avoid a race condition in which a signal is emitted before the intended 2166 recipient can call <a class="xref" href="#bus-messages-add-match" title="org.freedesktop.DBus.AddMatch">the section called “<code class="literal">org.freedesktop.DBus.AddMatch</code>”</a> to 2167 receive that signal: if the signal is sent directly to that recipient 2168 using a unicast message, it does not need to add a match rule at all, 2169 and there is no race condition. Another use for unicast signals, 2170 on message buses whose security policy prevents eavesdropping, is to 2171 send sensitive information which should only be visible to one 2172 recipient. 2173 </p><p> 2174 When the message bus receives a method call, if the 2175 <code class="literal">DESTINATION</code> field is absent, the call is taken to be 2176 a standard one-to-one message and interpreted by the message bus 2177 itself. For example, sending an 2178 <code class="literal">org.freedesktop.DBus.Peer.Ping</code> message with no 2179 <code class="literal">DESTINATION</code> will cause the message bus itself to 2180 reply to the ping immediately; the message bus will not make this 2181 message visible to other applications. 2182 </p><p> 2183 Continuing the <code class="literal">org.freedesktop.DBus.Peer.Ping</code> example, if 2184 the ping message were sent with a <code class="literal">DESTINATION</code> name of 2185 <code class="literal">com.yoyodyne.Screensaver</code>, then the ping would be 2186 forwarded, and the Yoyodyne Corporation screensaver application would be 2187 expected to reply to the ping. 2188 </p><p> 2189 Message bus implementations may impose a security policy which 2190 prevents certain messages from being sent or received. 2191 When a message cannot be sent or received due to a security 2192 policy, the message bus should send an error reply, unless the 2193 original message had the <code class="literal">NO_REPLY</code> flag. 2194 </p><div class="sect3" title="Eavesdropping"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-routing-eavesdropping"></a>Eavesdropping</h4></div></div></div><p> 2195 Receiving a unicast message whose <code class="literal">DESTINATION</code> 2196 indicates a different recipient is called 2197 <em class="firstterm">eavesdropping</em>. On a message bus which acts as 2198 a security boundary (like the standard system bus), the security 2199 policy should usually prevent eavesdropping, since unicast messages 2200 are normally kept private and may contain security-sensitive 2201 information. 2202 </p><p> 2203 Eavesdropping is mainly useful for debugging tools, such as 2204 the <code class="literal">dbus-monitor</code> tool in the reference 2205 implementation of D-Bus. Tools which eavesdrop on the message bus 2206 should be careful to avoid sending a reply or error in response to 2207 messages intended for a different client. 2208 </p><p> 2209 Clients may attempt to eavesdrop by adding match rules 2210 (see <a class="xref" href="#message-bus-routing-match-rules" title="Match Rules">the section called “Match Rules”</a>) containing 2211 the <code class="literal">eavesdrop='true'</code> match. If the message bus' 2212 security policy does not allow eavesdropping, the match rule can 2213 still be added, but will not have any practical effect. For 2214 compatibility with older message bus implementations, if adding such 2215 a match rule results in an error reply, the client may fall back to 2216 adding the same rule with the <code class="literal">eavesdrop</code> match 2217 omitted. 2218 </p></div><div class="sect3" title="Match Rules"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-routing-match-rules"></a>Match Rules</h4></div></div></div><p> 2219 An important part of the message bus routing protocol is match 2220 rules. Match rules describe the messages that should be sent to a 2221 client, based on the contents of the message. Broadcast signals 2222 are only sent to clients which have a suitable match rule: this 2223 avoids waking up client processes to deal with signals that are 2224 not relevant to that client. 2225 </p><p> 2226 Messages that list a client as their <code class="literal">DESTINATION</code> 2227 do not need to match the client's match rules, and are sent to that 2228 client regardless. As a result, match rules are mainly used to 2229 receive a subset of broadcast signals. 2230 </p><p> 2231 Match rules can also be used for eavesdropping 2232 (see <a class="xref" href="#message-bus-routing-eavesdropping" title="Eavesdropping">the section called “Eavesdropping”</a>), 2233 if the security policy of the message bus allows it. 2234 </p><p> 2235 Match rules are added using the AddMatch bus method 2236 (see <a class="xref" href="#bus-messages-add-match" title="org.freedesktop.DBus.AddMatch">the section called “<code class="literal">org.freedesktop.DBus.AddMatch</code>”</a>). Rules are 2237 specified as a string of comma separated key/value pairs. 2238 Excluding a key from the rule indicates a wildcard match. 2239 For instance excluding the the member from a match rule but 2240 adding a sender would let all messages from that sender through. 2241 An example of a complete rule would be 2242 "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'" 2243 </p><p> 2244 The following table describes the keys that can be used to create 2245 a match rule: 2246 The following table summarizes the D-Bus types. 2247 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Key</th><th>Possible Values</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">type</code></td><td>'signal', 'method_call', 'method_return', 'error'</td><td>Match on the message type. An example of a type match is type='signal'</td></tr><tr><td><code class="literal">sender</code></td><td>A bus or unique name (see <a class="xref" href="#term-bus-name" title="Bus Name">Bus Name</a> 2248 and <a class="xref" href="#term-unique-name" title="Unique Connection Name">Unique Connection Name</a> respectively) 2249 </td><td>Match messages sent by a particular sender. An example of a sender match 2250 is sender='org.freedesktop.Hal'</td></tr><tr><td><code class="literal">interface</code></td><td>An interface name (see <a class="xref" href="#message-protocol-names-interface" title="Interface names">the section called “Interface names”</a>)</td><td>Match messages sent over or to a particular interface. An example of an 2251 interface match is interface='org.freedesktop.Hal.Manager'. 2252 If a message omits the interface header, it must not match any rule 2253 that specifies this key.</td></tr><tr><td><code class="literal">member</code></td><td>Any valid method or signal name</td><td>Matches messages which have the give method or signal name. An example of 2254 a member match is member='NameOwnerChanged'</td></tr><tr><td><code class="literal">path</code></td><td>An object path (see <a class="xref" href="#message-protocol-marshaling-object-path" title="Valid Object Paths">the section called “Valid Object Paths”</a>)</td><td>Matches messages which are sent from or to the given object. An example of a 2255 path match is path='/org/freedesktop/Hal/Manager'</td></tr><tr><td><code class="literal">path_namespace</code></td><td>An object path</td><td> 2256 <p> 2257 Matches messages which are sent from or to an 2258 object for which the object path is either the 2259 given value, or that value followed by one or 2260 more path components. 2261 </p> 2262 2263 <p> 2264 For example, 2265 <code class="literal">path_namespace='/com/example/foo'</code> 2266 would match signals sent by 2267 <code class="literal">/com/example/foo</code> 2268 or by 2269 <code class="literal">/com/example/foo/bar</code>, 2270 but not by 2271 <code class="literal">/com/example/foobar</code>. 2272 </p> 2273 2274 <p> 2275 Using both <code class="literal">path</code> and 2276 <code class="literal">path_namespace</code> in the same match 2277 rule is not allowed. 2278 </p> 2279 2280 <p> 2281 <span class="emphasis"><em> 2282 This match key was added in version 0.16 of the 2283 D-Bus specification and implemented by the bus 2284 daemon in dbus 1.5.0 and later. 2285 </em></span> 2286 </p> 2287 </td></tr><tr><td><code class="literal">destination</code></td><td>A unique name (see <a class="xref" href="#term-unique-name" title="Unique Connection Name">Unique Connection Name</a>)</td><td>Matches messages which are being sent to the given unique name. An 2288 example of a destination match is destination=':1.0'</td></tr><tr><td><code class="literal">arg[0, 1, 2, 3, ...]</code></td><td>Any string</td><td>Arg matches are special and are used for further restricting the 2289 match based on the arguments in the body of a message. Only arguments of type 2290 STRING can be matched in this way. An example of an argument match 2291 would be arg3='Foo'. Only argument indexes from 0 to 63 should be 2292 accepted.</td></tr><tr><td><code class="literal">arg[0, 1, 2, 3, ...]path</code></td><td>Any string</td><td> 2293 <p>Argument path matches provide a specialised form of wildcard matching for 2294 path-like namespaces. They can match arguments whose type is either STRING or 2295 OBJECT_PATH. As with normal argument matches, 2296 if the argument is exactly equal to the string given in the match 2297 rule then the rule is satisfied. Additionally, there is also a 2298 match when either the string given in the match rule or the 2299 appropriate message argument ends with '/' and is a prefix of the 2300 other. An example argument path match is arg0path='/aa/bb/'. This 2301 would match messages with first arguments of '/', '/aa/', 2302 '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match 2303 messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</p> 2304 2305 <p>This is intended for monitoring “directories” in file system-like 2306 hierarchies, as used in the <em class="citetitle">dconf</em> configuration 2307 system. An application interested in all nodes in a particular hierarchy would 2308 monitor <code class="literal">arg0path='/ca/example/foo/'</code>. Then the service could 2309 emit a signal with zeroth argument <code class="literal">"/ca/example/foo/bar"</code> to 2310 represent a modification to the “bar” property, or a signal with zeroth 2311 argument <code class="literal">"/ca/example/"</code> to represent atomic modification of 2312 many properties within that directory, and the interested application would be 2313 notified in both cases.</p> 2314 <p> 2315 <span class="emphasis"><em> 2316 This match key was added in version 0.12 of the 2317 D-Bus specification, implemented for STRING 2318 arguments by the bus daemon in dbus 1.2.0 and later, 2319 and implemented for OBJECT_PATH arguments in dbus 1.5.0 2320 and later. 2321 </em></span> 2322 </p> 2323 </td></tr><tr><td><code class="literal">arg0namespace</code></td><td>Like a bus name, except that the string is not 2324 required to contain a '.' (period)</td><td> 2325 <p>Match messages whose first argument is of type STRING, and is a bus name 2326 or interface name within the specified namespace. This is primarily intended 2327 for watching name owner changes for a group of related bus names, rather than 2328 for a single name or all name changes.</p> 2329 2330 <p>Because every valid interface name is also a valid 2331 bus name, this can also be used for messages whose 2332 first argument is an interface name.</p> 2333 2334 <p>For example, the match rule 2335 <code class="literal">member='NameOwnerChanged',arg0namespace='com.example.backend'</code> 2336 matches name owner changes for bus names such as 2337 <code class="literal">com.example.backend.foo</code>, 2338 <code class="literal">com.example.backend.foo.bar</code>, and 2339 <code class="literal">com.example.backend</code> itself.</p> 2340 2341 <p>See also <a class="xref" href="#bus-messages-name-owner-changed" title="org.freedesktop.DBus.NameOwnerChanged">the section called “<code class="literal">org.freedesktop.DBus.NameOwnerChanged</code>”</a>.</p> 2342 <p> 2343 <span class="emphasis"><em> 2344 This match key was added in version 0.16 of the 2345 D-Bus specification and implemented by the bus 2346 daemon in dbus 1.5.0 and later. 2347 </em></span> 2348 </p> 2349 </td></tr><tr><td><code class="literal">eavesdrop</code></td><td><code class="literal">'true'</code>, <code class="literal">'false'</code></td><td>Since D-Bus 1.5.6, match rules do not 2350 match messages which have a <code class="literal">DESTINATION</code> 2351 field unless the match rule specifically 2352 requests this 2353 (see <a class="xref" href="#message-bus-routing-eavesdropping" title="Eavesdropping">the section called “Eavesdropping”</a>) 2354 by specifying <code class="literal">eavesdrop='true'</code> 2355 in the match rule. <code class="literal">eavesdrop='false'</code> 2356 restores the default behaviour. Messages are 2357 delivered to their <code class="literal">DESTINATION</code> 2358 regardless of match rules, so this match does not 2359 affect normal delivery of unicast messages. 2360 If the message bus has a security policy which forbids 2361 eavesdropping, this match may still be used without error, 2362 but will not have any practical effect. 2363 In older versions of D-Bus, this match was not allowed 2364 in match rules, and all match rules behaved as if 2365 <code class="literal">eavesdrop='true'</code> had been used. 2366 </td></tr></tbody></table></div><p> 2367 </p></div></div><div class="sect2" title="Message Bus Starting Services"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-starting-services"></a>Message Bus Starting Services</h3></div></div></div><p> 2368 The message bus can start applications on behalf of other applications. 2369 In CORBA terms, this would be called <em class="firstterm">activation</em>. 2370 An application that can be started in this way is called a 2371 <em class="firstterm">service</em>. 2372 </p><p> 2373 With D-Bus, starting a service is normally done by name. That is, 2374 applications ask the message bus to start some program that will own a 2375 well-known name, such as <code class="literal">org.freedesktop.TextEditor</code>. 2376 This implies a contract documented along with the name 2377 <code class="literal">org.freedesktop.TextEditor</code> for which objects 2378 the owner of that name will provide, and what interfaces those 2379 objects will have. 2380 </p><p> 2381 To find an executable corresponding to a particular name, the bus daemon 2382 looks for <em class="firstterm">service description files</em>. Service 2383 description files define a mapping from names to executables. Different 2384 kinds of message bus will look for these files in different places, see 2385 <a class="xref" href="#message-bus-types" title="Well-known Message Bus Instances">the section called “Well-known Message Bus Instances”</a>. 2386 </p><p> 2387 Service description files have the ".service" file 2388 extension. The message bus will only load service description files 2389 ending with .service; all other files will be ignored. The file format 2390 is similar to that of <a class="ulink" href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html" target="_top">desktop 2391 entries</a>. All service description files must be in UTF-8 2392 encoding. To ensure that there will be no name collisions, service files 2393 must be namespaced using the same mechanism as messages and service 2394 names. 2395 </p><p> 2396 [FIXME the file format should be much better specified than "similar to 2397 .desktop entries" esp. since desktop entries are already 2398 badly-specified. ;-)] 2399 These sections from the specification apply to service files as well: 2400 2401 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>General syntax</p></li><li class="listitem"><p>Comment format</p></li></ul></div><p> 2402 2403 </p><div class="figure"><a name="idp5671872"></a><p class="title"><b>Figure�9.�Example service description file</b></p><div class="figure-contents"><pre class="programlisting"> 2404 # Sample service description file 2405 [D-BUS Service] 2406 Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; 2407 Exec=/usr/libexec/gconfd-2 2408 </pre></div></div><p><br class="figure-break"> 2409 </p><p> 2410 When an application asks to start a service by name, the bus daemon tries to 2411 find a service that will own that name. It then tries to spawn the 2412 executable associated with it. If this fails, it will report an 2413 error. [FIXME what happens if two .service files offer the same service; 2414 what kind of error is reported, should we have a way for the client to 2415 choose one?] 2416 </p><p> 2417 The executable launched will have the environment variable 2418 <code class="literal">DBUS_STARTER_ADDRESS</code> set to the address of the 2419 message bus so it can connect and request the appropriate names. 2420 </p><p> 2421 The executable being launched may want to know whether the message bus 2422 starting it is one of the well-known message buses (see <a class="xref" href="#message-bus-types" title="Well-known Message Bus Instances">the section called “Well-known Message Bus Instances”</a>). To facilitate this, the bus must also set 2423 the <code class="literal">DBUS_STARTER_BUS_TYPE</code> environment variable if it is one 2424 of the well-known buses. The currently-defined values for this variable 2425 are <code class="literal">system</code> for the systemwide message bus, 2426 and <code class="literal">session</code> for the per-login-session message 2427 bus. The new executable must still connect to the address given 2428 in <code class="literal">DBUS_STARTER_ADDRESS</code>, but may assume that the 2429 resulting connection is to the well-known bus. 2430 </p><p> 2431 [FIXME there should be a timeout somewhere, either specified 2432 in the .service file, by the client, or just a global value 2433 and if the client being activated fails to connect within that 2434 timeout, an error should be sent back.] 2435 </p><div class="sect3" title="Message Bus Service Scope"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-starting-services-scope"></a>Message Bus Service Scope</h4></div></div></div><p> 2436 The "scope" of a service is its "per-", such as per-session, 2437 per-machine, per-home-directory, or per-display. The reference 2438 implementation doesn't yet support starting services in a different 2439 scope from the message bus itself. So e.g. if you start a service 2440 on the session bus its scope is per-session. 2441 </p><p> 2442 We could add an optional scope to a bus name. For example, for 2443 per-(display,session pair), we could have a unique ID for each display 2444 generated automatically at login and set on screen 0 by executing a 2445 special "set display ID" binary. The ID would be stored in a 2446 <code class="literal">_DBUS_DISPLAY_ID</code> property and would be a string of 2447 random bytes. This ID would then be used to scope names. 2448 Starting/locating a service could be done by ID-name pair rather than 2449 only by name. 2450 </p><p> 2451 Contrast this with a per-display scope. To achieve that, we would 2452 want a single bus spanning all sessions using a given display. 2453 So we might set a <code class="literal">_DBUS_DISPLAY_BUS_ADDRESS</code> 2454 property on screen 0 of the display, pointing to this bus. 2455 </p></div></div><div class="sect2" title="Well-known Message Bus Instances"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-types"></a>Well-known Message Bus Instances</h3></div></div></div><p> 2456 Two standard message bus instances are defined here, along with how 2457 to locate them and where their service files live. 2458 </p><div class="sect3" title="Login session message bus"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-login"></a>Login session message bus</h4></div></div></div><p> 2459 Each time a user logs in, a <em class="firstterm">login session message 2460 bus</em> may be started. All applications in the user's login 2461 session may interact with one another using this message bus. 2462 </p><p> 2463 The address of the login session message bus is given 2464 in the <code class="literal">DBUS_SESSION_BUS_ADDRESS</code> environment 2465 variable. If that variable is not set, applications may 2466 also try to read the address from the X Window System root 2467 window property <code class="literal">_DBUS_SESSION_BUS_ADDRESS</code>. 2468 The root window property must have type <code class="literal">STRING</code>. 2469 The environment variable should have precedence over the 2470 root window property. 2471 </p><p>The address of the login session message bus is given in the 2472 <code class="literal">DBUS_SESSION_BUS_ADDRESS</code> environment variable. If 2473 DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string 2474 "autolaunch:", the system should use platform-specific methods of 2475 locating a running D-Bus session server, or starting one if a running 2476 instance cannot be found. Note that this mechanism is not recommended 2477 for attempting to determine if a daemon is running. It is inherently 2478 racy to attempt to make this determination, since the bus daemon may 2479 be started just before or just after the determination is made. 2480 Therefore, it is recommended that applications do not try to make this 2481 determination for their functionality purposes, and instead they 2482 should attempt to start the server.</p><div class="sect4" title="X Windowing System"><div class="titlepage"><div><div><h5 class="title"><a name="message-bus-types-login-x-windows"></a>X Windowing System</h5></div></div></div><p> 2483 For the X Windowing System, the application must locate the 2484 window owner of the selection represented by the atom formed by 2485 concatenating: 2486 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the literal string "_DBUS_SESSION_BUS_SELECTION_"</p></li><li class="listitem"><p>the current user's username</p></li><li class="listitem"><p>the literal character '_' (underscore)</p></li><li class="listitem"><p>the machine's ID</p></li></ul></div><p> 2487 </p><p> 2488 The following properties are defined for the window that owns 2489 this X selection: 2490 </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td> 2491 <p>Atom</p> 2492 </td><td> 2493 <p>meaning</p> 2494 </td></tr><tr><td> 2495 <p>_DBUS_SESSION_BUS_ADDRESS</p> 2496 </td><td> 2497 <p>the actual address of the server socket</p> 2498 </td></tr><tr><td> 2499 <p>_DBUS_SESSION_BUS_PID</p> 2500 </td><td> 2501 <p>the PID of the server process</p> 2502 </td></tr></tbody></table></div><p> 2503 </p><p> 2504 At least the _DBUS_SESSION_BUS_ADDRESS property MUST be 2505 present in this window. 2506 </p><p> 2507 If the X selection cannot be located or if reading the 2508 properties from the window fails, the implementation MUST conclude 2509 that there is no D-Bus server running and proceed to start a new 2510 server. (See below on concurrency issues) 2511 </p><p> 2512 Failure to connect to the D-Bus server address thus obtained 2513 MUST be treated as a fatal connection error and should be reported 2514 to the application. 2515 </p><p> 2516 As an alternative, an implementation MAY find the information 2517 in the following file located in the current user's home directory, 2518 in subdirectory .dbus/session-bus/: 2519 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the machine's ID</p></li><li class="listitem"><p>the literal character '-' (dash)</p></li><li class="listitem"><p>the X display without the screen number, with the 2520 following prefixes removed, if present: ":", "localhost:" 2521 ."localhost.localdomain:". That is, a display of 2522 "localhost:10.0" produces just the number "10"</p></li></ul></div><p> 2523 </p><p> 2524 The contents of this file NAME=value assignment pairs and 2525 lines starting with # are comments (no comments are allowed 2526 otherwise). The following variable names are defined: 2527 </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td> 2528 <p>Variable</p> 2529 </td><td> 2530 <p>meaning</p> 2531 </td></tr><tr><td> 2532 <p>DBUS_SESSION_BUS_ADDRESS</p> 2533 </td><td> 2534 <p>the actual address of the server socket</p> 2535 </td></tr><tr><td> 2536 <p>DBUS_SESSION_BUS_PID</p> 2537 </td><td> 2538 <p>the PID of the server process</p> 2539 </td></tr><tr><td> 2540 <p>DBUS_SESSION_BUS_WINDOWID</p> 2541 </td><td> 2542 <p>the window ID</p> 2543 </td></tr></tbody></table></div><p> 2544 </p><p> 2545 At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present 2546 in this file. 2547 </p><p> 2548 Failure to open this file MUST be interpreted as absence of a 2549 running server. Therefore, the implementation MUST proceed to 2550 attempting to launch a new bus server if the file cannot be 2551 opened. 2552 </p><p> 2553 However, success in opening this file MUST NOT lead to the 2554 conclusion that the server is running. Thus, a failure to connect to 2555 the bus address obtained by the alternative method MUST NOT be 2556 considered a fatal error. If the connection cannot be established, 2557 the implementation MUST proceed to check the X selection settings or 2558 to start the server on its own. 2559 </p><p> 2560 If the implementation concludes that the D-Bus server is not 2561 running it MUST attempt to start a new server and it MUST also 2562 ensure that the daemon started as an effect of the "autolaunch" 2563 mechanism provides the lookup mechanisms described above, so 2564 subsequent calls can locate the newly started server. The 2565 implementation MUST also ensure that if two or more concurrent 2566 initiations happen, only one server remains running and all other 2567 initiations are able to obtain the address of this server and 2568 connect to it. In other words, the implementation MUST ensure that 2569 the X selection is not present when it attempts to set it, without 2570 allowing another process to set the selection between the 2571 verification and the setting (e.g., by using XGrabServer / 2572 XungrabServer). 2573 </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp5724640"></a></h5></div></div></div><p> 2574 On Unix systems, the session bus should search for .service files 2575 in <code class="literal">$XDG_DATA_DIRS/dbus-1/services</code> as defined 2576 by the 2577 <a class="ulink" href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html" target="_top">XDG Base Directory Specification</a>. 2578 Implementations may also search additional locations, which 2579 should be searched with lower priority than anything in 2580 XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults; 2581 for example, the reference implementation also 2582 looks in <code class="literal">${datadir}/dbus-1/services</code> as 2583 set at compile time. 2584 </p><p> 2585 As described in the XDG Base Directory Specification, software 2586 packages should install their session .service files to their 2587 configured <code class="literal">${datadir}/dbus-1/services</code>, 2588 where <code class="literal">${datadir}</code> is as defined by the GNU 2589 coding standards. System administrators or users can arrange 2590 for these service files to be read by setting XDG_DATA_DIRS or by 2591 symlinking them into the default locations. 2592 </p></div></div><div class="sect3" title="System message bus"><div class="titlepage"><div><div><h4 class="title"><a name="message-bus-types-system"></a>System message bus</h4></div></div></div><p> 2593 A computer may have a <em class="firstterm">system message bus</em>, 2594 accessible to all applications on the system. This message bus may be 2595 used to broadcast system events, such as adding new hardware devices, 2596 changes in the printer queue, and so forth. 2597 </p><p> 2598 The address of the system message bus is given 2599 in the <code class="literal">DBUS_SYSTEM_BUS_ADDRESS</code> environment 2600 variable. If that variable is not set, applications should try 2601 to connect to the well-known address 2602 <code class="literal">unix:path=/var/run/dbus/system_bus_socket</code>. 2603 <sup>[<a name="idp5733888" href="#ftn.idp5733888" class="footnote">2</a>]</sup> 2604 </p><p> 2605 On Unix systems, the system bus should default to searching 2606 for .service files in 2607 <code class="literal">/usr/local/share/dbus-1/system-services</code>, 2608 <code class="literal">/usr/share/dbus-1/system-services</code> and 2609 <code class="literal">/lib/dbus-1/system-services</code>, with that order 2610 of precedence. It may also search other implementation-specific 2611 locations, but should not vary these locations based on environment 2612 variables. 2613 <sup>[<a name="idp5738096" href="#ftn.idp5738096" class="footnote">3</a>]</sup> 2614 </p><p> 2615 Software packages should install their system .service 2616 files to their configured 2617 <code class="literal">${datadir}/dbus-1/system-services</code>, 2618 where <code class="literal">${datadir}</code> is as defined by the GNU 2619 coding standards. System administrators can arrange 2620 for these service files to be read by editing the system bus' 2621 configuration file or by symlinking them into the default 2622 locations. 2623 </p></div></div><div class="sect2" title="Message Bus Messages"><div class="titlepage"><div><div><h3 class="title"><a name="message-bus-messages"></a>Message Bus Messages</h3></div></div></div><p> 2624 The special message bus name <code class="literal">org.freedesktop.DBus</code> 2625 responds to a number of additional messages. 2626 </p><div class="sect3" title="org.freedesktop.DBus.Hello"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-hello"></a><code class="literal">org.freedesktop.DBus.Hello</code></h4></div></div></div><p> 2627 As a method: 2628 </p><pre class="programlisting"> 2629 STRING Hello () 2630 </pre><p> 2631 Reply arguments: 2632 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique name assigned to the connection</td></tr></tbody></table></div><p> 2633 </p><p> 2634 Before an application is able to send messages to other applications 2635 it must send the <code class="literal">org.freedesktop.DBus.Hello</code> message 2636 to the message bus to obtain a unique name. If an application without 2637 a unique name tries to send a message to another application, or a 2638 message to the message bus itself that isn't the 2639 <code class="literal">org.freedesktop.DBus.Hello</code> message, it will be 2640 disconnected from the bus. 2641 </p><p> 2642 There is no corresponding "disconnect" request; if a client wishes to 2643 disconnect from the bus, it simply closes the socket (or other 2644 communication channel). 2645 </p></div><div class="sect3" title="org.freedesktop.DBus.ListNames"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-names"></a><code class="literal">org.freedesktop.DBus.ListNames</code></h4></div></div></div><p> 2646 As a method: 2647 </p><pre class="programlisting"> 2648 ARRAY of STRING ListNames () 2649 </pre><p> 2650 Reply arguments: 2651 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>ARRAY of STRING</td><td>Array of strings where each string is a bus name</td></tr></tbody></table></div><p> 2652 </p><p> 2653 Returns a list of all currently-owned names on the bus. 2654 </p></div><div class="sect3" title="org.freedesktop.DBus.ListActivatableNames"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-list-activatable-names"></a><code class="literal">org.freedesktop.DBus.ListActivatableNames</code></h4></div></div></div><p> 2655 As a method: 2656 </p><pre class="programlisting"> 2657 ARRAY of STRING ListActivatableNames () 2658 </pre><p> 2659 Reply arguments: 2660 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>ARRAY of STRING</td><td>Array of strings where each string is a bus name</td></tr></tbody></table></div><p> 2661 </p><p> 2662 Returns a list of all names that can be activated on the bus. 2663 </p></div><div class="sect3" title="org.freedesktop.DBus.NameHasOwner"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-exists"></a><code class="literal">org.freedesktop.DBus.NameHasOwner</code></h4></div></div></div><p> 2664 As a method: 2665 </p><pre class="programlisting"> 2666 BOOLEAN NameHasOwner (in STRING name) 2667 </pre><p> 2668 Message arguments: 2669 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name to check</td></tr></tbody></table></div><p> 2670 Reply arguments: 2671 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>BOOLEAN</td><td>Return value, true if the name exists</td></tr></tbody></table></div><p> 2672 </p><p> 2673 Checks if the specified name exists (currently has an owner). 2674 </p></div><div class="sect3" title="org.freedesktop.DBus.NameOwnerChanged"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-owner-changed"></a><code class="literal">org.freedesktop.DBus.NameOwnerChanged</code></h4></div></div></div><p> 2675 This is a signal: 2676 </p><pre class="programlisting"> 2677 NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner) 2678 </pre><p> 2679 Message arguments: 2680 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name with a new owner</td></tr><tr><td>1</td><td>STRING</td><td>Old owner or empty string if none</td></tr><tr><td>2</td><td>STRING</td><td>New owner or empty string if none</td></tr></tbody></table></div><p> 2681 </p><p> 2682 This signal indicates that the owner of a name has changed. 2683 It's also the signal to use to detect the appearance of 2684 new names on the bus. 2685 </p></div><div class="sect3" title="org.freedesktop.DBus.NameLost"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-lost"></a><code class="literal">org.freedesktop.DBus.NameLost</code></h4></div></div></div><p> 2686 This is a signal: 2687 </p><pre class="programlisting"> 2688 NameLost (STRING name) 2689 </pre><p> 2690 Message arguments: 2691 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name which was lost</td></tr></tbody></table></div><p> 2692 </p><p> 2693 This signal is sent to a specific application when it loses 2694 ownership of a name. 2695 </p></div><div class="sect3" title="org.freedesktop.DBus.NameAcquired"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-name-acquired"></a><code class="literal">org.freedesktop.DBus.NameAcquired</code></h4></div></div></div><p> 2696 This is a signal: 2697 </p><pre class="programlisting"> 2698 NameAcquired (STRING name) 2699 </pre><p> 2700 Message arguments: 2701 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name which was acquired</td></tr></tbody></table></div><p> 2702 </p><p> 2703 This signal is sent to a specific application when it gains 2704 ownership of a name. 2705 </p></div><div class="sect3" title="org.freedesktop.DBus.StartServiceByName"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-start-service-by-name"></a><code class="literal">org.freedesktop.DBus.StartServiceByName</code></h4></div></div></div><p> 2706 As a method: 2707 </p><pre class="programlisting"> 2708 UINT32 StartServiceByName (in STRING name, in UINT32 flags) 2709 </pre><p> 2710 Message arguments: 2711 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name of the service to start</td></tr><tr><td>1</td><td>UINT32</td><td>Flags (currently not used)</td></tr></tbody></table></div><p> 2712 Reply arguments: 2713 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Return value</td></tr></tbody></table></div><p> 2714 Tries to launch the executable associated with a name. For more information, see <a class="xref" href="#message-bus-starting-services" title="Message Bus Starting Services">the section called “Message Bus Starting Services”</a>. 2715 2716 </p><p> 2717 The return value can be one of the following values: 2718 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Identifier</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>DBUS_START_REPLY_SUCCESS</td><td>1</td><td>The service was successfully started.</td></tr><tr><td>DBUS_START_REPLY_ALREADY_RUNNING</td><td>2</td><td>A connection already owns the given name.</td></tr></tbody></table></div><p> 2719 </p></div><div class="sect3" title="org.freedesktop.DBus.UpdateActivationEnvironment"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-update-activation-environment"></a><code class="literal">org.freedesktop.DBus.UpdateActivationEnvironment</code></h4></div></div></div><p> 2720 As a method: 2721 </p><pre class="programlisting"> 2722 UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment) 2723 </pre><p> 2724 Message arguments: 2725 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>ARRAY of DICT<STRING,STRING></td><td>Environment to add or update</td></tr></tbody></table></div><p> 2726 Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services. 2727 </p><p> 2728 Some bus instances, such as the standard system bus, may disable access to this method for some or all callers. 2729 </p><p> 2730 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. 2731 </p></div><div class="sect3" title="org.freedesktop.DBus.GetNameOwner"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-name-owner"></a><code class="literal">org.freedesktop.DBus.GetNameOwner</code></h4></div></div></div><p> 2732 As a method: 2733 </p><pre class="programlisting"> 2734 STRING GetNameOwner (in STRING name) 2735 </pre><p> 2736 Message arguments: 2737 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Name to get the owner of</td></tr></tbody></table></div><p> 2738 Reply arguments: 2739 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Return value, a unique connection name</td></tr></tbody></table></div><p> 2740 Returns the unique connection name of the primary owner of the name 2741 given. If the requested name doesn't have an owner, returns a 2742 <code class="literal">org.freedesktop.DBus.Error.NameHasNoOwner</code> error. 2743 </p></div><div class="sect3" title="org.freedesktop.DBus.GetConnectionUnixUser"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-connection-unix-user"></a><code class="literal">org.freedesktop.DBus.GetConnectionUnixUser</code></h4></div></div></div><p> 2744 As a method: 2745 </p><pre class="programlisting"> 2746 UINT32 GetConnectionUnixUser (in STRING bus_name) 2747 </pre><p> 2748 Message arguments: 2749 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique or well-known bus name of the connection to 2750 query, such as <code class="literal">:12.34</code> or 2751 <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p> 2752 Reply arguments: 2753 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Unix user ID</td></tr></tbody></table></div><p> 2754 Returns the Unix user ID of the process connected to the server. If 2755 unable to determine it (for instance, because the process is not on the 2756 same machine as the bus daemon), an error is returned. 2757 </p></div><div class="sect3" title="org.freedesktop.DBus.GetConnectionUnixProcessID"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-connection-unix-process-id"></a><code class="literal">org.freedesktop.DBus.GetConnectionUnixProcessID</code></h4></div></div></div><p> 2758 As a method: 2759 </p><pre class="programlisting"> 2760 UINT32 GetConnectionUnixProcessID (in STRING bus_name) 2761 </pre><p> 2762 Message arguments: 2763 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique or well-known bus name of the connection to 2764 query, such as <code class="literal">:12.34</code> or 2765 <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p> 2766 Reply arguments: 2767 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>UINT32</td><td>Unix process id</td></tr></tbody></table></div><p> 2768 Returns the Unix process ID of the process connected to the server. If 2769 unable to determine it (for instance, because the process is not on the 2770 same machine as the bus daemon), an error is returned. 2771 </p></div><div class="sect3" title="org.freedesktop.DBus.AddMatch"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-add-match"></a><code class="literal">org.freedesktop.DBus.AddMatch</code></h4></div></div></div><p> 2772 As a method: 2773 </p><pre class="programlisting"> 2774 AddMatch (in STRING rule) 2775 </pre><p> 2776 Message arguments: 2777 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Match rule to add to the connection</td></tr></tbody></table></div><p> 2778 Adds a match rule to match messages going through the message bus (see <a class="xref" href="#message-bus-routing-match-rules" title="Match Rules">the section called “Match Rules”</a>). 2779 If the bus does not have enough resources the <code class="literal">org.freedesktop.DBus.Error.OOM</code> 2780 error is returned. 2781 </p></div><div class="sect3" title="org.freedesktop.DBus.RemoveMatch"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-remove-match"></a><code class="literal">org.freedesktop.DBus.RemoveMatch</code></h4></div></div></div><p> 2782 As a method: 2783 </p><pre class="programlisting"> 2784 RemoveMatch (in STRING rule) 2785 </pre><p> 2786 Message arguments: 2787 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Match rule to remove from the connection</td></tr></tbody></table></div><p> 2788 Removes the first rule that matches (see <a class="xref" href="#message-bus-routing-match-rules" title="Match Rules">the section called “Match Rules”</a>). 2789 If the rule is not found the <code class="literal">org.freedesktop.DBus.Error.MatchRuleNotFound</code> 2790 error is returned. 2791 </p></div><div class="sect3" title="org.freedesktop.DBus.GetId"><div class="titlepage"><div><div><h4 class="title"><a name="bus-messages-get-id"></a><code class="literal">org.freedesktop.DBus.GetId</code></h4></div></div></div><p> 2792 As a method: 2793 </p><pre class="programlisting"> 2794 GetId (out STRING id) 2795 </pre><p> 2796 Reply arguments: 2797 </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Argument</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>STRING</td><td>Unique ID identifying the bus daemon</td></tr></tbody></table></div><p> 2798 Gets the unique ID of the bus. The unique ID here is shared among all addresses the 2799 bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in 2800 <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a>. Each address the bus is listening on also has its own unique 2801 ID, as described in <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>. The per-bus and per-address IDs are not related. 2802 There is also a per-machine ID, described in <a class="xref" href="#standard-interfaces-peer" title="org.freedesktop.DBus.Peer">the section called “<code class="literal">org.freedesktop.DBus.Peer</code>”</a> and returned 2803 by org.freedesktop.DBus.Peer.GetMachineId(). 2804 For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session. 2805 </p></div></div></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a name="idp5904720"></a>Glossary</h2></div></div></div><p> 2806 This glossary defines some of the terms used in this specification. 2807 </p><dl><dt><a name="term-bus-name"></a>Bus Name</dt><dd><p> 2808 The message bus maintains an association between names and 2809 connections. (Normally, there's one connection per application.) A 2810 bus name is simply an identifier used to locate connections. For 2811 example, the hypothetical <code class="literal">com.yoyodyne.Screensaver</code> 2812 name might be used to send a message to a screensaver from Yoyodyne 2813 Corporation. An application is said to <em class="firstterm">own</em> a 2814 name if the message bus has associated the application's connection 2815 with the name. Names may also have <em class="firstterm">queued 2816 owners</em> (see <a class="xref" href="#term-queued-owner" title="Queued Name Owner">Queued Name Owner</a>). 2817 The bus assigns a unique name to each connection, 2818 see <a class="xref" href="#term-unique-name" title="Unique Connection Name">Unique Connection Name</a>. Other names 2819 can be thought of as "well-known names" and are 2820 used to find applications that offer specific functionality. 2821 </p><p> 2822 See <a class="xref" href="#message-protocol-names-bus" title="Bus names">the section called “Bus names”</a> for details of 2823 the syntax and naming conventions for bus names. 2824 </p></dd><dt><a name="term-message"></a>Message</dt><dd><p> 2825 A message is the atomic unit of communication via the D-Bus 2826 protocol. It consists of a <em class="firstterm">header</em> and a 2827 <em class="firstterm">body</em>; the body is made up of 2828 <em class="firstterm">arguments</em>. 2829 </p></dd><dt><a name="term-message-bus"></a>Message Bus</dt><dd><p> 2830 The message bus is a special application that forwards 2831 or routes messages between a group of applications 2832 connected to the message bus. It also manages 2833 <em class="firstterm">names</em> used for routing 2834 messages. 2835 </p></dd><dt><a name="term-name"></a>Name</dt><dd><p> 2836 See <a class="xref" href="#term-bus-name" title="Bus Name">Bus Name</a>. "Name" may 2837 also be used to refer to some of the other names 2838 in D-Bus, such as interface names. 2839 </p></dd><dt><a name="namespace"></a>Namespace</dt><dd><p> 2840 Used to prevent collisions when defining new interfaces, bus names 2841 etc. The convention used is the same one Java uses for defining 2842 classes: a reversed domain name. 2843 See <a class="xref" href="#message-protocol-names-bus" title="Bus names">the section called “Bus names”</a>, 2844 <a class="xref" href="#message-protocol-names-interface" title="Interface names">the section called “Interface names”</a>, 2845 <a class="xref" href="#message-protocol-names-error" title="Error names">the section called “Error names”</a>, 2846 <a class="xref" href="#message-protocol-marshaling-object-path" title="Valid Object Paths">the section called “Valid Object Paths”</a>. 2847 </p></dd><dt><a name="term-object"></a>Object</dt><dd><p> 2848 Each application contains <em class="firstterm">objects</em>, which have 2849 <em class="firstterm">interfaces</em> and 2850 <em class="firstterm">methods</em>. Objects are referred to by a name, 2851 called a <em class="firstterm">path</em>. 2852 </p></dd><dt><a name="one-to-one"></a>One-to-One</dt><dd><p> 2853 An application talking directly to another application, without going 2854 through a message bus. One-to-one connections may be "peer to peer" or 2855 "client to server." The D-Bus protocol has no concept of client 2856 vs. server after a connection has authenticated; the flow of messages 2857 is symmetrical (full duplex). 2858 </p></dd><dt><a name="term-path"></a>Path</dt><dd><p> 2859 Object references (object names) in D-Bus are organized into a 2860 filesystem-style hierarchy, so each object is named by a path. As in 2861 LDAP, there's no difference between "files" and "directories"; a path 2862 can refer to an object, while still having child objects below it. 2863 </p></dd><dt><a name="term-queued-owner"></a>Queued Name Owner</dt><dd><p> 2864 Each bus name has a primary owner; messages sent to the name go to the 2865 primary owner. However, certain names also maintain a queue of 2866 secondary owners "waiting in the wings." If the primary owner releases 2867 the name, then the first secondary owner in the queue automatically 2868 becomes the new owner of the name. 2869 </p></dd><dt><a name="term-service"></a>Service</dt><dd><p> 2870 A service is an executable that can be launched by the bus daemon. 2871 Services normally guarantee some particular features, for example they 2872 may guarantee that they will request a specific name such as 2873 "org.freedesktop.Screensaver", have a singleton object 2874 "/org/freedesktop/Application", and that object will implement the 2875 interface "org.freedesktop.ScreensaverControl". 2876 </p></dd><dt><a name="term-service-description-files"></a>Service Description Files</dt><dd><p> 2877 ".service files" tell the bus about service applications that can be 2878 launched (see <a class="xref" href="#term-service" title="Service">Service</a>). Most importantly they 2879 provide a mapping from bus names to services that will request those 2880 names when they start up. 2881 </p></dd><dt><a name="term-unique-name"></a>Unique Connection Name</dt><dd><p> 2882 The special name automatically assigned to each connection by the 2883 message bus. This name will never change owner, and will be unique 2884 (never reused during the lifetime of the message bus). 2885 It will begin with a ':' character. 2886 </p></dd></dl></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idp5281040" href="#idp5281040" class="para">1</a>] </sup>Lockfiles are used instead of real file 2887 locking <code class="literal">fcntl()</code> because real locking 2888 implementations are still flaky on network 2889 filesystems.</p></div><div class="footnote"><p><sup>[<a id="ftn.idp5733888" href="#idp5733888" class="para">2</a>] </sup> 2890 The D-Bus reference implementation actually honors the 2891 <code class="literal">$(localstatedir)</code> configure option 2892 for this address, on both client and server side. 2893 </p></div><div class="footnote"><p><sup>[<a id="ftn.idp5738096" href="#idp5738096" class="para">3</a>] </sup> 2894 The system bus is security-sensitive and is typically executed 2895 by an init system with a clean environment. Its launch helper 2896 process is particularly security-sensitive, and specifically 2897 clears its own environment. 2898 </p></div></div></div></body></html> 2899