<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.15</releaseinfo>
- <date>3 November 2010</date>
+ <releaseinfo>Version 0.17</releaseinfo>
+ <date>(not final)</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
</address>
</affiliation>
</author>
+ <author>
+ <firstname>Sven</firstname>
+ <surname>Herzberg</surname>
+ <affiliation>
+ <orgname>Imendio AB</orgname>
+ <address>
+ <email>sven@imendio.com</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
<revhistory>
<revision>
<revremark></revremark>
</revision>
<revision>
+ <revnumber>0.16</revnumber>
+ <date>11 April 2011</date>
+ <authorinitials></authorinitials>
+ <revremark>add path_namespace, arg0namespace; argNpath matches object
+ paths</revremark>
+ </revision>
+ <revision>
<revnumber>0.15</revnumber>
<date>3 November 2010</date>
<authorinitials></authorinitials>
</row><row>
<entry><literal>STRUCT</literal></entry>
<entry>114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')</entry>
- <entry>Struct</entry>
+ <entry>Struct; type code 114 'r' is reserved for use in
+ bindings and implementations to represent the general
+ concept of a struct, and must not appear in signatures
+ used on D-Bus.</entry>
</row><row>
<entry><literal>VARIANT</literal></entry>
<entry>118 (ASCII 'v') </entry>
</row><row>
<entry><literal>DICT_ENTRY</literal></entry>
<entry>101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}') </entry>
- <entry>Entry in a dict or map (array of key-value pairs)</entry>
+ <entry>Entry in a dict or map (array of key-value pairs).
+ Type code 101 'e' is reserved for use in bindings and
+ implementations to represent the general concept of a
+ dict or dict-entry, and must not appear in signatures
+ used on D-Bus.</entry>
</row><row>
<entry><literal>UNIX_FD</literal></entry>
<entry>104 (ASCII 'h')</entry>
<entry>Unix file descriptor</entry>
</row>
+ <row>
+ <entry>(reserved)</entry>
+ <entry>109 (ASCII 'm')</entry>
+ <entry>Reserved for <ulink
+ url="https://bugs.freedesktop.org/show_bug.cgi?id=27857">a
+ 'maybe' type compatible with the one in GVariant</ulink>,
+ and must not appear in signatures used on D-Bus until
+ specified here</entry>
+ </row>
+ <row>
+ <entry>(reserved)</entry>
+ <entry>42 (ASCII '*')</entry>
+ <entry>Reserved for use in bindings/implementations to
+ represent any <firstterm>single complete type</firstterm>,
+ and must not appear in signatures used on D-Bus.</entry>
+ </row>
+ <row>
+ <entry>(reserved)</entry>
+ <entry>63 (ASCII '?')</entry>
+ <entry>Reserved for use in bindings/implementations to
+ represent any <firstterm>basic type</firstterm>, and must
+ not appear in signatures used on D-Bus.</entry>
+ </row>
+ <row>
+ <entry>(reserved)</entry>
+ <entry>64 (ASCII '@'), 38 (ASCII '&'),
+ 94 (ASCII '^')</entry>
+ <entry>Reserved for internal use by bindings/implementations,
+ and must not appear in signatures used on D-Bus.
+ GVariant uses these type-codes to encode calling
+ conventions.</entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
</row><row>
<entry><literal>VARIANT</literal></entry>
<entry>
- A variant type has a marshaled <literal>SIGNATURE</literal>
- 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.
+ A variant type has a marshaled
+ <literal>SIGNATURE</literal> 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.
</entry>
<entry>
1 (alignment of the signature)
</itemizedlist>
</para>
+ <para>
+ Object paths are often namespaced by starting with a reversed
+ domain name and containing an interface version number, in the
+ same way as
+ <link linkend="message-protocol-names-interface">interface
+ names</link> and
+ <link linkend="message-protocol-names-bus">well-known
+ bus names</link>.
+ This makes it possible to implement more than one service, or
+ more than one version of a service, in the same process,
+ even if the services share a connection but cannot otherwise
+ co-operate (for instance, if they are implemented by different
+ plugins).
+ </para>
+
+ <para>
+ For instance, if the owner of <literal>example.com</literal> is
+ developing a D-Bus API for a music player, they might use the
+ hierarchy of object paths that start with
+ <literal>/com/example/MusicPlayer1</literal> for its objects.
+ </para>
</sect3>
-
<sect3 id="message-protocol-marshaling-signature">
<title>Valid Signatures</title>
<para>
<listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
</itemizedlist>
</para>
+
+ <para>
+ Interface names should start with the reversed DNS domain name of
+ the author of the interface (in lower-case), like interface names
+ in Java. It is conventional for the rest of the interface name
+ to consist of words run together, with initial capital letters
+ on all words ("CamelCase"). Several levels of hierarchy can be used.
+ It is also a good idea to include the major version of the interface
+ in the name, and increment it if incompatible changes are made;
+ this way, a single object can implement several versions of an
+ interface in parallel, if necessary.
+ </para>
+
+ <para>
+ For instance, if the owner of <literal>example.com</literal> is
+ developing a D-Bus API for a music player, they might define
+ interfaces called <literal>com.example.MusicPlayer1</literal>,
+ <literal>com.example.MusicPlayer1.Track</literal> and
+ <literal>com.example.MusicPlayer1.Seekable</literal>.
+ </para>
+
+ <para>
+ D-Bus does not distinguish between the concepts that would be
+ called classes and interfaces in Java: either can be identified on
+ D-Bus by an interface name.
+ </para>
</sect3>
<sect3 id="message-protocol-names-bus">
<title>Bus names</title>
<para>
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 connection has exactly one bus name that is a <firstterm>unique
+ connection name</firstterm>. The unique connection name remains
+ with the connection for its entire lifetime.
A bus name is of type <literal>STRING</literal>,
meaning that it must be valid UTF-8. However, there are also
some additional restrictions that apply to bus names
specifically:
<itemizedlist>
<listitem><para>Bus names that start with a colon (':')
- character are unique connection names.
+ character are unique connection names. Other bus names
+ are called <firstterm>well-known bus names</firstterm>.
</para>
</listitem>
<listitem><para>Bus names are composed of 1 or more elements separated by
Note that the hyphen ('-') character is allowed in bus names but
not in interface names.
</para>
+
+ <para>
+ Like <link linkend="message-protocol-names-interface">interface
+ names</link>, well-known bus names should start with the
+ reversed DNS domain name of the author of the interface (in
+ lower-case), and it is conventional for the rest of the well-known
+ bus name to consist of words run together, with initial
+ capital letters. As with interface names, including a version
+ number in well-known bus names is a good idea; it's possible to
+ have the well-known bus name for more than one version
+ simultaneously if backwards compatibility is required.
+ </para>
+
+ <para>
+ If a well-known bus name implies the presence of a "main" interface,
+ that "main" interface is often given the same name as
+ the well-known bus name, and situated at the corresponding object
+ path. For instance, if the owner of <literal>example.com</literal>
+ is developing a D-Bus API for a music player, they might define
+ that any application that takes the well-known name
+ <literal>com.example.MusicPlayer1</literal> should have an object
+ at the object path <literal>/com/example/MusicPlayer1</literal>
+ which implements the interface
+ <literal>com.example.MusicPlayer1</literal>.
+ </para>
</sect3>
<sect3 id="message-protocol-names-member">
<title>Member names</title>
<listitem><para>Must be at least 1 byte in length.</para></listitem>
</itemizedlist>
</para>
+
+ <para>
+ It is conventional for member names on D-Bus to consist of
+ capitalized words with no punctuation ("camel-case").
+ Method names should usually be verbs, such as
+ <literal>GetItems</literal>, and signal names should usually be
+ a description of an event, such as <literal>ItemsChanged</literal>.
+ </para>
</sect3>
<sect3 id="message-protocol-names-error">
<title>Error names</title>
<para>
Error names have the same restrictions as interface names.
</para>
+
+ <para>
+ Error names have the same naming conventions as interface
+ names, and often contain <literal>.Error.</literal>; for instance,
+ the owner of <literal>example.com</literal> might define the
+ errors <literal>com.example.MusicPlayer.Error.FileNotFound</literal>
+ and <literal>com.example.MusicPlayer.Error.OutOfMemory</literal>.
+ The errors defined by D-Bus itself, such as
+ <literal>org.freedesktop.DBus.Error.Failed</literal>, follow a
+ similar pattern.
+ </para>
</sect3>
</sect2>
[FIXME we need to specify in detail each transport and its possible arguments]
Current transports include: unix domain sockets (including
- abstract namespace on linux), TCP/IP, and a debug/testing transport using
- in-process pipes. Future possible transports include one that
+ 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.
</para>
</informaltable>
</sect3>
</sect2>
+ <sect2 id="transports-launchd">
+ <title>launchd</title>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ <para>
+ launchd is not available on Microsoft Windows.
+ </para>
+ <sect3 id="transports-launchd-addresses">
+ <title>Server Address Format</title>
+ <para>
+ launchd addresses are identified by the "launchd:" prefix
+ and support the following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>env</entry>
+ <entry>(environment variable)</entry>
+ <entry>path of the unix domain socket for the launchd created dbus-daemon.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+ </sect2>
<sect2 id="transports-tcp-sockets">
<title>TCP Sockets</title>
<para>
</informaltable>
</sect3>
</sect2>
-
- </sect1>
-
- <sect1 id="naming-conventions">
- <title>Naming Conventions</title>
-
- <para>
- D-Bus namespaces are all lowercase and correspond to reversed domain
- names, as with Java. e.g. "org.freedesktop"
- </para>
- <para>
- Interface, signal, method, and property names are "WindowsStyleCaps", note
- that the first letter is capitalized, unlike Java.
- </para>
+ </sect1>
+ <sect1 id="meta-transports">
+ <title>Meta Transports</title>
<para>
- Object paths are normally all lowercase with underscores used rather than
- hyphens.
+ Meta transports are a kind of transport with special enhancements or
+ behavior. Currently available meta transports include: autolaunch
</para>
- </sect1>
+
+ <sect2 id="meta-transports-autolaunch">
+ <title>Autolaunch</title>
+ <para>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.
+ </para>
+ <sect3 id="meta-transports-autolaunch-addresses">
+ <title>Server Address Format</title>
+ <para>
+ Autolaunch addresses uses the "autolaunch:" prefix and support the
+ following key/value pairs:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>scope</entry>
+ <entry>(string)</entry>
+ <entry>scope of autolaunch (Windows only)
+ <itemizedlist>
+ <listitem>
+ <para>
+ "*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.
+ <programlisting>
+ <install-root>/bin/[lib]dbus-1.dll
+ <install-root>/[lib]dbus-1.dll
+ </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ "*user" - limit session bus to the recent user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ other values - specify dedicated session bus like "release",
+ "debug" or other
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3 id="meta-transports-autolaunch-windows-implementation">
+ <title>Windows implementation</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </sect3>
+ </sect2>
+ </sect1>
<sect1 id="uuids">
<title>UUIDs</title>
path match is path='/org/freedesktop/Hal/Manager'</entry>
</row>
<row>
+ <entry><literal>path_namespace</literal></entry>
+ <entry>An object path</entry>
+ <entry>
+ <para>
+ Matches messages which are sent from or to an
+ object for which the object path is either the
+ given value, or that value followed by one or
+ more path components.
+ </para>
+
+ <para>
+ For example,
+ <literal>path_namespace='/com/example/foo'</literal>
+ would match signals sent by
+ <literal>/com/example/foo</literal>
+ or by
+ <literal>/com/example/foo/bar</literal>,
+ but not by
+ <literal>/com/example/foobar</literal>.
+ </para>
+
+ <para>
+ Using both <literal>path</literal> and
+ <literal>path_namespace</literal> in the same match
+ rule is not allowed.
+ </para>
+
+ <para>
+ <emphasis>
+ This match key was added in version 0.16 of the
+ D-Bus specification and implemented by the bus
+ daemon in dbus 1.5.0 and later.
+ </emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
<entry><literal>destination</literal></entry>
<entry>A unique name (see <xref linkend="term-unique-name"/>)</entry>
<entry>Matches messages which are being sent to the given unique name. An
argument <literal>"/ca/example/"</literal> to represent atomic modification of
many properties within that directory, and the interested application would be
notified in both cases.</para>
+ <para>
+ <emphasis>
+ This match key was added in version 0.12 of the
+ D-Bus specification, implemented for STRING
+ arguments by the bus daemon in dbus 1.2.0 and later,
+ and implemented for OBJECT_PATH arguments in dbus 1.5.0
+ and later.
+ </emphasis>
+ </para>
</entry>
</row>
<row>
<entry><literal>arg0namespace</literal></entry>
- <entry>Like a bus name or interface name, except that the string may contain only
- one element, and may end with a trailing period</entry>
+ <entry>Like a bus name, except that the string is not
+ required to contain a '.' (period)</entry>
<entry>
<para>Match messages whose first argument is of type STRING, and is a bus name
or interface name within the specified namespace. This is primarily intended
for watching name owner changes for a group of related bus names, rather than
for a single name or all name changes.</para>
- <para>If the value has a trailing period, then only bus names or interface names
- within that namespace are matched. If it has no trailing period, an exact
- match is also allowed.</para>
+ <para>Because every valid interface name is also a valid
+ bus name, this can also be used for messages whose
+ first argument is an interface name.</para>
<para>For example, the match rule
<literal>member='NameOwnerChanged',arg0namespace='com.example.backend'</literal>
<literal>com.example.backend.foo.bar</literal>, and
<literal>com.example.backend</literal> itself.</para>
- <para>On the other hand, the match rule
- <literal>member='NameOwnerChanged',arg0namespace='com.example.backend.'</literal>
- (with a trailing period in the namespace) matches owner changes for
- <literal>com.example.backend.foo</literal> and
- <literal>com.example.backend.foo.bar</literal>, but not for
- <literal>com.example.backend</literal>.
- </para>
-
<para>See also <xref linkend='bus-messages-name-owner-changed'/>.</para>
+ <para>
+ <emphasis>
+ This match key was added in version 0.16 of the
+ D-Bus specification and implemented by the bus
+ daemon in dbus 1.5.0 and later.
+ </emphasis>
+ </para>
</entry>
</row>
</tbody>
<xref linkend="message-bus-types"/>.
</para>
<para>
- [FIXME the file format should be much better specified than "similar to
- .desktop entries" esp. since desktop entries are already
- badly-specified. ;-)] Service description files have the ".service" file
+ 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 <ulink
encoding. To ensure that there will be no name collisions, service files
must be namespaced using the same mechanism as messages and service
names.
+ </para>
+
+ <para>
+ [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:
+
+ <itemizedlist>
+ <listitem><para>General syntax</para></listitem>
+ <listitem><para>Comment format</para></listitem>
+ </itemizedlist>
<figure>
<title>Example service description file</title>