<article id="index">
<articleinfo>
<title>D-Bus Specification</title>
- <releaseinfo>Version 0.17</releaseinfo>
- <date>(not final)</date>
+ <releaseinfo>Version 0.19</releaseinfo>
+ <date>UNRELEASED</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
</address>
</affiliation>
</author>
+ <author>
+ <firstname>Simon</firstname>
+ <surname>McVittie</surname>
+ <affiliation>
+ <orgname>Collabora Ltd.</orgname>
+ <address>
+ <email>simon.mcvittie@collabora.co.uk</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>David</firstname>
+ <surname>Zeuthen</surname>
+ <affiliation>
+ <orgname>Red Hat, Inc.</orgname>
+ <address>
+ <email>davidz@redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
<revhistory>
<revision>
<revremark></revremark>
</revision>
<revision>
+ <revnumber>0.18</revnumber>
+ <date>29 July 2011</date>
+ <authorinitials>smcv</authorinitials>
+ <revremark>define eavesdropping, unicast, broadcast; add eavesdrop
+ match keyword; promote type system to a top-level section</revremark>
+ </revision>
+ <revision>
+ <revnumber>0.17</revnumber>
+ <date>1 June 2011</date>
+ <authorinitials>smcv/davidz</authorinitials>
+ <revremark>define ObjectManager; reserve extra pseudo-type-codes used
+ by GVariant</revremark>
+ </revision>
+ <revision>
<revnumber>0.16</revnumber>
<date>11 April 2011</date>
<authorinitials></authorinitials>
</sect1>
- <sect1 id="message-protocol">
- <title>Message Protocol</title>
-
- <para>
- A <firstterm>message</firstterm> consists of a
- <firstterm>header</firstterm> and a <firstterm>body</firstterm>. 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.
- </para>
-
- <para>
- The body of the message is made up of zero or more
- <firstterm>arguments</firstterm>, which are typed values, such as an
- integer or a byte array.
- </para>
+ <sect1 id="type-system">
+ <title>Type System</title>
<para>
- Both header and body use the same type system and format for
- serializing data. Each type of value has a wire format.
+ D-Bus has a type system, in which values of various types can be
+ serialized into a sequence of bytes referred to as the
+ <firstterm>wire format</firstterm> in a standard way.
Converting a value from some other representation into the wire
format is called <firstterm>marshaling</firstterm> and converting
it back from the wire format is <firstterm>unmarshaling</firstterm>.
</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>
</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>
</sect2>
+ </sect1>
+
+ <sect1 id="message-protocol">
+ <title>Message Protocol</title>
+
+ <para>
+ A <firstterm>message</firstterm> consists of a
+ <firstterm>header</firstterm> and a <firstterm>body</firstterm>. 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.
+ </para>
+
+ <para>
+ The body of the message is made up of zero or more
+ <firstterm>arguments</firstterm>, which are typed values, such as an
+ integer or a byte array.
+ </para>
+
+ <para>
+ Both header and body use the D-Bus <link linkend="type-system">type
+ system</link> and format for serializing data.
+ </para>
+
<sect2 id="message-protocol-messages">
<title>Message Format</title>
<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>
</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>
- <para>
- Object paths are normally all lowercase with underscores used rather than
- hyphens.
- </para>
- </sect1>
<sect1 id="uuids">
<title>UUIDs</title>
</programlisting>
</para>
<para>
+ It is conventional to give D-Bus properties names consisting of
+ capitalized words without punctuation ("CamelCase"), like
+ <link linkend="message-protocol-names-member">member names</link>.
+ For instance, the GObject property
+ <literal>connection-status</literal> or the Qt property
+ <literal>connectionStatus</literal> could be represented on D-Bus
+ as <literal>ConnectionStatus</literal>.
+ </para>
+ <para>
+ Strictly speaking, D-Bus property names are not required to follow
+ the same naming restrictions as member names, but D-Bus property
+ names that would not be valid member names (in particular,
+ GObject-style dash-separated property names) can cause interoperability
+ problems and should be avoided.
+ </para>
+ <para>
The available properties and whether they are writable can be determined
by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,
see <xref linkend="standard-interfaces-introspectable"/>.
annotation.
</para>
</sect2>
+
+ <sect2 id="standard-interfaces-objectmanager">
+ <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
+ <para>
+ An API can optionally make use of this interface for one or
+ more sub-trees of objects. The root of each sub-tree implements
+ this interface so other applications can get all objects,
+ interfaces and properties in a single method call. It is
+ appropriate to use this interface if users of the tree of
+ objects are expected to be interested in all interfaces of all
+ objects in the tree; a more granular API should be used if
+ users of the objects are expected to be interested in a small
+ subset of the objects, a small subset of their interfaces, or
+ both.
+ </para>
+ <para>
+ The method that applications can use to get all objects and
+ properties is <literal>GetManagedObjects</literal>:
+ </para>
+ <para>
+ <programlisting>
+ org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties);
+ </programlisting>
+ </para>
+ <para>
+ The return value of this method is a dict whose keys are
+ object paths. All returned object paths are children of the
+ object path implementing this interface, i.e. their object
+ paths start with the ObjectManager's object path plus '/'.
+ </para>
+ <para>
+ Each value is a dict whose keys are interfaces names. Each
+ value in this inner dict is the same dict that would be
+ returned by the <link
+ linkend="standard-interfaces-properties">org.freedesktop.DBus.Properties.GetAll()</link>
+ method for that combination of object path and interface. If
+ an interface has no properties, the empty dict is returned.
+ </para>
+ <para>
+ Changes are emitted using the following two signals:
+ </para>
+ <para>
+ <programlisting>
+ org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
+ DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties);
+ org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
+ ARRAY<STRING> interfaces);
+ </programlisting>
+ </para>
+ <para>
+ The <literal>InterfacesAdded</literal> signal is emitted when
+ either a new object is added or when an existing object gains
+ one or more interfaces. The
+ <literal>InterfacesRemoved</literal> signal is emitted
+ whenever an object is removed or it loses one or more
+ interfaces. The second parameter of the
+ <literal>InterfacesAdded</literal> signal contains a dict with
+ the interfaces and properties (if any) that have been added to
+ the given object path. Similarly, the second parameter of the
+ <literal>InterfacesRemoved</literal> signal contains an array
+ of the interfaces that were removed. Note that changes on
+ properties on existing interfaces are not reported using this
+ interface - an application should also monitor the existing <link
+ linkend="standard-interfaces-properties">PropertiesChanged</link>
+ signal on each object.
+ </para>
+ <para>
+ Applications SHOULD NOT export objects that are children of an
+ object (directly or otherwise) implementing this interface but
+ which are not returned in the reply from the
+ <literal>GetManagedObjects()</literal> method of this
+ interface on the given object.
+ </para>
+ <para>
+ The intent of the <literal>ObjectManager</literal> interface
+ is to make it easy to write a robust client
+ implementation. The trivial client implementation only needs
+ to make two method calls:
+ </para>
+ <para>
+ <programlisting>
+ org.freedesktop.DBus.AddMatch (bus_proxy,
+ "type='signal',name='org.example.App',path_namespace='/org/example/App'");
+ objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
+ </programlisting>
+ </para>
+ <para>
+ on the message bus and the remote application's
+ <literal>ObjectManager</literal>, respectively. Whenever a new
+ remote object is created (or an existing object gains a new
+ interface), the <literal>InterfacesAdded</literal> signal is
+ emitted, and since this signal contains all properties for the
+ interfaces, no calls to the
+ <literal>org.freedesktop.Properties</literal> interface on the
+ remote object are needed. Additionally, since the initial
+ <literal>AddMatch()</literal> rule already includes signal
+ messages from the newly created child object, no new
+ <literal>AddMatch()</literal> call is needed.
+ </para>
+
+ <para>
+ <emphasis>
+ The <literal>org.freedesktop.DBus.ObjectManager</literal>
+ interface was added in version 0.17 of the D-Bus
+ specification.
+ </emphasis>
+ </para>
+ </sect2>
</sect1>
<sect1 id="introspection-format">
</para>
<para>
- Messages may have a <literal>DESTINATION</literal> field (see <xref
- linkend="message-protocol-header-fields"/>). If the
- <literal>DESTINATION</literal> 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
- <literal>DESTINATION</literal> field set to the specified recipient,
- regardless of whether the recipient has set up a match rule matching
- the message.
- </para>
-
- <para>
- Signals normally do not specify a destination; they are sent to all
- applications with <firstterm>message matching rules</firstterm> that
- match the message.
- </para>
-
- <para>
- When the message bus receives a method call, if the
- <literal>DESTINATION</literal> 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
- <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
- <literal>DESTINATION</literal> will cause the message bus itself to
- reply to the ping immediately; the message bus will not make this
- message visible to other applications.
- </para>
-
- <para>
- Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
- the ping message were sent with a <literal>DESTINATION</literal> name of
- <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
- forwarded, and the Yoyodyne Corporation screensaver application would be
- expected to reply to the ping.
+ Applications may send <firstterm>unicast messages</firstterm> to
+ a specific recipient or to the message bus itself, or
+ <firstterm>broadcast messages</firstterm> to all interested recipients.
+ See <xref linkend="message-bus-routing"/> for details.
</para>
</sect2>
<sect2 id="message-bus-routing">
<title>Message Bus Message Routing</title>
+
+ <para>
+ Messages may have a <literal>DESTINATION</literal> field (see <xref
+ linkend="message-protocol-header-fields"/>), resulting in a
+ <firstterm>unicast message</firstterm>. If the
+ <literal>DESTINATION</literal> 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
+ <literal>DESTINATION</literal> field set to the specified recipient,
+ regardless of whether the recipient has set up a match rule matching
+ the message.
+ </para>
+
+ <para>
+ When the message bus receives a signal, if the
+ <literal>DESTINATION</literal> field is absent, it is considered to
+ be a <firstterm>broadcast signal</firstterm>, and is sent to all
+ applications with <firstterm>message matching rules</firstterm> that
+ match the message. Most signal messages are broadcasts.
+ </para>
+
+ <para>
+ Unicast signal messages (those with a <literal>DESTINATION</literal>
+ field) are not commonly used, but they are treated like any unicast
+ message: they are delivered to the specified receipient,
+ regardless of its match rules. One use for unicast signals is to
+ avoid a race condition in which a signal is emitted before the intended
+ recipient can call <xref linkend="bus-messages-add-match"/> to
+ receive that signal: if the signal is sent directly to that recipient
+ using a unicast message, it does not need to add a match rule at all,
+ and there is no race condition. Another use for unicast signals,
+ on message buses whose security policy prevents eavesdropping, is to
+ send sensitive information which should only be visible to one
+ recipient.
+ </para>
+
+ <para>
+ When the message bus receives a method call, if the
+ <literal>DESTINATION</literal> 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
+ <literal>org.freedesktop.DBus.Peer.Ping</literal> message with no
+ <literal>DESTINATION</literal> will cause the message bus itself to
+ reply to the ping immediately; the message bus will not make this
+ message visible to other applications.
+ </para>
+
+ <para>
+ Continuing the <literal>org.freedesktop.DBus.Peer.Ping</literal> example, if
+ the ping message were sent with a <literal>DESTINATION</literal> name of
+ <literal>com.yoyodyne.Screensaver</literal>, then the ping would be
+ forwarded, and the Yoyodyne Corporation screensaver application would be
+ expected to reply to the ping.
+ </para>
+
<para>
- FIXME
+ Message bus implementations may impose a security policy which
+ prevents certain messages from being sent or received.
+ When a message cannot be sent or received due to a security
+ policy, the message bus should send an error reply, unless the
+ original message had the <literal>NO_REPLY</literal> flag.
</para>
+
+ <sect3 id="message-bus-routing-eavesdropping">
+ <title>Eavesdropping</title>
+ <para>
+ Receiving a unicast message whose <literal>DESTINATION</literal>
+ indicates a different recipient is called
+ <firstterm>eavesdropping</firstterm>. On a message bus which acts as
+ a security boundary (like the standard system bus), the security
+ policy should usually prevent eavesdropping, since unicast messages
+ are normally kept private and may contain security-sensitive
+ information.
+ </para>
+
+ <para>
+ Eavesdropping is mainly useful for debugging tools, such as
+ the <literal>dbus-monitor</literal> tool in the reference
+ implementation of D-Bus. Tools which eavesdrop on the message bus
+ should be careful to avoid sending a reply or error in response to
+ messages intended for a different client.
+ </para>
+
+ <para>
+ Clients may attempt to eavesdrop by adding match rules
+ (see <xref linkend="message-bus-routing-match-rules"/>) containing
+ the <literal>eavesdrop='true'</literal> match. If the message bus'
+ security policy does not allow eavesdropping, the match rule can
+ still be added, but will not have any practical effect. For
+ compatibility with older message bus implementations, if adding such
+ a match rule results in an error reply, the client may fall back to
+ adding the same rule with the <literal>eavesdrop</literal> match
+ omitted.
+ </para>
+ </sect3>
+
<sect3 id="message-bus-routing-match-rules">
<title>Match Rules</title>
<para>
- 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.
+ An important part of the message bus routing protocol is match
+ rules. Match rules describe the messages that should be sent to a
+ client, based on the contents of the message. Broadcast signals
+ are only sent to clients which have a suitable match rule: this
+ avoids waking up client processes to deal with signals that are
+ not relevant to that client.
+ </para>
+ <para>
+ Messages that list a client as their <literal>DESTINATION</literal>
+ do not need to match the client's match rules, and are sent to that
+ client regardless. As a result, match rules are mainly used to
+ receive a subset of broadcast signals.
+ </para>
+ <para>
+ Match rules can also be used for eavesdropping
+ (see <xref linkend="message-bus-routing-eavesdropping"/>),
+ if the security policy of the message bus allows it.
</para>
<para>
Match rules are added using the AddMatch bus method
</para>
</entry>
</row>
+ <row>
+ <entry><literal>eavesdrop</literal></entry>
+ <entry><literal>'true'</literal>, <literal>'false'</literal></entry>
+ <entry>Since D-Bus 1.5.6, match rules do not
+ match messages which have a <literal>DESTINATION</literal>
+ field unless the match rule specifically
+ requests this
+ (see <xref linkend="message-bus-routing-eavesdropping"/>)
+ by specifying <literal>eavesdrop='true'</literal>
+ in the match rule. <literal>eavesdrop='false'</literal>
+ restores the default behaviour. Messages are
+ delivered to their <literal>DESTINATION</literal>
+ regardless of match rules, so this match does not
+ affect normal delivery of unicast messages.
+ If the message bus has a security policy which forbids
+ eavesdropping, this match may still be used without error,
+ but will not have any practical effect.
+ In older versions of D-Bus, this match was not allowed
+ in match rules, and all match rules behaved as if
+ <literal>eavesdrop='true'</literal> had been used.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<sect4>
<title></title>
<para>
- [FIXME specify location of .service files, probably using
- DESKTOP_DIRS etc. from basedir specification, though login session
- bus is not really desktop-specific]
+ On Unix systems, the session bus should search for .service files
+ in <literal>$XDG_DATA_DIRS/dbus-1/services</literal> as defined
+ by the
+ <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory Specification</ulink>.
+ Implementations may also search additional locations, which
+ should be searched with lower priority than anything in
+ XDG_DATA_HOME, XDG_DATA_DIRS or their respective defaults;
+ for example, the reference implementation also
+ looks in <literal>${datadir}/dbus-1/services</literal> as
+ set at compile time.
+ </para>
+ <para>
+ As described in the XDG Base Directory Specification, software
+ packages should install their session .service files to their
+ configured <literal>${datadir}/dbus-1/services</literal>,
+ where <literal>${datadir}</literal> is as defined by the GNU
+ coding standards. System administrators or users can arrange
+ for these service files to be read by setting XDG_DATA_DIRS or by
+ symlinking them into the default locations.
</para>
</sect4>
</sect3>
can be thought of as "well-known names" and are
used to find applications that offer specific functionality.
</para>
+
+ <para>
+ See <xref linkend="message-protocol-names-bus"/> for details of
+ the syntax and naming conventions for bus names.
+ </para>
</glossdef>
</glossentry>
<glossentry id="namespace"><glossterm>Namespace</glossterm>
<glossdef>
- <para>
- 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.
+ <para>
+ Used to prevent collisions when defining new interfaces, bus names
+ etc. The convention used is the same one Java uses for defining
+ classes: a reversed domain name.
+ See <xref linkend="message-protocol-names-bus"/>,
+ <xref linkend="message-protocol-names-interface"/>,
+ <xref linkend="message-protocol-names-error"/>,
+ <xref linkend="message-protocol-marshaling-object-path"/>.
</para>
</glossdef>
</glossentry>