<?xml version="1.0"?>
<!--
 Copyright (C) 2019 Red Hat, Inc.

 SPDX-License-Identifier: LGPL-2.1-or-later

 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, see <http://www.gnu.org/licenses/>.
 Author: Christian J. Kellner <christian@kellner.me>
-->

<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
    <!--
      org.freedesktop.portal.GameMode:
      @short_description: Portal for accessing GameMode

      Interface for accessing GameMode from within the sandbox. It
      is analogous to the com.feralinteractive.GameMode interface
      and will proxy request there, but with additional permission
      checking and pid mapping. The latter is necessary in the case
      that sandbox has pid  namespace isolation enabled. See the man
      page for pid_namespaces(7) for more details, but briefly, it
      means that the sandbox has its own process id namespace which
      is separated from the one on the host. Thus there will be two
      separate process ids (PID) within two different namespaces
      that both identify same process. One id from the PID namespace
      inside the sandbox and one id from the host PID namespace.
      Since org.freedesktop.portal.GameMode expects pids from the host
      PID namespace but programs inside the sandbox can only know PID
      from the sandbox namespace, process ids need to be translated from
      the portal to the host namespace. The portal will do that transparently
      for all calls where this is necessary.

      Note: #org.freedesktop.portal.GameMode will monitor active clients,
      i.e. games and other programs that have successfully called
      org.freedesktop.portal.GameMode.RegisterGame().
      In the event that a client terminates without a call to the
      org.freedesktop.portal.GameMode.UnregisterGame() method, GameMode will
      automatically un-register the client. This might happen with a (small)
      delay.

      This documentation describes version 4 of this interface.
    -->
    <interface name="org.freedesktop.portal.GameMode">
      <!--
          QueryStatus:
          @pid: Process id to query the GameMode status of
          @result: The GameMode status for @pid

          Query the GameMode status for a process.

          If the caller is running inside a sandbox with PID namespace
          isolation, the @pid will be translated to the respective host PID.

          See the general introduction for details.

          The @result will be one of:

          - `0` if GameMode is inactive
          - `1` if GameMode is active
          - `2` if GameMode is active and @pid is registered
          - `-1` if the query failed inside GameMode
      -->
      <method name="QueryStatus">
        <arg type="i" name="pid" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>
      <!--
          RegisterGame:
          @pid: Process id of the game to register
          @result: Status of the request: 0 for success, -1 indicates an error

          Register a game with GameMode and thus request GameMode to
          be activated.

          If the caller is running inside a sandbox with PID namespace
          isolation, the @pid will be translated to the respective host PID.

          See the general introduction for details.

          If the GameMode has already been requested for @pid before,
          this call will fail, i.e. result will be -1.

          The @result will be one of:

          - `0` if the game with @pid was successfully registered
          - `-1` if the request was rejected by GameMode
      -->
      <method name="RegisterGame">
        <arg type="i" name="pid" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>
      <!--
          UnregisterGame:
          @pid: Process id of the game to un-register
          @result: Status of the request: 0 for success, -1 indicates an error

          Un-register a game from GameMode.

          If the call is successful and there are no other games or clients
          registered, GameMode will be deactivated.

          If the caller is running inside a sandbox with PID namespace
          isolation, the @pid will be translated to the respective host PID.

          The @result will be one of:
          
          - `0` if the game with @pid was successfully un-registered
          - `-1` if the request was rejected by GameMode
      -->
      <method name="UnregisterGame">
        <arg type="i" name="pid" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          QueryStatusByPid:
          @target: Process id to query the GameMode status of
          @requester: Process id of the process requesting the information
          @result: The GameMode status for @target

          Query the GameMode status for a process.

          Like org.freedesktop.portal.GameMode.QueryStatus() but @requester
          acting on behalf of @target.
      -->
      <method name="QueryStatusByPid">
        <arg type="i" name="target" direction="in"/>
        <arg type="i" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          RegisterGameByPid:
          @target: Process id of the game to register
          @requester: Process id of the process requesting the registration
          @result: Status of the request: 0 for success, -1 indicates an error

          Register a game with GameMode.

          Like org.freedesktop.portal.GameMode.RegisterGame() but @requester
          acting on behalf of @target.
      -->
      <method name="RegisterGameByPid">
        <arg type="i" name="target" direction="in"/>
        <arg type="i" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          UnregisterGameByPid:
          @target: Process id of the game to un-register
          @requester: Process id of the process requesting the un-registration
          @result: Status of the request: 0 for success, -1 indicates an error

          Un-register a game with GameMode.

          Like org.freedesktop.portal.GameMode.UnregisterGame() but @requester
          acting on behalf of @target.
      -->
      <method name="UnregisterGameByPid">
        <arg type="i" name="target" direction="in"/>
        <arg type="i" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!-- PidFd based APIs -->
      <!--
          QueryStatusByPIDFd:
          @target: Pidfd to query the GameMode status of
          @requester: Pidfd of the process requesting the information
          @result: The GameMode status for @target

          Query the GameMode status for a process.

          Like org.freedesktop.portal.GameMode.QueryStatusByPid() but @requester
          and @target are pidfds representing the processes.
      -->
      <method name="QueryStatusByPIDFd">
        <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
        <arg type="h" name="target" direction="in"/>
        <arg type="h" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          RegisterGameByPIDFd:
          @target: Pidfd of the game to register
          @requester: Pidfd of the process requesting the registration
          @result: Status of the request: 0 for success, -1 indicates an error

          Register a game with GameMode.

          Like org.freedesktop.portal.GameMode.RegisterGameByPid() but @requester
          and @target are pidfds representing the processes.
      -->
      <method name="RegisterGameByPIDFd">
        <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
        <arg type="h" name="target" direction="in"/>
        <arg type="h" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          UnregisterGameByPIDFd:
          @target: Pidfd of the game to un-register
          @requester: Pidfd of the process requesting the un-registration
          @result: Status of the request: 0 for success, -1 indicates an error

          Un-register a game with GameMode.

          Like org.freedesktop.portal.GameMode.UnregisterGameByPid() but @requester
          and @target are pidfds representing the processes.
      -->
      <method name="UnregisterGameByPIDFd">
        <annotation name="org.gtk.GDBus.C.UnixFD" value="true"/>
        <arg type="h" name="target" direction="in"/>
        <arg type="h" name="requester" direction="in"/>
        <arg type="i" name="result" direction="out"/>
      </method>

      <!--
          Active:

          Whether any pid on the system has enabled Game Mode.
      -->
      <property name="Active" type="b" access="read"/>

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