mirror of
https://gitlab.freedesktop.org/dbus/dbus.git
synced 2026-01-25 17:20:27 +01:00
a70b042f0d
* dbus/dbus-server.c (dbus_server_listen): allow abstract sockets using unix:abstract=/foo, and when listening in a tmpdir i.e. unix:tmpdir=/tmp, always use abstract sockets if we can. * dbus/dbus-transport.c (_dbus_transport_open): support unix:abstract=/foo * dbus/dbus-server-unix.c (_dbus_server_new_for_domain_socket): support abstract sockets * dbus/dbus-transport-unix.c (_dbus_transport_new_for_domain_socket): support abstract sockets * dbus/dbus-sysdeps.c (_dbus_connect_unix_socket): add "abstract" toggle as an argument, implement abstract namespace support (_dbus_listen_unix_socket): ditto * configure.in: add --enable-abstract-sockets and implement a configure check for autodetection of the right value.
1999 lines
78 KiB
Text
1999 lines
78 KiB
Text
<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
|
|
]>
|
|
<article id="index">
|
|
<artheader>
|
|
<title>D-BUS Specification</title>
|
|
<releaseinfo>Version 0.7</releaseinfo>
|
|
<date>26 March 2003</date>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Havoc</firstname>
|
|
<surname>Pennington</surname>
|
|
<affiliation>
|
|
<orgname>Red Hat, Inc</orgname>
|
|
<address>
|
|
<email>hp@pobox.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>Anders</firstname>
|
|
<surname>Carlsson</surname>
|
|
<affiliation>
|
|
<orgname>CodeFactory AB</orgname>
|
|
<address>
|
|
<email>andersca@codefactory.se</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>Alexander</firstname>
|
|
<surname>Larsson</surname>
|
|
<affiliation>
|
|
<orgname>Red Hat, Inc</orgname>
|
|
<address>
|
|
<email>alexl@redhat.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
</artheader>
|
|
|
|
<sect1 id="introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
D-BUS is a system for low-latency, low-overhead, easy to use
|
|
interprocess communication (IPC). In more detail:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
D-BUS is <emphasis>low-latency</emphasis> because it is designed
|
|
to avoid round trips and allow asynchronous operation, much like
|
|
the X protocol.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
D-BUS is <emphasis>low-overhead</emphasis> because it uses a
|
|
binary protocol, and does not have to convert to and from a text
|
|
format such as XML. Because D-BUS is intended for potentially
|
|
high-resolution same-machine IPC, not primarily for Internet IPC,
|
|
this is an interesting optimization.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
D-BUS is <emphasis>easy to use</emphasis> because it works in terms
|
|
of <firstterm>messages</firstterm> rather than byte streams, and
|
|
does not require users to understand any complex concepts such as a
|
|
new type system or elaborate APIs. Libraries implementing D-BUS
|
|
may choose to abstract messages as "method calls" (see
|
|
<xref linkend="message-conventions-method">).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The base D-BUS protocol is a peer-to-peer protocol, specified in <xref
|
|
linkend="message-protocol">. That is, it is a system for one application
|
|
to talk to a single other application. However, the primary intended
|
|
application of D-BUS is the D-BUS <firstterm>message bus</firstterm>,
|
|
specified in <xref linkend="message-bus">. The message bus is a special
|
|
application that accepts connections from multiple other applications, and
|
|
forwards messages among them.
|
|
</para>
|
|
<para>
|
|
Things that D-BUS can be used for is for example notification of
|
|
system changes (notification of when a camera is plugged in to a
|
|
computer, or a new version of some software has been installed),
|
|
or desktop interoperablity, for example a file monitoring
|
|
service or a configuration service.
|
|
</para>
|
|
</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 inteprets 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>
|
|
|
|
<sect2 id="message-protocol-header-encoding">
|
|
<title>Header Encoding</title>
|
|
<para>
|
|
Following the mandatory fields, there are zero or more named fields (see
|
|
<xref linkend="message-protocol-header-fields">), and then nul bytes
|
|
padding the header such that its total length in bytes is a multiple of
|
|
8.
|
|
</para>
|
|
<para>
|
|
The header MUST begin with the following mandatory fields in the following
|
|
order:
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<thead>
|
|
<row>
|
|
<entry>Size</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>1 byte</entry>
|
|
<entry>Endianness flag; ASCII 'l' for little-endian
|
|
or ASCII 'B' for big-endian.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1 byte</entry>
|
|
<entry>Bitwise OR of flags. Unknown flags
|
|
MUST be ignored. Currently-defined flags are described below.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1 byte</entry>
|
|
<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
|
|
version for this version of the specification is 0.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1 byte</entry>
|
|
<entry>A nul byte, reserved for future use.
|
|
Any value for this byte MUST be accepted.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4 bytes</entry>
|
|
<entry>An unsigned 32-bit integer in the
|
|
message's byte order, indicating the total length in bytes of
|
|
the header including named fields and any alignment padding.
|
|
MUST be a multiple of 8.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4 bytes</entry>
|
|
<entry>An unsigned 32-bit integer in the
|
|
message's byte order, indicating the total length in bytes of
|
|
the message body.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>4 bytes</entry>
|
|
<entry>The message's serial number, an unsigned 32-bit integer in
|
|
the message's byte order. Applications MUST NOT reuse the same
|
|
serial number for different messages more often than 32-bit
|
|
unsigned integer wraparound. Zero is not a valid serial number.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Flags that can appear in the second byte of the header:
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<thead>
|
|
<row>
|
|
<entry>Hex value</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>0x1</entry>
|
|
<entry>This message is an error reply. If the first argument exists and is a string, it is an error message.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="message-protocol-header-fields">
|
|
<title>Header Fields</title>
|
|
<para>
|
|
In addition to the required header information mentioned
|
|
in <xref linkend="message-protocol-header-encoding">,
|
|
the header may contain zero or more named
|
|
header fields. These fields are named to allow
|
|
future versions of this protocol specification to
|
|
add new fields; implementations must ignore fields
|
|
they do not understand. Implementations must not
|
|
invent their own header fields; only changes to
|
|
this specification may introduce new header fields.
|
|
</para>
|
|
|
|
<para>
|
|
Header field names MUST consist of 4 non-nul bytes. The field name is
|
|
NOT nul terminated; it occupies exactly 4 bytes. Following the name,
|
|
the field MUST have a type code, and then a properly-aligned value
|
|
of that type.
|
|
See <xref linkend="message-protocol-arguments"> for a description
|
|
of how each type is encoded. If an implementation sees a header
|
|
field name that it does not understand, it MUST ignore
|
|
that field.
|
|
</para>
|
|
|
|
<para>
|
|
Here are the currently-defined named header fields:
|
|
<informaltable>
|
|
<tgroup cols=3>
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Type</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>name</entry>
|
|
<entry>STRING</entry>
|
|
<entry>The name of the message, such as org.freedesktop.Peer.Ping</entry>
|
|
</row>
|
|
<row>
|
|
<entry>rply</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>The serial number of the message this message is a reply
|
|
to. (The serial number is one of the mandatory header fields,
|
|
see <xref linkend="message-protocol-header-encoding">.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>srvc</entry>
|
|
<entry>STRING</entry>
|
|
<entry>The name of the service this message should be routed to.
|
|
Only used in combination with the message bus, see
|
|
<xref linkend="message-bus">.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>sndr</entry>
|
|
<entry>STRING</entry>
|
|
<entry>The name of the base service that sent this message.
|
|
The message bus fills in this field; the field is
|
|
only meaningful in combination with the message bus.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
|
|
</sect2>
|
|
<sect2 id="message-protocol-header-padding">
|
|
<title>Header Alignment Padding</title>
|
|
<para>
|
|
To allow implementations to keep the header and the body in a single
|
|
buffer while keeping data types aligned, the total length of the header
|
|
must be a multiple of 8 bytes. To achieve this, the header MUST be padded
|
|
with nul bytes to align its total length on an 8-byte boundary.
|
|
The minimum number of padding bytes MUST be used. Because all possible
|
|
named fields use at least 8 bytes, implementations can distinguish
|
|
padding (which must be less than 8 bytes) from additional named fields
|
|
(which must be at least 8 bytes).
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="message-protocol-arguments">
|
|
<title>Message Arguments</title>
|
|
<para>
|
|
The message body is made up of arguments. Each argument
|
|
is a type code, followed by the value of the argument
|
|
in a type-dependent format.
|
|
</para>
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols=3>
|
|
<thead>
|
|
<row>
|
|
<entry>Type name</entry>
|
|
<entry>Code</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>INVALID</entry>
|
|
<entry>0</entry>
|
|
<entry>Not a valid type code (error if it appears in a message)</entry>
|
|
</row><row>
|
|
<entry>NIL</entry>
|
|
<entry>1</entry>
|
|
<entry>Marks an "unset" or "nonexistent" argument</entry>
|
|
</row><row>
|
|
<entry>BYTE</entry>
|
|
<entry>2</entry>
|
|
<entry>8-bit unsigned integer</entry>
|
|
</row><row>
|
|
<entry>BOOLEAN</entry>
|
|
<entry>3</entry>
|
|
<entry>Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid.</entry>
|
|
</row><row>
|
|
<entry>INT32</entry>
|
|
<entry>4</entry>
|
|
<entry>32-bit signed integer</entry>
|
|
</row><row>
|
|
<entry>UINT32</entry>
|
|
<entry>5</entry>
|
|
<entry>32-bit unsigned integer</entry>
|
|
</row><row>
|
|
<entry>INT64</entry>
|
|
<entry>6</entry>
|
|
<entry>64-bit signed integer</entry>
|
|
</row><row>
|
|
<entry>UINT64</entry>
|
|
<entry>7</entry>
|
|
<entry>64-bit unsigned integer</entry>
|
|
</row><row>
|
|
<entry>DOUBLE</entry>
|
|
<entry>8</entry>
|
|
<entry>IEEE 754 double</entry>
|
|
</row><row>
|
|
<entry>STRING</entry>
|
|
<entry>9</entry>
|
|
<entry>UTF-8 string (<emphasis>must</emphasis> be valid UTF-8). Must be zero terminated. </entry>
|
|
</row><row>
|
|
<entry>NAMED</entry>
|
|
<entry>10</entry>
|
|
<entry>A named byte array, used for custom types</entry>
|
|
</row><row>
|
|
<entry>ARRAY</entry>
|
|
<entry>11</entry>
|
|
<entry>Array</entry>
|
|
</row><row>
|
|
<entry>DICT</entry>
|
|
<entry>12</entry>
|
|
<entry>A dictionary of key/value pairs</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
The types are encoded as follows:
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<thead>
|
|
<row>
|
|
<entry>Type name</entry>
|
|
<entry>Encoding</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>INVALID</entry>
|
|
<entry>Not applicable; cannot be encoded.</entry>
|
|
</row><row>
|
|
<entry>NIL</entry>
|
|
<entry>No data is encoded; the type code is followed immediately
|
|
by the type code of the next argument.</entry>
|
|
</row><row>
|
|
<entry>BYTE</entry>
|
|
<entry>A byte.</entry>
|
|
</row><row>
|
|
<entry>BOOLEAN</entry>
|
|
<entry>A byte, with valid values 0 and 1.</entry>
|
|
</row><row>
|
|
<entry>INT32</entry>
|
|
<entry>32-bit signed integer in the message's byte order, aligned to 4-byte boundary.</entry>
|
|
</row><row>
|
|
<entry>UINT32</entry>
|
|
<entry>32-bit unsigned integer in the message's byte order, aligned to 4-byte boundary.</entry>
|
|
</row><row>
|
|
<entry>INT64</entry>
|
|
<entry>64-bit signed integer in the message's byte order, aligned to 8-byte boundary.</entry>
|
|
</row><row>
|
|
<entry>UINT64</entry>
|
|
<entry>64-bit unsigned integer in the message's byte order, aligned to 8-byte boundary.</entry>
|
|
</row><row>
|
|
<entry>DOUBLE</entry>
|
|
<entry>64-bit IEEE 754 double in the message's byte order, aligned to 8-byte boundary.</entry>
|
|
</row><row>
|
|
<entry>STRING</entry>
|
|
<entry>UINT32 aligned to 4-byte boundary indicating the string's
|
|
length in bytes excluding its terminating nul, followed by
|
|
string data of the given length, followed by a terminating nul
|
|
byte.
|
|
</entry>
|
|
</row><row>
|
|
<entry>NAMED</entry>
|
|
<entry>A string (encoded as the STRING type above) giving the
|
|
name of the type followed by an UINT32 aligned to 4-byte boundary
|
|
indicating the data length in bytes, followed by the data.
|
|
</entry>
|
|
</row><row>
|
|
<entry>ARRAY</entry>
|
|
<entry>A sequence of bytes giving the element type of the array, terminated
|
|
by a type different from ARRAY (just one byte for one-dimensional arrays, but
|
|
larger for multi-dimensional arrays), followed by an UINT32 (aligned to 4 bytes)
|
|
giving the length of the array data in bytes. This is followed by each array entry
|
|
encoded the way it would normally be encoded, except arrays, which are encoded
|
|
without the type information, since that is already declared above. Arrays containing
|
|
NIL are not allowed.
|
|
</entry>
|
|
</row><row>
|
|
<entry>DICT</entry>
|
|
<entry>UINT32 giving the length of the dictionary data in bytes.
|
|
This is followed by a number of keyname/value pairs, where the
|
|
keyname is encoded as a STRING above, and the value is encoded
|
|
as a byte with typecode and how that type normally would be encoded
|
|
alone.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="message-protocol-names">
|
|
<title>Valid names</title>
|
|
<para>
|
|
Messages and services have names with type STRING, meaning that
|
|
they must be valid UTF-8. However, there are also some
|
|
additional restrictions that apply to message and service names
|
|
specifically:
|
|
<itemizedlist>
|
|
<listitem><para>They must contain at least one '.' (period) character</para></listitem>
|
|
<listitem><para>They must not begin with a '.' (period) character</para></listitem>
|
|
<listitem><para>They must not exceed 256 bytes in length</para></listitem>
|
|
<listitem><para>They must be at least 1 byte in length</para></listitem>
|
|
</itemizedlist>
|
|
As a special exception, base service names (those beginning with a colon (':') character)
|
|
need not contain a period.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="auth-protocol">
|
|
<title>Authentication Protocol</title>
|
|
<para>
|
|
Before the flow of messages begins, two applications must
|
|
authenticate. A simple plain-text protocol is used for
|
|
authentication; this protocol is a SASL profile, and maps fairly
|
|
directly from the SASL specification. The message encoding is
|
|
NOT used here, only plain text messages.
|
|
</para>
|
|
<para>
|
|
In examples, "C:" and "S:" indicate lines sent by the client and
|
|
server respectively.
|
|
</para>
|
|
<sect2 id="auth-protocol-overview">
|
|
<title>Protocol Overview</title>
|
|
<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
|
|
command, then the \r\n ending the line. The protocol is
|
|
case-sensitive. All bytes must be in the ASCII character set.
|
|
|
|
Commands from the client to the server are as follows:
|
|
|
|
<itemizedlist>
|
|
<listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
|
|
<listitem><para>CANCEL</para></listitem
|
|
<listitem><para>BEGIN</para></listitem>
|
|
<listitem><para>DATA <data in base 64 encoding></para></listitem>
|
|
<listitem><para>ERROR [human-readable error explanation]</para></listitem>
|
|
</itemizedlist>
|
|
|
|
From server to client are as follows:
|
|
|
|
<itemizedlist>
|
|
<listitem><para>REJECTED <space-separated list of mechanism names></para></listitem>
|
|
<listitem><para>OK</para></listitem>
|
|
<listitem><para>DATA <data in base 64 encoding></para></listitem>
|
|
<listitem><para>ERROR</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-nul-byte">
|
|
<title>Special credentials-passing nul byte</title>
|
|
<para>
|
|
Immediately after connecting to the server, the client must send a
|
|
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
|
|
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
|
|
received from the client is not a nul byte, the server may disconnect
|
|
that client.
|
|
</para>
|
|
<para>
|
|
A nul byte in any context other than the initial byte is an error;
|
|
the protocol is ASCII-only.
|
|
</para>
|
|
<para>
|
|
The credentials sent along with the nul byte may be used with the
|
|
SASL mechanism EXTERNAL.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-auth">
|
|
<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.
|
|
</para>
|
|
<para>
|
|
If an AUTH command specifies a mechanism, and the server supports
|
|
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.
|
|
</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.
|
|
</para>
|
|
<para>
|
|
If authentication succeeds after exchanging DATA commands,
|
|
an OK command should 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
|
|
stream of D-BUS messages.
|
|
</para>
|
|
<para>
|
|
The first octet received by the server after the \r\n of the BEGIN
|
|
command from the client MUST be the first octet of the
|
|
authenticated/encrypted stream of D-BUS messages.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-cancel">
|
|
<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
|
|
send a REJECTED command and abort the current authentication
|
|
exchange.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-data">
|
|
<title>DATA Command</title>
|
|
<para>
|
|
The DATA command may come from either client or server, and simply
|
|
contains a base64-encoded block of data to be interpreted
|
|
according to the SASL mechanism in use.
|
|
</para>
|
|
<para>
|
|
Some SASL mechanisms support sending an "empty string";
|
|
FIXME we need some way to do this.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-begin">
|
|
<title>BEGIN Command</title>
|
|
<para>
|
|
The BEGIN command acknowledges that the client has received an
|
|
OK command from the server, and that the stream of messages
|
|
is about to begin.
|
|
</para>
|
|
<para>
|
|
The first octet received by the server after the \r\n of the BEGIN
|
|
command from the client MUST be the first octet of the
|
|
authenticated/encrypted stream of D-BUS messages.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-rejected">
|
|
<title>REJECTED Command</title>
|
|
<para>
|
|
The REJECTED command indicates that the current authentication
|
|
exchange has failed, and further exchange of DATA is inappropriate.
|
|
The client would normally try another mechanism, or try providing
|
|
different responses to challenges.
|
|
</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
|
|
each time it sends a REJECTED message. Clients are free to
|
|
ignore all lists received after the first.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-ok">
|
|
<title>OK Command</title>
|
|
<para>
|
|
The OK command indicates that the client has been authenticated,
|
|
and that further communication will be a stream of D-BUS messages
|
|
(optionally encrypted, as negotiated) rather than this protocol.
|
|
</para>
|
|
<para>
|
|
The first octet received by the client after the \r\n of the OK
|
|
command MUST be the first octet of the authenticated/encrypted
|
|
stream of D-BUS messages.
|
|
</para>
|
|
<para>
|
|
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
|
|
after the OK command has been sent.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-command-error">
|
|
<title>ERROR Command</title>
|
|
<para>
|
|
The ERROR command indicates that either server or client did not
|
|
know a command, does not accept the given command in the current
|
|
context, or did not understand the arguments to the command. This
|
|
allows the protocol to be extended; a client or server can send a
|
|
command present or permitted only in new protocol versions, and if
|
|
an ERROR is received instead of an appropriate response, fall back
|
|
to using some other technique.
|
|
</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
|
|
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>
|
|
</sect2>
|
|
<sect2 id="auth-examples">
|
|
<title>Authentication examples</title>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Example of successful magic cookie authentication</title>
|
|
<programlisting>
|
|
(MAGIC_COOKIE is a made up mechanism)
|
|
|
|
C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
<figure>
|
|
<title>Example of finding out mechanisms then picking one</title>
|
|
<programlisting>
|
|
C: AUTH
|
|
S: REJECTED KERBEROS_V4 SKEY
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
<figure>
|
|
<title>Example of client sends unknown command then falls back to regular auth</title>
|
|
<programlisting>
|
|
C: FOOBAR
|
|
S: ERROR
|
|
C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
<figure>
|
|
<title>Example of server doesn't support initial auth mechanism</title>
|
|
<programlisting>
|
|
C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
|
|
S: REJECTED KERBEROS_V4 SKEY
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
<figure>
|
|
<title>Example of wrong password or the like followed by successful retry</title>
|
|
<programlisting>
|
|
C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
|
|
S: REJECTED KERBEROS_V4 SKEY
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
|
|
S: REJECTED
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
<figure>
|
|
<title>Example of skey cancelled and restarted</title>
|
|
<programlisting>
|
|
C: AUTH MAGIC_COOKIE BsAY3g4gBNo=
|
|
S: REJECTED KERBEROS_V4 SKEY
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: CANCEL
|
|
S: REJECTED
|
|
C: AUTH SKEY bW9yZ2Fu
|
|
S: DATA OTUgUWE1ODMwOA==
|
|
C: DATA Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
|
|
S: OK
|
|
C: BEGIN
|
|
</programlisting>
|
|
</figure>
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="auth-mechanisms">
|
|
<title>Authentication mechanisms</title>
|
|
<para>
|
|
This section describes some new authentication mechanisms.
|
|
D-BUS also allows any standard SASL mechanism of course.
|
|
</para>
|
|
<sect3 id="auth-mechanisms-sha">
|
|
<title>DBUS_COOKIE_SHA1</title>
|
|
<para>
|
|
The DBUS_COOKIE_SHA1 mechanism is designed to establish that a client
|
|
has the ability to read a private file owned by the user being
|
|
authenticated. If the client can prove that it has access to a secret
|
|
cookie stored in this file, then the client is authenticated.
|
|
Thus the security of DBUS_COOKIE_SHA1 depends on a secure home
|
|
directory.
|
|
</para>
|
|
<para>
|
|
Authentication proceeds as follows:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The client sends the username it would like to authenticate
|
|
as.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The server sends the name of its "cookie context" (see below); a
|
|
space character; the integer ID of the secret cookie the client
|
|
must demonstrate knowledge of; a space character; then a
|
|
hex-encoded randomly-generated challenge string.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The client locates the cookie, and generates its own hex-encoded
|
|
randomly-generated challenge string. The client then
|
|
concatentates the server's hex-encoded challenge, a ":"
|
|
character, its own hex-encoded challenge, another ":" character,
|
|
and the hex-encoded cookie. It computes the SHA-1 hash of this
|
|
composite string. It sends back to the server the client's
|
|
hex-encoded challenge string, a space character, and the SHA-1
|
|
hash.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The server generates the same concatenated string used by the
|
|
client and computes its SHA-1 hash. It compares the hash with
|
|
the hash received from the client; if the two hashes match, the
|
|
client is authenticated.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Each server has a "cookie context," which is a name that identifies a
|
|
set of cookies that apply to that server. A sample context might be
|
|
"org_freedesktop_session_bus". Context names must be valid ASCII,
|
|
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
|
|
otherwise.
|
|
</para>
|
|
<para>
|
|
Cookies are stored in a user's home directory, in the directory
|
|
<filename>~/.dbus-keyrings/</filename>. This directory must
|
|
not be readable or writable by other users. If it is,
|
|
clients and servers must ignore it. The directory
|
|
contains cookie files named after the cookie context.
|
|
</para>
|
|
<para>
|
|
A cookie file contains one cookie per line. Each line
|
|
has three space-separated fields:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The cookie ID number, which must be a non-negative integer and
|
|
may not be used twice in the same file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The cookie's creation time, in UNIX seconds-since-the-epoch
|
|
format.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The cookie itself, a hex-encoded random block of bytes.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Only server processes modify the cookie file.
|
|
They must do so with this procedure:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Create a lockfile name by appending ".lock" to the name of the
|
|
cookie file. The server should attempt to create this file
|
|
using <literal>O_CREAT | O_EXCL</literal>. If file creation
|
|
fails, the lock fails. Servers should retry for a reasonable
|
|
period of time, then they may choose to delete an existing lock
|
|
to keep users from having to manually delete a stale
|
|
lock. <footnote><para>Lockfiles are used instead of real file
|
|
locking <literal>fcntl()</literal> because real locking
|
|
implementations are still flaky on network
|
|
filesystems.</para></footnote>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Once the lockfile has been created, the server loads the cookie
|
|
file. It should then delete any cookies that are old (the
|
|
timeout can be fairly short), or more than a reasonable
|
|
time in the future (so that cookies never accidentally
|
|
become permanent, if the clock was set far into the future
|
|
at some point). If no recent keys remain, the
|
|
server may generate a new key.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The pruned and possibly added-to cookie file
|
|
must be resaved atomically (using a temporary
|
|
file which is rename()'d).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The lock must be dropped by deleting the lockfile.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Clients need not lock the file in order to load it,
|
|
because servers are required to save the file atomically.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="addresses">
|
|
<title>Server Addresses</title>
|
|
<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?]
|
|
</para>
|
|
<para>
|
|
For example:
|
|
<programlisting>unix:path=/tmp/dbus-test</programlisting>
|
|
Which is the address to a unix socket with the path /tmp/dbus-test.
|
|
</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
|
|
separated by a semi-colon. The library will then try to connect
|
|
to the first address and if that fails, it'll try to connect to
|
|
the next one specified, and so forth. For example
|
|
<programlisting>unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2</programlisting>
|
|
</para>
|
|
<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>
|
|
</sect1>
|
|
|
|
<sect1 id="message-conventions">
|
|
<title>Message Conventions</title>
|
|
<para>
|
|
This section documents conventions that are not essential to D-BUS
|
|
functionality, but should generally be followed in order to simplify
|
|
programmer's lives.
|
|
</para>
|
|
<sect2 id="message-conventions-naming">
|
|
<title>Message Naming</title>
|
|
<para>
|
|
Messages are normally named in the form
|
|
"org.freedesktop.Peer.Ping", which has three
|
|
distinct components:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Namespace e.g. <literal>org.freedesktop</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Message names have a Java-style namespace: a reversed domain
|
|
name. The components of the domain are normally lowercase.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Package or object e.g. <literal>Peer</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The next part of the message name can be thought of as the name
|
|
of a singleton object, or as the name of a package of related
|
|
messages. More than one dot-separated component might be used
|
|
here. (Note that D-BUS does not define any idea of object
|
|
instances or object references.) The package or object name is
|
|
capitalized LikeThis.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Method or operation e.g. <literal>Ping</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The final part of the message name is the most specific, and
|
|
should be a verb indicating an operation to be performed on the
|
|
object. The method or operation name is capitalized LikeThis.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
A reply to a message conventionally has the same name as the message
|
|
being replied to. When following method call conventions (see <xref
|
|
linkend="message-conventions-method">), this convention is mandatory,
|
|
because a message with multiple possible replies can't be mapped
|
|
to method call semantics without special-case code.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="message-conventions-method">
|
|
<title>Method Call Mapping</title>
|
|
<para>
|
|
Some implementations of D-BUS may present an API that translates object
|
|
method calls into D-BUS messages. This document does not specify in
|
|
detail how such an API should look or work. However, it does specify how
|
|
message-based protocols should be designed to be friendly to such an
|
|
API.
|
|
</para>
|
|
<para>
|
|
Remember that D-BUS does not have object references or object instances.
|
|
So when one application sends the message
|
|
<literal>org.freedesktop.Peer.Ping</literal>, it sends it to another
|
|
application, not to any kind of sub-portion of that application.
|
|
However, a convenience API used within the recipient application may
|
|
route all messages that start with
|
|
<literal>org.freedesktop.Peer</literal> to a particular object instance,
|
|
and may invoke the <literal>Ping()</literal> method on said instance in
|
|
order to handle the message. This is a convenience API based on
|
|
method calls.
|
|
</para>
|
|
<para>
|
|
A "method call" consists of a message and, optionally, a reply to that
|
|
message. The name of the "method" is the last component of the message,
|
|
for example, <literal>org.freedesktop.Peer.Ping</literal> would map to
|
|
the method <literal>Ping()</literal> on some object.
|
|
</para>
|
|
<para>
|
|
Arguments to a method may be considered "in" (processed by the
|
|
recipient of the message), or "out" (returned to the sender of the
|
|
message in the reply). "inout" arguments are both sent and received,
|
|
i.e. the caller passes in a value which is modified. An "inout" argument
|
|
is equivalent to an "in" argument, followed by an "out" argument.
|
|
</para>
|
|
<para>
|
|
Given a method with zero or one return values, followed by zero or more
|
|
arguments, where each argument may be "in", "out", or "inout", the
|
|
caller constructs a message by appending each "in" or "inout" argument,
|
|
in order. "out" arguments are not represented in the caller's message.
|
|
</para>
|
|
<para>
|
|
The recipient constructs a reply by appending first the return value
|
|
if any, then each "out" or "inout" argument, in order.
|
|
"in" arguments are not represented in the reply message.
|
|
</para>
|
|
<para>
|
|
The standard reply message MUST have the same name as the message being
|
|
replied to, and MUST set the "rply" header field to the serial
|
|
number of the message being replied to.
|
|
</para>
|
|
<para>
|
|
If an error occurs, an error reply may be sent in place of the standard
|
|
reply. Error replies can be identified by a special header flag, see
|
|
<xref linkend="message-protocol-header-encoding">. Error replies have a
|
|
name which reflects the type of error that occurred. Error replies would
|
|
generally be mapped to exceptions in a programming language. If an
|
|
error reply has a first argument, and that argument has type STRING,
|
|
then the argument must be an error message.
|
|
</para>
|
|
<para>
|
|
[FIXME discuss mapping of broadcast messages + matching rules
|
|
to signals and slots]
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="standard-messages">
|
|
<title>Standard Peer-to-Peer Messages</title>
|
|
<para>
|
|
In the following message definitions, "method call notation" is presented
|
|
in addition to simply listing the message names and arguments. The special
|
|
type name ANY means any type other than NIL, and the special type name
|
|
ANY_OR_NIL means any valid type.
|
|
[FIXME the messages here are just made up to illustrate the
|
|
format for defining them]
|
|
</para>
|
|
<sect2 id="standard-messages-ping">
|
|
<title><literal>org.freedesktop.Peer.Ping</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
void Ping ()
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
On receipt of the message <literal>org.freedesktop.Peer.Ping</literal>,
|
|
an application should reply with
|
|
<literal>org.freedesktop.Peer.Ping</literal>. Neither the
|
|
message nor its reply have any arguments.
|
|
[FIXME the messages here are just made up to illustrate the
|
|
format for defining them]
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="standard-messages-get-props">
|
|
<title><literal>org.freedesktop.Props.Get</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
ANY_OR_NIL Get (in STRING property_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 of the property to get</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>ANY_OR_NIL</entry>
|
|
<entry>The value of the property. The type depends on the property.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
|
|
[FIXME the messages here are just made up to illustrate the
|
|
format for defining them]
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="message-bus">
|
|
<title>Message Bus Specification</title>
|
|
<sect2 id="message-bus-overview">
|
|
<title>Message Bus Overview</title>
|
|
<para>
|
|
The message bus accepts connections from one or more applications.
|
|
Once connected, applications can send and receive messages from
|
|
the message bus, as in the peer-to-peer case.
|
|
</para>
|
|
<para>
|
|
The message bus keeps track of a set of
|
|
<firstterm>services</firstterm>. A service is simply a name, such as
|
|
<literal>com.yoyodyne.Screensaver</literal>, which can be
|
|
<firstterm>owned</firstterm> by one or more of the connected
|
|
applications. The message bus itself always owns the special service
|
|
<literal>org.freedesktop.DBus</literal>.
|
|
</para>
|
|
<para>
|
|
Services may have <firstterm>secondary owners</firstterm>. Secondary owners
|
|
of a service are kept in a queue; if the primary owner of a service
|
|
disconnects, or releases the service, the next secondary owner becomes
|
|
the new owner of the service.
|
|
</para>
|
|
<para>
|
|
Messages may have a <literal>srvc</literal> field (see <xref
|
|
linkend="message-protocol-header-fields">). When the message bus
|
|
receives a message, if the <literal>srvc</literal> field is absent, the
|
|
message is taken to be a standard peer-to-peer message and interpreted
|
|
by the message bus itself. For example, sending
|
|
an <literal>org.freedesktop.Peer.Ping</literal> message with no
|
|
<literal>srvc</literal> will cause the message bus itself to reply
|
|
to the ping immediately; the message bus would never make
|
|
this message visible to other applications.
|
|
</para>
|
|
<para>
|
|
If the <literal>srvc</literal> field is present, then it indicates a
|
|
request for the message bus to route the message. In the usual case,
|
|
messages are routed to the owner of the named service.
|
|
Messages may also be <firstterm>broadcast</firstterm>
|
|
by sending them to the special service
|
|
<literal>org.freedesktop.DBus.Broadcast</literal>. Broadcast messages are
|
|
sent to all applications with <firstterm>message matching
|
|
rules</firstterm> that match the message.
|
|
</para>
|
|
<para>
|
|
Continuing the <literal>org.freedesktop.Peer.Ping</literal> example, if
|
|
the ping message were sent with a <literal>srvc</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. If
|
|
<literal>org.freedesktop.Peer.Ping</literal> were sent to
|
|
<literal>org.freedesktop.DBus.Broadcast</literal>, then multiple applications
|
|
might receive the ping, and all would normally reply to it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="message-bus-services">
|
|
<title>Message Bus Services</title>
|
|
<para>
|
|
A service is a name that identifies a certain application. Each
|
|
application connected to the message bus has at least one service name
|
|
assigned at connection time and returned in response to the
|
|
<literal>org.freedesktop.DBus.Hello</literal> message.
|
|
This automatically-assigned service name is called
|
|
the application's <firstterm>base service</firstterm>.
|
|
Base service names are unique and MUST never be reused for two different
|
|
applications.
|
|
</para>
|
|
<para>
|
|
Ownership of the base service is a prerequisite for interaction with
|
|
the message bus. It logically follows that the base service is always
|
|
the first service that an application comes to own, and the last
|
|
service that it loses ownership of.
|
|
</para>
|
|
<para>
|
|
Base service names must begin with the character ':' (ASCII colon
|
|
character); service names that are not base service names must not begin
|
|
with this character. (The bus must reject any attempt by an application
|
|
to manually create a service name beginning with ':'.) This restriction
|
|
categorically prevents "spoofing"; messages sent to a base service name
|
|
will always go to a single application instance and that instance only.
|
|
</para>
|
|
<para>
|
|
An application can request additional service names to be associated
|
|
with it using the
|
|
<literal>org.freedesktop.DBus.AcquireService</literal>
|
|
message. [FIXME what service names are allowed; ASCII or unicode;
|
|
length limit; etc.]
|
|
</para>
|
|
<para>
|
|
[FIXME this needs more detail, and should move the service-related message
|
|
descriptions up into this section perhaps]
|
|
Service ownership handling can be specified in the flags part
|
|
of the <literal>org.freedesktop.DBus.AcquireService</literal>
|
|
message. If an application specifies the
|
|
DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT flag, then all applications
|
|
trying to acquire the service will be put in a queue. When the
|
|
primary owner disconnects from the bus or removes ownership
|
|
from the service, the next application in the queue will be the
|
|
primary owner. If the DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT
|
|
flag is not specified, then the primary owner will lose
|
|
ownership whenever another application requests ownership of the
|
|
service.
|
|
</para>
|
|
<para>
|
|
When a client disconnects from the bus, all the services that
|
|
the clients own are deleted, or in the case of a service that
|
|
prohibits replacement, ownership is transferred to the next
|
|
client in the queue, if any.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="message-bus-routing">
|
|
<title>Message Bus Message Routing</title>
|
|
<para>
|
|
When a message is received by the message bus, the message's
|
|
<literal>sndr</literal> header field MUST be set to the base service of
|
|
the application which sent the message. If the service already has
|
|
a <literal>sndr</literal> field, the pre-existing field is replaced.
|
|
This rule means that a replies are always sent to the base service name,
|
|
i.e. to the same application that sent the message being replied to.
|
|
</para>
|
|
<para>
|
|
[FIXME go into detail about broadcast, multicast, unicast, etc.]
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="message-bus-activation">
|
|
<title>Message Bus Service Activation</title>
|
|
<para>
|
|
<firstterm>Activation</firstterm> means to locate a service
|
|
owner for a service that is currently unowned. For now, it
|
|
means to launch an executable that will take ownership of
|
|
a particular service.
|
|
</para>
|
|
<para>
|
|
To find an executable corresponding to a particular service, the bus
|
|
daemon looks for <firstterm>service description files</firstterm>.
|
|
Service description files define a mapping from service names to
|
|
executables. Different kinds of message bus will look for these files
|
|
in different places, see <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 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
|
|
url="http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html">desktop
|
|
entries</ulink>. All service description files must be in
|
|
UTF-8 encoding. To ensure that there will be no name
|
|
collisions, service files must be namespaced using the same
|
|
mechanism as messages and service names.
|
|
|
|
<figure>
|
|
<title>Example service description file</title>
|
|
<programlisting>
|
|
# Sample service description file
|
|
[D-BUS Service]
|
|
Name=org.gnome.ConfigurationDatabase
|
|
Exec=/usr/libexec/gconfd-2
|
|
</programlisting>
|
|
</figure>
|
|
</para>
|
|
<para>
|
|
When an application requests a service to be activated, the
|
|
bus daemon tries to find it in the list of activation
|
|
entries. It then tries to spawn the executable associated with
|
|
it. If this fails, it will report an error. [FIXME what
|
|
happens if two .service files offer the same service; what
|
|
kind of error is reported, should we have a way for the client
|
|
to choose one?]
|
|
</para>
|
|
<para>
|
|
The executable launched will have the environment variable
|
|
<literal>DBUS_ACTIVATION_ADDRESS</literal> set to the address of the
|
|
message bus so it can connect and register the appropriate services.
|
|
</para>
|
|
<para>
|
|
The executable being launched may want to know whether the message bus
|
|
activating it is one of the well-known message buses (see <xref
|
|
linkend="message-bus-types">). To facilitate this, the bus MUST also set
|
|
the <literal>DBUS_ACTIVATION_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 <literal>session</literal> for the per-login-session message
|
|
bus. The activated executable must still connect to the address given
|
|
in <literal>DBUS_ACTIVATION_ADDRESS</literal>, but may assume that the
|
|
resulting connection is to the well-known bus.
|
|
</para>
|
|
<para>
|
|
[FIXME there should be a timeout somewhere, either specified
|
|
in the .service file, by the client, or just a global value
|
|
and if the client being activated fails to connect within that
|
|
timeout, an error should be sent back.]
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="message-bus-types">
|
|
<title>Well-known Message Bus Instances</title>
|
|
<para>
|
|
Two standard message bus instances are defined here, along with how
|
|
to locate them and where their service files live.
|
|
</para>
|
|
<sect3 id="message-bus-types-login">
|
|
<title>Login session message bus</title>
|
|
<para>
|
|
Each time a user logs in, a <firstterm>login session message
|
|
bus</firstterm> may be started. All applications in the user's login
|
|
session may interact with one another using this message bus.
|
|
</para>
|
|
<para>
|
|
The address of the login session message bus is given
|
|
in the <literal>DBUS_SESSION_BUS_ADDRESS</literal> environment
|
|
variable. If that variable is not set, applications may
|
|
also try to read the address from the X Window System root
|
|
window property <literal>_DBUS_SESSION_BUS_ADDRESS</literal>.
|
|
The root window property must have type <literal>STRING</literal>.
|
|
The environment variable should have precedence over the
|
|
root window property.
|
|
</para>
|
|
<para>
|
|
[FIXME specify location of .service files, probably using
|
|
DESKTOP_DIRS etc. from basedir specification, though login session
|
|
bus is not really desktop-specific]
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="message-bus-types-system">
|
|
<title>System message bus</title>
|
|
<para>
|
|
A computer may have a <firstterm>system message bus</firstterm>,
|
|
accessible to all applications on the system. This message bus may be
|
|
used to broadcast system events, such as adding new hardware devices,
|
|
changes in the printer queue, and so forth.
|
|
</para>
|
|
<para>
|
|
The address of the login session message bus is given
|
|
in the <literal>DBUS_SYSTEM_BUS_ADDRESS</literal> environment
|
|
variable. If that variable is not set, applications should try
|
|
to connect to the well-known address
|
|
<literal>unix:path=/var/run/dbus/system_bus_socket</literal>.
|
|
<footnote>
|
|
<para>
|
|
The D-BUS reference implementation actually honors the
|
|
<literal>$(localstatedir)</literal> configure option
|
|
for this address, on both client and server side.
|
|
</para>
|
|
</footnote>
|
|
</para>
|
|
<para>
|
|
[FIXME specify location of system bus .service files]
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="message-bus-messages">
|
|
<title>Message Bus Messages</title>
|
|
<para>
|
|
The special message bus service <literal>org.freedesktop.DBus</literal>
|
|
responds to a number of messages, allowing applications to
|
|
interact with the message bus.
|
|
</para>
|
|
|
|
<sect3 id="bus-messages-hello">
|
|
<title><literal>org.freedesktop.DBus.Hello</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
STRING Hello ()
|
|
</programlisting>
|
|
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>STRING</entry>
|
|
<entry>Name of the service assigned to the application</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Before an application is able to send messages to other
|
|
applications it must send the
|
|
<literal>org.freedesktop.DBus.Hello</literal> message to the
|
|
message bus service. If an application tries to send a
|
|
message to another application, or a message to the message
|
|
bus service that isn't the
|
|
<literal>org.freedesktop.DBus.Hello</literal> message, it
|
|
will be disconnected from the bus. If a client wishes to
|
|
disconnect from the bus, it just has to disconnect from the
|
|
transport used. No de-registration message is necessary.
|
|
</para>
|
|
<para>
|
|
The reply message contains the name of the application's base service.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="bus-messages-list-services">
|
|
<title><literal>org.freedesktop.DBus.ListServices</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
STRING_ARRAY ListServices ()
|
|
</programlisting>
|
|
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>STRING_ARRAY</entry>
|
|
<entry>Array of strings where each string is the name of a service</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Returns a list of all existing services registered with the message bus.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="bus-messages-service-exists">
|
|
<title><literal>org.freedesktop.DBus.ServiceExists</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
BOOLEAN ServiceExists (in STRING service_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 of the service</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>BOOLEAN</entry>
|
|
<entry>Return value, true if the service exists</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Checks if a service with a specified name exists.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-acquire-service">
|
|
<title><literal>org.freedesktop.DBus.AcquireService</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
UINT32 AcquireService (in STRING service_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 of the service</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags</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>
|
|
Tries to become owner of a specific service. The flags
|
|
specified can be the following values logically ORed together:
|
|
|
|
<informaltable>
|
|
<tgroup cols=3>
|
|
<thead>
|
|
<row>
|
|
<entry>Identifier</entry>
|
|
<entry>Value</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>DBUS_SERVICE_FLAGS_PROHIBIT_REPLACEMENT</entry>
|
|
<entry>0x1</entry>
|
|
<entry>
|
|
If the application succeeds in being the owner of the specified service,
|
|
then ownership of the service can't be transferred until the service
|
|
disconnects. If this flag is not set, then any application trying to become
|
|
the owner of the service will succeed and the previous owner will be
|
|
sent a <literal>org.freedesktop.DBus.ServiceLost</literal> message.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>DBUS_SERVICE_FLAGS_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 service if
|
|
there is no current owner.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
[FIXME if it's one of the following values, why are the values
|
|
done as flags instead of just 0, 1, 2, 3, 4]
|
|
The return value can be one of the following values:
|
|
|
|
<informaltable>
|
|
<tgroup cols=3>
|
|
<thead>
|
|
<row>
|
|
<entry>Identifier</entry>
|
|
<entry>Value</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>DBUS_SERVICE_REPLY_PRIMARY_OWNER</entry>
|
|
<entry>0x1</entry>
|
|
<entry>The application is now the primary owner of the service.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>DBUS_SERVICE_REPLY_IN_QUEUE</entry>
|
|
<entry>0x2</entry>
|
|
<entry>The service already has an owner which do not want to give up ownership and therefore the application has been put in a queue.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>DBUS_SERVICE_REPLY_SERVICE_EXISTS</entry>
|
|
<entry>0x4</entry>
|
|
<entry>The service does already have a primary owner, and DBUS_SERVICE_FLAG_REPLACE_EXISTING was not specified when trying to acquire the service.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>DBUS_SERVICE_REPLY_ALREADY_OWNER</entry>
|
|
<entry>0x8</entry>
|
|
<entry>The application trying to request ownership of the service is already the owner of it.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="bus-messages-service-acquired">
|
|
<title><literal>org.freedesktop.DBus.ServiceAcquired</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
ServiceAcquired (in STRING service_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 of the service</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
This message is sent to a specific application when it becomes the
|
|
primary owner of a service.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="bus-messages-service-lost">
|
|
<title><literal>org.freedesktop.DBus.ServiceLost</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
ServiceLost (in STRING service_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 of the service</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
This message is sent to a specific application when it loses primary
|
|
ownership of a service.
|
|
|
|
[FIXME instead of ServiceLost/ServiceCreated going only to
|
|
a specific app, why not just OwnerChanged that covers both
|
|
lost and created and changed owner and deleted]
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-service-created">
|
|
<title><literal>org.freedesktop.DBus.ServiceCreated</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
ServiceCreated (in STRING service_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 of the service</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
This message is broadcast to all applications when a service has been
|
|
successfully registered on the message bus.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-service-deleted">
|
|
<title><literal>org.freedesktop.DBus.ServiceDeleted</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
ServiceDeleted (in STRING service_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 of the service</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
This message is broadcast to all applications when a service has been
|
|
deleted from the message bus.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-activate-service">
|
|
<title><literal>org.freedesktop.DBus.ActivateService</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
UINT32 ActivateService (in STRING service_name, in UINT32 flags)
|
|
</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 of the service to activate</entry>
|
|
</row>
|
|
<row>
|
|
<entry>1</entry>
|
|
<entry>UINT32</entry>
|
|
<entry>Flags (currently not used)</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>Result code; DBUS_ACTIVATION_REPLY_ACTIVATED if
|
|
the service was activated successfully or
|
|
DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE if the service is
|
|
already active.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
<para>
|
|
Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation">.
|
|
|
|
[FIXME need semantics in much more detail here; for example,
|
|
if I activate a service then send it a message, is the message
|
|
queued for the new service or is there a race]
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-out-of-memory">
|
|
<title><literal>org.freedesktop.DBus.Error.NoMemory</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
void NoMemory ()
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Sent by the message bus when it can't process a message due to an out of memory failure.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bus-messages-service-does-not-exist">
|
|
<title><literal>org.freedesktop.DBus.Error.ServiceDoesNotExist</literal></title>
|
|
<para>
|
|
As a method:
|
|
<programlisting>
|
|
void ServiceDoesNotExist (in STRING error)
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Sent by the message bus as a reply to a client that tried to send a message to a service that doesn't exist.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
<!--
|
|
<appendix id="implementation-notes">
|
|
<title>Implementation notes</title>
|
|
<sect1 id="implementation-notes-subsection">
|
|
<title></title>
|
|
<para>
|
|
</para>
|
|
</sect1>
|
|
</appendix>
|
|
-->
|
|
|
|
<glossary><title>Glossary</title>
|
|
<para>
|
|
This glossary defines some of the terms used in this specification.
|
|
</para>
|
|
|
|
<glossentry id="term-activation"><glossterm>Activation</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The process of creating an owner for a particular service,
|
|
typically by launching an executable.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id="term-base-service"><glossterm>Base Service</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The special service automatically assigned to an application by the
|
|
message bus. This service may never change owner, and the service
|
|
name will be unique (never reused during the lifetime of the
|
|
message bus).
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id="term-broadcast"><glossterm>Broadcast</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A message sent to the special <literal>org.freedesktop.DBus.Broadcast</literal>
|
|
service; the message bus will forward the broadcast message
|
|
to all applications that have expressed interest in it.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id="term-message"><glossterm>Message</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A message is the atomic unit of communication via the D-BUS
|
|
protocol. It consists of a <firstterm>header</firstterm> and a
|
|
<firstterm>body</firstterm>; the body is made up of
|
|
<firstterm>arguments</firstterm>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id="term-message-bus"><glossterm>Message Bus</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The message bus is a special application that forwards
|
|
or broadcasts messages between a group of applications
|
|
connected to the message bus. It also manages
|
|
<firstterm>services</firstterm>.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
<glossentry id="namespace"><glossterm>Namespace</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Used to prevent collisions when defining message and service
|
|
names. The convention used is the same as Java uses for
|
|
defining classes: a reversed domain name.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="peer-to-peer"><glossterm>Peer-to-peer</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
An application talking directly to another application, without going through a message bus.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="term-secondary-owner"><glossterm>Secondary service owner</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
Each service has a primary owner; messages sent to the service name
|
|
go to the primary owner. However, certain services also maintain
|
|
a queue of secondary owners "waiting in the wings." If
|
|
the primary owner releases the service, then the first secondary
|
|
owner in the queue automatically becomes the primary owner.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="term-service"><glossterm>Service</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
A service is simply a named list of applications. For example, the
|
|
hypothetical <literal>com.yoyodyne.Screensaver</literal> service might
|
|
accept messages that affect a screensaver from Yoyodyne Corporation.
|
|
An application is said to <firstterm>own</firstterm> a service if the
|
|
message bus has associated the application with the service name.
|
|
Services may also have <firstterm>secondary owners</firstterm> (see
|
|
<xref linkend="term-secondary-owner">).
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="term-service-name"><glossterm>Service name</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
The name used when referring to a service. If the service is
|
|
a base service it has a unique service name, for example
|
|
":1-20", and otherwise it should be namespaced.
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry id="term-service-description-files"><glossterm>Service Description Files</glossterm>
|
|
<glossdef>
|
|
<para>
|
|
".service files" tell the bus how to activate a particular service.
|
|
See <xref linkend="term-activation">
|
|
</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
|
|
</glossary>
|
|
</article>
|
|
|