The D-Bus protocol is frozen (only compatible extensions are allowed) as of November 8, 2006. However, this specification could still use a fair bit of work to make interoperable reimplementation possible without reference to the D-Bus reference implementation. Thus, this specification is not marked 1.0. To mark it 1.0, we'd like to see someone invest significant effort in clarifying the specification language, and growing the specification to cover more aspects of the reference implementation's behavior.

Until this work is complete, any attempt to reimplement D-Bus will probably require looking at the reference implementation and/or asking questions on the D-Bus mailing list about intended behavior. Questions on the list are very welcome.

Nonetheless, this document should be a useful starting point and is to our knowledge accurate, though incomplete.

The simplest type codes are the basic types, which are the types whose structure is entirely defined by their 1-character type code. Basic types consist of fixed types and string-like types.

The fixed types are basic types whose values have a fixed length, namely BYTE, BOOLEAN, DOUBLE, UNIX_FD, and signed or unsigned integers of length 16, 32 or 64 bits.

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"
        

The characteristics of the fixed types are listed in this table.

The string-like types are basic types with a variable length. The value of any string-like type is conceptually 0 or more Unicode codepoints encoded in UTF-8, none of which may be U+0000. The UTF-8 text must be validated strictly: in particular, it must not contain overlong sequences or codepoints above U+10FFFF.

Since D-Bus Specification version 0.21, in accordance with Unicode Corrigendum #9, the "noncharacters" U+FDD0..U+FDEF, U+nFFFE and U+nFFFF are allowed in UTF-8 strings (but note that older versions of D-Bus rejected these noncharacters).

The marshalling formats for the string-like types all end with a single zero (NUL) byte, but that byte is not considered to be part of the text.

The characteristics of the string-like types are listed in this table.

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.

Empty structures are not allowed; there must be at least one type code between the parentheses.

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"
        

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.

Unlike a message signature, the variant signature can contain only a single complete type. So "i", "ai" or "(ii)" is OK, but "ii" is not. Use of variants may not cause a total message depth to be larger than 64, including other container types such as structures.

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.

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 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. Boundaries are calculated globally, with respect to the first byte in the message. To properly align a value, alignment padding may be necessary before the value. 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.

As an exception to natural alignment, STRUCT and DICT_ENTRY values are always aligned to an 8-byte boundary, regardless of the alignments of their contents.

To marshal and unmarshal fixed types, you simply read one value from the data block corresponding to each type code in the signature. All signed integer values are encoded in two's complement, DOUBLE values are IEEE 754 double-precision floating-point, and BOOLEAN values are encoded in 32 bits (of which only the least significant bit is used).

The string-like types (STRING, OBJECT_PATH and SIGNATURE) are all marshalled as a fixed-length unsigned integer n giving the length of the variable part, followed by n nonzero bytes of UTF-8 text, followed by a single zero (nul) byte which is not considered to be part of the text. The alignment of the string-like type is the same as the alignment of n: any padding required for n appears immediately before n itself. There is never any alignment padding between n and the string text, or between the string text and the trailing nul. The alignment padding for the next value in the message (if there is one) starts after the trailing nul.

For the STRING and OBJECT_PATH types, n is encoded in 4 bytes (a UINT32), leading to 4-byte alignment. For the SIGNATURE type, n is encoded as a single byte (a UINT8). As a result, alignment padding is never required before a SIGNATURE.

For example, if the current position is a multiple of 8 bytes from the beginning of a little-endian message, strings ‘foo’, ‘+’ and ‘bar’ would be serialized in sequence as follows:

                                          no padding required, we are already at a multiple of 4
0x03 0x00 0x00 0x00                       length of ‘foo’ = 3
                    0x66 0x6f 0x6f        ‘foo’
                                   0x00   trailing nul

                                          no padding required, we are already at a multiple of 4
0x01 0x00 0x00 0x00                       length of ‘+’ = 1
                    0x2b                  ‘+’
                         0x00             trailing nul

                               0x00 0x00  2 bytes of padding to reach next multiple of 4
0x03 0x00 0x00 0x00                       length of ‘bar’ = 3
                    0x62 0x61 0x72        ‘bar’
                                    0x00  trailing nul
        

Arrays are marshalled as a UINT32 n giving the length of the array data in bytes, followed by alignment padding to the alignment boundary of the array element type, followed by the n bytes of the array elements marshalled in sequence. n does not include the padding after the length, or any padding after the last element. i.e. n should be divisible by the number of elements in the array.

For instance, if the current position in the message is a multiple of 8 bytes and the byte-order is big-endian, an array containing only the 64-bit integer 5 would be marshalled as:

00 00 00 08               n = 8 bytes of data
00 00 00 00               padding to 8-byte boundary
00 00 00 00  00 00 00 05  first element = 5
        

Arrays have a maximum length defined to be 2 to the 26th power or 67108864 (64 MiB). Implementations must not send or accept arrays exceeding this length.

Structs and dict entries are marshalled in the same way as their contents, but their alignment is always to an 8-byte boundary, even if their contents would normally be less strictly aligned.

Variants are marshalled as the SIGNATURE of the contents (which must be a single complete type), followed by a marshalled value with the type given by that signature. The variant has the same 1-byte alignment as the signature, which means that alignment padding before a variant is never needed. Use of variants must not cause a total message depth to be larger than 64, including other container types such as structures. (See Valid Signatures.)

Given all this, the types are marshaled on the wire as follows:

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 (128 MiB). 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:

Message types that can appear in the second byte of the header are:

Flags that can appear in the third byte of the header:

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.

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.

            org.freedesktop.DBus.StartServiceByName (in STRING name, in UINT32 flags,
                                                     out UINT32 resultcode)
          

            unsigned int org::freedesktop::DBus::StartServiceByName (const char  *name,
                                                                     unsigned int flags);
          

            void org::freedesktop::DBus::StartServiceByName (const char   *name,
                                                             unsigned int  flags,
                                                             unsigned int *resultcode);
          

            org.freedesktop.DBus.NameLost (STRING name)
          

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 idiosyncrasy 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.

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:

From server to client are as follows:

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".

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.

The AUTH command is sent by the client to the server. The server replies with DATA, OK or REJECTED.

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 CANCEL command is sent by the client to the server. The server replies with REJECTED.

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.

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. If sent by the client, the server replies with DATA, OK or REJECTED.

Some SASL mechanisms support sending an "empty string"; FIXME we need some way to do this.

The BEGIN command is sent by the client to the server. The server does not reply.

The BEGIN command acknowledges that the client has received an OK command from the server and completed any feature negotiation that it wishes to do, and declares 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.

Unlike all other commands, the server does not reply to the BEGIN command with an authentication command of its own. After the \r\n of the reply to the command before BEGIN, the next octet received by the client must be the first octet of the authenticated/encrypted stream of D-Bus messages.

The REJECTED command is sent by the server to the client.

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.

The OK command is sent by the server to the client.

The OK command indicates that the client has been authenticated. The client may now proceed with negotiating Unix file descriptor passing. To do that it shall send NEGOTIATE_UNIX_FD to the server.

Otherwise, 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 BEGIN command has been received. Further communication will be a stream of D-Bus messages (optionally encrypted, as negotiated) rather than this protocol.

If there is no negotiation, 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. If the client negotiates Unix file descriptor passing, the first octet received by the client after the \r\n of the AGREE_UNIX_FD or ERROR reply must be the first octet of the authenticated/encrypted stream.

The OK command has one argument, which is the GUID of the server. See the section called “Server Addresses” for more on server GUIDs.

The ERROR command can be sent in either direction. If sent by the client, the server replies with REJECTED.

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.

The NEGOTIATE_UNIX_FD command is sent by the client to the server. The server replies with AGREE_UNIX_FD or ERROR.

The NEGOTIATE_UNIX_FD command indicates that the client supports Unix file descriptor passing. This command may only be sent after the connection is authenticated, i.e. after OK was received by the client. This command may only be sent on transports that support Unix file descriptor passing.

On receiving NEGOTIATE_UNIX_FD the server must respond with either AGREE_UNIX_FD or ERROR. It shall respond the former if the transport chosen supports Unix file descriptor passing and the server supports this feature. It shall respond the latter if the transport does not support Unix file descriptor passing, the server does not support this feature, or the server decides not to enable file descriptor passing due to security or other reasons.

The AGREE_UNIX_FD command is sent by the server to the client.

The AGREE_UNIX_FD command indicates that the server supports Unix file descriptor passing. This command may only be sent after the connection is authenticated, and the client sent NEGOTIATE_UNIX_FD to enable Unix file descriptor passing. This command may only be sent on transports that support Unix file descriptor passing.

On receiving AGREE_UNIX_FD the client must respond with BEGIN, followed by its stream of messages, or by disconnecting. The server must not accept additional commands using this protocol after the BEGIN command has been received. Further communication will be a stream of D-Bus messages (optionally encrypted, as negotiated) rather than this protocol.

Future extensions to the authentication and negotiation protocol are possible. For that new commands may be introduced. If a client or server receives an unknown command it shall respond with ERROR and not consider this fatal. New commands may be introduced both before, and after authentication, i.e. both before and after the OK command.

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.

This section describes some authentication mechanisms that are often supported by practical D-Bus implementations. The D-Bus protocol also allows any other standard SASL mechanism, although implementations of D-Bus often do not.

Unix domain sockets can be either paths in the file system or on Linux kernels, they can be abstract which are similar to paths but do not show up in the file system.

When a socket is opened by the D-Bus library it truncates the path name right before the first trailing Nul byte. This is true for both normal paths and abstract paths. Note that this is a departure from previous versions of D-Bus that would create sockets with a fixed length path name. Names which were shorter than the fixed length would be padded by Nul bytes.

Unix domain sockets are not available on Windows. On all other platforms, they are the recommended transport for D-Bus, either used alone or in conjunction with systemd or launchd addresses.

Unix addresses that specify path or abstract are both listenable and connectable. Unix addresses that specify tmpdir or dir are only listenable: the corresponding connectable address will specify either path or abstract. Similarly, Unix addresses that specify runtime are only listenable, and the corresponding connectable address will specify path.

launchd is an open-source server management system that replaces init, inetd and cron on Apple Mac OS X versions 10.4 and above. It provides a common session bus address for each user and deprecates the X11-enabled D-Bus launcher on OSX.

launchd allocates a socket and provides it with the unix path through the DBUS_LAUNCHD_SESSION_BUS_SOCKET variable in launchd's environment. Every process spawned by launchd (or dbus-daemon, if it was started by launchd) can access it through its environment. Other processes can query for the launchd socket by executing: $ launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET This is normally done by the D-Bus client library so doesn't have to be done manually.

launchd is not available on Microsoft Windows.

launchd addresses are listenable and connectable.

systemd is an open-source server management system that replaces init and inetd on newer Linux systems. It supports socket activation. The D-Bus systemd transport is used to acquire socket activation file descriptors from systemd and use them as D-Bus transport when the current process is spawned by socket activation from it.

The systemd transport accepts only one or more Unix domain or TCP streams sockets passed in via socket activation. Using Unix domain sockets is strongly recommended.

The systemd transport is not available on non-Linux operating systems.

The systemd transport defines no parameter keys.

systemd addresses are listenable, but not connectable. The corresponding connectable address is the unix or tcp address of the socket.

The tcp transport provides TCP/IP based connections between clients located on the same or different hosts.

Similar to remote X11, the TCP transport has no integrity or confidentiality protection, so it should normally only be used across the local loopback interface, for example using an address like tcp:host=127.0.0.1 or tcp:host=localhost. In particular, configuring the well-known system bus or the well-known session bus to listen on a non-loopback TCP address is insecure.

On Windows and most Unix platforms, the TCP stack is unable to transfer credentials over a TCP connection, so the EXTERNAL authentication mechanism does not normally work for this transport (although the reference implementation of D-Bus is able to identify loopback TCPv4 connections on Windows by their port number, partially enabling the EXTERNAL mechanism). The DBUS_COOKIE_SHA1 mechanism is normally used instead.

Developers are sometimes tempted to use remote TCP as a debugging tool. However, if this functionality is left enabled in finished products, the result will be dangerously insecure. Instead of using remote TCP, developers should relay connections via Secure Shell or a similar protocol.

Remote TCP connections were historically sometimes used to share a single session bus between login sessions of the same user on different machines within a trusted local area network, in conjunction with unencrypted remote X11, a NFS-shared home directory and NIS (YP) authentication. This is insecure against an attacker on the same LAN and should be considered strongly deprecated; more specifically, it is insecure in the same ways and for the same reasons as unencrypted remote X11 and NFSv2/NFSv3. The D-Bus maintainers recommend using a separate session bus per (user, machine) pair, only accessible from within that machine.

All tcp addresses are listenable. tcp addresses in which both host and port are specified, and port is non-zero, are also connectable.

The nonce-tcp transport provides a modified TCP transport using a simple authentication mechanism, to ensure that only clients with read access to a certain location in the filesystem can connect to the server. The server writes a secret, the nonce, to a file and an incoming client connection is only accepted if the client sends the nonce right after the connect. The nonce mechanism requires no setup and is orthogonal to the higher-level authentication mechanisms described in the Authentication section.

The nonce-tcp transport is conceptually similar to a combination of the DBUS_COOKIE_SHA1 authentication mechanism and the tcp transport, and appears to have originally been implemented as a result of a misunderstanding of the SASL authentication mechanisms.

Like the ordinary tcp transport, the nonce-tcp transport has no integrity or confidentiality protection, so it should normally only be used across the local loopback interface, for example using an address like tcp:host=127.0.0.1 or tcp:host=localhost. Other uses are insecure. See the section called “TCP Sockets” for more information on situations where these transports have been used, and alternatives to these transports.

Implementations of D-Bus on Windows operating systems normally use a nonce-tcp transport via the local loopback interface. This is because the unix transport, which would otherwise be recommended, is not available on these operating systems.

On start, the server generates a random 16 byte nonce and writes it to a file in the user's temporary directory. The nonce file location is published as part of the server's D-Bus address using the "noncefile" key-value pair. After an accept, the server reads 16 bytes from the socket. If the read bytes do not match the nonce stored in the nonce file, the server MUST immediately drop the connection. If the nonce match the received byte sequence, the client is accepted and the transport behaves like an ordinary tcp transport.

After a successful connect to the server socket, the client MUST read the nonce from the file published by the server via the noncefile= key-value pair and send it over the socket. After that, the transport behaves like an ordinary tcp transport.

All nonce-tcp addresses are listenable. nonce-tcp addresses in which host, port and noncefile are all specified, and port is nonzero, are also connectable.

This transport forks off a process and connects its standard input and standard output with an anonymous Unix domain socket. This socket is then used for communication by the transport. This transport may be used to use out-of-process forwarder programs as basis for the D-Bus protocol.

The forked process will inherit the standard error output and process group from the parent process.

Executed subprocesses are not available on Windows.

unixexec addresses are connectable, but are not listenable.

The autolaunch transport provides a way for dbus clients to autodetect a running dbus session bus and to autolaunch a session bus if not present.

On Unix, autolaunch addresses are connectable, but not listenable.

On Windows, autolaunch addresses are both connectable and listenable.

The org.freedesktop.DBus.Peer interface has two methods:

          org.freedesktop.DBus.Peer.Ping ()
          org.freedesktop.DBus.Peer.GetMachineId (out STRING machine_uuid)
        

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 handles this method automatically.

On receipt of the METHOD_CALL message org.freedesktop.DBus.Peer.GetMachineId, an application should reply with a METHOD_RETURN containing a hex-encoded UUID representing the identity of the machine the process is running on. This UUID must be the same for all processes on a single system at least until that system next reboots. It should be the same across reboots if possible, but this is not always possible to implement and is not guaranteed. It does not matter which object path a GetMachineId is sent to. The reference implementation handles this method automatically.

The UUID is intended to be per-instance-of-the-operating-system, so may represent a virtual machine running on a hypervisor, rather than a physical machine. Basically if two processes see the same UUID, they should also see the same shared memory, UNIX domain sockets, process IDs, and other features that require a running OS kernel in common between the processes.

The UUID is often used where other programs might use a hostname. Hostnames can change without rebooting, however, or just be "localhost" - so the UUID is more robust.

the section called “UUIDs” explains the format of the UUID.

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.

the section called “Introspection Data Format” describes the format of this XML string.

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);
              org.freedesktop.DBus.Properties.GetAll (in STRING interface_name,
                                                      out DICT<STRING,VARIANT> props);
        

It is conventional to give D-Bus properties names consisting of capitalized words without punctuation ("CamelCase"), like member names. For instance, the GObject property connection-status or the Qt property connectionStatus could be represented on D-Bus as ConnectionStatus.

Strictly speaking, D-Bus property names are not required to follow the same naming restrictions as member names, but D-Bus property names that would not be valid member names (in particular, GObject-style dash-separated property names) can cause interoperability problems and should be avoided.

The available properties and whether they are writable can be determined by calling org.freedesktop.DBus.Introspectable.Introspect, see 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).

If org.freedesktop.DBus.Properties.GetAll is called with a valid interface name which contains no properties, an empty array should be returned. If it is called with a valid interface name for which some properties are not accessible to the caller (for example, due to per-property access control implemented in the service), those properties should be silently omitted from the result array. If org.freedesktop.DBus.Properties.Get is called for any such properties, an appropriate access control error should be returned.

If one or more properties change on an object, the org.freedesktop.DBus.Properties.PropertiesChanged signal may be emitted (this signal was added in 0.14):

              org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
                                                                 DICT<STRING,VARIANT> changed_properties,
                                                                 ARRAY<STRING> invalidated_properties);
        

where changed_properties is a dictionary containing the changed properties with the new values and invalidated_properties is an array of properties that changed but the value is not conveyed.

Whether the PropertiesChanged signal is supported can be determined by calling org.freedesktop.DBus.Introspectable.Introspect. Note that the signal may be supported for an object but it may differ how whether and how it is used on a per-property basis (for e.g. performance or security reasons). Each property (or the parent interface) must be annotated with the org.freedesktop.DBus.Property.EmitsChangedSignal annotation to convey this (usually the default value true is sufficient meaning that the annotation does not need to be used). See the section called “Introspection Data Format” for details on this annotation.

An API can optionally make use of this interface for one or more sub-trees of objects. The root of each sub-tree implements this interface so other applications can get all objects, interfaces and properties in a single method call. It is appropriate to use this interface if users of the tree of objects are expected to be interested in all interfaces of all objects in the tree; a more granular API should be used if users of the objects are expected to be interested in a small subset of the objects, a small subset of their interfaces, or both.

The method that applications can use to get all objects and properties is GetManagedObjects:

          org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties);
        

The return value of this method is a dict whose keys are object paths. All returned object paths are children of the object path implementing this interface, i.e. their object paths start with the ObjectManager's object path plus '/'.

Each value is a dict whose keys are interfaces names. Each value in this inner dict is the same dict that would be returned by the org.freedesktop.DBus.Properties.GetAll() method for that combination of object path and interface. If an interface has no properties, the empty dict is returned.

Changes are emitted using the following two signals:

          org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
                                                              DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties);
          org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
                                                                ARRAY<STRING> interfaces);
        

The InterfacesAdded signal is emitted when either a new object is added or when an existing object gains one or more interfaces. The InterfacesRemoved signal is emitted whenever an object is removed or it loses one or more interfaces. The second parameter of the InterfacesAdded signal contains a dict with the interfaces and properties (if any) that have been added to the given object path. Similarly, the second parameter of the InterfacesRemoved signal contains an array of the interfaces that were removed. Note that changes on properties on existing interfaces are not reported using this interface - an application should also monitor the existing PropertiesChanged signal on each object.

Applications SHOULD NOT export objects that are children of an object (directly or otherwise) implementing this interface but which are not returned in the reply from the GetManagedObjects() method of this interface on the given object.

The intent of the ObjectManager interface is to make it easy to write a robust client implementation. The trivial client implementation only needs to make two method calls:

          org.freedesktop.DBus.AddMatch (bus_proxy,
                                         "type='signal',sender='org.example.App2',path_namespace='/org/example/App2'");
          objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
        

on the message bus and the remote application's ObjectManager, respectively. Whenever a new remote object is created (or an existing object gains a new interface), the InterfacesAdded signal is emitted, and since this signal contains all properties for the interfaces, no calls to the org.freedesktop.Properties interface on the remote object are needed. Additionally, since the initial AddMatch() rule already includes signal messages from the newly created child object, no new AddMatch() call is needed.

The org.freedesktop.DBus.ObjectManager interface was added in version 0.17 of the D-Bus specification.

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 "com.example.TextEditor1". 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, with an object located at /org/freedesktop/DBus that implements the org.freedesktop.DBus interface. This service allows applications to make administrative requests of the bus itself. 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 "com.example.TextEditor1", and the second will be queued as a possible owner of that name. When the first exits, the second will take over.

Applications may send unicast messages to a specific recipient or to the message bus itself, or broadcast messages to all interested recipients. See the section called “Message Bus Message Routing” for details.

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. the section called “Bus names” describes the format of a valid name. These names can be released again using the org.freedesktop.DBus.ReleaseName message.

Messages may have a DESTINATION field (see the section called “Header Fields”), resulting in a unicast message. If the DESTINATION field is present, it specifies a message recipient by name. Method calls and replies normally specify this field. The message bus must send messages (of any type) with the DESTINATION field set to the specified recipient, regardless of whether the recipient has set up a match rule matching the message.

When the message bus receives a signal, if the DESTINATION field is absent, it is considered to be a broadcast signal, and is sent to all applications with message matching rules that match the message. Most signal messages are broadcasts, and no other message types currently defined in this specification may be broadcast.

Unicast signal messages (those with a DESTINATION field) are not commonly used, but they are treated like any unicast message: they are delivered to the specified receipient, regardless of its match rules. One use for unicast signals is to avoid a race condition in which a signal is emitted before the intended recipient can call the section called “org.freedesktop.DBus.AddMatch” to receive that signal: if the signal is sent directly to that recipient using a unicast message, it does not need to add a match rule at all, and there is no race condition. Another use for unicast signals, on message buses whose security policy prevents eavesdropping, is to send sensitive information which should only be visible to one recipient.

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 implementations may impose a security policy which prevents certain messages from being sent or received. When a method call message cannot be sent or received due to a security policy, the message bus should send an error reply, unless the original message had the NO_REPLY flag.

The message bus can start applications on behalf of other applications. This is referred to as service activation or activation. An application that can be started in this way is called a service or an activatable service.

Starting a service should be read as synonymous with service activation.

In D-Bus, service activation is normally done by auto-starting. In auto-starting, applications send a message to a particular well-known name, such as com.example.TextEditor1, without specifying the NO_AUTO_START flag in the message header. If no application on the bus owns the requested name, but the bus daemon does know how to start an activatable service for that name, then the bus daemon will start that service, wait for it to request that name, and deliver the message to it.

It is also possible for applications to send an explicit request to start a service: this is another form of activation, distinct from auto-starting. See the section called “org.freedesktop.DBus.StartServiceByName” for details.

In either case, this implies a contract documented along with the name com.example.TextEditor1 for which object 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 the section called “Well-known Message Bus Instances”.

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 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.

On the well-known system bus, the name of a service description file must be its well-known name plus .service, for instance com.example.ConfigurationDatabase1.service.

On the well-known session bus, services should follow the same service description file naming convention as on the system bus, but for backwards compatibility they are not required to do so.

[FIXME the file format should be much better specified than "similar to .desktop entries" esp. since desktop entries are already badly-specified. ;-)] These sections from the specification apply to service files as well:

Service description files must contain a D-BUS Service group with at least the keys Name (the well-known name of the service) and Exec (the command to be executed).

            # Sample service description file
            [D-BUS Service]
            Name=com.example.ConfigurationDatabase1
            Exec=/usr/bin/sample-configd
          

Additionally, service description files for the well-known system bus on Unix must contain a User key, whose value is the name of a user account (e.g. root). The system service will be run as that user.

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.

On the well-known system bus, it is not possible for two .service files in the same directory to offer the same service, because they are constrained to have names that match the service name.

On the well-known session bus, if two .service files in the same directory offer the same service name, the result is undefined. Distributors should avoid this situation, for instance by naming session services' .service files according to their service name.

If two .service files in different directories offer the same service name, the one in the higher-priority directory is used: for instance, on the system bus, .service files in /usr/local/share/dbus-1/system-services take precedence over those in /usr/share/dbus-1/system-services.

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 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.]

Two standard message bus instances are defined here, along with how to locate them and where their service files live.

The special message bus name org.freedesktop.DBus responds to a number of additional messages at the object path /org/freedesktop/DBus. That object path is also used when emitting the the section called “org.freedesktop.DBus.NameOwnerChanged” signal.

For historical reasons, some of the methods in the org.freedesktop.DBus interface are available on multiple object paths. Message bus implementations should accept method calls that were added before specification version 0.26 on any object path. Message bus implementations should not accept newer method calls on unexpected object paths, and as a security hardening measure, older method calls that are security-sensitive may be rejected with the error org.freedesktop.DBus.Error.AccessDenied when called on an unexpected object path. Client software should send all method calls to /org/freedesktop/DBus instead of relying on this.

In addition to the method calls listed below, the message bus should implement the standard Introspectable, Properties and Peer interfaces (see the section called “Standard Interfaces”). Support for the Properties and Peer interfaces was added in version 1.11.x of the reference implementation of the message bus.

            STRING Hello ()
          

            UINT32 RequestName (in STRING name, in UINT32 flags)
          

            UINT32 ReleaseName (in STRING name)
          

            ARRAY of STRING ListQueuedOwners (in STRING name)
          

            ARRAY of STRING ListNames ()
          

            ARRAY of STRING ListActivatableNames ()
          

            BOOLEAN NameHasOwner (in STRING name)
          

            NameOwnerChanged (STRING name, STRING old_owner, STRING new_owner)
          

            NameLost (STRING name)
          

            NameAcquired (STRING name)
          

            UINT32 StartServiceByName (in STRING name, in UINT32 flags)
          

            UpdateActivationEnvironment (in ARRAY of DICT<STRING,STRING> environment)
          

            STRING GetNameOwner (in STRING name)
          

            UINT32 GetConnectionUnixUser (in STRING bus_name)
          

            UINT32 GetConnectionUnixProcessID (in STRING bus_name)
          

            DICT<STRING,VARIANT> GetConnectionCredentials (in STRING bus_name)
          

            ARRAY of BYTE GetAdtAuditSessionData (in STRING bus_name)
          

            ARRAY of BYTE GetConnectionSELinuxSecurityContext (in STRING bus_name)
          

            AddMatch (in STRING rule)
          

            RemoveMatch (in STRING rule)
          

            GetId (out STRING id)
          

            BecomeMonitor (in ARRAY of STRING rule, in UINT32 flags)
          

The special message bus name org.freedesktop.DBus exports several properties (see the section called “org.freedesktop.DBus.Properties”) on the object path /org/freedesktop/DBus.

            Read-only constant ARRAY of STRING Features
          

            Read-only constant ARRAY of STRING Interfaces