Portal Documentation

Version 0.6


Table of Contents

I. Portal API Reference
org.freedesktop.portal.Request — Shared request interface
org.freedesktop.portal.FileChooser — File chooser portal
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.Screenshot — Portal for taking screenshots
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.Documents — Document portal
II. Portal Backend API Reference
org.freedesktop.impl.portal.Request — Shared request 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.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.PermissionStore — Database to store permissions

Portal API Reference


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

Requests made via portal interfaces generally involve user interaction.

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.

Table of Contents

org.freedesktop.portal.Request — Shared request interface
org.freedesktop.portal.FileChooser — File chooser portal
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.Screenshot — Portal for taking screenshots
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.Documents — Document portal

Name

org.freedesktop.portal.Request — Shared request interface

Methods

Close ();

Signals

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

Description

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

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

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

Method Details

The Close() method

Close ();

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

Signal Details

The "Response" signal

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

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

The response indicates how the user interaction ended:

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

u response:

Numeric response

a{sv} results:

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


Name

org.freedesktop.portal.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);

Properties

version  readable   u

Description

The FileChooser portal allows sandboxed applications to ask the user for access to files outside the sandbox. The portal backend will present the user with a file chooser dialog.

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

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict include:

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')])]

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_window:

Identifier for the application window

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

The SaveFile() method

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

Asks for a location to save a file.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict include:

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.

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.

current_file ay

The current file (when saving an existing file).

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_window:

Identifier for the application window

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Properties

version  readable   u

Description

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

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict include:

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_window:

Identifier for the application window

IN s uri:

The uri to open

IN a{sv} options:

Vardict with optional further onformation

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.Print — Portal for printing

Methods

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

Properties

version  readable   u

Description

The Print portal allows sandboxed applications to print.

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

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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 s parent_window:

Identifier for the application window

IN s title:

Title for the print dialog

IN h fd:

File descriptor for reading the content to print

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

The PreparePrint() method

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

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

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict:

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_window:

Identifier for the application window

IN s title:

Title for the print dialog

IN a{sv} settings:

Serialized print settings

IN a{sv} page_setup:

Serialized page setup

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Properties

version  readable   u

Description

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

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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.

All the keys in the options are are optional.

IN s parent_window:

Identifier for the application window

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Properties

version  readable   u

Description

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

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.

IN u pid:

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

IN as devices:

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

IN a{sv} options:

vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Properties

version  readable   u

Description

This simple portal lets sandboxed applications request a screenshot.

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

Method Details

The Screenshot() method

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

Takes a screenshot.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict include:

modal b

Whether the dialog should be modal. Default is yes.

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

uri s

String containing the uri of the screenshot.

IN s parent_window:

Identifier for the application window

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Signals

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

Properties

version  readable   u

Description

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

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

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

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

priority s

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

default-action s

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

default-action-target v

Target parameter to send along when activating the default action.

buttons aa{sv}

Array of serialized buttons to add to the notification.

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

label s

User-visible label for the button. Mandatory.

action s

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

target v

Target parameter to send along when activating the action.

IN s id:

Application-provided ID for this notification

IN a{sv} notification:

Vardict with the serialized notification

The RemoveNotification() method

RemoveNotification (IN  s id);

Withdraws a notification.

IN s id:

Application-provided ID for this notification

Signal Details

The "ActionInvoked" signal

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

for the action, if one was specified

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

s id:

the application-provided ID for the notification

s action:

the name of the action

av parameter:

array which will contain the target parameter

Property Details

The "version" property

version  readable   u


Name

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

Methods

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

Properties

version  readable   u

Description

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

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:

reason s

User-visible reason for the inhibition.

IN s window:

Identifier for the window

IN u flags:

Flags identifying what is inhibited

IN a{sv} options:

Vardict with optional further information

OUT o handle:

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

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.NetworkMonitor — Network monitoring portal

Signals

changed (b available);

Properties

available     readable   b
metered       readable   b
connectivity  readable   u
version       readable   u

Description

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

Signal Details

The "changed" signal

changed (b available);

Emitted when the network configuration changes.

b available:

Whether network is currently available

Property Details

The "available" property

available  readable   b

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

The "metered" property

metered  readable   b

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.

The "connectivity" property

connectivity  readable   u

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.

The "version" property

version  readable   u


Name

org.freedesktop.portal.ProxyResolver — Proxy information

Methods

Lookup (IN  s  uri,
        OUT as proxies);

Properties

version  readable   u

Description

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

Method Details

The Lookup() method

Lookup (IN  s  uri,
        OUT as proxies);

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

IN s uri:

Destination to connect to

OUT as proxies:

List of proxy uris

Property Details

The "version" property

version  readable   u


Name

org.freedesktop.portal.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);
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.

Method Details

The GetMountPoint() method

GetMountPoint (OUT ay path);

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

OUT ay path:

the path at which the fuse filesystem is mounted

The Add() method

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

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

IN h o_path_fd:

open file descriptor for the file to add

IN b reuse_existing:

whether to reuse an existing document store entry for the file

IN b persistent:

whether to add the file only for this session or permanently

OUT s doc_id:

the ID of the file in the document store

The AddNamed() method

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

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

IN h o_path_parent_fd:

open file descriptor for the parent directory

IN ay filename:

the basename for the file

IN b reuse_existing:

whether to reuse an existing document store entry for the file

IN b persistent:

whether to add the file only for this session or permanently

OUT s doc_id:

the ID of the file in the document store

The GrantPermissions() method

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

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

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

IN s doc_id:

the ID of the file in the document store

IN s app_id:

the ID of the application to which permissions are granted

IN as permissions:

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

The RevokePermissions() method

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

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

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

IN s doc_id:

the ID of the file in the document store

IN s app_id:

the ID of the application to which permissions are granted

IN as permissions:

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

The Delete() method

Delete (IN  s doc_id);

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

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

IN s doc_id:

the ID of the file in the document store

The Lookup() method

Lookup (IN  ay filename,
        OUT s  doc_id);

Looks up the document ID for a file.

This call is no not available inside the sandbox.

IN ay filename:

a path in the host filesystem

OUT s doc_id:

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

The Info() method

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

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

This call is not available inside the sandbox.

IN s doc_id:

the ID of the file in the document store

OUT ay path:

the path for the file in the host filesystem

OUT a{sas} apps:

a dictionary mapping application IDs to the permissions for that application

The List() method

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

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

This call is not available inside the sandbox.

IN s app_id:

an application ID, or '' to list all documents

OUT a{say} docs:

a dictonary mapping document IDs to their filesystem path

Portal Backend API Reference


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

The separation 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.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.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.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.

Method Details

The Close() method

Close ();

Ends the user interaction to which this object refers. Dialogs and other UIs related to the request should be closed.


Name

org.freedesktop.impl.portal.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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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.

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 handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The SaveFile() method

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

Presents a file chooser dialog to the user to save a file.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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.

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 handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN s title:

Title for the file chooser dialog

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


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

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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.

The following results get returned via the results vardict:

choice s

The app id that was selected.

IN o handle:

Object path to export the Request object at

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN as choices:

App ids of applications to let the user choose from

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

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

Methods

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

Description

The Print portal allows sandboxed applications to print.

Method Details

The Print() method

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

Prints a file.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

The file is given in the form of a file descriptor open for reading.

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

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

Supported keys in the options vardict:

modal b

Whether to make the dialog modal. Defaults to yes.

token u

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

IN o handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN s title:

Title for the print dialog

IN h fd:

File descriptor from which to read the content to print

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call

The PreparePrint() method

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

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

Supported keys in the options vardict:

modal b

Whether to make the dialog modal. Defaults to yes.

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 handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN s title:

Title for the print dialog

IN a{sv} settings:

Serialized print settings

IN a{sv} page_setup:

Serialized page setup

IN a{sv} options:

Vardict with optional further information

OUT u response:

OUT a{sv} results:


Name

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

Methods

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

Description

This Email portal lets sandboxed applications request sending an email.

Method Details

The ComposeEmail() method

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

Lets the user compose an email.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

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 handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

org.freedesktop.impl.portal.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);

Description

This screenshot portal lets sandboxed applications request a screenshot.

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.

The parent_window identifier must be of the form "x11:$XID" for an X11 window. Support for other window systems may be added in the future.

Supported keys in the options vardict include:

modal b

Whether the dialog should be modal. Defaults to yes.

The following results get returned via the results vardict:

uri s

A string containing the uri of the screenshot.

IN o handle:

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

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

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

Methods

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

Signals

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

Description

This notification interface lets sandboxed applications send and withdraw notifications.

Method Details

The AddNotification() method

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

Sends a notification.

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

The format of the notification is the same as for AddNotification().

IN s app_id:

App id of the application

IN s id:

Application-provided ID for this notification

IN a{sv} notification:

Vardict with the serialized notification

The RemoveNotification() method

RemoveNotification (IN  s app_id,
                    IN  s id);

Withdraws a notification.

IN s app_id:

App id of the application

IN s id:

Application-provided ID for this notification

Signal Details

The "ActionInvoked" signal

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

for the action, if one was specified

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

s app_id:

App id of the application

s id:

the application-provided ID for the notification

s action:

the name of the action

av parameter:

array which will contain the target parameter


Name

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

Methods

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

Description

The inhibit portal lets sandboxed applications inhibit the user session from ending, suspending, idling or getting switched away.

Method Details

The Inhibit() method

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

Inhibits session status changes. As a side-effect of this call, a org.freedesktop.impl.portal.Request object is exported on the object path handle. To end the inhibition, call Close() on that object.

The flags determine what changes are inhibited:

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

Supported keys in the options vardict include:

reason s

User-visible reason for the inhibition.

IN o handle:

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

IN s app_id:

Application id

IN s window:

Identifier for the window

IN u flags:

Flags identifying what is inhibited

IN a{sv} options:

Vardict with optional further information


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 handle:

Object path to export the Request object at

IN s app_id:

App id of the application

IN s parent_window:

Identifier for the application window

IN s title:

Title for the dialog

IN s subtitle:

Subtitle for the dialog

IN s body:

Body text, may be ""

IN a{sv} options:

Vardict with optional further information

OUT u response:

Numeric response

OUT a{sv} results:

Vardict with the results of the call


Name

org.freedesktop.impl.portal.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);

Signals

Changed (s      table,
         s      id,
         b      deleted,
         v      data,
         a{sas} permissions);

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 table:

the name of the table to use

IN s id:

the resource ID to look up

OUT a{sas} permissions:

map from application ID to permissions

OUT v data:

data that is associated with the resource

The Set() method

Set (IN  s      table,
     IN  b      create,
     IN  s      id,
     IN  a{sas} app_permissions,
     IN  v      data);

Writes the entry for a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN a{sas} app_permissions:

map from application ID to permissions

IN v data:

data to associate with the resource

The Delete() method

Delete (IN  s table,
        IN  s id);

Removes the entry for a resource in the given table.

IN s table:

the name of the table to use

IN s id:

the resource ID to delete

The SetValue() method

SetValue (IN  s table,
          IN  b create,
          IN  s id,
          IN  v data);

Sets just the data for a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN v data:

data to associate with the resource

The SetPermission() method

SetPermission (IN  s  table,
               IN  b  create,
               IN  s  id,
               IN  s  app,
               IN  as permissions);

Sets the permissions for an application and a resource in the given table.

IN s table:

the name of the table to use

IN b create:

whether to create the table if it does not exist

IN s id:

the resource ID to modify

IN s app:

the application ID to modify

IN as permissions:

permissions to set

The List() method

List (IN  s  table,
      OUT as ids);

Returns all the resources that are present in the table.

IN s table:

the name of the table to use

OUT as ids:

IDs of all resources that are present in the table

Signal Details

The "Changed" signal

Changed (s      table,
         s      id,
         b      deleted,
         v      data,
         a{sas} permissions);

The Changed signal is emitted when the entry for a resource is modified or deleted. If the entry was deleted, then data and permissions contain the last values that were found in the database. If the entry was modified, they contain the new values.

s table:

the name of the table

s id:

b deleted:

whether the resource was deleted

v data:

the data that is associated the resource

a{sas} permissions:

the permissions that are associated with the resource