<?xml version="1.0"?>
<!--
 Copyright (C) 2016 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.Inhibit:
      @short_description: Portal for inhibiting session transitions

      This simple interface lets sandboxed applications inhibit the user
      session from ending, suspending, idling or getting switched away.

      This documentation describes version 3 of this interface.
  -->
  <interface name="org.freedesktop.portal.Inhibit">
    <!--
        Inhibit:
        @window: Identifier for the window
        @flags: Flags identifying what is inhibited
        @options: Vardict with optional further information
        @handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Inhibits a session status changes. To remove the inhibition,
        call org.freedesktop.portal.Request.Close() on the returned
        handle.

        The flags determine what changes are inhibited:
        <simplelist>
          <member>1: Logout</member>
          <member>2: User Switch</member>
          <member>4: Suspend</member>
          <member>8: Idle</member>
        </simplelist>

        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 inhibition.</para></listitem>
          </varlistentry>
        </variablelist>
    -->
    <method name="Inhibit">
      <arg type="s" name="window" direction="in"/>
      <arg type="u" name="flags" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
    </method>

    <!--
        CreateMonitor:
        @window: the parent window
        @options: Vardict with optional further information
        @handle: Object path for the #org.freedesktop.portal.Request object representing this call

        Creates a monitoring session. While this session is
        active, the caller will receive StateChanged signals
        with updates on the session state.

        A successfully created session can at any time be closed using
        org.freedesktop.portal.Session::Close, or may at any time be closed
        by the portal implementation, which will be signalled via
        org.freedesktop.portal.Session::Closed.

        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>session_handle_token s</term>
            <listitem><para>
              A string that will be used as the last element of the session handle. Must be a valid
              object path element. See the #org.freedesktop.portal.Session documentation for
              more information about the session handle.
            </para></listitem>
          </varlistentry>
        </variablelist>

        The following results get returned via the #org.freedesktop.portal.Request::Response signal:
        <variablelist>
          <varlistentry>
            <term>session_handle o</term>
            <listitem><para>
              The session handle. An object path for the
              #org.freedesktop.portal.Session object representing the created
              session.
            </para></listitem>
          </varlistentry>
        </variablelist>

        This method was added in version 2 of this interface.
    -->
    <method name="CreateMonitor">
      <arg type="s" name="window" direction="in"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
    </method>

    <!--
        StateChanged:
        @session_handle: Object path for the #org.freedesktop.portal.Session object
        @state: Vardict with information about the session state

        The StateChanged signal is sent to active monitoring sessions when
        the session state changes.

        When the session state changes to 'Query End', clients with active monitoring
        sessions are expected to respond by calling 
        org.freedesktop.portal.Inhibit.QueryEndResponse() within a second
        of receiving the StateChanged signal. They may call org.freedesktop.portal.Inhibit.Inhibit()
        first to inhibit logout, to prevent the session from proceeding to the Ending state.

        The following information may get returned in the @state vardict:
        <variablelist>
          <varlistentry>
            <term>screensaver-active b</term>
            <listitem><para>
              Whether the screensaver is active.
            </para></listitem>
          </varlistentry>
           <varlistentry>
            <term>session-state u</term>
            <listitem><para>
              The state of the session. This member is new in version 3.
            </para>
            <simplelist>
              <member>1: Running</member>
              <member>2: Query End</member>
              <member>3: Ending</member>
            </simplelist>
            </listitem>
          </varlistentry>
        </variablelist>
    -->
    <signal name="StateChanged">
      <arg type="o" name="session_handle" direction="out"/>
      <arg type="a{sv}" name="state" direction="out"/>
    </signal>

    <!--
      QueryEndResponse:
      @session_handle: Object path for the #org.freedesktop.portal.Session object

      Acknowledges that the caller received the #org.freedesktop.portal.Inhibit::StateChanged
      signal. This method should be called within one second or receiving a StateChanged
      signal with the 'Query End' state.

      Since version 3.
    -->
    <method name="QueryEndResponse">
      <arg type="o" name="session_handle" direction="in"/>
    </method>

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