<?xml version="1.0"?>
<!--
 Copyright (C) 2018 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 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, see <http://www.gnu.org/licenses/>.

 Author: Matthias Clasen <mclasen@redhat.com>
-->

<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  <!--
       org.freedesktop.portal.FileTransfer:
       @short_description: Portal for transferring files between apps

       The #org.freedesktop.portal.FileTransfer portal operates as a middle-man
       between apps when transferring files via drag-and-drop or copy-paste,
       taking care of the necessary exporting of files in the document portal.

       Toolkits are expected to use the application/vnd.portal.filetransfer
       mimetype when using this mechanism for file exchange via copy-paste
       or drag-and-drop.

       The data that is transmitted with this mimetype should be the key
       returned by the org.freedesktop.portal.FileTransfer.StartTransfer()
       method. Upon receiving this mimetype, the target should call
       org.freedesktop.portal.FileTransfer.RetrieveFiles() with the key,
       to obtain the list of files. The portal will take care of exporting
       files in the document store as necessary to make them accessible to the
       target.

       The D-Bus interface for the this portal is available under the
       bus name org.freedesktop.portal.Documents and the object path
       /org/freedesktop/portal/documents.

       This documentation describes version 1 of this interface.
  -->
  <interface name="org.freedesktop.portal.FileTransfer">
    <!--
        StartTransfer:
        @options: Vardict with optional further information
        @key: a key that needs to be passed to org.freedesktop.portal.FileTransfer.RetrieveFiles() to obtain the files

        Starts a session for a file transfer.
        The caller should call org.freedesktop.portal.FileTransfer.AddFiles()
        at least once, to add files to this session.

        Another application can then call
        org.freedesktop.portal.FileTransfer.RetrieveFiles() to obtain them, if
        it has the @key.

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>writable b</term>
            <listitem><para>
              Whether to allow the chosen application to write to the files.
              Default: False
            </para><para>
              This key only takes effect for files that need to be exported
              in the document portal for the receiving app. But it does require
              the passed-in file descriptors to be writable.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>autostop b</term>
            <listitem><para>
              Whether to stop the transfer automatically after the first
              org.freedesktop.portal.FileTransfer.RetrieveFiles() call. Default: True
            </para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="StartTransfer">
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="s" name="key" direction="out"/>
    </method>

    <!--
        AddFiles:
        @key: A key returned by org.freedesktop.portal.FileTransfer.StartTransfer()
        @fds: File descriptors for the files to register
        @options: Vardict with optional further information

        Adds files to a session. This method can be called multiple times on
        a given session. Note that only regular files (not directories) can
        be added.

        Note that the session bus often has a low limit of file descriptors per
        message (typically, 16), so you may have to send large file lists with
        multiple org.freedesktop.portal.FileTransfer.AddFiles() calls.

        The @options vardict currently has no supported entries.
    -->
    <method name="AddFiles">
      <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
      <arg type="s" name="key" direction="in"/>
      <arg type="ah" name="fds" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
    </method>

    <!--
        RetrieveFiles:
        @key: A key returned by org.freedesktop.portal.FileTransfer.StartTransfer()
        @options: Vardict with optional further information
        @files: list of paths

        Retrieves files that were previously added to the session with
        org.freedesktop.portal.FileTransfer.AddFiles(). The files will be
        exported in the document portal as-needed for the caller, and they
        will be writable if the owner of the session allowed it.

        After the first org.freedesktop.portal.FileTransfer.RetrieveFiles() call,
        the session will be closed by the portal, unless @autostop has been set to False.

        The @options vardict currently has no supported entries.
    -->
    <method name="RetrieveFiles">
      <arg type="s" name="key" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="as" name="files" direction="out"/>
    </method>

    <!--
        StopTransfer:
        @key: A key returned by org.freedesktop.portal.FileTransfer.StartTransfer()

        Ends the transfer. Further calls to org.freedesktop.portal.FileTransfer.AddFiles()
        or org.freedesktop.portal.FileTransfer.RetrieveFiles() for this key will return an error.
    -->
    <method name="StopTransfer">
      <arg type="s" name="key" direction="in"/>
    </method>

    <!--
        TransferClosed:
        @key: key returned by StartTransfer

        The TransferClosed signal is emitted to the caller of StartTransfer
        when the transfer is closed.
    -->
    <signal name="TransferClosed">
      <arg type="s" name="key"/>
    </signal>

    <property name="version" type="u" access="read"/>
  </interface>
</node>
