dbus: Introspection
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 
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 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 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
in the HAL specification
(http://people.freedesktop.org/~dkukawka/hal-spec-git/hal-spec.html#interfaces).
Info Catalog
dbus: Bus names
dbus: Inspection
dbus: Nodes and Interfaces