.. _org.freedesktop.portal.Usb:

==========================
 Usb
==========================

-----------
Description
-----------

.. _org.freedesktop.portal.Usb 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.



.. _org.freedesktop.portal.Usb Properties:

----------
Properties
----------

.. _org.freedesktop.portal.Usb:version:

org.freedesktop.portal.Usb:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.Usb Methods:

-------
Methods
-------

.. _org.freedesktop.portal.Usb.CreateSession:

org.freedesktop.portal.Usb.CreateSession
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    CreateSession (
      IN options a{sv},
      OUT session_handle o
    )



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.



options
  Vardict with optional further information

session_handle
  Object path for the session.



.. _org.freedesktop.portal.Usb.EnumerateDevices:

org.freedesktop.portal.Usb.EnumerateDevices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    EnumerateDevices (
      IN options a{sv},
      OUT devices a(sa{sv})
    )




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.



options
  Vardict with optional further information. There is currently

devices
  



.. _org.freedesktop.portal.Usb.AcquireDevices:

org.freedesktop.portal.Usb.AcquireDevices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    AcquireDevices (
      IN parent_window s,
      IN devices a(sa{sv}),
      IN options a{sv},
      OUT handle o
    )



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.



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



.. _org.freedesktop.portal.Usb.FinishAcquireDevices:

org.freedesktop.portal.Usb.FinishAcquireDevices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    FinishAcquireDevices (
      IN handle o,
      IN options a{sv},
      OUT results a(sa{sv}),
      OUT finished b
    )



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.



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



.. _org.freedesktop.portal.Usb.ReleaseDevices:

org.freedesktop.portal.Usb.ReleaseDevices
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    ReleaseDevices (
      IN devices as,
      IN options a{sv}
    )



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.



devices
  Array of device identifiers

options
  Vardict with optional further information


.. _org.freedesktop.portal.Usb Signals:

-------
Signals
-------

.. _org.freedesktop.portal.Usb::DeviceEvents:

org.freedesktop.portal.Usb::DeviceEvents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    DeviceEvents (
      session_handle o,
      events a(ssa{sv})
    )



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.



session_handle
  Object path for the :ref:`org.freedesktop.portal.Session` object

events
  A list of events which occured.


