Portal API Reference¶
Table of Contents
- 1. Common Conventions
- I. Portal API Reference
- org.freedesktop.portal.Request — Shared request interface
- org.freedesktop.portal.Session — Shared session interface
- org.freedesktop.portal.FileChooser — File chooser portal
- org.freedesktop.portal.Trash — Portal for trashing files
- org.freedesktop.portal.OpenURI — Portal for opening URIs
- org.freedesktop.portal.Print — Portal for printing
- org.freedesktop.portal.Email — Portal for sending email
- org.freedesktop.portal.Device — Portal for device access
- org.freedesktop.portal.Location — Portal for obtaining information about the location
- org.freedesktop.portal.Screenshot — Portal for taking screenshots
- org.freedesktop.portal.ScreenCast — Screen cast portal
- org.freedesktop.portal.RemoteDesktop — Remote desktop portal
- org.freedesktop.portal.Notification — Portal for sending notifications
- org.freedesktop.portal.Inhibit — Portal for inhibiting session transitions
- org.freedesktop.portal.NetworkMonitor — Network monitoring portal
- org.freedesktop.portal.ProxyResolver — Proxy information
- org.freedesktop.portal.Settings — Settings interface
- org.freedesktop.portal.Documents — Document portal
- org.freedesktop.portal.Flatpak — Flatpak portal
- II. Portal Backend API Reference
- org.freedesktop.impl.portal.Request — Shared request interface
- org.freedesktop.impl.portal.Session — Shared session interface
- org.freedesktop.impl.portal.FileChooser — File chooser portal backend interface
- org.freedesktop.impl.portal.AppChooser — Interface for choosing an application
- org.freedesktop.impl.portal.Print — Print portal backend interface
- org.freedesktop.impl.portal.Email — Email portal backend interface
- org.freedesktop.impl.portal.Screenshot — Screenshot portal backend interface
- org.freedesktop.impl.portal.ScreenCast — Screen cast portal backend interface
- org.freedesktop.impl.portal.RemoteDesktop — Remote desktop portal backend interface
- org.freedesktop.impl.portal.Notification — Notification portal backend interface
- org.freedesktop.impl.portal.Inhibit — Inhibit portal backend interface
- org.freedesktop.impl.portal.Access — Interface for presenting an access dialog
- org.freedesktop.impl.portal.Settings — Settings portal backend interface
- org.freedesktop.impl.portal.Lockdown — Lockdown backend interface
- org.freedesktop.impl.portal.PermissionStore — Database to store permissions
Table of Contents
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.
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.
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.
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.
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 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.Request — Shared request interface
- org.freedesktop.portal.Session — Shared session interface
- org.freedesktop.portal.FileChooser — File chooser portal
- org.freedesktop.portal.Trash — Portal for trashing files
- org.freedesktop.portal.OpenURI — Portal for opening URIs
- org.freedesktop.portal.Print — Portal for printing
- org.freedesktop.portal.Email — Portal for sending email
- org.freedesktop.portal.Device — Portal for device access
- org.freedesktop.portal.Location — Portal for obtaining information about the location
- org.freedesktop.portal.Screenshot — Portal for taking screenshots
- org.freedesktop.portal.ScreenCast — Screen cast portal
- org.freedesktop.portal.RemoteDesktop — Remote desktop portal
- org.freedesktop.portal.Notification — Portal for sending notifications
- org.freedesktop.portal.Inhibit — Portal for inhibiting session transitions
- org.freedesktop.portal.NetworkMonitor — Network monitoring portal
- org.freedesktop.portal.ProxyResolver — Proxy information
- org.freedesktop.portal.Settings — Settings interface
- org.freedesktop.portal.Documents — Document portal
- org.freedesktop.portal.Flatpak — Flatpak portal
Name
org.freedesktop.portal.Request — Shared request interface
Methods
Close ();
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.
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:responseNumeric response
a{sv}:resultsVardict with results. The keys and values in the vardict depend on the request.
Name
org.freedesktop.portal.Session — Shared session interface
Methods
Close ();
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 org.freedesktop.portal.Session::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.
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);
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 1 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 thehandle.- 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.
- 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 pattern (indicated by 0) or a mimetype (indicated by 1).
Example: [('Images', [(0, '*.ico'), (1, 'image/png')]), ('Text', [(0, '*.txt')])]
- 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, te second string is a user-visible label. The a(ss) is the list of choices, each being a is 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')]
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')]
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the file chooser dialog
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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 thehandle.- 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 filename.
- current_folder ay
Suggested folder to save the file in. The byte array is expected to be null-terminated.
- current_file ay
The current file (when saving an existing file). The byte array is expected to be null-terminated.
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.
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the file chooser dialog
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
Name
org.freedesktop.portal.Trash — Portal for trashing files
Methods
TrashFile (IN h fd, OUT u result);
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:fdfile descriptor for the file to trash
OUT u:resultthe result. 0 if trashing failed, 1 if trashing succeeded, other values may be returned in the future
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);
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 2 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 thehandle.- 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.
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:uriThe uri to open
IN a{sv}:optionsVardict with optional further onformation
OUT o:handleObject 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 thehandle.- 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.
The OpenFile method was introduced in version 2 of the OpenURI portal API.
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN h:fdFile descriptor for the file to open
IN a{sv}:optionsVardict with optional further onformation
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
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);
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 1 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 thehandle.- 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_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the print dialog
IN h:fdFile descriptor for reading the content to print
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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);
Presents a print dialog to the user and returns print settings and page setup.
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 thehandle.- modal b
Whether to make the dialog modal. Defaults to yes.
The following results get returned via the "Response" signal:
- 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 following keys are supported in the print settings vardict:
- orientation s
One of landscape, portrait, reverse_landscape or reverse_portrait.
- paper-format s
A paper name according to PWG 5101.1-2002.
- paper-width s
Paper width, in millimeters.
- paper-height s
Paper height, in millimeters.
- n-copies s
The number of copies to print.
- default-source s
The default paper source.
- quality s
Print quality, one of normal, high, low or draft.
- resolution s
The resolution, sets both resolution-x and resolution-y.
- use-color s
Whether to use color, one of true or false.
- duplex s
Duplex printing mode, one of simplex, horizontal or vertical.
- collate s
Whether to collate copies, one of true or false.
- reverse s
Whether to reverse the order of printed pages, one of true or false.
- media-type s
A media type according to PWG 5101.1-2002.
- dither s
The dithering to use, one of fine, none, coarse, lineart, grayscale or error-diffusion.
- scale s
The scale in percent.
- print-pages s
What pages to print, one of all, selection, current or ranges.
- page-ranges s
A list of page ranges, formatted like this: 1-3,5,9-11.
- page-set s
What pages to print, one of all, even or odd.
- finishings s
- number-up s
The number of pages per sheet.
- number-up-layout s
One of lrtb, lrbt, rltb, rlbt, tblr, tbrl, btlr, btrl.
- output-bin s
- resolution-x s
The horizontal resolution in dpi.
- resolution-y s
The vertical resolution in dpi.
- printer-lpi s
The resolution in lpi (lines per inch).
- output-basename s
Basename to use for print-to-file.
- output-file-format s
Format to use for print-to-file, one of PDF, PS, SVG.
- output-uri s
The uri used for print-to-file.
The following keys are supported in the page setup vardict:
- PPDName s
The PPD name.
- Name s
The name of the page setup.
- DisplayName s
User-visible name for the page setup.
- Width d
Paper width in millimeters.
- Height d
Paper height in millimeters.
- MarginTop d
Top margin in millimeters.
- MarginBottom d
Bottom margin in millimeters.
- MarginLeft d
Left margin in millimeters.
- MarginRight d
Right margin in millimeters.
- Orientation s
Orientation, one of portrait, landscape, reverse-portrait or reverse-landscape.
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the print dialog
IN a{sv}:settingsSerialized print settings
IN a{sv}:page_setupSerialized page setup
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
Name
org.freedesktop.portal.Email — Portal for sending email
Methods
ComposeEmail (IN s parent_window, IN a{sv} options, OUT o handle);
Description
This simple portal lets sandboxed applications request to send an email, optionally providing an address, subject, body and attachments.
This documentation describes version 2 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.
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 thehandle.- address s
The email address to send to.
- subject s
The subject for the email.
- body s
The body for the email.
- attachment_fds ah
File descriptors for files to attach.
All the keys in the options are are optional.
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
Name
org.freedesktop.portal.Device — Portal for device access
Methods
AccessDevice (IN u pid, IN as devices, IN a{sv} options, OUT o handle);
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 thehandle.
IN u:pidthe pid of the application on whose behalf the request is made
IN as:devicesa 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}:optionsvardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
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);
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 org.freedesktop.portal.Session::Close, or may
at any time be closed by the portal implementation, which will be
signalled via org.freedesktop.portal.Session::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}:optionsVardict with optional further information
OUT o:handleObject 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 thehandle.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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 microsections since the Unix epoch.
o:session_handleObject path for the org.freedesktop.portal.Session object
a{sv}:locationVardict with the current location data
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);
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);
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:
- 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 thehandle.- modal b
Whether the dialog should be modal. Default is yes.
- interactive b
Hint shether 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_windowIN a{sv}:optionsOUT o:handle
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 thehandle.
The following results get returned via the "Response" signal:
- color (ddd)
The color, rgb values in the range [0,1].
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
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);
Description
The Screen cast portal allows to create screen cast sessions.
This documentation describes version 1 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 org.freedesktop.portal.Session::Close, or may at any time be closed by the portal implementation, which will be signalled via org.freedesktop.portal.Session::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 thehandle.- 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}:optionsVardict with optional further information
OUT o:handleObject 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 thehandle.- types u
Bitmask of what types of content to record. Default is MONITOR.
- multiple b
Whether to allow selecting multiple sources. Default is no.
For available source types, see the AvailableSourceTypes property.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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 org.freedesktop.portal.ScreenCast::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 thehandle.
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.
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.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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_remote object, by using
pw_remote_connect_fd. Only the screen cast stream
nodes will be available from this PipeWire node.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
OUT h:fdFile descriptor of an open PipeWire remote.
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);
Description
The Remote desktop portal allows to create remote desktop sessions.
This documentation describes version 1 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. 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.
To also get a screen content, call the #org.freedesktop.ScreenCast.SelectSources with the #org.freedesktop.Session object created with this method.
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 thehandle.- 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}:optionsVardict with optional further information
OUT o:handleObject 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 thehandle.- types u
Bitmask of what device types to request remote controlling of. Default is all.
For available source types, see the AvailableDeviceTypes property.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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 thehandle.
The following results get returned via the "Response" signal:
- devices u
A bitmask of the devices selected by the user.
If a screen cast source was selected, the results of the org.freedesktop.portal.ScreenCast.Start response signal may be included.
IN o:session_handleObject path for the org.freedesktop.portal.Session object
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN d:dxRelative movement on the x axis
IN d:dyRelative 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN d:xPointer motion x coordinate
IN d:yPointer 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:buttonThe pointer button was pressed or released
IN u:stateThe 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN d:dxRelative axis movement on the x axis
IN d:dyRelative 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:axisThe axis that was scrolled
IN i:stepsThe 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:keycodeKeyboard code that was pressed or released
IN u:stateNew 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:keysymKeyboard symbol that was pressed or released
IN u:stateNew 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN u:slotTouch slot where touch point appeared
IN d:xTouch down x coordinate
IN d:yTouch 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN u:slotTouch slot where touch point appeared
IN d:xTouch motion x coordinate
IN d:yTouch 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:slotTouch slot where touch point appeared
Name
org.freedesktop.portal.Notification — Portal for sending notifications
Methods
AddNotification (IN s id, IN a{sv} notification); RemoveNotification (IN s id);
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 #org.freedeskop.portal.Notification::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:idApplication-provided ID for this notification
IN a{sv}:notificationVardict with the serialized 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:idthe application-provided ID for the notification
s:actionthe name of the action
av:parameterarray which will contain the target parameter
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);
Description
This simple interface lets sandboxed applications inhibit the user session from ending, suspending, idling or getting switched away.
This documentation describes version 2 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 thehandle.- reason s
User-visible reason for the inhibition.
IN s:windowIdentifier for the window
IN u:flagsFlags identifying what is inhibited
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject 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 org.freedesktop.portal.Session::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 thehandle.- 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:windowthe parent window
IN a{sv}:optionsVardict with optional further information
OUT o:handleObject path for the org.freedesktop.portal.Request object representing this call
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.
The following information may get returned in the state vardict:
- screensaver-active b
Whether the screensaver is active.
o:session_handleObject path for the org.freedesktop.portal.Session object
a{sv}:stateVardict with information about the session state
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);
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:availablewhether 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:meteredwhether 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:connectivitythe 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}:statusa dictionary with the current values
Name
org.freedesktop.portal.ProxyResolver — Proxy information
Methods
Lookup (IN s uri, OUT as proxies);
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:uriDestination to connect to
OUT as:proxiesList of proxy uris
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);
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 valid keys are entirely implementation details that are undocumented. If you are a toolkit and want to use this please open an issue.
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:namespacesList of namespaces to filter results by, supports simple globbing explained below.
OUT a{sa{sv}}:valueDictionary of namespaces to its keys and values.
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);
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 3 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:paththe 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_fdopen file descriptor for the file to add
IN b:reuse_existingwhether to reuse an existing document store entry for the file
IN b:persistentwhether to add the file only for this session or permanently
OUT s:doc_idthe 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_fdopen file descriptor for the parent directory
IN ay:filenamethe basename for the file
IN b:reuse_existingwhether to reuse an existing document store entry for the file
IN b:persistentwhether to add the file only for this session or permanently
OUT s:doc_idthe 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 GrantPermission.
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.
IN ah:o_path_fdsopen file descriptors for the files to export
IN u:flagsflags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
IN s:app_idan application ID, or empty string
IN as:permissionsthe permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
OUT as:doc_idsthe 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 GrantPermission.
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_fdIN ay:filenamethe basename for the file
IN u:flagsflags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
IN s:app_idan application ID, or empty string
IN as:permissionsthe permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
OUT s:doc_idthe 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_idthe ID of the file in the document store
IN s:app_idthe ID of the application to which permissions are granted
IN as:permissionsthe 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_idthe ID of the file in the document store
IN s:app_idthe ID of the application from which permissions are revoked
IN as:permissionsthe 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_idthe 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:filenamea path in the host filesystem
OUT s:doc_idthe 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_idthe ID of the file in the document store
OUT ay:paththe path for the file in the host filesystem
OUT a{sas}:appsa 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_idan application ID, or '' to list all documents
OUT a{say}:docsa dictonary mapping document IDs to their filesystem path
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);
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.
The D-Bus interface for the document portal is available under the bus name org.freedesktop.portal.Flatpak and the object path /org/freedesktop/portal/flatpak.
This documentation describes version 1 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);
This methods let you start a new instance of your application, optionally enabling a tighter sandbox.
The following flags values are supported:
- 1
Clear the environment.
- 2
Spawn the latest version of the app.
- 4
Spawn in a sandbox (equivalent of the sandbox option of flatpak run).
- 8
Spawn without network (equivalent of the unshare=network option of flatpak run).
The following options are supported:
- sandbox-expose as
A list of filenames for files inside the sandbox that will be exposed to the new sandbox, for reading and writing. Note that absolute paths or subdirectories are not allowed.
- sandbox-expose-ro as
A list of filenames for files inside the sandbox that will be exposed to the new sandbox, readonly. Note that absolute paths or subdirectories are not allowed.
IN ay:cwd_paththe working directory for the new process
IN aay:argvthe argv for the new process, starting with the executable to launch
IN a{uh}:fdsan array of file descriptors to pass to the new process
IN a{ss}:envsan array of variable/value pairs for the environment of the new process
IN u:flagsflags
IN a{sv}:optionsVardict with optional further information
OUT u:pidthe PID of the new process
The SpawnSignal() method
SpawnSignal (IN u pid,
IN u signal,
IN b to_process_group);
This methods let 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.
IN u:pidthe PID of the process to send the signal to
IN u:signalthe signal to send (see signal(7))
IN b:to_process_groupwhether to send the signal to the process group
Signal Details
The "SpawnExited" signal
SpawnExited (u pid,
u exit_status);
Emitted when a process started by Spawn() exits.
u:pidthe PID of the process that has ended
u:exit_statusthe exit status (see waitpid(2))
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 or 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.Request — Shared request interface
- org.freedesktop.impl.portal.Session — Shared session interface
- org.freedesktop.impl.portal.FileChooser — File chooser portal backend interface
- org.freedesktop.impl.portal.AppChooser — Interface for choosing an application
- org.freedesktop.impl.portal.Print — Print portal backend interface
- org.freedesktop.impl.portal.Email — Email portal backend interface
- org.freedesktop.impl.portal.Screenshot — Screenshot portal backend interface
- org.freedesktop.impl.portal.ScreenCast — Screen cast portal backend interface
- org.freedesktop.impl.portal.RemoteDesktop — Remote desktop portal backend interface
- org.freedesktop.impl.portal.Notification — Notification portal backend interface
- org.freedesktop.impl.portal.Inhibit — Inhibit portal backend interface
- org.freedesktop.impl.portal.Access — Interface for presenting an access dialog
- org.freedesktop.impl.portal.Settings — Settings portal backend interface
- org.freedesktop.impl.portal.Lockdown — Lockdown backend interface
- org.freedesktop.impl.portal.PermissionStore — Database to store permissions
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.
Name
org.freedesktop.impl.portal.Session — Shared session interface
Methods
Close ();
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.
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);
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.
- filters a(sa(us))
A 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)
A list of serialized combo boxes. See 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 OpenFile() for details.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the file chooser dialog
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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 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)
A list of serialized combo boxes. See 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 OpenFile() for details.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the file chooser dialog
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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.
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.
The following results get returned via the results vardict:
- choice s
The app id that was selected.
IN o:handleObject path to export the Request object at
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN as:choicesApp ids of applications to let the user choose from
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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:handlethe request handle
IN as:choicesApp ids of applications to let the user choose from
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);
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:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the print dialog
IN h:fdFile descriptor from which to read the content to print
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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.
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 Print() documentation has details about the supported keys in settings and page-setup.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the print dialog
IN a{sv}:settingsSerialized print settings
IN a{sv}:page_setupSerialized page setup
IN a{sv}:optionsVardict with optional further information
OUT u:responseOUT a{sv}:results
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);
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.
- subject s
The subject for the email.
- body s
The body for the email.
- attachments as
The uris for files to attach.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict with the results of the call
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);
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.
The following results get returned via the results vardict:
- uri s
A string containing the uri of the screenshot.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict with the results of the call
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);
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 screen cast session.
The following results get returned via the "Response" signal:
- session_id s
The session id. A string representing the created screen cast session.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleObject path for the org.freedesktop.impl.portal.Session object representing the session being created
IN s:app_idApp id of the application
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict with the results of the call
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.
For available source types, see the AvailableSourceTypes property.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleObject path for the org.freedesktop.impl.portal.Session object representing the session
IN s:app_idApp id of the application
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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 "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.
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.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleObject path for the org.freedesktop.impl.portal.Session object representing the session
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict with the results of the call
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);
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 "Response" signal:
- session s
The session id. A string representing the created screen cast session.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleIN s:app_idApp id of the application
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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);
IN o:handleIN o:session_handleIN s:app_idIN a{sv}:optionsOUT u:responseOUT a{sv}:results
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.
IN o:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleIN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN d:dxRelative movement on the x axis
IN d:dyRelative 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN d:xPointer motion x coordinate
IN d:yPointer 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:buttonThe pointer button was pressed or released
IN u:stateThe 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN d:dxRelative axis movement on the x axis
IN d:dyRelative 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:axisThe axis that was scrolled
IN i:stepsThe 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:keycodeKeyboard code that was pressed or released
IN u:stateNew 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN i:keysymKeyboard symbol that was pressed or released
IN u:stateNew 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN u:slotTouch slot where touch point appeared
IN d:xTouch down x coordinate
IN d:yTouch 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:streamThe PipeWire stream node the coordinate is relative to
IN u:slotTouch slot where touch point appeared
IN d:xTouch motion x coordinate
IN d:yTouch 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_handleObject path for the org.freedesktop.portal.Session object
IN a{sv}:optionsVardict with optional further information
IN u:slotTouch slot where touch point appeared
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);
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
AddNotification().
IN s:app_idApp id of the application
IN s:idApplication-provided ID for this notification
IN a{sv}:notificationVardict with the serialized 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_idApp id of the application
s:idthe application-provided ID for the notification
s:actionthe name of the action
av:parameterarray which will contain the target parameter
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);
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:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApplication id
IN s:windowIdentifier for the window
IN u:flagsFlags identifying what is inhibited
IN a{sv}:optionsVardict 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:handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN o:session_handleObject path for the org.freedesktop.impl.portal.Request object representing this call
IN s:app_idApp id of the application
IN s:windowthe parent window
OUT u:response
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.
The following information may get returned in the state vardict:
- screensaver-active b
Whether the screensaver is active.
o:session_handleObject path for the org.freedesktop.portal.Session object
a{sv}:stateVardict with information about the session state
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 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 OpenFile() for details.
IN o:handleObject path to export the Request object at
IN s:app_idApp id of the application
IN s:parent_windowIdentifier for the application window, see Common Conventions
IN s:titleTitle for the dialog
IN s:subtitleSubtitle for the dialog
IN s:bodyBody text, may be ""
IN a{sv}:optionsVardict with optional further information
OUT u:responseNumeric response
OUT a{sv}:resultsVardict with the results of the call
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);
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 valid keys 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:namespacesList of namespaces to filter results by, supports simple globbing explained below.
OUT a{sa{sv}}:valueDictionary of namespaces to its keys and values.
Name
org.freedesktop.impl.portal.Lockdown — Lockdown backend interface
Properties
disable-printing readable b disable-save-to-disk readable b disable-application-handlers readable b disable-location readable b disable-camera readable b disable-microphone readable b disable-sound-output readable 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.
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); List (IN s table, OUT as ids);
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.
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:tablethe name of the table to use
IN s:idthe resource ID to look up
OUT a{sas}:permissionsmap from application ID to permissions
OUT v:datadata 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:tablethe name of the table to use
IN b:createwhether to create the table if it does not exist
IN s:idthe resource ID to modify
IN a{sas}:app_permissionsmap from application ID to permissions
IN v:datadata 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:tablethe name of the table to use
IN s:idthe 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:tablethe name of the table to use
IN b:createwhether to create the table if it does not exist
IN s:idthe resource ID to modify
IN v:datadata 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:tablethe name of the table to use
IN b:createwhether to create the table if it does not exist
IN s:idthe resource ID to modify
IN s:appthe application ID to modify
IN as:permissionspermissions to set
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:tablethe name of the table
s:idb:deletedwhether the resource was deleted
v:datathe data that is associated the resource
a{sas}:permissionsthe permissions that are associated with the resource