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