2.3 Knowing the details of D-Bus services.

D-Bus services publish their interfaces. This can be retrieved and analyzed during runtime, in order to understand the used implementation.

The resulting introspection data are in XML format. The root introspection element is always a node element. It might have a name attribute, which denotes the (absolute) object path an interface is introspected.

The root node element may have node and interface children. A child node element must have a name attribute, this case it is the relative object path to the root node element.

An interface element has just one attribute, name, which is the full name of that interface. The default interface ‘org.freedesktop.DBus.Introspectable’ is always present. Example:

<node name="/org/bluez">
  <interface name="org.freedesktop.DBus.Introspectable">
    …
  </interface>
  <interface name="org.bluez.Manager">
    …
  </interface>
  <interface name="org.bluez.Database">
    …
  </interface>
  <interface name="org.bluez.Security">
    …
  </interface>
  <node name="service_audio"/>
  <node name="service_input"/>
  <node name="service_network"/>
  <node name="service_serial"/>
</node>

Children of an interface element can be method, signal and property elements. A method element stands for a D-Bus method of the surrounding interface. The element itself has a name attribute, showing the method name. Children elements arg stand for the arguments of a method. Example:

<method name="ResolveHostName">
  <arg name="interface" type="i" direction="in"/>
  <arg name="protocol" type="i" direction="in"/>
  <arg name="name" type="s" direction="in"/>
  <arg name="aprotocol" type="i" direction="in"/>
  <arg name="flags" type="u" direction="in"/>
  <arg name="interface" type="i" direction="out"/>
  <arg name="protocol" type="i" direction="out"/>
  <arg name="name" type="s" direction="out"/>
  <arg name="aprotocol" type="i" direction="out"/>
  <arg name="address" type="s" direction="out"/>
  <arg name="flags" type="u" direction="out"/>
</method>

arg elements can have the attributes name, type and direction. The name attribute is optional. The type attribute stands for the signature of the argument in D-Bus. For a discussion of D-Bus types and their Lisp representation see Mapping Lisp types and D-Bus types..¹ The direction attribute of an arg element can be only ‘in’ or ‘out’; in case it is omitted, it defaults to ‘in’.

A signal element of an interface has a similar structure. The direction attribute of an arg child element can be only ‘out’ here; which is also the default value. Example:

<signal name="StateChanged">
  <arg name="state" type="i"/>
  <arg name="error" type="s"/>
</signal>

A property element has no arg child element. It just has the attributes name, type and access, which are all mandatory. The access attribute allows the values ‘readwrite’, ‘read’, and ‘write’. Example:

<property name="Status" type="u" direction="read"/>

annotation elements can be children of interface, method, signal, and property elements. Unlike properties, which can change their values during lifetime of a D-Bus object, annotations are static. Often they are used for code generators of D-Bus language bindings. Example:

<annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>

Annotations have just name and value attributes, both must be strings.

Function: dbus-introspect bus service path ¶

This function returns all interfaces and sub-nodes of service, registered at object path path at bus bus.

bus must be either the keyword :system or the keyword :session. service must be a known service name, and path must be a valid object path. The last two parameters are strings. The result, the introspection data, is a string in XML format. Example:

(dbus-introspect
 :system "org.freedesktop.Hal"
 "/org/freedesktop/Hal/devices/computer")

⇒ "<!DOCTYPE node PUBLIC
    "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
    "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
    <node>
      <interface name="org.freedesktop.Hal.Device">
        <method name="GetAllProperties">
          <arg name="properties" direction="out" type="a{sv}"/>
        </method>
        …
        <signal name="PropertyModified">
          <arg name="num_updates" type="i"/>
          <arg name="updates" type="a(sbb)"/>
        </signal>
      </interface>
      …
    </node>"

This example informs us, that the service ‘org.freedesktop.Hal’ at object path ‘/org/freedesktop/Hal/devices/computer’ offers the interface ‘org.freedesktop.Hal.Device’ (and 2 other interfaces not documented here). This interface contains the method ‘GetAllProperties’, which needs no input parameters, but returns as output parameter an array of dictionary entries (key-value pairs). Every dictionary entry has a string as key, and a variant as value.

The interface offers also a signal, which returns 2 parameters: an integer, and an array consisting of elements which are a struct of a string and 2 boolean values.²

Function: dbus-introspect-xml bus service path ¶

This function serves a similar purpose to the function dbus-introspect. The returned value is a parsed XML tree, which can be used for further analysis. Example:

(dbus-introspect-xml
 :session "org.freedesktop.xesam.searcher"
 "/org/freedesktop/xesam/searcher/main")

⇒ (node ((name . "/org/freedesktop/xesam/searcher/main"))
    (interface ((name . "org.freedesktop.xesam.Search"))
      (method ((name . "GetHitData"))
        (arg ((name . "search")
              (type . "s")
              (direction . "in")))
        (arg ((name . "hit_ids")
              (type . "au")
              (direction . "in")))
        (arg ((name . "fields")
              (type . "as")
              (direction . "in")))
        (arg ((name . "hit_data")
              (type . "aav")
              (direction . "out"))))
      …
      (signal ((name . "HitsAdded"))
        (arg ((name . "search") (type . "s")))
        (arg ((name . "count") (type . "u")))))
    …)

Function: dbus-introspect-get-attribute object attribute ¶

This function returns the attribute value of a D-Bus introspection object. The value of object can be any subtree of a parsed XML tree as retrieved with dbus-introspect-xml. attribute must be a string according to the attribute names in the D-Bus specification. Example:

(dbus-introspect-get-attribute
 (dbus-introspect-xml
  :system "org.freedesktop.SystemToolsBackends"
  "/org/freedesktop/SystemToolsBackends/UsersConfig")
 "name")

⇒ "/org/freedesktop/SystemToolsBackends/UsersConfig"

If object has no attribute, the function returns nil.