gio/org.freedesktop.portal.Documents.xml

   1 <!DOCTYPE node PUBLIC
   2 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
   3 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
   4
   5 <!--
   6  Copyright (C) 2015 Red Hat, Inc.
   7
   8  This library is free software; you can redistribute it and/or
   9  modify it under the terms of the GNU Lesser General Public
  10  License as published by the Free Software Foundation; either
  11  version 2.1 of the License, or (at your option) any later version.
  12
  13  This library is distributed in the hope that it will be useful,
  14  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  Lesser General Public License for more details.
  17
  18  You should have received a copy of the GNU Lesser General
  19  Public License along with this library; if not, write to the
  20  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21  Boston, MA 02110-1301, USA.
  22
  23  Author: Alexander Larsson <alexl@redhat.com>
  24 -->
  25
  26 <node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  27   <!--
  28       org.freedesktop.portal.Documents:
  29       @short_description: Document portal
  30
  31       The document portal allows to make files from the outside world
  32       available to sandboxed applications in a controlled way.
  33
  34       Exported files will be made accessible to the application via
  35       a fuse filesystem that gets mounted at /run/user/$UID/doc/. The
  36       filesystem gets mounted both outside and inside the sandbox, but
  37       the view inside the sandbox is restricted to just those files
  38       that the application is allowed to access.
  39
  40       Individual files will appear at /run/user/$UID/doc/$DOC_ID/filename,
  41       where $DOC_ID is the ID of the file in the document store. It is
  42       returned by the org.freedesktop.portal.Documents.Add() and
  43       org.freedesktop.portal.Documents.AddNamed() calls.
  44
  45       The permissions that the application has for a document store entry
  46       (see org.freedesktop.portal.Documents.GrantPermissions()) are reflected
  47       in the POSIX mode bits in the fuse filesystem.
  48   -->
  49   <interface name='org.freedesktop.portal.Documents'>
  50     <property name="version" type="u" access="read"/>
  51
  52     <!--
  53         GetMountPoint:
  54         @path: the path at which the fuse filesystem is mounted
  55
  56         Returns the path at which the document store fuse filesystem
  57         is mounted. This will typically be /run/user/$UID/doc/.
  58     -->
  59     <method name="GetMountPoint">
  60       <arg type='ay' name='path' direction='out'/>
  61     </method>
  62
  63     <!--
  64         Add:
  65         @o_path_fd: open file descriptor for the file to add
  66         @reuse_existing: whether to reuse an existing document store entry for the file
  67         @persistent: whether to add the file only for this session or permanently
  68         @doc_id: the ID of the file in the document store
  69
  70         Adds a file to the document store. The file is passed in the
  71         form of an open file descriptor to prove that the caller has
  72         access to the file.
  73     -->
  74     <method name="Add">
  75       <arg type='h' name='o_path_fd' direction='in'/>
  76       <arg type='b' name='reuse_existing' direction='in'/>
  77       <arg type='b' name='persistent' direction='in'/>
  78       <arg type='s' name='doc_id' direction='out'/>
  79     </method>
  80
  81     <!--
  82         AddNamed:
  83         @o_path_parent_fd: open file descriptor for the parent directory
  84         @filename: the basename for the file
  85         @reuse_existing: whether to reuse an existing document store entry for the file
  86         @persistent: whether to add the file only for this session or permanently
  87         @doc_id: the ID of the file in the document store
  88
  89         Creates an entry in the document store for writing a new file.
  90     -->
  91     <method name="AddNamed">
  92       <arg type='h' name='o_path_parent_fd' direction='in'/>
  93       <arg type='ay' name='filename' direction='in'/>
  94       <arg type='b' name='reuse_existing' direction='in'/>
  95       <arg type='b' name='persistent' direction='in'/>
  96       <arg type='s' name='doc_id' direction='out'/>
  97     </method>
  98
  99     <!--
 100         AddFull:
 101         @o_path_fds: open file descriptors for the files to export
 102         @flags: flags, 1 == reuse_existing, 2 == persistent
 103         @app_id: an application ID, or empty string
 104         @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
 105         @doc_ids: the IDs of the files in the document store
 106         @extra_info: Extra info returned
 107
 108         Adds multiple files to the document store. The file is passed in the
 109         form of an open file descriptor to prove that the caller has
 110         access to the file.
 111
 112         Additionally, if app_id is specified, it will be given the permissions
 113         listed in GrantPermission.
 114
 115         The method also returns some extra info that can be used to avoid
 116         multiple roundtrips. For now it only contains as "mountpoint", the
 117         fuse mountpoint of the document portal.
 118
 119         This method was added in version 2 of the org.freedesktop.portal.Documents interface.
 120     -->
 121     <method name="AddFull">
 122       <arg type='ah' name='o_path_fds' direction='in'/>
 123       <arg type='u' name='flags' direction='in'/>
 124       <arg type='s' name='app_id' direction='in'/>
 125       <arg type='as' name='permissions' direction='in'/>
 126       <arg type='as' name='doc_ids' direction='out'/>
 127       <arg type='a{sv}' name='extra_out' direction='out'/>
 128     </method>
 129
 130     <!--
 131         GrantPermissions:
 132         @doc_id: the ID of the file in the document store
 133         @app_id: the ID of the application to which permissions are granted
 134         @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
 135
 136         Grants access permissions for a file in the document store
 137         to an application.
 138
 139         This call is available inside the sandbox if the application
 140         has the 'grant-permissions' permission for the document.
 141     -->
 142     <method name="GrantPermissions">
 143       <arg type='s' name='doc_id' direction='in'/>
 144       <arg type='s' name='app_id' direction='in'/>
 145       <arg type='as' name='permissions' direction='in'/>
 146     </method>
 147
 148     <!--
 149         RevokePermissions:
 150         @doc_id: the ID of the file in the document store
 151         @app_id: the ID of the application to which permissions are granted
 152         @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete'
 153
 154         Revokes access permissions for a file in the document store
 155         from an application.
 156
 157         This call is available inside the sandbox if the application
 158         has the 'grant-permissions' permission for the document.
 159     -->
 160     <method name="RevokePermissions">
 161       <arg type='s' name='doc_id' direction='in'/>
 162       <arg type='s' name='app_id' direction='in'/>
 163       <arg type='as' name='permissions' direction='in'/>
 164     </method>
 165
 166     <!--
 167         Delete:
 168         @doc_id: the ID of the file in the document store
 169
 170         Removes an entry from the document store. The file itself is
 171         not deleted.
 172
 173         This call is available inside the sandbox if the application
 174         has the 'delete' permission for the document.
 175     -->
 176     <method name="Delete">
 177       <arg type='s' name='doc_id' direction='in'/>
 178     </method>
 179
 180     <!--
 181         Lookup:
 182         @filename: a path in the host filesystem
 183         @doc_id: the ID of the file in the document store, or '' if the file is not in the document store
 184
 185         Looks up the document ID for a file.
 186
 187         This call is no not available inside the sandbox.
 188     -->
 189     <method name="Lookup">
 190       <arg type='ay' name='filename' direction='in'/>
 191       <arg type='s' name='doc_id' direction='out'/>
 192     </method>
 193
 194     <!--
 195         Info:
 196         @doc_id: the ID of the file in the document store
 197         @path: the path for the file in the host filesystem
 198         @apps: a dictionary mapping application IDs to the permissions for that application
 199
 200         Gets the filesystem path and application permissions for a document store
 201         entry.
 202
 203         This call is not available inside the sandbox.
 204     -->
 205     <method name="Info">
 206       <arg type='s' name='doc_id' direction='in'/>
 207       <arg type='ay' name='path' direction='out'/>
 208       <arg type='a{sas}' name='apps' direction='out'/>
 209     </method>
 210
 211     <!--
 212         List:
 213         @app_id: an application ID, or '' to list all documents
 214         @docs: a dictonary mapping document IDs to their filesystem path
 215
 216         Lists documents in the document store for an application (or for
 217         all applications).
 218
 219         This call is not available inside the sandbox.
 220     -->
 221     <method name="List">
 222       <arg type='s' name='app_id' direction='in'/>
 223       <arg type='a{say}' name='docs' direction='out'/>
 224     </method>
 225   </interface>
 226 </node>