<article id="index">
<articleinfo>
- <title>D-BUS Specification</title>
- <releaseinfo>Version 0.11</releaseinfo>
- <date>6 February 2005</date>
+ <title>D-Bus Specification</title>
+ <releaseinfo>Version 0.12</releaseinfo>
+ <date>7 November 2006</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
<sect1 id="introduction">
<title>Introduction</title>
<para>
- D-BUS is a system for low-latency, low-overhead, easy to use
+ D-Bus is a system for low-latency, low-overhead, easy to use
interprocess communication (IPC). In more detail:
<itemizedlist>
<listitem>
<para>
- D-BUS is <emphasis>low-latency</emphasis> because it is designed
+ D-Bus is <emphasis>low-latency</emphasis> because it is designed
to avoid round trips and allow asynchronous operation, much like
the X protocol.
</para>
</listitem>
<listitem>
<para>
- D-BUS is <emphasis>low-overhead</emphasis> because it uses a
+ D-Bus is <emphasis>low-overhead</emphasis> 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
+ 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.
</para>
</listitem>
<listitem>
<para>
- D-BUS is <emphasis>easy to use</emphasis> because it works in terms
+ D-Bus is <emphasis>easy to use</emphasis> because it works in terms
of <firstterm>messages</firstterm> rather than byte streams, and
- automatically handles a lot of the hard IPC issues. Also, the D-BUS
+ 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.
</para>
<para>
- The base D-BUS protocol is a one-to-one (peer-to-peer or client-server)
+ The base D-Bus protocol is a one-to-one (peer-to-peer or client-server)
protocol, specified in <xref linkend="message-protocol"/>. 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 <firstterm>message bus</firstterm>, specified in <xref
+ D-Bus <firstterm>message bus</firstterm>, specified in <xref
linkend="message-bus"/>. The message bus is a special application that
accepts connections from multiple other applications, and forwards
messages among them.
</para>
<para>
- Uses of D-BUS include notification of system changes (notification of when
+ 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.
</para>
<para>
- D-BUS is designed for two specific use cases:
+ D-Bus is designed for two specific use cases:
<itemizedlist>
<listitem>
<para>
</para>
</listitem>
</itemizedlist>
- D-BUS is not intended to be a generic IPC system for any possible
+ 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>
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 inteprets the body of the message.
+ it; the recipient interprets the body of the message.
</para>
<para>
<title>Type Signatures</title>
<para>
- The D-BUS protocol does not include type tags in the marshaled data; a
+ The D-Bus protocol does not include type tags in the marshaled data; a
block of marshaled values must have a known <firstterm>type
signature</firstterm>. The type signature is made up of <firstterm>type
codes</firstterm>. A type code is an ASCII character representing the
</para>
<para>
- The <literal>STRUCT</literal> type code 'r' is not currently used in the D-BUS protocol,
+ The <literal>STRUCT</literal> 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.
</para>
</para>
<para>
- The following table summarizes the D-BUS types.
+ The following table summarizes the D-Bus types.
<informaltable>
<tgroup cols="3">
<thead>
<para>
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.
+ order and alignment issues are handled uniformly for all D-Bus types.
</para>
<para>
A block of bytes has an associated byte order. The byte order
- has to be discovered in some way; for D-BUS messages, the
+ has to be discovered in some way; for D-Bus messages, the
byte order is part of the message header as described in
<xref linkend="message-protocol-messages"/>. For now, assume
that the byte order is known to be either little endian or big
<para>
An object path is a name used to refer to an object instance.
- Conceptually, each participant in a D-BUS message exchange may have
+ 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.
<entry>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
+ D-Bus connection must be disconnected. The major protocol
version for this version of the specification is 0.
FIXME this field is stupid and pointless to put in
every message.
<sect2 id="message-protocol-names">
<title>Valid Names</title>
<para>
- The various names in D-BUS messages have some restrictions.
+ The various names in D-Bus messages have some restrictions.
</para>
<para>
There is a <firstterm>maximum name length</firstterm>
<sect4 id="message-protocol-types-method-apis">
<title>Mapping method calls to native APIs</title>
<para>
- APIs for D-BUS may map method calls to a method call in a specific
+ 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.
+ in an IDL to a D-Bus message.
</para>
<para>
In APIs of this nature, arguments to a method are often termed "in"
(which implies sent in the <literal>METHOD_CALL</literal>), or "out" (which implies
returned in the <literal>METHOD_RETURN</literal>). 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"
+ 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.
exceptions.
</para>
<para>
- In converting from native APIs to D-BUS, it is perhaps nice to
- map D-BUS naming conventions ("FooBar") to native conventions
+ 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
+ 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,
+ 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.
</para>
<para>
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>
<title>Invalid Protocol and Spec Extensions</title>
<para>
- For security reasons, the D-BUS protocol should be strictly parsed and
+ 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 idiosyncracy of a widely-deployed implementation. In
+ 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.
</para>
<para>
- The following extension points are built in to D-BUS on purpose and must
+ 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
+ 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.
<para>
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.
+ stream of D-Bus messages.
</para>
<para>
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.
+ authenticated/encrypted stream of D-Bus messages.
</para>
</sect2>
<sect2 id="auth-command-cancel">
<para>
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.
+ authenticated/encrypted stream of D-Bus messages.
</para>
</sect2>
<sect2 id="auth-command-rejected">
<title>OK Command</title>
<para>
The OK command indicates that the client has been authenticated,
- and that further communication will be a stream of D-BUS messages
+ and that further communication will be a stream of D-Bus messages
(optionally encrypted, as negotiated) rather than this protocol.
</para>
<para>
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.
+ stream of D-Bus messages.
</para>
<para>
The client must respond to the OK command by sending a BEGIN
if only canceling/rejecting the authentication.
</para>
<para>
- If the D-BUS protocol changes incompatibly at some future time,
+ 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.
+ negotiate extensions or changes to the D-Bus protocol in the future.
</para>
</sect2>
<sect2 id="auth-examples">
<title>Authentication mechanisms</title>
<para>
This section describes some new authentication mechanisms.
- D-BUS also allows any standard SASL mechanism of course.
+ D-Bus also allows any standard SASL mechanism of course.
</para>
<sect3 id="auth-mechanisms-sha">
<title>DBUS_COOKIE_SHA1</title>
<para>
The client locates the cookie, and generates its own hex-encoded
randomly-generated challenge string. The client then
- concatentates the server's hex-encoded challenge, a ":"
+ concatenates the server's hex-encoded challenge, a ":"
character, its own hex-encoded challenge, another ":" character,
and the hex-encoded cookie. It computes the SHA-1 hash of this
composite string. It sends back to the server the client's
<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>
<title>Unix Domain Sockets</title>
<para>
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 i
+ kernels, they can be abstract which are similar to paths but
do not show up in the file system.
</para>
<para>
When a socket is opened by the D-Bus library it truncates the path
- name right befor the first trailing Nul byte. This is true for both
+ 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
<title>Naming Conventions</title>
<para>
- D-BUS namespaces are all lowercase and correspond to reversed domain
+ D-Bus namespaces are all lowercase and correspond to reversed domain
names, as with Java. e.g. "org.freedesktop"
</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>
<para>
See <xref linkend="message-protocol-types-notation"/> for details on
the notation used in this section. There are some standard interfaces
- that may be useful across various D-BUS applications.
+ that may be useful across various D-Bus applications.
</para>
<sect2 id="standard-interfaces-peer">
<title><literal>org.freedesktop.DBus.Peer</literal></title>
<para>
The <literal>org.freedesktop.DBus.Peer</literal> interface
- has one method:
+ has two methods:
<programlisting>
org.freedesktop.DBus.Peer.Ping ()
+ org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
</programlisting>
</para>
<para>
<literal>org.freedesktop.DBus.Peer.Ping</literal>, an application should do
nothing other than reply with a <literal>METHOD_RETURN</literal> as
usual. It does not matter which object path a ping is sent to. The
- reference implementation should simply handle this method on behalf of
- all objects, though it doesn't yet. (The point is, you're really pinging
- the peer process, not a specific object.)
+ reference implementation handles this method automatically.
+ </para>
+ <para>
+ On receipt of the <literal>METHOD_CALL</literal> message
+ <literal>org.freedesktop.DBus.Peer.GetMachineId</literal>, an application should
+ reply with a <literal>METHOD_RETURN</literal> 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.
+ </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>
<para>
The following table describes the keys that can be used to create
a match rule:
- The following table summarizes the D-BUS types.
+ The following table summarizes the D-Bus types.
<informaltable>
<tgroup cols="3">
<thead>
<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>
<firstterm>service</firstterm>.
</para>
<para>
- With D-BUS, starting a service is normally done by name. That is,
+ 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 <literal>org.freedesktop.TextEditor</literal>.
This implies a contract documented along with the name
<literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
<footnote>
<para>
- The D-BUS reference implementation actually honors the
+ The D-Bus reference implementation actually honors the
<literal>$(localstatedir)</literal> configure option
for this address, on both client and server side.
</para>
<glossentry id="term-message"><glossterm>Message</glossterm>
<glossdef>
<para>
- A message is the atomic unit of communication via the D-BUS
+ A message is the atomic unit of communication via the D-Bus
protocol. It consists of a <firstterm>header</firstterm> and a
<firstterm>body</firstterm>; the body is made up of
<firstterm>arguments</firstterm>.
<para>
See <xref linkend="term-bus-name"/>. "Name" may
also be used to refer to some of the other names
- in D-BUS, such as interface names.
+ in D-Bus, such as interface names.
</para>
</glossdef>
</glossentry>
<para>
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
+ "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).
</para>
<glossentry id="term-path"><glossterm>Path</glossterm>
<glossdef>
<para>
- Object references (object names) in D-BUS are organized into a
+ 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.
projects / platform / upstream / dbus.git / blobdiff