Portal Documentation

Version 1.18.2


Table of Contents

1. Common Conventions
Portal requests
Sessions
Parent window identifiers
I. Portal API Reference
org.freedesktop.portal.Account — Portal for obtaining information about the user
org.freedesktop.portal.Background — Portal for requesting autostart and background activity
org.freedesktop.portal.Camera — Camera portal
org.freedesktop.portal.Clipboard
org.freedesktop.portal.Device — Portal for device access
org.freedesktop.portal.Documents — Document portal
org.freedesktop.portal.DynamicLauncher — Portal for installing application launchers
org.freedesktop.portal.Email — Portal for sending email
org.freedesktop.portal.FileChooser — File chooser portal
org.freedesktop.portal.FileTransfer — Portal for transferring files between apps
org.freedesktop.portal.Flatpak.UpdateMonitor
org.freedesktop.portal.Flatpak — Flatpak portal
org.freedesktop.portal.GameMode — Portal for accessing GameMode
org.freedesktop.portal.GlobalShortcuts
org.freedesktop.portal.Inhibit — Portal for inhibiting session transitions
org.freedesktop.portal.InputCapture — Portal for permitting input capture
org.freedesktop.portal.Location — Portal for obtaining information about the location
org.freedesktop.portal.MemoryMonitor — Memory monitoring portal
org.freedesktop.portal.NetworkMonitor — Network monitoring portal
org.freedesktop.portal.Notification — Portal for sending notifications
org.freedesktop.portal.OpenURI — Portal for opening URIs
org.freedesktop.portal.PowerProfileMonitor — Power Profile monitoring portal
org.freedesktop.portal.Print — Portal for printing
org.freedesktop.portal.ProxyResolver — Proxy information
org.freedesktop.portal.Realtime — Portal for setting threads to realtime
org.freedesktop.portal.RemoteDesktop — Remote desktop portal
org.freedesktop.portal.Request — Shared request interface
org.freedesktop.portal.ScreenCast — Screen cast portal
org.freedesktop.portal.Screenshot — Portal for taking screenshots
org.freedesktop.portal.Secret — Portal for retrieving application secret
org.freedesktop.portal.Session — Shared session interface
org.freedesktop.portal.Settings — Settings interface
org.freedesktop.portal.Trash — Portal for trashing files
org.freedesktop.portal.Wallpaper — Portal for setting the desktop's Wallpaper
II. Portal Backend API Reference
org.freedesktop.impl.portal.Access — Interface for presenting an access dialog
org.freedesktop.impl.portal.Account — Backend for the portal for obtaining user information
org.freedesktop.impl.portal.AppChooser — Interface for choosing an application
org.freedesktop.impl.portal.Background — Background portal backend interface
org.freedesktop.impl.portal.Clipboard
org.freedesktop.impl.portal.Email — Email portal backend interface
org.freedesktop.impl.portal.FileChooser — File chooser portal backend interface
org.freedesktop.impl.portal.GlobalShortcuts
org.freedesktop.impl.portal.Inhibit — Inhibit portal backend interface
org.freedesktop.impl.portal.InputCapture — Capture input portal backend interface
org.freedesktop.impl.portal.Lockdown — Lockdown backend interface
org.freedesktop.impl.portal.Notification — Notification portal backend interface
org.freedesktop.impl.portal.PermissionStore — Database to store permissions
org.freedesktop.impl.portal.Print — Print portal backend interface
org.freedesktop.impl.portal.RemoteDesktop — Remote desktop portal backend interface
org.freedesktop.impl.portal.Request — Shared request interface
org.freedesktop.impl.portal.ScreenCast — Screen cast portal backend interface
org.freedesktop.impl.portal.Screenshot — Screenshot portal backend interface
org.freedesktop.impl.portal.Secret — Secret portal backend interface
org.freedesktop.impl.portal.Session — Shared session interface
org.freedesktop.impl.portal.Settings — Settings portal backend interface
org.freedesktop.impl.portal.Wallpaper — Portal for setting the desktop's Wallpaper
III. Background Apps Monitoring API
org.freedesktop.background.Monitor — Background applications monitor

Chapter 1. Common Conventions

Requests made via portal interfaces generally involve user interaction, and dialogs that can stay open for a long time. Therefore portal APIs don't just use async method calls (which time out after at most 25 seconds), but instead return results via a Response signal on Request objects.

Portal APIs don't use properties very much. This is partially because we need to be careful about the flow of information, and partially because it would be unexpected to have a dialog appear when you just set a property.

Portal requests

The general flow of the portal API is that the application makes a portal request, the portal replies to that method call with a handle (i.e. object path) to Request object that corresponds to the request. The object is exported on the bus and stays alive as long as the user interaction lasts. When the user interaction is over, the portal sends a Response signal back to the application with the results from the interaction, if any.

To avoid a race condition between the caller subscribing to the signal after receiving the reply for the method call and the signal getting emitted, a convention for Request object paths has been established that allows the caller to subscribe to the signal before making the method call.

Sessions

Some portal requests are connected to each other and need to be used in sequence. The pattern we use in such cases is a Session object. Just like Requests, Sessions are represented by an object path, that is returned by the initial CreateSession call. Subsequent calls take the object path of the session they operate on as an argument.

Sessions can be ended from the application side by calling the Close() method. They can also be closed from the service side, in which case the ::Closed signal is emitted to inform the application.

Parent window identifiers

Most portals interact with the user by showing dialogs. These dialogs should generally be placed on top of the application window that triggered them. To arrange this, the compositor needs to know about the application window. Many portal requests expect a "parent_window" string argument for this reason.

Under X11, the "parent_window" argument should have the form "x11:XID", where XID is the XID of the application window in hexadecimal notation.

Under Wayland, it should have the form "wayland:HANDLE", where HANDLE is a surface handle obtained with the xdg_foreign protocol.

For other windowing systems, or if you don't have a suitable handle, just pass an empty string for "parent_window".

Portal API Reference


Portal interfaces are available to sandboxed applications with the default filtered session bus access of Flatpak. Unless otherwise specified, they appear under the bus name org.freedesktop.portal.Desktop and the object path /org/freedesktop/portal/desktop on the session bus.

Table of Contents

org.freedesktop.portal.Account — Portal for obtaining information about the user
org.freedesktop.portal.Background — Portal for requesting autostart and background activity
org.freedesktop.portal.Camera — Camera portal
org.freedesktop.portal.Clipboard
org.freedesktop.portal.Device — Portal for device access
org.freedesktop.portal.Documents — Document portal
org.freedesktop.portal.DynamicLauncher — Portal for installing application launchers
org.freedesktop.portal.Email — Portal for sending email
org.freedesktop.portal.FileChooser — File chooser portal
org.freedesktop.portal.FileTransfer — Portal for transferring files between apps
org.freedesktop.portal.Flatpak.UpdateMonitor
org.freedesktop.portal.Flatpak — Flatpak portal
org.freedesktop.portal.GameMode — Portal for accessing GameMode
org.freedesktop.portal.GlobalShortcuts
org.freedesktop.portal.Inhibit — Portal for inhibiting session transitions
org.freedesktop.portal.InputCapture — Portal for permitting input capture
org.freedesktop.portal.Location — Portal for obtaining information about the location
org.freedesktop.portal.MemoryMonitor — Memory monitoring portal
org.freedesktop.portal.NetworkMonitor — Network monitoring portal
org.freedesktop.portal.Notification — Portal for sending notifications
org.freedesktop.portal.OpenURI — Portal for opening URIs
org.freedesktop.portal.PowerProfileMonitor — Power Profile monitoring portal
org.freedesktop.portal.Print — Portal for printing
org.freedesktop.portal.ProxyResolver — Proxy information
org.freedesktop.portal.Realtime — Portal for setting threads to realtime
org.freedesktop.portal.RemoteDesktop — Remote desktop portal
org.freedesktop.portal.Request — Shared request interface
org.freedesktop.portal.ScreenCast — Screen cast portal
org.freedesktop.portal.Screenshot — Portal for taking screenshots
org.freedesktop.portal.Secret — Portal for retrieving application secret
org.freedesktop.portal.Session — Shared session interface
org.freedesktop.portal.Settings — Settings interface
org.freedesktop.portal.Trash — Portal for trashing files
org.freedesktop.portal.Wallpaper — Portal for setting the desktop's Wallpaper

Name

org.freedesktop.portal.Account — Portal for obtaining information about the user

Methods

GetUserInformation (IN  s     window,
                    IN  a{sv} options,
                    OUT o     handle);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications query basic information about the user, like their name and avatar photo.

This documentation describes version 1 of this interface.

Method Details

The GetUserInformation() method

GetUserInformation (IN  s     window,
                    IN  a{sv} options,
                    OUT o     handle);

Gets information about the user.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

reason s

A string that can be shown in the dialog to expain why the information is needed. This should be a complete sentence that explains what the application will do with the returned information, for example: Allows your personal information to be included with recipes you share with your friends.

The following results get returned via the "Response" signal:

id s

The user id.

name s

The users real name.

image s

The uri of an image file for the users avatar photo.

IN s window:

Identifier for the window

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Background — Portal for requesting autostart and background activity

Methods

RequestBackground (IN  s     parent_window,
                   IN  a{sv} options,
                   OUT o     handle);
SetStatus         (IN  a{sv} options);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications request that the application is allowed to run in the background or started automatically when the user logs in.

This documentation describes version 2 of this interface.

Method Details

The RequestBackground() method

RequestBackground (IN  s     parent_window,
                   IN  a{sv} options,
                   OUT o     handle);

IN s parent_window:

IN a{sv} options:

OUT o handle:

The SetStatus() method

SetStatus (IN  a{sv} options);

Sets the status of the application running in background.

Supported keys in the options vardict include:

message s

A string that will be used as the status message of the application. This should be a single line that can be presented to the user in a list, not a full sentence or paragraph. Must be shorter than 96 characters.

This method was added in version 2.

IN a{sv} options:

Vardict with optional further information

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Camera — Camera portal

Methods

AccessCamera       (IN  a{sv} options,
                    OUT o     handle);
OpenPipeWireRemote (IN  a{sv} options,
                    OUT h     fd);

Properties

IsCameraPresent  readable   b
version          readable   u

Description

The camera portal enables applications to access camera devices, such as web cams.

Method Details

The AccessCamera() method

AccessCamera (IN  a{sv} options,
              OUT o     handle);

Request to gain access to the camera.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

Following the "Response" signal, if granted, OpenPipeWireRemote() can be used to open a PipeWire remote.

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The OpenPipeWireRemote() method

OpenPipeWireRemote (IN  a{sv} options,
                    OUT h     fd);

Open a file descriptor to the PipeWire remote where the camera nodes are available. The file descriptor should be used to create a pw_core object, by using pw_context_connect_fd.

This method will only succeed if the application already has permission to access camera devices.

There are currently no supported keys in the options vardict.

IN a{sv} options:

Vardict with optional further information

OUT h fd:

File descriptor of an open PipeWire remote.

Property Details

The "IsCameraPresent" property

IsCameraPresent  readable   b

A boolean stating whether there is any cameras available.

The "version" property

version  readable   u


Name

org.freedesktop.portal.Clipboard

Methods

RequestClipboard   (IN  o     session_handle,
                    IN  a{sv} options);
SetSelection       (IN  o     session_handle,
                    IN  a{sv} options);
SelectionWrite     (IN  o     session_handle,
                    IN  u     serial,
                    OUT h     fd);
SelectionWriteDone (IN  o     session_handle,
                    IN  u     serial,
                    IN  b     success);
SelectionRead      (IN  o     session_handle,
                    IN  s     mime_type,
                    OUT h     fd);

Signals

SelectionOwnerChanged (o     session_handle,
                       a{sv} options);
SelectionTransfer     (o     session_handle,
                       s     mime_type,
                       u     serial);

Properties

version  readable   u

Description

Method Details

The RequestClipboard() method

RequestClipboard (IN  o     session_handle,
                  IN  a{sv} options);

Requests clipboard access for the given portal session. This request must be made before the session starts.

This portal does NOT create it's own session. Instead, it offers existing sessions created from other portals the option to integrate with the clipboard. For whether this interface is supported for a given session, refer to that portal's documentation. See org.freedesktop.portal.RemoteDesktop to integrate clipboard with the remote desktop session.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The SetSelection() method

SetSelection (IN  o     session_handle,
              IN  a{sv} options);

Sets the owner of the clipboard formats in 'mime_types' in options to the session, i.e. this session has data for the advertised clipboard formats.

See org.freedesktop.portal.FileTransfer to transfer files using the 'application/vnd.portal.filetransfer' mimetype.

May only be called if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types as

A list of mime types that the session has clipboard content for.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The SelectionWrite() method

SelectionWrite (IN  o session_handle,
                IN  u serial,
                OUT h fd);

Answer to 'SelectionTransfer' signal. Transfers the clipboard content for the given serial to the method callee via a file descriptor. It is the Callee that creates the file descriptor.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN u serial:

The serial of the request where this answer is directed towards

OUT h fd:

A UnixFD handle to the contents of the selection being written to

The SelectionWriteDone() method

SelectionWriteDone (IN  o session_handle,
                    IN  u serial,
                    IN  b success);

data was successful ('true') or not ('false')

Notifies that the transfer of the clipboard data has either completed successfully, or failed.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN u serial:

The serial of the request where this answer is directed to

IN b success:

A boolean which indicates whether the transfer of the clipboard

The SelectionRead() method

SelectionRead (IN  o session_handle,
               IN  s mime_type,
               OUT h fd);

Transfer the clipboard content given the specified mime type to the method caller via a file descriptor. It is the callee that creates the file descriptor.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN s mime_type:

The mime-type string of the requested format

OUT h fd:

A UnixFD handle to the contents of the selection being read

Signal Details

The "SelectionOwnerChanged" signal

SelectionOwnerChanged (o     session_handle,
                       a{sv} options);

Notifies the session that the clipboard selection has changed.

Caller will only be notified if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types as

A list of mime types that the the new clipboard selection has content for.

session_is_owner b

A boolean for whether the session is the owner of the clipboard selection ('true') or not ('false').

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

The "SelectionTransfer" signal

SelectionTransfer (o session_handle,
                   s mime_type,
                   u serial);

Notifies the session of a request for clipboard content of the given mime type. The callee provides a serial to track the request, which any SelectionWrite() responses must use.

Once the caller is done handling the 'SelectionTransfer' request, they must call SelectionWriteDone() with the corresponding request's serial and whether the request completed successfully. If the request is not handled, the caller should respond by setting 'success' to 'false'.

Caller will only be notified if clipboard access was given after starting the session.

o session_handle:

Object path for the org.freedesktop.portal.Session object

s mime_type:

The mime-type string of the requested format

u serial:

The serial used to track this transfer, to which the answer of this request must use

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Device — Portal for device access

Methods

AccessDevice (IN  u     pid,
              IN  as    devices,
              IN  a{sv} options,
              OUT o     handle);

Properties

version  readable   u

Description

This interface lets services ask if an application should get access to devices such as microphones, speakers or cameras. Not a portal in the strict sense, since the API is not directly accessible to applications inside the sandbox.

This documentation describes version 1 of this interface.

Method Details

The AccessDevice() method

AccessDevice (IN  u     pid,
              IN  as    devices,
              IN  a{sv} options,
              OUT o     handle);

Asks for access to a device.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

IN u pid:

the pid of the application on whose behalf the request is made

IN as devices:

a list of devices to request access to. Supported values are 'microphone', 'speakers', 'camera'. Asking for multiple devices at the same time may or may not be supported

IN a{sv} options:

vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Documents — Document portal

Methods

GetMountPoint     (OUT ay     path);
Add               (IN  h      o_path_fd,
                   IN  b      reuse_existing,
                   IN  b      persistent,
                   OUT s      doc_id);
AddNamed          (IN  h      o_path_parent_fd,
                   IN  ay     filename,
                   IN  b      reuse_existing,
                   IN  b      persistent,
                   OUT s      doc_id);
AddFull           (IN  ah     o_path_fds,
                   IN  u      flags,
                   IN  s      app_id,
                   IN  as     permissions,
                   OUT as     doc_ids,
                   OUT a{sv}  extra_out);
AddNamedFull      (IN  h      o_path_fd,
                   IN  ay     filename,
                   IN  u      flags,
                   IN  s      app_id,
                   IN  as     permissions,
                   OUT s      doc_id,
                   OUT a{sv}  extra_out);
GrantPermissions  (IN  s      doc_id,
                   IN  s      app_id,
                   IN  as     permissions);
RevokePermissions (IN  s      doc_id,
                   IN  s      app_id,
                   IN  as     permissions);
Delete            (IN  s      doc_id);
Lookup            (IN  ay     filename,
                   OUT s      doc_id);
Info              (IN  s      doc_id,
                   OUT ay     path,
                   OUT a{sas} apps);
List              (IN  s      app_id,
                   OUT a{say} docs);

Properties

version  readable   u

Description

The document portal allows to make files from the outside world available to sandboxed applications in a controlled way.

Exported files will be made accessible to the application via a fuse filesystem that gets mounted at /run/user/$UID/doc/. The filesystem gets mounted both outside and inside the sandbox, but the view inside the sandbox is restricted to just those files that the application is allowed to access.

Individual files will appear at /run/user/$UID/doc/$DOC_ID/filename, where $DOC_ID is the ID of the file in the document store. It is returned by the Add() and AddNamed() calls.

The permissions that the application has for a document store entry (see GrantPermissions()) are reflected in the POSIX mode bits in the fuse filesystem.

The D-Bus interface for the document portal is available under the bus name org.freedesktop.portal.Documents and the object path /org/freedesktop/portal/documents.

This documentation describes version 4 of this interface.

Method Details

The GetMountPoint() method

GetMountPoint (OUT ay path);

Returns the path at which the document store fuse filesystem is mounted. This will typically be /run/user/$UID/doc/.

OUT ay path:

the path at which the fuse filesystem is mounted

The Add() method

Add (IN  h o_path_fd,
     IN  b reuse_existing,
     IN  b persistent,
     OUT s doc_id);

Adds a file to the document store. The file is passed in the form of an open file descriptor to prove that the caller has access to the file.

IN h o_path_fd:

open file descriptor for the file to add

IN b reuse_existing:

whether to reuse an existing document store entry for the file

IN b persistent:

whether to add the file only for this session or permanently

OUT s doc_id:

the ID of the file in the document store

The AddNamed() method

AddNamed (IN  h  o_path_parent_fd,
          IN  ay filename,
          IN  b  reuse_existing,
          IN  b  persistent,
          OUT s  doc_id);

Creates an entry in the document store for writing a new file.

IN h o_path_parent_fd:

open file descriptor for the parent directory

IN ay filename:

the basename for the file

IN b reuse_existing:

whether to reuse an existing document store entry for the file

IN b persistent:

whether to add the file only for this session or permanently

OUT s doc_id:

the ID of the file in the document store

The AddFull() method

AddFull (IN  ah    o_path_fds,
         IN  u     flags,
         IN  s     app_id,
         IN  as    permissions,
         OUT as    doc_ids,
         OUT a{sv} extra_out);

Adds multiple files to the document store. The file is passed in the form of an open file descriptor to prove that the caller has access to the file.

If the as-needed-by-app flag is given, files will only be added to the document store if the application does not already have access to them. For files that are not added to the document store, the doc_ids array will contain an empty string.

Additionally, if app_id is specified, it will be given the permissions listed in GrantPermissions().

The method also returns some extra info that can be used to avoid multiple roundtrips. For now it only contains as "mountpoint", the fuse mountpoint of the document portal.

This method was added in version 2 of the org.freedesktop.portal.Documents interface.

Support for exporting directories were added in version 4 of the org.freedesktop.portal.Documents interface.

IN ah o_path_fds:

open file descriptors for the files to export

IN u flags:

flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app, 8 = export directory

IN s app_id:

an application ID, or empty string

IN as permissions:

the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'

OUT as doc_ids:

the IDs of the files in the document store

OUT a{sv} extra_out:

The AddNamedFull() method

AddNamedFull (IN  h     o_path_fd,
              IN  ay    filename,
              IN  u     flags,
              IN  s     app_id,
              IN  as    permissions,
              OUT s     doc_id,
              OUT a{sv} extra_out);

Creates an entry in the document store for writing a new file.

If the as-needed-by-app flag is given, file will only be added to the document store if the application does not already have access to it. For file that is not added to the document store, the doc_id will contain an empty string.

Additionally, if app_id is specified, it will be given the permissions listed in GrantPermissions().

The method also returns some extra info that can be used to avoid multiple roundtrips. For now it only contains as "mountpoint", the fuse mountpoint of the document portal.

This method was added in version 3 of the org.freedesktop.portal.Documents interface.

IN h o_path_fd:

IN ay filename:

the basename for the file

IN u flags:

flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app

IN s app_id:

an application ID, or empty string

IN as permissions:

the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'

OUT s doc_id:

the ID of the file in the document store

OUT a{sv} extra_out:

The GrantPermissions() method

GrantPermissions (IN  s  doc_id,
                  IN  s  app_id,
                  IN  as permissions);

Grants access permissions for a file in the document store to an application.

This call is available inside the sandbox if the application has the 'grant-permissions' permission for the document.

IN s doc_id:

the ID of the file in the document store

IN s app_id:

the ID of the application to which permissions are granted

IN as permissions:

the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'

The RevokePermissions() method

RevokePermissions (IN  s  doc_id,
                   IN  s  app_id,
                   IN  as permissions);

Revokes access permissions for a file in the document store from an application.

This call is available inside the sandbox if the application has the 'grant-permissions' permission for the document.

IN s doc_id:

the ID of the file in the document store

IN s app_id:

the ID of the application from which permissions are revoked

IN as permissions:

the permissions to revoke, possible values are 'read', 'write', 'grant-permissions' and 'delete'

The Delete() method

Delete (IN  s doc_id);

Removes an entry from the document store. The file itself is not deleted.

This call is available inside the sandbox if the application has the 'delete' permission for the document.

IN s doc_id:

the ID of the file in the document store

The Lookup() method

Lookup (IN  ay filename,
        OUT s  doc_id);

Looks up the document ID for a file.

This call is not available inside the sandbox.

IN ay filename:

a path in the host filesystem

OUT s doc_id:

the ID of the file in the document store, or '' if the file is not in the document store

The Info() method

Info (IN  s      doc_id,
      OUT ay     path,
      OUT a{sas} apps);

Gets the filesystem path and application permissions for a document store entry.

This call is not available inside the sandbox.

IN s doc_id:

the ID of the file in the document store

OUT ay path:

the path for the file in the host filesystem

OUT a{sas} apps:

a dictionary mapping application IDs to the permissions for that application

The List() method

List (IN  s      app_id,
      OUT a{say} docs);

Lists documents in the document store for an application (or for all applications).

This call is not available inside the sandbox.

IN s app_id:

an application ID, or '' to list all documents

OUT a{say} docs:

a dictionary mapping document IDs to their filesystem path

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.DynamicLauncher — Portal for installing application launchers

Methods

Install             (IN  s     token,
                     IN  s     desktop_file_id,
                     IN  s     desktop_entry,
                     IN  a{sv} options);
PrepareInstall      (IN  s     parent_window,
                     IN  s     name,
                     IN  v     icon_v,
                     IN  a{sv} options,
                     OUT o     handle);
RequestInstallToken (IN  s     name,
                     IN  v     icon_v,
                     IN  a{sv} options,
                     OUT s     token);
Uninstall           (IN  s     desktop_file_id,
                     IN  a{sv} options);
GetDesktopEntry     (IN  s     desktop_file_id,
                     OUT s     contents);
GetIcon             (IN  s     desktop_file_id,
                     OUT v     icon_v,
                     OUT s     icon_format,
                     OUT u     icon_size);
Launch              (IN  s     desktop_file_id,
                     IN  a{sv} options);

Properties

SupportedLauncherTypes  readable   u
version                 readable   u

Description

The DynamicLauncher portal allows sandboxed (or unsandboxed) applications to install launchers (.desktop files) which have an icon associated with them and which execute a command in the application. The desktop environment would display the launcher to the user in its menu of installed applications. For example this can be used by a sandboxed browser to install web app launchers. The portal also allows apps to uninstall the launchers, launch them, and read the desktop file and icon data for them.

The standard way to install a launcher is to use the PrepareInstall() method which results in a dialog being presented to the user so they can confirm they want to install the launcher. Then, the token returned by PrepareInstall() would be passed to the Install() method to complete the installation.

However, in the rare circumstance that an unsandboxed process such as a system component needs to install a launcher without user interaction, this can be accomplished by using the RequestInstallToken() method and passing the acquired token to Install().

This documentation describes version 1 of this interface.

Method Details

The Install() method

Install (IN  s     token,
         IN  s     desktop_file_id,
         IN  s     desktop_entry,
         IN  a{sv} options);

Installs a .desktop launcher and icon into appropriate directories to allow the desktop environment to find them. Please note that this method overwrites any existing launcher with the same id. If you want to present the user with a confirmation dialog in that case, you can check for it using the GetDesktopEntry() method and clean up any state from the previous launcher if you want.

token must be a token that was returned by a previous PrepareInstall() or RequestInstallToken() call. The token can only be used once and is valid for up to five minutes.

The icon and name used for the launcher will be the ones from the previous PrepareInstall() or RequestInstallToken() call.

The desktop_file_id must have ".desktop" as a suffix. Except in the special case when the calling process has no associated app ID, desktop_file_id must have the app ID followed by a period as a prefix, regardless of whether the calling process is sandboxed or unsandboxed.

The desktop_entry should be a valid desktop entry file beginning with "[Desktop Entry]", except it should not include Name= or Icon= entries (if present, these will be overwritten by the portal implementation). The Exec= entry will be rewritten to call the sandboxed application e.g. via "flatpak run", if the application is sandboxed.

It is recommended to include a TryExec= line with either a binary name or an absolute path. The launcher will be deleted if the TryExec binary cannot be found on session start.

The options vardict currently has no supported entries.

IN s token:

Token proving authorization of the installation

IN s desktop_file_id:

The .desktop file name to be used

IN s desktop_entry:

The text of the Desktop Entry file to be installed, see below

IN a{sv} options:

Vardict with optional further information

The PrepareInstall() method

PrepareInstall (IN  s     parent_window,
                IN  s     name,
                IN  v     icon_v,
                IN  a{sv} options,
                OUT o     handle);

Presents a dialog to the user to allow them to see the icon, potentially change the name, and confirm installation of the launcher.

Supported keys in the options vardict:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

modal b

Whether to make the dialog modal. Defaults to yes.

launcher_type u

The type of launcher being created. For supported values see the SupportedLauncherTypes property. Defaults to "Application".

target s

For a launcher of type "Webapp", this is the URL of the web app being installed. This is displayed in the user-facing dialog. For other launcher types, this is not needed.

editable_name b

If true, the user will be able to edit the name of the launcher. Defaults to true.

editable_icon b

If true, the user will be able to edit the icon of the launcher, if the implementation supports this. Defaults to false.

The following results get returned via the "Response" signal:

name s

The name chosen by the user for the launcher.

token s

Token that can be passed to a subsequent Install() call to complete the installation without another dialog.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s name:

The default name for the launcher

IN v icon_v:

A #GBytesIcon icon as returned by g_icon_serialize(). Must be a png or jpeg no larger than 512x512, or an svg

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The RequestInstallToken() method

RequestInstallToken (IN  s     name,
                     IN  v     icon_v,
                     IN  a{sv} options,
                     OUT s     token);

This method is intended for use only by specific components that have their application ID allowlisted in the portal backend (e.g. GNOME Software and KDE Discover). It is otherwise not guaranteed to work.

The token returned by this method can be used to avoid the need for a confirmation dialog; the token can be passed to the Install() method just as if it were acquired via the PrepareInstall() method.

The options vardict currently has no supported entries.

IN s name:

The name that will be used in the desktop file

IN v icon_v:

A #GBytesIcon icon as returned by g_icon_serialize(). Must be a png or jpeg no larger than 512x512, or an svg

IN a{sv} options:

Vardict with optional further information

OUT s token:

the token to be used with the Install() method

The Uninstall() method

Uninstall (IN  s     desktop_file_id,
           IN  a{sv} options);

This method deletes the desktop file and corresponding icon from the appropriate directories to remove the launcher referred to by desktop_file_id.

The desktop_file_id must have ".desktop" as a suffix. Except in the special case when the calling process has no associated app ID, desktop_file_id must have the app ID followed by a period as a prefix, regardless of whether the calling process is sandboxed or unsandboxed.

For example, Epiphany, which has the app ID "org.gnome.Epiphany" in stable builds, might use a desktop_file_id like "org.gnome.Epiphany.WebApp_e9d0e1e4b0a10856aa3b38d9eb4375de4070d043.desktop" In that example the desktop file would exist at the path "~/.local/share/xdg-desktop-portal/applications/org.gnome.Epiphany.WebApp_e9d0e1e4b0a10856aa3b38d9eb4375de4070d043.desktop" with a sym link in "~/.local/share/applications/". The checksum at the end of the file name is an implementation detail in Epiphany and not required by the portal.

This method is intended to be called by the application that created the launcher, e.g. a web browser, so it can clean up associated data as part of the uninstallation. Consequently, the proper way for a software center to remove a launcher is by using the APIs provided by the application that installed it. For example, for GNOME Software to remove web launchers created by Epiphany, it would use the org.gnome.Epiphany.WebAppProvider D-Bus interface.

Please note that this method call will fail if the specified launcher already does not exist.

The options vardict currently has no supported entries.

IN s desktop_file_id:

The .desktop file name

IN a{sv} options:

Vardict with optional further information

The GetDesktopEntry() method

GetDesktopEntry (IN  s desktop_file_id,
                 OUT s contents);

This function returns the contents of a desktop file with the name desktop_file_id in contents.

The desktop_file_id must have ".desktop" as a suffix. Except in the special case when the calling process has no associated app ID, desktop_file_id must have the app ID followed by a period as a prefix.

This method only works for desktop files that were created by the dynamic launcher portal.

IN s desktop_file_id:

The .desktop file name

OUT s contents:

the contents of the named .desktop file

The GetIcon() method

GetIcon (IN  s desktop_file_id,
         OUT v icon_v,
         OUT s icon_format,
         OUT u icon_size);

This function returns the contents of the icon specified in the "Icon" key of the desktop file with the name desktop_file_id in icon_v. The icon #GVariant can be passed to g_icon_deserialize() to reconstruct the #GIcon.

The desktop_file_id must have ".desktop" as a suffix. Except in the special case when the calling process has no associated app ID, desktop_file_id must have the app ID followed by a period as a prefix.

The format and size of the icon are returned in icon_format and icon_size. For svg icons, icon_size is currently always set to 4096, but don't depend on that as it may change in the future.

This method only works for desktop files that were created by the dynamic launcher portal.

IN s desktop_file_id:

The .desktop file name

OUT v icon_v:

the icon as a serialized #GBytesIcon

OUT s icon_format:

one of "png", "jpeg", "svg"

OUT u icon_size:

the width and height in pixels of the icon

The Launch() method

Launch (IN  s     desktop_file_id,
        IN  a{sv} options);

This function launches the app specified by desktop_file_id.

The desktop_file_id must have ".desktop" as a suffix. Except in the special case when the calling process has no associated app ID, desktop_file_id must have the app ID followed by a period as a prefix.

This method only works for desktop files that were created by the dynamic launcher portal.

Supported keys in the options vardict include:

activation_token s

A token that can be used to activate the chosen application.

The activation_token option was introduced in version 1 of the interface.

IN s desktop_file_id:

The .desktop file name

IN a{sv} options:

Vardict with optional further information

Property Details

The "SupportedLauncherTypes" property

SupportedLauncherTypes  readable   u

A bitmask of available launcher types. Currently defined types are:

1: Application. A launcher that represents an application.
2: Webapp. A launcher that represents a web app.

The "version" property

version  readable   u


Name

org.freedesktop.portal.Email — Portal for sending email

Methods

ComposeEmail (IN  s     parent_window,
              IN  a{sv} options,
              OUT o     handle);

Properties

version  readable   u

Description

This simple portal lets sandboxed applications request to send an email, optionally providing an address, subject, body and attachments.

This documentation describes version 4 of this interface.

Method Details

The ComposeEmail() method

ComposeEmail (IN  s     parent_window,
              IN  a{sv} options,
              OUT o     handle);

Presents a window that lets the user compose an email.

Note that the default email client for the host will need to support mailto: URIs following RFC 2368, with "cc", "bcc", "subject" and "body" query keys each corresponding to the email header of the same name, and with each attachment being passed as a "file://" URI as a value in an "attachment" query key.

For example:

mailto:foobar.com,bazbar.com?cc=ceobar.com&subject=Test20e-mail20subject&attachment=file://path/to/full/file.txt

would send a mail to "foobar.com", "bazbar.com", with a CC: to "ceobar.com", with the subject "Test e-mail subject" and the file pointed by URI "file://path/to/full/file.txt" as an attachment.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

address s

The email address to send to. Must conform to the HTML5 definition of valid email address.

addresses as

Email addresses to send to. This will be used in addition to address and must pass the same validation.

This option was added in version 3.

cc as

Email addresses to cc.

This option was added in version 3.

bcc as

Email addresses to bcc.

This option was added in version 3.

subject s

The subject for the email.

body s

The body for the email.

attachment_fds ah

File descriptors for files to attach.

activation_token s

A token that can be used to activate the chosen application.

The activation_token option was introduced in version 4 of the interface.

All the keys in the options are are optional.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.FileChooser — File chooser portal

Methods

OpenFile  (IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT o     handle);
SaveFile  (IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT o     handle);
SaveFiles (IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT o     handle);

Properties

version  readable   u

Description

The FileChooser portal allows sandboxed applications to ask the user for access to files outside the sandbox. The portal backend will present the user with 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/.

This documentation describes version 3 of this interface.

Method Details

The OpenFile() method

OpenFile (IN  s     parent_window,
          IN  s     title,
          IN  a{sv} options,
          OUT o     handle);

Asks to open one or more files.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

accept_label s

Label for the accept button. Mnemonic underlines are allowed.

modal b

Whether the dialog should be modal. Default is yes.

multiple b

Whether multiple files can be selected or not. Default is single-selection.

directory b

Whether to select for folders instead of files. Default is to select files. This option was added in version 3.

filters a(sa(us))

List of serialized file filters.

Each item in the array specifies a single filter to offer to the user. The first string is a user-visible name for the filter. The a(us) specifies a list of filter strings, which can be either a glob-style pattern (indicated by 0) or a mimetype (indicated by 1). Patterns are case-sensitive. To match different capitalizations of, e.g. '*.ico', use a pattern like '*.[iI][cC][oO]'.

Example: [('Images', [(0, '*.ico'), (1, 'image/png')]), ('Text', [(0, '*.txt')])]

Note that filters are purely there to aid the user in making a useful selection. The portal may still allow the user to select files that don't match any filter criteria, and applications must be prepared to handle that.

current_filter (sa(us))

Request that this filter be set by default at dialog creation. If the filters list is nonempty, it should match a filter in the list to set the default filter from the list. Alternatively, it may be specified when the list is empty to apply the filter unconditionally.

choices a(ssa(ss)s)

List of serialized combo boxes to add to the file chooser.

For each element, the first string is an ID that will be returned with the response, the second string is a user-visible label. The a(ss) is the list of choices, each being an ID and a user-visible label. The final string is the initial selection, or "", to let the portal decide which choice will be initially selected. None of the strings, except for the initial selection, should be empty.

As a special case, passing an empty array for the list of choices indicates a boolean choice that is typically displayed as a check button, using "true" and "false" as the choices.

Example: [('encoding', 'Encoding', [('utf8', 'Unicode (UTF-8)'), ('latin15', 'Western')], 'latin15'), ('reencode', 'Reencode', [], 'false')]

current_folder ay

Suggested folder from which the files should be opened. The byte array contains a path in the same encoding as the file system, and it's expected to be terminated by a nul byte.

If the path points to a location in the document storage, it will be replaced with the path to the location on the host.

The portal implementation is free to ignore this option.

The following results get returned via the "Response" signal:

uris as

An array of strings containing the uris of the selected files.

choices a(ss)

An array of pairs of strings, the first string being the ID of a combobox that was passed into this call, the second string being the selected option.

Example: [('encoding', 'utf8'), ('reencode', 'true')]

current_filter (sa(us))

The filter that was selected. This may match a filter in the filter list or another filter that was applied unconditionally.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SaveFile() method

SaveFile (IN  s     parent_window,
          IN  s     title,
          IN  a{sv} options,
          OUT o     handle);

Asks for a location to save a file.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

accept_label s

Label for the accept button. Mnemonic underlines are allowed.

modal b

Whether the dialog should be modal. Default is yes.

filters a(sa(us))

List of serialized file filters. See OpenFile() for details.

current_filter (sa(us))

Request that this filter be set by default at dialog creation. See OpenFile() for details.

choices a(ssa(ss)s)

List of serialized combo boxes. See OpenFile() for details.

current_name s

Suggested name of the file.

current_folder ay

Suggested folder in which the file should be saved. The byte array contains a path in the same encoding as the file system, and it's expected to be terminated by a nul byte.

If the path points to a location in the document storage, it will be replaced with the path to the location on the host.

The portal implementation is free to ignore this option.

current_file ay

The current file (when saving an existing file), in the same encoding as the file system. The byte array is expected to be terminated by a nul byte.

The following results get returned via the "Response" signal:

uris as

An array of strings containing the uri of the selected file.

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See OpenFile() for details.

current_filter (sa(us))

The filter that was selected. See OpenFile() for details.

current_folder ay

Suggested folder in which the file should be saved. The byte array contains a path in the same encoding as the file system, and it's expected to be terminated by a nul byte.

If the path points to a location in the document storage, it will be replaced with the path to the location on the host.

The portal implementation is free to ignore this option.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SaveFiles() method

SaveFiles (IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT o     handle);

Asks for a folder as a location to save one or more files. The names of the files will be used as-is and appended to the selected folder's path in the list of returned files. If the selected folder already contains a file with one of the given names, the portal may prompt or take some other action to construct a unique file name and return that instead.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

accept_label s

Label for the accept button. Mnemonic underlines are allowed.

modal b

Whether the dialog should be modal. Default is yes.

choices a(ssa(ss)s)

List of serialized combo boxes. See OpenFile() for details.

current_folder ay

Suggested folder in which the files should be saved. The byte array contains a path in the same encoding as the file system, and it's expected to be terminated by a nul byte.

If the path points to a location in the document storage, it will be replaced with the path to the location on the host.

The portal implementation is free to ignore this option.

files aay

An array of file names, using the same encoding as the file system, to be saved. Each byte array is expected to be terminated by a nul byte.

The following results get returned via the "Response" signal:

uris as

An array of strings containing the uri corresponding to each file given by options, in the same order. Note that the file names may have changed, for example if a file with the same name in the selected folder already exists.

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See OpenFile() for details.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.FileTransfer — Portal for transferring files between apps

Methods

StartTransfer (IN  a{sv} options,
               OUT s     key);
AddFiles      (IN  s     key,
               IN  ah    fds,
               IN  a{sv} options);
RetrieveFiles (IN  s     key,
               IN  a{sv} options,
               OUT as    files);
StopTransfer  (IN  s     key);

Signals

TransferClosed (s key);

Properties

version  readable   u

Description

The org.freedesktop.portal.FileTransfer portal operates as a middle-man between apps when transferring files via drag-and-drop or copy-paste, taking care of the necessary exporting of files in the document portal.

Toolkits are expected to use the application/vnd.portal.filetransfer mimetype when using this mechanism for file exchange via copy-paste or drag-and-drop.

The data that is transmitted with this mimetype should be the key returned by the StartTransfer() method. Upon receiving this mimetype, the target should call RetrieveFiles() with the key, to obtain the list of files. The portal will take care of exporting files in the document store as necessary to make them accessible to the target.

The D-Bus interface for the this portal is available under the bus name org.freedesktop.portal.Documents and the object path /org/freedesktop/portal/documents.

This documentation describes version 1 of this interface.

Method Details

The StartTransfer() method

StartTransfer (IN  a{sv} options,
               OUT s     key);

Starts a session for a file transfer. The caller should call AddFiles() at least once, to add files to this session.

Another application can then call RetrieveFiles() to obtain them, if it has the key.

Supported keys in the options vardict include:

writable b

Whether to allow the chosen application to write to the files. Default: False

This key only takes effect for files that need to be exported in the document portal for the receiving app. But it does require the passed-in file descriptors to be writable.

autostop b

Whether to stop the transfer automatically after the first RetrieveFiles() call. Default: True

IN a{sv} options:

Vardict with optional further information

OUT s key:

a key that needs to be passed to RetrieveFiles() to obtain the files

The AddFiles() method

AddFiles (IN  s     key,
          IN  ah    fds,
          IN  a{sv} options);

Adds files or directories to a session. This method can be called multiple times on a given session. Either regular files or directories can be added.

Note that the session bus often has a low limit of file descriptors per message (typically, 16), so you may have to send large lists with multiple AddFiles() calls.

The options vardict currently has no supported entries.

IN s key:

A key returned by StartTransfer()

IN ah fds:

File descriptors for the files or directories to register

IN a{sv} options:

Vardict with optional further information

The RetrieveFiles() method

RetrieveFiles (IN  s     key,
               IN  a{sv} options,
               OUT as    files);

Retrieves files or directories that were previously added to the session with AddFiles(). The files or directories will be exported in the document portal as-needed for the caller, and they will be writable if the owner of the session allowed it.

After the first RetrieveFiles() call, the session will be closed by the portal, unless autostop has been set to False.

The options vardict currently has no supported entries.

IN s key:

A key returned by StartTransfer()

IN a{sv} options:

Vardict with optional further information

OUT as files:

list of paths

The StopTransfer() method

StopTransfer (IN  s key);

Ends the transfer. Further calls to AddFiles() or RetrieveFiles() for this key will return an error.

IN s key:

A key returned by StartTransfer()

Signal Details

The "TransferClosed" signal

TransferClosed (s key);

The TransferClosed signal is emitted to the caller of StartTransfer when the transfer is closed.

s key:

key returned by StartTransfer

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Flatpak.UpdateMonitor

Methods

Close  ();
Update (IN  s     parent_window,
        IN  a{sv} options);

Signals

UpdateAvailable (a{sv} update_info);
Progress        (a{sv} info);

Description

Method Details

The Close() method

Close ();

Ends the update monitoring and cancels any ongoing installation.

The Update() method

Update (IN  s     parent_window,
        IN  a{sv} options);

see Common Conventions options: Vardict with optional further information

Asks to install an update of the calling app. During the installation, "Progress" signals will be emitted to communicate the status and progress.

Note that updates are only allowed if the new version has the same permissions (or less) than the currently installed version. If the new version requires a new permission then the operation will fail with the error org.freedesktop.DBus.Error.NotSupported and updates has to be done with the system tools.

Currently, no options are accepted.

IN s parent_window:

Identifier for the application window,

IN a{sv} options:

Signal Details

The "UpdateAvailable" signal

UpdateAvailable (a{sv} update_info);

Gets emitted when a new update is available. This is only sent once with the same information, but can be sent many times if new updates appear.

The following information may be included in the update_info dictionary:

running-commit s

The commit of the currently running instance.

local-commit s

The commit that is currently installed. Restarting the application will cause this commit to be used.

remote-commit s

The commit that is available as an update from the remote. Updating the application will deploy this commit.

a{sv} update_info:

More information about the available update

The "Progress" signal

Progress (a{sv} info);

Gets emitted to indicate progress of the installation. It's undefined exactly how often this is sent, but it will be emitted at least once at the end with non-zero status field. For each successful operation in the update we're also guaranteed to send one (and only one) signal with progress 100.

The following fields may be included in the info:

n_ops u

The number of operations that the update consists of.

op u

The position of the currently active operation.

progress u

The progress of the currently active operation, as a number between 0 and 100.

status u

The overall status of the update.

0: Running
1: Empty. No update to install
2: Done
3: Failed

error s

The error name, sent when status is Failed

error_message s

The error message, sent when status is Failed

a{sv} info:

More information about the update progress


Name

org.freedesktop.portal.Flatpak — Flatpak portal

Methods

Spawn               (IN  ay    cwd_path,
                     IN  aay   argv,
                     IN  a{uh} fds,
                     IN  a{ss} envs,
                     IN  u     flags,
                     IN  a{sv} options,
                     OUT u     pid);
SpawnSignal         (IN  u     pid,
                     IN  u     signal,
                     IN  b     to_process_group);
CreateUpdateMonitor (IN  a{sv} options,
                     OUT o     handle);

Signals

SpawnStarted (u pid,
              u relpid);
SpawnExited  (u pid,
              u exit_status);

Properties

version   readable   u
supports  readable   u

Description

The flatpak portal exposes some interactions with flatpak on the host to the sandbox. For example, it allows you to restart the applications or start a more sandboxed instance.

This portal is available on the D-Bus session bus under the bus name org.freedesktop.portal.Flatpak and the object path /org/freedesktop/portal/Flatpak.

This documentation describes version 6 of this interface.

Method Details

The Spawn() method

Spawn (IN  ay    cwd_path,
       IN  aay   argv,
       IN  a{uh} fds,
       IN  a{ss} envs,
       IN  u     flags,
       IN  a{sv} options,
       OUT u     pid);

IN ay cwd_path:

IN aay argv:

IN a{uh} fds:

IN a{ss} envs:

IN u flags:

IN a{sv} options:

OUT u pid:

The SpawnSignal() method

SpawnSignal (IN  u pid,
             IN  u signal,
             IN  b to_process_group);

This method lets you send a Unix signal to a process that was started with Spawn(). The pid argument here should be the PID that is returned by the Spawn() call: it is not necessarily valid in the caller's PID namespace.

IN u pid:

the PID inside the container to signal

IN u signal:

the signal to send (see signal(7))

IN b to_process_group:

whether to send the signal to the process group

The CreateUpdateMonitor() method

CreateUpdateMonitor (IN  a{sv} options,
                     OUT o     handle);

Creates an update monitor object that will emit signals when an update for the caller becomes available, and can be used to install it.

The handle will be of the form /org/freedesktop/portal/Flatpak/update_monitor/SENDER/TOKEN, where SENDER is the caller's unique name, with the initial ':' removed and all '.' replaced by '_', and TOKEN is a unique token that the caller can optionally provide with the 'handle_token' key in the options vardict.

Currently, no other options are accepted.

This was added in version 2 of this interface (available from flatpak 1.5.0 and later).

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Flatpak.UpdateMonitor object

Signal Details

The "SpawnStarted" signal

SpawnStarted (u pid,
              u relpid);

This is only non-zero if the expose PIDs flag (32) or the share PIDs flag (128) was passed to Spawn(), and it may still be zero if the process exits before its relative PID could be read.

Emitted when a process started by Spawn() has fully started. In other words, Spawn() returns once the sandbox has been started, and this signal is emitted once the process inside itself is started.

Only emitted by version 4 of this interface (available from flatpak 1.8.0 and later) and if the notify start flag (64) was passed to Spawn().

u pid:

the PID of the process that has been started

u relpid:

the PID of the process relative to the current namespace.

The "SpawnExited" signal

SpawnExited (u pid,
             u exit_status);

Emitted when a process started by Spawn() exits. Use g_spawn_check_exit_status(), or the macros such as WIFEXITED documented in waitpid(2), to interpret the exit_status.

This signal is not emitted for processes that were not launched directly by Spawn(), for example if a process launched by Spawn() runs foreground or background child processes.

u pid:

the PID of the process that has ended

u exit_status:

the wait status (see waitpid(2))

Property Details

The "version" property

version  readable   u

The "supports" property

supports  readable   u

Flags marking what optional features are available. The following flags values are supported:

1 (FLATPAK_SPAWN_SUPPORT_FLAGS_EXPOSE_PIDS)

Supports the expose sandbox pids flag of Spawn. If the version of this interface is 5 or later, this also indicates that the share sandbox pids flag is available.

This was added in version 3 of this interface (available from flatpak 1.6.0 and later).


Name

org.freedesktop.portal.GameMode — Portal for accessing GameMode

Methods

QueryStatus           (IN  i pid,
                       OUT i result);
RegisterGame          (IN  i pid,
                       OUT i result);
UnregisterGame        (IN  i pid,
                       OUT i result);
QueryStatusByPid      (IN  i target,
                       IN  i requester,
                       OUT i result);
RegisterGameByPid     (IN  i target,
                       IN  i requester,
                       OUT i result);
UnregisterGameByPid   (IN  i target,
                       IN  i requester,
                       OUT i result);
QueryStatusByPIDFd    (IN  h target,
                       IN  h requester,
                       OUT i result);
RegisterGameByPIDFd   (IN  h target,
                       IN  h requester,
                       OUT i result);
UnregisterGameByPIDFd (IN  h target,
                       IN  h requester,
                       OUT i result);

Properties

Active   readable   b
version  readable   u

Description

Interface for accessing GameMode from within the sandbox. It is analogous to the com.feralinteractive.GameMode interface and will proxy request there, but with additional permission checking and pid mapping. The latter is necessary in the case that sandbox has pid namespace isolation enabled. See the man page for pid_namespaces(7) for more details, but briefly, it means that the sandbox has its own process id namespace which is separated from the one on the host. Thus there will be two separate process ids (pids) within two different namespaces that both identify same process. One id from the pid namespace inside the sandbox and one id from the host pid namespace. Since org.freedesktop.portal.GameMode expects pids from the host pid namespace but programs inside the sandbox can only know pids from the sandbox namespace, process ids need to be translated from the portal to the host namespace. The portal will do that transparently for all calls where this is necessary.

Note: org.freedesktop.portal.GameMode will monitor active clients, i.e. games and other programs that have successfully called RegisterGame(). In the event that a client terminates without a call to the UnregisterGame() method, GameMode will automatically un-register the client. This might happen with a (small) delay.

This documentation describes version 4 of this interface.

Method Details

The QueryStatus() method

QueryStatus (IN  i pid,
             OUT i result);

Query the GameMode status for a process. If the caller is running inside a sandbox with pid namespace isolation, the pid will be translated to the respective host pid. See the general introduction for details. Will return: 0 if GameMode is inactive, 1 if GameMode is active, 2 if GameMode is active and pid is registered, -1 if the query failed inside GameMode

IN i pid:

Process id to query the GameMode status of

OUT i result:

The GameMode status for pid '

The RegisterGame() method

RegisterGame (IN  i pid,
              OUT i result);

Register a game with GameMode and thus request GameMode to be activated. If the caller is running inside a sandbox with pid namespace isolation, the pid will be translated to the respective host pid. See the general introduction for details. If the GameMode has already been requested for pid before, this call will fail, i.e. result will be -1. Will return: 0 if the game with pid was successfully registered, -1 if the request was rejected by GameMode

IN i pid:

Process id of the game to register

OUT i result:

Status of the request: 0 for success, -1 indicates an error

The UnregisterGame() method

UnregisterGame (IN  i pid,
                OUT i result);

Un-register a game from GameMode; if the call is successful and there are no other games or clients registered, GameMode will be deactivated. If the caller is running inside a sandbox with pid namespace isolation, the pid will be translated to the respective host pid. Will return: 0 if the game with pid was successfully un-registered, -1 if the request was rejected by GameMode

IN i pid:

Process id of the game to un-register

OUT i result:

Status of the request: 0 for success, -1 indicates an error

The QueryStatusByPid() method

QueryStatusByPid (IN  i target,
                  IN  i requester,
                  OUT i result);

Query the GameMode status for a process.

Like QueryStatus() but requester acting on behalf of target.

IN i target:

Process id to query the GameMode status of

IN i requester:

Process id of the process requesting the information

OUT i result:

The GameMode status for target

The RegisterGameByPid() method

RegisterGameByPid (IN  i target,
                   IN  i requester,
                   OUT i result);

Register a game with GameMode.

Like RegisterGame() but requester acting on behalf of target.

IN i target:

Process id of the game to register

IN i requester:

Process id of the process requesting the registration

OUT i result:

Status of the request: 0 for success, -1 indicates an error

The UnregisterGameByPid() method

UnregisterGameByPid (IN  i target,
                     IN  i requester,
                     OUT i result);

Un-register a game with GameMode.

Like UnregisterGame() but requester acting on behalf of target.

IN i target:

Process id of the game to un-register

IN i requester:

Process id of the process requesting the un-registration

OUT i result:

Status of the request: 0 for success, -1 indicates an error

The QueryStatusByPIDFd() method

QueryStatusByPIDFd (IN  h target,
                    IN  h requester,
                    OUT i result);

Query the GameMode status for a process.

Like QueryStatusByPid() but requester and target are pidfds representing the processes.

IN h target:

Pidfd to query the GameMode status of

IN h requester:

Pidfd of the process requesting the information

OUT i result:

The GameMode status for target

The RegisterGameByPIDFd() method

RegisterGameByPIDFd (IN  h target,
                     IN  h requester,
                     OUT i result);

Register a game with GameMode.

Like RegisterGameByPid() but requester and target are pidfds representing the processes.

IN h target:

Pidfd of the game to register

IN h requester:

Pidfd of the process requesting the registration

OUT i result:

Status of the request: 0 for success, -1 indicates an error

The UnregisterGameByPIDFd() method

UnregisterGameByPIDFd (IN  h target,
                       IN  h requester,
                       OUT i result);

Un-register a game with GameMode.

Like UnregisterGameByPid() but requester and target are pidfds representing the processes.

IN h target:

Pidfd of the game to un-register

IN h requester:

Pidfd of the process requesting the un-registration

OUT i result:

Status of the request: 0 for success, -1 indicates an error

Property Details

The "Active" property

Active  readable   b

Whether any pid on the system has enabled Game Mode.

The "version" property

version  readable   u


Name

org.freedesktop.portal.GlobalShortcuts

Methods

CreateSession (IN  a{sv}     options,
               OUT o         handle);
BindShortcuts (IN  o         session_handle,
               IN  a(sa{sv}) shortcuts,
               IN  s         parent_window,
               IN  a{sv}     options,
               OUT o         request_handle);
ListShortcuts (IN  o         session_handle,
               IN  a{sv}     options,
               OUT o         request_handle);

Signals

Activated        (o         session_handle,
                  s         shortcut_id,
                  t         timestamp,
                  a{sv}     options);
Deactivated      (o         session_handle,
                  s         shortcut_id,
                  t         timestamp,
                  a{sv}     options);
ShortcutsChanged (o         session_handle,
                  a(sa{sv}) shortcuts);

Properties

version  readable   u

Description

Method Details

The CreateSession() method

CreateSession (IN  a{sv} options,
               OUT o     handle);

Creates a global shortcuts session.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

The following results get returned via the "Response" signal:

session_handle o

The session handle. An object path for the org.freedesktop.portal.Session object representing the created session.

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The BindShortcuts() method

BindShortcuts (IN  o         session_handle,
               IN  a(sa{sv}) shortcuts,
               IN  s         parent_window,
               IN  a{sv}     options,
               OUT o         request_handle);

Bind the shortcuts. This will typically result the portal presenting a dialog showing the shortcuts and allowing users to configure the shortcuts. An application can only attempt bind shortcuts of a session once.

Each element of the shortcuts array is a tuple composed of a shortcut id, and a vardict with the following keys:

description s

User-readable text describing what the shortcut does.

preferred_trigger s

The preferred shortcut trigger, defined as described by the "shortcuts" XDG specification. Optional.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the "Response" signal:

shortcuts a(sa{sv})

A list of shortcuts. The list of keys it may contain is described below, and is different from the shortcuts variable of this method.

Each element of the shortcuts array returned by the "Response" signal is a tuple composed of a shortcut id, and a vardict with the following keys:

description s

User-readable text describing what the shortcut does.

trigger_description s

User-readable text describing how to trigger the shortcut for the client to render.

IN o session_handle:

Object path for the #org.freedesktop.impl.portal.Session object representing the session

IN a(sa{sv}) shortcuts:

The list of shortcuts to bind

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o request_handle:

Object path for the org.freedesktop.portal.Request object representing this call

The ListShortcuts() method

ListShortcuts (IN  o     session_handle,
               IN  a{sv} options,
               OUT o     request_handle);

Lists all shortcuts.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the "Response" signal:

shortcuts a(sa{sv})

A list of shortcuts.

See the "Response" signal of the BindShortcuts() method for the list of supported properties of shortcuts.

IN o session_handle:

Object path for the #org.freedesktop.impl.portal.Session object representing the session

IN a{sv} options:

Vardict with optional further information

OUT o request_handle:

Signal Details

The "Activated" signal

Activated (o     session_handle,
           s     shortcut_id,
           t     timestamp,
           a{sv} options);

Notifies about a shortcut becoming active.

o session_handle:

Session that requested the shortcut

s shortcut_id:

the application-provided ID for the notification

t timestamp:

the time of activation with millisecond granularity, with an undefined base.

a{sv} options:

Vardict with optional further information

The "Deactivated" signal

Deactivated (o     session_handle,
             s     shortcut_id,
             t     timestamp,
             a{sv} options);

Notifies that a shortcut is not active anymore.

o session_handle:

Session that requested the shortcut

s shortcut_id:

the application-provided ID for the notification

t timestamp:

the time of deactivation with millisecond granularity, with an undefined base.

a{sv} options:

Vardict with optional further information

The "ShortcutsChanged" signal

ShortcutsChanged (o         session_handle,
                  a(sa{sv}) shortcuts);

Indicates that the information associated with some of the shortcuts has changed.

See the "Response" signal of the BindShortcuts() method for the list of supported properties of shortcuts.

o session_handle:

Session that requested the shortcut

a(sa{sv}) shortcuts:

The different shortcuts that have been registered. See org.freedesktop.portal.GlobalShortcuts.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Inhibit — Portal for inhibiting session transitions

Methods

Inhibit          (IN  s     window,
                  IN  u     flags,
                  IN  a{sv} options,
                  OUT o     handle);
CreateMonitor    (IN  s     window,
                  IN  a{sv} options,
                  OUT o     handle);
QueryEndResponse (IN  o     session_handle);

Signals

StateChanged (o     session_handle,
              a{sv} state);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications inhibit the user session from ending, suspending, idling or getting switched away.

This documentation describes version 3 of this interface.

Method Details

The Inhibit() method

Inhibit (IN  s     window,
         IN  u     flags,
         IN  a{sv} options,
         OUT o     handle);

Inhibits a session status changes. To remove the inhibition, call Close() on the returned handle.

The flags determine what changes are inhibited:

1: Logout
2: User Switch
4: Suspend
8: Idle

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

reason s

User-visible reason for the inhibition.

IN s window:

Identifier for the window

IN u flags:

Flags identifying what is inhibited

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The CreateMonitor() method

CreateMonitor (IN  s     window,
               IN  a{sv} options,
               OUT o     handle);

Creates a monitoring session. While this session is active, the caller will receive StateChanged signals with updates on the session state.

A successfully created session can at any time be closed using org.freedesktop.portal.Session::Close, or may at any time be closed by the portal implementation, which will be signalled via "Closed".

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

The following results get returned via the "Response" signal:

session_handle o

The session handle. An object path for the org.freedesktop.portal.Session object representing the created session.

This method was added in version 2 of this interface.

IN s window:

the parent window

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The QueryEndResponse() method

QueryEndResponse (IN  o session_handle);

Acknowledges that the caller received the "StateChanged" signal. This method should be called within one second or receiving a StateChanged signal with the 'Query End' state.

Since version 3.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

Signal Details

The "StateChanged" signal

StateChanged (o     session_handle,
              a{sv} state);

The StateChanged signal is sent to active monitoring sessions when the session state changes.

When the session state changes to 'Query End', clients with active monitoring sessions are expected to respond by calling QueryEndResponse() within a second of receiving the StateChanged signal. They may call Inhibit() first to inhibit logout, to prevent the session from proceeding to the Ending state.

The following information may get returned in the state vardict:

screensaver-active b

Whether the screensaver is active.

session-state u

The state of the session. This member is new in version 3.

1: Running
2: Query End
3: Ending

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} state:

Vardict with information about the session state

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.InputCapture — Portal for permitting input capture

Methods

CreateSession      (IN  s      parent_window,
                    IN  a{sv}  options,
                    OUT o      handle);
GetZones           (IN  o      session_handle,
                    IN  a{sv}  options,
                    OUT o      handle);
SetPointerBarriers (IN  o      session_handle,
                    IN  a{sv}  options,
                    IN  aa{sv} barriers,
                    IN  u      zone_set,
                    OUT o      handle);
Enable             (IN  o      session_handle,
                    IN  a{sv}  options);
Disable            (IN  o      session_handle,
                    IN  a{sv}  options);
Release            (IN  o      session_handle,
                    IN  a{sv}  options);
ConnectToEIS       (IN  o      session_handle,
                    IN  a{sv}  options,
                    OUT h      fd);

Signals

Disabled     (o     session_handle,
              a{sv} options);
Activated    (o     session_handle,
              a{sv} options);
Deactivated  (o     session_handle,
              a{sv} options);
ZonesChanged (o     session_handle,
              a{sv} options);

Properties

SupportedCapabilities  readable   u
version                readable   u

Description

The InputCapture portal allows capture input events from connected physical or logical devices. Capturing input has two distinct states: "enabled" where an application has requested that input should be captured once certain conditions are met (but no input events are being delivered yet) and "active", when input events are being delivered to the application. An application can only control the "enabled" state, the compositor decides when to switch into the "active" state - and which devices to capture.

Once the compositor activates input capturing, events from physical or logical devices are sent directly to the application instead of using those events to update the pointer position on-screen. The compositor is in control of the input capturing and may filter events and/or stop capturing at any time.

Input capturing is an asynchronous operation using "triggers". An application sets up a number of triggers but it is the compositor who decides when the trigger conditions are met. Currently, the only defined trigger are pointer barriers: horizontal or vertical "lines" on the screen that should trigger when the cursor moves across those lines. See SetPointerBarriers().

There is currently no way for an application to activate immediate input capture.

The InputCapture portal merely *manages* the logic when input should be captured. The transport of actual input events is delegated to a transport layer, specifically libei. See ConnectToEIS().

This documentation describes version 1 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  s     parent_window,
               IN  a{sv} options,
               OUT o     handle);

Create a capture input session. A successfully created session can at any time be closed using Close(), or may at any time be closed by the portal implementation, which will be signalled via "Closed".

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

capabilities u

Bitmask of requested capabilities, see the SupportedCapabilities property. This value is required and must not be zero.

The following results get returned via the "Response" signal:

session_handle o

The session handle. An object path for the org.freedesktop.portal.Session object representing the created session.

capabilities u

The capabilities available to this session. This is always a subset of the requested capabilities. See the SupportedCapabilities property for details. Note that while a capability may be available to a session, there is no guarantee a device with that capability is currently available or if one does become available that it will trigger input capture.

It is best to view this set as a negative confirmation - a capability that was requested but is missing is an indication that this application may not capture events of that capability.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The GetZones() method

GetZones (IN  o     session_handle,
          IN  a{sv} options,
          OUT o     handle);

Retrieve the set of currently available input zones for this session. The zones may not be continuous and may be a logical representation of the physical screens (e.g. a 4k screen may be represented as low-resolution screen instead). A set of zones is identified by a unique zone_set ID.

The name "Zone" was chosen to provide distinction with the libei "Region".

If the zones change (e.g. a monitor is unplugged), the "ZonesChanged" signal is emitted and the application should re-request the current zones to update its internal state.

Note that zones are session-specific, there is no guarantee that two applications see the same screen zones. An empty zone list implies that no pointer barriers can be set.

Whenever the application calls GetZones, the current zone_set ID is returned that references the current set of zones. To establish a pointer barrier, the application must pass this ID to SetPointerBarriers(). A mismatch of zone_set IDs implies the application is not using the current zone set and pointer barriers will fail.

The zone_set ID increases by an unspecified amount with each change to the set of zones. Applications must be able to handle the zone_set ID wrapping around. Implementations of this portal must to increase the zone_set ID by a sensible amount to allow for wrapping detection.

The following results get returned via the "Response" signal:

zones a(uuii)

An array of regions, each specifying that zone's width, height, x/y offset.

zone_set u

A unique ID to be used in the SetPointerBarriers() method to refer to this set of zones. This id increases by an unspecified amount whenever the zones change and pointer barriers can only be set up if the zone_set matches the most recent returned zone_set.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SetPointerBarriers() method

SetPointerBarriers (IN  o      session_handle,
                    IN  a{sv}  options,
                    IN  aa{sv} barriers,
                    IN  u      zone_set,
                    OUT o      handle);

Set up zero or more pointer barriers. Pointer barriers are horizontal or vertical "lines" that should trigger the start of input capture when the cursor moves across the pointer barrier. After a successful Enable() call and when the compositor has deemed the pointer barrier to be crossed, input events (from compositor-determined input devices) are sent to the application via the transport layer.

Pointer barriers are situated on the top (for horizontal barriers) or left (for vertical barriers) edge of their respective pixels and their width or height is inclusive each pixel's width or height. In other words, a barrier spanning x1=0, x2=1 is exactly two pixels wide. A pointer barrier must be situated at the outside boundary of the union of all zones. A pointer barrier must be fully contained within one zone.

For example, consider two zones of size 1920x1080 with offsets 0,0 and 1920,0, respectively. (i.e. a left-right dual-monitor setup). The following pointer barriers are permitted:

  • top edge of left screen: x1=0,y1=0,x2=1919,y1=0

  • bottom edge of left screen: x1=0,y1=1080,x2=1919,y1=1080

  • top edge of right screen: x1=1920,y1=0,x2=3839,y1=0

  • bottom edge of right screen: x1=1920,y1=1080,x2=3839,y1=1080

  • left edge of left screen: x1=0,y1=0,x2=0,y1=1079

  • right edge of right screen: x1=3840,y1=0,x2=3840,y1=1079

A pointer barrier is considered triggered when the pointer would logically move off that zone, even if the actual cusor movement is clipped to the zone.

A zero-sized array of pointer barriers removes all existing pointer barriers for this session. Setting pointer barriers immediately suspends the current session and the application must call Enable() after this method.

The zone_set must be equivalent to the last returned zone_set of the GetZones() method. A mismatch of ids implies the application is not using the current zone set and pointer barriers will fail.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

Supported keys in the barriers vardicts include:

barrier_id u

The non-zero id of this barrier. This id is used in the "Activated" signal to inform which barrier triggered input capture.

position (iiii)

The x1/y1 x2/y2 position of the pointer barrier. A horizontal pointer barrier must have y1 == y2, a vertical pointer barrier must have x1 == x2. Diagonal pointer barriers are not supported.

The following results get returned via the "Response" signal:

failed_barriers au

An array of barrier_ids of pointer barriers that have been denied. The id matches the barrier_id of the entries in the barriers argument.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN aa{sv} barriers:

An array of vardicts, each specifying one barrier

IN u zone_set:

A unique zone_set ID referring to the zone set

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The Enable() method

Enable (IN  o     session_handle,
        IN  a{sv} options);

Enable input capturing. This does not immediately trigger capture, it merely enables the capturing to be triggered at some future point (e.g. by the cursor moving across a barrier). If and when that happens, the "Activated" signal is emitted.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The Disable() method

Disable (IN  o     session_handle,
         IN  a{sv} options);

Disable input capturing. No "Disabled" signal will be emitted.

If input capturing is currently ongoing, no "Deactivated" signal will be emitted.

Due to the asynchronous nature of this protocol, "Deactivated" and/or "Deactivated" signals may nevertheless be received by the application after a call to Enable().

Input events will not be captured until a subsequent Enable() call.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The Release() method

Release (IN  o     session_handle,
         IN  a{sv} options);

Release any ongoing input capture. No "Deactivated" signal will be emitted.

Due to the asynchronous nature of this protocol, a "Deactivated" signal may nevertheless be received by the application after a call to Release().

The activation_id provided in the options vardict specifies which currently ongoing input capture should be terminated. The asynchronous nature of this portal allows for an input capture to be Deactivated and a new input capture to be Activated before the client requests the Release for the previous input capture.

A compositor should ignore a Release() request for a no longer active activation_id.

Supported keys in the options vardict include:

activation_id u

The same activation_id number as in the "Activated" signal.

cursor_position (dd)

The suggested cursor position within the Zones available in this session.

This is a suggestion to the compositor to place the cursor in the correct position to allow for fluent movement between virtual screens. The compositor is not required to honor this suggestion.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The ConnectToEIS() method

ConnectToEIS (IN  o     session_handle,
              IN  a{sv} options,
              OUT h     fd);

Set up the connection to an active EIS implementation. Once input capturing starts, input events are sent via the EI protocol between the compositor and the application. This call must be invoked before Enable().

A session only needs to set this up once, the EIS implementation is not affected by calls to Disable() and Enable() - the same connection can be re-used until the session is closed.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT h fd:

A file descriptor to an active EIS implementation that can be passed to a passive libei context

Signal Details

The "Disabled" signal

Disabled (o     session_handle,
          a{sv} options);

The Disabled signal is emitted when the application will no longer receive captured input. If input capturing is currently ongoing, the "Deactivated" signal is emitted before this signal.

Applications must call Enable() to request future input capturing for this session.

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

The "Activated" signal

Activated (o     session_handle,
           a{sv} options);

The Activated signal is emitted when input capture starts and input events are about to be sent to the application.

This signal is only emitted after a prior call to Enable().

Supported keys in the options vardict include:

activation_id u

A number that can be used to synchronize with the transport-layer. This number has no intrinsic meaning but is guaranteed to increase by an unspecified amount on each call.

In particular: if the compositor sends a activation_id of N as part of this request it will also set the sequence in EIS' start_emulating event the same value N on the EIS connection before the first event from a device is sent. This allows an application to have a synchronization point and attribute an event sequence to the portal interaction.

Applications must be able to handle the activation_id number wrapping around. Implementations of this portal must increase the activation_id number by a sensible amount to allow for wrapping detection.

cursor_position (dd)

The current cursor position in the same coordinate space as the Zones. Note that this position is usually outside the Zones available to this session as all PointerBarriers are at the edge of their respective Zones.

For example, a fast movement against a barrier on the right edge of a screen may logically put the cursor dozens of pixels into the (non-existing) screen on the other side of the barrier. It is the application's responsibility to calculate and adjust the cursor position as necessary.

barrier_id u

The barrier id of the barrier that triggered. If the value is nonzero, it matches the barrier id as specified in SetPointerBarriers().

If the id is zero, the pointer barrier could not be determined. If the id is missing, the input capture was not triggered by a pointer barrier.

Where more than one pointer barrier are triggered by the same movement it is up to the compositor to choose one barrier (or use a barrier id of zero).

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

The "Deactivated" signal

Deactivated (o     session_handle,
             a{sv} options);

The Deactivated signal is emitted when input capture stopped and input events are no longer sent to the application. To prevent future input capture, an application must call Disable().

Supported keys in the options vardict include:

activation_id u

The same activation_id number as in the corresponding "Activated" signal.

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

The "ZonesChanged" signal

ZonesChanged (o     session_handle,
              a{sv} options);

The ZonesChanged signal is emitted when the set of zones available **to this session** change. An application should immediately call GetZones() to update its state of the zones followed by SetPointerBarriers() to re-establish the pointer barriers.

The ZonesChanged signal includes the zone_set ID of the set of zones invalidated, see #GetZones(). Due to the asynchronous nature of this protocol, the zone_set ID may identify a set of zones that the application has never (or not yet) seen. Applications must be able to handle unknown zone_set IDs. In particular, because the zone_set ID is guaranteed to increment, an application holding a zone_set ID higher than the ID in this signal can usually simply discard the signal.

Supported keys in the options vardict include:

zone_set u

The zone_set ID of the invalidated zone set as described in GetZones()

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

Property Details

The "SupportedCapabilities" property

SupportedCapabilities  readable   u

A bitmask of supported capabilities. This list is constant, it is not the list of capabilities currently available but rather which capabilies are implemented by the portal.

Applications must ignore unknown capabilities.

Currently defined types are:

1: KEYBOARD
2: POINTER
4: TOUCHSCREEN

The "version" property

version  readable   u


Name

org.freedesktop.portal.Location — Portal for obtaining information about the location

Methods

CreateSession (IN  a{sv} options,
               OUT o     handle);
Start         (IN  o     session_handle,
               IN  s     parent_window,
               IN  a{sv} options,
               OUT o     handle);

Signals

LocationUpdated (o     session_handle,
                 a{sv} location);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications query basic information about the location.

This documentation describes version 1 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  a{sv} options,
               OUT o     handle);

Create a location session. A successfully created session can at any time be closed using Close(), or may at any time be closed by the portal implementation, which will be signalled via "Closed".

Supported keys in the options vardict include:

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

distance-threshold u

Distance threshold in meters. Default is 0.

time-threshold u

Time threshold in seconds. Default is 0.

accuracy u

Requested accuracy. Default is EXACT. Values: NONE 0, COUNTRY 1, CITY 2, NEIGHBORHOOD 3, STREET 4, EXACT 5

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the created org.freedesktop.portal.Session object

The Start() method

Start (IN  o     session_handle,
       IN  s     parent_window,
       IN  a{sv} options,
       OUT o     handle);

Start the location session. An application can only attempt start a session once.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Signal Details

The "LocationUpdated" signal

LocationUpdated (o     session_handle,
                 a{sv} location);

The LocationUpdated signal is emitted when the location has changed, as well as when the initial location has been determined.

The following results may get returned via the location:

Latitude d

The latitude, in degrees.

Longitude d

The longitude, in degrees.

Altitude d

The altitude, in meters.

Accuracy d

The accuracy, in meters.

Speed d

The speed, in meters per second.

Heading d

The heading, in degrees, going clockwise. North 0, East 90, South 180, West 270.

Timestamp (tt)

The timestamp, as seconds and microseconds since the Unix epoch.

o session_handle:

Object path for the org.freedesktop.portal.Session object

a{sv} location:

Vardict with the current location data

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.MemoryMonitor — Memory monitoring portal

Signals

LowMemoryWarning (y level);

Properties

version  readable   u

Description

The Memory Monitor interface provides information about low system memory to sandboxed applications. It is not a portal in the strict sense, since it does not involve user interaction. Applications are expected to use this interface indirectly, via a library API such as the GLib GMemoryMonitor interface.

This documentation describes version 1 of this interface.

Signal Details

The "LowMemoryWarning" signal

LowMemoryWarning (y level);

Signal emitted when a particular low memory situation happens with 0 being the lowest level of memory availability warning, and 255 being the highest. Those levels are defined and documented in Low Memory Monitor's documentation.

y level:

An integer representing the level of low memory warning.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.NetworkMonitor — Network monitoring portal

Methods

GetAvailable    (OUT b     available);
GetMetered      (OUT b     metered);
GetConnectivity (OUT u     connectivity);
GetStatus       (OUT a{sv} status);
CanReach        (IN  s     hostname,
                 IN  u     port,
                 OUT b     reachable);

Signals

changed ();

Properties

version  readable   u

Description

The NetworkMonitor interface provides network status information to sandboxed applications. It is not a portal in the strict sense, since it does not involve user interaction. Applications are expected to use this interface indirectly, via a library API such as the GLib GNetworkMonitor interface.

This documentation describes version 3 of this interface.

Method Details

The GetAvailable() method

GetAvailable (OUT b available);

Returns whether the network is considered available. That is, whether the system as a default route for at least one of IPv4 or IPv6.

This method was added in version 2 to replace the available property.

OUT b available:

whether the network is available

The GetMetered() method

GetMetered (OUT b metered);

Returns whether the network is considered metered. That is, whether the system as traffic flowing through the default connection that is subject ot limitations by service providers.

This method was added in version 2 to replace the metered property.

OUT b metered:

whether the network is metered

The GetConnectivity() method

GetConnectivity (OUT u connectivity);

Returns more detailed information about the host's network connectivity. The meaning of the value is:

1: Local only. The host is not configured with a route to the internet.
2: Limited connectivity. The host is connected to a network, but can't reach the full internet.
3: Captive portal. The host is behind a captive portal and cannot reach the full internet.
4: Full network. The host connected to a network, and can reach the full internet.

This method was added in version 2 to replace the connectivity property.

OUT u connectivity:

the level of connectivity

The GetStatus() method

GetStatus (OUT a{sv} status);

Returns the three values all at once.

The following results get returned via status:

available b

Whether the network is available.

metered b

Whether the network is metered.

connectivity u

The level of connectivity.

This method was added in version 3 to avoid multiple round-trips.

OUT a{sv} status:

a dictionary with the current values

The CanReach() method

CanReach (IN  s hostname,
          IN  u port,
          OUT b reachable);

Returns whether the given hostname is believed to be reachable. This method was added in version 3.

IN s hostname:

the hostname to reach

IN u port:

the port to reach

OUT b reachable:

Whether the hostname:port was reachable

Signal Details

The "changed" signal

changed ();

Emitted when the network configuration changes.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Notification — Portal for sending notifications

Methods

AddNotification    (IN  s     id,
                    IN  a{sv} notification);
RemoveNotification (IN  s     id);

Signals

ActionInvoked (s  id,
               s  action,
               av parameter);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications send and withdraw notifications. It is not possible for the application to learn if the notification was actually presented to the user. Not a portal in the strict sense, since there is no user interaction.

Note that in contrast to most other portal requests, notifications are expected to outlast the running application. If a user clicks on a notification after the application has exited, it will get activated again.

Notifications can specify actions that can be activated by the user. Actions whose name starts with 'app.' are assumed to be exported and will be activated via the ActivateAction() method in the org.freedesktop.Application interface. Other actions are activated by sending the "ActionInvoked" signal to the application.

This documentation describes version 1 of this interface.

Method Details

The AddNotification() method

AddNotification (IN  s     id,
                 IN  a{sv} notification);

Sends a notification.

The ID can be used to later withdraw the notification. If the application reuses the same ID without withdrawing, the notification is replaced by the new one.

The format of the serialized notification is a vardict, with the following supported keys, all of which are optional:

title s

User-visible string to display as the title.

body s

User-visible string to display as the body.

icon v

Serialized icon (see g_icon_serialize()).

The portal only accepts serialized GThemedIcon and GBytesIcons. Both of these have the form (sv). For themed icons, the string is "themed", and the value is an array of strings containing the icon names. For bytes icons, the string is "bytes", and the value is a bytestring containing the icon data in png, jpeg or svg form. For historical reasons, it is also possible to send a simple string for themed icons with a single icon name.

There may be further restrictions on the supported kinds of icons.

priority s

The priority for the notification. Supported values: low, normal, high, urgent.

default-action s

Name of an action that is exported by the application. This action will be activated when the user clicks on the notification.

default-action-target v

Target parameter to send along when activating the default action.

buttons aa{sv}

Array of serialized buttons to add to the notification.

The format for serialized buttons is a vardict with the following supported keys:

label s

User-visible label for the button. Mandatory.

action s

Name of an action that is exported by the application. The action will be activated when the user clicks on the button. Mandatory.

target v

Target parameter to send along when activating the action.

IN s id:

Application-provided ID for this notification

IN a{sv} notification:

Vardict with the serialized notification

The RemoveNotification() method

RemoveNotification (IN  s id);

Withdraws a notification.

IN s id:

Application-provided ID for this notification

Signal Details

The "ActionInvoked" signal

ActionInvoked (s  id,
               s  action,
               av parameter);

for the action, if one was specified

Send to the application when a non-exported action is activated.

s id:

the application-provided ID for the notification

s action:

the name of the action

av parameter:

array which will contain the target parameter

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.OpenURI — Portal for opening URIs

Methods

OpenURI       (IN  s     parent_window,
               IN  s     uri,
               IN  a{sv} options,
               OUT o     handle);
OpenFile      (IN  s     parent_window,
               IN  h     fd,
               IN  a{sv} options,
               OUT o     handle);
OpenDirectory (IN  s     parent_window,
               IN  h     fd,
               IN  a{sv} options,
               OUT o     handle);

Properties

version  readable   u

Description

The OpenURI portal allows sandboxed applications to open URIs (e.g. a http: link to the applications homepage) under the control of the user.

This documentation describes version 4 of this interface.

Method Details

The OpenURI() method

OpenURI (IN  s     parent_window,
         IN  s     uri,
         IN  a{sv} options,
         OUT o     handle);

Asks to open a uri.

Note that file:// uris are explicitly not supported by this method. To request opening local files, use OpenFile().

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

writable b

Whether to allow the chosen application to write to the file.

This key only takes effect the uri points to a local file that is exported in the document portal, and the chosen application is sandboxed itself.

ask b

Whether to ask the user to choose an app. If this is not passed, or false, the portal may use a default or pick the last choice.

The ask option was introduced in version 3 of the interface.

activation_token s

A token that can be used to activate the chosen application.

The activation_token option was introduced in version 4 of the interface.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s uri:

The uri to open

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The OpenFile() method

OpenFile (IN  s     parent_window,
          IN  h     fd,
          IN  a{sv} options,
          OUT o     handle);

Asks to open a local file.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

writable b

Whether to allow the chosen application to write to the file.

This key only takes effect the uri points to a local file that is exported in the document portal, and the chosen application is sandboxed itself.

ask b

Whether to ask the user to choose an app. If this is not passed, or false, the portal may use a default or pick the last choice.

The ask option was introduced in version 3 of the interface.

activation_token s

A token that can be used to activate the chosen application.

The activation_token option was introduced in version 4 of the interface.

The OpenFile method was introduced in version 2 of the OpenURI portal API.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN h fd:

File descriptor for the file to open

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The OpenDirectory() method

OpenDirectory (IN  s     parent_window,
               IN  h     fd,
               IN  a{sv} options,
               OUT o     handle);

Asks to open the directory containing a local file in the file browser.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

activation_token s

A token that can be used to activate the chosen application.

The activation_token option was introduced in version 4 of the interface.

The OpenDirectory method was introduced in version 3 of the OpenURI portal API.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN h fd:

File descriptor for a file

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.PowerProfileMonitor — Power Profile monitoring portal

Properties

power-saver-enabled  readable   b
version              readable   u

Description

The Power Profile Monitor interface provides information about the user-selected system-wide power profile, to sandboxed applications. It is not a portal in the strict sense, since it does not involve user interaction. Applications are expected to use this interface indirectly, via a library API such as the GLib GPowerProfileMonitor interface.

This documentation describes version 1 of this interface.

Property Details

The "power-saver-enabled" property

power-saver-enabled  readable   b

Whether “Power Saver” mode is enabled on the system.

The "version" property

version  readable   u


Name

org.freedesktop.portal.Print — Portal for printing

Methods

Print        (IN  s     parent_window,
              IN  s     title,
              IN  h     fd,
              IN  a{sv} options,
              OUT o     handle);
PreparePrint (IN  s     parent_window,
              IN  s     title,
              IN  a{sv} settings,
              IN  a{sv} page_setup,
              IN  a{sv} options,
              OUT o     handle);

Properties

version  readable   u

Description

The Print portal allows sandboxed applications to print.

Due to the way in which printing requires bi-directional communication, using this portal will often require applications to make multiple requests. First, use PreparePrint() to obtain print settings, use them to format your output, then use Print() to print the formatted document. It is expected that high-level toolkit APIs such as GtkPrintOperation will hide most of this complexity.

This documentation describes version 2 of this interface.

Method Details

The Print() method

Print (IN  s     parent_window,
       IN  s     title,
       IN  h     fd,
       IN  a{sv} options,
       OUT o     handle);

Asks to print a file.

The file must be passed in the form of a file descriptor open for reading. This ensures that sandboxed applications only print files that they have access to.

If a valid token is present in the options, then this call will print with the settings from the Print call that the token refers to. If no token is present, then a print dialog will be presented to the user.

Note that it is up to the portal implementation to determine how long it considers tokens valid.

Supported keys in the options vardict:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

modal b

Whether to make the dialog modal. Defaults to yes.

token u

Token that was returned by a previous PreparePrint() call.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the print dialog

IN h fd:

File descriptor for reading the content to print

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The PreparePrint() method

PreparePrint (IN  s     parent_window,
              IN  s     title,
              IN  a{sv} settings,
              IN  a{sv} page_setup,
              IN  a{sv} options,
              OUT o     handle);

IN s parent_window:

IN s title:

IN a{sv} settings:

IN a{sv} page_setup:

IN a{sv} options:

OUT o handle:

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.ProxyResolver — Proxy information

Methods

Lookup (IN  s  uri,
        OUT as proxies);

Properties

version  readable   u

Description

The ProxyResolver interface provides network proxy information to sandboxed applications. It is not a portal in the strict sense, since it does not involve user interaction. Applications are expected to use this interface indirectly, via a library API such as the GLib GProxyResolver interface.

This documentation describes version 1 of this interface.

Method Details

The Lookup() method

Lookup (IN  s  uri,
        OUT as proxies);

Looks up which proxy to use to connect to uri. The returned proxy uri are of the form 'protocol://[user[:password]host:port'. The protocol can be http, rtsp, socks or another proxying protocol. 'direct://' is used when no proxy is needed.

IN s uri:

Destination to connect to

OUT as proxies:

List of proxy uris

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Realtime — Portal for setting threads to realtime

Methods

MakeThreadRealtimeWithPID     (IN  t process,
                               IN  t thread,
                               IN  u priority);
MakeThreadHighPriorityWithPID (IN  t process,
                               IN  t thread,
                               IN  i priority);

Properties

MaxRealtimePriority  readable   i
MinNiceLevel         readable   i
RTTimeUSecMax        readable   x
version              readable   u

Description

Interface for setting a thread to realtime from within the sandbox. It is analogous to the org.freedesktop.RealtimeKit1 interface and will proxy requests there but with pid mapping. The latter is necessary in the case that sandbox has pid namespace isolation enabled.

Note that this proxy does not bypass any limitations that RealtimeKit imposes on processes which are documented here: https://git.0pointer.net/rtkit.git/tree/README

This documentation describes version 1 of this interface.

Method Details

The MakeThreadRealtimeWithPID() method

MakeThreadRealtimeWithPID (IN  t process,
                           IN  t thread,
                           IN  u priority);

IN t process:

Process id

IN t thread:

Thread id

IN u priority:

Priority

The MakeThreadHighPriorityWithPID() method

MakeThreadHighPriorityWithPID (IN  t process,
                               IN  t thread,
                               IN  i priority);

IN t process:

Process id

IN t thread:

Thread id

IN i priority:

Priority

Property Details

The "MaxRealtimePriority" property

MaxRealtimePriority  readable   i

The "MinNiceLevel" property

MinNiceLevel  readable   i

The "RTTimeUSecMax" property

RTTimeUSecMax  readable   x

The "version" property

version  readable   u


Name

org.freedesktop.portal.RemoteDesktop — Remote desktop portal

Methods

CreateSession               (IN  a{sv} options,
                             OUT o     handle);
SelectDevices               (IN  o     session_handle,
                             IN  a{sv} options,
                             OUT o     handle);
Start                       (IN  o     session_handle,
                             IN  s     parent_window,
                             IN  a{sv} options,
                             OUT o     handle);
NotifyPointerMotion         (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  d     dx,
                             IN  d     dy);
NotifyPointerMotionAbsolute (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  d     x,
                             IN  d     y);
NotifyPointerButton         (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     button,
                             IN  u     state);
NotifyPointerAxis           (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  d     dx,
                             IN  d     dy);
NotifyPointerAxisDiscrete   (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     axis,
                             IN  i     steps);
NotifyKeyboardKeycode       (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     keycode,
                             IN  u     state);
NotifyKeyboardKeysym        (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     keysym,
                             IN  u     state);
NotifyTouchDown             (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  u     slot,
                             IN  d     x,
                             IN  d     y);
NotifyTouchMotion           (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  u     slot,
                             IN  d     x,
                             IN  d     y);
NotifyTouchUp               (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     slot);
ConnectToEIS                (IN  o     session_handle,
                             IN  a{sv} options,
                             OUT h     fd);

Properties

AvailableDeviceTypes  readable   u
version               readable   u

Description

The Remote desktop portal allows to create remote desktop sessions.

This documentation describes version 2 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  a{sv} options,
               OUT o     handle);

Create a remote desktop session.

A remote desktop session is used to allow remote controlling a desktop session.

A remote desktop session may only be started and stopped with this interface, but you can use the org.freedesktop.portal.Session object created with this method together with certain methods on the org.freedesktop.portal.ScreenCast and org.freedesktop.portal.Clipboard interfaces. Specifically, you can call SelectSources() to also get screen content, and OpenPipeWireRemote() to acquire a file descriptor for a PipeWire remote. See org.freedesktop.portal.ScreenCast for more information on how to use those methods. To capture clipboard content, you can call RequestClipboard(). See org.freedesktop.portal.Clipboard for more information on the clipboard integration.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

The following results get returned via the "Response" signal:

session_handle o

The session handle. An object path for the org.freedesktop.portal.Session object representing the created session.

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SelectDevices() method

SelectDevices (IN  o     session_handle,
               IN  a{sv} options,
               OUT o     handle);

Select input devices to remote control.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

types u

Bitmask of what device types to request remote controlling of. Default is all.

restore_token s

The token to restore a previous session.

If the stored session cannot be restored, this value is ignored and the user will be prompted normally. This may happen when, for example, the session contains a monitor or a window that is not available anymore, or when the stored permissions are withdrawn.

The restore token is invalidated after using it once. To restore the same session again, use the new restore token sent in response to starting this session.

This option was added in version 2 of this interface.

persist_mode u

How this session should persist. Default is 0. Accepted values are:

0: Do not persist (default)
1: Permissions persist as long as the application is running
2: Permissions persist until explicitly revoked

If the permission for the session to persist is granted, a restore token will be returned via the "Response" signal of the start method used to start the session.

This option was added in version 2 of this interface.

For available device types, see the AvailableDeviceTypes property.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The Start() method

Start (IN  o     session_handle,
       IN  s     parent_window,
       IN  a{sv} options,
       OUT o     handle);

Start the remote desktop session. This will typically result in the portal presenting a dialog letting the user select what to share, including devices and optionally screen content if screen cast sources was selected.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the "Response" signal:

devices u

A bitmask of the devices selected by the user.

clipboard_enabled b

A boolean for whether the clipboard was enabled ('true') or not ('false'). See the org.freedesktop.portal.Clipboard documentation for more information. Since version 2.

restore_token s

The restore token. This token is a single use token that can later be used to restore a session. See SelectDevices() for details.

This response option was added in version 2 of this interface.

If a screen cast source was selected, the results of the org.freedesktop.portal.ScreenCast.Start response signal may be included.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The NotifyPointerMotion() method

NotifyPointerMotion (IN  o     session_handle,
                     IN  a{sv} options,
                     IN  d     dx,
                     IN  d     dy);

Notify about a new relative pointer motion event. The (dx, dy) vector represents the new pointer position in the streams logical coordinate space.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN d dx:

Relative movement on the x axis

IN d dy:

Relative movement on the y axis

The NotifyPointerMotionAbsolute() method

NotifyPointerMotionAbsolute (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  d     x,
                             IN  d     y);

Notify about a new absolute pointer motion event. The (x, y) position represents the new pointer position in the streams logical coordinate space (see the logical_size stream property in org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN d x:

Pointer motion x coordinate

IN d y:

Pointer motion y coordinate

The NotifyPointerButton() method

NotifyPointerButton (IN  o     session_handle,
                     IN  a{sv} options,
                     IN  i     button,
                     IN  u     state);

The pointer button is encoded according to Linux Evdev button codes.

May only be called if POINTER access was provided after starting the session.

Available button states:

0: Released
1: Pressed

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i button:

The pointer button was pressed or released

IN u state:

The new state of the button

The NotifyPointerAxis() method

NotifyPointerAxis (IN  o     session_handle,
                   IN  a{sv} options,
                   IN  d     dx,
                   IN  d     dy);

The axis movement from a 'smooth scroll' device, such as a touchpad. When applicable, the size of the motion delta should be equivalent to the motion vector of a pointer motion done using the same advice.

May only be called if POINTER access was provided after starting the session.

Supported keys in the options vardict include:

finish b

If set to true, this is the last axis event in a series, for example as a result of the fingers being lifted from a touchpad after a two-finger scroll. Default is false.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN d dx:

Relative axis movement on the x axis

IN d dy:

Relative axis movement on the y axis

The NotifyPointerAxisDiscrete() method

NotifyPointerAxisDiscrete (IN  o     session_handle,
                           IN  a{sv} options,
                           IN  u     axis,
                           IN  i     steps);

May only be called if POINTER access was provided after starting the session.

Available axes:

0: Vertical scroll
1: Horizontal scroll

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u axis:

The axis that was scrolled

IN i steps:

The number of steps scrolled

The NotifyKeyboardKeycode() method

NotifyKeyboardKeycode (IN  o     session_handle,
                       IN  a{sv} options,
                       IN  i     keycode,
                       IN  u     state);

May only be called if KEYBOARD access was provided after starting the session.

Available keyboard keycode states:

0: Released
1: Pressed

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i keycode:

Keyboard code that was pressed or released

IN u state:

New state of keyboard keycode

The NotifyKeyboardKeysym() method

NotifyKeyboardKeysym (IN  o     session_handle,
                      IN  a{sv} options,
                      IN  i     keysym,
                      IN  u     state);

May only be called if KEYBOARD access was provided after starting the session.

Available keyboard keysym states:

0: Released
1: Pressed

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i keysym:

Keyboard symbol that was pressed or released

IN u state:

New state of keyboard keysym

The NotifyTouchDown() method

NotifyTouchDown (IN  o     session_handle,
                 IN  a{sv} options,
                 IN  u     stream,
                 IN  u     slot,
                 IN  d     x,
                 IN  d     y);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch down event. The (x, y) position represents the new touch point position in the streams logical coordinate space (see the logical_size stream property in org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN u slot:

Touch slot where touch point appeared

IN d x:

Touch down x coordinate

IN d y:

Touch down y coordinate

The NotifyTouchMotion() method

NotifyTouchMotion (IN  o     session_handle,
                   IN  a{sv} options,
                   IN  u     stream,
                   IN  u     slot,
                   IN  d     x,
                   IN  d     y);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch motion event. The (x, y) position represents where the touch point position in the streams logical coordinate space moved (see the logical_size stream property in org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN u slot:

Touch slot where touch point appeared

IN d x:

Touch motion x coordinate

IN d y:

Touch motion y coordinate

The NotifyTouchUp() method

NotifyTouchUp (IN  o     session_handle,
               IN  a{sv} options,
               IN  u     slot);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch up event.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u slot:

Touch slot where touch point appeared

The ConnectToEIS() method

ConnectToEIS (IN  o     session_handle,
              IN  a{sv} options,
              OUT h     fd);

Request a connection to an EIS implementation. The returned handle can be passed to ei_setup_backend_fd() for a libei sender context to complete the connection. All information about available devices and the event flow is subject to libei. Please see the libei documentation for details.

This method may only be called once per session, where the EIS implementation disconnects the session should be closed.

This method must be called after #Start()

Once an EIS connection is established, input events must be sent exclusively via the EIS connection. Any events submitted via NotifyPointerMotion, NotifyKeyboardKeycode and other Notify* methods will return an error.

To see how to pair a PipeWire stream with a libei device region, see the documentation for the mapping_id stream property in #Start().

This method was added in version 2 of this interface.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT h fd:

A file descriptor to an EIS implementation that can be passed to a libei sender context

Property Details

The "AvailableDeviceTypes" property

AvailableDeviceTypes  readable   u

A bitmask of available source types. Currently defined types are:

1: KEYBOARD
2: POINTER
4: TOUCHSCREEN

The "version" property

version  readable   u


Name

org.freedesktop.portal.Request — Shared request interface

Methods

Close ();

Signals

Response (u     response,
          a{sv} results);

Description

The Request interface is shared by all portal interfaces. When a portal method is called, the reply includes a handle (i.e. object path) for a Request object, which will stay alive for the duration of the user interaction related to the method call.

The portal indicates that a portal request interaction is over by emitting the "Response" signal on the Request object.

The application can abort the interaction calling Close() on the Request object.

Since version 0.9 of xdg-desktop-portal, the handle will be of the form /org/freedesktop/portal/desktop/request/SENDER/TOKEN, where SENDER is the callers unique name, with the initial ':' removed and all '.' replaced by '_', and TOKEN is a unique token that the caller provided with the handle_token key in the options vardict.

This change was made to let applications subscribe to the Response signal before making the initial portal call, thereby avoiding a race condition. It is recommended that the caller should verify that the returned handle is what it expected, and update its signal subscription if it isn't. This ensures that applications will work with both old and new versions of xdg-desktop-portal.

The token that the caller provides should be unique and not guessable. To avoid clashes with calls made from unrelated libraries, it is a good idea to use a per-library prefix combined with a random number.

Method Details

The Close() method

Close ();

Closes the portal request to which this object refers and ends all related user interaction (dialogs, etc). A Response signal will not be emitted in this case.

Signal Details

The "Response" signal

Response (u     response,
          a{sv} results);

Emitted when the user interaction for a portal request is over.

The response indicates how the user interaction ended:

0: Success, the request is carried out
1: The user cancelled the interaction
2: The user interaction was ended in some other way

u response:

Numeric response

a{sv} results:

Vardict with results. The keys and values in the vardict depend on the request.


Name

org.freedesktop.portal.ScreenCast — Screen cast portal

Methods

CreateSession      (IN  a{sv} options,
                    OUT o     handle);
SelectSources      (IN  o     session_handle,
                    IN  a{sv} options,
                    OUT o     handle);
Start              (IN  o     session_handle,
                    IN  s     parent_window,
                    IN  a{sv} options,
                    OUT o     handle);
OpenPipeWireRemote (IN  o     session_handle,
                    IN  a{sv} options,
                    OUT h     fd);

Properties

AvailableSourceTypes  readable   u
AvailableCursorModes  readable   u
version               readable   u

Description

The Screen cast portal allows to create screen cast sessions.

This documentation describes version 5 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  a{sv} options,
               OUT o     handle);

Create a screen cast session. A successfully created session can at any time be closed using Close(), or may at any time be closed by the portal implementation, which will be signalled via "Closed".

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

session_handle_token s

A string that will be used as the last element of the session handle. Must be a valid object path element. See the org.freedesktop.portal.Session documentation for more information about the session handle.

The following results get returned via the "Response" signal:

session_handle o

The session handle. An object path for the org.freedesktop.portal.Session object representing the created session.

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SelectSources() method

SelectSources (IN  o     session_handle,
               IN  a{sv} options,
               OUT o     handle);

Configure what the screen cast session should record. This method must be called before starting the session.

Passing invalid input to this method will cause the session to be closed. An application may only attempt to select sources once per session.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

types u

Bitmask of what types of content to record. Default is MONITOR.

multiple b

Whether to allow selecting multiple sources. Default is no.

cursor_mode u

Determines how the cursor will be drawn in the screen cast stream. It must be one of the cursor modes advertised in org.freedesktop.portal.ScreenCast.AvailableCursorModes. Setting a cursor mode not advertised will cause the screen cast session to be closed. The default cursor mode is 'Hidden'.

This option was added in version 2 of this interface.

restore_token s

The token to restore a previous session.

If the stored session cannot be restored, this value is ignored and the user will be prompted normally. This may happen when, for example, the session contains a monitor or a window that is not available anymore, or when the stored permissions are withdrawn.

The restore token is invalidated after using it once. To restore the same session again, use the new restore token sent in response to starting this session.

Setting a restore_token is only allowed for screen cast sessions. Persistent remote desktop screen cast sessions can only be handled via the org.freedesktop.portal.RemoteDesktop interface.

This option was added in version 4 of this interface.

persist_mode u

How this session should persist. Default is 0. Accepted values are:

0: Do not persist (default)
1: Permissions persist as long as the application is running
2: Permissions persist until explicitly revoked

Setting persist_mode is only allowed for screen cast sessions. Persistent remote desktop screen cast sessions can only be handled via the org.freedesktop.portal.RemoteDesktop interface.

If the permission for the session to persist is granted, a restore token will be returned via the "Response" signal of the org.freedesktop.portal.ScreenCast.Start method.

This option was added in version 4 of this interface.

For available source types, see the AvailableSourceTypes property.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The Start() method

Start (IN  o     session_handle,
       IN  s     parent_window,
       IN  a{sv} options,
       OUT o     handle);

Start the screen cast session. This will typically result the portal presenting a dialog letting the user do the selection set up by SelectSources(). An application can only attempt start a session once.

A screen cast session may only be started after having selected sources using SelectSources().

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the "Response" signal:

streams a(ua{sv})

An array of PipeWire streams. Each stream consists of a PipeWire node ID (the first element in the tuple, and a Vardict of properties.

The array will contain a single stream if 'multiple' (see SelectSources()) was set to 'false', or at least one stream if 'multiple' was set to 'true' as part of the SelectSources() method.

restore_token s

The restore token. This token is a single use token that can later be used to restore a session. See SelectSources() for details.

This response option was added in version 4 of this interface.

Stream properties include:

id s

Opaque identifier. Will be unique for this stream and local to this session. Will persist with future sessions, if they are restored using a restore token. This property was added in version 4 of this interface. Optional.

position (ii)

A tuple consisting of the position (x, y) in the compositor coordinate space. Note that the position may not be equivalent to a position in a pixel coordinate space. Only available for monitor streams. Optional.

size (ii)

A tuple consisting of (width, height). The size represents the size of the stream as it is displayed in the compositor coordinate space. Note that this size may not be equivalent to a size in a pixel coordinate space. The size may differ from the size of the stream. Optional.

source_type u

The type of the content which is being screen casted. For available source types, see the AvailableSourceTypes property. This property was added in version 3 of this interface.

mapping_id s

An optional identifier used to map different aspects of the resource this stream corresponds to.

When used in a remote desktop session, the mapping_id can be used to match a libei region of absolute libei devices. There may be multiple absolute libei devices, and each device may have multiple regions, but a mapping_id will only match one of these regions per device. This property was added in version 5 of this interface.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The OpenPipeWireRemote() method

OpenPipeWireRemote (IN  o     session_handle,
                    IN  a{sv} options,
                    OUT h     fd);

Open a file descriptor to the PipeWire remote where the screen cast streams are available. The file descriptor should be used to create a pw_core object, by using pw_context_connect_fd. Only the screen cast stream nodes will be available from this PipeWire node.

IN o session_handle:

Object path for the org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

OUT h fd:

File descriptor of an open PipeWire remote.

Property Details

The "AvailableSourceTypes" property

AvailableSourceTypes  readable   u

A bitmask of available source types. Currently defined types are:

1: MONITOR
2: WINDOW
4: VIRTUAL

The "AvailableCursorModes" property

AvailableCursorModes  readable   u

A bitmask of available cursor modes.

Available cursor mode values:

1: Hidden. The cursor is not part of the screen cast stream.
2: Embedded: The cursor is embedded as part of the stream buffers.
4: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.

This property was added in version 2 of this interface.

The "version" property

version  readable   u


Name

org.freedesktop.portal.Screenshot — Portal for taking screenshots

Methods

Screenshot (IN  s     parent_window,
            IN  a{sv} options,
            OUT o     handle);
PickColor  (IN  s     parent_window,
            IN  a{sv} options,
            OUT o     handle);

Properties

version  readable   u

Description

This simple portal lets sandboxed applications request a screenshot.

The screenshot 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/.

This documentation describes version 2 of this interface.

Method Details

The Screenshot() method

Screenshot (IN  s     parent_window,
            IN  a{sv} options,
            OUT o     handle);

Takes a screenshot.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

modal b

Whether the dialog should be modal. Default is yes.

interactive b

Hint whether the dialog should offer customization before taking a screenshot. Default is no. Since version 2.

The following results get returned via the "Response" signal:

uri s

String containing the uri of the screenshot.

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The PickColor() method

PickColor (IN  s     parent_window,
           IN  a{sv} options,
           OUT o     handle);

Obtains the color of a single pixel.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the "Response" signal:

color (ddd)

The color, rgb values in the range [0,1].

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Secret — Portal for retrieving application secret

Methods

RetrieveSecret (IN  h     fd,
                IN  a{sv} options,
                OUT o     handle);

Properties

version  readable   u

Description

The Secret portal allows sandboxed applications to retrieve a per-application secret. The secret can then be used for encrypting confidential data inside the sandbox.

This documentation describes version 1 of this interface.

Method Details

The RetrieveSecret() method

RetrieveSecret (IN  h     fd,
                IN  a{sv} options,
                OUT o     handle);

Retrieves a master secret for a sandboxed application.

The master secret is unique per application and does not change as long as the application is installed (once it has been created). In a typical backend implementation, it is stored in the user's keyring, under the application ID as a key.

While the master secret can be used for encrypting any confidential data in the sandbox, the format is opaque to the application. In particular, the length of the secret might not be sufficient for the use with certain encryption algorithm. In that case, the application is supposed to expand it using a KDF algorithm.

The portal may return an additional identifier associated with the secret in the results vardict of "Response" signal. In the next call of this method, the application shall indicate it through a token element in options.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the org.freedesktop.portal.Request documentation for more information about the handle.

token s

An opaque string returned by a previous RetrieveSecret() call.

IN h fd:

Writable file descriptor for transporting the secret

IN a{sv} options:

Vardict with optional further information

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Session — Shared session interface

Methods

Close ();

Signals

Closed (a{sv} details);

Properties

version  readable   u

Description

The Session interface is shared by all portal interfaces that involve long lived sessions. When a method that creates a session is called, if successful, the reply will include a session handle (i.e. object path) for a Session object, which will stay alive for the duration of the session.

The duration of the session is defined by the interface that creates it. For convenience, the interface contains a method Close(), and a signal "Closed". Whether it is allowed to directly call Close() depends on the interface.

The handle of a session will be of the form /org/freedesktop/portal/desktop/session/SENDER/TOKEN, where SENDER is the callers unique name, with the initial ':' removed and all '.' replaced by '_', and TOKEN is a unique token that the caller provided with the session_handle_token key in the options vardict of the method creating the session.

The token that the caller provides should be unique and not guessable. To avoid clashes with calls made from unrelated libraries, it is a good idea to use a per-library prefix combined with a random number.

A client who started a session vanishing from the D-Bus is equivalent to closing all active sessions made by said client.

Method Details

The Close() method

Close ();

Closes the portal session to which this object refers and ends all related user interaction (dialogs, etc).

Signal Details

The "Closed" signal

Closed (a{sv} details);

Emitted when a session is closed.

The content of details is specified by the interface creating the session.

a{sv} details:

A key value Vardict with details about the closed session.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Settings — Settings interface

Methods

ReadAll (IN  as        namespaces,
         OUT a{sa{sv}} value);
Read    (IN  s         namespace,
         IN  s         key,
         OUT v         value);
ReadOne (IN  s         namespace,
         IN  s         key,
         OUT v         value);

Signals

SettingChanged (s namespace,
                s key,
                v value);

Properties

version  readable   u

Description

This interface provides read-only access to a small number of host settings required for toolkits similar to XSettings. It is not for general purpose settings.

Currently the interface provides the following keys:

org.freedesktop.appearance color-scheme u

Indicates the system's preferred color scheme. Supported values are:

0: No preference
1: Prefer dark appearance
2: Prefer light appearance

Unknown values should be treated as 0 (no preference).

org.freedesktop.appearance accent-color (ddd)

Indicates the system's preferred accent color as a tuple of RGB values in the sRGB color space, in the range [0,1]. Out-of-range RGB values should be treated as an unset accent color.

Implementations can provide other keys; they are entirely implementation details that are undocumented. If you are a toolkit and want to use this please open an issue.

This documentation describes version 2 of this interface.

Method Details

The ReadAll() method

ReadAll (IN  as        namespaces,
         OUT a{sa{sv}} value);

If namespaces is an empty array or contains an empty string it matches all. Globbing is supported but only for trailing sections, e.g. "org.example.*".

IN as namespaces:

List of namespaces to filter results by, supports simple globbing explained below.

OUT a{sa{sv}} value:

Dictionary of namespaces to its keys and values.

The Read() method

Read (IN  s namespace,
      IN  s key,
      OUT v value);

Reads a single value. Returns an error on any unknown namespace or key.

Deprecated, use ReadOne instead. The value argument was intended to have the value inside one layer of variant as it is in ReadOne, for example `<string "hello">` in GVariant text notation; but it is actually returned inside two layers of variant, for example `<<string "hello">>`.

IN s namespace:

Namespace to look up key in.

IN s key:

The key to get.

OUT v value:

The value key is set to.

Warning

The Read() method is deprecated.

The ReadOne() method

ReadOne (IN  s namespace,
         IN  s key,
         OUT v value);

Reads a single value which may be any valid DBus type. Returns an error on any unknown namespace or key.

This method was added in version 2.

IN s namespace:

Namespace to look up key in.

IN s key:

The key to get.

OUT v value:

The value key is set to.

Signal Details

The "SettingChanged" signal

SettingChanged (s namespace,
                s key,
                v value);

Emitted when a setting changes.

s namespace:

Namespace of changed setting.

s key:

The key of changed setting.

v value:

The new value.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Trash — Portal for trashing files

Methods

TrashFile (IN  h fd,
           OUT u result);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications send files to the trashcan.

This documentation describes version 1 of this interface.

Method Details

The TrashFile() method

TrashFile (IN  h fd,
           OUT u result);

Sends a file to the trashcan. Applications are allowed to trash a file if they can open it in r/w mode.

IN h fd:

file descriptor for the file to trash

OUT u result:

the result. 0 if trashing failed, 1 if trashing succeeded, other values may be returned in the future

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Wallpaper — Portal for setting the desktop's Wallpaper

Methods

SetWallpaperURI  (IN  s     parent_window,
                  IN  s     uri,
                  IN  a{sv} options,
                  OUT o     handle);
SetWallpaperFile (IN  s     parent_window,
                  IN  h     fd,
                  IN  a{sv} options,
                  OUT o     handle);

Properties

version  readable   u

Description

This simple interface lets sandboxed applications set the user's desktop background picture.

This documentation describes version 1 of this interface.

Method Details

The SetWallpaperURI() method

SetWallpaperURI (IN  s     parent_window,
                 IN  s     uri,
                 IN  a{sv} options,
                 OUT o     handle);

Asks to set a given picture as the desktop background picture.

Note that file: uris are explicitly not supported here. To use a local image file as background, use the SetWallpaperFile() method.

Supported keys in the options vardict include:

show-preview b

whether to show a preview of the picture. Note that the portal may decide to show a preview even if this option is not set

set-on s

where to set the wallpaper. Possible values are 'background', 'lockscreen' or 'both'

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s uri:

The picture file uri

IN a{sv} options:

Options that influence the behavior of the portal

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

The SetWallpaperFile() method

SetWallpaperFile (IN  s     parent_window,
                  IN  h     fd,
                  IN  a{sv} options,
                  OUT o     handle);

Asks to set a given local file as the desktop background picture.

Supported keys in the options vardict include:

show-preview b

whether to show a preview of the picture. Note that the portal may decide to show a preview even if this option is not set

set-on s

where to set the wallpaper. Possible values are 'background', 'lockscreen' or 'both'

IN s parent_window:

Identifier for the application window, see Common Conventions

IN h fd:

File descriptor for the file to open

IN a{sv} options:

Options that influence the behavior of the portal

OUT o handle:

Object path for the org.freedesktop.portal.Request object representing this call

Property Details

The "version" property

version  readable   u

Portal Backend API Reference


The backend interfaces are used by the portal frontend to carry out portal requests. They are provided by a separate process (or processes), and are not accessible to sandboxed applications.

The separation of the portal infrastructure into frontend and backend is a clean way to provide suitable user interfaces that fit into different desktop environments, while sharing the portal frontend.

The portal backends are focused on providing user interfaces and accessing session- or host-specific APIs and resources. Details of interacting with the containment infrastructure such as checking access, registering files in the document portal, etc., are handled by the portal frontend.

Table of Contents

org.freedesktop.impl.portal.Access — Interface for presenting an access dialog
org.freedesktop.impl.portal.Account — Backend for the portal for obtaining user information
org.freedesktop.impl.portal.AppChooser — Interface for choosing an application
org.freedesktop.impl.portal.Background — Background portal backend interface
org.freedesktop.impl.portal.Clipboard
org.freedesktop.impl.portal.Email — Email portal backend interface
org.freedesktop.impl.portal.FileChooser — File chooser portal backend interface
org.freedesktop.impl.portal.GlobalShortcuts
org.freedesktop.impl.portal.Inhibit — Inhibit portal backend interface
org.freedesktop.impl.portal.InputCapture — Capture input portal backend interface
org.freedesktop.impl.portal.Lockdown — Lockdown backend interface
org.freedesktop.impl.portal.Notification — Notification portal backend interface
org.freedesktop.impl.portal.PermissionStore — Database to store permissions
org.freedesktop.impl.portal.Print — Print portal backend interface
org.freedesktop.impl.portal.RemoteDesktop — Remote desktop portal backend interface
org.freedesktop.impl.portal.Request — Shared request interface
org.freedesktop.impl.portal.ScreenCast — Screen cast portal backend interface
org.freedesktop.impl.portal.Screenshot — Screenshot portal backend interface
org.freedesktop.impl.portal.Secret — Secret portal backend interface
org.freedesktop.impl.portal.Session — Shared session interface
org.freedesktop.impl.portal.Settings — Settings portal backend interface
org.freedesktop.impl.portal.Wallpaper — Portal for setting the desktop's Wallpaper

Name

org.freedesktop.impl.portal.Access — Interface for presenting an access dialog

Methods

AccessDialog (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  s     title,
              IN  s     subtitle,
              IN  s     body,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Description

This backend can be used by portal implementations that need to ask a direct access question, such as "May xyz use the microphone?"

Method Details

The AccessDialog() method

AccessDialog (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  s     title,
              IN  s     subtitle,
              IN  s     body,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Presents a "deny/grant" question to the user.

Supported keys in the options include:

modal b

Whether to make the dialog modal. Defaults to true.

deny_label s

Label for the Deny button.

grant_label s

Label for the Grant button.

icon s

Icon name for an icon to show in the dialog. This should be a symbolic icon name.

choices a(ssa(ss)s)

List of serialized choices. See org.freedesktop.portal.FileChooser.OpenFile() for details.

The following results get returned via the results vardict:

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See org.freedesktop.portal.FileChooser.OpenFile() for details.

IN o handle:

Object path to export the Request object at

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the dialog

IN s subtitle:

Subtitle for the dialog

IN s body:

Body text, may be ""

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

org.freedesktop.impl.portal.Account — Backend for the portal for obtaining user information

Methods

GetUserInformation (IN  o     handle,
                    IN  s     app_id,
                    IN  s     window,
                    IN  a{sv} options,
                    OUT u     response,
                    OUT a{sv} results);

Description

This Account portal lets sandboxed applications query basic information about the user, like their name and avatar photo. The portal backend will present the user with a dialog to confirm which (if any) information to share.

Method Details

The GetUserInformation() method

GetUserInformation (IN  o     handle,
                    IN  s     app_id,
                    IN  s     window,
                    IN  a{sv} options,
                    OUT u     response,
                    OUT a{sv} results);

Gets information about the user.

Supported keys in the options vardict include:

reason s

A string that can be shown in the dialog to expain why the information is needed. This should be a complete sentence that explains what the application will do with the returned information, for example: Allows your personal information to be included with recipes you share with your friends.

The following results get returned via the results vardict:

id s

The user id.

name s

The users real name.

image s

The uri of an image file for the users avatar photo.

IN o handle:

Object path for the #org.freedesktop.portal.Request object representing this call

IN s app_id:

App id of the application

IN s window:

Identifier for the window

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

org.freedesktop.impl.portal.AppChooser — Interface for choosing an application

Methods

ChooseApplication (IN  o     handle,
                   IN  s     app_id,
                   IN  s     parent_window,
                   IN  as    choices,
                   IN  a{sv} options,
                   OUT u     response,
                   OUT a{sv} results);
UpdateChoices     (IN  o     handle,
                   IN  as    choices);

Description

This backend can be used by portal implementations that need to choose an application from a list of applications.

This documentation describes version 2 of this interface.

Method Details

The ChooseApplication() method

ChooseApplication (IN  o     handle,
                   IN  s     app_id,
                   IN  s     parent_window,
                   IN  as    choices,
                   IN  a{sv} options,
                   OUT u     response,
                   OUT a{sv} results);

Presents a list of applications to the user to choose one.

Supported keys in the options vardict include:

last_choice s

The app id that was selected the last time.

modal b

Whether to make the dialog modal. Defaults to yes.

content_type s

The content type to choose an application for.

uri s

The uri to choose an application for.

filename s

The filename to choose an application for. Note that this is just a basename, without a path.

activation_token s

A token that can be used to activate the application chooser.

The activation_token option was introduced in version 2 of the interface.

The following results get returned via the results vardict:

choice s

The app id that was selected.

activation_token s

A token that can be used to activate the chosen application. If the application selection has involved user interaction, a new token should be generated by the portal implementation. Otherwise, this token may be the same as the one passed in options.

The activation_token option was introduced in version 2 of the interface.

IN o handle:

Object path to export the Request object at

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN as choices:

App ids of applications to let the user choose from

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The UpdateChoices() method

UpdateChoices (IN  o  handle,
               IN  as choices);

This method can be called between the time of a ChooseApplication call and receiving the Response signal, to update the list of applications that are offered by the backend.

IN o handle:

the request handle

IN as choices:

App ids of applications to let the user choose from


Name

org.freedesktop.impl.portal.Background — Background portal backend interface

Methods

GetAppState      (OUT a{sv} apps);
NotifyBackground (IN  o     handle,
                  IN  s     app_id,
                  IN  s     name,
                  OUT u     response,
                  OUT a{sv} results);
EnableAutostart  (IN  s     app_id,
                  IN  b     enable,
                  IN  as    commandline,
                  IN  u     flags,
                  OUT b     result);

Description

This interface provides APIs related to applications that are running in the background.

Method Details

The GetAppState() method

GetAppState (OUT a{sv} apps);

Gets information about running apps. Each entry has an application ID as key. The returned values are of type u and have the following meaning:

0: Background (no open window)
1: Running (at least one open window)
2: Active (in the foreground)

OUT a{sv} apps:

an array with information about running apps

The NotifyBackground() method

NotifyBackground (IN  o     handle,
                  IN  s     app_id,
                  IN  s     name,
                  OUT u     response,
                  OUT a{sv} results);

Notifies the user that an application is running in the background.

The following results get returned via the results vardict:

result u

The choice that the user made regarding the background activity:

0: Forbid background activity by this app
1: Allow background activity by this app
2: Allow this instance of background activity

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s name:

A display name for the application

OUT u response:

Numeric response, not used

OUT a{sv} results:

Vardict with results of the call

The EnableAutostart() method

EnableAutostart (IN  s  app_id,
                 IN  b  enable,
                 IN  as commandline,
                 IN  u  flags,
                 OUT b  result);

Enables or disables autostart for an application.

The following flags are understood:

1: Use D-Bus activation

IN s app_id:

App id of the application

IN b enable:

TRUE to enable autostart, FALSE to disable it

IN as commandline:

The commandline to use in the autostart file

IN u flags:

Flags influencing the details of the autostarting

OUT b result:

TRUE if autostart was enabled, FALSE otherwise

Signal Details

The "RunningApplicationsChanged" signal

RunningApplicationsChanged ();

This signal gets emitted when applications change their state and it is worth calling GetAppState again.


Name

org.freedesktop.impl.portal.Clipboard

Methods

RequestClipboard   (IN  o     session_handle,
                    IN  a{sv} options);
SetSelection       (IN  o     session_handle,
                    IN  a{sv} options);
SelectionWrite     (IN  o     session_handle,
                    IN  u     serial,
                    OUT h     fd);
SelectionWriteDone (IN  o     session_handle,
                    IN  u     serial,
                    IN  b     success);
SelectionRead      (IN  o     session_handle,
                    IN  s     mime_type,
                    OUT h     fd);

Signals

SelectionOwnerChanged (o     session_handle,
                       a{sv} options);
SelectionTransfer     (o     session_handle,
                       s     mime_type,
                       u     serial);

Properties

version  readable   u

Description

Method Details

The RequestClipboard() method

RequestClipboard (IN  o     session_handle,
                  IN  a{sv} options);

Requests clipboard access for the given portal session. This request must be made before the session starts.

This portal does NOT create it's own session. Instead, it offers existing sessions created from other portals the option to integrate with the clipboard. For whether this interface is supported for a given session, refer to that portal's documentation. See #org.freedesktop.portal.RemoteDesktop to integrate clipboard with the remote desktop session.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The SetSelection() method

SetSelection (IN  o     session_handle,
              IN  a{sv} options);

Sets the owner of the clipboard formats in 'mime_types' in options to the session, i.e. this session has data for the advertised clipboard formats.

See #org.freedesktop.portal.FileTransfer to transfer files using the 'application/vnd.portal.filetransfer' mimetype.

May only be called if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types as

A list of mime types that the session has clipboard content for.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

The SelectionWrite() method

SelectionWrite (IN  o session_handle,
                IN  u serial,
                OUT h fd);

Answer to 'SelectionTransfer' signal. Transfers the clipboard content for the given serial to the method callee via a file descriptor. It is the Callee that creates the file descriptor.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN u serial:

The serial of the request where this answer is directed towards

OUT h fd:

A UnixFD handle to the contents of the selection being written to

The SelectionWriteDone() method

SelectionWriteDone (IN  o session_handle,
                    IN  u serial,
                    IN  b success);

data was successful ('true') or not ('false')

Notifies that the transfer of the clipboard data has either completed successfully, or failed.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN u serial:

The serial of the request where this answer is directed to

IN b success:

A boolean which indicates whether the transfer of the clipboard

The SelectionRead() method

SelectionRead (IN  o session_handle,
               IN  s mime_type,
               OUT h fd);

Transfer the clipboard content given the specified mime type to the method caller via a file descriptor. It is the callee that creates the file descriptor.

May only be called if clipboard access was given after starting the session.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN s mime_type:

The mime-type string of the requested format

OUT h fd:

A UnixFD handle to the contents of the selection being read

Signal Details

The "SelectionOwnerChanged" signal

SelectionOwnerChanged (o     session_handle,
                       a{sv} options);

Notifies the session that the clipboard selection has changed.

Caller will only be notified if clipboard access was given after starting the session.

Supported keys in the options vardict include:

mime_types as

A list of mime types that the the new clipboard selection has content for.

session_is_owner b

A boolean for whether the session is the owner of the clipboard selection ('true') or not ('false').

o session_handle:

Object path for the #org.freedesktop.portal.Session object

a{sv} options:

Vardict with optional further information

The "SelectionTransfer" signal

SelectionTransfer (o session_handle,
                   s mime_type,
                   u serial);

Notifies the session of a request for clipboard content of the given mime type. The callee provides a serial to track the request, which any org.freedesktop.portal.Clipboard.SelectionWrite() responses must use.

Once the caller is done handling the 'SelectionTransfer' request, they must call org.freedesktop.portal.Clipboard.SelectionWriteDone() with the corresponding request's serial and whether the request completed successfully. If the request is not handled, the caller should respond by setting 'success' to 'false'.

Caller will only be notified if clipboard access was given after starting the session.

o session_handle:

Object path for the #org.freedesktop.portal.Session object

s mime_type:

The mime-type string of the requested format

u serial:

The serial used to track this transfer, to which the answer of this request must use

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Email — Email portal backend interface

Methods

ComposeEmail (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Description

This Email portal lets sandboxed applications request sending an email.

Method Details

The ComposeEmail() method

ComposeEmail (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Lets the user compose an email.

Supported keys in the options vardict include:

address s

The email address to send to.

addresses as

Email addresses to send to.

cc as

Email addresses to cc.

bcc as

Email addresses to bcc.

subject s

The subject for the email.

body s

The body for the email.

attachments as

The uris for files to attach.

activation_token s

A token that can be used to activate the chosen application.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

org.freedesktop.impl.portal.FileChooser — File chooser portal backend interface

Methods

OpenFile  (IN  o     handle,
           IN  s     app_id,
           IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT u     response,
           OUT a{sv} results);
SaveFile  (IN  o     handle,
           IN  s     app_id,
           IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT u     response,
           OUT a{sv} results);
SaveFiles (IN  o     handle,
           IN  s     app_id,
           IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT u     response,
           OUT a{sv} results);

Description

The FileChooser portal allows sandboxed applications to ask the user for access to files outside the sandbox. The portal backend will present the user with a file chooser dialog.

Method Details

The OpenFile() method

OpenFile (IN  o     handle,
          IN  s     app_id,
          IN  s     parent_window,
          IN  s     title,
          IN  a{sv} options,
          OUT u     response,
          OUT a{sv} results);

Presents a file chooser dialog to the user to open one or more files.

Supported keys in the options vardict include:

accept_label s

The label for the accept button. Mnemonic underlines are allowed.

modal b

Whether to make the dialog modal. Default is yes.

multiple b

Whether to allow selection of multiple files. Default is no.

directory b

Whether to select for folders instead of files. Default is to select files.

filters a(sa(us))

A list of serialized file filters. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_filter (sa(us))

Request that this filter be set by default at dialog creation. See org.freedesktop.portal.FileChooser.OpenFile() for details.

choices a(ssa(ss)s)

A list of serialized combo boxes. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_folder ay

A suggested folder to open the files from. See org.freedesktop.portal.FileChooser.OpenFile() for details.

The following results get returned via the results vardict:

uris as

An array of strings containing the uris of the selected files.

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_filter (sa(us))

The filter that was selected. See org.freedesktop.portal.FileChooser.OpenFile() for details.

writable b

Whether the file is opened with write access. Default is no.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The SaveFile() method

SaveFile (IN  o     handle,
          IN  s     app_id,
          IN  s     parent_window,
          IN  s     title,
          IN  a{sv} options,
          OUT u     response,
          OUT a{sv} results);

Presents a file chooser dialog to the user to save a file.

Supported keys in the options vardict include:

accept_label s

The label for the accept button. Mnemonic underlines are allowed.

modal b

Whether to make the dialog modal. Default is yes.

multiple b

Whether to allow selection of multiple files. Default is no.

filters a(sa(us))

A list of serialized file filters. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_filter (sa(us))

Request that this filter be set by default at dialog creation. See org.freedesktop.portal.FileChooser.OpenFile() for details.

choices a(ssa(ss)s)

A list of serialized combo boxes. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_name s

A suggested filename.

current_folder ay

A suggested folder to save the file in.

current_file ay

The current file (when saving an existing file).

The following results get returned via the results vardict:

uris as

An array of strings containing the uri of the selected file.

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_filter (sa(us))

The filter that was selected. See org.freedesktop.portal.FileChooser.OpenFile() for details.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The SaveFiles() method

SaveFiles (IN  o     handle,
           IN  s     app_id,
           IN  s     parent_window,
           IN  s     title,
           IN  a{sv} options,
           OUT u     response,
           OUT a{sv} results);

Asks for a folder as a location to save one or more files. The names of the files will be used as-is and appended to the selected folder's path in the list of returned files. If the selected folder already contains a file with one of the given names, the portal may prompt or take some other action to construct a unique file name and return that instead.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the #org.freedesktop.portal.Request documentation for more information about the handle.

accept_label s

Label for the accept button. Mnemonic underlines are allowed.

modal b

Whether the dialog should be modal. Default is yes.

choices a(ssa(ss)s)

List of serialized combo boxes. See org.freedesktop.portal.FileChooser.OpenFile() for details.

current_folder ay

Suggested folder to save the files in. The byte array is expected to be null-terminated.

files aay

An array of file names to be saved. The array and byte arrays are expected to be null-terminated.

The following results get returned via the #org.freedesktop.portal.Request::Response signal:

uris as

An array of strings containing the uri corresponding to each file given by options, in the same order. Note that the file names may have changed, for example if a file with the same name in the selected folder already exists.

choices a(ss)

An array of pairs of strings, corresponding to the passed-in choices. See org.freedesktop.portal.FileChooser.OpenFile() for details.

IN o handle:

Object path for the #org.freedesktop.portal.Request object representing this call

IN s app_id:

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:


Name

org.freedesktop.impl.portal.GlobalShortcuts

Methods

CreateSession (IN  o         handle,
               IN  o         session_handle,
               IN  s         app_id,
               IN  a{sv}     options,
               OUT u         response,
               OUT a{sv}     results);
BindShortcuts (IN  o         handle,
               IN  o         session_handle,
               IN  a(sa{sv}) shortcuts,
               IN  s         parent_window,
               IN  a{sv}     options,
               OUT u         response,
               OUT a{sv}     results);
ListShortcuts (IN  o         handle,
               IN  o         session_handle,
               OUT u         response,
               OUT a{sv}     results);

Signals

Activated        (o         session_handle,
                  s         shortcut_id,
                  t         timestamp,
                  a{sv}     options);
Deactivated      (o         session_handle,
                  s         shortcut_id,
                  t         timestamp,
                  a{sv}     options);
ShortcutsChanged (o         session_handle,
                  a(sa{sv}) shortcuts);

Properties

version  readable   u

Description

Method Details

The CreateSession() method

CreateSession (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

Create a global shortcuts session.

The following results get returned via the #org.freedesktop.portal.Request::Response signal:

session_id s

The session id. A string representing the created global shortcuts session.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session being created

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information. See org.freedesktop.portal.GlobalShortcuts.CreateSession

OUT u response:

Numeric Request response

OUT a{sv} results:

Vardict with the results of the call

The BindShortcuts() method

BindShortcuts (IN  o         handle,
               IN  o         session_handle,
               IN  a(sa{sv}) shortcuts,
               IN  s         parent_window,
               IN  a{sv}     options,
               OUT u         response,
               OUT a{sv}     results);

Bind the shortcuts of this session. This will typically result the portal presenting a dialog letting the user configure shortcut triggers.

The results get returned via the #org.freedesktop.portal.Request::Response signal. See org.freedesktop.portal.GlobalShortcuts.BindShortcuts() for the list of supported properties of shortcuts.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN a(sa{sv}) shortcuts:

The identifier of the shortcuts we intend to register, empty for all shortcuts

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

OUT u response:

OUT a{sv} results:

Vardict with the results of the call

The ListShortcuts() method

ListShortcuts (IN  o     handle,
               IN  o     session_handle,
               OUT u     response,
               OUT a{sv} results);

IN o handle:

IN o session_handle:

OUT u response:

OUT a{sv} results:

Signal Details

The "Activated" signal

Activated (o     session_handle,
           s     shortcut_id,
           t     timestamp,
           a{sv} options);

Emitted when a shortcut is activated.

o session_handle:

Session that requested the shortcut

s shortcut_id:

the application-provided ID for the notification

t timestamp:

the time of activation with millisecond granularity, with an undefined base.

a{sv} options:

Vardict with optional further information

The "Deactivated" signal

Deactivated (o     session_handle,
             s     shortcut_id,
             t     timestamp,
             a{sv} options);

Emitted when a shortcut is deactivated.

o session_handle:

Session that requested the shortcut

s shortcut_id:

the application-provided ID for the notification

t timestamp:

the time of deactivation with millisecond granularity, with an undefined base.

a{sv} options:

Vardict with optional further information

The "ShortcutsChanged" signal

ShortcutsChanged (o         session_handle,
                  a(sa{sv}) shortcuts);

Emitted when shortcuts are changed.

The results get returned via the #org.freedesktop.portal.Request::Response signal. See org.freedesktop.portal.GlobalShortcuts.BindShortcuts() for the list of supported properties of shortcuts.

o session_handle:

Session that requested the shortcut

a(sa{sv}) shortcuts:

The list of changed shortcuts

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Inhibit — Inhibit portal backend interface

Methods

Inhibit          (IN  o     handle,
                  IN  s     app_id,
                  IN  s     window,
                  IN  u     flags,
                  IN  a{sv} options);
CreateMonitor    (IN  o     handle,
                  IN  o     session_handle,
                  IN  s     app_id,
                  IN  s     window,
                  OUT u     response);
QueryEndResponse (IN  o     session_handle);

Signals

StateChanged (o     session_handle,
              a{sv} state);

Description

The inhibit portal lets sandboxed applications inhibit the user session from ending, suspending, idling or getting switched away.

Method Details

The Inhibit() method

Inhibit (IN  o     handle,
         IN  s     app_id,
         IN  s     window,
         IN  u     flags,
         IN  a{sv} options);

Inhibits session status changes. As a side-effect of this call, a org.freedesktop.impl.portal.Request object is exported on the object path handle. To end the inhibition, call Close() on that object.

The flags determine what changes are inhibited:

1: Logout
2: User Switch
4: Suspend
8: Idle

Supported keys in the options vardict include:

reason s

User-visible reason for the inhibition.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

Application id

IN s window:

Identifier for the window

IN u flags:

Flags identifying what is inhibited

IN a{sv} options:

Vardict with optional further information

The CreateMonitor() method

CreateMonitor (IN  o handle,
               IN  o session_handle,
               IN  s app_id,
               IN  s window,
               OUT u response);

Creates a monitoring session. While this session is active, the caller will receive StateChanged signals with updates on the session state.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the created org.freedesktop.impl.portal.Session object

IN s app_id:

App id of the application

IN s window:

the parent window

OUT u response:

the result of the operation (0 == success)

The QueryEndResponse() method

QueryEndResponse (IN  o session_handle);

Acknowledges that the caller received the "StateChanged" signal. This method should be called within one second or receiving a StateChanged signal with the 'Query End' state.

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object

Signal Details

The "StateChanged" signal

StateChanged (o     session_handle,
              a{sv} state);

The StateChanged signal is sent to active monitoring sessions when the session state changes.

When the session state changes to 'Query End', clients with active monitoring sessions are expected to respond by calling QueryEndResponse() within a second of receiving the StateChanged signal.

The following information may get returned in the state vardict:

screensaver-active b

Whether the screensaver is active.

session-state u

The state of the session.

1: Running
2: Query End
3: Ending

o session_handle:

Object path for the #org.freedesktop.portal.Session object

a{sv} state:

Vardict with information about the session state


Name

org.freedesktop.impl.portal.InputCapture — Capture input portal backend interface

Methods

CreateSession      (IN  o      handle,
                    IN  o      session_handle,
                    IN  s      app_id,
                    IN  s      parent_window,
                    IN  a{sv}  options,
                    OUT u      response,
                    OUT a{sv}  results);
GetZones           (IN  o      handle,
                    IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    OUT u      response,
                    OUT a{sv}  results);
SetPointerBarriers (IN  o      handle,
                    IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    IN  aa{sv} barriers,
                    IN  u      zone_set,
                    OUT u      response,
                    OUT a{sv}  results);
Enable             (IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    OUT u      response,
                    OUT a{sv}  results);
Disable            (IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    OUT u      response,
                    OUT a{sv}  results);
Release            (IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    OUT u      response,
                    OUT a{sv}  results);
ConnectToEIS       (IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    OUT h      fd);

Signals

Disabled     (o     session_handle,
              a{sv} options);
Activated    (o     session_handle,
              a{sv} options);
Deactivated  (o     session_handle,
              a{sv} options);
ZonesChanged (o     session_handle,
              a{sv} options);

Properties

SupportedCapabilities  readable   u
version                readable   u

Description

The Capture Input portal allows clients to capture input from local devices. This portal is mostly a 1:1 mapping of the #org.freedesktop.portal.InputCapture portal, see that portal's documentation for details on methods, signals and arguments.

This documentation describes version 1 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  s     parent_window,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

IN o handle:

IN o session_handle:

IN s app_id:

IN s parent_window:

IN a{sv} options:

OUT u response:

OUT a{sv} results:

The GetZones() method

GetZones (IN  o     handle,
          IN  o     session_handle,
          IN  s     app_id,
          IN  a{sv} options,
          OUT u     response,
          OUT a{sv} results);

Return the current zones for this session.

The following results get returned in the results vardict:

zones a(uuii)

An array of zones with width, height, x-offset, y-offset.

zone_set u

The zone_set ID required in SetPointerBarriers().

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The SetPointerBarriers() method

SetPointerBarriers (IN  o      handle,
                    IN  o      session_handle,
                    IN  s      app_id,
                    IN  a{sv}  options,
                    IN  aa{sv} barriers,
                    IN  u      zone_set,
                    OUT u      response,
                    OUT a{sv}  results);

Set up zero or more pointer barriers.

Supported keys in the barriers vardicts include:

barrier_id u

The non-zero id of this barrier. This id is used in the #org.freedesktop.portal.impl.InputCapture::Activated signal to inform which barrier triggered input capture.

position (iiii)

The x1/y1 x2/y2 position of the pointer barrier. A horizontal pointer barrier must have y1 == y2, a vertical pointer barrier must have x1 == x2. Diagonal pointer barriers are not supported.

The following results get returned in the results vardict:

failed_barriers au

An array of barrier_ids of pointer barriers that have been denied. The id matches the barrier_id of the entries in the barriers argument.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

IN aa{sv} barriers:

An array of vardicts, each specifying one barrier

IN u zone_set:

A unique ID referring to the zone set

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The Enable() method

Enable (IN  o     session_handle,
        IN  s     app_id,
        IN  a{sv} options,
        OUT u     response,
        OUT a{sv} results);

Enable input capturing.

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:

The Disable() method

Disable (IN  o     session_handle,
         IN  s     app_id,
         IN  a{sv} options,
         OUT u     response,
         OUT a{sv} results);

Disable input capturing.

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:

The Release() method

Release (IN  o     session_handle,
         IN  s     app_id,
         IN  a{sv} options,
         OUT u     response,
         OUT a{sv} results);

Release ongoing input capturing.

Supported keys in the options vardict include:

activation_id u

The same activation_id number as in the "Activated" signal.

cursor_position (dd)

The suggested cursor position within the Zones available in this session.

This is a suggestion to the compositor to place the cursor in the correct position to allow for fluent movement between virtual screens. The compositor is not required to honor this suggestion.

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:

The ConnectToEIS() method

ConnectToEIS (IN  o     session_handle,
              IN  s     app_id,
              IN  a{sv} options,
              OUT h     fd);

Set up the connection to an EIS implementation. Once input capturing starts, input events are sent via the EI protocol between the compositor and the application. This call must be invoked before org.freedesktop.portal.InputCapture.Enable().

A session only needs to set this up once, the EIS implementation is not affected by calls to Disable() and org.freedesktop.portal.InputCapture.Enable() - the same context can be re-used until the session is closed.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT h fd:

A file descriptor to an EIS implementation that can be passed to a passive libei context

Signal Details

The "Disabled" signal

Disabled (o     session_handle,
          a{sv} options);

The Disabled signal is emitted when the application will no longer receive captured input. If input capturing is currently ongoing, the "Deactivated" signal is emitted before this signal.

o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

a{sv} options:

Vardict with optional further information

The "Activated" signal

Activated (o     session_handle,
           a{sv} options);

The Activated signal is emitted when input capture starts and input events are about to be sent to the application.

This signal is only emitted after a prior call to Enable().

Supported keys in the options vardict include:

activation_id u

A number that can be used to synchronize with the transport-layer. This number has no intrinsic meaning but is guaranteed to increase by an unspecified amount on each call.

In particular: if the compositor sends an activation_id of N as part of this request it will also set the sequence in EIS' start_emulating event the same value N on the EIS connection before the first event from a device is sent. This allows an application to have a synchronization point and attribute an event sequence to the portal interaction.

Applications must be able to handle the activation_id number wrapping around. Implementations of this portal must to increase the activation_id number by an sensible amount to allow for wrapping detection.

cursor_position (dd)

The current cursor position. Note that this position may be outside the Zones available to this session - this indicates movement larger than a single pixel.

For example, a fast movement against a barrier on the right edge of a screen may logically put the cursor dozens of pixels into the (non-existing) screen on the other side of the barrier. It is the application's responsibility to adjust the cursor position as necessary.

barrier_id u

The barrier id of the barrier that triggered. If the value is nonzero, it matches the barrier id as specified in SetPointerBarriers().

If the id is zero, the pointer barrier could be determined. If the id is missing, the input capture was not triggered by a pointer barrier.

Where more than one pointer barrier are triggered by the same movement it is up to the compositor to choose one barrier (or use a barrier id of zero).

o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

a{sv} options:

Vardict with optional further information

The "Deactivated" signal

Deactivated (o     session_handle,
             a{sv} options);

The Deactivated signal is emitted when input capture stopped and input events are no longer sent to the application. To prevent future input capture, an application must call org.freedesktop.portal.InputCapture.Disable().

Supported keys in the options vardict include:

activation_id u

The same activation_id as in the corresponding "Activated" signal.

cursor_position (dd)

The current cursor position. Note that this position may be outside the Zones available to this session - this indicates movement larger than a single pixel.

For example, a fast movement against a barrier on the right edge of a screen may logically put the cursor dozens of pixels into the (non-existing) screen on the other side of the barrier. It is the application's responsibility to adjust the cursor position as necessary.

o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

a{sv} options:

Vardict with optional further information

The "ZonesChanged" signal

ZonesChanged (o     session_handle,
              a{sv} options);

The ZonesChanged signal is emitted when one or more of the zones available **to this session** change. An application should immediately call org.freedesktop.portal.InputCapture.GetZones() to update its state of the zones.

o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

a{sv} options:

Vardict with optional further information

Property Details

The "SupportedCapabilities" property

SupportedCapabilities  readable   u

A bitmask of supported capabilities. This list is constant, it is not the list of capabilities currently available but rather which capabilies are implemented by the portal.

Applications must ignore unknown capabilities.

Currently defined types are:

1: KEYBOARD
2: POINTER
4: TOUCHSCREEN

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Lockdown — Lockdown backend interface

Properties

disable-printing              readwrite  b
disable-save-to-disk          readwrite  b
disable-application-handlers  readwrite  b
disable-location              readwrite  b
disable-camera                readwrite  b
disable-microphone            readwrite  b
disable-sound-output          readwrite  b

Description

This interface provides access to high-level desktop lockdown settings that can disable entire portals, such as disabling printing or location services.

This is meant to be used by different portal frontends.

Property Details

The "disable-printing" property

disable-printing  readwrite  b

The "disable-save-to-disk" property

disable-save-to-disk  readwrite  b

The "disable-application-handlers" property

disable-application-handlers  readwrite  b

The "disable-location" property

disable-location  readwrite  b

The "disable-camera" property

disable-camera  readwrite  b

The "disable-microphone" property

disable-microphone  readwrite  b

The "disable-sound-output" property

disable-sound-output  readwrite  b


Name

org.freedesktop.impl.portal.Notification — Notification portal backend interface

Methods

AddNotification    (IN  s     app_id,
                    IN  s     id,
                    IN  a{sv} notification);
RemoveNotification (IN  s     app_id,
                    IN  s     id);

Signals

ActionInvoked (s  app_id,
               s  id,
               s  action,
               av parameter);

Description

This notification interface lets sandboxed applications send and withdraw notifications.

Method Details

The AddNotification() method

AddNotification (IN  s     app_id,
                 IN  s     id,
                 IN  a{sv} notification);

Sends a notification.

The ID can be used to later withdraw the notification. If the application reuses the same ID without withdrawing, the notification is replaced by the new one.

The format of the notification is the same as for org.freedesktop.portal.Notification.AddNotification().

IN s app_id:

App id of the application

IN s id:

Application-provided ID for this notification

IN a{sv} notification:

Vardict with the serialized notification

The RemoveNotification() method

RemoveNotification (IN  s app_id,
                    IN  s id);

Withdraws a notification.

IN s app_id:

App id of the application

IN s id:

Application-provided ID for this notification

Signal Details

The "ActionInvoked" signal

ActionInvoked (s  app_id,
               s  id,
               s  action,
               av parameter);

for the action, if one was specified

Send to the application when a non-exported action is activated.

s app_id:

App id of the application

s id:

the application-provided ID for the notification

s action:

the name of the action

av parameter:

array which will contain the target parameter


Name

org.freedesktop.impl.portal.PermissionStore — Database to store permissions

Methods

Lookup           (IN  s      table,
                  IN  s      id,
                  OUT a{sas} permissions,
                  OUT v      data);
Set              (IN  s      table,
                  IN  b      create,
                  IN  s      id,
                  IN  a{sas} app_permissions,
                  IN  v      data);
Delete           (IN  s      table,
                  IN  s      id);
SetValue         (IN  s      table,
                  IN  b      create,
                  IN  s      id,
                  IN  v      data);
SetPermission    (IN  s      table,
                  IN  b      create,
                  IN  s      id,
                  IN  s      app,
                  IN  as     permissions);
DeletePermission (IN  s      table,
                  IN  s      id,
                  IN  s      app);
GetPermission    (IN  s      table,
                  IN  s      id,
                  IN  s      app,
                  OUT as     permissions);
List             (IN  s      table,
                  OUT as     ids);

Signals

Changed (s      table,
         s      id,
         b      deleted,
         v      data,
         a{sas} permissions);

Properties

version  readable   u

Description

The permission store can be used by portals to store permissions that sandboxed applications have to various resources, such as files outside the sandbox.

Since the resources managed by portals can be varied, the permission store is fairly free-form: there can be multiple tables; resources are identified by an ID, as are applications, and permissions are stored as string arrays. None of these strings are interpreted by the permission store in any way.

In addition, the permission store allows to associate extra data (in the form of a GVariant) with each resource.

This document describes version 2 of the permission store interface.

Method Details

The Lookup() method

Lookup (IN  s      table,
        IN  s      id,
        OUT a{sas} permissions,
        OUT v      data);

Looks up the entry for a resource in one of the tables and returns all associated application permissions and data.

IN s table:

the name of the table to use

IN s id:

the resource ID to look up

OUT a{sas} permissions:

map from application ID to permissions

OUT v data:

data that is associated with the resource

The Set() method

Set (IN  s      table,
     IN  b      create,
     IN  s      id,
     IN  a{sas} app_permissions,
     IN  v      data);

Writes the entry for a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN a{sas} app_permissions:

map from application ID to permissions

IN v data:

data to associate with the resource

The Delete() method

Delete (IN  s table,
        IN  s id);

Removes the entry for a resource in the given table.

IN s table:

the name of the table to use

IN s id:

the resource ID to delete

The SetValue() method

SetValue (IN  s table,
          IN  b create,
          IN  s id,
          IN  v data);

Sets just the data for a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN v data:

data to associate with the resource

The SetPermission() method

SetPermission (IN  s  table,
               IN  b  create,
               IN  s  id,
               IN  s  app,
               IN  as permissions);

Sets the permissions for an application and a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN s app:

the application ID to modify

IN as permissions:

permissions to set

The DeletePermission() method

DeletePermission (IN  s table,
                  IN  s id,
                  IN  s app);

Removes the entry for an application and a resource in the given table.

This method was added in version 2.

IN s table:

the name of the table to use

IN s id:

the resource ID to modify

IN s app:

the application ID to modify

The GetPermission() method

GetPermission (IN  s  table,
               IN  s  id,
               IN  s  app,
               OUT as permissions);

Gets the entry for an application and a resource in the given table.

IN s table:

the name of the table to use

IN s id:

the resource ID to modify

IN s app:

the application ID to modify

OUT as permissions:

permissions to get

The List() method

List (IN  s  table,
      OUT as ids);

Returns all the resources that are present in the table.

IN s table:

the name of the table to use

OUT as ids:

IDs of all resources that are present in the table

Signal Details

The "Changed" signal

Changed (s      table,
         s      id,
         b      deleted,
         v      data,
         a{sas} permissions);

The Changed signal is emitted when the entry for a resource is modified or deleted. If the entry was deleted, then data and permissions contain the last values that were found in the database. If the entry was modified, they contain the new values.

s table:

the name of the table

s id:

b deleted:

whether the resource was deleted

v data:

the data that is associated the resource

a{sas} permissions:

the permissions that are associated with the resource

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Print — Print portal backend interface

Methods

Print        (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  s     title,
              IN  h     fd,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);
PreparePrint (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  s     title,
              IN  a{sv} settings,
              IN  a{sv} page_setup,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Description

The Print portal allows sandboxed applications to print.

Method Details

The Print() method

Print (IN  o     handle,
       IN  s     app_id,
       IN  s     parent_window,
       IN  s     title,
       IN  h     fd,
       IN  a{sv} options,
       OUT u     response,
       OUT a{sv} results);

Prints a file.

The file is given in the form of a file descriptor open for reading.

If a valid token is present in the options, then this call will print with the settings from the Print call that the token refers to. If no token is present, then a print dialog will be presented to the user.

Note that it is up to the portal implementation to determine how long it considers tokens valid.

Supported keys in the options vardict:

modal b

Whether to make the dialog modal. Defaults to yes.

token u

Token that was returned by a previous PreparePrint() call.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the print dialog

IN h fd:

File descriptor from which to read the content to print

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The PreparePrint() method

PreparePrint (IN  o     handle,
              IN  s     app_id,
              IN  s     parent_window,
              IN  s     title,
              IN  a{sv} settings,
              IN  a{sv} page_setup,
              IN  a{sv} options,
              OUT u     response,
              OUT a{sv} results);

Presents a print dialog to the user and returns print settings and page setup.

Supported keys in the options vardict:

modal b

Whether to make the dialog modal. Defaults to yes.

accept_label s

Label for the accept button. Mnemonic underlines are allowed.

The following results get returned via the results vardict:

settings a{sv}

Print settings as set up by the user in the print dialog.

page-setup a{sv}

Page setup as set up by the user in the print dialog.

token u

Token that can be passed to a subsequent Print() call to bypass the print dialog.

The org.freedesktop.portal.Print.Print() documentation has details about the supported keys in settings and page-setup.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN s title:

Title for the print dialog

IN a{sv} settings:

Serialized print settings

IN a{sv} page_setup:

Serialized page setup

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:


Name

org.freedesktop.impl.portal.RemoteDesktop — Remote desktop portal backend interface

Methods

CreateSession               (IN  o     handle,
                             IN  o     session_handle,
                             IN  s     app_id,
                             IN  a{sv} options,
                             OUT u     response,
                             OUT a{sv} results);
SelectDevices               (IN  o     handle,
                             IN  o     session_handle,
                             IN  s     app_id,
                             IN  a{sv} options,
                             OUT u     response,
                             OUT a{sv} results);
Start                       (IN  o     handle,
                             IN  o     session_handle,
                             IN  s     app_id,
                             IN  s     parent_window,
                             IN  a{sv} options,
                             OUT u     response,
                             OUT a{sv} results);
NotifyPointerMotion         (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  d     dx,
                             IN  d     dy);
NotifyPointerMotionAbsolute (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  d     x,
                             IN  d     y);
NotifyPointerButton         (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     button,
                             IN  u     state);
NotifyPointerAxis           (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  d     dx,
                             IN  d     dy);
NotifyPointerAxisDiscrete   (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     axis,
                             IN  i     steps);
NotifyKeyboardKeycode       (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     keycode,
                             IN  u     state);
NotifyKeyboardKeysym        (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  i     keysym,
                             IN  u     state);
NotifyTouchDown             (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  u     slot,
                             IN  d     x,
                             IN  d     y);
NotifyTouchMotion           (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  u     slot,
                             IN  d     x,
                             IN  d     y);
NotifyTouchUp               (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     slot);
ConnectToEIS                (IN  o     session_handle,
                             IN  s     app_id,
                             IN  a{sv} options,
                             OUT h     fd);

Properties

AvailableDeviceTypes  readable   u
version               readable   u

Description

The Remote desktop portal allows to create remote desktop sessions.

This documentation describes version 2 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

Create a remote desktop session.

A remote desktop session is used to allow remote controlling a desktop session. It can also be used together with a screen cast session (see org.freedesktop.portal.ScreenCast), but may only be started and stopped with this interface.

The following results get returned via the #org.freedesktop.portal.Request::Response signal:

session s

The session id. A string representing the created screen cast session.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The SelectDevices() method

SelectDevices (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

Configure what the devices remote desktop session should expose.

Supported keys in the options vardict include:

types u

Bitmask of what device types to request remote controlling of. Default is all.

restore_data (suv)

The data to restore from a previous session.

If the stored session cannot be restored, this value is ignored and the user will be prompted normally. This may happen when, for example, the session contains a monitor or a window that is not available anymore, or when the stored permissions are withdrawn.

The restore data is composed of the vendor name (e.g. "GNOME" or "KDE"), the version of the implementation-specific private data, and the implementation-specific private data itself.

This option was added in version 2 of this interface.

persist_mode u

How this session should persist. Default is 0. Accepted values are:

0: Do not persist (default)
1: Permissions persist as long as the application is running
2: Permissions persist until explicitly revoked

If the permission for the session to persist is granted, "restore_data" will be returned via the #org.freedesktop.portal.Request::Response signal of the org.freedesktop.impl.portal.RemoteDesktop.Start method.

This option was added in version 2 of this interface.

For available device types, see the AvailableDeviceTypes property.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The Start() method

Start (IN  o     handle,
       IN  o     session_handle,
       IN  s     app_id,
       IN  s     parent_window,
       IN  a{sv} options,
       OUT u     response,
       OUT a{sv} results);

Start the remote desktop session. This will typically result the portal presenting a dialog.

Supported keys in the options vardict include:

handle_token s

A string that will be used as the last element of the handle. Must be a valid object path element. See the #org.freedesktop.portal.Request documentation for more information about the handle.

The following results get returned via the #org.freedesktop.portal.Request::Response signal:

devices u

A bitmask of the devices selected by the user.

clipboard_enabled b

A boolean for whether the clipboard was enabled ('true') or not ('false'). See the #org.freedesktop.portal.Clipboard documentation for more information. Since version 2.

streams a(ua{sv})

Equivalent to the streams entry documented in org.freedesktop.impl.portal.ScreenCast.Start.

devices u

The device types that can be used for remote control. See the AvailableDeviceTypes property.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The NotifyPointerMotion() method

NotifyPointerMotion (IN  o     session_handle,
                     IN  a{sv} options,
                     IN  d     dx,
                     IN  d     dy);

Notify about a new relative pointer motion event. The (dx, dy) vector represents the new pointer position in the streams logical coordinate space.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN d dx:

Relative movement on the x axis

IN d dy:

Relative movement on the y axis

The NotifyPointerMotionAbsolute() method

NotifyPointerMotionAbsolute (IN  o     session_handle,
                             IN  a{sv} options,
                             IN  u     stream,
                             IN  d     x,
                             IN  d     y);

Notify about a new absolute pointer motion event. The (x, y) position represents the new pointer position in the streams logical coordinate space (see the logical_size stream property in #org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN d x:

Pointer motion x coordinate

IN d y:

Pointer motion y coordinate

The NotifyPointerButton() method

NotifyPointerButton (IN  o     session_handle,
                     IN  a{sv} options,
                     IN  i     button,
                     IN  u     state);

The pointer button is encoded according to Linux Evdev button codes.

May only be called if POINTER access was provided after starting the session.

Available button states:

0: Released
1: Pressed

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i button:

The pointer button was pressed or released

IN u state:

The new state of the button

The NotifyPointerAxis() method

NotifyPointerAxis (IN  o     session_handle,
                   IN  a{sv} options,
                   IN  d     dx,
                   IN  d     dy);

The axis movement from a 'smooth scroll' device, such as a touchpad. When applicable, the size of the motion delta should be equivalent to the motion vector of a pointer motion done using the same advice.

May only be called if POINTER access was provided after starting the session.

Supported keys in the options vardict include:

finish b

If set to true, this is the last axis event in a series, for example as a result of the fingers being lifted from a touchpad after a two-finger scroll. Default is false.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN d dx:

Relative axis movement on the x axis

IN d dy:

Relative axis movement on the y axis

The NotifyPointerAxisDiscrete() method

NotifyPointerAxisDiscrete (IN  o     session_handle,
                           IN  a{sv} options,
                           IN  u     axis,
                           IN  i     steps);

May only be called if POINTER access was provided after starting the session.

Available axes:

0: Vertical scroll
1: Horizontal scroll

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u axis:

The axis that was scrolled

IN i steps:

The number of steps scrolled

The NotifyKeyboardKeycode() method

NotifyKeyboardKeycode (IN  o     session_handle,
                       IN  a{sv} options,
                       IN  i     keycode,
                       IN  u     state);

May only be called if KEYBOARD access was provided after starting the session.

Available keyboard keysym states:

0: Released
1: Pressed

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i keycode:

Keyboard code that was pressed or released

IN u state:

New state of keyboard keysym

The NotifyKeyboardKeysym() method

NotifyKeyboardKeysym (IN  o     session_handle,
                      IN  a{sv} options,
                      IN  i     keysym,
                      IN  u     state);

May only be called if KEYBOARD access was provided after starting the session.

Available keyboard keysym states:

0: Released
1: Pressed

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN i keysym:

Keyboard symbol that was pressed or released

IN u state:

New state of keyboard keysym

The NotifyTouchDown() method

NotifyTouchDown (IN  o     session_handle,
                 IN  a{sv} options,
                 IN  u     stream,
                 IN  u     slot,
                 IN  d     x,
                 IN  d     y);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch down event. The (x, y) position represents the new touch point position in the streams logical coordinate space (see the logical_size stream property in #org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN u slot:

Touch slot where touch point appeared

IN d x:

Touch down x coordinate

IN d y:

Touch down y coordinate

The NotifyTouchMotion() method

NotifyTouchMotion (IN  o     session_handle,
                   IN  a{sv} options,
                   IN  u     stream,
                   IN  u     slot,
                   IN  d     x,
                   IN  d     y);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch motion event. The (x, y) position represents where the touch point position in the streams logical coordinate space moved (see the logical_size stream property in #org.freedesktop.portal.ScreenCast).

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u stream:

The PipeWire stream node the coordinate is relative to

IN u slot:

Touch slot where touch point appeared

IN d x:

Touch motion x coordinate

IN d y:

Touch motion y coordinate

The NotifyTouchUp() method

NotifyTouchUp (IN  o     session_handle,
               IN  a{sv} options,
               IN  u     slot);

May only be called if TOUCHSCREEN access was provided after starting the session.

Notify about a new touch up event.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN a{sv} options:

Vardict with optional further information

IN u slot:

Touch slot where touch point appeared

The ConnectToEIS() method

ConnectToEIS (IN  o     session_handle,
              IN  s     app_id,
              IN  a{sv} options,
              OUT h     fd);

sender libei context

Request a connection to an EIS implementation.

This method is available in version 2 of this interface.

IN o session_handle:

Object path for the #org.freedesktop.portal.Session object

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT h fd:

A file descriptor to an EIS implementation that can be passed to a

Property Details

The "AvailableDeviceTypes" property

AvailableDeviceTypes  readable   u

A bitmask of available source types. Currently defined types are:

1: KEYBOARD
2: POINTER
4: TOUCHSCREEN

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Request — Shared request interface

Methods

Close ();

Description

The Request interface is shared by all portal backend interfaces. When a backend method is called, the backend exports a Request object on the object path that was sent with the method call. The Request will stay alive for the duration of the user interaction related to the method call.

The portal can abort the interaction calling Close() on the Request object.

Method Details

The Close() method

Close ();

Ends the user interaction to which this object refers. Dialogs and other UIs related to the request should be closed.


Name

org.freedesktop.impl.portal.ScreenCast — Screen cast portal backend interface

Methods

CreateSession (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);
SelectSources (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);
Start         (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  s     parent_window,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

Properties

AvailableSourceTypes  readable   u
AvailableCursorModes  readable   u
version               readable   u

Description

The Screen cast portal allows to create screen cast sessions.

This documentation describes version 5 of this interface.

Method Details

The CreateSession() method

CreateSession (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

IN o handle:

IN o session_handle:

IN s app_id:

IN a{sv} options:

OUT u response:

OUT a{sv} results:

The SelectSources() method

SelectSources (IN  o     handle,
               IN  o     session_handle,
               IN  s     app_id,
               IN  a{sv} options,
               OUT u     response,
               OUT a{sv} results);

Configure what the screen cast session should record.

Supported keys in the options vardict include:

types u

Bitmask of what type of content to record. Default is MONITOR.

multiple b

Whether to allow selecting multiple sources. Default is no.

cursor_mode u

Determines how the cursor will be drawn in the screen cast stream. It must be one of the cursor modes advertised in #org.freedesktop.portal.impl.ScreenCast.AvailableCursorModes. Setting a cursor mode not advertised will cause the screen cast session to be closed. The default cursor mode is 'Hidden'.

This option was added in version 2 of this interface.

restore_data (suv)

The data to restore from a previous session.

If the stored session cannot be restored, this value is ignored and the user will be prompted normally. This may happen when, for example, the session contains a monitor or a window that is not available anymore, or when the stored permissions are withdrawn.

The restore data is composed of the vendor name (e.g. "GNOME" or "KDE"), the version of the implementation-specific private data, and the implementation-specific private data itself.

This option was added in version 4 of this interface.

persist_mode u

How this session should persist. Default is 0. Accepted values are:

0: Do not persist (default)
1: Permissions persist as long as the application is running
2: Permissions persist until explicitly revoked

If the permission for the session to persist is granted, "persist_mode" will be returned via the #org.freedesktop.portal.Request::Response signal of the org.freedesktop.impl.portal.ScreenCast.Start method.

This option was added in version 4 of this interface.

For available source types, see the AvailableSourceTypes property.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The Start() method

Start (IN  o     handle,
       IN  o     session_handle,
       IN  s     app_id,
       IN  s     parent_window,
       IN  a{sv} options,
       OUT u     response,
       OUT a{sv} results);

Start the screen cast session. This will typically result the portal presenting a dialog letting the user do the selection set up by SelectSources.

The following results get returned via the #org.freedesktop.portal.Request::Response signal:

streams a(ua{sv})

An array of PipeWire streams. Each stream consists of a PipeWire node ID (the first element in the tuple, and a Vardict of properties.

The array will contain a single stream if 'multiple' (see SelectSources) was set to 'false', or at least one stream if 'multiple' was set to 'true' as part of the SelectSources method.

persist_mode u

Portal implementations can optionally offer ways to "reduce" the persist mode, for example by explicitly asking the user. See the 'persist_mode' option of SelectSources for a list of possible values.

If no persist mode is returned by the Start request, it is assumed to be the same persist mode received during SelectSources.

This option was added in version 4 of this interface.

restore_data (suv)

The data to be restored. This is the data that a portal implementation sent in reaction to transient or persistent modes.

This data will be stored in the permission store if the effective persist mode is 2, and may be passed in the future as part of the SelectSources() method call. The portal backend should store enough information in 'restore_data' to be able to restore the session later. The portal backend can deal with unavailable sources however they see fit.

Data generated by a portal implementation must be consumable by the same portal implementation, but not necessarily by others. Thus, it is important to properly handle 'restore_data' not being in a valid format. This may happen when, e.g., the user switched to another desktop environment, or is using a different portal implementation.

This response option was added in version 4 of this interface.

Stream properties include:

position (ii)

A tuple consisting of the position (x, y) in the compositor coordinate space. Note that the position may not be equivalent to a position in a pixel coordinate space. Only available for monitor streams.

size (ii)

A tuple consisting of (width, height). The size represents the size of the stream as it is displayed in the compositor coordinate space. Note that this size may not be equivalent to a size in a pixel coordinate space. The size may differ from the size of the stream.

source_type u

The type of the content which is being screen casted. For available source types, see the AvailableSourceTypes property. This property was added in version 3 of this interface.

mapping_id s

An optional identifier used to map different aspects of the resource this stream corresponds to.

When used in a remote desktop session, the mapping_id can be used to match a libei region of absolute libei devices. There may be multiple absolute libei devices, and each device may have multiple regions, but a mapping_id will only match one of these regions per device. This property was added in version 5 of this interface.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN o session_handle:

Object path for the org.freedesktop.impl.portal.Session object representing the session

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

Property Details

The "AvailableSourceTypes" property

AvailableSourceTypes  readable   u

A bitmask of available source types. Currently defined types are:

1: MONITOR
2: WINDOW
4: VIRTUAL

The "AvailableCursorModes" property

AvailableCursorModes  readable   u

Available cursor mode values:

1: Hidden. The cursor is not part of the screen cast stream.
2: Embedded: The cursor is embedded as part of the stream buffers.
4: Metadata: The cursor is not part of the screen cast stream, but sent as PipeWire stream metadata.

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Screenshot — Screenshot portal backend interface

Methods

Screenshot (IN  o     handle,
            IN  s     app_id,
            IN  s     parent_window,
            IN  a{sv} options,
            OUT u     response,
            OUT a{sv} results);
PickColor  (IN  o     handle,
            IN  s     app_id,
            IN  s     parent_window,
            IN  a{sv} options,
            OUT u     response,
            OUT a{sv} results);

Properties

version  readable   u

Description

This screenshot portal lets sandboxed applications request a screenshot.

This documentation describes version 2 of this interface.

Method Details

The Screenshot() method

Screenshot (IN  o     handle,
            IN  s     app_id,
            IN  s     parent_window,
            IN  a{sv} options,
            OUT u     response,
            OUT a{sv} results);

Takes a screenshot.

Supported keys in the options vardict include:

modal b

Whether the dialog should be modal. Defaults to yes.

interactive b

Hint whether the dialog should offer customization before taking a screenshot. Defaults to no.

permission_store_checked b

Hint whether the screenshot portal has checked the 'screenshot' permission for the requesting app. Defaults to no.

This option was added in version 2 of this interface.

The following results get returned via the results vardict:

uri s

A string containing the uri of the screenshot.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The PickColor() method

PickColor (IN  o     handle,
           IN  s     app_id,
           IN  s     parent_window,
           IN  a{sv} options,
           OUT u     response,
           OUT a{sv} results);

Obtains the value of a pixel.

The following results get returned via the results vardict:

color (ddd)

The color, rgb values in the range [0,1].

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see Common Conventions

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Secret — Secret portal backend interface

Methods

RetrieveSecret (IN  o     handle,
                IN  s     app_id,
                IN  h     fd,
                IN  a{sv} options,
                OUT u     response,
                OUT a{sv} results);

Properties

version  readable   u

Description

The Secret portal allows sandboxed applications to retrieve a per-application master secret.

Method Details

The RetrieveSecret() method

RetrieveSecret (IN  o     handle,
                IN  s     app_id,
                IN  h     fd,
                IN  a{sv} options,
                OUT u     response,
                OUT a{sv} results);

Retrieves a master secret for a sandboxed application.

Supported keys in the options vardict include:

token s

An opaque string associated with the retrieve secret.

IN o handle:

Object path for the org.freedesktop.impl.portal.Request object representing this call

IN s app_id:

App id of the application

IN h fd:

Writable file descriptor for transporting the secret

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Session — Shared session interface

Methods

Close ();

Signals

Closed ();

Properties

version  readable   u

Description

The Session interface is shared by all portal interfaces that involve long lived sessions. When a method that creates a session is called, the reply will include a session handle (i.e. object path) for a Session object, which will stay alive for the duration of the session.

The portal can abort the interaction by calling Close() on the Session object.

Method Details

The Close() method

Close ();

Close the session.

Signal Details

The "Closed" signal

Closed ();

The session was closed by the portal implementation.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Settings — Settings portal backend interface

Methods

ReadAll (IN  as        namespaces,
         OUT a{sa{sv}} value);
Read    (IN  s         namespace,
         IN  s         key,
         OUT v         value);

Signals

SettingChanged (s namespace,
                s key,
                v value);

Properties

version  readable   u

Description

This interface provides read-only access to a small number of host settings required for toolkits similar to XSettings. It is not for general purpose settings.

Currently the interface provides the following keys:

org.freedesktop.appearance color-scheme u

Indicates the system's preferred color scheme. Supported values are:

0: No preference
1: Prefer dark appearance
2: Prefer light appearance

Unknown values should be treated as 0 (no preference).

org.freedesktop.appearance accent-color (ddd)

Indicates the system's preferred accent color as a tuple of RGB values in the sRGB color space, in the range [0,1]. Out-of-range RGB values should be treated as an unset accent color.

Implementations can provide other keys; they are entirely implementation details that are undocumented. If you are a toolkit and want to use this please open an issue.

Note that the Settings portal can operate without this backend, implementing it is optional.

Method Details

The ReadAll() method

ReadAll (IN  as        namespaces,
         OUT a{sa{sv}} value);

If namespaces is an empty array or contains an empty string it matches all. Globbing is supported but only for trailing sections, e.g. "org.example.*".

IN as namespaces:

List of namespaces to filter results by, supports simple globbing explained below.

OUT a{sa{sv}} value:

Dictionary of namespaces to its keys and values.

The Read() method

Read (IN  s namespace,
      IN  s key,
      OUT v value);

Reads a single value. Returns an error on any unknown namespace or key.

IN s namespace:

Namespace to look up key in.

IN s key:

The key to get.

OUT v value:

The value key is set to.

Signal Details

The "SettingChanged" signal

SettingChanged (s namespace,
                s key,
                v value);

Emitted when a setting changes.

s namespace:

Namespace of changed setting.

s key:

The key of changed setting.

v value:

The new value.

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.impl.portal.Wallpaper — Portal for setting the desktop's Wallpaper

Methods

SetWallpaperURI (IN  o     handle,
                 IN  s     app_id,
                 IN  s     parent_window,
                 IN  s     uri,
                 IN  a{sv} options,
                 OUT u     response);

Description

This simple interface lets sandboxed applications set the user's desktop background picture.

Method Details

The SetWallpaperURI() method

SetWallpaperURI (IN  o     handle,
                 IN  s     app_id,
                 IN  s     parent_window,
                 IN  s     uri,
                 IN  a{sv} options,
                 OUT u     response);

Common Conventions options: Options that influence the behavior of the portal response: Numberic response

Asks to set a given picture as the desktop background picture.

The following options are supported:

show-preview b

whether to show a preview of the picture. Note that the portal may decide to show a preview even if this option is not set

set-on s

where to set the wallpaper. Possible values are 'background', 'lockscreen' or 'both'

IN o handle:

Object path to export the Request object at

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window, see

IN s uri:

IN a{sv} options:

OUT u response:

Background Apps Monitoring API


In addition to managing the regular interfaces that sandboxed applications use to interfact with the host system, xdg-desktop-portals also monitors running applications without an active window - if the portal backend provides an implementation of the Background portal.

This API can be used by host system services to provide rich interfaces to manage background running applications.

Table of Contents

org.freedesktop.background.Monitor — Background applications monitor

Name

org.freedesktop.background.Monitor — Background applications monitor

Properties

BackgroundApps  readable   aa{sv}
version         readable   u

Description

This interface provides APIs related to applications that are running in the background.

This documentation describes version 1 of this interface.

Property Details

The "BackgroundApps" property

BackgroundApps  readable   aa{sv}

The list of applications that are considered to be running in background. The following keys are supported:

app_id s

App id of the application.

instance s

The Flatpak instance of the application.

message s

Status message reported by the application. Optional.

The "version" property

version  readable   u