what is the purpose of dbus interface xml file?

Question

I am reading D-Bus API Design Guidelines:

Interface files for public API should be installed to $(datadir)/dbus-1/interfaces so that other services can load them.

OK... in order to understand how these interface files work, I open the file /usr/share/dbus-1/interfaces/org.gnome.Shell.Screenshot.xml (I'm using Ubuntu 20.04)

<node>
  <interface name="org.gnome.Shell.Screenshot">
  ...
    <method name="PickColor">
      <arg type="a{sv}" direction="out" name="result"/>
    </method>

Well, I see the interface name, I see the method name, but that is not enough. If I want to call this method using dbus-send

$ dbus-send --print-reply --dest=<service.name> </path/to/object> org.gnome.Shell.Screenshot.PickColor

I need <service.name> and <path/to/object>, which this xml-file does not provide.

The queston is: what is the purpose of this file if it does not provide full information about the service interface? Is it used by dbus-daemon or by any other programs? Are such files really needed for something? Should I make a conclusion that an xml-file, which does not provide a path to object in , is incomplete? Should such file also mention a service known name (org.gnome.Shell.Screenshot in this case)?

ukBaz · Answer 1 · 2022-02-08T07:27:30.173

The org.freedesktop.DBus.Introspectable interface has one method:

      org.freedesktop.DBus.Introspectable.Introspect (out STRING xml_data)

Object instances may implement Introspect which returns an XML description of the object. The introspection format is documented at: https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format

Using busctl on the command line I can use list to get all the services, tree to get all the objects, and then intropspect to find the API. Using these three commands I can discover the D-Bus services on a system

$ busctl list
$ busctl tree <service>
$ busctl introspect <service> <object>

The service you mentioned in your question is on the Session/User bus so it would be:

$ busctl --user list | grep Screenshot
NAME                                          PID PROCESS         USER       CONNECTION    UNIT              SESSION DESCRIPTION
---------------------------------------------------------------------------------------------------------------------------------
org.gnome.Screenshot                            - -               -          (activatable) -                 -       -          
org.gnome.Shell.Screenshot                   1259 gnome-shell     LinuxMachine1 :1.37         user@1000.service -       -          

$ busctl --user tree org.gnome.Shell.Screenshot
├─/StatusNotifierWatcher
└─/org
  ├─/org/freedesktop
  │ ├─/org/freedesktop/Notifications
  │ └─/org/freedesktop/portal
  │   └─/org/freedesktop/portal/desktop
  ├─/org/gnome
  │ ├─/org/gnome/Mutter
  │ │ ├─/org/gnome/Mutter/DisplayConfig
  │ │ └─/org/gnome/Mutter/IdleMonitor
  │ │   └─/org/gnome/Mutter/IdleMonitor/Core
  │ ├─/org/gnome/ScreenSaver
  │ ├─/org/gnome/SessionManager
  │ │ └─/org/gnome/SessionManager/EndSessionDialog
  │ ├─/org/gnome/Shell
  │ │ ├─/org/gnome/Shell/AudioDeviceSelection
  │ │ ├─/org/gnome/Shell/Introspect
  │ │ ├─/org/gnome/Shell/Screencast
  │ │ ├─/org/gnome/Shell/Screenshot
  │ │ └─/org/gnome/Shell/Wacom
  │ └─/org/gnome/keyring
  │   └─/org/gnome/keyring/Prompter
  └─/org/gtk
    ├─/org/gtk/MountOperationHandler
    └─/org/gtk/Notifications

$ busctl --user introspect org.gnome.Shell.Screenshot /org/gnome/Shell/Screenshot
NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
org.freedesktop.DBus.Introspectable interface -         -            -
.Introspect                         method    -         s            -
org.freedesktop.DBus.Peer           interface -         -            -
.GetMachineId                       method    -         s            -
.Ping                               method    -         -            -
org.freedesktop.DBus.Properties     interface -         -            -
.Get                                method    ss        v            -
.GetAll                             method    s         a{sv}        -
.Set                                method    ssv       -            -
.PropertiesChanged                  signal    sa{sv}as  -            -
org.gnome.Shell.Screenshot          interface -         -            -
.FlashArea                          method    iiii      -            -
.PickColor                          method    -         a{sv}        -
.Screenshot                         method    bbs       bs           -
.ScreenshotArea                     method    iiiibs    bs           -
.ScreenshotWindow                   method    bbbs      bs           -
.SelectArea                         method    -         iiii         -

And for completeness, running the same command as you did:

$ busctl --user call org.gnome.Shell.Screenshot /org/gnome/Shell/Screenshot org.gnome.Shell.Screenshot PickColor
a{sv} 1 "color" (ddd) 1 1 1

It is a splendid answer, which answers many questions, which I had about dbus, but this particular question was asking something else: what is the purpose of such xml files, if they do not provide full information about services? Are they really needed for something? You are talking about calling the method `Introspect`, but some people write their services without providing this method. But still they provide xml files, describing their service. Should I make a conclusion that an xml-file, which does not provide a path to object in ``, is incomplete? — John Smith, Feb 08 '22 at 09:04
As it says in the documentation I linked to, its primary use if for the returned XML string that describes the object on Introspection. For me, using the `PyGObject` bindings, the XML is passed to [Gio.DBusNodeInfo.new_for_xml](https://lazka.github.io/pgi-docs/index.html#Gio-2.0/classes/DBusNodeInfo.html#Gio.DBusNodeInfo.new_for_xml). As alluded to in the linked documentation, the XML might be used elsewhere also. I suspect the answer will depend on the specific D-Bus bindings you use and what you are creating. — ukBaz, Feb 08 '22 at 10:08

score 1 · Accepted Answer · answered Feb 08 '22 at 13:42

The answer is in the name: it’s a D-Bus interface file. It defines an interface, not an instantiation of that interface. There may be zero or more instantiations of an interface in D-Bus, and they may be dynamic. So their paths can’t be specified in an XML file.

If D-Bus was designed now, perhaps this XML file would have been structured or implemented differently. But this is what there is.

what is the purpose of dbus interface xml file?

2 Answers2