<article id="index">
<articleinfo>
<title>D-BUS Specification</title>
- <releaseinfo>Version 0.10</releaseinfo>
- <date>28 January 2005</date>
+ <releaseinfo>Version 0.11</releaseinfo>
+ <date>6 February 2005</date>
<authorgroup>
<author>
<firstname>Havoc</firstname>
spec and the reference implementation probably will not
incorporate features that interfere with the core use cases.
</para>
+
+ <para>
+ 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.
+ </para>
</sect1>
<literal>INT32</literal> 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 three <firstterm>container</firstterm>
- types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, and <literal>VARIANT</literal>.
+ In addition to basic types, there are four <firstterm>container</firstterm>
+ types: <literal>STRUCT</literal>, <literal>ARRAY</literal>, <literal>VARIANT</literal>,
+ and <literal>DICT_ENTRY</literal>.
</para>
<para>
<para>
A <literal>DICT_ENTRY</literal> 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; and it
- has exactly two single complete types inside the curly
- braces. Implementations must not accept dict entries outside of arrays,
- and must not accept dict entries with zero, one, or more than two
- fields. A dict entry is always a key-value pair.
+ 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.
</para>
<para>
</row>
<row>
<entry>2nd <literal>BYTE</literal></entry>
- <entry><firstterm>Message type</firstterm>. Unknown types MUST be ignored.
+ <entry><firstterm>Message type</firstterm>. Unknown types must be ignored.
Currently-defined types are described below.
</entry>
</row>
<row>
<entry>3rd <literal>BYTE</literal></entry>
<entry>Bitwise OR of flags. Unknown flags
- MUST be ignored. Currently-defined flags are described below.
+ must be ignored. Currently-defined flags are described below.
</entry>
</row>
<row>
<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.
<row>
<entry><literal>INVALID</literal></entry>
<entry>0</entry>
- <entry>This is an invalid type, if seen in a message
- the connection should be dropped immediately.</entry>
+ <entry>This is an invalid type.</entry>
</row>
<row>
<entry><literal>METHOD_CALL</literal></entry>
<entry>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.</entry>
+ to return the reply despite this flag and the only harm
+ from doing so is extra network traffic.
+ </entry>
</row>
<row>
<entry><literal>NO_AUTO_START</literal></entry>
<entry>0x2</entry>
- <entry>This message should not automatically launch an owner
- for the destination name.
+ <entry>The bus must not launch an owner
+ for the destination name in response to this message.
</entry>
</row>
</tbody>
<para>
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
+ 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 that should be ignored
+ 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.
</para>
<para>
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 <literal>INTERFACE</literal> field of type <literal>UINT32</literal> would be considered
- corrupt.
+ with the wrong type stored in the field value. So for example a
+ message with an <literal>INTERFACE</literal> field of type
+ <literal>UINT32</literal> would be considered corrupt.
</para>
<para>
<entry>6</entry>
<entry><literal>STRING</literal></entry>
<entry>optional</entry>
- <entry>The name of the connection this message should be routed to.
+ <entry>The name of the connection this message is intended for.
Only used in combination with the message bus, see
<xref linkend="message-bus"/>.</entry>
</row>
additional restrictions that apply to interface names
specifically:
<itemizedlist>
- <listitem><para>They are composed of 1 or more elements separated by
+ <listitem><para>Interface names are composed of 1 or more elements separated by
a period ('.') character. All elements must contain at least
one character.
</para>
</para>
</listitem>
- <listitem><para>They must contain at least one '.' (period)
+ <listitem><para>Interface names must contain at least one '.' (period)
character (and thus at least two elements).
</para></listitem>
- <listitem><para>They must not begin with a '.' (period) character.</para></listitem>
- <listitem><para>They must not exceed the maximum name length.</para></listitem>
+ <listitem><para>Interface names must not begin with a '.' (period) character.</para></listitem>
+ <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
</itemizedlist>
</para>
</sect3>
<sect3 id="message-protocol-names-bus">
<title>Bus names</title>
<para>
- Bus names have the same restrictions as interface names, with a
- special exception for unique connection names. A unique name's first
- element must start with a colon (':') character. After the colon, any
- characters in "[A-Z][a-z][0-9]_" may appear. Elements after
- the first must follow the usual rules, except that they may start with
- a digit. Bus names not starting with a colon have none of these
- exceptions and follow the same rules as interface names.
+ 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 <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.
+ </para>
+ </listitem>
+ <listitem><para>Bus names are composed of 1 or more elements separated by
+ a period ('.') character. All elements must contain at least
+ one character.
+ </para>
+ </listitem>
+ <listitem><para>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.
+ </para>
+ </listitem>
+
+ <listitem><para>Bus names must contain at least one '.' (period)
+ character (and thus at least two elements).
+ </para></listitem>
+
+ <listitem><para>Bus names must not begin with a '.' (period) character.</para></listitem>
+ <listitem><para>Bus names must not exceed the maximum name length.</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Note that the hyphen ('-') character is allowed in bus names but
+ not in interface names.
</para>
</sect3>
<sect3 id="message-protocol-names-member">
messages map naturally to methods on objects in a typical program.
</para>
<para>
- A method call message is expected to have a <literal>MEMBER</literal> header field
+ A method call message is required to have a <literal>MEMBER</literal> header field
indicating the name of the method. Optionally, the message has an
<literal>INTERFACE</literal> field giving the interface the method is a part of. In the
absence of an <literal>INTERFACE</literal> field, if two interfaces on the same object have
to receive the message.
</para>
<para>
- When an application handles a method call message, it is expected to
+ When an application handles a method call message, it is required to
return a reply. The reply is identified by a <literal>REPLY_SERIAL</literal> header field
indicating the serial number of the <literal>METHOD_CALL</literal> being replied to. The
reply can have one of two types; either <literal>METHOD_RETURN</literal> or <literal>ERROR</literal>.
</para>
<para>
Even if a method call has no return values, a <literal>METHOD_RETURN</literal>
- reply is expected, so the caller will know the method
+ reply is required, so the caller will know the method
was successfully processed.
</para>
<para>
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
+ 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.
+ </para>
+ <para>
This specification doesn't require anything of native API bindings;
the preceding is only a suggested convention for consistency
among bindings.
</para>
</sect4>
-
</sect3>
<sect3 id="message-protocol-types-signal">
</sect3>
</sect2>
+ <sect2 id="message-protocol-handling-invalid">
+ <title>Invalid Protocol and Spec Extensions</title>
+
+ <para>
+ 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
+ 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>
+ 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).
+ </para>
+
+ <para>
+ 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.
+ <itemizedlist>
+ <listitem>
+ <para>
+ In the authentication protocol (see <xref linkend="auth-protocol"/>) 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The authentication protocol supports pluggable auth mechanisms.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The address format (see <xref linkend="addresses"/>) supports new
+ kinds of transport.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Messages with an unknown type (something other than
+ <literal>METHOD_CALL</literal>, <literal>METHOD_RETURN</literal>,
+ <literal>ERROR</literal>, <literal>SIGNAL</literal>) 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Header fields with an unknown or unexpected field code must be ignored,
+ though again they must still be well-formed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ New standard interfaces (with new methods and signals) can of course be added.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
</sect1>
<sect1 id="auth-protocol">
<para>
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
+ 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.
<itemizedlist>
<listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
- <listitem><para>OK</para></listitem>
+ <listitem><para>OK <GUID in hex></para></listitem>
<listitem><para>DATA <data in hex encoding></para></listitem>
<listitem><para>ERROR</para></listitem>
</itemizedlist>
</para>
+ <para>
+ 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".
+ </para>
</sect2>
<sect2 id="auth-nul-byte">
<title>Special credentials-passing nul byte</title>
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
+ 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
<title>AUTH command</title>
<para>
If an AUTH command has no arguments, it is a request to list
- available mechanisms. The server SHOULD respond with a REJECTED
- command listing the mechanisms it understands.
+ available mechanisms. The server must respond with a REJECTED
+ command listing the mechanisms it understands, or with an error.
</para>
<para>
If an AUTH command specifies a mechanism, and the server supports
- said mechanism, the server SHOULD begin exchanging SASL
+ said mechanism, the server should begin exchanging SASL
challenge-response data with the client using DATA commands.
</para>
<para>
If the server does not support the mechanism given in the AUTH
- command, it SHOULD send a REJECTED command listing the mechanisms
- it does support.
+ command, it must send either a REJECTED command listing the mechanisms
+ it does support, or an error.
</para>
<para>
- 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, the
- server should reject authentication by sending REJECTED.
+ 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.
</para>
<para>
If authentication succeeds after exchanging DATA commands,
- an OK command should be sent to the client.
+ an OK command must be sent to the client.
</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
+ command must be the first octet of the authenticated/encrypted
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
+ command from the client must be the first octet of the
authenticated/encrypted stream of D-BUS messages.
</para>
</sect2>
<title>CANCEL Command</title>
<para>
At any time up to sending the BEGIN command, the client may send a
- CANCEL command. On receiving the CANCEL command, the server MUST
+ CANCEL command. On receiving the CANCEL command, the server must
send a REJECTED command and abort the current authentication
exchange.
</para>
</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
+ command from the client must be the first octet of the
authenticated/encrypted stream of D-BUS messages.
</para>
</sect2>
</para><para>
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
+ 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.
</para>
</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
+ command must be the first octet of the authenticated/encrypted
stream of D-BUS messages.
</para>
<para>
- The client MUST respond to the OK command by sending a BEGIN
+ 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
+ The server must not accept additional commands using this protocol
after the OK command has been sent.
</para>
+ <para>
+ The OK command has one argument, which is the GUID of the server.
+ See <xref linkend="addresses"/> for more on server GUIDs.
+ </para>
</sect2>
<sect2 id="auth-command-error">
<title>ERROR Command</title>
</para>
<para>
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
+ 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.
</para>
+ <para>
+ 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.
+ </para>
</sect2>
<sect2 id="auth-examples">
<title>Authentication examples</title>
(MAGIC_COOKIE is a made up mechanism)
C: AUTH MAGIC_COOKIE 3138363935333137393635383634
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
C: FOOBAR
S: ERROR
C: AUTH MAGIC_COOKIE 3736343435313230333039
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
- S: OK
+ S: OK 1234deadbeef
C: BEGIN
</programlisting>
</figure>
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_global" that's used by servers that do not specify
+ "org_freedesktop_general" that's used by servers that do not specify
otherwise.
</para>
<para>
</listitem>
<listitem>
<para>
- The cookie itself, a hex-encoded random block of bytes.
+ 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.
</para>
</listitem>
</itemizedlist>
</para>
<para>
- Only server processes modify the cookie file.
+ Only server processes modify the cookie file.
They must do so with this procedure:
<itemizedlist>
<listitem>
<para>
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.
- [FIXME how do you escape colon, comma, and semicolon in the values of the key=value pairs?]
+ Each value is escaped.
</para>
<para>
For example:
Which is the address to a unix socket with the path /tmp/dbus-test.
</para>
<para>
+ Value escaping is similar to URI escaping but simpler.
+ <itemizedlist>
+ <listitem>
+ <para>
+ The set of optionally-escaped bytes is:
+ <literal>[0-9A-Za-z_-/.\]</literal>. To escape, each
+ <emphasis>byte</emphasis> (note, not character) which is not in the
+ set of optionally-escaped bytes must be replaced with an ASCII
+ percent (<literal>%</literal>) 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To unescape, append each byte in the value; if a byte is an ASCII
+ percent (<literal>%</literal>) character then append the following
+ hex value instead. It is an error if a <literal>%</literal> byte
+ does not have two hex digits following. It is an error if a
+ non-optionally-escaped byte is seen unescaped.
+ </para>
+ </listitem>
+ </itemizedlist>
+ The set of optionally-escaped bytes is intended to preserve address
+ readability and convenience.
+ </para>
+
+ <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.
+ </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.
+ </para>
+
+ <para>
[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
the next one specified, and so forth. For example
<programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
</para>
+
+ </sect1>
+
+ <sect1 id="transports">
+ <title>Transports</title>
<para>
[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
tunnels over X11 protocol.
</para>
+
+ <sect2 id="transports-unix-domain-sockets">
+ <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
+ 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
+ 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.
+ </para>
+ </sect2>
</sect1>
- <sect1 id="standard-messages">
- <title>Standard One-to-One Messages</title>
+ <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="standard-interfaces">
+ <title>Standard Interfaces</title>
<para>
See <xref linkend="message-protocol-types-notation"/> for details on
- the notation used in this section.
+ the notation used in this section. There are some standard interfaces
+ that may be useful across various D-BUS applications.
</para>
- <sect2 id="standard-messages-ping">
- <title><literal>org.freedesktop.Peer.Ping</literal></title>
- <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:
<programlisting>
- org.freedesktop.Peer.Ping ()
+ org.freedesktop.DBus.Peer.Ping ()
</programlisting>
</para>
<para>
- On receipt of the <literal>METHOD_CALL</literal>
- message <literal>org.freedesktop.Peer.Ping</literal>, an application
- should do nothing other than reply with a <literal>METHOD_RETURN</literal> as usual.
+ On receipt of the <literal>METHOD_CALL</literal> message
+ <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.)
</para>
</sect2>
+ <sect2 id="standard-interfaces-introspectable">
+ <title><literal>org.freedesktop.DBus.Introspectable</literal></title>
+ <para>
+ This interface has one method:
+ <programlisting>
+ org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
+ </programlisting>
+ </para>
+ <para>
+ Objects instances may implement
+ <literal>Introspect</literal> 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.
+ </para>
+ <para>
+ <xref linkend="introspection-format"/> describes the format of this XML string.
+ </para>
+ </sect2>
+ <sect2 id="standard-interfaces-properties">
+ <title><literal>org.freedesktop.DBus.Properties</literal></title>
+ <para>
+ Many native APIs will have a concept of object <firstterm>properties</firstterm>
+ or <firstterm>attributes</firstterm>. These can be exposed via the
+ <literal>org.freedesktop.DBus.Properties</literal> interface.
+ </para>
+ <para>
+ <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);
+ </programlisting>
+ </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"/>.
+ </para>
+ <para>
+ 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).
+ </para>
+ </sect2>
</sect1>
+ <sect1 id="introspection-format">
+ <title>Introspection Data Format</title>
+ <para>
+ As described in <xref linkend="standard-interfaces-introspectable"/>,
+ 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.
+ </para>
+ <para>
+ Here is an example of introspection data:
+ <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>
+ </programlisting>
+ </para>
+ <para>
+ A more formal DTD and spec needs writing, but here are some quick notes.
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The possible directions are "in" and "out",
+ unlike CORBA there is no "inout"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The possible property access flags are
+ "readwrite", "read", and "write"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multiple interfaces can of course be listed for
+ one <node>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The "name" attribute on arguments is optional.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ 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:
+ </para>
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Values (separated by ,)</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>org.freedesktop.DBus.Deprecated</entry>
+ <entry>true,false</entry>
+ <entry>Whether or not the entity is deprecated; defaults to false</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.GLib.CSymbol</entry>
+ <entry>(string)</entry>
+ <entry>The C symbol; may be used for methods and interfaces</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.DBus.Method.NoReply</entry>
+ <entry>true,false</entry>
+ <entry>If set, don't expect a reply to the method call; defaults to false.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
<sect1 id="message-bus">
<title>Message Bus Specification</title>
<sect2 id="message-bus-overview">
<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.Peer.Ping</literal> message with no
+ <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.Peer.Ping</literal> example, if
+ 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
A connection can request additional names to be associated with it using
the <literal>org.freedesktop.DBus.RequestName</literal> message. <xref
linkend="message-protocol-names-bus"/> describes the format of a valid
- name.
+ name. These names can be released again using the
+ <literal>org.freedesktop.DBus.ReleaseName</literal> message.
</para>
<sect3 id="bus-messages-request-name">
<para>
This method call should be sent to
<literal>org.freedesktop.DBus</literal> and asks the message bus to
- assign the given name to the method caller. The flags argument
- contains any of the following values logically ORed together:
+ 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:
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If replacement is not possible, and the method caller is
+ currently not in the queue, the method caller is appended to the
+ queue.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ 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 <emphasis>do not</emphasis>
+ 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.
+ </para>
+ <para>
+ The flags argument contains any of the following values logically ORed
+ together:
<informaltable>
<tgroup cols="3">
</thead>
<tbody>
<row>
- <entry>DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT</entry>
+ <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
<entry>0x1</entry>
<entry>
- If the application succeeds in becoming the owner of the specified name,
- then ownership of the name can't be transferred until the application
- disconnects. If this flag is not set, then any application trying to become
- the owner of the name will succeed and the previous owner will be
- sent a <literal>org.freedesktop.DBus.NameOwnerChanged</literal> signal.
+
+ 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
+ <literal>org.freedesktop.DBus.NameLost</literal> 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.
+
</entry>
</row>
<row>
<entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
<entry>0x2</entry>
<entry>
+
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.
+ 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.
+
+ </entry>
+ </row>
+ <row>
+ <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
+ <entry>0x4</entry>
+ <entry>
+
+ 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.
+
</entry>
</row>
</tbody>
<entry>1</entry> <entry>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 did not
- specify DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
+ DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
</row>
<row>
<entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
<entry>2</entry>
- <entry>The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.</entry>
+
+ <entry>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.
+ </entry>
</row>
<row>
- <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry>
- <entry>3</entry>
- <entry>The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.</entry>
+ <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
+ <entry>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.</entry>
</row>
<row>
<entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
</tgroup>
</informaltable>
</para>
+ </sect3>
+
+ <sect3 id="bus-messages-release-name">
+ <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
+ <para>
+ As a method:
+ <programlisting>
+ UINT32 ReleaseName (in STRING name)
+ </programlisting>
+ Message arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>STRING</entry>
+ <entry>Name to release</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Reply arguments:
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0</entry>
+ <entry>UINT32</entry>
+ <entry>Return value</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ This method call should be sent to
+ <literal>org.freedesktop.DBus</literal> 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:
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Conventional Name</entry>
+ <entry>Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>DBUS_RELEASE_NAME_REPLY_RELEASED</entry>
+ <entry>1</entry> <entry>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.</entry>
+ </row>
+ <row>
+ <entry>DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</entry>
+ <entry>2</entry>
+ <entry>The given name does not exist on this bus.</entry>
+ </row>
+ <row>
+ <entry>DBUS_RELEASE_NAME_REPLY_NOT_OWNER</entry>
+ <entry>3</entry>
+ <entry>The caller was not the primary owner of this name,
+ and was also not waiting in the queue to own this name.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
</sect3>
</sect2>
<para>
The executable being launched may want to know whether the message bus
starting it is one of the well-known message buses (see <xref
- linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
+ linkend="message-bus-types"/>). To facilitate this, the bus must also set
the <literal>DBUS_STARTER_BUS_TYPE</literal> environment variable if it is one
of the well-known buses. The currently-defined values for this variable
are <literal>system</literal> for the systemwide message bus,
and if the client being activated fails to connect within that
timeout, an error should be sent back.]
</para>
+
+ <sect3 id="message-bus-starting-services-scope">
+ <title>Message Bus Service Scope</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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
+ <literal>_DBUS_DISPLAY_ID</literal> 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.
+ </para>
+ <para>
+ 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 <literal>_DBUS_DISPLAY_BUS_ADDRESS</literal>
+ property on screen 0 of the display, pointing to this bus.
+ </para>
+ </sect3>
</sect2>
<sect2 id="message-bus-types">
projects / platform / upstream / dbus.git / blobdiff