dbus: Properties and Annotations
2.6 What else to know about interfaces.
=======================================
Interfaces can have properties. These can be exposed via the
‘org.freedesktop.DBus.Properties’ interface(1). That is, properties can
be retrieved and changed during lifetime of an element.
A generalized interface is ‘org.freedesktop.DBus.Objectmanager’(2),
which returns objects, their interfaces and properties for a given
service in just one call.
Annotations, on the other hand, are static values for an element.
Often, they are used to instruct generators, how to generate code from
the interface for a given language binding.
-- Function: dbus-introspect-get-property-names bus service path
interface
Return a list of strings with all property names of INTERFACE of
SERVICE in D-Bus BUS at object path PATH. Example:
(dbus-introspect-get-property-names
:session "org.kde.kded" "/modules/networkstatus"
"org.kde.Solid.Networking.Client")
⇒ ("Status")
If an interface declares properties, the corresponding element
supports also the ‘org.freedesktop.DBus.Properties’ interface.
-- Function: dbus-introspect-get-property bus service path interface
property
This function returns PROPERTY of INTERFACE as XML element. It
must be located at SERVICE in D-Bus BUS at object path PATH.
PROPERTY must be a string, element of the list returned by
‘dbus-introspect-get-property-names’.
A PROPERTY value can be retrieved by the function
‘dbus-introspect-get-attribute’. Example:
(dbus-introspect-get-property
:session "org.kde.kded" "/modules/networkstatus"
"org.kde.Solid.Networking.Client" "Status")
⇒ (property ((access . "read") (type . "u") (name . "Status")))
(dbus-introspect-get-attribute
(dbus-introspect-get-property
:session "org.kde.kded" "/modules/networkstatus"
"org.kde.Solid.Networking.Client" "Status")
"access")
⇒ "read"
-- Function: dbus-get-property bus service path interface property
This function returns the value of PROPERTY of INTERFACE. It will
be checked at BUS, SERVICE, PATH. The result can be any valid
D-Bus value, or ‘nil’ if there is no PROPERTY. Example:
(dbus-get-property
:session "org.kde.kded" "/modules/networkstatus"
"org.kde.Solid.Networking.Client" "Status")
⇒ 4
-- Function: dbus-set-property bus service path interface property
value
Set value of PROPERTY of INTERFACE to VALUE. It will be checked at
BUS, SERVICE, PATH. When the value has been set successful, the
result is VALUE. Otherwise, ‘nil’ is returned. Example:
(dbus-set-property
:session "org.kde.kaccess" "/MainApplication"
"com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
⇒ 500
-- Function: dbus-get-all-properties bus service path interface
This function returns all properties of INTERFACE. It will be
checked at BUS, SERVICE, PATH. The result is a list of cons.
Every cons contains the name of the property, and its value. If
there are no properties, ‘nil’ is returned. Example:
(dbus-get-all-properties
:session "org.kde.kaccess" "/MainApplication"
"com.trolltech.Qt.QApplication")
⇒ (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
("globalStrut" 0 0) ("startDragTime" . 500)
("startDragDistance" . 4) ("quitOnLastWindowClosed" . t)
("styleSheet" . ""))
-- Function: dbus-get-all-managed-objects bus service path
This function returns all objects at BUS, SERVICE, PATH, and the
children of PATH. The result is a list of objects. Every object
is a cons of an existing path name, and the list of available
interface objects. An interface object is another cons, which car
is the interface name, and the cdr is the list of properties as
returned by ‘dbus-get-all-properties’ for that path and interface.
Example:
(dbus-get-all-managed-objects
:session "org.gnome.SettingsDaemon" "/")
⇒ (("/org/gnome/SettingsDaemon/MediaKeys"
("org.gnome.SettingsDaemon.MediaKeys")
("org.freedesktop.DBus.Peer")
("org.freedesktop.DBus.Introspectable")
("org.freedesktop.DBus.Properties")
("org.freedesktop.DBus.ObjectManager"))
("/org/gnome/SettingsDaemon/Power"
("org.gnome.SettingsDaemon.Power.Keyboard")
("org.gnome.SettingsDaemon.Power.Screen")
("org.gnome.SettingsDaemon.Power"
("Icon" . ". GThemedIcon battery-full-charged-symbolic ")
("Tooltip" . "Laptop battery is charged"))
("org.freedesktop.DBus.Peer")
("org.freedesktop.DBus.Introspectable")
("org.freedesktop.DBus.Properties")
("org.freedesktop.DBus.ObjectManager"))
...)
If possible, ‘org.freedesktop.DBus.ObjectManager.GetManagedObjects’
is used for retrieving the information. Otherwise, the information
is collected via ‘org.freedesktop.DBus.Introspectable.Introspect’
and ‘org.freedesktop.DBus.Properties.GetAll’, which is slow.
An overview of all existing object paths, their interfaces and
properties could be retrieved by the following code:
(with-current-buffer (switch-to-buffer "*objectmanager*")
(erase-buffer)
(let (result)
(dolist (service (dbus-list-known-names :session) result)
(message "%s" service)
(add-to-list
'result
(cons service
(dbus-get-all-managed-objects :session service "/"))))
(insert (message "%s" (pp result)))
(redisplay t)))
-- Function: dbus-introspect-get-annotation-names bus service path
interface &optional name
Return a list of all annotation names as list of strings. If NAME
is ‘nil’, the annotations are children of INTERFACE, otherwise NAME
must be a ‘method’, ‘signal’, or ‘property’ XML element, where the
annotations belong to. Example:
(dbus-introspect-get-annotation-names
:session "de.berlios.Pinot" "/de/berlios/Pinot"
"de.berlios.Pinot" "GetStatistics")
⇒ ("de.berlios.Pinot.GetStatistics")
Default annotation names(3) are
‘org.freedesktop.DBus.Deprecated’
Whether or not the entity is deprecated; defaults to ‘nil’
‘org.freedesktop.DBus.GLib.CSymbol’
The C symbol; may be used for ‘methods’ and ‘interfaces’
‘org.freedesktop.DBus.Method.NoReply’
If set, don’t expect a reply to the ‘method’ call; defaults to
‘nil’
-- Function: dbus-introspect-get-annotation bus service path interface
name annotation
Return annotation ANNOTATION as XML object. If NAME is ‘nil’,
ANNOTATION is a child of INTERFACE, otherwise NAME must be the name
of a ‘method’, ‘signal’, or ‘property’ XML element, where the
ANNOTATION belongs to.
An attribute value can be retrieved by
‘dbus-introspect-get-attribute’. Example:
(dbus-introspect-get-annotation
:session "de.berlios.Pinot" "/de/berlios/Pinot"
"de.berlios.Pinot" "GetStatistics"
"de.berlios.Pinot.GetStatistics")
⇒ (annotation ((name . "de.berlios.Pinot.GetStatistics")
(value . "pinotDBus")))
(dbus-introspect-get-attribute
(dbus-introspect-get-annotation
:session "de.berlios.Pinot" "/de/berlios/Pinot"
"de.berlios.Pinot" "GetStatistics"
"de.berlios.Pinot.GetStatistics")
"value")
⇒ "pinotDBus"
---------- Footnotes ----------
(1) See
<http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>
(2) See
<http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager>
(3) See
<http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>
Info Catalog
dbus: Methods and Signal
dbus: Inspection
dbus: Arguments and Signatures