afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
Close stale issues and PRs / stale (push) Has been cancelled
43 lines
2.0 KiB
ReStructuredText
43 lines
2.0 KiB
ReStructuredText
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 :doc:`backend D-Bus interfaces <impl-dbus-interfaces>`
|
|
in an executable. This executable must be `D-Bus activatable
|
|
<https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html>`_.
|
|
* 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:
|
|
|
|
.. code-block::
|
|
|
|
[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 :doc:`backend D-Bus interfaces <impl-dbus-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.
|