Writing a New Backend

Portal backends are session services that provide user interfaces, and access APIs and resources specific to the desktop environment they are running. For example, the KDE backend may use KDE-specific technologies, toolkit, and APIs.

For a new portal backend (let’s call it foo) to be discoverable by XDG Desktop Portal, the following steps are necessary:

  • Implement one or more backend D-Bus interfaces in an executable. This executable must be D-Bus activatable.

  • Install foo.portal file under {DATADIR}/xdg-desktop-portal/portals. Usually, {DATADIR} is /usr/share. The syntax of the portal file is documented below.

  • Make sure the new backend is picked by XDG Desktop Portal by adding a config file that points to the new foo portal backend. The syntax of the config file is documented below.

Portal (.portal) File

Portal files are files that allow XDG Desktop Portal to know which portal backends are available, and which backend D-Bus interfaces they implement. They usually look like this:

[portal]
DBusName=org.freedesktop.impl.portal.desktop.foo
Interfaces=org.freedesktop.impl.portal.AppChooser;org.freedesktop.impl.portal.Background;org.freedesktop.impl.portal.Clipboard;org.freedesktop.impl.portal.FileChooser;org.freedesktop.impl.portal.Lockdown;org.freedesktop.impl.portal.RemoteDesktop;org.freedesktop.impl.portal.ScreenCast;
UseIn=gnome

The following keys are supported in this file:

  • DBusName: the D-Bus activation name of the portal backend service.

  • Interfaces: which backend D-Bus interfaces this portal backend implements.

  • UseIn: which desktop environments the portal backend should run. This key is officially deprecated, and has been replaced by the config file, but it’s recommended to keep it there for legacy systems.