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> 227