Next: Nodes and Interfaces, Previous: Bus names, Up: Inspection

### 2.2 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 Type Conversion.1 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 langugae 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 symbol `:system` or the symbol `: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.2

— Function: dbus-introspect-xml bus service path

> This function has the same intention as 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

> It returns the attribute value of a D-Bus introspection object. object can be every 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`.

#### Footnotes

[1] D-Bus signatures are explained in the D-Bus specification http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures.

[2] The interfaces of the service ‘`org.freedesktop.Hal`’ are described at http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces.