Portals

libportal is a library that provides GIO-style async API wrappers for the D-Bus portal APIs in xdg-desktop-portal.

Where possible, applications should prefer to use existing library APIs that have portal support. For example, a GTK application should use Gtk.FileChooserNative instead of xdp_portal_open_file().

Some portal interfaces are not covered in libportal, since they already have perfectly adequate APIs in GLib (which libportal depends on anyway).

• NetworkMonitor: Use GNetworkMonitor
• ProxyResolver: Use GProxyResolver
• Settings: Use a plain GDBusProxy
• GameMode: Not currently covered
• Secrets: Not currently covered

Accounts

The Accounts portal lets applications query basic information about the user, such as user ID, name and avatar picture.

See xdp_portal_get_user_information().

The underlying D-Bus interface is org.freedesktop.portal.Account.

Background

The Background portal lets applications request background permissions such as enabling autostart.

See xdp_portal_request_background().

The underlying D-Bus interface is org.freedesktop.portal.Background.

Camera

The Camera portal lets applications access camera devices and open PipeWire remotes for them.

To test if the Camera portal is available, you can use xdp_portal_is_camera_present().

See xdp_portal_access_camera().

The underlying D-Bus interface is org.freedesktop.portal.Camera.

Email

The Email portal lets applications send email, by prompting the user to compose a message. The email may already have an address, subject, body or attachments.

See xdp_portal_compose_email().

The underlying D-Bus interface is org.freedesktop.portal.Email.

File

The File portal lets applications ask the user for access to files outside the sandbox, by presenting a file chooser dialog.

The selected files will be made accessible to the application via the document portal, and the returned URI will point into the document portal fuse filesystem in /run/user/$UID/doc/.

See xdp_portal_open_file(), xdp_portal_save_file(), and xdp_portal_save_files().

The underlying D-Bus interface is org.freedesktop.portal.FileChooser.

Session

The Session portal lets applications inhibit certain login session state changes, and be informed about the impending end of the session.

A typical use for this functionality is to prevent the session from locking while a video is playing.

See xdp_portal_session_inhibit(), and xdp_portal_session_monitor_start().

The underlying D-Bus interface is org.freedesktop.portal.Inhibit.

Location

The Access portal lets app access to location information.

Location monitoring makes location information available via the XdpPortal::location-updated signal.

See xdp_portal_location_monitor_start().

The underlying D-Bus interface is org.freedesktop.portal.Location.

Notification

The Notification portal lets applications send desktop notifications.

See xdp_portal_add_notification().

The underlying D-Bus interface is org.freedesktop.portal.Notification.

Open URI

The Open URI portal lets applications open URIs in external handlers. A typical example is to open a pdf file in a document viewer.

See xdp_portal_open_uri(), and xdp_portal_open_directory().

The underlying D-Bus interface is org.freedesktop.portal.OpenURI.

Print

The Print portal lets applications send documents to a printer.

See xdp_portal_prepare_print(), and xdp_portal_print_file().

The underlying D-Bus interface is org.freedesktop.portal.Print.

Screencast

The Screencast portal lets applications create screencast sessions.

A screencast session makes the content of a monitor or window available as a PipeWire stream.

See xdp_portal_create_screencast_session().

The underlying D-Bus interface is org.freedesktop.portal.ScreenCast.

Remote Desktop

The Remote Desktop portal allows remote control of a session.

A remote desktop session allows to inject events into the input stream.

See xdp_portal_create_remote_desktop_session().

The underlying D-Bus interface is org.freedesktop.portal.RemoteDesktop.

Screenshot

The Screenshot portal allows applications to take screenshots or pick colors.

See xdp_portal_take_screenshot(), and xdp_portal_pick_color().

The underlying D-Bus interface is org.freedesktop.portal.Screenshot.

Spawn

The Spawn portal lets applications spawn a process in another copy of their sandbox.

To monitor spawned processes, use the XdpPortal::spawn-exited signal.

See xdp_portal_spawn().

The underlying D-Bus interface is org.freedesktop.portal.Flatpak.

Trash

The Trash portal lets applications send a file to the trash can.

See xdp_portal_trash_file().

The underlying D-Bus interface is org.freedesktop.portal.Trash.

Updates

The Updates portal lets applications be informed about available software updates (for themselves) and install those updates.

See xdp_portal_update_install().

The underlying D-Bus interface is org.freedesktop.portal.Flatpak.

Wallpaper

The Wallpaper portal lets applications set desktop backgrounds.

See xdp_portal_set_wallpaper().

The underlying D-Bus interface is org.freedesktop.portal.Wallpaper.