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 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 The D-Bus interface for the document portal is available under the 50 bus name org.freedesktop.portal.Documents and the object path 51 /org/freedesktop/portal/documents. 52 53 This documentation describes version 3 of this interface. 54 --> 55 <interface name='org.freedesktop.portal.Documents'> 56 <property name="version" type="u" access="read"/> 57 58 <!-- 59 GetMountPoint: 60 @path: the path at which the fuse filesystem is mounted 61 62 Returns the path at which the document store fuse filesystem 63 is mounted. This will typically be /run/user/$UID/doc/. 64 --> 65 <method name="GetMountPoint"> 66 <arg type='ay' name='path' direction='out'/> 67 </method> 68 69 <!-- 70 Add: 71 @o_path_fd: open file descriptor for the file to add 72 @reuse_existing: whether to reuse an existing document store entry for the file 73 @persistent: whether to add the file only for this session or permanently 74 @doc_id: the ID of the file in the document store 75 76 Adds a file to the document store. The file is passed in the 77 form of an open file descriptor to prove that the caller has 78 access to the file. 79 --> 80 <method name="Add"> 81 <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/> 82 <arg type='h' name='o_path_fd' direction='in'/> 83 <arg type='b' name='reuse_existing' direction='in'/> 84 <arg type='b' name='persistent' direction='in'/> 85 <arg type='s' name='doc_id' direction='out'/> 86 </method> 87 88 <!-- 89 AddNamed: 90 @o_path_parent_fd: open file descriptor for the parent directory 91 @filename: the basename for the file 92 @reuse_existing: whether to reuse an existing document store entry for the file 93 @persistent: whether to add the file only for this session or permanently 94 @doc_id: the ID of the file in the document store 95 96 Creates an entry in the document store for writing a new file. 97 --> 98 <method name="AddNamed"> 99 <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/> 100 <arg type='h' name='o_path_parent_fd' direction='in'/> 101 <arg type='ay' name='filename' direction='in'/> 102 <arg type='b' name='reuse_existing' direction='in'/> 103 <arg type='b' name='persistent' direction='in'/> 104 <arg type='s' name='doc_id' direction='out'/> 105 </method> 106 107 <!-- 108 AddFull: 109 @o_path_fds: open file descriptors for the files to export 110 @flags: flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app 111 @app_id: an application ID, or empty string 112 @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete' 113 @doc_ids: the IDs of the files in the document store 114 @extra_info: Extra info returned 115 116 Adds multiple files to the document store. The file is passed in the 117 form of an open file descriptor to prove that the caller has 118 access to the file. 119 120 If the as-needed-by-app flag is given, files will only be added to 121 the document store if the application does not already have access to them. 122 For files that are not added to the document store, the doc_ids array will 123 contain an empty string. 124 125 Additionally, if app_id is specified, it will be given the permissions 126 listed in GrantPermission. 127 128 The method also returns some extra info that can be used to avoid 129 multiple roundtrips. For now it only contains as "mountpoint", the 130 fuse mountpoint of the document portal. 131 132 This method was added in version 2 of the org.freedesktop.portal.Documents interface. 133 --> 134 <method name="AddFull"> 135 <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/> 136 <arg type='ah' name='o_path_fds' direction='in'/> 137 <arg type='u' name='flags' direction='in'/> 138 <arg type='s' name='app_id' direction='in'/> 139 <arg type='as' name='permissions' direction='in'/> 140 <arg type='as' name='doc_ids' direction='out'/> 141 <arg type='a{sv}' name='extra_out' direction='out'/> 142 </method> 143 144 <!-- 145 AddNamedFull: 146 @o_path_fds: open file descriptor for the parent directory 147 @filename: the basename for the file 148 @flags: flags, 1 == reuse_existing, 2 == persistent, 4 == as-needed-by-app 149 @app_id: an application ID, or empty string 150 @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete' 151 @doc_id: the ID of the file in the document store 152 @extra_info: Extra info returned 153 154 Creates an entry in the document store for writing a new file. 155 156 If the as-needed-by-app flag is given, file will only be added to 157 the document store if the application does not already have access to it. 158 For file that is not added to the document store, the doc_id will 159 contain an empty string. 160 161 Additionally, if app_id is specified, it will be given the permissions 162 listed in GrantPermission. 163 164 The method also returns some extra info that can be used to avoid 165 multiple roundtrips. For now it only contains as "mountpoint", the 166 fuse mountpoint of the document portal. 167 168 This method was added in version 3 of the org.freedesktop.portal.Documents interface. 169 --> 170 <method name="AddNamedFull"> 171 <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/> 172 <arg type='h' name='o_path_fd' direction='in'/> 173 <arg type='ay' name='filename' direction='in'/> 174 <arg type='u' name='flags' direction='in'/> 175 <arg type='s' name='app_id' direction='in'/> 176 <arg type='as' name='permissions' direction='in'/> 177 <arg type='s' name='doc_id' direction='out'/> 178 <arg type='a{sv}' name='extra_out' direction='out'/> 179 </method> 180 181 <!-- 182 GrantPermissions: 183 @doc_id: the ID of the file in the document store 184 @app_id: the ID of the application to which permissions are granted 185 @permissions: the permissions to grant, possible values are 'read', 'write', 'grant-permissions' and 'delete' 186 187 Grants access permissions for a file in the document store 188 to an application. 189 190 This call is available inside the sandbox if the application 191 has the 'grant-permissions' permission for the document. 192 --> 193 <method name="GrantPermissions"> 194 <arg type='s' name='doc_id' direction='in'/> 195 <arg type='s' name='app_id' direction='in'/> 196 <arg type='as' name='permissions' direction='in'/> 197 </method> 198 199 <!-- 200 RevokePermissions: 201 @doc_id: the ID of the file in the document store 202 @app_id: the ID of the application from which permissions are revoked 203 @permissions: the permissions to revoke, possible values are 'read', 'write', 'grant-permissions' and 'delete' 204 205 Revokes access permissions for a file in the document store 206 from an application. 207 208 This call is available inside the sandbox if the application 209 has the 'grant-permissions' permission for the document. 210 --> 211 <method name="RevokePermissions"> 212 <arg type='s' name='doc_id' direction='in'/> 213 <arg type='s' name='app_id' direction='in'/> 214 <arg type='as' name='permissions' direction='in'/> 215 </method> 216 217 <!-- 218 Delete: 219 @doc_id: the ID of the file in the document store 220 221 Removes an entry from the document store. The file itself is 222 not deleted. 223 224 This call is available inside the sandbox if the application 225 has the 'delete' permission for the document. 226 --> 227 <method name="Delete"> 228 <arg type='s' name='doc_id' direction='in'/> 229 </method> 230 231 <!-- 232 Lookup: 233 @filename: a path in the host filesystem 234 @doc_id: the ID of the file in the document store, or '' if the file is not in the document store 235 236 Looks up the document ID for a file. 237 238 This call is not available inside the sandbox. 239 --> 240 <method name="Lookup"> 241 <arg type='ay' name='filename' direction='in'/> 242 <arg type='s' name='doc_id' direction='out'/> 243 </method> 244 245 <!-- 246 Info: 247 @doc_id: the ID of the file in the document store 248 @path: the path for the file in the host filesystem 249 @apps: a dictionary mapping application IDs to the permissions for that application 250 251 Gets the filesystem path and application permissions for a document store 252 entry. 253 254 This call is not available inside the sandbox. 255 --> 256 <method name="Info"> 257 <arg type='s' name='doc_id' direction='in'/> 258 <arg type='ay' name='path' direction='out'/> 259 <arg type='a{sas}' name='apps' direction='out'/> 260 </method> 261 262 <!-- 263 List: 264 @app_id: an application ID, or '' to list all documents 265 @docs: a dictionary mapping document IDs to their filesystem path 266 267 Lists documents in the document store for an application (or for 268 all applications). 269 270 This call is not available inside the sandbox. 271 --> 272 <method name="List"> 273 <arg type='s' name='app_id' direction='in'/> 274 <arg type='a{say}' name='docs' direction='out'/> 275 </method> 276 </interface> 277</node> 278