• Stars
    star
    599
  • Rank 74,745 (Top 2 %)
  • Language
    C
  • License
    GNU Lesser Genera...
  • Created over 8 years ago
  • Updated 8 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Desktop integration portal

xdg-desktop-portal

A portal frontend service for Flatpak and possibly 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.

Documentation for the available D-Bus interfaces can be found here.

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.

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:

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.

More Repositories

1

flatpak

Linux application sandboxing and distribution framework
C
4,242
star
2

flatpak-builder-tools

Various helper tools for flatpak-builder
Python
195
star
3

flat-manager

Manager for flatpak repositories
Rust
146
star
4

flatpak-builder

Tool to build flatpaks from source
C
139
star
5

xdg-desktop-portal-gtk

Gtk implementation of xdg-desktop-portal
C
126
star
6

flatpak-github-actions

Build your Flatpak application using Github Actions
JavaScript
117
star
7

libportal

libportal - Flatpak portal library
C
80
star
8

flatpak-docs

Flatpak documentation
reStructuredText
78
star
9

flatpak.github.io

Flatpak website
SCSS
55
star
10

xdg-dbus-proxy

C
36
star
11

flatpak-xdg-utils

Simple portal-based commandline tools for use inside flatpak sandboxes
C
32
star
12

freedesktop-sdk-images

Flatpak freedesktop 1.6 runtime. Note: New development is at https://gitlab.com/freedesktop-sdk/freedesktop-sdk
C
29
star
13

flatpak-build-scripts

A collection of scripts for setting up build machines and running builds
Shell
16
star
14

qt-flatpak-demo

Flatpak demo application
C++
16
star
15

flatpak-docker-images

Makefile
9
star
16

ppa-flatpak

PPA builds of flatpak
C
8
star
17

freedesktop-sdk-base

Yocto layer and build script for flatpak runtime base
BitBake
8
star
18

meta-flatpak

Shell
7
star
19

ppa-ostree

ostree backports for Ubuntu, used in Flatpak PPA
C
4
star
20

ppa-flatpak-builder

PPA for flatpak-builder
C
2
star
21

flatpak-sample-authenticator

Sample authenticator or flatpak
C
2
star
22

flatpak-oci-specs

1
star
23

ppa-xdg-desktop-portal-gtk

Packaging for xdg-desktop-portal-gtk in Ubuntu PPA
C
1
star
24

ppa-xdg-desktop-portal

C
1
star