Portal API Reference

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:

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

The "version" property

version  readable   u

The RequestBackground() method

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

Requests that the application is allowed to run in the background.

Supported keys in the options vardict include:

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

The SetStatus() method

SetStatus (IN  a{sv} options);

Sets the status of the application running in background.

Supported keys in the options vardict include:

This method was added in version 2.

The "version" property

version  readable   u

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:

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

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.

The "IsCameraPresent" property

IsCameraPresent  readable   b

A boolean stating whether there is any cameras available.

The "version" property

version  readable   u

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:

The "version" property

version  readable   u

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

The "version" property

version  readable   u

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.

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:

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

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.

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.

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.

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.

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:

The "SupportedLauncherTypes" property

SupportedLauncherTypes  readable   u

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

The "version" property

version  readable   u

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:

All the keys in the options are are optional.

The "version" property

version  readable   u

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:

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

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:

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

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:

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

The "version" property

version  readable   u

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:

The AddFiles() method

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

Adds files to a session. This method can be called multiple times on a given session. Note that only regular files (not 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 file lists with multiple AddFiles() calls.

The options vardict currently has no supported entries.

The RetrieveFiles() method

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

Retrieves files that were previously added to the session with AddFiles(). The files 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.

The StopTransfer() method

StopTransfer (IN  s key);

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

The "TransferClosed" signal

TransferClosed (s key);

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

The "version" property

version  readable   u

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.

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:

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:

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);

This method lets you start a new instance of your application, optionally enabling a tighter sandbox.

The following flags values are supported:

Unknown (unsupported) flags are an error and will cause Spawn() to fail.

Unknown (unsupported) options are ignored. The following options are supported:

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.

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

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().

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.

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:

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

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

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

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

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.

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.

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.

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.

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.

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.

The "Active" property

Active  readable   b

Whether any pid on the system has enabled Game Mode.

The "version" property

version  readable   u

The CreateSession() method

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

Creates a global shortcuts session.

Supported keys in the options vardict include:

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

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:

Supported keys in the options vardict include:

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

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:

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:

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

The "Activated" signal

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

Notifies about a shortcut becoming active.

The "Deactivated" signal

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

Notifies that a shortcut is not active anymore.

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.

The "version" property

version  readable   u

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:

Supported keys in the options vardict include:

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:

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

This method was added in version 2 of this interface.

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.

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:

The "version" property

version  readable   u

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:

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:

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:

The "version" property

version  readable   u

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.

The "version" property

version  readable   u

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.

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.

The GetConnectivity() method

GetConnectivity (OUT u connectivity);

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

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

The GetStatus() method

GetStatus (OUT a{sv} status);

Returns the three values all at once.

The following results get returned via status:

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

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.

The "changed" signal

changed ();

Emitted when the network configuration changes.

The "version" property

version  readable   u

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:

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

The RemoveNotification() method

RemoveNotification (IN  s id);

Withdraws a notification.

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.

The "version" property

version  readable   u

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:

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:

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

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:

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

The "version" property

version  readable   u

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

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:

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);

Presents a print dialog to the user and returns print settings and page setup.

Supported keys in the options vardict:

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

The following keys are supported in the print settings vardict:

The following keys are supported in the page setup vardict:

The "version" property

version  readable   u

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.

The "version" property

version  readable   u

The MakeThreadRealtimeWithPID() method

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

The MakeThreadHighPriorityWithPID() method

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

The "MaxRealtimePriority" property

MaxRealtimePriority  readable   i

The "MinNiceLevel" property

MinNiceLevel  readable   i

The "RTTimeUSecMax" property

RTTimeUSecMax  readable   x

The "version" property

version  readable   u

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 interface. Specifically, you can call SelectSources() to also get screen content, and org.freedesktop.portal.ScreenCast.OpenPipewireRemote() to acquire a file descriptor for a PipeWire remote. See org.freedesktop.portal.ScreenCast for more information on how to use those methods.

Supported keys in the options vardict include:

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

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:

For available source types, see the AvailableDeviceTypes property.

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:

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

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

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.

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

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:

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:

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:

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:

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:

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

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

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.

The "AvailableDeviceTypes" property

AvailableDeviceTypes  readable   u

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

The "version" property

version  readable   u

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.

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:

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:

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

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:

For available source types, see the AvailableSourceTypes property.

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:

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

Stream properties include:

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.

The "AvailableSourceTypes" property

AvailableSourceTypes  readable   u

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

The "AvailableCursorModes" property

AvailableCursorModes  readable   u

A bitmask of available cursor modes.

Available cursor mode values:

This property was added in version 2 of this interface.

The "version" property

version  readable   u

The Screenshot() method

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

Supported keys in the options vardict include: parent_window: Identifier for the application window, see Common Conventions options: Vardict with optional further information handle: Object path for the org.freedesktop.portal.Request object representing this call

Takes a screenshot.

Supported keys in the options vardict include:

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

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:

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

The "version" property

version  readable   u

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:

The "version" property

version  readable   u

The Close() method

Close ();

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

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.

The "version" property

version  readable   u

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

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

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.*".

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.

The "SettingChanged" signal

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

Emitted when a setting changes.

The "version" property

version  readable   u

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.

The "version" property

version  readable   u

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:

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:

The "version" property

version  readable   u