Properties and Annotations

Interfaces can have properties. These can be exposed via the ‘org.freedesktop.DBus.Properties’ interface¹. That is, properties can be retrieved and changed during lifetime of an element.

A generalized interface is ‘org.freedesktop.DBus.Objectmanager’², 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 functions 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³ 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"

2.6 What else to know about interfaces.

Footnotes