In Linux,Dbus is a way for processes to communicate with each other. For example, programs likePidgin instant messenger allow other programs to find out or change the user's status (Available, Away, etc). Another example is thenetwork-manager service that publishes which internet connection is active. Programs that sometimes connect to the internet can then pick the best time to download updates to the system.
Messages are sent along buses. Services attach themselves to these buses, and allow clients to pass messages to and from them.
There are two main buses, thesystem bus andsession bus. Services on the system bus affect the whole system, such as providing information about the network or disk drives. Services on the session bus provide access to programs running on the desktop, like Pidgin.
importdbussys_bus=dbus.SystemBus()
Services attached to a bus can be contacted using theirwell-known name. While this could be any string, the format is normally that of a reverse domain name: an example for a spreadsheet program called "CalcProgram" from "My Corp Inc." could be "com.mycorp.CalcProgram".
Services publish objects using slash-separated paths (this is similar to webpages). Someone on dbus can request an object if they know this path.
The object passed back is not a full object: it just refers to the service's copy of the object. It is called aproxy object.
proxy_for_cell_a2=sys_bus.get_object('com.mycorp.CalcProgram','/spreadsheet1/cells/a2')
Before the proxy object can be used, we need to specify what type of object it is. We do this by creating an interface object.
cell_a2=dbus.Interface(proxy_for_cell_a2,'com.mycorp.CalcProgram.SpreadsheetCell')
Whatever methods are set up for this type of object can be called:
cell_a2.getContents()
| Name | Example | Description |
|---|---|---|
| service well known name | com.mycorp.CalcProgram | Identifies the application |
| path of an object | /spreadsheet1/cells/a2 | Identifies an object published by a service |
| interface | com.mycorp.CalcProgram.SpreadsheetCell | Identifies what type of object we expect |
These examples have been tested with dbus-python 0.83.0. Older library versions may not have the same interface.
Calling an interface's methods / Listing HAL Devices:
importdbusbus=dbus.SystemBus()hal_manager_object=bus.get_object('org.freedesktop.Hal','/org/freedesktop/Hal/Manager')hal_manager_interface=dbus.Interface(hal_manager_object,'org.freedesktop.Hal.Manager')# calling method upon interfaceprinthal_manager_interface.GetAllDevices()# accessing a method through 'get_dbus_method' through proxy object by specifying interfacemethod=hal_manager_object.get_dbus_method('GetAllDevices','org.freedesktop.Hal.Manager')print(method())# calling method upon proxy object by specifying the interface to useprint(hal_manager_object.GetAllDevices(dbus_interface='org.freedesktop.Hal.Manager'))
Introspecting an object:
importdbusbus=dbus.SystemBus()hal_manager_object=bus.get_object('org.freedesktop.Hal',# service'/org/freedesktop/Hal/Manager'# published object)introspection_interface=dbus.Interface(hal_manager_object,dbus.INTROSPECTABLE_IFACE,)# Introspectable interfaces define a property 'Introspect' that# will return an XML string that describes the object's interfaceinterface=introspection_interface.Introspect()print(interface)
Avahi:
importdbussys_bus=dbus.SystemBus()# get an object called / in org.freedesktop.Avahi to talk toraw_server=sys_bus.get_object('org.freedesktop.Avahi','/')# objects support interfaces. get the org.freedesktop.Avahi.Server interface to our org.freedesktop.Avahi object.server=dbus.Interface(raw_server,'org.freedesktop.Avahi.Server')# The so-called documentation is at /usr/share/avahi/introspection/Server.introspectprint(server)print(server.GetVersionString())print(server.GetHostName())
These examples have been tested with pydbus 0.2 and 0.3.
Calling an interface's methods / Listing systemd units:
frompydbusimportSystemBusbus=SystemBus()systemd=bus.get('.systemd1'# service name - names starting with . automatically get org.freedesktop prepended.# no object path - it'll be set to the service name transformed to the path format (/org/freedesktop/systemd1))forunitinsystemd.ListUnits()[0]:print(unit)
Introspecting an object:
frompydbusimportSystemBusbus=SystemBus()systemd=bus.get('.systemd1')# Introspectable interfaces define a property 'Introspect' that# will return an XML string that describes the object's interfaceprint(systemd.Introspect()[0])# Introspection data is automatically converted to Python's help system datahelp(systemd)
Avahi:
frompydbusimportSystemBusbus=SystemBus()# get an object called / in org.freedesktop.Avahi to talk toavahi=bus.get('.Avahi','/')# See the object's APIhelp(avahi)print(avahi.GetVersionString())print(avahi.GetHostName())