| <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.75.2"></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> | |
| <code class="email"><<a class="email" href="mailto:hp@pobox.com">hp@pobox.com</a>></code><br> | |
| </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> | |
| <code class="email"><<a class="email" href="mailto:andersca@codefactory.se">andersca@codefactory.se</a>></code><br> | |
| </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> | |
| <code class="email"><<a class="email" href="mailto:alexl@redhat.com">alexl@redhat.com</a>></code><br> | |
| </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> | |
| <code class="email"><<a class="email" href="mailto:sven@imendio.com">sven@imendio.com</a>></code><br> | |
| </p></div></div></div></div></div><div><p class="releaseinfo">Version 0.15</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.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="#message-protocol">Message Protocol</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><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-tcp-sockets">TCP Sockets</a></span></dt><dt><span class="sect2"><a href="#transports-nonce-tcp-sockets">Nonce-secured TCP Sockets</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="#naming-conventions">Naming Conventions</a></span></dt><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></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="#idp5788992">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> | |
| D-Bus is a system for low-latency, low-overhead, easy to use | |
| interprocess communication (IPC). In more detail: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| D-Bus is <span class="emphasis"><em>low-latency</em></span> because it is designed | |
| to avoid round trips and allow asynchronous operation, much like | |
| the X protocol. | |
| </p></li><li class="listitem"><p> | |
| D-Bus is <span class="emphasis"><em>low-overhead</em></span> because it uses a | |
| binary protocol, and does not have to convert to and from a text | |
| format such as XML. Because D-Bus is intended for potentially | |
| high-resolution same-machine IPC, not primarily for Internet IPC, | |
| this is an interesting optimization. | |
| </p></li><li class="listitem"><p> | |
| D-Bus is <span class="emphasis"><em>easy to use</em></span> because it works in terms | |
| of <em class="firstterm">messages</em> rather than byte streams, and | |
| automatically handles a lot of the hard IPC issues. Also, the D-Bus | |
| library is designed to be wrapped in a way that lets developers use | |
| their framework's existing object/type system, rather than learning | |
| a new one specifically for IPC. | |
| </p></li></ul></div><p> | |
| </p><p> | |
| The base D-Bus protocol is a one-to-one (peer-to-peer or client-server) | |
| protocol, specified in <a class="xref" href="#message-protocol" title="Message Protocol">the section called “Message Protocol”</a>. That is, it is | |
| a system for one application to talk to a single other | |
| application. However, the primary intended application of the protocol is the | |
| 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 | |
| accepts connections from multiple other applications, and forwards | |
| messages among them. | |
| </p><p> | |
| Uses of D-Bus include notification of system changes (notification of when | |
| a camera is plugged in to a computer, or a new version of some software | |
| has been installed), or desktop interoperability, for example a file | |
| monitoring service or a configuration service. | |
| </p><p> | |
| D-Bus is designed for two specific use cases: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| A "system bus" for notifications from the system to user sessions, | |
| and to allow the system to request input from user sessions. | |
| </p></li><li class="listitem"><p> | |
| A "session bus" used to implement desktop environments such as | |
| GNOME and KDE. | |
| </p></li></ul></div><p> | |
| D-Bus is not intended to be a generic IPC system for any possible | |
| application, and intentionally omits many features found in other | |
| IPC systems for this reason. | |
| </p><p> | |
| At the same time, the bus daemons offer a number of features not found in | |
| other IPC systems, such as single-owner "bus names" (similar to X | |
| selections), on-demand startup of services, and security policies. | |
| In many ways, these features are the primary motivation for developing | |
| D-Bus; other systems would have sufficed if IPC were the only goal. | |
| </p><p> | |
| D-Bus may turn out to be useful in unanticipated applications, but future | |
| versions of this spec and the reference implementation probably will not | |
| incorporate features that interfere with the core use cases. | |
| </p><p> | |
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |
| document are to be interpreted as described in RFC 2119. However, the | |
| document could use a serious audit to be sure it makes sense to do | |
| so. Also, they are not capitalized. | |
| </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> | |
| The D-Bus protocol is frozen (only compatible extensions are allowed) as | |
| of November 8, 2006. However, this specification could still use a fair | |
| bit of work to make interoperable reimplementation possible without | |
| reference to the D-Bus reference implementation. Thus, this | |
| specification is not marked 1.0. To mark it 1.0, we'd like to see | |
| someone invest significant effort in clarifying the specification | |
| language, and growing the specification to cover more aspects of the | |
| reference implementation's behavior. | |
| </p><p> | |
| Until this work is complete, any attempt to reimplement D-Bus will | |
| probably require looking at the reference implementation and/or asking | |
| questions on the D-Bus mailing list about intended behavior. | |
| Questions on the list are very welcome. | |
| </p><p> | |
| Nonetheless, this document should be a useful starting point and is | |
| to our knowledge accurate, though incomplete. | |
| </p></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> | |
| A <em class="firstterm">message</em> consists of a | |
| <em class="firstterm">header</em> and a <em class="firstterm">body</em>. If you | |
| think of a message as a package, the header is the address, and the body | |
| contains the package contents. The message delivery system uses the header | |
| information to figure out where to send the message and how to interpret | |
| it; the recipient interprets the body of the message. | |
| </p><p> | |
| The body of the message is made up of zero or more | |
| <em class="firstterm">arguments</em>, which are typed values, such as an | |
| integer or a byte array. | |
| </p><p> | |
| Both header and body use the same type system and format for | |
| serializing data. Each type of value has a wire format. | |
| Converting a value from some other representation into the wire | |
| format is called <em class="firstterm">marshaling</em> and converting | |
| it back from the wire format is <em class="firstterm">unmarshaling</em>. | |
| </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> | |
| The D-Bus protocol does not include type tags in the marshaled data; a | |
| block of marshaled values must have a known <em class="firstterm">type | |
| signature</em>. The type signature is made up of <em class="firstterm">type | |
| codes</em>. A type code is an ASCII character representing the | |
| type of a value. Because ASCII characters are used, the type signature | |
| will always form a valid ASCII string. A simple string compare | |
| determines whether two type signatures are equivalent. | |
| </p><p> | |
| As a simple example, the type code for 32-bit integer (<code class="literal">INT32</code>) is | |
| the ASCII character 'i'. So the signature for a block of values | |
| containing a single <code class="literal">INT32</code> would be: | |
| </p><pre class="programlisting"> | |
| "i" | |
| </pre><p> | |
| A block of values containing two <code class="literal">INT32</code> would have this signature: | |
| </p><pre class="programlisting"> | |
| "ii" | |
| </pre><p> | |
| </p><p> | |
| All <em class="firstterm">basic</em> types work like | |
| <code class="literal">INT32</code> in this example. To marshal and unmarshal | |
| basic types, you simply read one value from the data | |
| block corresponding to each type code in the signature. | |
| In addition to basic types, there are four <em class="firstterm">container</em> | |
| types: <code class="literal">STRUCT</code>, <code class="literal">ARRAY</code>, <code class="literal">VARIANT</code>, | |
| and <code class="literal">DICT_ENTRY</code>. | |
| </p><p> | |
| <code class="literal">STRUCT</code> has a type code, ASCII character 'r', but this type | |
| code does not appear in signatures. Instead, ASCII characters | |
| '(' and ')' are used to mark the beginning and end of the struct. | |
| So for example, a struct containing two integers would have this | |
| signature: | |
| </p><pre class="programlisting"> | |
| "(ii)" | |
| </pre><p> | |
| Structs can be nested, so for example a struct containing | |
| an integer and another struct: | |
| </p><pre class="programlisting"> | |
| "(i(ii))" | |
| </pre><p> | |
| The value block storing that struct would contain three integers; the | |
| type signature allows you to distinguish "(i(ii))" from "((ii)i)" or | |
| "(iii)" or "iii". | |
| </p><p> | |
| The <code class="literal">STRUCT</code> type code 'r' is not currently used in the D-Bus protocol, | |
| but is useful in code that implements the protocol. This type code | |
| is specified to allow such code to interoperate in non-protocol contexts. | |
| </p><p> | |
| Empty structures are not allowed; there must be at least one | |
| type code between the parentheses. | |
| </p><p> | |
| <code class="literal">ARRAY</code> has ASCII character 'a' as type code. The array type code must be | |
| followed by a <em class="firstterm">single complete type</em>. The single | |
| complete type following the array is the type of each array element. So | |
| the simple example is: | |
| </p><pre class="programlisting"> | |
| "ai" | |
| </pre><p> | |
| which is an array of 32-bit integers. But an array can be of any type, | |
| such as this array-of-struct-with-two-int32-fields: | |
| </p><pre class="programlisting"> | |
| "a(ii)" | |
| </pre><p> | |
| Or this array of array of integer: | |
| </p><pre class="programlisting"> | |
| "aai" | |
| </pre><p> | |
| </p><p> | |
| The phrase <em class="firstterm">single complete type</em> deserves some | |
| definition. A single complete type is a basic type code, a variant type code, | |
| an array with its element type, or a struct with its fields. | |
| So the following signatures are not single complete types: | |
| </p><pre class="programlisting"> | |
| "aa" | |
| </pre><p> | |
| </p><pre class="programlisting"> | |
| "(ii" | |
| </pre><p> | |
| </p><pre class="programlisting"> | |
| "ii)" | |
| </pre><p> | |
| And the following signatures contain multiple complete types: | |
| </p><pre class="programlisting"> | |
| "ii" | |
| </pre><p> | |
| </p><pre class="programlisting"> | |
| "aiai" | |
| </pre><p> | |
| </p><pre class="programlisting"> | |
| "(ii)(ii)" | |
| </pre><p> | |
| Note however that a single complete type may <span class="emphasis"><em>contain</em></span> | |
| multiple other single complete types. | |
| </p><p> | |
| <code class="literal">VARIANT</code> has ASCII character 'v' as its type code. A marshaled value of | |
| type <code class="literal">VARIANT</code> will have the signature of a single complete type as part | |
| of the <span class="emphasis"><em>value</em></span>. This signature will be followed by a | |
| marshaled value of that type. | |
| </p><p> | |
| A <code class="literal">DICT_ENTRY</code> works exactly like a struct, but rather | |
| than parentheses it uses curly braces, and it has more restrictions. | |
| The restrictions are: it occurs only as an array element type; it has | |
| exactly two single complete types inside the curly braces; the first | |
| single complete type (the "key") must be a basic type rather than a | |
| container type. Implementations must not accept dict entries outside of | |
| arrays, must not accept dict entries with zero, one, or more than two | |
| fields, and must not accept dict entries with non-basic-typed keys. A | |
| dict entry is always a key-value pair. | |
| </p><p> | |
| The first field in the <code class="literal">DICT_ENTRY</code> is always the key. | |
| A message is considered corrupt if the same key occurs twice in the same | |
| array of <code class="literal">DICT_ENTRY</code>. However, for performance reasons | |
| implementations are not required to reject dicts with duplicate keys. | |
| </p><p> | |
| In most languages, an array of dict entry would be represented as a | |
| map, hash table, or dict object. | |
| </p><p> | |
| The following table summarizes the D-Bus types. | |
| </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</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)</td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>104 (ASCII 'h')</td><td>Unix file descriptor</td></tr></tbody></table></div><p> | |
| </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> | |
| Given a type signature, a block of bytes can be converted into typed | |
| values. This section describes the format of the block of bytes. Byte | |
| order and alignment issues are handled uniformly for all D-Bus types. | |
| </p><p> | |
| A block of bytes has an associated byte order. The byte order | |
| has to be discovered in some way; for D-Bus messages, the | |
| byte order is part of the message header as described in | |
| <a class="xref" href="#message-protocol-messages" title="Message Format">the section called “Message Format”</a>. For now, assume | |
| that the byte order is known to be either little endian or big | |
| endian. | |
| </p><p> | |
| Each value in a block of bytes is aligned "naturally," for example | |
| 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an | |
| 8-byte boundary. To properly align a value, <em class="firstterm">alignment | |
| padding</em> may be necessary. The alignment padding must always | |
| be the minimum required padding to properly align the following value; | |
| and it must always be made up of nul bytes. The alignment padding must | |
| not be left uninitialized (it can't contain garbage), and more padding | |
| than required must not be used. | |
| </p><p> | |
| Given all this, the types are marshaled on the wire as follows: | |
| </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 | |
| length in bytes excluding its terminating nul, followed by | |
| non-nul string data of the given length, followed by a terminating nul | |
| byte. | |
| </td><td> | |
| 4 (for the length) | |
| </td></tr><tr><td><code class="literal">OBJECT_PATH</code></td><td>Exactly the same as <code class="literal">STRING</code> except the | |
| content must be a valid object path (see below). | |
| </td><td> | |
| 4 (for the length) | |
| </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 | |
| byte (thus signatures have a maximum length of 255) | |
| and the content must be a valid signature (see below). | |
| </td><td> | |
| 1 | |
| </td></tr><tr><td><code class="literal">ARRAY</code></td><td> | |
| A <code class="literal">UINT32</code> giving the length of the array data in bytes, followed by | |
| alignment padding to the alignment boundary of the array element type, | |
| followed by each array element. The array length is from the | |
| end of the alignment padding to the end of the last element, | |
| i.e. it does not include the padding after the length, | |
| or any padding after the last element. | |
| Arrays have a maximum length defined to be 2 to the 26th power or | |
| 67108864. Implementations must not send or accept arrays exceeding this | |
| length. | |
| </td><td> | |
| 4 (for the length) | |
| </td></tr><tr><td><code class="literal">STRUCT</code></td><td> | |
| A struct must start on an 8-byte boundary regardless of the | |
| type of the struct fields. The struct value consists of each | |
| field marshaled in sequence starting from that 8-byte | |
| alignment boundary. | |
| </td><td> | |
| 8 | |
| </td></tr><tr><td><code class="literal">VARIANT</code></td><td> | |
| A variant type has a marshaled | |
| <code class="literal">SIGNATURE</code> followed by a marshaled | |
| value with the type given in the signature. Unlike | |
| a message signature, the variant signature can | |
| contain only a single complete type. So "i", "ai" | |
| or "(ii)" is OK, but "ii" is not. Use of variants may not | |
| cause a total message depth to be larger than 64, including | |
| other container types such as structures. | |
| </td><td> | |
| 1 (alignment of the signature) | |
| </td></tr><tr><td><code class="literal">DICT_ENTRY</code></td><td> | |
| Identical to STRUCT. | |
| </td><td> | |
| 8 | |
| </td></tr><tr><td><code class="literal">UNIX_FD</code></td><td>32-bit unsigned integer in the message's byte | |
| order. The actual file descriptors need to be | |
| transferred out-of-band via some platform specific | |
| mechanism. On the wire, values of this type store the index to the | |
| file descriptor in the array of file descriptors that | |
| accompany the message.</td><td>4</td></tr></tbody></table></div><p> | |
| </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> | |
| An object path is a name used to refer to an object instance. | |
| Conceptually, each participant in a D-Bus message exchange may have | |
| any number of object instances (think of C++ or Java objects) and each | |
| such instance will have a path. Like a filesystem, the object | |
| instances in an application form a hierarchical tree. | |
| </p><p> | |
| The following rules define a valid object path. Implementations must | |
| not send or accept messages with invalid object paths. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| The path may be of any length. | |
| </p></li><li class="listitem"><p> | |
| The path must begin with an ASCII '/' (integer 47) character, | |
| and must consist of elements separated by slash characters. | |
| </p></li><li class="listitem"><p> | |
| Each element must only contain the ASCII characters | |
| "[A-Z][a-z][0-9]_" | |
| </p></li><li class="listitem"><p> | |
| No element may be the empty string. | |
| </p></li><li class="listitem"><p> | |
| Multiple '/' characters cannot occur in sequence. | |
| </p></li><li class="listitem"><p> | |
| A trailing '/' character is not allowed unless the | |
| path is the root path (a single '/' character). | |
| </p></li></ul></div><p> | |
| </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> | |
| An implementation must not send or accept invalid signatures. | |
| Valid signatures will conform to the following rules: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| The signature ends with a nul byte. | |
| </p></li><li class="listitem"><p> | |
| The signature is a list of single complete types. | |
| Arrays must have element types, and structs must | |
| have both open and close parentheses. | |
| </p></li><li class="listitem"><p> | |
| Only type codes and open and close parentheses are | |
| allowed in the signature. The <code class="literal">STRUCT</code> type code | |
| is not allowed in signatures, because parentheses | |
| are used instead. | |
| </p></li><li class="listitem"><p> | |
| The maximum depth of container type nesting is 32 array type | |
| codes and 32 open parentheses. This implies that the maximum | |
| total depth of recursion is 64, for an "array of array of array | |
| of ... struct of struct of struct of ..." where there are 32 | |
| array and 32 struct. | |
| </p></li><li class="listitem"><p> | |
| The maximum length of a signature is 255. | |
| </p></li><li class="listitem"><p> | |
| Signatures must be nul-terminated. | |
| </p></li></ul></div><p> | |
| </p></div></div><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> | |
| A message consists of a header and a body. The header is a block of | |
| values with a fixed signature and meaning. The body is a separate block | |
| of values, with a signature specified in the header. | |
| </p><p> | |
| The length of the header must be a multiple of 8, allowing the body to | |
| begin on an 8-byte boundary when storing the entire message in a single | |
| buffer. If the header does not naturally end on an 8-byte boundary | |
| up to 7 bytes of nul-initialized alignment padding must be added. | |
| </p><p> | |
| The message body need not end on an 8-byte boundary. | |
| </p><p> | |
| The maximum length of a message, including header, header alignment padding, | |
| and body is 2 to the 27th power or 134217728. Implementations must not | |
| send or accept messages exceeding this size. | |
| </p><p> | |
| The signature of the header is: | |
| </p><pre class="programlisting"> | |
| "yyyyuua(yv)" | |
| </pre><p> | |
| Written out more readably, this is: | |
| </p><pre class="programlisting"> | |
| BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT) | |
| </pre><p> | |
| </p><p> | |
| These values have the following meanings: | |
| </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 | |
| or ASCII 'B' for big-endian. Both header and body are | |
| 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. | |
| Currently-defined types are described below. | |
| </td></tr><tr><td>3rd <code class="literal">BYTE</code></td><td>Bitwise OR of flags. Unknown flags | |
| must be ignored. Currently-defined flags are described below. | |
| </td></tr><tr><td>4th <code class="literal">BYTE</code></td><td>Major protocol version of the sending application. If | |
| the major protocol version of the receiving application does not | |
| match, the applications will not be able to communicate and the | |
| D-Bus connection must be disconnected. The major protocol | |
| version for this version of the specification is 1. | |
| </td></tr><tr><td>1st <code class="literal">UINT32</code></td><td>Length in bytes of the message body, starting | |
| from the end of the header. The header ends after | |
| its alignment padding to an 8-boundary. | |
| </td></tr><tr><td>2nd <code class="literal">UINT32</code></td><td>The serial of this message, used as a cookie | |
| by the sender to identify the reply corresponding | |
| to this request. This must not be zero. | |
| </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 | |
| fields</em> where the byte is the field code, and the | |
| variant is the field value. The message type determines | |
| which fields are required. | |
| </td></tr></tbody></table></div><p> | |
| </p><p> | |
| <em class="firstterm">Message types</em> that can appear in the second byte | |
| of the header are: | |
| </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 | |
| 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> | |
| </p><p> | |
| Flags that can appear in the third byte of the header: | |
| </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 | |
| error replies; the reply can be omitted as an | |
| optimization. However, it is compliant with this specification | |
| to return the reply despite this flag and the only harm | |
| from doing so is extra network traffic. | |
| </td></tr><tr><td><code class="literal">NO_AUTO_START</code></td><td>0x2</td><td>The bus must not launch an owner | |
| for the destination name in response to this message. | |
| </td></tr></tbody></table></div><p> | |
| </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> | |
| The array at the end of the header contains <em class="firstterm">header | |
| fields</em>, where each field is a 1-byte field code followed | |
| by a field value. A header must contain the required header fields for | |
| its message type, and zero or more of any optional header | |
| fields. Future versions of this protocol specification may add new | |
| fields. Implementations must ignore fields they do not | |
| understand. Implementations must not invent their own header fields; | |
| only changes to this specification may introduce new header fields. | |
| </p><p> | |
| Again, if an implementation sees a header field code that it does not | |
| expect, it must ignore that field, as it will be part of a new | |
| (but compatible) version of this specification. This also applies | |
| to known header fields appearing in unexpected messages, for | |
| example: if a signal has a reply serial it must be ignored | |
| even though it has no meaning as of this version of the spec. | |
| </p><p> | |
| However, implementations must not send or accept known header fields | |
| with the wrong type stored in the field value. So for example a | |
| message with an <code class="literal">INTERFACE</code> field of type | |
| <code class="literal">UINT32</code> would be considered corrupt. | |
| </p><p> | |
| Here are the currently-defined header fields: | |
| </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, | |
| or the object a signal is emitted from. | |
| The special path | |
| <code class="literal">/org/freedesktop/DBus/Local</code> is reserved; | |
| implementations should not send messages with this path, | |
| and the reference implementation of the bus daemon will | |
| disconnect any application that attempts to do so. | |
| </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> | |
| The interface to invoke a method call on, or | |
| that a signal is emitted from. Optional for | |
| method calls, required for signals. | |
| The special interface | |
| <code class="literal">org.freedesktop.DBus.Local</code> is reserved; | |
| implementations should not send messages with this | |
| interface, and the reference implementation of the bus | |
| daemon will disconnect any application that attempts to | |
| do so. | |
| </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 | |
| 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. | |
| Only used in combination with the message bus, see | |
| <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. | |
| The message bus fills in this field so it is reliable; the field is | |
| 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. | |
| If omitted, it is assumed to be the | |
| 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 | |
| accompany the message. If omitted, it is assumed | |
| that no Unix file descriptors accompany the | |
| message. The actual file descriptors need to be | |
| transferred via platform specific mechanism | |
| out-of-band. They must be sent at the same time as | |
| part of the message itself. They may not be sent | |
| before the first byte of the message itself is | |
| transferred or after the last byte of the message | |
| itself.</td></tr></tbody></table></div><p> | |
| </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> | |
| The various names in D-Bus messages have some restrictions. | |
| </p><p> | |
| There is a <em class="firstterm">maximum name length</em> | |
| of 255 which applies to bus names, interfaces, and members. | |
| </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> | |
| Interfaces have names with type <code class="literal">STRING</code>, meaning that | |
| they must be valid UTF-8. However, there are also some | |
| additional restrictions that apply to interface names | |
| specifically: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Interface names are composed of 1 or more elements separated by | |
| a period ('.') character. All elements must contain at least | |
| one character. | |
| </p></li><li class="listitem"><p>Each element must only contain the ASCII characters | |
| "[A-Z][a-z][0-9]_" and must not begin with a digit. | |
| </p></li><li class="listitem"><p>Interface names must contain at least one '.' (period) | |
| character (and thus at least two elements). | |
| </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> | |
| </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> | |
| Connections have one or more bus names associated with them. | |
| A connection has exactly one bus name that is a unique connection | |
| name. The unique connection name remains with the connection for | |
| its entire lifetime. | |
| A bus name is of type <code class="literal">STRING</code>, | |
| meaning that it must be valid UTF-8. However, there are also | |
| some additional restrictions that apply to bus names | |
| specifically: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bus names that start with a colon (':') | |
| character are unique connection names. | |
| </p></li><li class="listitem"><p>Bus names are composed of 1 or more elements separated by | |
| a period ('.') character. All elements must contain at least | |
| one character. | |
| </p></li><li class="listitem"><p>Each element must only contain the ASCII characters | |
| "[A-Z][a-z][0-9]_-". Only elements that are part of a unique | |
| connection name may begin with a digit, elements in | |
| other bus names must not begin with a digit. | |
| </p></li><li class="listitem"><p>Bus names must contain at least one '.' (period) | |
| character (and thus at least two elements). | |
| </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> | |
| </p><p> | |
| Note that the hyphen ('-') character is allowed in bus names but | |
| not in interface names. | |
| </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> | |
| Member (i.e. method or signal) names: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Must only contain the ASCII characters | |
| "[A-Z][a-z][0-9]_" and may not begin with a | |
| 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> | |
| </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> | |
| Error names have the same restrictions as interface names. | |
| </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> | |
| Each of the message types (<code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>, <code class="literal">ERROR</code>, and | |
| <code class="literal">SIGNAL</code>) has its own expected usage conventions and header fields. | |
| This section describes these conventions. | |
| </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> | |
| Some messages invoke an operation on a remote object. These are | |
| called method call messages and have the type tag <code class="literal">METHOD_CALL</code>. Such | |
| messages map naturally to methods on objects in a typical program. | |
| </p><p> | |
| A method call message is required to have a <code class="literal">MEMBER</code> header field | |
| indicating the name of the method. Optionally, the message has an | |
| <code class="literal">INTERFACE</code> field giving the interface the method is a part of. In the | |
| absence of an <code class="literal">INTERFACE</code> field, if two interfaces on the same object have | |
| a method with the same name, it is undefined which of the two methods | |
| will be invoked. Implementations may also choose to return an error in | |
| this ambiguous case. However, if a method name is unique | |
| implementations must not require an interface field. | |
| </p><p> | |
| Method call messages also include a <code class="literal">PATH</code> field | |
| indicating the object to invoke the method on. If the call is passing | |
| through a message bus, the message will also have a | |
| <code class="literal">DESTINATION</code> field giving the name of the connection | |
| to receive the message. | |
| </p><p> | |
| When an application handles a method call message, it is required to | |
| return a reply. The reply is identified by a <code class="literal">REPLY_SERIAL</code> header field | |
| indicating the serial number of the <code class="literal">METHOD_CALL</code> being replied to. The | |
| reply can have one of two types; either <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code>. | |
| </p><p> | |
| If the reply has type <code class="literal">METHOD_RETURN</code>, the arguments to the reply message | |
| are the return value(s) or "out parameters" of the method call. | |
| If the reply has type <code class="literal">ERROR</code>, then an "exception" has been thrown, | |
| and the call fails; no return value will be provided. It makes | |
| no sense to send multiple replies to the same method call. | |
| </p><p> | |
| Even if a method call has no return values, a <code class="literal">METHOD_RETURN</code> | |
| reply is required, so the caller will know the method | |
| was successfully processed. | |
| </p><p> | |
| The <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code> reply message must have the <code class="literal">REPLY_SERIAL</code> | |
| header field. | |
| </p><p> | |
| If a <code class="literal">METHOD_CALL</code> message has the flag <code class="literal">NO_REPLY_EXPECTED</code>, | |
| then as an optimization the application receiving the method | |
| call may choose to omit the reply message (regardless of | |
| whether the reply would have been <code class="literal">METHOD_RETURN</code> or <code class="literal">ERROR</code>). | |
| However, it is also acceptable to ignore the <code class="literal">NO_REPLY_EXPECTED</code> | |
| flag and reply anyway. | |
| </p><p> | |
| Unless a message has the flag <code class="literal">NO_AUTO_START</code>, if the | |
| destination name does not exist then a program to own the destination | |
| name will be started before the message is delivered. The message | |
| will be held until the new program is successfully started or has | |
| failed to start; in case of failure, an error will be returned. This | |
| flag is only relevant in the context of a message bus, it is ignored | |
| during one-to-one communication with no intermediate bus. | |
| </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> | |
| APIs for D-Bus may map method calls to a method call in a specific | |
| programming language, such as C++, or may map a method call written | |
| in an IDL to a D-Bus message. | |
| </p><p> | |
| In APIs of this nature, arguments to a method are often termed "in" | |
| (which implies sent in the <code class="literal">METHOD_CALL</code>), or "out" (which implies | |
| returned in the <code class="literal">METHOD_RETURN</code>). Some APIs such as CORBA also have | |
| "inout" arguments, which are both sent and received, i.e. the caller | |
| passes in a value which is modified. Mapped to D-Bus, an "inout" | |
| argument is equivalent to an "in" argument, followed by an "out" | |
| argument. You can't pass things "by reference" over the wire, so | |
| "inout" is purely an illusion of the in-process API. | |
| </p><p> | |
| Given a method with zero or one return values, followed by zero or more | |
| arguments, where each argument may be "in", "out", or "inout", the | |
| caller constructs a message by appending each "in" or "inout" argument, | |
| in order. "out" arguments are not represented in the caller's message. | |
| </p><p> | |
| The recipient constructs a reply by appending first the return value | |
| if any, then each "out" or "inout" argument, in order. | |
| "in" arguments are not represented in the reply message. | |
| </p><p> | |
| Error replies are normally mapped to exceptions in languages that have | |
| exceptions. | |
| </p><p> | |
| In converting from native APIs to D-Bus, it is perhaps nice to | |
| map D-Bus naming conventions ("FooBar") to native conventions | |
| such as "fooBar" or "foo_bar" automatically. This is OK | |
| as long as you can say that the native API is one that | |
| was specifically written for D-Bus. It makes the most sense | |
| when writing object implementations that will be exported | |
| over the bus. Object proxies used to invoke remote D-Bus | |
| objects probably need the ability to call any D-Bus method, | |
| and thus a magic name mapping like this could be a problem. | |
| </p><p> | |
| This specification doesn't require anything of native API bindings; | |
| the preceding is only a suggested convention for consistency | |
| among bindings. | |
| </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> | |
| Unlike method calls, signal emissions have no replies. | |
| A signal emission is simply a single message of type <code class="literal">SIGNAL</code>. | |
| It must have three header fields: <code class="literal">PATH</code> giving the object | |
| the signal was emitted from, plus <code class="literal">INTERFACE</code> and <code class="literal">MEMBER</code> giving | |
| the fully-qualified name of the signal. The <code class="literal">INTERFACE</code> header is required | |
| for signals, though it is optional for method calls. | |
| </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> | |
| Messages of type <code class="literal">ERROR</code> are most commonly replies | |
| to a <code class="literal">METHOD_CALL</code>, but may be returned in reply | |
| to any kind of message. The message bus for example | |
| will return an <code class="literal">ERROR</code> in reply to a signal emission if | |
| the bus does not have enough memory to send the signal. | |
| </p><p> | |
| An <code class="literal">ERROR</code> may have any arguments, but if the first | |
| argument is a <code class="literal">STRING</code>, it must be an error message. | |
| The error message may be logged or shown to the user | |
| in some way. | |
| </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> | |
| This document uses a simple pseudo-IDL to describe particular method | |
| calls and signals. Here is an example of a method call: | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags, | |
| out UINT32 resultcode) | |
| </pre><p> | |
| This means <code class="literal">INTERFACE</code> = org.freedesktop.DBus, <code class="literal">MEMBER</code> = StartServiceByName, | |
| <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 | |
| is <code class="literal">UINT32</code>. Remember that the <code class="literal">MEMBER</code> field can't contain any '.' (period) | |
| characters so it's known that the last part of the name in | |
| the "IDL" is the member name. | |
| </p><p> | |
| In C++ that might end up looking like this: | |
| </p><pre class="programlisting"> | |
| unsigned int org::freedesktop::DBus::StartServiceByName (const char *name, | |
| unsigned int flags); | |
| </pre><p> | |
| or equally valid, the return value could be done as an argument: | |
| </p><pre class="programlisting"> | |
| void org::freedesktop::DBus::StartServiceByName (const char *name, | |
| unsigned int flags, | |
| unsigned int *resultcode); | |
| </pre><p> | |
| It's really up to the API designer how they want to make | |
| this look. You could design an API where the namespace wasn't used | |
| in C++, using STL or Qt, using varargs, or whatever you wanted. | |
| </p><p> | |
| Signals are written as follows: | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.NameLost (STRING name) | |
| </pre><p> | |
| Signals don't specify "in" vs. "out" because only | |
| a single direction is possible. | |
| </p><p> | |
| It isn't especially encouraged to use this lame pseudo-IDL in actual | |
| API implementations; you might use the native notation for the | |
| language you're using, or you might use COM or CORBA IDL, for example. | |
| </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> | |
| For security reasons, the D-Bus protocol should be strictly parsed and | |
| validated, with the exception of defined extension points. Any invalid | |
| protocol or spec violations should result in immediately dropping the | |
| connection without notice to the other end. Exceptions should be | |
| carefully considered, e.g. an exception may be warranted for a | |
| well-understood idiosyncrasy of a widely-deployed implementation. In | |
| cases where the other end of a connection is 100% trusted and known to | |
| be friendly, skipping validation for performance reasons could also make | |
| sense in certain cases. | |
| </p><p> | |
| Generally speaking violations of the "must" requirements in this spec | |
| should be considered possible attempts to exploit security, and violations | |
| of the "should" suggestions should be considered legitimate (though perhaps | |
| they should generate an error in some cases). | |
| </p><p> | |
| The following extension points are built in to D-Bus on purpose and must | |
| not be treated as invalid protocol. The extension points are intended | |
| for use by future versions of this spec, they are not intended for third | |
| parties. At the moment, the only way a third party could extend D-Bus | |
| without breaking interoperability would be to introduce a way to negotiate new | |
| feature support as part of the auth protocol, using EXTENSION_-prefixed | |
| commands. There is not yet a standard way to negotiate features. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| In the authentication protocol (see <a class="xref" href="#auth-protocol" title="Authentication Protocol">the section called “Authentication Protocol”</a>) unknown | |
| commands result in an ERROR rather than a disconnect. This enables | |
| future extensions to the protocol. Commands starting with EXTENSION_ are | |
| reserved for third parties. | |
| </p></li><li class="listitem"><p> | |
| The authentication protocol supports pluggable auth mechanisms. | |
| </p></li><li class="listitem"><p> | |
| The address format (see <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>) supports new | |
| kinds of transport. | |
| </p></li><li class="listitem"><p> | |
| Messages with an unknown type (something other than | |
| <code class="literal">METHOD_CALL</code>, <code class="literal">METHOD_RETURN</code>, | |
| <code class="literal">ERROR</code>, <code class="literal">SIGNAL</code>) are ignored. | |
| Unknown-type messages must still be well-formed in the same way | |
| as the known messages, however. They still have the normal | |
| header and body. | |
| </p></li><li class="listitem"><p> | |
| Header fields with an unknown or unexpected field code must be ignored, | |
| though again they must still be well-formed. | |
| </p></li><li class="listitem"><p> | |
| New standard interfaces (with new methods and signals) can of course be added. | |
| </p></li></ul></div><p> | |
| </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> | |
| Before the flow of messages begins, two applications must | |
| authenticate. A simple plain-text protocol is used for | |
| authentication; this protocol is a SASL profile, and maps fairly | |
| directly from the SASL specification. The message encoding is | |
| NOT used here, only plain text messages. | |
| </p><p> | |
| In examples, "C:" and "S:" indicate lines sent by the client and | |
| server respectively. | |
| </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> | |
| The protocol is a line-based protocol, where each line ends with | |
| \r\n. Each line begins with an all-caps ASCII command name containing | |
| only the character range [A-Z_], a space, then any arguments for the | |
| command, then the \r\n ending the line. The protocol is | |
| case-sensitive. All bytes must be in the ASCII character set. | |
| Commands from the client to the server are as follows: | |
| </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> | |
| From server to client are as follows: | |
| </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> | |
| </p><p> | |
| Unofficial extensions to the command set must begin with the letters | |
| "EXTENSION_", to avoid conflicts with future official commands. | |
| For example, "EXTENSION_COM_MYDOMAIN_DO_STUFF". | |
| </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> | |
| Immediately after connecting to the server, the client must send a | |
| single nul byte. This byte may be accompanied by credentials | |
| information on some operating systems that use sendmsg() with | |
| SCM_CREDS or SCM_CREDENTIALS to pass credentials over UNIX domain | |
| sockets. However, the nul byte must be sent even on other kinds of | |
| socket, and even on operating systems that do not require a byte to be | |
| sent in order to transmit credentials. The text protocol described in | |
| this document begins after the single nul byte. If the first byte | |
| received from the client is not a nul byte, the server may disconnect | |
| that client. | |
| </p><p> | |
| A nul byte in any context other than the initial byte is an error; | |
| the protocol is ASCII-only. | |
| </p><p> | |
| The credentials sent along with the nul byte may be used with the | |
| SASL mechanism EXTERNAL. | |
| </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> | |
| If an AUTH command has no arguments, it is a request to list | |
| available mechanisms. The server must respond with a REJECTED | |
| command listing the mechanisms it understands, or with an error. | |
| </p><p> | |
| If an AUTH command specifies a mechanism, and the server supports | |
| said mechanism, the server should begin exchanging SASL | |
| challenge-response data with the client using DATA commands. | |
| </p><p> | |
| If the server does not support the mechanism given in the AUTH | |
| command, it must send either a REJECTED command listing the mechanisms | |
| it does support, or an error. | |
| </p><p> | |
| If the [initial-response] argument is provided, it is intended for use | |
| with mechanisms that have no initial challenge (or an empty initial | |
| challenge), as if it were the argument to an initial DATA command. If | |
| the selected mechanism has an initial challenge and [initial-response] | |
| was provided, the server should reject authentication by sending | |
| REJECTED. | |
| </p><p> | |
| If authentication succeeds after exchanging DATA commands, | |
| an OK command must be sent to the client. | |
| </p><p> | |
| The first octet received by the server after the \r\n of the BEGIN | |
| command from the client must be the first octet of the | |
| authenticated/encrypted stream of D-Bus messages. | |
| </p><p> | |
| If BEGIN is received by the server, the first octet received | |
| by the client after the \r\n of the OK command must be the | |
| first octet of the authenticated/encrypted stream of D-Bus | |
| messages. | |
| </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> | |
| At any time up to sending the BEGIN command, the client may send a | |
| CANCEL command. On receiving the CANCEL command, the server must | |
| send a REJECTED command and abort the current authentication | |
| exchange. | |
| </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> | |
| The DATA command may come from either client or server, and simply | |
| contains a hex-encoded block of data to be interpreted | |
| according to the SASL mechanism in use. | |
| </p><p> | |
| Some SASL mechanisms support sending an "empty string"; | |
| FIXME we need some way to do this. | |
| </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> | |
| The BEGIN command acknowledges that the client has received an | |
| OK command from the server, and that the stream of messages | |
| is about to begin. | |
| </p><p> | |
| The first octet received by the server after the \r\n of the BEGIN | |
| command from the client must be the first octet of the | |
| authenticated/encrypted stream of D-Bus messages. | |
| </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> | |
| The REJECTED command indicates that the current authentication | |
| exchange has failed, and further exchange of DATA is inappropriate. | |
| The client would normally try another mechanism, or try providing | |
| different responses to challenges. | |
| </p><p> | |
| Optionally, the REJECTED command has a space-separated list of | |
| available auth mechanisms as arguments. If a server ever provides | |
| a list of supported mechanisms, it must provide the same list | |
| each time it sends a REJECTED message. Clients are free to | |
| ignore all lists received after the first. | |
| </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> | |
| The OK command indicates that the client has been | |
| authenticated. The client may now proceed with negotiating | |
| Unix file descriptor passing. To do that it shall send | |
| NEGOTIATE_UNIX_FD to the server. | |
| </p><p> | |
| Otherwise, the client must respond to the OK command by | |
| sending a BEGIN command, followed by its stream of messages, | |
| or by disconnecting. The server must not accept additional | |
| commands using this protocol after the BEGIN command has been | |
| received. Further communication will be a stream of D-Bus | |
| messages (optionally encrypted, as negotiated) rather than | |
| this protocol. | |
| </p><p> | |
| If a client sends BEGIN the first octet received by the client | |
| after the \r\n of the OK command must be the first octet of | |
| the authenticated/encrypted stream of D-Bus messages. | |
| </p><p> | |
| The OK command has one argument, which is the GUID of the server. | |
| See <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a> for more on server GUIDs. | |
| </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> | |
| The ERROR command indicates that either server or client did not | |
| know a command, does not accept the given command in the current | |
| context, or did not understand the arguments to the command. This | |
| allows the protocol to be extended; a client or server can send a | |
| command present or permitted only in new protocol versions, and if | |
| an ERROR is received instead of an appropriate response, fall back | |
| to using some other technique. | |
| </p><p> | |
| If an ERROR is sent, the server or client that sent the | |
| error must continue as if the command causing the ERROR had never been | |
| received. However, the the server or client receiving the error | |
| should try something other than whatever caused the error; | |
| if only canceling/rejecting the authentication. | |
| </p><p> | |
| If the D-Bus protocol changes incompatibly at some future time, | |
| applications implementing the new protocol would probably be able to | |
| check for support of the new protocol by sending a new command and | |
| receiving an ERROR from applications that don't understand it. Thus the | |
| ERROR feature of the auth protocol is an escape hatch that lets us | |
| negotiate extensions or changes to the D-Bus protocol in the future. | |
| </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> | |
| The NEGOTIATE_UNIX_FD command indicates that the client | |
| supports Unix file descriptor passing. This command may only | |
| be sent after the connection is authenticated, i.e. after OK | |
| was received by the client. This command may only be sent on | |
| transports that support Unix file descriptor passing. | |
| </p><p> | |
| On receiving NEGOTIATE_UNIX_FD the server must respond with | |
| either AGREE_UNIX_FD or ERROR. It shall respond the former if | |
| the transport chosen supports Unix file descriptor passing and | |
| the server supports this feature. It shall respond the latter | |
| if the transport does not support Unix file descriptor | |
| passing, the server does not support this feature, or the | |
| server decides not to enable file descriptor passing due to | |
| security or other reasons. | |
| </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> | |
| The AGREE_UNIX_FD command indicates that the server supports | |
| Unix file descriptor passing. This command may only be sent | |
| after the connection is authenticated, and the client sent | |
| NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This | |
| command may only be sent on transports that support Unix file | |
| descriptor passing. | |
| </p><p> | |
| On receiving AGREE_UNIX_FD the client must respond with BEGIN, | |
| followed by its stream of messages, or by disconnecting. The | |
| server must not accept additional commands using this protocol | |
| after the BEGIN command has been received. Further | |
| communication will be a stream of D-Bus messages (optionally | |
| encrypted, as negotiated) rather than this protocol. | |
| </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> | |
| Future extensions to the authentication and negotiation | |
| protocol are possible. For that new commands may be | |
| introduced. If a client or server receives an unknown command | |
| it shall respond with ERROR and not consider this fatal. New | |
| commands may be introduced both before, and after | |
| authentication, i.e. both before and after the OK command. | |
| </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> | |
| </p><div class="figure"><a name="idp5161344"></a><p class="title"><b>Figure 1. Example of successful magic cookie authentication</b></p><div class="figure-contents"><pre class="programlisting"> | |
| (MAGIC_COOKIE is a made up mechanism) | |
| C: AUTH MAGIC_COOKIE 3138363935333137393635383634 | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5163168"></a><p class="title"><b>Figure 2. Example of finding out mechanisms then picking one</b></p><div class="figure-contents"><pre class="programlisting"> | |
| C: AUTH | |
| S: REJECTED KERBEROS_V4 SKEY | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5165072"></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"> | |
| C: FOOBAR | |
| S: ERROR | |
| C: AUTH MAGIC_COOKIE 3736343435313230333039 | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5166960"></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"> | |
| C: AUTH MAGIC_COOKIE 3736343435313230333039 | |
| S: REJECTED KERBEROS_V4 SKEY | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5168976"></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"> | |
| C: AUTH MAGIC_COOKIE 3736343435313230333039 | |
| S: REJECTED KERBEROS_V4 SKEY | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f | |
| S: REJECTED | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5171152"></a><p class="title"><b>Figure 6. Example of skey cancelled and restarted</b></p><div class="figure-contents"><pre class="programlisting"> | |
| C: AUTH MAGIC_COOKIE 3736343435313230333039 | |
| S: REJECTED KERBEROS_V4 SKEY | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: CANCEL | |
| S: REJECTED | |
| C: AUTH SKEY 7ab83f32ee | |
| S: DATA 8799cabb2ea93e | |
| C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f | |
| S: OK 1234deadbeef | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5173216"></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"> | |
| (MAGIC_COOKIE is a made up mechanism) | |
| C: AUTH MAGIC_COOKIE 3138363935333137393635383634 | |
| S: OK 1234deadbeef | |
| C: NEGOTIATE_UNIX_FD | |
| S: AGREE_UNIX_FD | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><div class="figure"><a name="idp5175216"></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"> | |
| (MAGIC_COOKIE is a made up mechanism) | |
| C: AUTH MAGIC_COOKIE 3138363935333137393635383634 | |
| S: OK 1234deadbeef | |
| C: NEGOTIATE_UNIX_FD | |
| S: ERROR | |
| C: BEGIN | |
| </pre></div></div><p><br class="figure-break"> | |
| </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> | |
| This section documents the auth protocol in terms of | |
| a state machine for the client and the server. This is | |
| probably the most robust way to implement the protocol. | |
| </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> | |
| To more precisely describe the interaction between the | |
| protocol state machine and the authentication mechanisms the | |
| following notation is used: MECH(CHALL) means that the | |
| server challenge CHALL was fed to the mechanism MECH, which | |
| returns one of | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| CONTINUE(RESP) means continue the auth conversation | |
| and send RESP as the response to the server; | |
| </p></li><li class="listitem"><p> | |
| OK(RESP) means that after sending RESP to the server | |
| the client side of the auth conversation is finished | |
| and the server should return "OK"; | |
| </p></li><li class="listitem"><p> | |
| ERROR means that CHALL was invalid and could not be | |
| processed. | |
| </p></li></ul></div><p> | |
| Both RESP and CHALL may be empty. | |
| </p><p> | |
| The Client starts by getting an initial response from the | |
| default mechanism and sends AUTH MECH RESP, or AUTH MECH if | |
| the mechanism did not provide an initial response. If the | |
| mechanism returns CONTINUE, the client starts in state | |
| <span class="emphasis"><em>WaitingForData</em></span>, if the mechanism | |
| returns OK the client starts in state | |
| <span class="emphasis"><em>WaitingForOK</em></span>. | |
| </p><p> | |
| The client should keep track of available mechanisms and | |
| which it mechanisms it has already attempted. This list is | |
| used to decide which AUTH command to send. When the list is | |
| exhausted, the client should give up and close the | |
| connection. | |
| </p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive DATA CHALL | |
| </p><table border="0" summary="Simple list" class="simplelist"><tr><td> | |
| MECH(CHALL) returns CONTINUE(RESP) → send | |
| DATA RESP, goto | |
| <span class="emphasis"><em>WaitingForData</em></span> | |
| </td></tr><tr><td> | |
| MECH(CHALL) returns OK(RESP) → send DATA | |
| RESP, goto <span class="emphasis"><em>WaitingForOK</em></span> | |
| </td></tr><tr><td> | |
| MECH(CHALL) returns ERROR → send ERROR | |
| [msg], goto <span class="emphasis"><em>WaitingForData</em></span> | |
| </td></tr></table><p> | |
| </p></li><li class="listitem"><p> | |
| Receive REJECTED [mechs] → | |
| send AUTH [next mech], goto | |
| WaitingForData or <span class="emphasis"><em>WaitingForOK</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive ERROR → send | |
| CANCEL, goto | |
| <span class="emphasis"><em>WaitingForReject</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive OK → send | |
| BEGIN, terminate auth | |
| conversation, authenticated | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → send | |
| ERROR, goto | |
| <span class="emphasis"><em>WaitingForData</em></span> | |
| </p></li></ul></div><p title="WaitingForData"> | |
| </p><p title="WaitingForOK"><b><span class="emphasis"><em>WaitingForOK</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive OK → send BEGIN, terminate auth | |
| conversation, <span class="emphasis"><em>authenticated</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive REJECT [mechs] → send AUTH [next mech], | |
| goto <span class="emphasis"><em>WaitingForData</em></span> or | |
| <span class="emphasis"><em>WaitingForOK</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive DATA → send CANCEL, goto | |
| <span class="emphasis"><em>WaitingForReject</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive ERROR → send CANCEL, goto | |
| <span class="emphasis"><em>WaitingForReject</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → send ERROR, goto | |
| <span class="emphasis"><em>WaitingForOK</em></span> | |
| </p></li></ul></div><p title="WaitingForOK"> | |
| </p><p title="WaitingForReject"><b><span class="emphasis"><em>WaitingForReject</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive REJECT [mechs] → send AUTH [next mech], | |
| goto <span class="emphasis"><em>WaitingForData</em></span> or | |
| <span class="emphasis"><em>WaitingForOK</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → terminate auth | |
| conversation, disconnect | |
| </p></li></ul></div><p title="WaitingForReject"> | |
| </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> | |
| For the server MECH(RESP) means that the client response | |
| RESP was fed to the the mechanism MECH, which returns one of | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| CONTINUE(CHALL) means continue the auth conversation and | |
| send CHALL as the challenge to the client; | |
| </p></li><li class="listitem"><p> | |
| OK means that the client has been successfully | |
| authenticated; | |
| </p></li><li class="listitem"><p> | |
| REJECT means that the client failed to authenticate or | |
| there was an error in RESP. | |
| </p></li></ul></div><p> | |
| The server starts out in state | |
| <span class="emphasis"><em>WaitingForAuth</em></span>. If the client is | |
| rejected too many times the server must disconnect the | |
| client. | |
| </p><p title="WaitingForAuth"><b><span class="emphasis"><em>WaitingForAuth</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive AUTH → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive AUTH MECH RESP | |
| </p><table border="0" summary="Simple list" class="simplelist"><tr><td> | |
| MECH not valid mechanism → send REJECTED | |
| [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </td></tr><tr><td> | |
| MECH(RESP) returns CONTINUE(CHALL) → send | |
| DATA CHALL, goto | |
| <span class="emphasis"><em>WaitingForData</em></span> | |
| </td></tr><tr><td> | |
| MECH(RESP) returns OK → send OK, goto | |
| <span class="emphasis"><em>WaitingForBegin</em></span> | |
| </td></tr><tr><td> | |
| MECH(RESP) returns REJECT → send REJECTED | |
| [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </td></tr></table><p> | |
| </p></li><li class="listitem"><p> | |
| Receive BEGIN → terminate | |
| auth conversation, disconnect | |
| </p></li><li class="listitem"><p> | |
| Receive ERROR → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → send | |
| ERROR, goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li></ul></div><p title="WaitingForAuth"> | |
| </p><p title="WaitingForData"><b><span class="emphasis"><em>WaitingForData</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive DATA RESP | |
| </p><table border="0" summary="Simple list" class="simplelist"><tr><td> | |
| MECH(RESP) returns CONTINUE(CHALL) → send | |
| DATA CHALL, goto | |
| <span class="emphasis"><em>WaitingForData</em></span> | |
| </td></tr><tr><td> | |
| MECH(RESP) returns OK → send OK, goto | |
| <span class="emphasis"><em>WaitingForBegin</em></span> | |
| </td></tr><tr><td> | |
| MECH(RESP) returns REJECT → send REJECTED | |
| [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </td></tr></table><p> | |
| </p></li><li class="listitem"><p> | |
| Receive BEGIN → terminate auth conversation, | |
| disconnect | |
| </p></li><li class="listitem"><p> | |
| Receive CANCEL → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive ERROR → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → send ERROR, goto | |
| <span class="emphasis"><em>WaitingForData</em></span> | |
| </p></li></ul></div><p title="WaitingForData"> | |
| </p><p title="WaitingForBegin"><b><span class="emphasis"><em>WaitingForBegin</em></span>. </b> | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Receive BEGIN → terminate auth conversation, | |
| client authenticated | |
| </p></li><li class="listitem"><p> | |
| Receive CANCEL → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive ERROR → send REJECTED [mechs], goto | |
| <span class="emphasis"><em>WaitingForAuth</em></span> | |
| </p></li><li class="listitem"><p> | |
| Receive anything else → send ERROR, goto | |
| <span class="emphasis"><em>WaitingForBegin</em></span> | |
| </p></li></ul></div><p title="WaitingForBegin"> | |
| </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> | |
| This section describes some new authentication mechanisms. | |
| D-Bus also allows any standard SASL mechanism of course. | |
| </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> | |
| The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client | |
| has the ability to read a private file owned by the user being | |
| authenticated. If the client can prove that it has access to a secret | |
| cookie stored in this file, then the client is authenticated. | |
| Thus the security of DBUS_COOKIE_SHA1 depends on a secure home | |
| directory. | |
| </p><p> | |
| Throughout this description, "hex encoding" must output the digits | |
| from a to f in lower-case; the digits A to F must not be used | |
| in the DBUS_COOKIE_SHA1 mechanism. | |
| </p><p> | |
| Authentication proceeds as follows: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| The client sends the username it would like to authenticate | |
| as, hex-encoded. | |
| </p></li><li class="listitem"><p> | |
| The server sends the name of its "cookie context" (see below); a | |
| space character; the integer ID of the secret cookie the client | |
| must demonstrate knowledge of; a space character; then a | |
| randomly-generated challenge string, all of this hex-encoded into | |
| one, single string. | |
| </p></li><li class="listitem"><p> | |
| The client locates the cookie and generates its own | |
| randomly-generated challenge string. The client then concatenates | |
| the server's decoded challenge, a ":" character, its own challenge, | |
| another ":" character, and the cookie. It computes the SHA-1 hash | |
| of this composite string as a hex digest. It concatenates the | |
| client's challenge string, a space character, and the SHA-1 hex | |
| digest, hex-encodes the result and sends it back to the server. | |
| </p></li><li class="listitem"><p> | |
| The server generates the same concatenated string used by the | |
| client and computes its SHA-1 hash. It compares the hash with | |
| the hash received from the client; if the two hashes match, the | |
| client is authenticated. | |
| </p></li></ul></div><p> | |
| </p><p> | |
| Each server has a "cookie context," which is a name that identifies a | |
| set of cookies that apply to that server. A sample context might be | |
| "org_freedesktop_session_bus". Context names must be valid ASCII, | |
| nonzero length, and may not contain the characters slash ("/"), | |
| backslash ("\"), space (" "), newline ("\n"), carriage return ("\r"), | |
| tab ("\t"), or period ("."). There is a default context, | |
| "org_freedesktop_general" that's used by servers that do not specify | |
| otherwise. | |
| </p><p> | |
| Cookies are stored in a user's home directory, in the directory | |
| <code class="filename">~/.dbus-keyrings/</code>. This directory must | |
| not be readable or writable by other users. If it is, | |
| clients and servers must ignore it. The directory | |
| contains cookie files named after the cookie context. | |
| </p><p> | |
| A cookie file contains one cookie per line. Each line | |
| has three space-separated fields: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| The cookie ID number, which must be a non-negative integer and | |
| may not be used twice in the same file. | |
| </p></li><li class="listitem"><p> | |
| The cookie's creation time, in UNIX seconds-since-the-epoch | |
| format. | |
| </p></li><li class="listitem"><p> | |
| The cookie itself, a hex-encoded random block of bytes. The cookie | |
| may be of any length, though obviously security increases | |
| as the length increases. | |
| </p></li></ul></div><p> | |
| </p><p> | |
| Only server processes modify the cookie file. | |
| They must do so with this procedure: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Create a lockfile name by appending ".lock" to the name of the | |
| cookie file. The server should attempt to create this file | |
| using <code class="literal">O_CREAT | O_EXCL</code>. If file creation | |
| fails, the lock fails. Servers should retry for a reasonable | |
| period of time, then they may choose to delete an existing lock | |
| to keep users from having to manually delete a stale | |
| lock. <sup>[<a name="idp5260576" href="#ftn.idp5260576" class="footnote">1</a>]</sup> | |
| </p></li><li class="listitem"><p> | |
| Once the lockfile has been created, the server loads the cookie | |
| file. It should then delete any cookies that are old (the | |
| timeout can be fairly short), or more than a reasonable | |
| time in the future (so that cookies never accidentally | |
| become permanent, if the clock was set far into the future | |
| at some point). If no recent keys remain, the | |
| server may generate a new key. | |
| </p></li><li class="listitem"><p> | |
| The pruned and possibly added-to cookie file | |
| must be resaved atomically (using a temporary | |
| file which is rename()'d). | |
| </p></li><li class="listitem"><p> | |
| The lock must be dropped by deleting the lockfile. | |
| </p></li></ul></div><p> | |
| </p><p> | |
| Clients need not lock the file in order to load it, | |
| because servers are required to save the file atomically. | |
| </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> | |
| Server addresses consist of a transport name followed by a colon, and | |
| then an optional, comma-separated list of keys and values in the form key=value. | |
| Each value is escaped. | |
| </p><p> | |
| For example: | |
| </p><pre class="programlisting">unix:path=/tmp/dbus-test</pre><p> | |
| Which is the address to a unix socket with the path /tmp/dbus-test. | |
| </p><p> | |
| Value escaping is similar to URI escaping but simpler. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| The set of optionally-escaped bytes is: | |
| <code class="literal">[0-9A-Za-z_-/.\]</code>. To escape, each | |
| <span class="emphasis"><em>byte</em></span> (note, not character) which is not in the | |
| set of optionally-escaped bytes must be replaced with an ASCII | |
| percent (<code class="literal">%</code>) and the value of the byte in hex. | |
| The hex value must always be two digits, even if the first digit is | |
| zero. The optionally-escaped bytes may be escaped if desired. | |
| </p></li><li class="listitem"><p> | |
| To unescape, append each byte in the value; if a byte is an ASCII | |
| percent (<code class="literal">%</code>) character then append the following | |
| hex value instead. It is an error if a <code class="literal">%</code> byte | |
| does not have two hex digits following. It is an error if a | |
| non-optionally-escaped byte is seen unescaped. | |
| </p></li></ul></div><p> | |
| The set of optionally-escaped bytes is intended to preserve address | |
| readability and convenience. | |
| </p><p> | |
| A server may specify a key-value pair with the key <code class="literal">guid</code> | |
| and the value a hex-encoded 16-byte sequence. <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a> | |
| describes the format of the <code class="literal">guid</code> field. If present, | |
| this UUID may be used to distinguish one server address from another. A | |
| server should use a different UUID for each address it listens on. For | |
| example, if a message bus daemon offers both UNIX domain socket and TCP | |
| connections, but treats clients the same regardless of how they connect, | |
| those two connections are equivalent post-connection but should have | |
| distinct UUIDs to distinguish the kinds of connection. | |
| </p><p> | |
| The intent of the address UUID feature is to allow a client to avoid | |
| opening multiple identical connections to the same server, by allowing the | |
| client to check whether an address corresponds to an already-existing | |
| connection. Comparing two addresses is insufficient, because addresses | |
| can be recycled by distinct servers, and equivalent addresses may look | |
| different if simply compared as strings (for example, the host in a TCP | |
| address can be given as an IP address or as a hostname). | |
| </p><p> | |
| Note that the address key is <code class="literal">guid</code> even though the | |
| rest of the API and documentation says "UUID," for historical reasons. | |
| </p><p> | |
| [FIXME clarify if attempting to connect to each is a requirement | |
| or just a suggestion] | |
| When connecting to a server, multiple server addresses can be | |
| separated by a semi-colon. The library will then try to connect | |
| to the first address and if that fails, it'll try to connect to | |
| the next one specified, and so forth. For example | |
| </p><pre class="programlisting">unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</pre><p> | |
| </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> | |
| [FIXME we need to specify in detail each transport and its possible arguments] | |
| Current transports include: unix domain sockets (including | |
| abstract namespace on linux), launchd, TCP/IP, and a debug/testing transport | |
| using in-process pipes. Future possible transports include one that | |
| tunnels over X11 protocol. | |
| </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> | |
| Unix domain sockets can be either paths in the file system or on Linux | |
| kernels, they can be abstract which are similar to paths but | |
| do not show up in the file system. | |
| </p><p> | |
| When a socket is opened by the D-Bus library it truncates the path | |
| name right before the first trailing Nul byte. This is true for both | |
| normal paths and abstract paths. Note that this is a departure from | |
| previous versions of D-Bus that would create sockets with a fixed | |
| length path name. Names which were shorter than the fixed length | |
| would be padded by Nul bytes. | |
| </p><p> | |
| Unix domain sockets are not available on windows. | |
| </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> | |
| Unix domain socket addresses are identified by the "unix:" prefix | |
| and support the following key/value pairs: | |
| </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> | |
| launchd is a open-source server management system that replaces init, inetd | |
| and cron on Apple Mac OS X versions 10.4 and above. It provides a common session | |
| bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX. | |
| </p><p> | |
| launchd allocates a socket and provides it with the unix path through the | |
| DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process | |
| spawned by launchd (or dbus-daemon, if it was started by launchd) can access | |
| it through its environment. | |
| Other processes can query for the launchd socket by executing: | |
| $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET | |
| This is normally done by the D-Bus client library so doesn't have to be done | |
| manually. | |
| </p><p> | |
| launchd is not available on Microsoft Windows. | |
| </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> | |
| launchd addresses are identified by the "launchd:" prefix | |
| and support the following key/value pairs: | |
| </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="TCP Sockets"><div class="titlepage"><div><div><h3 class="title"><a name="transports-tcp-sockets"></a>TCP Sockets</h3></div></div></div><p> | |
| The tcp transport provides TCP/IP based connections between clients | |
| located on the same or different hosts. | |
| </p><p> | |
| Using tcp transport without any additional secure authentification mechanismus | |
| over a network is unsecure. | |
| </p><p> | |
| Windows notes: Because of the tcp stack on windows does not provide sending | |
| credentials over a tcp connection, the EXTERNAL authentification | |
| mechanismus does not work. | |
| </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> | |
| TCP/IP socket addresses are identified by the "tcp:" prefix | |
| and support the following key/value pairs: | |
| </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 | |
| choose a free port provided from the underlaying operating system. | |
| libdbus is able to retrieve the real used port from the server. | |
| </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> | |
| The nonce-tcp transport provides a secured TCP transport, using a | |
| simple authentication mechanism to ensure that only clients with read | |
| access to a certain location in the filesystem can connect to the server. | |
| The server writes a secret, the nonce, to a file and an incoming client | |
| connection is only accepted if the client sends the nonce right after | |
| the connect. The nonce mechanism requires no setup and is orthogonal to | |
| the higher-level authentication mechanisms described in the | |
| Authentication section. | |
| </p><p> | |
| On start, the server generates a random 16 byte nonce and writes it | |
| to a file in the user's temporary directory. The nonce file location | |
| is published as part of the server's D-Bus address using the | |
| "noncefile" key-value pair. | |
| After an accept, the server reads 16 bytes from the socket. If the | |
| read bytes do not match the nonce stored in the nonce file, the | |
| server MUST immediately drop the connection. | |
| If the nonce match the received byte sequence, the client is accepted | |
| and the transport behaves like an unsecured tcp transport. | |
| </p><p> | |
| After a successful connect to the server socket, the client MUST read | |
| the nonce from the file published by the server via the noncefile= | |
| key-value pair and send it over the socket. After that, the | |
| transport behaves like an unsecured tcp transport. | |
| </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> | |
| Nonce TCP/IP socket addresses uses the "nonce-tcp:" prefix | |
| and support the following key/value pairs: | |
| </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 | |
| choose a free port provided from the underlaying operating system. | |
| libdbus is able to retrieve the real used port from the server. | |
| </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><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> | |
| Meta transports are a kind of transport with special enhancements or | |
| behavior. Currently available meta transports include: autolaunch | |
| </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 | |
| a running dbus session bus and to autolaunch a session bus if not present. | |
| </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> | |
| Autolaunch addresses uses the "autolaunch:" prefix and support the | |
| following key/value pairs: | |
| </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) | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| "*install-path" - limit session bus to dbus installation path. | |
| The dbus installation path is determined from the location of | |
| the shared dbus library. If the library is located in a 'bin' | |
| subdirectory the installation root is the directory above, | |
| otherwise the directory where the library lives is taken as | |
| installation root. | |
| </p><pre class="programlisting"> | |
| <install-root>/bin/[lib]dbus-1.dll | |
| <install-root>/[lib]dbus-1.dll | |
| </pre><p> | |
| </p></li><li class="listitem"><p> | |
| "*user" - limit session bus to the recent user. | |
| </p></li><li class="listitem"><p> | |
| other values - specify dedicated session bus like "release", | |
| "debug" or other | |
| </p></li></ul></div> | |
| </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> | |
| On start, the server opens a platform specific transport, creates a mutex | |
| and a shared memory section containing the related session bus address. | |
| This mutex will be inspected by the dbus client library to detect a | |
| running dbus session bus. The access to the mutex and the shared memory | |
| section are protected by global locks. | |
| </p><p> | |
| In the recent implementation the autolaunch transport uses a tcp transport | |
| on localhost with a port choosen from the operating system. This detail may | |
| change in the future. | |
| </p><p> | |
| Disclaimer: The recent implementation is in an early state and may not | |
| work in all cirumstances and/or may have security issues. Because of this | |
| the implementation is not documentated yet. | |
| </p></div></div></div><div class="sect1" title="Naming Conventions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="naming-conventions"></a>Naming Conventions</h2></div></div></div><p> | |
| D-Bus namespaces are all lowercase and correspond to reversed domain | |
| names, as with Java. e.g. "org.freedesktop" | |
| </p><p> | |
| Interface, signal, method, and property names are "WindowsStyleCaps", note | |
| that the first letter is capitalized, unlike Java. | |
| </p><p> | |
| Object paths are normally all lowercase with underscores used rather than | |
| hyphens. | |
| </p></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> | |
| A working D-Bus implementation uses universally-unique IDs in two places. | |
| First, each server address has a UUID identifying the address, | |
| as described in <a class="xref" href="#addresses" title="Server Addresses">the section called “Server Addresses”</a>. Second, each operating | |
| system kernel instance running a D-Bus client or server has a UUID | |
| identifying that kernel, retrieved by invoking the method | |
| 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>). | |
| </p><p> | |
| The term "UUID" in this document is intended literally, i.e. an | |
| identifier that is universally unique. It is not intended to refer to | |
| RFC4122, and in fact the D-Bus UUID is not compatible with that RFC. | |
| </p><p> | |
| The UUID must contain 128 bits of data and be hex-encoded. The | |
| hex-encoded string may not contain hyphens or other non-hex-digit | |
| characters, and it must be exactly 32 characters long. To generate a | |
| UUID, the current reference implementation concatenates 96 bits of random | |
| data followed by the 32-bit time in seconds since the UNIX epoch (in big | |
| endian byte order). | |
| </p><p> | |
| It would also be acceptable and probably better to simply generate 128 | |
| bits of random data, as long as the random number generator is of high | |
| quality. The timestamp could conceivably help if the random bits are not | |
| very random. With a quality random number generator, collisions are | |
| extremely unlikely even with only 96 bits, so it's somewhat academic. | |
| </p><p> | |
| Implementations should, however, stick to random data for the first 96 bits | |
| of the UUID. | |
| </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> | |
| 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 | |
| the notation used in this section. There are some standard interfaces | |
| that may be useful across various D-Bus applications. | |
| </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> | |
| The <code class="literal">org.freedesktop.DBus.Peer</code> interface | |
| has two methods: | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.Peer.Ping () | |
| org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid) | |
| </pre><p> | |
| </p><p> | |
| On receipt of the <code class="literal">METHOD_CALL</code> message | |
| <code class="literal">org.freedesktop.DBus.Peer.Ping</code>, an application should do | |
| nothing other than reply with a <code class="literal">METHOD_RETURN</code> as | |
| usual. It does not matter which object path a ping is sent to. The | |
| reference implementation handles this method automatically. | |
| </p><p> | |
| On receipt of the <code class="literal">METHOD_CALL</code> message | |
| <code class="literal">org.freedesktop.DBus.Peer.GetMachineId</code>, an application should | |
| reply with a <code class="literal">METHOD_RETURN</code> containing a hex-encoded | |
| UUID representing the identity of the machine the process is running on. | |
| This UUID must be the same for all processes on a single system at least | |
| until that system next reboots. It should be the same across reboots | |
| if possible, but this is not always possible to implement and is not | |
| guaranteed. | |
| It does not matter which object path a GetMachineId is sent to. The | |
| reference implementation handles this method automatically. | |
| </p><p> | |
| The UUID is intended to be per-instance-of-the-operating-system, so may represent | |
| a virtual machine running on a hypervisor, rather than a physical machine. | |
| Basically if two processes see the same UUID, they should also see the same | |
| shared memory, UNIX domain sockets, process IDs, and other features that require | |
| a running OS kernel in common between the processes. | |
| </p><p> | |
| The UUID is often used where other programs might use a hostname. Hostnames | |
| can change without rebooting, however, or just be "localhost" - so the UUID | |
| is more robust. | |
| </p><p> | |
| <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a> explains the format of the UUID. | |
| </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> | |
| This interface has one method: | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data) | |
| </pre><p> | |
| </p><p> | |
| Objects instances may implement | |
| <code class="literal">Introspect</code> which returns an XML description of | |
| the object, including its interfaces (with signals and methods), objects | |
| below it in the object path tree, and its properties. | |
| </p><p> | |
| <a class="xref" href="#introspection-format" title="Introspection Data Format">the section called “Introspection Data Format”</a> describes the format of this XML string. | |
| </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> | |
| Many native APIs will have a concept of object <em class="firstterm">properties</em> | |
| or <em class="firstterm">attributes</em>. These can be exposed via the | |
| <code class="literal">org.freedesktop.DBus.Properties</code> interface. | |
| </p><p> | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.Properties.Get (in STRING interface_name, | |
| in STRING property_name, | |
| out VARIANT value); | |
| org.freedesktop.DBus.Properties.Set (in STRING interface_name, | |
| in STRING property_name, | |
| in VARIANT value); | |
| org.freedesktop.DBus.Properties.GetAll (in STRING interface_name, | |
| out DICT<STRING,VARIANT> props); | |
| </pre><p> | |
| </p><p> | |
| The available properties and whether they are writable can be determined | |
| by calling <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>, | |
| 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>. | |
| </p><p> | |
| An empty string may be provided for the interface name; in this case, | |
| if there are multiple properties on an object with the same name, | |
| the results are undefined (picking one by according to an arbitrary | |
| deterministic rule, or returning an error, are the reasonable | |
| possibilities). | |
| </p><p> | |
| If one or more properties change on an object, the | |
| <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code> | |
| signal may be emitted (this signal was added in 0.14): | |
| </p><p> | |
| </p><pre class="programlisting"> | |
| org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name, | |
| DICT<STRING,VARIANT> changed_properties, | |
| ARRAY<STRING> invalidated_properties); | |
| </pre><p> | |
| </p><p> | |
| where <code class="literal">changed_properties</code> is a dictionary | |
| containing the changed properties with the new values and | |
| <code class="literal">invalidated_properties</code> is an array of | |
| properties that changed but the value is not conveyed. | |
| </p><p> | |
| Whether the <code class="literal">PropertiesChanged</code> signal is | |
| supported can be determined by calling | |
| <code class="literal">org.freedesktop.DBus.Introspectable.Introspect</code>. Note | |
| that the signal may be supported for an object but it may | |
| differ how whether and how it is used on a per-property basis | |
| (for e.g. performance or security reasons). Each property (or | |
| the parent interface) must be annotated with the | |
| <code class="literal">org.freedesktop.DBus.Property.EmitsChangedSignal</code> | |
| annotation to convey this (usually the default value | |
| <code class="literal">true</code> is sufficient meaning that the | |
| 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 | |
| annotation. | |
| </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> | |
| 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>, | |
| objects may be introspected at runtime, returning an XML string | |
| that describes the object. The same XML format may be used in | |
| other contexts as well, for example as an "IDL" for generating | |
| static language bindings. | |
| </p><p> | |
| Here is an example of introspection data: | |
| </p><pre class="programlisting"> | |
| <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" | |
| "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> | |
| <node name="/org/freedesktop/sample_object"> | |
| <interface name="org.freedesktop.SampleInterface"> | |
| <method name="Frobate"> | |
| <arg name="foo" type="i" direction="in"/> | |
| <arg name="bar" type="s" direction="out"/> | |
| <arg name="baz" type="a{us}" direction="out"/> | |
| <annotation name="org.freedesktop.DBus.Deprecated" value="true"/> | |
| </method> | |
| <method name="Bazify"> | |
| <arg name="bar" type="(iiu)" direction="in"/> | |
| <arg name="bar" type="v" direction="out"/> | |
| </method> | |
| <method name="Mogrify"> | |
| <arg name="bar" type="(iiav)" direction="in"/> | |
| </method> | |
| <signal name="Changed"> | |
| <arg name="new_value" type="b"/> | |
| </signal> | |
| <property name="Bar" type="y" access="readwrite"/> | |
| </interface> | |
| <node name="child_of_sample_object"/> | |
| <node name="another_child_of_sample_object"/> | |
| </node> | |
| </pre><p> | |
| </p><p> | |
| A more formal DTD and spec needs writing, but here are some quick notes. | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| Only the root <node> element can omit the node name, as it's | |
| known to be the object that was introspected. If the root | |
| <node> does have a name attribute, it must be an absolute | |
| object path. If child <node> have object paths, they must be | |
| relative. | |
| </p></li><li class="listitem"><p> | |
| If a child <node> has any sub-elements, then they | |
| must represent a complete introspection of the child. | |
| If a child <node> is empty, then it may or may | |
| not have sub-elements; the child must be introspected | |
| in order to find out. The intent is that if an object | |
| knows that its children are "fast" to introspect | |
| it can go ahead and return their information, but | |
| otherwise it can omit it. | |
| </p></li><li class="listitem"><p> | |
| The direction element on <arg> may be omitted, | |
| in which case it defaults to "in" for method calls | |
| and "out" for signals. Signals only allow "out" | |
| so while direction may be specified, it's pointless. | |
| </p></li><li class="listitem"><p> | |
| The possible directions are "in" and "out", | |
| unlike CORBA there is no "inout" | |
| </p></li><li class="listitem"><p> | |
| The possible property access flags are | |
| "readwrite", "read", and "write" | |
| </p></li><li class="listitem"><p> | |
| Multiple interfaces can of course be listed for | |
| one <node>. | |
| </p></li><li class="listitem"><p> | |
| The "name" attribute on arguments is optional. | |
| </p></li></ul></div><p> | |
| </p><p> | |
| Method, interface, property, and signal elements may have | |
| "annotations", which are generic key/value pairs of metadata. | |
| They are similar conceptually to Java's annotations and C# attributes. | |
| Well-known annotations: | |
| </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> | |
| <p> | |
| If set to <code class="literal">false</code>, the | |
| <code class="literal">org.freedesktop.DBus.Properties.PropertiesChanged</code> | |
| 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 | |
| guaranteed to be emitted if the property changes. | |
| </p> | |
| <p> | |
| If set to <code class="literal">invalidates</code> the signal | |
| is emitted but the value is not included in the | |
| signal. | |
| </p> | |
| <p> | |
| If set to <code class="literal">true</code> the signal is | |
| emitted with the value included. | |
| </p> | |
| <p> | |
| The value for the annotation defaults to | |
| <code class="literal">true</code> if the enclosing interface | |
| element does not specify the annotation. Otherwise it | |
| defaults to the value specified in the enclosing | |
| interface element. | |
| </p> | |
| </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> | |
| The message bus accepts connections from one or more applications. | |
| Once connected, applications can exchange messages with other | |
| applications that are also connected to the bus. | |
| </p><p> | |
| In order to route messages among connections, the message bus keeps a | |
| mapping from names to connections. Each connection has one | |
| unique-for-the-lifetime-of-the-bus name automatically assigned. | |
| Applications may request additional names for a connection. Additional | |
| names are usually "well-known names" such as | |
| "org.freedesktop.TextEditor". When a name is bound to a connection, | |
| that connection is said to <em class="firstterm">own</em> the name. | |
| </p><p> | |
| The bus itself owns a special name, <code class="literal">org.freedesktop.DBus</code>. | |
| This name routes messages to the bus, allowing applications to make | |
| administrative requests. For example, applications can ask the bus | |
| to assign a name to a connection. | |
| </p><p> | |
| Each name may have <em class="firstterm">queued owners</em>. When an | |
| application requests a name for a connection and the name is already in | |
| use, the bus will optionally add the connection to a queue waiting for | |
| the name. If the current owner of the name disconnects or releases | |
| the name, the next connection in the queue will become the new owner. | |
| </p><p> | |
| This feature causes the right thing to happen if you start two text | |
| editors for example; the first one may request "org.freedesktop.TextEditor", | |
| and the second will be queued as a possible owner of that name. When | |
| the first exits, the second will take over. | |
| </p><p> | |
| 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>). If the | |
| <code class="literal">DESTINATION</code> field is present, it specifies a message | |
| recipient by name. Method calls and replies normally specify this field. | |
| The message bus must send messages (of any type) with the | |
| <code class="literal">DESTINATION</code> field set to the specified recipient, | |
| regardless of whether the recipient has set up a match rule matching | |
| the message. | |
| </p><p> | |
| Signals normally do not specify a destination; they are sent to all | |
| applications with <em class="firstterm">message matching rules</em> that | |
| match the message. | |
| </p><p> | |
| When the message bus receives a method call, if the | |
| <code class="literal">DESTINATION</code> field is absent, the call is taken to be | |
| a standard one-to-one message and interpreted by the message bus | |
| itself. For example, sending an | |
| <code class="literal">org.freedesktop.DBus.Peer.Ping</code> message with no | |
| <code class="literal">DESTINATION</code> will cause the message bus itself to | |
| reply to the ping immediately; the message bus will not make this | |
| message visible to other applications. | |
| </p><p> | |
| Continuing the <code class="literal">org.freedesktop.DBus.Peer.Ping</code> example, if | |
| the ping message were sent with a <code class="literal">DESTINATION</code> name of | |
| <code class="literal">com.yoyodyne.Screensaver</code>, then the ping would be | |
| forwarded, and the Yoyodyne Corporation screensaver application would be | |
| expected to reply to the ping. | |
| </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> | |
| Each connection has at least one name, assigned at connection time and | |
| returned in response to the | |
| <code class="literal">org.freedesktop.DBus.Hello</code> method call. This | |
| automatically-assigned name is called the connection's <em class="firstterm">unique | |
| name</em>. Unique names are never reused for two different | |
| connections to the same bus. | |
| </p><p> | |
| Ownership of a unique name is a prerequisite for interaction with | |
| the message bus. It logically follows that the unique name is always | |
| the first name that an application comes to own, and the last | |
| one that it loses ownership of. | |
| </p><p> | |
| Unique connection names must begin with the character ':' (ASCII colon | |
| character); bus names that are not unique names must not begin | |
| with this character. (The bus must reject any attempt by an application | |
| to manually request a name beginning with ':'.) This restriction | |
| categorically prevents "spoofing"; messages sent to a unique name | |
| will always go to the expected connection. | |
| </p><p> | |
| When a connection is closed, all the names that it owns are deleted (or | |
| transferred to the next connection in the queue if any). | |
| </p><p> | |
| A connection can request additional names to be associated with it using | |
| 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 | |
| name. These names can be released again using the | |
| <code class="literal">org.freedesktop.DBus.ReleaseName</code> message. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UINT32 RequestName (in STRING name, in UINT32 flags) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| This method call should be sent to | |
| <code class="literal">org.freedesktop.DBus</code> and asks the message bus to | |
| assign the given name to the method caller. Each name maintains a | |
| queue of possible owners, where the head of the queue is the primary | |
| or current owner of the name. Each potential owner in the queue | |
| maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and | |
| DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName | |
| call. When RequestName is invoked the following occurs: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> | |
| If the method caller is currently the primary owner of the name, | |
| the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE | |
| values are updated with the values from the new RequestName call, | |
| and nothing further happens. | |
| </p></li><li class="listitem"><p> | |
| If the current primary owner (head of the queue) has | |
| DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName | |
| invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then | |
| the caller of RequestName replaces the current primary owner at | |
| the head of the queue and the current primary owner moves to the | |
| second position in the queue. If the caller of RequestName was | |
| in the queue previously its flags are updated with the values from | |
| the new RequestName in addition to moving it to the head of the queue. | |
| </p></li><li class="listitem"><p> | |
| If replacement is not possible, and the method caller is | |
| currently in the queue but not the primary owner, its flags are | |
| updated with the values from the new RequestName call. | |
| </p></li><li class="listitem"><p> | |
| If replacement is not possible, and the method caller is | |
| currently not in the queue, the method caller is appended to the | |
| queue. | |
| </p></li><li class="listitem"><p> | |
| If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE | |
| set and is not the primary owner, it is removed from the | |
| queue. This can apply to the previous primary owner (if it | |
| was replaced) or the method caller (if it updated the | |
| DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the | |
| queue, or if it was just added to the queue with that flag set). | |
| </p></li></ul></div><p> | |
| </p><p> | |
| Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the | |
| queue," even if another application already in the queue had specified | |
| DBUS_NAME_FLAG_REPLACE_EXISTING. This comes up if a primary owner | |
| that does not allow replacement goes away, and the next primary owner | |
| does allow replacement. In this case, queued items that specified | |
| DBUS_NAME_FLAG_REPLACE_EXISTING <span class="emphasis"><em>do not</em></span> | |
| automatically replace the new primary owner. In other words, | |
| DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the | |
| time RequestName is called. This is deliberate to avoid an infinite loop | |
| anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT | |
| and DBUS_NAME_FLAG_REPLACE_EXISTING. | |
| </p><p> | |
| The flags argument contains any of the following values logically ORed | |
| together: | |
| </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> | |
| If an application A specifies this flag and succeeds in | |
| becoming the owner of the name, and another application B | |
| later calls RequestName with the | |
| DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A | |
| will lose ownership and receive a | |
| <code class="literal">org.freedesktop.DBus.NameLost</code> signal, and | |
| application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT | |
| is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING | |
| is not specified by application B, then application B will not replace | |
| application A as the owner. | |
| </td></tr><tr><td>DBUS_NAME_FLAG_REPLACE_EXISTING</td><td>0x2</td><td> | |
| Try to replace the current owner if there is one. If this | |
| flag is not set the application will only become the owner of | |
| the name if there is no current owner. If this flag is set, | |
| the application will replace the current owner if | |
| the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT. | |
| </td></tr><tr><td>DBUS_NAME_FLAG_DO_NOT_QUEUE</td><td>0x4</td><td> | |
| Without this flag, if an application requests a name that is | |
| already owned, the application will be placed in a queue to | |
| own the name when the current owner gives it up. If this | |
| flag is given, the application will not be placed in the | |
| queue, the request for the name will simply fail. This flag | |
| also affects behavior when an application is replaced as | |
| name owner; by default the application moves back into the | |
| waiting queue, unless this flag was provided when the application | |
| became the name owner. | |
| </td></tr></tbody></table></div><p> | |
| The return code can be one of the following values: | |
| </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 | |
| the name, replacing any previous owner. Either the name had no | |
| owner before, or the caller specified | |
| DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified | |
| 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, | |
| DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either | |
| the current owner did not specify | |
| DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting | |
| application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING. | |
| </td></tr><tr><td>DBUS_REQUEST_NAME_REPLY_EXISTS</td><td>3</td><td>The name already has an owner, | |
| DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either | |
| DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the | |
| current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not | |
| 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> | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UINT32 ReleaseName (in STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| This method call should be sent to | |
| <code class="literal">org.freedesktop.DBus</code> and asks the message bus to | |
| release the method caller's claim to the given name. If the caller is | |
| the primary owner, a new primary owner will be selected from the | |
| queue if any other owners are waiting. If the caller is waiting in | |
| the queue for the name, the caller will removed from the queue and | |
| will not be made an owner of the name if it later becomes available. | |
| If there are no other owners in the queue for the name, it will be | |
| removed from the bus entirely. | |
| The return code can be one of the following values: | |
| </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 | |
| the given name. Either the caller was the primary owner of | |
| the name, and the name is now unused or taken by somebody | |
| waiting in the queue for the name, or the caller was waiting | |
| in the queue for the name and has now been removed from the | |
| 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, | |
| and was also not waiting in the queue to own this name.</td></tr></tbody></table></div><p> | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| ARRAY of STRING ListQueuedOwners (in STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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 | |
| <code class="literal">com.example.cappuccino</code></td></tr></tbody></table></div><p> | |
| Reply arguments: | |
| </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 | |
| for the name</td></tr></tbody></table></div><p> | |
| </p><p> | |
| This method call should be sent to | |
| <code class="literal">org.freedesktop.DBus</code> and lists the connections | |
| currently queued for a bus name (see | |
| <a class="xref" href="#term-queued-owner" title="Queued Name Owner">Queued Name Owner</a>). | |
| </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> | |
| FIXME | |
| </p><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> | |
| An important part of the message bus routing protocol is match | |
| rules. Match rules describe what messages can be sent to a client | |
| based on the contents of the message. When a message is routed | |
| through the bus it is compared to clients' match rules. If any | |
| of the rules match, the message is dispatched to the client. | |
| If none of the rules match the message never leaves the bus. This | |
| is an effective way to control traffic over the bus and to make sure | |
| only relevant message need to be processed by the client. | |
| </p><p> | |
| Match rules are added using the AddMatch bus method | |
| (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 | |
| specified as a string of comma separated key/value pairs. | |
| Excluding a key from the rule indicates a wildcard match. | |
| For instance excluding the the member from a match rule but | |
| adding a sender would let all messages from that sender through. | |
| An example of a complete rule would be | |
| "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'" | |
| </p><p> | |
| The following table describes the keys that can be used to create | |
| a match rule: | |
| The following table summarizes the D-Bus types. | |
| </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> | |
| and <a class="xref" href="#term-unique-name" title="Unique Connection Name">Unique Connection Name</a> respectively) | |
| </td><td>Match messages sent by a particular sender. An example of a sender match | |
| 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 | |
| interface match is interface='org.freedesktop.Hal.Manager'. | |
| If a message omits the interface header, it must not match any rule | |
| 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 | |
| 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 | |
| path match is path='/org/freedesktop/Hal/Manager'</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 | |
| 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 | |
| match based on the arguments in the body of a message. As of this time | |
| only string arguments can be matched. An example of an argument match | |
| would be arg3='Foo'. Only argument indexes from 0 to 63 should be | |
| accepted.</td></tr><tr><td><code class="literal">arg[0, 1, 2, 3, ...]path</code></td><td>Any string</td><td>Argument path matches provide a specialised form of wildcard | |
| matching for path-like namespaces. As with normal argument matches, | |
| if the argument is exactly equal to the string given in the match | |
| rule then the rule is satisfied. Additionally, there is also a | |
| match when either the string given in the match rule or the | |
| appropriate message argument ends with '/' and is a prefix of the | |
| other. An example argument path match is arg0path='/aa/bb/'. This | |
| would match messages with first arguments of '/', '/aa/', | |
| '/aa/bb/', '/aa/bb/cc/' and '/aa/bb/cc'. It would not match | |
| messages with first arguments of '/aa/b', '/aa' or even '/aa/bb'.</td></tr></tbody></table></div><p> | |
| </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> | |
| The message bus can start applications on behalf of other applications. | |
| In CORBA terms, this would be called <em class="firstterm">activation</em>. | |
| An application that can be started in this way is called a | |
| <em class="firstterm">service</em>. | |
| </p><p> | |
| With D-Bus, starting a service is normally done by name. That is, | |
| applications ask the message bus to start some program that will own a | |
| well-known name, such as <code class="literal">org.freedesktop.TextEditor</code>. | |
| This implies a contract documented along with the name | |
| <code class="literal">org.freedesktop.TextEditor</code> for which objects | |
| the owner of that name will provide, and what interfaces those | |
| objects will have. | |
| </p><p> | |
| To find an executable corresponding to a particular name, the bus daemon | |
| looks for <em class="firstterm">service description files</em>. Service | |
| description files define a mapping from names to executables. Different | |
| kinds of message bus will look for these files in different places, see | |
| <a class="xref" href="#message-bus-types" title="Well-known Message Bus Instances">the section called “Well-known Message Bus Instances”</a>. | |
| </p><p> | |
| Service description files have the ".service" file | |
| extension. The message bus will only load service description files | |
| ending with .service; all other files will be ignored. The file format | |
| is similar to that of <a class="ulink" href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html" target="_top">desktop | |
| entries</a>. All service description files must be in UTF-8 | |
| encoding. To ensure that there will be no name collisions, service files | |
| must be namespaced using the same mechanism as messages and service | |
| names. | |
| </p><p> | |
| [FIXME the file format should be much better specified than "similar to | |
| .desktop entries" esp. since desktop entries are already | |
| badly-specified. ;-)] | |
| These sections from the specification apply to service files as well: | |
| </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> | |
| </p><div class="figure"><a name="idp5565600"></a><p class="title"><b>Figure 9. Example service description file</b></p><div class="figure-contents"><pre class="programlisting"> | |
| # Sample service description file | |
| [D-BUS Service] | |
| Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf; | |
| Exec=/usr/libexec/gconfd-2 | |
| </pre></div></div><p><br class="figure-break"> | |
| </p><p> | |
| When an application asks to start a service by name, the bus daemon tries to | |
| find a service that will own that name. It then tries to spawn the | |
| executable associated with it. If this fails, it will report an | |
| error. [FIXME what happens if two .service files offer the same service; | |
| what kind of error is reported, should we have a way for the client to | |
| choose one?] | |
| </p><p> | |
| The executable launched will have the environment variable | |
| <code class="literal">DBUS_STARTER_ADDRESS</code> set to the address of the | |
| message bus so it can connect and request the appropriate names. | |
| </p><p> | |
| The executable being launched may want to know whether the message bus | |
| 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 | |
| the <code class="literal">DBUS_STARTER_BUS_TYPE</code> environment variable if it is one | |
| of the well-known buses. The currently-defined values for this variable | |
| are <code class="literal">system</code> for the systemwide message bus, | |
| and <code class="literal">session</code> for the per-login-session message | |
| bus. The new executable must still connect to the address given | |
| in <code class="literal">DBUS_STARTER_ADDRESS</code>, but may assume that the | |
| resulting connection is to the well-known bus. | |
| </p><p> | |
| [FIXME there should be a timeout somewhere, either specified | |
| in the .service file, by the client, or just a global value | |
| and if the client being activated fails to connect within that | |
| timeout, an error should be sent back.] | |
| </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> | |
| The "scope" of a service is its "per-", such as per-session, | |
| per-machine, per-home-directory, or per-display. The reference | |
| implementation doesn't yet support starting services in a different | |
| scope from the message bus itself. So e.g. if you start a service | |
| on the session bus its scope is per-session. | |
| </p><p> | |
| We could add an optional scope to a bus name. For example, for | |
| per-(display,session pair), we could have a unique ID for each display | |
| generated automatically at login and set on screen 0 by executing a | |
| special "set display ID" binary. The ID would be stored in a | |
| <code class="literal">_DBUS_DISPLAY_ID</code> property and would be a string of | |
| random bytes. This ID would then be used to scope names. | |
| Starting/locating a service could be done by ID-name pair rather than | |
| only by name. | |
| </p><p> | |
| Contrast this with a per-display scope. To achieve that, we would | |
| want a single bus spanning all sessions using a given display. | |
| So we might set a <code class="literal">_DBUS_DISPLAY_BUS_ADDRESS</code> | |
| property on screen 0 of the display, pointing to this bus. | |
| </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> | |
| Two standard message bus instances are defined here, along with how | |
| to locate them and where their service files live. | |
| </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> | |
| Each time a user logs in, a <em class="firstterm">login session message | |
| bus</em> may be started. All applications in the user's login | |
| session may interact with one another using this message bus. | |
| </p><p> | |
| The address of the login session message bus is given | |
| in the <code class="literal">DBUS_SESSION_BUS_ADDRESS</code> environment | |
| variable. If that variable is not set, applications may | |
| also try to read the address from the X Window System root | |
| window property <code class="literal">_DBUS_SESSION_BUS_ADDRESS</code>. | |
| The root window property must have type <code class="literal">STRING</code>. | |
| The environment variable should have precedence over the | |
| root window property. | |
| </p><p>The address of the login session message bus is given in the | |
| <code class="literal">DBUS_SESSION_BUS_ADDRESS</code> environment variable. If | |
| DBUS_SESSION_BUS_ADDRESS is not set, or if it's set to the string | |
| "autolaunch:", the system should use platform-specific methods of | |
| locating a running D-Bus session server, or starting one if a running | |
| instance cannot be found. Note that this mechanism is not recommended | |
| for attempting to determine if a daemon is running. It is inherently | |
| racy to attempt to make this determination, since the bus daemon may | |
| be started just before or just after the determination is made. | |
| Therefore, it is recommended that applications do not try to make this | |
| determination for their functionality purposes, and instead they | |
| 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> | |
| For the X Windowing System, the application must locate the | |
| window owner of the selection represented by the atom formed by | |
| concatenating: | |
| </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> | |
| </p><p> | |
| The following properties are defined for the window that owns | |
| this X selection: | |
| </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td> | |
| <p>Atom</p> | |
| </td><td> | |
| <p>meaning</p> | |
| </td></tr><tr><td> | |
| <p>_DBUS_SESSION_BUS_ADDRESS</p> | |
| </td><td> | |
| <p>the actual address of the server socket</p> | |
| </td></tr><tr><td> | |
| <p>_DBUS_SESSION_BUS_PID</p> | |
| </td><td> | |
| <p>the PID of the server process</p> | |
| </td></tr></tbody></table></div><p> | |
| </p><p> | |
| At least the _DBUS_SESSION_BUS_ADDRESS property MUST be | |
| present in this window. | |
| </p><p> | |
| If the X selection cannot be located or if reading the | |
| properties from the window fails, the implementation MUST conclude | |
| that there is no D-Bus server running and proceed to start a new | |
| server. (See below on concurrency issues) | |
| </p><p> | |
| Failure to connect to the D-Bus server address thus obtained | |
| MUST be treated as a fatal connection error and should be reported | |
| to the application. | |
| </p><p> | |
| As an alternative, an implementation MAY find the information | |
| in the following file located in the current user's home directory, | |
| in subdirectory .dbus/session-bus/: | |
| </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 | |
| following prefixes removed, if present: ":", "localhost:" | |
| ."localhost.localdomain:". That is, a display of | |
| "localhost:10.0" produces just the number "10"</p></li></ul></div><p> | |
| </p><p> | |
| The contents of this file NAME=value assignment pairs and | |
| lines starting with # are comments (no comments are allowed | |
| otherwise). The following variable names are defined: | |
| </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td> | |
| <p>Variable</p> | |
| </td><td> | |
| <p>meaning</p> | |
| </td></tr><tr><td> | |
| <p>DBUS_SESSION_BUS_ADDRESS</p> | |
| </td><td> | |
| <p>the actual address of the server socket</p> | |
| </td></tr><tr><td> | |
| <p>DBUS_SESSION_BUS_PID</p> | |
| </td><td> | |
| <p>the PID of the server process</p> | |
| </td></tr><tr><td> | |
| <p>DBUS_SESSION_BUS_WINDOWID</p> | |
| </td><td> | |
| <p>the window ID</p> | |
| </td></tr></tbody></table></div><p> | |
| </p><p> | |
| At least the DBUS_SESSION_BUS_ADDRESS variable MUST be present | |
| in this file. | |
| </p><p> | |
| Failure to open this file MUST be interpreted as absence of a | |
| running server. Therefore, the implementation MUST proceed to | |
| attempting to launch a new bus server if the file cannot be | |
| opened. | |
| </p><p> | |
| However, success in opening this file MUST NOT lead to the | |
| conclusion that the server is running. Thus, a failure to connect to | |
| the bus address obtained by the alternative method MUST NOT be | |
| considered a fatal error. If the connection cannot be established, | |
| the implementation MUST proceed to check the X selection settings or | |
| to start the server on its own. | |
| </p><p> | |
| If the implementation concludes that the D-Bus server is not | |
| running it MUST attempt to start a new server and it MUST also | |
| ensure that the daemon started as an effect of the "autolaunch" | |
| mechanism provides the lookup mechanisms described above, so | |
| subsequent calls can locate the newly started server. The | |
| implementation MUST also ensure that if two or more concurrent | |
| initiations happen, only one server remains running and all other | |
| initiations are able to obtain the address of this server and | |
| connect to it. In other words, the implementation MUST ensure that | |
| the X selection is not present when it attempts to set it, without | |
| allowing another process to set the selection between the | |
| verification and the setting (e.g., by using XGrabServer / | |
| XungrabServer). | |
| </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idp5618368"></a></h5></div></div></div><p> | |
| [FIXME specify location of .service files, probably using | |
| DESKTOP_DIRS etc. from basedir specification, though login session | |
| bus is not really desktop-specific] | |
| </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> | |
| A computer may have a <em class="firstterm">system message bus</em>, | |
| accessible to all applications on the system. This message bus may be | |
| used to broadcast system events, such as adding new hardware devices, | |
| changes in the printer queue, and so forth. | |
| </p><p> | |
| The address of the system message bus is given | |
| in the <code class="literal">DBUS_SYSTEM_BUS_ADDRESS</code> environment | |
| variable. If that variable is not set, applications should try | |
| to connect to the well-known address | |
| <code class="literal">unix:path=/var/run/dbus/system_bus_socket</code>. | |
| <sup>[<a name="idp5623392" href="#ftn.idp5623392" class="footnote">2</a>]</sup> | |
| </p><p> | |
| [FIXME specify location of system bus .service files] | |
| </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> | |
| The special message bus name <code class="literal">org.freedesktop.DBus</code> | |
| responds to a number of additional messages. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| STRING Hello () | |
| </pre><p> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| Before an application is able to send messages to other applications | |
| it must send the <code class="literal">org.freedesktop.DBus.Hello</code> message | |
| to the message bus to obtain a unique name. If an application without | |
| a unique name tries to send a message to another application, or a | |
| message to the message bus itself that isn't the | |
| <code class="literal">org.freedesktop.DBus.Hello</code> message, it will be | |
| disconnected from the bus. | |
| </p><p> | |
| There is no corresponding "disconnect" request; if a client wishes to | |
| disconnect from the bus, it simply closes the socket (or other | |
| communication channel). | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| ARRAY of STRING ListNames () | |
| </pre><p> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| Returns a list of all currently-owned names on the bus. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| ARRAY of STRING ListActivatableNames () | |
| </pre><p> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| Returns a list of all names that can be activated on the bus. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| BOOLEAN NameHasOwner (in STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Reply arguments: | |
| </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> | |
| </p><p> | |
| Checks if the specified name exists (currently has an owner). | |
| </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> | |
| This is a signal: | |
| </p><pre class="programlisting"> | |
| NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| </p><p> | |
| This signal indicates that the owner of a name has changed. | |
| It's also the signal to use to detect the appearance of | |
| new names on the bus. | |
| </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> | |
| This is a signal: | |
| </p><pre class="programlisting"> | |
| NameLost (STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| </p><p> | |
| This signal is sent to a specific application when it loses | |
| ownership of a name. | |
| </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> | |
| This is a signal: | |
| </p><pre class="programlisting"> | |
| NameAcquired (STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| </p><p> | |
| This signal is sent to a specific application when it gains | |
| ownership of a name. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UINT32 StartServiceByName (in STRING name, in UINT32 flags) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Reply arguments: | |
| </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> | |
| 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>. | |
| </p><p> | |
| The return value can be one of the following values: | |
| </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> | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Normally, session bus activated services inherit the environment of the bus daemon. This method adds to or modifies that environment when activating services. | |
| </p><p> | |
| Some bus instances, such as the standard system bus, may disable access to this method for some or all callers. | |
| </p><p> | |
| 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. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| STRING GetNameOwner (in STRING name) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| Reply arguments: | |
| </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> | |
| Returns the unique connection name of the primary owner of the name | |
| given. If the requested name doesn't have an owner, returns a | |
| <code class="literal">org.freedesktop.DBus.Error.NameHasNoOwner</code> error. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UINT32 GetConnectionUnixUser (in STRING bus_name) | |
| </pre><p> | |
| Message arguments: | |
| </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 | |
| query, such as <code class="literal">:12.34</code> or | |
| <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p> | |
| Reply arguments: | |
| </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> | |
| Returns the Unix user ID of the process connected to the server. If | |
| unable to determine it (for instance, because the process is not on the | |
| same machine as the bus daemon), an error is returned. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| UINT32 GetConnectionUnixProcessID (in STRING bus_name) | |
| </pre><p> | |
| Message arguments: | |
| </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 | |
| query, such as <code class="literal">:12.34</code> or | |
| <code class="literal">com.example.tea</code></td></tr></tbody></table></div><p> | |
| Reply arguments: | |
| </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> | |
| Returns the Unix process ID of the process connected to the server. If | |
| unable to determine it (for instance, because the process is not on the | |
| same machine as the bus daemon), an error is returned. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| AddMatch (in STRING rule) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| 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>). | |
| If the bus does not have enough resources the <code class="literal">org.freedesktop.DBus.Error.OOM</code> | |
| error is returned. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| RemoveMatch (in STRING rule) | |
| </pre><p> | |
| Message arguments: | |
| </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> | |
| 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>). | |
| If the rule is not found the <code class="literal">org.freedesktop.DBus.Error.MatchRuleNotFound</code> | |
| error is returned. | |
| </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> | |
| As a method: | |
| </p><pre class="programlisting"> | |
| GetId (out STRING id) | |
| </pre><p> | |
| Reply arguments: | |
| </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> | |
| Gets the unique ID of the bus. The unique ID here is shared among all addresses the | |
| bus daemon is listening on (TCP, UNIX domain socket, etc.) and its format is described in | |
| <a class="xref" href="#uuids" title="UUIDs">the section called “UUIDs”</a>. Each address the bus is listening on also has its own unique | |
| 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. | |
| 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 | |
| by org.freedesktop.DBus.Peer.GetMachineId(). | |
| For a desktop session bus, the bus ID can be used as a way to uniquely identify a user's session. | |
| </p></div></div></div><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a name="idp5788992"></a>Glossary</h2></div></div></div><p> | |
| This glossary defines some of the terms used in this specification. | |
| </p><dl><dt><a name="term-bus-name"></a>Bus Name</dt><dd><p> | |
| The message bus maintains an association between names and | |
| connections. (Normally, there's one connection per application.) A | |
| bus name is simply an identifier used to locate connections. For | |
| example, the hypothetical <code class="literal">com.yoyodyne.Screensaver</code> | |
| name might be used to send a message to a screensaver from Yoyodyne | |
| Corporation. An application is said to <em class="firstterm">own</em> a | |
| name if the message bus has associated the application's connection | |
| with the name. Names may also have <em class="firstterm">queued | |
| owners</em> (see <a class="xref" href="#term-queued-owner" title="Queued Name Owner">Queued Name Owner</a>). | |
| The bus assigns a unique name to each connection, | |
| see <a class="xref" href="#term-unique-name" title="Unique Connection Name">Unique Connection Name</a>. Other names | |
| can be thought of as "well-known names" and are | |
| used to find applications that offer specific functionality. | |
| </p></dd><dt><a name="term-message"></a>Message</dt><dd><p> | |
| A message is the atomic unit of communication via the D-Bus | |
| protocol. It consists of a <em class="firstterm">header</em> and a | |
| <em class="firstterm">body</em>; the body is made up of | |
| <em class="firstterm">arguments</em>. | |
| </p></dd><dt><a name="term-message-bus"></a>Message Bus</dt><dd><p> | |
| The message bus is a special application that forwards | |
| or routes messages between a group of applications | |
| connected to the message bus. It also manages | |
| <em class="firstterm">names</em> used for routing | |
| messages. | |
| </p></dd><dt><a name="term-name"></a>Name</dt><dd><p> | |
| See <a class="xref" href="#term-bus-name" title="Bus Name">Bus Name</a>. "Name" may | |
| also be used to refer to some of the other names | |
| in D-Bus, such as interface names. | |
| </p></dd><dt><a name="namespace"></a>Namespace</dt><dd><p> | |
| Used to prevent collisions when defining new interfaces or bus | |
| names. The convention used is the same one Java uses for defining | |
| classes: a reversed domain name. | |
| </p></dd><dt><a name="term-object"></a>Object</dt><dd><p> | |
| Each application contains <em class="firstterm">objects</em>, which have | |
| <em class="firstterm">interfaces</em> and | |
| <em class="firstterm">methods</em>. Objects are referred to by a name, | |
| called a <em class="firstterm">path</em>. | |
| </p></dd><dt><a name="one-to-one"></a>One-to-One</dt><dd><p> | |
| An application talking directly to another application, without going | |
| through a message bus. One-to-one connections may be "peer to peer" or | |
| "client to server." The D-Bus protocol has no concept of client | |
| vs. server after a connection has authenticated; the flow of messages | |
| is symmetrical (full duplex). | |
| </p></dd><dt><a name="term-path"></a>Path</dt><dd><p> | |
| Object references (object names) in D-Bus are organized into a | |
| filesystem-style hierarchy, so each object is named by a path. As in | |
| LDAP, there's no difference between "files" and "directories"; a path | |
| can refer to an object, while still having child objects below it. | |
| </p></dd><dt><a name="term-queued-owner"></a>Queued Name Owner</dt><dd><p> | |
| Each bus name has a primary owner; messages sent to the name go to the | |
| primary owner. However, certain names also maintain a queue of | |
| secondary owners "waiting in the wings." If the primary owner releases | |
| the name, then the first secondary owner in the queue automatically | |
| becomes the new owner of the name. | |
| </p></dd><dt><a name="term-service"></a>Service</dt><dd><p> | |
| A service is an executable that can be launched by the bus daemon. | |
| Services normally guarantee some particular features, for example they | |
| may guarantee that they will request a specific name such as | |
| "org.freedesktop.Screensaver", have a singleton object | |
| "/org/freedesktop/Application", and that object will implement the | |
| interface "org.freedesktop.ScreensaverControl". | |
| </p></dd><dt><a name="term-service-description-files"></a>Service Description Files</dt><dd><p> | |
| ".service files" tell the bus about service applications that can be | |
| launched (see <a class="xref" href="#term-service" title="Service">Service</a>). Most importantly they | |
| provide a mapping from bus names to services that will request those | |
| names when they start up. | |
| </p></dd><dt><a name="term-unique-name"></a>Unique Connection Name</dt><dd><p> | |
| The special name automatically assigned to each connection by the | |
| message bus. This name will never change owner, and will be unique | |
| (never reused during the lifetime of the message bus). | |
| It will begin with a ':' character. | |
| </p></dd></dl></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.idp5260576" href="#idp5260576" class="para">1</a>] </sup>Lockfiles are used instead of real file | |
| locking <code class="literal">fcntl()</code> because real locking | |
| implementations are still flaky on network | |
| filesystems.</p></div><div class="footnote"><p><sup>[<a name="ftn.idp5623392" href="#idp5623392" class="para">2</a>] </sup> | |
| The D-Bus reference implementation actually honors the | |
| <code class="literal">$(localstatedir)</code> configure option | |
| for this address, on both client and server side. | |
| </p></div></div></div></body></html> |