Revonzy Mini Shell

<?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 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 StartTransfer method. Upon receiving this mimetype,
       the target should call 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 onformation
        @key: a key that needs to be passed to RetrieveFiles to obtain the files

        Starts a session for a file transfer.
        The caller should call AddFiles at least once, to add files to this session.

        Another application can then call RetrieveFiles to obtain them, if it has
        the @session and @secret.

        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
              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 StartTransfer
        @fds: File descriptors for the files to register

        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 AddFiles calls.
    -->
    <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 StartTransfer
        @options: Vardict with optional further onformation
        @files: list of paths

        Retrieves files that were previously added to the session with
        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 RetrieveFiles call, the session will be closed
        by the portal, unless autostop has been set to False.
    -->
    <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 StartTransfer

        Ends the transfer. Further calls to AddFiles or 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>