D-Bus API Design Guidelines

Each D-Bus method call is a round trip from a client program to a service and back again, which is expensive — taking on the order of a millisecond. One of the top priorities in D-Bus API design is to minimize the number of round trips needed by clients. This can be achieved by a combination of providing specific convenience APIs and designing APIs which operate on large data sets in a single call, rather than requiring as many calls as elements in the data set.

Consider an address book API, com.example.MyService1.AddressBook. It might have an AddContact(ss) → (u)) method to add a contact (taking name and e-mail address parameters and returning a unique contact ID), and a RemoveContact(u)) method to remove one by ID. In the normal case of operating on single contacts in the address book, these calls are optimal. However, if the user wants to import a list of contacts, or delete multiple contacts simultaneously, one call has to be made per contact — this could take a long time for large contact lists.

Instead of the AddContact and RemoveContact methods, the interface could have an UpdateContacts(a(ss)au) → (au)) method, which takes an array of structs containing the new contacts’ details, and an array of IDs of the contacts to delete, and returns an array of IDs for the new contacts. This reduces the number of round trips needed to one.

Adding convenience APIs to replace a series of common method calls with a single method call specifically for that task is best done after the API has been profiled and bottlenecks identified, otherwise it could lead to premature optimization. One area where convenience methods can typically be added is during initialization of a client, where multiple method calls are needed to establish its state with the service.

D-Bus’ type system is similar to Python’s, but with a terser syntax which may be unfamiliar to C developers. The key to using the type system effectively is to expose as much structure in types as possible. In particular, sending structured strings over D-Bus should be avoided, as they need to be built and parsed; both are complex operations which are prone to bugs.

For APIs being used in constrained situations, enumerated values should be transmitted as unsigned integers. For APIs which need to be extended by third parties or which are used in more loosely coupled systems, enumerated values should be strings in some defined format.

Transmitting values as integers means string parsing and matching can be avoided, the messages are more compact, and typos can be more easily avoided by developers (if, for example, C enums are used in the implementation).

Transmitting values as strings means additional values can be defined by third parties without fear of conflicting over integer values; for instance by using the same reverse-domain-name namespacing as D-Bus interfaces.

In both cases, the interface documentation should describe the meaning of each value. It should state whether the type can be extended in future and, if so, how the service and client should handle unrecognized values — typically by considering them equal to an ‘unknown’ or ‘failure’ value. Conventionally, zero is used as the ‘unknown’ value.

<!--
    Status:

    Status of the object.
    Valid statuses: ‘unknown’, ‘ready’, ‘complete’.
-->
<property name="Status" type="s" access="read" />

<!--
    Status:

    Status of the object.
    Valid statuses: 0 = Unknown, 1 = Ready, 2 = Complete.
    Unrecognized statuses should be considered equal to Unknown.
-->
<property name="Status" type="u" access="read" />

Similarly, enumerated values should be used instead of booleans, as they allow extra values to be added in future, and there is no ambiguity about the sense of the boolean value.

<!--
   MoveAddressBook:
   @direction: %TRUE to move it up in the list, %FALSE to move it down

   Move this address book up or down in the user’s list of address books.
   Higher address books have their contacts displayed first in search
   results.
-->
<method name="MoveAddressBook">
  <arg name="direction" type="b" direction="in" />
</method>

<!--
   MoveAddressBook:
   @direction: 0 = Move it up in the list, 1 = Move it down

   Move this address book up or down in the user’s list of address books.
   Higher address books have their contacts displayed first in search
   results.

   Unrecognized enum values for @direction will result in the address book
   not moving.
-->
<method name="MoveAddressBook">
  <arg name="direction" type="u" direction="in" />
</method>

Enumerated values should also be used instead of human readable strings, which should not be sent over the bus if possible. The service and client could be running in different locales, and hence interpret any human readable strings differently, or present them to the user in the wrong language. Transmit an enumerated value and convert it to a human readable string in the client.

In situations where a service has received a human readable string from somewhere else, it should pass it on unmodified to the client, ideally with its locale alongside. Passing human readable information to a client is better than passing nothing.

<!--
   ProgressNotification:
   @progress_message: Human readable progress message string.

   Emitted whenever significant progress is made with some example
   operation. The @progress_message can be displayed in a UI dialogue to
   please the user.
-->
<signal name="ProgressNotification">
  <arg name="progress_message" type="s" />
</method>

<!--
   ProgressNotification:
   @progress_state: 0 = Preparing, 1 = In progress, 2 = Finished

   Emitted whenever significant progress is made with some example
   operation. The @progress_state is typically converted to a human readable
   string and presented to the user. Unrecognized @progress_state values
   should be treated as state 1, in progress.
-->
<signal name="ProgressNotification">
  <arg name="progress_state" type="u" />
</method>

D-Bus has none of the problems of signed versus unsigned integers which C has (specifically, it does not do implicit sign conversion), so integer types should always be chosen to be an appropriate size and signedness for the data they could possibly contain. Typically, unsigned values are more frequently needed than signed values.

Structures can be used almost anywhere in a D-Bus type, and arrays of structures are particularly useful. Structures should be used wherever data fields are related. Note, however, that structures are not extensible in future, so always consider Extensibility.

<!--
   AddContacts:
   @names: Array of contact names to add.
   @emails: Corresponding array of contact e-mail addresses.
   @ids: Returned array of the IDs of the new contacts. This will be the
     same length as @names.

   Add zero or more contacts to the address book, using their names and
   e-mail addresses. @names and @emails must be the same length.
-->
<method name="AddContacts">
  <arg name="names" type="as" direction="in" />
  <arg name="emails" type="as" direction="in" />
  <arg name="ids" type="au" direction="out" />
</method>

<!--
   AddContacts:
   @details: Array of (contact name, contact e-mail address) to add.
   @ids: Returned array of the IDs of the new contacts. This will be the
     same length as @details.

   Add zero or more contacts to the address book, using their names and
   e-mail addresses.
-->
<method name="AddContacts">
  <arg name="details" type="a(ss)" direction="in" />
  <arg name="ids" type="au" direction="out" />
</method>

Note that D-Bus arrays are automatically transmitted with their length, so there is no need to null-terminate them or encode their length separately.

Some D-Bus APIs have very well-defined use cases, and will never need extension. Others are used in more loosely coupled systems which may change over time, and hence should be designed to be extensible from the beginning without the need to break API in future. This is a trade off between having a more complex API, and being able to easily extend it in future.

The key tool for extensibility in D-Bus is a{sv}, the dictionary mapping strings to variants. If well-defined namespaced strings are used as the dictionary keys, arbitrary D-Bus peers can add whatever information they need into the dictionary. Any other peer which understands it can query and retrieve the information; other peers will ignore it.

The canonical example of an extensible API using a{sv} is Telepathy. It uses a{sv} values as the final element in structures to allow them to be extended in future.

A secondary tool is the use of flag fields in method calls. The set of accepted flags is entirely under the control of the interface designer and, as with enumerated types, can be extended in future without breaking API. Adding more flags allows the functionality of the method call to be tweaked.

D-Bus method calls are explicitly asynchronous due to the latency inherent in IPC. This means that peers should not block on receiving a reply from a method call; they should schedule other work (in a main loop) and handle the reply when it is received. Even though method replies may take a while, the caller is guaranteed to receive exactly one reply eventually. This reply could be the return value from the method, an error from the method, or an error from the D-Bus daemon indicating the service failed in some way (e.g. due to crashing).

Because of this, service implementations should be careful to always reply exactly once to each method call. Replying at the end of a long-running operation is correct — the client will patiently wait until the operation has finished and the reply is received.

Note that D-Bus client bindings may implement synthetic timeouts of several tens of seconds, unless explicitly disabled for a call. For very long-running operations, you should disable the client bindings’ timeout and make it clear in the client’s UI that the application has not frozen and is simply running a long operation.

An anti-pattern to avoid in this situation is to start a long-running operation when a method call is received, then to never reply to the method call and instead notify the client of completion of the operation via a signal. This approach is incorrect as signal emissions do not have a one-to-one relationship with method calls — the signal could theoretically be emitted multiple times, or never, which the client would not be able to handle.

Similarly, use a D-Bus error reply to signify failure of an operation triggered by a method call, rather than using a custom error code in the method’s reply. This means that a reply always indicates success, and an error always indicates failure — rather than a reply indicating either depending on its parameters, and having to return dummy values in the other parameters. Using D-Bus error replies also means such failures can be highlighted in debugging tools, simplifying debugging.

Clients should handle all possible standard and documented D-Bus errors for each method call. IPC inherently has more potential failures than normal C function calls, and clients should be prepared to handle all of them gracefully.

Use standard D-Bus interfaces where possible.

All D-Bus names, from service names through to method parameters, follow a set of conventions. Following these conventions makes APIs more natural to use and consistent with all other services on the system.

Services use reverse-domain-name notation, based on the domain name of the project providing the service (all in lower case), plus a unique name for the service (in camel case).

Almost all names use camel case with no underscores, as in the examples below. Method and signal parameters are an exception, using lowercase_with_underscores. Type information is never encoded in the parameter name (i.e. not Hungarian notation).

See also: API versioning.

XML comments containing documentation in the gtk-doc format is the recommended format for use with gdbus-codegen. Using gdbus-codegen, these comments can be extracted, converted to DocBook format and included in the project’s API manual. For example:

<!--
    org.freedesktop.DBus.Properties:
    @short_description: Standard property getter/setter interface

    Interface for all objects which expose properties on the bus, allowing
    those properties to be got, set, and signals emitted to notify of changes
    to the property values.
-->
<interface name="org.freedesktop.DBus.Properties">
  <!--
      Get:
      @interface_name: Name of the interface the property is defined on.
      @property_name: Name of the property to get.
      @value: Property value, wrapped in a variant.

      Retrieves the value of the property at @property_name on
      @interface_name on this object. If @interface_name is an empty string,
      all interfaces will be searched for @property_name; if multiple
      properties match, the result is undefined.

      If @interface_name or @property_name do not exist, a
      #org.freedesktop.DBus.Error.InvalidArgs error is returned.
  -->
  <method name="Get">
    <arg type="s" name="interface_name" direction="in"/>
    <arg type="s" name="property_name" direction="in"/>
    <arg type="v" name="value" direction="out"/>
  </method>

  <!--
      PropertiesChanged:
      @interface_name: Name of the interface the properties changed on.
      @changed_properties: Map of property name to updated value for the
        changed properties.
      @invalidated_properties: List of names of other properties which have
        changed, but whose updated values are not notified.

      Emitted when one or more properties change values on @interface_name.
      A property may be listed in @changed_properties or
      @invalidated_properties depending on whether the service wants to
      broadcast the property’s new value. If a value is large or infrequently
      used, the service might not want to broadcast it, and will wait for
      clients to request it instead.
  -->
  <signal name="PropertiesChanged">
    <arg type="s" name="interface_name"/>
    <arg type="a{sv}" name="changed_properties"/>
    <arg type="as" name="invalidated_properties"/>
  </signal>
</interface>

Documentation can also be added as annotation elements in the XML. This format is also supported by gdbus-codegen, but gtk-doc comments are preferred. For example:

<interface name="org.freedesktop.DBus.Properties">
  <annotation name="org.gtk.GDBus.DocString" value="Interface for all
    objects which expose properties on the bus, allowing those properties to
    be got, set, and signals emitted to notify of changes to the property
    values."/>
  <annotation name="org.gtk.GDBus.DocString.Short"
    value="Standard property getter/setter interface"/>

  <method name="Get">
    <annotation name="org.gtk.GDBus.DocString" value="Retrieves the value of
      the property at @property_name on @interface_name on this object. If
      @interface_name is an empty string, all interfaces will be searched
      for @property_name; if multiple properties match, the result is
      undefined.

      If @interface_name or @property_name do not exist, a
      #org.freedesktop.DBus.Error.InvalidArgs error is returned."/>

    <arg type="s" name="interface_name" direction="in">
      <annotation name="org.gtk.GDBus.DocString"
        value="Name of the interface the property is defined on."/>
    </arg>

    <arg type="s" name="property_name" direction="in">
      <annotation name="org.gtk.GDBus.DocString"
        value="Name of the property to get."/>
    </arg>

    <arg type="v" name="value" direction="out">
      <annotation name="org.gtk.GDBus.DocString"
        value="Property value, wrapped in a variant."/>
    </arg>
  </method>

  <signal name="PropertiesChanged">
    <annotation name="org.gtk.GDBus.DocString" value="Emitted when one or
      more properties change values on @interface_name. A property may be
      listed in @changed_properties or @invalidated_properties depending on
      whether the service wants to broadcast the property’s new value. If a
      value is large or infrequently used, the service might not want to
      broadcast it, and will wait for clients to request it instead."/>

    <arg type="s" name="interface_name">
      <annotation name="org.gtk.GDBus.DocString"
        value="Name of the interface the properties changed on."/>
    </arg>

    <arg type="a{sv}" name="changed_properties">
      <annotation name="org.gtk.GDBus.DocString"
        value="Map of property name to updated value for the changed
          properties."/>
    </arg>

    <arg type="as" name="invalidated_properties">
      <annotation name="org.gtk.GDBus.DocString"
        value="List of names of other properties which have changed, but
          whose updated values are not notified."/>
    </arg>
  </signal>
</interface>

dbus-monitor is a core D-Bus tool, and allows eavesdropping on the session or system bus, printing all messages it sees. The messages may be filtered using a standard D-Bus match rule to make the stream more manageable.

Previous versions of D-Bus have required the security policy for the system bus to be manually relaxed to allow eavesdropping on all messages. This meant that debugging it was difficult and insecure. The latest versions of D-Bus add support for monitor-only connections for the root user, which means that dbus-monitor can be run as root to painlessly monitor all messages on the system bus without modifying its security policy.

Bustle is a graphical version of dbus-monitor, with a UI focused on profiling D-Bus performance by plotting messages on a timeline. It is ideal for finding bottlenecks in IPC performance between a service and client.

D-Feet is an introspection tool for D-Bus, which displays all peers on the bus graphically, with their objects, interfaces, methods, signals and properties listed for examination. It is useful for debugging all kinds of issues related to presence of services on the bus and the objects they expose.