<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.11</releaseinfo>
- <date>6 February 2005</date>
+ <releaseinfo>Version 0.12</releaseinfo>
+ <date>7 November 2006</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
</itemizedlist>
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. D-Bus may turn out to be useful
- in unanticipated applications, but future versions of this
- spec and the reference implementation probably will not
+ IPC systems for this reason.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
</para>
document could use a serious audit to be sure it makes sense to do
so. Also, they are not capitalized.
</para>
+
+ <sect2 id="stability">
+ <title>Protocol and Specification Stability</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Nonetheless, this document should be a useful starting point and is
+ to our knowledge accurate, though incomplete.
+ </para>
+ </sect2>
</sect1>
A signal emission is simply a single message of type <literal>SIGNAL</literal>.
It must have three header fields: <literal>PATH</literal> giving the object
the signal was emitted from, plus <literal>INTERFACE</literal> and <literal>MEMBER</literal> giving
- the fully-qualified name of the signal.
+ the fully-qualified name of the signal. The <literal>INTERFACE</literal> header is required
+ for signals, though it is optional for method calls.
</para>
</sect3>
<para>
A server may specify a key-value pair with the key <literal>guid</literal>
- and the value a hex-encoded 16-byte sequence. This globally unique ID must
- be created by filling the first 4 bytes with a 32-bit UNIX time since the
- epoch, and the remaining 12 bytes with random bytes. If present, the GUID
- may be used to distinguish one server from another. A server should use a
- different GUID 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 GUIDs to distinguish
- the kinds of connection.
+ and the value a hex-encoded 16-byte sequence. <xref linkend="uuids"/>
+ describes the format of the <literal>guid</literal> 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.
</para>
<para>
- The intent of the GUID 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.
+ 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).
+ </para>
+
+ <para>
+ Note that the address key is <literal>guid</literal> even though the
+ rest of the API and documentation says "UUID," for historical reasons.
</para>
<para>
hyphens.
</para>
</sect1>
+
+ <sect1 id="uuids">
+ <title>UUIDs</title>
+ <para>
+ 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 <xref linkend="addresses"/>. 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 <xref
+ linkend="standard-interfaces-peer"/>).
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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).
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Implementations should, however, stick to random data for the first 96 bits
+ of the UUID.
+ </para>
+ </sect1>
<sect1 id="standard-interfaces">
<title>Standard Interfaces</title>
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 may change due to reconfiguration or hardware changes.
+ 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.
</para>
<para>
- The UUID must contain 128 bits of data and be hex-encoded (meaning, the hex
- string contains 32 ASCII characters). 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 recommended algorithm is to put the current time in seconds
- since the UNIX epoch in the last 32 bits of the UUID, and to put randomly-generated bits
- in the first 96 bits of the UUID.
- </para>
- <para>
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.
</para>
+ <para>
+ 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.
+ </para>
+ <para>
+ <xref linkend="uuids"/> explains the format of the UUID.
+ </para>
</sect2>
<sect2 id="standard-interfaces-introspectable">
<entry><literal>interface</literal></entry>
<entry>An interface name (see <xref linkend="message-protocol-names-interface"/>)</entry>
<entry>Match messages sent over or to a particular interface. An example of an
- interface match is interface='org.freedesktop.Hal.Manager'</entry>
+ 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.</entry>
</row>
<row>
<entry><literal>member</literal></entry>
example of a destination match is destination=':1.0'</entry>
</row>
<row>
- <entry><literal>arg[1, 2, 3, ...]</literal></entry>
+ <entry><literal>arg[0, 1, 2, 3, ...]</literal></entry>
<entry>Any string</entry>
<entry>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'.</entry>
+ would be arg3='Foo'. Only argument indexes from 0 to 63 should be
+ accepted.</entry>
</row>
</tbody>
</tgroup>
projects / platform / upstream / dbus.git / blobdiff