1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
---
layout: default
---
<picture class="full pixels">
<source srcset="assets/splash-dark.png" media="(prefers-color-scheme: dark)">
<img src="assets/splash.png">
</picture>
# XDG Desktop Portal
A portal frontend service for [Flatpak](http://www.flatpak.org) and other
desktop containment frameworks.
xdg-desktop-portal works by exposing a series of D-Bus interfaces known as
_portals_ under a well-known name (`org.freedesktop.portal.Desktop`) and object
path (`/org/freedesktop/portal/desktop`).
The portal interfaces include APIs for file access, opening URIs, printing
and others.
<a href="https://flatpak.github.io/xdg-desktop-portal/docs" class="pixelbutton"><picture alt="Documentation for the available D-Bus interfaces">
<source srcset="assets/docs-button-dark.png" media="(prefers-color-scheme: dark)">
<img src="assets/docs-button.png">
</picture></a>
## Version Numbering
xdg-desktop-portal uses even minor vesion numbers for stable versions, and odd
minor version numbers for unstable versions. During an unstable version cycle,
portal APIs can make backward incompatible changes, meaning that applications
should only depend on APIs defined in stable xdg-desktop-portal versions in
production.
## Building xdg-desktop-portal
xdg-desktop-portal depends on GLib and Flatpak. To build the documentation, you
will need xmlto and the docbook stylesheets. For more instructions, please read
[CONTRIBUTING.md](https://github.com/flatpak/xdg-desktop-portal/blob/main/CONTRIBUTING.md).
## Using Portals
Flatpak grants sandboxed applications _talk_ access to names in the
org.freedesktop.portal.\* prefix. One possible way to use the portal APIs
is thus just to make D-Bus calls. For many of the portals, toolkits (e.g.
GTK) are expected to support portals transparently if you use suitable
high-level APIs.
To implement most portals, xdg-desktop-portal relies on a backend
that provides implementations of the org.freedesktop.impl.portal.\* interfaces.
Here are some examples of available backends:
- GTK [xdg-desktop-portal-gtk](http://github.com/flatpak/xdg-desktop-portal-gtk)
- GNOME [xdg-desktop-portal-gnome](https://gitlab.gnome.org/GNOME/xdg-desktop-portal-gnome/)
- KDE [xdg-desktop-portal-kde](https://invent.kde.org/plasma/xdg-desktop-portal-kde)
- LXQt [xdg-desktop-portal-lxqt](https://github.com/lxqt/xdg-desktop-portal-lxqt)
- Pantheon (elementary OS) [xdg-desktop-portal-pantheon](https://github.com/elementary/portals)
- wlroots [xdg-desktop-portal-wlr](https://github.com/emersion/xdg-desktop-portal-wlr)
- Deepin [xdg-desktop-portal-dde](https://github.com/linuxdeepin/xdg-desktop-portal-dde)
- Xapp (Cinnamon, MATE, Xfce) [xdg-desktop-portal-xapp](https://github.com/linuxmint/xdg-desktop-portal-xapp)
## Design Considerations
There are several reasons for the frontend/backend separation of the portal
code:
- We want to have _native_ portal dialogs that match the session desktop (i.e.
GTK dialogs for GNOME, Qt dialogs for KDE)
- One of the limitations of the D-Bus proxying in flatpak is that allowing a
sandboxed app to talk to a name implicitly also allows it to talk to any other
name owned by the same unique name. Therefore, sandbox-facing D-Bus apis
should generally be hosted on a dedicated bus connection. For portals, the
frontend takes care of this for us.
- The frontend can handle all the interaction with _portal infrastructure_, such
as the permission store and the document store, freeing the backends to focus
on just providing a user interface.
- The frontend can also handle argument validation, and be strict about only
letting valid requests through to the backend.
The portal apis are all following the pattern of an initial method call, whose
response returns an object handle for an _org.freedesktop.portal.Request_ object
that represents the portal interaction. The end of the interaction is done via a
_Response_ signal that gets emitted on that object. This pattern was chosen over
a simple method call with return, since portal apis are expected to show dialogs
and interact with the user, which may well take longer than the maximum method
call timeout of D-Bus. Another advantage is that the caller can cancel an
ongoing interaction by calling the _Cancel_ method on the request object.
One consideration for deciding the shape of portal APIs is that we want them to
'hide' behind existing library APIs where possible, to make it as easy as
possible to have apps use them _transparently_. For example, the OpenFile portal
is working well as a backend for the GtkFileChooserNative API.
When it comes to files, we need to be careful to not let portal apis subvert the
limited filesystem view that apps have in their sandbox. Therefore, files should
only be passed into portal APIs in one of two forms:
- As a document ID referring to a file that has been exported in the document
portal
- As an open fd. The portal can work its way back to a file path from the fd,
and passing an fd proves that the app inside the sandbox has access to the
file to open it.
When it comes to processes, passing pids around is not useful in a sandboxed
world where apps are likely in their own pid namespace. And passing pids from
inside the sandbox is problematic, since the app can just lie.
## Contributing
XDG Desktop Portals is [Free Software](https://www.gnu.org/philosophy/free-sw.html). Contributions [welcome](https://github.com/flatpak/xdg-desktop-portal/blob/main/CONTRIBUTING.md).
|
