Xdp – 1.0: libportal Reference Manual
Description: Reference for Xdp-1.0: libportal Reference Manual

#### libportal Reference Manual

# 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.