"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"

"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">

 Copyright (C) 2015 Red Hat, Inc.

 This library is free software; you can redistribute it and/or

 modify it under the terms of the GNU Lesser General Public

 License as published by the Free Software Foundation; either

 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,

 but WITHOUT ANY WARRANTY; without even the implied warranty of

 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, 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'/>

      <arg type='b' name='reuse_existing' direction='in'/>

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

    </method>

  </interface>

</node>