D-BUS Specification
Havoc
Pennington
Red Hat, Inc.
????
<
mailto:hp@pobox.com
hp@pobox.com
>
??
Anders
Carlsson
CodeFactory AB
????????????
<
mailto:andersca@codefactory.se
andersca@codefactory.se
>
??????????
Alexander
Larsson
Red Hat, Inc.
????????????
<
mailto:alexl@redhat.com
alexl@redhat.com
>
??????????
Version 0.11
Table of Contents
#introduction
Introduction
#message-protocol
Message Protocol
#message-protocol-signatures
Type Signatures
#message-protocol-marshaling
Marshaling (Wire Format)
#message-protocol-messages
Message Format
#message-protocol-names
Valid Names
#message-protocol-types
Message Types
#message-protocol-handling-invalid
Invalid Protocol and Spec Extensions
#auth-protocol
Authentication Protocol
#auth-protocol-overview
Protocol Overview
#auth-nul-byte
Special credentials-passing nul byte
#auth-command-auth
AUTH command
#auth-command-cancel
CANCEL Command
#auth-command-data
DATA Command
#auth-command-begin
BEGIN Command
#auth-command-rejected
REJECTED Command
#auth-command-ok
OK Command
#auth-command-error
ERROR Command
#auth-examples
Authentication examples
#auth-states
Authentication state diagrams
#auth-mechanisms
Authentication mechanisms
#addresses
Server Addresses
#naming-conventions
Naming Conventions
#standard-interfaces
Standard Interfaces
#standard-interfaces-peer
org.freedesktop.DBus.Peer
#standard-interfaces-introspectable
org.freedesktop.DBus.Introspectable
#standard-interfaces-properties
org.freedesktop.DBus.Properties
#introspection-format
Introspection Data Format
#message-bus
Message Bus Specification
#message-bus-overview
Message Bus Overview
#message-bus-names
Message Bus Names
#message-bus-routing
Message Bus Message Routing
#message-bus-starting-services
Message Bus Starting Services
#message-bus-types
Well-known Message Bus Instances
#message-bus-messages
Message Bus Messages
#id2991593
Glossary
Introduction
D-BUS is a system for low-latency, low-overhead, easy to use
interprocess communication (IPC). In more detail:
D-BUS is
low-latency
because it is designed
to avoid round trips and allow asynchronous operation, much like
the X protocol.
D-BUS is
low-overhead
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.
D-BUS is
easy to use
because it works in terms
of
messages
rather than byte streams, and
automatically handles a lot of the hard IPC issues. Also, the D-BUS
library is designed to be wrapped in a way that lets developers use
their framework's existing object/type system, rather than learning
a new one specifically for IPC.
The base D-BUS protocol is a one-to-one (peer-to-peer or client-server)
protocol, specified in
#message-protocol
the section called “Message Protocol”
. That is, it is
a system for one application to talk to a single other
application. However, the primary intended application of the protocol is the
D-BUS
message bus
, specified in
#message-bus
the section called “Message Bus Specification”
. The message bus is a special application that
accepts connections from multiple other applications, and forwards
messages among them.
Uses of D-BUS include notification of system changes (notification of when
a camera is plugged in to a computer, or a new version of some software
has been installed), or desktop interoperability, for example a file
monitoring service or a configuration service.
D-BUS is designed for two specific use cases:
A "system bus" for notifications from the system to user sessions,
and to allow the system to request input from user sessions.
A "session bus" used to implement desktop environments such as
GNOME and KDE.
D-BUS is not intended to be a generic IPC system for any possible
application, and intentionally omits many features found in other
IPC systems for this reason. D-BUS may turn out to be useful
in unanticipated applications, but future versions of this
spec and the reference implementation probably will not
incorporate features that interfere with the core use cases.
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.
Message Protocol
A
message
consists of a
header
and a
body
. 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.
The body of the message is made up of zero or more
arguments
, which are typed values, such as an
integer or a byte array.
Both header and body use the same type system and format for
serializing data. Each type of value has a wire format.
Converting a value from some other representation into the wire
format is called
marshaling
and converting
it back from the wire format is
unmarshaling
.
Type Signatures
The D-BUS protocol does not include type tags in the marshaled data; a
block of marshaled values must have a known
type
signature
.  The type signature is made up of
type
codes
. A type code is an ASCII character representing the
type of a value. Because ASCII characters are used, the type signature
will always form a valid ASCII string. A simple string compare
determines whether two type signatures are equivalent.
As a simple example, the type code for 32-bit integer (
INT32
) is
the ASCII character 'i'. So the signature for a block of values
containing a single
INT32
would be:
"i"
A block of values containing two
INT32
would have this signature:
"ii"
All
basic
types work like
INT32
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 four
container
types:
STRUCT
,
ARRAY
,
VARIANT
,
and
DICT_ENTRY
.
STRUCT
has a type code, ASCII character 'r', but this type
code does not appear in signatures. Instead, ASCII characters
'(' and ')' are used to mark the beginning and end of the struct.
So for example, a struct containing two integers would have this
signature:
"(ii)"
Structs can be nested, so for example a struct containing
an integer and another struct:
"(i(ii))"
The value block storing that struct would contain three integers; the
type signature allows you to distinguish "(i(ii))" from "((ii)i)" or
"(iii)" or "iii".
The
STRUCT
type code 'r' is not currently used in the D-BUS protocol,
but is useful in code that implements the protocol. This type code
is specified to allow such code to interoperate in non-protocol contexts.
ARRAY
has ASCII character 'a' as type code. The array type code must be
followed by a
single complete type
. The single
complete type following the array is the type of each array element. So
the simple example is:
"ai"
which is an array of 32-bit integers. But an array can be of any type,
such as this array-of-struct-with-two-int32-fields:
"a(ii)"
Or this array of array of integer:
"aai"
The phrase
single complete type
deserves some
definition. A single complete type is a basic type code, a variant type code,
an array with its element type, or a struct with its fields.
So the following signatures are not single complete types:
"aa"
"(ii"
"ii)"
And the following signatures contain multiple complete types:
"ii"
"aiai"
"(ii)(ii)"
Note however that a single complete type may
contain
multiple other single complete types.
VARIANT
has ASCII character 'v' as its type code. A marshaled value of
type
VARIANT
will have the signature of a single complete type as part
of the
value
.  This signature will be followed by a
marshaled value of that type.
A
DICT_ENTRY
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; 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.
The first field in the
DICT_ENTRY
is always the key.
A message is considered corrupt if the same key occurs twice in the same
array of
DICT_ENTRY
. However, for performance reasons
implementations are not required to reject dicts with duplicate keys.
In most languages, an array of dict entry would be represented as a
map, hash table, or dict object.
The following table summarizes the D-BUS types.
Conventional Name
Code
Description
INVALID
0 (ASCII NUL)
Not a valid type code, used to terminate signatures
BYTE
121 (ASCII 'y')
8-bit unsigned integer
BOOLEAN
98 (ASCII 'b')
Boolean value, 0 is
FALSE
and 1 is
TRUE
. Everything else is invalid.
INT16
110 (ASCII 'n')
16-bit signed integer
UINT16
113 (ASCII 'q')
16-bit unsigned integer
INT32
105 (ASCII 'i')
32-bit signed integer
UINT32
117 (ASCII 'u')
32-bit unsigned integer
INT64
120 (ASCII 'x')
64-bit signed integer
UINT64
116 (ASCII 't')
64-bit unsigned integer
DOUBLE
100 (ASCII 'd')
IEEE 754 double
STRING
115 (ASCII 's')
UTF-8 string (
must
be valid UTF-8). Must be nul terminated.
OBJECT_PATH
111 (ASCII 'o')
Name of an object instance
SIGNATURE
103 (ASCII 'g')
A type signature
ARRAY
97 (ASCII 'a')
Array
STRUCT
114 (ASCII 'r'), 40 (ASCII '('), 41 (ASCII ')')
Struct
VARIANT
118 (ASCII 'v')
Variant type (the type of the value is part of the value itself)
DICT_ENTRY
101 (ASCII 'e'), 123 (ASCII '{'), 125 (ASCII '}')
Entry in a dict or map (array of key-value pairs)
Marshaling (Wire Format)
Given a type signature, a block of bytes can be converted into typed
values. This section describes the format of the block of bytes.  Byte
order and alignment issues are handled uniformly for all D-BUS types.
A block of bytes has an associated byte order. The byte order
has to be discovered in some way; for D-BUS messages, the
byte order is part of the message header as described in
#message-protocol-messages
the section called “Message Format”
. For now, assume
that the byte order is known to be either little endian or big
endian.
Each value in a block of bytes is aligned "naturally," for example
4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
8-byte boundary. To properly align a value,
alignment
padding
may be necessary. The alignment padding must always
be the minimum required padding to properly align the following value;
and it must always be made up of nul bytes. The alignment padding must
not be left uninitialized (it can't contain garbage), and more padding
than required must not be used.
Given all this, the types are marshaled on the wire as follows:
Conventional Name
Encoding
Alignment
INVALID
Not applicable; cannot be marshaled.
N/A
BYTE
A single 8-bit byte.
1
BOOLEAN
As for
UINT32
, but only 0 and 1 are valid values.
4
INT16
16-bit signed integer in the message's byte order.
2
UINT16
16-bit unsigned integer in the message's byte order.
2
INT32
32-bit signed integer in the message's byte order.
4
UINT32
32-bit unsigned integer in the message's byte order.
4
INT64
64-bit signed integer in the message's byte order.
8
UINT64
64-bit unsigned integer in the message's byte order.
8
DOUBLE
64-bit IEEE 754 double in the message's byte order.
8
STRING
A
UINT32
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.
4 (for the length)
OBJECT_PATH
Exactly the same as
STRING
except the
content must be a valid object path (see below).
4 (for the length)
SIGNATURE
The same as
STRING
except the length is a single
byte (thus signatures have a maximum length of 255)
and the content must be a valid signature (see below).
1
ARRAY
A
UINT32
giving the length of the array data in bytes, followed by
alignment padding to the alignment boundary of the array element type,
followed by each array element. The array length is from the
end of the alignment padding to the end of the last element,
i.e. it does not include the padding after the length,
or any padding after the last element.
Arrays have a maximum length defined to be 2 to the 26th power or
67108864. Implementations must not send or accept arrays exceeding this
length.
4 (for the length)
STRUCT
A struct must start on an 8-byte boundary regardless of the
type of the struct fields. The struct value consists of each
field marshaled in sequence starting from that 8-byte
alignment boundary.
8
VARIANT
A variant type has a marshaled
SIGNATURE
followed by a marshaled value with the type
given in the signature.
Unlike a message signature, the variant signature
can contain only a single complete type.
So "i" is OK, "ii" is not.
1 (alignment of the signature)
DICT_ENTRY
Identical to STRUCT.
8
Valid Object Paths
An object path is a name used to refer to an object instance.
Conceptually, each participant in a D-BUS message exchange may have
any number of object instances (think of C++ or Java objects) and each
such instance will have a path. Like a filesystem, the object
instances in an application form a hierarchical tree.
The following rules define a valid object path. Implementations must
not send or accept messages with invalid object paths.
The path may be of any length.
The path must begin with an ASCII '/' (integer 47) character,
and must consist of elements separated by slash characters.
Each element must only contain the ASCII characters
"[A-Z][a-z][0-9]_"
No element may be the empty string.
Multiple '/' characters cannot occur in sequence.
A trailing '/' character is not allowed unless the
path is the root path (a single '/' character).
Valid Signatures
An implementation must not send or accept invalid signatures.
Valid signatures will conform to the following rules:
The signature ends with a nul byte.
The signature is a list of single complete types.
Arrays must have element types, and structs must
have both open and close parentheses.
Only type codes and open and close parentheses are
allowed in the signature. The
STRUCT
type code
is not allowed in signatures, because parentheses
are used instead.
The maximum depth of container type nesting is 32 array type
codes and 32 open parentheses. This implies that the maximum
total depth of recursion is 64, for an "array of array of array
of ... struct of struct of struct of ..."  where there are 32
array and 32 struct.
The maximum length of a signature is 255.
Signatures must be nul-terminated.
Message Format
A message consists of a header and a body. The header is a block of
values with a fixed signature and meaning.  The body is a separate block
of values, with a signature specified in the header.
The length of the header must be a multiple of 8, allowing the body to
begin on an 8-byte boundary when storing the entire message in a single
buffer. If the header does not naturally end on an 8-byte boundary
up to 7 bytes of nul-initialized alignment padding must be added.
The message body need not end on an 8-byte boundary.
The maximum length of a message, including header, header alignment padding,
and body is 2 to the 27th power or 134217728. Implementations must not
send or accept messages exceeding this size.
The signature of the header is:
"yyyyuua(yv)"
Written out more readably, this is:
BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
These values have the following meanings:
Value
Description
1st
BYTE
Endianness flag; ASCII 'l' for little-endian
or ASCII 'B' for big-endian. Both header and body are
in this endianness.
2nd
BYTE
Message type
. Unknown types must be ignored.
Currently-defined types are described below.
3rd
BYTE
Bitwise OR of flags. Unknown flags
must be ignored. Currently-defined flags are described below.
4th
BYTE
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.
FIXME this field is stupid and pointless to put in
every message.
1st
UINT32
Length in bytes of the message body, starting
from the end of the header. The header ends after
its alignment padding to an 8-boundary.
2nd
UINT32
The serial of this message, used as a cookie
by the sender to identify the reply corresponding
to this request.
ARRAY
of
STRUCT
of (
BYTE
,
VARIANT
)
An array of zero or more
header
fields
where the byte is the field code, and the
variant is the field value. The message type determines
which fields are required.
Message types
that can appear in the second byte
of the header are:
Conventional name
Decimal value
Description
INVALID
0
This is an invalid type.
METHOD_CALL
1
Method call.
METHOD_RETURN
2
Method reply with returned data.
ERROR
3
Error reply. If the first argument exists and is a
string, it is an error message.
SIGNAL
4
Signal emission.
Flags that can appear in the third byte of the header:
Conventional name
Hex value
Description
NO_REPLY_EXPECTED
0x1
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 and the only harm
from doing so is extra network traffic.
NO_AUTO_START
0x2
The bus must not launch an owner
for the destination name in response to this message.
Header Fields
The array at the end of the header contains
header
fields
, where each field is a 1-byte field code followed
by a field value. A header must contain the required header fields for
its message type, and zero or more of any optional header
fields. Future versions of this protocol specification may 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.
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
(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 it must be ignored
even though it has no meaning as of this version of the spec.
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
INTERFACE
field of type
UINT32
would be considered corrupt.
Here are the currently-defined header fields:
Conventional Name
Decimal Code
Type
Required In
Description
INVALID
0
N/A
not allowed
Not a valid field name (error if it appears in a message)
PATH
1
OBJECT_PATH
METHOD_CALL
,
SIGNAL
The object to send a call to,
or the object a signal is emitted from.
INTERFACE
2
STRING
SIGNAL
The interface to invoke a method call on, or
that a signal is emitted from. Optional for
method calls, required for signals.
MEMBER
3
STRING
METHOD_CALL
,
SIGNAL
The member, either the method name or signal name.
ERROR_NAME
4
STRING
ERROR
The name of the error that occurred, for errors
REPLY_SERIAL
5
UINT32
ERROR
,
METHOD_RETURN
The serial number of the message this message is a reply
to. (The serial number is the second
UINT32
in the header.)
DESTINATION
6
STRING
optional
The name of the connection this message is intended for.
Only used in combination with the message bus, see
#message-bus
the section called “Message Bus Specification”
.
SENDER
7
STRING
optional
Unique name of the sending connection.
The message bus fills in this field so it is reliable; the field is
only meaningful in combination with the message bus.
SIGNATURE
8
SIGNATURE
optional
The signature of the message body.
If omitted, it is assumed to be the
empty signature "" (i.e. the body must be 0-length).
Valid Names
The various names in D-BUS messages have some restrictions.
There is a
maximum name length
of 255 which applies to bus names, interfaces, and members.
Interface names
Interfaces have names with type
STRING
, meaning that
they must be valid UTF-8. However, there are also some
additional restrictions that apply to interface names
specifically:
They are composed of 1 or more elements separated by
a period ('.') character. All elements must contain at least
one character.
Each element must only contain the ASCII characters
"[A-Z][a-z][0-9]_" and must not begin with a digit.
They must contain at least one '.' (period)
character (and thus at least two elements).
They must not begin with a '.' (period) character.
They must not exceed the maximum name length.
Bus names
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.
Member names
Member (i.e. method or signal) names:
Must only contain the ASCII characters
"[A-Z][a-z][0-9]_" and may not begin with a
digit.
Must not contain the '.' (period) character.
Must not exceed the maximum name length.
Must be at least 1 byte in length.
Error names
Error names have the same restrictions as interface names.
Message Types
Each of the message types (
METHOD_CALL
,
METHOD_RETURN
,
ERROR
, and
SIGNAL
) has its own expected usage conventions and header fields.
This section describes these conventions.
Method Calls
Some messages invoke an operation on a remote object.  These are
called method call messages and have the type tag
METHOD_CALL
. Such
messages map naturally to methods on objects in a typical program.
A method call message is required to have a
MEMBER
header field
indicating the name of the method. Optionally, the message has an
INTERFACE
field giving the interface the method is a part of. In the
absence of an
INTERFACE
field, if two interfaces on the same object have
a method with the same name, it is undefined which of the two methods
will be invoked. Implementations may also choose to return an error in
this ambiguous case. However, if a method name is unique
implementations must not require an interface field.
Method call messages also include a
PATH
field
indicating the object to invoke the method on. If the call is passing
through a message bus, the message will also have a
DESTINATION
field giving the name of the connection
to receive the message.
When an application handles a method call message, it is required to
return a reply. The reply is identified by a
REPLY_SERIAL
header field
indicating the serial number of the
METHOD_CALL
being replied to. The
reply can have one of two types; either
METHOD_RETURN
or
ERROR
.
If the reply has type
METHOD_RETURN
, the arguments to the reply message
are the return value(s) or "out parameters" of the method call.
If the reply has type
ERROR
, then an "exception" has been thrown,
and the call fails; no return value will be provided. It makes
no sense to send multiple replies to the same method call.
Even if a method call has no return values, a
METHOD_RETURN
reply is required, so the caller will know the method
was successfully processed.
The
METHOD_RETURN
or
ERROR
reply message must have the
REPLY_SERIAL
header field.
If a
METHOD_CALL
message has the flag
NO_REPLY_EXPECTED
,
then as an optimization the application receiving the method
call may choose to omit the reply message (regardless of
whether the reply would have been
METHOD_RETURN
or
ERROR
).
However, it is also acceptable to ignore the
NO_REPLY_EXPECTED
flag and reply anyway.
Unless a message has the flag
NO_AUTO_START
, if the
destination name does not exist then a program to own the destination
name will be started before the message is delivered.  The message
will be held until the new program is successfully started or has
failed to start; in case of failure, an error will be returned. This
flag is only relevant in the context of a message bus, it is ignored
during one-to-one communication with no intermediate bus.
Mapping method calls to native APIs
APIs for D-BUS may map method calls to a method call in a specific
programming language, such as C++, or may map a method call written
in an IDL to a D-BUS message.
In APIs of this nature, arguments to a method are often termed "in"
(which implies sent in the
METHOD_CALL
), or "out" (which implies
returned in the
METHOD_RETURN
). Some APIs such as CORBA also have
"inout" arguments, which are both sent and received, i.e. the caller
passes in a value which is modified. Mapped to D-BUS, an "inout"
argument is equivalent to an "in" argument, followed by an "out"
argument. You can't pass things "by reference" over the wire, so
"inout" is purely an illusion of the in-process API.
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.
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.
Error replies are normally mapped to exceptions in languages that have
exceptions.
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.
This specification doesn't require anything of native API bindings;
the preceding is only a suggested convention for consistency
among bindings.
Signal Emission
Unlike method calls, signal emissions have no replies.
A signal emission is simply a single message of type
SIGNAL
.
It must have three header fields:
PATH
giving the object
the signal was emitted from, plus
INTERFACE
and
MEMBER
giving
the fully-qualified name of the signal.
Errors
Messages of type
ERROR
are most commonly replies
to a
METHOD_CALL
, but may be returned in reply
to any kind of message. The message bus for example
will return an
ERROR
in reply to a signal emission if
the bus does not have enough memory to send the signal.
An
ERROR
may have any arguments, but if the first
argument is a
STRING
, it must be an error message.
The error message may be logged or shown to the user
in some way.
Notation in this document
This document uses a simple pseudo-IDL to describe particular method
calls and signals. Here is an example of a method call:
org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
out UINT32 resultcode)
This means
INTERFACE
= org.freedesktop.DBus,
MEMBER
= StartServiceByName,
METHOD_CALL
arguments are
STRING
and
UINT32
,
METHOD_RETURN
argument
is
UINT32
. Remember that the
MEMBER
field can't contain any '.' (period)
characters so it's known that the last part of the name in
the "IDL" is the member name.
In C++ that might end up looking like this:
unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
unsigned int flags);
or equally valid, the return value could be done as an argument:
void org::freedesktop::DBus::StartServiceByName (const char   *name,
unsigned int  flags,
unsigned int *resultcode);
It's really up to the API designer how they want to make
this look. You could design an API where the namespace wasn't used
in C++, using STL or Qt, using varargs, or whatever you wanted.
Signals are written as follows:
org.freedesktop.DBus.NameLost (STRING name)
Signals don't specify "in" vs. "out" because only
a single direction is possible.
It isn't especially encouraged to use this lame pseudo-IDL in actual
API implementations; you might use the native notation for the
language you're using, or you might use COM or CORBA IDL, for example.
Invalid Protocol and Spec Extensions
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.
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).
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.
In the authentication protocol (see
#auth-protocol
the section called “Authentication 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.
The authentication protocol supports pluggable auth mechanisms.
The address format (see
#addresses
the section called “Server Addresses”
) supports new
kinds of transport.
Messages with an unknown type (something other than
METHOD_CALL
,
METHOD_RETURN
,
ERROR
,
SIGNAL
) 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.
Header fields with an unknown or unexpected field code must be ignored,
though again they must still be well-formed.
New standard interfaces (with new methods and signals) can of course be added.
Authentication Protocol
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.
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
Protocol Overview
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:
AUTH [mechanism] [initial-response]
CANCEL
BEGIN
DATA <data in hex encoding>
ERROR [human-readable error explanation]
From server to client are as follows:
REJECTED <space-separated list of mechanism names>
OK <GUID in hex>
DATA <data in hex encoding>
ERROR
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".
Special credentials-passing nul byte
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.
A nul byte in any context other than the initial byte is an error;
the protocol is ASCII-only.
The credentials sent along with the nul byte may be used with the
SASL mechanism EXTERNAL.
AUTH command
If an AUTH command has no arguments, it is a request to list
available mechanisms. The server must respond with a REJECTED
command listing the mechanisms it understands, or with an error.
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.
If the server does not support the mechanism given in the AUTH
command, it must send either a REJECTED command listing the mechanisms
it does support, or an error.
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.
If authentication succeeds after exchanging DATA commands,
an OK command must be sent to the client.
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.
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.
CANCEL Command
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.
DATA Command
The DATA command may come from either client or server, and simply
contains a hex-encoded block of data to be interpreted
according to the SASL mechanism in use.
Some SASL mechanisms support sending an "empty string";
FIXME we need some way to do this.
BEGIN Command
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.
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.
REJECTED Command
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.
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.
OK Command
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.
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.
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.
The OK command has one argument, which is the GUID of the server.
See
#addresses
the section called “Server Addresses”
for more on server GUIDs.
ERROR Command
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.
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.
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.
Authentication examples
Figure?1.?Example of successful magic cookie authentication
(MAGIC_COOKIE is a made up mechanism)
C: AUTH MAGIC_COOKIE 3138363935333137393635383634
S: OK 1234deadbeef
C: BEGIN
Figure?2.?Example of finding out mechanisms then picking one
C: AUTH
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
S: OK 1234deadbeef
C: BEGIN
Figure?3.?Example of client sends unknown command then falls back to regular auth
C: FOOBAR
S: ERROR
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: OK 1234deadbeef
C: BEGIN
Figure?4.?Example of server doesn't support initial auth mechanism
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
S: OK 1234deadbeef
C: BEGIN
Figure?5.?Example of wrong password or the like followed by successful retry
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
S: REJECTED
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
S: OK 1234deadbeef
C: BEGIN
Figure?6.?Example of skey cancelled and restarted
C: AUTH MAGIC_COOKIE 3736343435313230333039
S: REJECTED KERBEROS_V4 SKEY
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: CANCEL
S: REJECTED
C: AUTH SKEY 7ab83f32ee
S: DATA 8799cabb2ea93e
C: DATA 8ac876e8f68ee9809bfa876e6f9876g8fa8e76e98f
S: OK 1234deadbeef
C: BEGIN
Authentication state diagrams
This section documents the auth protocol in terms of
a state machine for the client and the server. This is
probably the most robust way to implement the protocol.
Client states
To more precisely describe the interaction between the
protocol state machine and the authentication mechanisms the
following notation is used: MECH(CHALL) means that the
server challenge CHALL was fed to the mechanism MECH, which
returns one of
CONTINUE(RESP) means continue the auth conversation
and send RESP as the response to the server;
OK(RESP) means that after sending RESP to the server
the client side of the auth conversation is finished
and the server should return "OK";
ERROR means that CHALL was invalid and could not be
processed.
Both RESP and CHALL may be empty.
The Client starts by getting an initial response from the
default mechanism and sends AUTH MECH RESP, or AUTH MECH if
the mechanism did not provide an initial response.  If the
mechanism returns CONTINUE, the client starts in state
WaitingForData
, if the mechanism
returns OK the client starts in state
WaitingForOK
.
The client should keep track of available mechanisms and
which it mechanisms it has already attempted. This list is
used to decide which AUTH command to send. When the list is
exhausted, the client should give up and close the
connection.
WaitingForData
.?
Receive DATA CHALL
MECH(CHALL) returns CONTINUE(RESP) → send
DATA RESP, goto
WaitingForData
MECH(CHALL) returns OK(RESP) → send DATA
RESP, goto
WaitingForOK
MECH(CHALL) returns ERROR → send ERROR
[msg], goto
WaitingForData
Receive REJECTED [mechs] →
send AUTH [next mech], goto
WaitingForData or
WaitingForOK
Receive ERROR → send
CANCEL, goto
WaitingForReject
Receive OK → send
BEGIN, terminate auth
conversation, authenticated
Receive anything else → send
ERROR, goto
WaitingForData
WaitingForOK
.?
Receive OK → send BEGIN, terminate auth
conversation,
authenticated
Receive REJECT [mechs] → send AUTH [next mech],
goto
WaitingForData
or
WaitingForOK
Receive DATA → send CANCEL, goto
WaitingForReject
Receive ERROR → send CANCEL, goto
WaitingForReject
Receive anything else → send ERROR, goto
WaitingForOK
WaitingForReject
.?
Receive REJECT [mechs] → send AUTH [next mech],
goto
WaitingForData
or
WaitingForOK
Receive anything else → terminate auth
conversation, disconnect
Server states
For the server MECH(RESP) means that the client response
RESP was fed to the the mechanism MECH, which returns one of
CONTINUE(CHALL) means continue the auth conversation and
send CHALL as the challenge to the client;
OK means that the client has been successfully
authenticated;
REJECT means that the client failed to authenticate or
there was an error in RESP.
The server starts out in state
WaitingForAuth
.  If the client is
rejected too many times the server must disconnect the
client.
WaitingForAuth
.?
Receive AUTH → send REJECTED [mechs], goto
WaitingForAuth
Receive AUTH MECH RESP
MECH not valid mechanism → send REJECTED
[mechs], goto
WaitingForAuth
MECH(RESP) returns CONTINUE(CHALL) → send
DATA CHALL, goto
WaitingForData
MECH(RESP) returns OK → send OK, goto
WaitingForBegin
MECH(RESP) returns REJECT → send REJECTED
[mechs], goto
WaitingForAuth
Receive BEGIN → terminate
auth conversation, disconnect
Receive ERROR → send REJECTED [mechs], goto
WaitingForAuth
Receive anything else → send
ERROR, goto
WaitingForAuth
WaitingForData
.?
Receive DATA RESP
MECH(RESP) returns CONTINUE(CHALL) → send
DATA CHALL, goto
WaitingForData
MECH(RESP) returns OK → send OK, goto
WaitingForBegin
MECH(RESP) returns REJECT → send REJECTED
[mechs], goto
WaitingForAuth
Receive BEGIN → terminate auth conversation,
disconnect
Receive CANCEL → send REJECTED [mechs], goto
WaitingForAuth
Receive ERROR → send REJECTED [mechs], goto
WaitingForAuth
Receive anything else → send ERROR, goto
WaitingForData
WaitingForBegin
.?
Receive BEGIN → terminate auth conversation,
client authenticated
Receive CANCEL → send REJECTED [mechs], goto
WaitingForAuth
Receive ERROR → send REJECTED [mechs], goto
WaitingForAuth
Receive anything else → send ERROR, goto
WaitingForBegin
Authentication mechanisms
This section describes some new authentication mechanisms.
D-BUS also allows any standard SASL mechanism of course.
DBUS_COOKIE_SHA1
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.
Authentication proceeds as follows:
The client sends the username it would like to authenticate
as.
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.
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.
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.
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_general" that's used by servers that do not specify
otherwise.
Cookies are stored in a user's home directory, in the directory
~/.dbus-keyrings/
. 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.
A cookie file contains one cookie per line. Each line
has three space-separated fields:
The cookie ID number, which must be a non-negative integer and
may not be used twice in the same file.
The cookie's creation time, in UNIX seconds-since-the-epoch
format.
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.
Only server processes modify the cookie file.
They must do so with this procedure:
Create a lockfile name by appending ".lock" to the name of the
cookie file.  The server should attempt to create this file
using
O_CREAT | O_EXCL
.  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.
[
#ftn.id2989007
1
]
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.
The pruned and possibly added-to cookie file
must be resaved atomically (using a temporary
file which is rename()'d).
The lock must be dropped by deleting the lockfile.
Clients need not lock the file in order to load it,
because servers are required to save the file atomically.
Server Addresses
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.
Each value is escaped.
For example:
unix:path=/tmp/dbus-test
Which is the address to a unix socket with the path /tmp/dbus-test.
Value escaping is similar to URI escaping but simpler.
The set of optionally-escaped bytes is:
[0-9A-Za-z_-/.\]
. To escape, each
byte
(note, not character) which is not in the
set of optionally-escaped bytes must be replaced with an ASCII
percent (
%
) 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.
To unescape, append each byte in the value; if a byte is an ASCII
percent (
%
) character then append the following
hex value instead. It is an error if a
%
byte
does not have two hex digits following. It is an error if a
non-optionally-escaped byte is seen unescaped.
The set of optionally-escaped bytes is intended to preserve address
readability and convenience.
A server may specify a key-value pair with the key
guid
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.
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.
[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
unix:path=/tmp/dbus-test;unix:path=/tmp/dbus-test2
[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.
Naming Conventions
D-BUS namespaces are all lowercase and correspond to reversed domain
names, as with Java. e.g. "org.freedesktop"
Interface, signal, method, and property names are "WindowsStyleCaps", note
that the first letter is capitalized, unlike Java.
Object paths are normally all lowercase with underscores used rather than
hyphens.
Standard Interfaces
See
#message-protocol-types-notation
the section called “Notation in this document”
for details on
the notation used in this section. There are some standard interfaces
that may be useful across various D-BUS applications.
org.freedesktop.DBus.Peer
The
org.freedesktop.DBus.Peer
interface
has one method:
org.freedesktop.DBus.Peer.Ping ()
On receipt of the
METHOD_CALL
message
org.freedesktop.DBus.Peer.Ping
, an application should do
nothing other than reply with a
METHOD_RETURN
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.)
org.freedesktop.DBus.Introspectable
This interface has one method:
org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)
Objects instances may implement
Introspect
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.
#introspection-format
the section called “Introspection Data Format”
describes the format of this XML string.
org.freedesktop.DBus.Properties
Many native APIs will have a concept of object
properties
or
attributes
. These can be exposed via the
org.freedesktop.DBus.Properties
interface.
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);
The available properties and whether they are writable can be determined
by calling
org.freedesktop.DBus.Introspectable.Introspect
,
see
#standard-interfaces-introspectable
the section called “
org.freedesktop.DBus.Introspectable
”
.
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).
Introspection Data Format
As described in
#standard-interfaces-introspectable
the section called “
org.freedesktop.DBus.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.
Here is an example of introspection data:
<!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>
A more formal DTD and spec needs writing, but here are some quick notes.
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.
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.
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.
The possible directions are "in" and "out",
unlike CORBA there is no "inout"
The possible property access flags are
"readwrite", "read", and "write"
Multiple interfaces can of course be listed for
one <node>.
The "name" attribute on arguments is optional.
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:
Name
Values (separated by ,)
Description
org.freedesktop.DBus.Deprecated
true,false
Whether or not the entity is deprecated; defaults to false
org.freedesktop.DBus.GLib.CSymbol
(string)
The C symbol; may be used for methods and interfaces
Message Bus Specification
Message Bus Overview
The message bus accepts connections from one or more applications.
Once connected, applications can exchange messages with other
applications that are also connected to the bus.
In order to route messages among connections, the message bus keeps a
mapping from names to connections. Each connection has one
unique-for-the-lifetime-of-the-bus name automatically assigned.
Applications may request additional names for a connection. Additional
names are usually "well-known names" such as
"org.freedesktop.TextEditor". When a name is bound to a connection,
that connection is said to
own
the name.
The bus itself owns a special name,
org.freedesktop.DBus
.
This name routes messages to the bus, allowing applications to make
administrative requests. For example, applications can ask the bus
to assign a name to a connection.
Each name may have
queued owners
.  When an
application requests a name for a connection and the name is already in
use, the bus will optionally add the connection to a queue waiting for
the name. If the current owner of the name disconnects or releases
the name, the next connection in the queue will become the new owner.
This feature causes the right thing to happen if you start two text
editors for example; the first one may request "org.freedesktop.TextEditor",
and the second will be queued as a possible owner of that name. When
the first exits, the second will take over.
Messages may have a
DESTINATION
field (see
#message-protocol-header-fields
the section called “Header Fields”
).  If the
DESTINATION
field is present, it specifies a message
recipient by name. Method calls and replies normally specify this field.
Signals normally do not specify a destination; they are sent to all
applications with
message matching rules
that
match the message.
When the message bus receives a method call, if the
DESTINATION
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
org.freedesktop.DBus.Peer.Ping
message with no
DESTINATION
will cause the message bus itself to
reply to the ping immediately; the message bus will not make this
message visible to other applications.
Continuing the
org.freedesktop.DBus.Peer.Ping
example, if
the ping message were sent with a
DESTINATION
name of
com.yoyodyne.Screensaver
, then the ping would be
forwarded, and the Yoyodyne Corporation screensaver application would be
expected to reply to the ping.
Message Bus Names
Each connection has at least one name, assigned at connection time and
returned in response to the
org.freedesktop.DBus.Hello
method call.  This
automatically-assigned name is called the connection's
unique
name
.  Unique names are never reused for two different
connections to the same bus.
Ownership of a unique name is a prerequisite for interaction with
the message bus. It logically follows that the unique name is always
the first name that an application comes to own, and the last
one that it loses ownership of.
Unique connection names must begin with the character ':' (ASCII colon
character); bus names that are not unique names must not begin
with this character. (The bus must reject any attempt by an application
to manually request a name beginning with ':'.) This restriction
categorically prevents "spoofing"; messages sent to a unique name
will always go to the expected connection.
When a connection is closed, all the names that it owns are deleted (or
transferred to the next connection in the queue if any).
A connection can request additional names to be associated with it using
the
org.freedesktop.DBus.RequestName
message.
#message-protocol-names-bus
the section called “Bus names”
describes the format of a valid
name.
org.freedesktop.DBus.RequestName
As a method:
UINT32 RequestName (in STRING name, in UINT32 flags)
Message arguments:
Argument
Type
Description
0
STRING
Name to request
1
UINT32
Flags
Reply arguments:
Argument
Type
Description
0
UINT32
Return value
This method call should be sent to
org.freedesktop.DBus
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:
Conventional Name
Value
Description
DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT
0x1
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
org.freedesktop.DBus.NameLost
signal.
DBUS_NAME_FLAG_REPLACE_EXISTING
0x2
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 return code can be one of the following values:
Conventional Name
Value
Description
DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER
1
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.
DBUS_REQUEST_NAME_REPLY_IN_QUEUE
2
The name already had an owner, DBUS_NAME_FLAG_REPLACE_EXISTING was not specified, and the current owner specified DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.
DBUS_REQUEST_NAME_REPLY_EXISTS
3
The name already has an owner, and DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.
DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER
4
The application trying to request ownership of a name is already the owner of it.
Message Bus Message Routing
FIXME
Message Bus Starting Services
The message bus can start applications on behalf of other applications.
In CORBA terms, this would be called
activation
.
An application that can be started in this way is called a
service
.
With D-BUS, starting a service is normally done by name. That is,
applications ask the message bus to start some program that will own a
well-known name, such as
org.freedesktop.TextEditor
.
This implies a contract documented along with the name
org.freedesktop.TextEditor
for which objects
the owner of that name will provide, and what interfaces those
objects will have.
To find an executable corresponding to a particular name, the bus daemon
looks for
service description files
.  Service
description files define a mapping from names to executables. Different
kinds of message bus will look for these files in different places, see
#message-bus-types
the section called “Well-known Message Bus Instances”
.
[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
http://www.freedesktop.org/standards/desktop-entry-spec/desktop-entry-spec.html
desktop
entries
. 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?7.?Example service description file
# Sample service description file
[D-BUS Service]
Names=org.freedesktop.ConfigurationDatabase;org.gnome.GConf;
Exec=/usr/libexec/gconfd-2
When an application asks to start a service by name, the bus daemon tries to
find a service that will own that name. 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?]
The executable launched will have the environment variable
DBUS_STARTER_ADDRESS
set to the address of the
message bus so it can connect and request the appropriate names.
The executable being launched may want to know whether the message bus
starting it is one of the well-known message buses (see
#message-bus-types
the section called “Well-known Message Bus Instances”
). To facilitate this, the bus must also set
the
DBUS_STARTER_BUS_TYPE
environment variable if it is one
of the well-known buses. The currently-defined values for this variable
are
system
for the systemwide message bus,
and
session
for the per-login-session message
bus. The new executable must still connect to the address given
in
DBUS_STARTER_ADDRESS
, but may assume that the
resulting connection is to the well-known bus.
[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.]
Message Bus Service Scope
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.
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
_DBUS_DISPLAY_ID
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.
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
_DBUS_DISPLAY_BUS_ADDRESS
property on screen 0 of the display, pointing to this bus.
Well-known Message Bus Instances
Two standard message bus instances are defined here, along with how
to locate them and where their service files live.
Login session message bus
Each time a user logs in, a
login session message
bus
may be started. All applications in the user's login
session may interact with one another using this message bus.
The address of the login session message bus is given
in the
DBUS_SESSION_BUS_ADDRESS
environment
variable. If that variable is not set, applications may
also try to read the address from the X Window System root
window property
_DBUS_SESSION_BUS_ADDRESS
.
The root window property must have type
STRING
.
The environment variable should have precedence over the
root window property.
[FIXME specify location of .service files, probably using
DESKTOP_DIRS etc. from basedir specification, though login session
bus is not really desktop-specific]
System message bus
A computer may have a
system message bus
,
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.
The address of the system message bus is given
in the
DBUS_SYSTEM_BUS_ADDRESS
environment
variable. If that variable is not set, applications should try
to connect to the well-known address
unix:path=/var/run/dbus/system_bus_socket
.
[
#ftn.id2990575
2
]
[FIXME specify location of system bus .service files]
Message Bus Messages
The special message bus name
org.freedesktop.DBus
responds to a number of additional messages.
org.freedesktop.DBus.Hello
As a method:
STRING Hello ()
Reply arguments:
Argument
Type
Description
0
STRING
Unique name assigned to the connection
Before an application is able to send messages to other applications
it must send the
org.freedesktop.DBus.Hello
message
to the message bus to obtain a unique name. If an application without
a unique name tries to send a message to another application, or a
message to the message bus itself that isn't the
org.freedesktop.DBus.Hello
message, it will be
disconnected from the bus.
There is no corresponding "disconnect" request; if a client wishes to
disconnect from the bus, it simply closes the socket (or other
communication channel).
org.freedesktop.DBus.ListNames
As a method:
ARRAY of STRING ListNames ()
Reply arguments:
Argument
Type
Description
0
ARRAY of STRING
Array of strings where each string is a bus name
Returns a list of all currently-owned names on the bus.
org.freedesktop.DBus.NameHasOwner
As a method:
BOOLEAN NameHasOwner (in STRING name)
Message arguments:
Argument
Type
Description
0
STRING
Name to check
Reply arguments:
Argument
Type
Description
0
BOOLEAN
Return value, true if the name exists
Checks if the specified name exists (currently has an owner).
org.freedesktop.DBus.NameOwnerChanged
This is a signal:
NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
Message arguments:
Argument
Type
Description
0
STRING
Name with a new owner
1
STRING
Old owner or empty string if none
2
STRING
New owner or empty string if none
This signal indicates that the owner of a name has changed.
It's also the signal to use to detect the appearance of
new names on the bus.
org.freedesktop.DBus.NameLost
This is a signal:
NameLost (STRING name)
Message arguments:
Argument
Type
Description
0
STRING
Name which was lost
This signal is sent to a specific application when it loses
ownership of a name.
org.freedesktop.DBus.NameAcquired
This is a signal:
NameAcquired (STRING name)
Message arguments:
Argument
Type
Description
0
STRING
Name which was acquired
This signal is sent to a specific application when it gains
ownership of a name.
org.freedesktop.DBus.StartServiceByName
As a method:
UINT32 StartServiceByName (in STRING name, in UINT32 flags)
Message arguments:
Argument
Type
Description
0
STRING
Name of the service to start
1
UINT32
Flags (currently not used)
Reply arguments:
Argument
Type
Description
0
UINT32
Return value
Tries to launch the executable associated with a name. For more information, see
#message-bus-starting-services
the section called “Message Bus Starting Services”
.
The return value can be one of the following values:
Identifier
Value
Description
DBUS_START_REPLY_SUCCESS
1
The service was successfully started.
DBUS_START_REPLY_ALREADY_RUNNING
2
A connection already owns the given name.
org.freedesktop.DBus.GetNameOwner
As a method:
STRING GetNameOwner (in STRING name)
Message arguments:
Argument
Type
Description
0
STRING
Name to get the owner of
Reply arguments:
Argument
Type
Description
0
STRING
Return value, a unique connection name
Returns the unique connection name of the primary owner of the name
given. If the requested name doesn't have an owner, returns a
org.freedesktop.DBus.Error.NameHasNoOwner
error.
org.freedesktop.DBus.GetConnectionUnixUser
As a method:
UINT32 GetConnectionUnixUser (in STRING connection_name)
Message arguments:
Argument
Type
Description
0
STRING
Name of the connection to query
Reply arguments:
Argument
Type
Description
0
UINT32
unix user id
Returns the unix uid of the process connected to the server. If unable to
determine it, a
org.freedesktop.DBus.Error.Failed
error is returned.
Glossary
This glossary defines some of the terms used in this specification.
Bus Name
The message bus maintains an association between names and
connections. (Normally, there's one connection per application.)  A
bus name is simply an identifier used to locate connections. For
example, the hypothetical
com.yoyodyne.Screensaver
name might be used to send a message to a screensaver from Yoyodyne
Corporation.  An application is said to
own
a
name if the message bus has associated the application's connection
with the name.  Names may also have
queued
owners
(see
#term-queued-owner
Queued Name Owner
).
The bus assigns a unique name to each connection,
see
#term-unique-name
Unique Connection Name
. Other names
can be thought of as "well-known names" and are
used to find applications that offer specific functionality.
Message
A message is the atomic unit of communication via the D-BUS
protocol. It consists of a
header
and a
body
; the body is made up of
arguments
.
Message Bus
The message bus is a special application that forwards
or routes messages between a group of applications
connected to the message bus. It also manages
names
used for routing
messages.
Name
See
#term-bus-name
Bus Name
. "Name" may
also be used to refer to some of the other names
in D-BUS, such as interface names.
Namespace
Used to prevent collisions when defining new interfaces or bus
names. The convention used is the same one Java uses for defining
classes: a reversed domain name.
Object
Each application contains
objects
, which have
interfaces
and
methods
. Objects are referred to by a name,
called a
path
.
One-to-One
An application talking directly to another application, without going
through a message bus. One-to-one connections may be "peer to peer" or
"client to server." The D-BUS protocol has no concept of client
vs. server after a connection has authenticated; the flow of messages
is symmetrical (full duplex).
Path
Object references (object names) in D-BUS are organized into a
filesystem-style hierarchy, so each object is named by a path. As in
LDAP, there's no difference between "files" and "directories"; a path
can refer to an object, while still having child objects below it.
Queued Name Owner
Each bus name has a primary owner; messages sent to the name go to the
primary owner. However, certain names also maintain a queue of
secondary owners "waiting in the wings." If the primary owner releases
the name, then the first secondary owner in the queue automatically
becomes the new owner of the name.
Service
A service is an executable that can be launched by the bus daemon.
Services normally guarantee some particular features, for example they
may guarantee that they will request a specific name such as
"org.freedesktop.Screensaver", have a singleton object
"/org/freedesktop/Application", and that object will implement the
interface "org.freedesktop.ScreensaverControl".
Service Description Files
".service files" tell the bus about service applications that can be
launched (see
#term-service
Service
). Most importantly they
provide a mapping from bus names to services that will request those
names when they start up.
Unique Connection Name
The special name automatically assigned to each connection by the
message bus. This name will never change owner, and will be unique
(never reused during the lifetime of the message bus).
It will begin with a ':' character.
[
#id2989007
1
]
Lockfiles are used instead of real file
locking
fcntl()
because real locking
implementations are still flaky on network
filesystems.
[
#id2990575
2
]
The D-BUS reference implementation actually honors the
$(localstatedir)
configure option
for this address, on both client and server side.
