<?xml version="1.0"?>
<!--
 Copyright (C) 2019 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.Background:
      @short_description: Portal for requesting autostart and background activity

      This simple interface lets sandboxed applications request that
      the application is allowed to run in the background or started
      automatically when the user logs in.

      This documentation describes version 2 of this interface.
  -->
  <interface name="org.freedesktop.portal.Background">
    <!--
        RequestBackground:
        @parent_window: Identifier for the application window, see <link linkend="parent_window">Common Conventions</link>
        @options: Vardict with optional further information
        @handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Requests that the application is allowed to run in the
        background.

        Supported keys in the @options vardict include:
        <variablelist>
          <varlistentry>
            <term>handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the
              @handle. Must be a valid object path element. See the
              #org.freedesktop.portal.Request documentation for more
              information about the @handle.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>reason s</term>
            <listitem><para>
              User-visible reason for the request.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>autostart b</term>
            <listitem><para>
              TRUE if the app also wants to be started automatically
              at login.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>commandline as</term>
            <listitem><para>
              Commandline to use add when autostarting at login.
              If this is not specified, the Exec line from the
              desktop file will be used.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>dbus-activatable b</term>
            <listitem><para>
              If TRUE, use D-Bus activation for autostart.
            </para></listitem>
          </varlistentry>
        </variablelist>

       The following results get returned via the
       #org.freedesktop.portal.Request::Response signal:

      <variablelist>
        <varlistentry>
          <term>background b</term>
          <listitem><para>
            TRUE if the application is allowed to run in the background.
          </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>autostart b</term>
          <listitem><para>
            TRUE if the application is will be autostarted.
          </para></listitem>
        </varlistentry>
      </variablelist>
    -->
    <method name="RequestBackground">
      <arg type="s" name="parent_window" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
    </method>

    <!--
      SetStatus:
      @options: Vardict with optional further information

      Sets the status of the application running in background.

      Supported keys in the @options vardict include:
      <variablelist>
        <varlistentry>
          <term>message s</term>
          <listitem><para>
            A string that will be used as the status message of the application.
            This should be a single line that can be presented to the user in a
            list, not a full sentence or paragraph. Must be shorter than 96
            characters.
          </para></listitem>
        </varlistentry>
      </variablelist>

      This method was added in version 2.
    -->
    <method name="SetStatus">
      <arg type="a{sv}" name="options" direction="in"/>
    </method>

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