org.freedesktop.portal.Documents: Flatpak Library Reference Manual

## org.freedesktop.portal.Documents

org.freedesktop.portal.Documents — Document portal

## Methods

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

## Properties

    version  readable   u

## Description

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

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

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

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

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

This documentation describes version 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 `path``: | the path at which the fuse filesystem is mounted

### The Add() method

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

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

`IN h `o_path_fd``: | open file descriptor for the file to add
`IN b `reuse_existing``: | whether to reuse an existing document store entry for the file
`IN b `persistent``: | whether to add the file only for this session or permanently
`OUT s `doc_id``: | the ID of the file in the document store

### The AddNamed() method

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

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

`IN h `o_path_parent_fd``: | open file descriptor for the parent directory
`IN ay `filename``: | the basename for the file
`IN b `reuse_existing``: | whether to reuse an existing document store entry for the file
`IN b `persistent``: | whether to add the file only for this session or permanently
`OUT s `doc_id``: | the ID of the file in the document store

### The AddFull() method

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

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

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

Additionally, if app_id is specified, it will be given the permissions listed in 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_fds``: | open file descriptors for the files to export
`IN u `flags``: | flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
`IN s `app_id``: | an application ID, or empty string
`IN as `permissions``: | the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
`OUT as `doc_ids``: | the IDs of the files in the document store
`OUT a{sv} `extra_out``: |

### The AddNamedFull() method

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

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

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

Additionally, if app_id is specified, it will be given the permissions listed in 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_fd``: |
`IN ay `filename``: | the basename for the file
`IN u `flags``: | flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app
`IN s `app_id``: | an application ID, or empty string
`IN as `permissions``: | the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
`OUT s `doc_id``: | the ID of the file in the document store
`OUT a{sv} `extra_out``: |

### The GrantPermissions() method

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

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

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

`IN s `doc_id``: | the ID of the file in the document store
`IN s `app_id``: | the ID of the application to which permissions are granted
`IN as `permissions``: | the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'

### The RevokePermissions() method

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

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

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

`IN s `doc_id``: | the ID of the file in the document store
`IN s `app_id``: | the ID of the application from which permissions are revoked
`IN as `permissions``: | the permissions to revoke, possible values are 'read', 'write', 'grant-permissions' and 'delete'

### The Delete() method

    Delete (IN  s doc_id);

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

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

`IN s `doc_id``: | the ID of the file in the document store

### The Lookup() method

    Lookup (IN  ay filename,
            OUT s  doc_id);

Looks up the document ID for a file.

This call is not available inside the sandbox.

`IN ay `filename``: | a path in the host filesystem
`OUT s `doc_id``: | the ID of the file in the document store, or '' if the file is not in the document store

### The Info() method

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

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

This call is not available inside the sandbox.

`IN s `doc_id``: | the ID of the file in the document store
`OUT ay `path``: | the path for the file in the host filesystem
`OUT a{sas} `apps``: | a dictionary mapping application IDs to the permissions for that application

### The List() method

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

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

This call is not available inside the sandbox.

`IN s `app_id``: | an application ID, or '' to list all documents
`OUT a{say} `docs``: | a dictonary mapping document IDs to their filesystem path

## Property Details

### The "version" property

    version  readable   u