Video game tester jobs online

Dbus Tutorial Introspection Figuring Out The Rules

Dbus Tutorial Introspection Figuring Out The Rules

Introduction
Introspection
Network Manager 
Create a Service
Gobject Introspection


Last time, we discussed what to use dbus for and the basics of structuring a dbus command. We went over how to structure the grammar of a command so it makes sense (mapping the destination, path, method, and message elements), and we went over the syntax (stringing together those elements in a coherent way).

This lesson is about figuring out what methods are available and how to use them.


Introspection

dbus is introspectable. That means you can ask dbus what commands are available.

Heres an introspection example. You can see that the return is XML wrapped inside a string (you dont need to read it all):

$ dbus-send --system --print-reply --dest=org.freedesktop.NetworkManager /org/freedesktop/NetworkManager org.freedesktop.DBus.Introspectable.Introspect
method return sender=:1.4 -> dest=:1.441 reply_serial=2
 string "

<node>
 <interface name="org.freedesktop.DBus.Introspectable">
 <method name="Introspect">
 <arg direction="out" name="data" type="s">
 </arg></method>
 <interface name="org.freedesktop.DBus.Properties">
 <method name="Get">
 <arg direction="in" name="interface" type="s">
 <arg direction="in" name="propname" type="s">
 <arg direction="out" name="value" type="v">
 </arg></arg></arg></method>
 <method name="Set">
 <arg direction="in" name="interface" type="s">
 <arg direction="in" name="propname" type="s">
 <arg direction="in" name="value" type="v">
 </arg></arg></arg></method>
 <method name="GetAll">
 <arg direction="in" name="interface" type="s">
 <arg direction="out" name="props" type="a{sv}">
 </arg></arg></method>
 </interface>
 <interface name="org.freedesktop.NetworkManager">
 <method name="state">
 <arg direction="out" name="state" type="u">
 </arg></method>
 <method name="SetLogging">
 <arg direction="in" name="level" type="s">
 <arg direction="in" name="domains" type="s">
 </arg></arg></method>
 <method name="GetPermissions">
 <arg direction="out" name="permissions" type="a{ss}">
 </arg></method>
 <method name="Enable">
 <arg direction="in" name="enable" type="b">
 </arg></method>
 <method name="Sleep">
 <arg direction="in" name="sleep" type="b">
 </arg></method>
 <method name="DeactivateConnection">
 <arg direction="in" name="active_connection" type="o">
 </arg></method>
 <method name="AddAndActivateConnection">
 <arg direction="in" name="connection" type="a{sa{sv}}">
 <arg direction="in" name="device" type="o">
 <arg direction="in" name="specific_object" type="o">
 <arg direction="out" name="path" type="o">
 <arg direction="out" name="active_connection" type="o">
 </arg></arg></arg></arg></arg></method>
 <method name="ActivateConnection">
 <arg direction="in" name="connection" type="o">
 <arg direction="in" name="device" type="o">
 <arg direction="in" name="specific_object" type="o">
 <arg direction="out" name="active_connection" type="o">
 </arg></arg></arg></arg></method>
 <method name="GetDeviceByIpIface">
 <arg direction="in" name="iface" type="s">
 <arg direction="out" name="device" type="o">
 </arg></arg><<method>
 <method name="GetDevices">
 <arg direction="out" name="devices" type="ao">
 </arg></method>
 <signal name="DeviceRemoved">
 <arg type="o">
 </arg> </signal>
 <signal name="DeviceAdded">
 <arg type="o">
 </arg> </signal>
 <signal name="PropertiesChanged">
 <arg type="a{sv}">
 </arg> </signal>
 <signal name="StateChanged">
 <arg type="u">
 </arg> </signal>
 <signal name="CheckPermissions">
 </signal>
 <property access="read" name="State" type="u">
 <property access="read" name="Version" type="s">
 <property access="read" name="ActiveConnections" type="ao">
 <property access="read" name="WimaxHardwareEnabled" type="b">
 <property access="readwrite" name="WimaxEnabled" type="b">
 <property access="read" name="WwanHardwareEnabled" type="b">
 <property access="readwrite" name="WwanEnabled" type="b">
 <property access="read" name="WirelessHardwareEnabled" type="b">
 <property access="readwrite" name="WirelessEnabled" type="b">
 <property access="read" name="NetworkingEnabled" type="b">
 </property> </property> </property> </property> </property> </property> </property> </property> </property> </property>
 <node name="AccessPoint">
 <node name="ActiveConnection">
 <node name="AgentManager">
 <node name="DHCP4Config">
 <node name="Devices">
 <node name="IP4Config">
 <node name="Settings">
 </node>
" </node> </node> </node> </node> </node> </node>

Lets see if we can translate this into something more human readable.

For example,

<node>
 <interface name="org.freedesktop.DBus.Introspectable">
 <method name="Introspect">
 <arg direction="out" name="data" type="s">
 </arg&gt;&lt;/method> 

 ... 

</node>

is the method we used for introspection (remember?).

See the org.freedesktop.DBus.Introspectable.Introspect?  The arg direction "out" means the the response, and type "d" means data string).


How to use introspection to create a dbus query or command

Heres a slightly more complex example of an introspection response:

 <interface name="org.freedesktop.DBus.Properties">
 ...
 <method name="GetAll">
 <arg direction="in" name="interface" type="s">
 <arg direction="out" name="props" type="a{sv}">
 </arg> </arg> </method>

 ...

 <interface name="org.freedesktop.NetworkManager"> 

This generic method, org.freedesktop.DBus.Properties.GetAll, returns a complete dump of all of some other interfaces properties.

Lets go back to grammar (destination, path, method, message) and say that again:

I want to see a dump of Network managers top-level properties.
"Hey Network Manager, please give me a printout of all of Network Managers top-level properties."

Destination: "Hey, Network Manager": org.freedesktop.NetworkManager

Path:  "Network Managers": org/freedesktop/NetworkManager

Method: "Give me a printout of properties": org.freedesktop.DBus.Properties.GetAll

Message: "top-level": org.freedesktop.NetworkManager

You probably noticed that this example has some duplication. When working with dbus, get used to it.


Now lets put it into the right syntax:

dbus-send [ --system| --session] --print-reply --dest=DEST PATH METHOD [MESSAGE]

$ dbus-send --system --print-reply 
 --dest=org.freedesktop.NetworkManager 
 org/freedesktop/NetworkManager 
 org.freedesktop.DBus.Properties.GetAll 
 string:"org.freedesktop.NetworkManager"

Lets do one more slightly different example:

<interface name="org.freedesktop.NetworkManager">
 ...
 <method name="ActivateConnection">
 <arg direction="in" name="connection" type="o">
 <arg direction="in" name="device" type="o">
 <arg direction="in" name="specific_object" type="o">
 <arg direction="out" name="active_connection" type="o">
 </arg> </arg> </arg> </arg> </method>

 </node>
" </node> </node> </node> </node> </node> </node>

This method, ActivateConnection, makes a known connection into the active network connection. For example, when switching from one access point to another. There are three extra pieces of information needed, and network manager returns one piece of information in the response.

Lets go back to grammar (destination, path, method, message) and say that again:

"Hey Network Manager, make Access Point Foo (using wireless device 0 and network password settings 67) the active connection."

Destination: "Hey, Network Manager": org.freedesktop.NetworkManager

Path:  "Network Manager": org/freedesktop/NetworkManager

Method: "Make...the active connection": org.freedesktop.NetworkManager.ActivateConnection

Message 1: "Access Point Foo": org/freedesktop/NetworkManager/AccessPoint/220

Message 2: "wireless device 0": org/freedesktop/NetworkManager/Device/0

Message 3: "network password info 67": org/freedesktop/NetworkManager/Settings/67

Now lets put it into the right syntax:

dbus-send [ --system| --session] --print-reply --dest=DEST PATH METHOD [MESSAGE]

$ dbus-send --system --print-reply 
 --dest=org.freedesktop.NetworkManager 
 org/freedesktop/NetworkManager 
 org.freedesktop.NetworkManager/ActivateConnection 
 objpath:"org/freedesktop/NetworkManager/AccessPoint/220" 

 objpath:"org/freedesktop/NetworkManager/Device/0" 
 objpath:"org/freedesktop/NetworkManager/Settings/67"

Obviously, this example wont work for you unless you do the introspection to find valid Access Points, Devices, and Settings that work together. dbus will tell you a lot of it...if you ask...but its not a user-friendly graphical user interface. You need to ask the right questions and use your own logic.

Making introspection easier is where d-feet comes in.


d-feet makes introspection easy

d-feet is a python application (part of the d-feet package in Debian and Ubuntu) that does introspection for you while you write your program.


In this screenshot, you can see lots of the same introspection information that we retrieved before. Easier to read and understand, isnt it? See how the Interfaces and Methods are listed for each Object Path?

Without d-feet, use the following dbus-send command to find out whats available on the bus:

$ dbus-send --session --print-reply --dest="org.freedesktop.DBus" /org/freedesktop/DBus org.freedesktop.DBus.ListActivatableNames

Now you know how to find the information you need to use dbus properly.
download more info