[glib/sandboxed-dbus-activation: 1/3] Update flatpak document portal interface

[Matthias Clasen <matthiasc src gnome org>]

commit fbdfb8504aafc5437bf1d0a78db5ef454197db20
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue May 23 21:54:39 2017 -0400

    Update flatpak document portal interface
    
    This api has been changed upstream, recently.

 gio/Makefile.am                          |    1 +
 gio/org.freedesktop.portal.Documents.xml |  161 +++++++++++++++++++++++++++++-
 2 files changed, 160 insertions(+), 2 deletions(-)
---
diff --git a/gio/Makefile.am b/gio/Makefile.am
index 67db1b7..b0aad64 100644
--- a/gio/Makefile.am
+++ b/gio/Makefile.am
@@ -383,6 +383,7 @@ $(xdp_dbus_built_sources) : $(portal_interfaces)
                --generate-c-code $(builddir)/xdp-dbus                  \
                --annotate "org.freedesktop.portal.Documents.Add()" "org.gtk.GDBus.C.UnixFD" "true" \
                --annotate "org.freedesktop.portal.Documents.AddNamed()" "org.gtk.GDBus.C.UnixFD" "true" \
+               --annotate "org.freedesktop.portal.Documents.AddFull()" "org.gtk.GDBus.C.UnixFD" "true" \
                $^
 
 portal_sources = \
diff --git a/gio/org.freedesktop.portal.Documents.xml b/gio/org.freedesktop.portal.Documents.xml
index 92eabf9..16da31d 100644
--- a/gio/org.freedesktop.portal.Documents.xml
+++ b/gio/org.freedesktop.portal.Documents.xml
@@ -15,23 +15,79 @@
  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, see <http://www.gnu.org/licenses/>.
+ 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.
+  -->
   <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">
       <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">
       <arg type='h' name='o_path_parent_fd' direction='in'/>
       <arg type='ay' name='filename' direction='in'/>
@@ -39,28 +95,129 @@
       <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
+        @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.
+
+        Additionally, if app_id is specified, it will be given the permissions
+        listed in GrantPermission.
+
+        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 the org.freedesktop.portal.Documents interface.
+    -->
+    <method name="AddFull">
+      <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'/>
+      <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 to which permissions are granted
+        @permissions: the permissions to grant, 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 no 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'/>
       <arg type='a{sas}' name='apps' direction='out'/>
     </method>
+
+    <!--
+        List:
+        @app_id: an application ID, or '' to list all documents
+        @docs: a dictonary 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'/>
       <arg type='a{say}' name='docs' direction='out'/>