afb81b8278
Some checks failed
Docker. / Ubuntu (push) Has been cancelled
User-agent updater. / User-agent (push) Failing after 15s
Lock Threads / lock (push) Failing after 10s
Waiting for answer. / waiting-for-answer (push) Failing after 22s
Close stale issues and PRs / stale (push) Successful in 13s
Needs user action. / needs-user-action (push) Failing after 8s
Can't reproduce. / cant-reproduce (push) Failing after 8s
305 lines
12 KiB
XML
305 lines
12 KiB
XML
<?xml version="1.0"?>
|
|
|
|
<!--
|
|
Copyright (C) 2015 Red Hat, Inc.
|
|
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General
|
|
Public License along with this library; if not, write to the
|
|
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
|
Boston, MA 02110-1301, USA.
|
|
|
|
Author: Alexander Larsson <alexl@redhat.com>
|
|
-->
|
|
|
|
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
|
<!--
|
|
org.freedesktop.portal.Documents:
|
|
@short_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.
|
|
-->
|
|
<interface name="org.freedesktop.portal.Documents">
|
|
<property name="version" type="u" access="read"/>
|
|
|
|
<!--
|
|
GetMountPoint:
|
|
@path: the path at which the fuse filesystem is mounted
|
|
|
|
Returns the path at which the document store fuse filesystem
|
|
is mounted. This will typically be ``/run/user/$UID/doc/``.
|
|
-->
|
|
<method name="GetMountPoint">
|
|
<arg type="ay" name="path" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
Add:
|
|
@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
|
|
|
|
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.
|
|
-->
|
|
<method name="Add">
|
|
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
|
|
<arg type="h" name="o_path_fd" direction="in"/>
|
|
<arg type="b" name="reuse_existing" direction="in"/>
|
|
<arg type="b" name="persistent" direction="in"/>
|
|
<arg type="s" name="doc_id" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
AddNamed:
|
|
@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
|
|
|
|
Creates an entry in the document store for writing a new file.
|
|
-->
|
|
<method name="AddNamed">
|
|
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
|
|
<arg type="h" name="o_path_parent_fd" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QByteArray"/>
|
|
<arg type="ay" name="filename" direction="in"/>
|
|
<arg type="b" name="reuse_existing" direction="in"/>
|
|
<arg type="b" name="persistent" direction="in"/>
|
|
<arg type="s" name="doc_id" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
AddFull:
|
|
@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_info: Extra info returned
|
|
|
|
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.
|
|
-->
|
|
<method name="AddFull">
|
|
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QList<QDBusUnixFileDescriptor>"/>
|
|
<arg type="ah" name="o_path_fds" direction="in"/>
|
|
<arg type="u" name="flags" direction="in"/>
|
|
<arg type="s" name="app_id" direction="in"/>
|
|
<arg type="as" name="permissions" direction="in"/>
|
|
<arg type="as" name="doc_ids" direction="out"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="extra_out" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
AddNamedFull:
|
|
@o_path_fds: open file descriptor for the parent directory
|
|
@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_info: Extra info returned
|
|
|
|
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.
|
|
-->
|
|
<method name="AddNamedFull">
|
|
<annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
|
|
<arg type="h" name="o_path_fd" direction="in"/>
|
|
<arg type="ay" name="filename" direction="in"/>
|
|
<arg type="u" name="flags" direction="in"/>
|
|
<arg type="s" name="app_id" direction="in"/>
|
|
<arg type="as" name="permissions" direction="in"/>
|
|
<arg type="s" name="doc_id" direction="out"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QVariantMap"/>
|
|
<arg type="a{sv}" name="extra_out" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
GrantPermissions:
|
|
@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``
|
|
|
|
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.
|
|
-->
|
|
<method name="GrantPermissions">
|
|
<arg type="s" name="doc_id" direction="in"/>
|
|
<arg type="s" name="app_id" direction="in"/>
|
|
<arg type="as" name="permissions" direction="in"/>
|
|
</method>
|
|
|
|
<!--
|
|
RevokePermissions:
|
|
@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'
|
|
|
|
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.
|
|
-->
|
|
<method name="RevokePermissions">
|
|
<arg type="s" name="doc_id" direction="in"/>
|
|
<arg type="s" name="app_id" direction="in"/>
|
|
<arg type="as" name="permissions" direction="in"/>
|
|
</method>
|
|
|
|
<!--
|
|
Delete:
|
|
@doc_id: the ID of the file in the document store
|
|
|
|
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.
|
|
-->
|
|
<method name="Delete">
|
|
<arg type="s" name="doc_id" direction="in"/>
|
|
</method>
|
|
|
|
<!--
|
|
Lookup:
|
|
@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
|
|
|
|
Looks up the document ID for a file.
|
|
|
|
This call is not available inside the sandbox.
|
|
-->
|
|
<method name="Lookup">
|
|
<arg type="ay" name="filename" direction="in"/>
|
|
<arg type="s" name="doc_id" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
Info:
|
|
@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
|
|
|
|
Gets the filesystem path and application permissions for a document store
|
|
entry.
|
|
|
|
This call is not available inside the sandbox.
|
|
-->
|
|
<method name="Info">
|
|
<arg type="s" name="doc_id" direction="in"/>
|
|
<arg type="ay" name="path" direction="out"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QMap<QString,QStringList>"/>
|
|
<arg type="a{sas}" name="apps" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
List:
|
|
@app_id: an application ID, or '' to list all documents
|
|
@docs: a dictionary mapping document IDs to their filesystem path
|
|
|
|
Lists documents in the document store for an application (or for
|
|
all applications).
|
|
|
|
This call is not available inside the sandbox.
|
|
-->
|
|
<method name="List">
|
|
<arg type="s" name="app_id" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QMap<QString,QByteArray>"/>
|
|
<arg type="a{say}" name="docs" direction="out"/>
|
|
</method>
|
|
|
|
<!--
|
|
GetHostPaths:
|
|
@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
|
|
|
|
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.
|
|
-->
|
|
<method name="GetHostPaths">
|
|
<arg type="as" name="doc_ids" direction="in"/>
|
|
<annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QMap<QString,QByteArray>"/>
|
|
<arg type="a{say}" name="paths" direction="out"/>
|
|
</method>
|
|
</interface>
|
|
</node>
|