.. _org.freedesktop.portal.Documents:

================================
 Documents
================================

-----------
Description
-----------

.. _org.freedesktop.portal.Documents Description:

Document portal

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 `org.freedesktop.portal.Documents.Add`_ and
`org.freedesktop.portal.Documents.AddNamed`_ calls.

The permissions that the application has for a document store entry
(see `org.freedesktop.portal.Documents.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 5 of this interface.



.. _org.freedesktop.portal.Documents Properties:

----------
Properties
----------

.. _org.freedesktop.portal.Documents:version:

org.freedesktop.portal.Documents:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.Documents Methods:

-------
Methods
-------

.. _org.freedesktop.portal.Documents.GetMountPoint:

org.freedesktop.portal.Documents.GetMountPoint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetMountPoint (
      OUT path ay
    )



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



path
  the path at which the fuse filesystem is mounted



.. _org.freedesktop.portal.Documents.Add:

org.freedesktop.portal.Documents.Add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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.



o_path_fd
  open file descriptor for the file to add

reuse_existing
  whether to reuse an existing document store entry for the file

persistent
  whether to add the file only for this session or permanently

doc_id
  the ID of the file in the document store



.. _org.freedesktop.portal.Documents.AddNamed:

org.freedesktop.portal.Documents.AddNamed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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



o_path_parent_fd
  open file descriptor for the parent directory

filename
  the basename for the file

reuse_existing
  whether to reuse an existing document store entry for the file

persistent
  whether to add the file only for this session or permanently

doc_id
  the ID of the file in the document store



.. _org.freedesktop.portal.Documents.AddFull:

org.freedesktop.portal.Documents.AddFull
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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 `org.freedesktop.portal.Documents.GrantPermissions`_.

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

This method was added in version 2 of this interface.

Support for exporting directories was added in version 4 of this interface.



o_path_fds
  open file descriptors for the files to export

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

app_id
  an application ID, or empty string

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

doc_ids
  the IDs of the files in the document store

extra_out
  



.. _org.freedesktop.portal.Documents.AddNamedFull:

org.freedesktop.portal.Documents.AddNamedFull
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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 `org.freedesktop.portal.Documents.GrantPermissions`_.

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

This method was added in version 3 of this interface.



o_path_fd
  

filename
  the basename for the file

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

app_id
  an application ID, or empty string

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

doc_id
  the ID of the file in the document store

extra_out
  



.. _org.freedesktop.portal.Documents.GrantPermissions:

org.freedesktop.portal.Documents.GrantPermissions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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.



doc_id
  the ID of the file in the document store

app_id
  the ID of the application to which permissions are granted

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



.. _org.freedesktop.portal.Documents.RevokePermissions:

org.freedesktop.portal.Documents.RevokePermissions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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.



doc_id
  the ID of the file in the document store

app_id
  the ID of the application from which permissions are revoked

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



.. _org.freedesktop.portal.Documents.Delete:

org.freedesktop.portal.Documents.Delete
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Delete (
      IN doc_id s
    )



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.



doc_id
  the ID of the file in the document store



.. _org.freedesktop.portal.Documents.Lookup:

org.freedesktop.portal.Documents.Lookup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Lookup (
      IN filename ay,
      OUT doc_id s
    )



Looks up the document ID for a file.

This call is not available inside the sandbox.



filename
  a path in the host filesystem

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



.. _org.freedesktop.portal.Documents.Info:

org.freedesktop.portal.Documents.Info
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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

This call is not available inside the sandbox.



doc_id
  the ID of the file in the document store

path
  the path for the file in the host filesystem

apps
  a dictionary mapping application IDs to the permissions for that application



.. _org.freedesktop.portal.Documents.List:

org.freedesktop.portal.Documents.List
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

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



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

This call is not available inside the sandbox.



app_id
  an application ID, or '' to list all documents

docs
  a dictionary mapping document IDs to their filesystem path



.. _org.freedesktop.portal.Documents.GetHostPaths:

org.freedesktop.portal.Documents.GetHostPaths
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    GetHostPaths (
      IN doc_ids as,
      OUT paths a{say}
    )



Gets the host filesystem paths for document store entries.

The host filesystem path is also available in the ``user.document-portal.host-path`` extended file attribute.

This call is available inside the sandbox, if the application has the ``read`` permission for the documents.

This method was added in version 5 of this interface.



doc_ids
  the list of IDs of the files in the document store

paths
  a dictionary mapping document IDs to the paths in the host filesystem


