DBus Overview

Object Paths

D-Bus objects are identified within an application via their object path. The object path intentionally looks just like a standard Unix file system path. The primary difference is that the path may contain only numbers, letters, underscores, and the / character.

From a functional standpoint, the primary purpose of object paths is simply to be a unique identifier for an object. The "hierarchy" implied the path structure is almost purely conventional. Applications with a naturally hierarchical structure will likely take advantage of this feature while others may choose to ignore it completely.

Interfaces

D-Bus interfaces define the methods and signals supported by D-Bus objects. In order to make use of a D-Bus interface it must be known to remote users. This interface definition may be hard coded into an application or may be queried at run time through the D-Bus introspection mechanism. Although technically optional, most D-Bus implementations automatically provide introspection support for the objects they export.

The naming convention for D-Bus interfaces is similar to that of well-known bus names. To reduce the chance of name clashes, the accepted convention is to prefix the interface name with a reversed DNS domain name. For example, the standard "Introspection" interface is "org.freedesktop.DBus.Introspectable"

The constraints on methods and signals names contained within D-Bus interfaces are similar to those employed by many popular programming languages. They must begin with a letter and may consist of only letters, numbers, and underscores.

Each method and signal explicitly defines the number and types of arguments they accept. These are encoded as D-Bus Signature strings.

Signature Strings

D-Bus uses a string-based type encoding mechanism called Signatures to describe the number and types of arguments requried by methods and signals. Signatures are used for interface declaration/documentation, data marshalling, and validity checking. Their string encoding uses a simple, though expressive, format and a basic understanding of it is required for effective D-Bus use. The table below lists the fundamental types and their encoding characters.

No spacing is allowed within signature strings. When defining signatures for multi-argument methods and signatures, the types of each argument are concatenated into a single string. For example, the signature for a method that accepts two integers followed by a string would be "iis".

Methods

D-Bus methods may accept any number of arguments and may return any number of values, including none. When method calls specify no return value, a "method return" message is still sent to the calling application. This allows applications using the remote API to know that the remote method invocation has completed even if no useful result is returned.

The only case in which a return message is not sent in acknowledgement to a D-Bus method call is if the "no reply expected" flag is sent as part of the method invocation. This is an optional D-Bus implementation feature that, if supported, may be used to suppress the generation of the reply message.

The signature strings for method argument lists and method return values may contain multiple types. For each argument accepted and each value returned, the type of the argument/return value is simply appended, in order, to the signature string. For example, a method accepting two unsigned 32-bit integers and returning two strings would use "uu" for the argument signature and "ss" for the return value signature. If the method accepts no arguments or returns no values, the signatures for those attributes are empty strings.

Signals

D-Bus signals provide a 1-to-many, publish-subscribe mechanism. Similar to method return values, D-Bus signals may contain an arbitrary ammount of data. Unlike methods however, signals are entirely asynchronous and may be emitted by D-Bus objects at any time.

By default, signals emitted from D-Bus objects will not be sent to any clients. To receive signals, client applications must explicitly register their interest in the specific signals emitted by D-Bus objects.

Bus Names

There are two types of bus names: unique and well-known. Unique bus names are assigned by the bus to each client connection. They begin with a :, and they are guaranteed never to be reused during the life of the bus. Unlike process ids which can roll-over and be reused, unique bus names are guaranteed to be truly unique.

D-Bus clients may request additional, "well-known" bus names in order to offer their services under names that are agreed upon by convention. This allows applications to easily find the offered services at a known location. For example, the Gnome Network Manager offers its services on the well-known bus name of org.freedesktop.NetworkManager to prevent prospective users from needing to determine the network manager’s unique bus name.

Well known bus names have essentially the same naming requirements as DNS domain names (though bus names may include the _ character). As the whole point of "well-known" bus names is simplicity of resource naming, the accepted convention for avoiding unintentional name clashes is to prefix the well known bus names with a reversed DNS domain name: org.frobozz.Zork

D-Bus imposes a simple arbitration mechanism on the ownership of bus names. If a client requests an unused name, it is immediately granted. If the name is currently owned, however, the client has two options for obtaining the name. It can attempt to steal ownership or it can place itself in a queue for eventual ownership.

To steal ownership, two conditions must be met. The application currently owning the name must have informed the bus that it is willing to relinquish ownership of the name and the stealing application must set the flag enabling the ownership request to steal the name from the owning application. If both of these conditions are not met, the request for the name will simply fail and return an error code stating that the name is currently unavailable.

To queue for ownership, the requesting application sets a flag in the ownership request indicating that if the name is not currently available, the request should be queued. If, at some point in the future, ownership is granted to the client, it will be informed of this fact by way of a signal.

Message Routing

Messages are routed to client connections by destination address and match rules. Destination address routing is used when a message’s destination parameter contains a unique or well-known bus name. This is typically the case with method call and return messages which inherently require 1-to-1 communication. Signals, on the other hand, are broadcast messages with no specific destination. For these, client applications must register match rules in order to receive the signals they are interested in.

Although signal registration is the most common use for message matching rules, DBus message matching rules can be used to request delivery of any messages transmitted over the bus; including the method call and return messages between arbitrary bus clients. The messages delivered via match rules are always copies so it is not possible to use this mechanism to redirect messages away from their intended targets.

Message match rules are set via the org.freedesktop.DBus.AddMatch method and are formatted as a series of comma-separated, key=value paris contained within a single string. Excluded keys indicate wildcard matches that match every message. If all components of the match rule match a message, it will be delivered to the requesting application. The following table provides a terse description of the keys and values that may be specified in match rules. For full details, please refer to the DBus specification.

Bus Addresses

Bus addresses specify the connection mechanism (TCP, Unix socket, etc) and any extra information required for successful connection and authentication. The format for bus addresses is a transport name followed by a colon followed by an optional, comma-separated set of key=value pairs. Multiple addresses may be specified in the same string, separated by semicolons.