<?xml version="1.0"?>
<!--
 Copyright (C) 2020 Endless OS Foundation LLC
               2023-2024 GNOME Foundation 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: Georges Basile Stavracas Neto <georges.stavracas@gmail.com>
         Ryan Gonzalez <rymg19+github@gmail.com>
-->

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

      This interface lets sandboxed applications monitor and request
      access to connected USB devices.

      Applications should prefer specialized portals for specific
      device types, such as the Camera portal for cameras.

      This documentation describes version 1 of this interface.
    -->
  <interface name="org.freedesktop.portal.Usb">

    <!--
        CreateSession:
        @options: Vardict with optional further information
        @session_handle: Object path for the session.

        Creates an USB monitoring session. This is only necessary to
        receive device events, like device being plugged or unplugged.

        Supported keys in the @options vardict include:

        * ``session_handle_token`` (``s``)

          A string that will be used as the last element of the session handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Session` documentation for
          more information about the session handle.
    -->
    <method name="CreateSession">
      <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="session_handle" direction="out"/>
    </method>

    <!--
        EnumerateDevices:
        @options: Vardict with optional further information. There is currently
        no option supported.

        Enumerates all connected USB devices that this application has permission
        to see.

        The following results are returned in the @device vardict:

        * ``id`` (``s``)

          Each element of the @devices array contains the device ID, and a
          device information vardict with the following keys:

        * ``parent`` (``s``)

          Device ID of the parent device.

        * ``readable`` (``b``)

          Whether the device can be opened for reading with
          org.freedesktop.portal.Usb.AcquireDevices(). If not present, then
          it should be assumed to be false.

        * ``writable`` (``b``)

          Whether the device can be opened for writing with
          org.freedesktop.portal.Usb.AcquireDevices(). If not present, then
          it should be assumed to be false.

        * ``device-file`` (``s``)

          A string path to the device node inside the /dev filesystem.

        * ``properties`` (``a{sv}``)

          A list of udev properties that this device has. These properties
          are not parsed in any way by the portal, it is up to apps to parse
          them.
     -->
    <method name="EnumerateDevices">
      <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QList&lt;QPair&lt;QString,QVariantMap&gt;&gt;"/>
      <arg type="a(sa{sv})" name="devices" direction="out"/>
    </method>

    <!--
        AcquireDevices:
        @parent_window: Identifier for the application window, see :doc:`window-identifiers`
        @devices: Array of device identifiers and access options
        @options: Vardict with optional further information
        @handle: Object path for the :ref:`org.freedesktop.portal.Request` object representing this call

        Request to acquires (i.e. open) the given device nodes.  The
        process of acquiring is finished by calling
        `FinishAcquireDevices` after the request emitted a `Success`
        response.

        Each element of the @devices array contains the device ID, and an
        access option vardict with the following keys:

        * ``writable`` (``b``)

          Whether the device will be opened in read-write or read-only mode.
          Default: False

        Supported keys in the @options vardict include:

        * ``handle_token`` (``s``)

          A string that will be used as the last element of the @handle. Must be a valid
          object path element. See the :ref:`org.freedesktop.portal.Request` documentation
          for more information about the @handle.

        The :ref:`org.freedesktop.portal.Request::Response` signal is emitted
        without any extra information.
     -->
    <method name="AcquireDevices">
      <arg type="s" name="parent_window" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QList&lt;QPair&lt;QString,QVariantMap&gt;&gt;"/>
      <arg type="a(sa{sv})" name="devices" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In2" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <arg type="o" name="handle" direction="out"/>
    </method>

    <!--
        FinishAcquireDevices:
        @handle: The request object path for the acquisition to finish
        @options: Vardict with optional further information
        @results: Array of device ids, and the result of the access
        @finished: Whether all device results were reported

        Retrieves the file descriptors of the devices requested during
        org.freedesktop.portal.Usb.AcquireDevices(). The file
        descriptors remain usable until the underlying device is
        removed, they are released with `ReleaseDevices`, the D-Bus
        connections is closed, or the portal revokes the file
        descriptor which can happen at any point. Devices which are
        not needed anymore should be passed to `ReleaseDevices`.

        If not all devices could be send, @finished will be false and
        org.freedesktop.portal.Usb.FinishAcquireDevices must be called again
        until @finished is true, before calling
        org.freedesktop.portal.Usb.AcquireDevices again.

        This method can only be called once for a given token, and only
        after calling org.freedesktop.portal.Usb.AcquireDevices().

        Each element of the @results array contains the device ID, and
        a vardict with the following keys:

        * ``success`` (``b``)

          Whether the device access was successful or not.

        * ``fd`` (``h``)

          The file descriptor representing the device. The file
          descriptor is meant to be passed on to the USB library.

          Only present if this was a successful device access.

        * ``error`` (``s``)

          Error message describing why accessing the device was not
          successful. Only present if this was an failed device access.

        There are no supported keys in the @options vardict.
     -->
    <method name="FinishAcquireDevices">
      <arg type="o" name="handle" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QList&lt;QPair&lt;QString,QVariantMap&gt;&gt;"/>
      <arg type="a(sa{sv})" name="results" direction="out"/>
      <arg type="b" name="finished" direction="out"/>
    </method>

    <!--
        ReleaseDevices:
        @devices: Array of device identifiers
        @options: Vardict with optional further information

        Releases previously acquired devices. The file descriptors of
        thoses devices might become unusable as a result of this.

        Each element of the @devices array contains the device ID of the device.

        There are no supported keys in the @options vardict.
     -->
    <method name="ReleaseDevices">
      <arg type="as" name="devices" direction="in"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QVariantMap"/>
      <arg type="a{sv}" name="options" direction="in"/>
    </method>

    <!--
        DeviceEvents:
        @session_handle: Object path for the :ref:`org.freedesktop.portal.Session` object
        @events: A list of events which occured.

        The DeviceEvents signal is emitted when one or more USB devices have
        been added, changed, or removed. This signal is only emitted for active
        sessions created with org.freedesktop.portal.Usb.CreateSession().

        Each element of the @events array is composed of the following fields:

        * ``action`` (``s``)

          Type of event that occurred. One of "add", "change", or "remove".

        * ``id`` (``s``)

          Device ID that the event occurred on.

        * ``device`` (``a{sv}``)

          Device properties attached to the ID. See
          org.freedesktop.portal.Usb.EnumerateDevices() for a list of all
          the properties that may be present in the vardict.
      -->
    <signal name="DeviceEvents">
      <arg type="o" name="session_handle" direction="out"/>
      <annotation name="org.qtproject.QtDBus.QtTypeName.Out1" value="QList&lt;std::tuple&lt;QString,QString,QVariantMap&gt;&gt;"/>
      <arg type="a(ssa{sv})" name="events" direction="out"/>
    </signal>

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