<commit_before>********
DBus API
********

Note: **the DBus interface is subject to change**

Interfaces:

*  :ref:`manager`
*  :ref:`device`
*  :ref:`profile`
*  :ref:`resolution`
*  :ref:`button`
*  :ref:`led`

Changing settings on a device is a three-step process:

#. Change the various properties to the desired value
#. Invoke :func:`org.freedesktop.ratbag1.Device.Commit() <Commit>`
#. Optional: if an error occured writing the new data to the device,
   a :func:`org.freedesktop.ratbag1.Resync <Resync>` signal is emitted on the device and
   all properties are updated accordingly.

The time it takes to write settings to a device varies greatly, any caller
must be prepared to receive a :func:`org.freedesktop.ratbag1.Device.Resync
<Resync>` signal several seconds after
:func:`org.freedesktop.ratbag1.Device.Commit() <Commit>`.

Notes on the DBus API
---------------------

For easier debugging, objects paths are constructed from the device. e.g.
``/org/freedesktop/ratbag/button/event5/p0/b10`` is the button interface for
button 10 on profile 0 on event5. The naming is subject to change. Do not
rely on a constructed object path in your application.

Types
.....

Types used by these interfaces:

+----------+-----------------------------------+
| Type     | Description                       |
+==========+===================================+
| ``b``    | Bool                              |
+----------+-----------------------------------+
| ``o``    | Object path                       |
+----------+-----------------------------------+
| ``s``    | String                            |
+----------+-----------------------------------+
| ``u``    | Unsigned 32-bit integer           |
+----------+-----------------------------------+
|``(uuu)`` | A triplet of 32-bit integers      |
+----------+-----------------------------------+
| ``ao``   | Array of object paths             |
+----------+-----------------------------------+
| ``as``   | Array of strings                  |
+----------+-----------------------------------+
| ``au``   | Array of 32-bit integers          |
+----------+-----------------------------------+
| ``a(uu)``| Array of 2 32-bit integer tuples  |
+----------+-----------------------------------+

For details on each type, see the `DBus Specification
<https://dbus.freedesktop.org/doc/dbus-specification.html>`_.

Flags
.....

Properties marked as **constant** do not change for the lifetime of the
object. Properties marked as **mutable** may change, and a
``org.freedesktop.DBus.Properties.PropertyChanged`` signal is sent for those
unless otherwise specified.

.. _manager:

org.freedesktop.ratbag1.Manager
-------------------------------

The **org.freedesktop.ratbag1.Manager** interface is the entry point to
interact with ratbagd.

.. attribute:: APIVersion

        :type: i
        :flags: read-only,constant

	The DBus API version. This is a stopgap feature while the DBus API
	is still in flux. The version has no backwards or
	forward-compatibilty guarantees - your client must understand
	**exactly** the same version, it is not enough to support an older
	or a newer version.

	This API will be removed once the DBus API is declared stable.

.. attribute:: Devices

        :type: ao<commit_msg>doc: replace some tabs with spaces<commit_after>********
DBus API
********

Note: **the DBus interface is subject to change**

Interfaces:

*  :ref:`manager`
*  :ref:`device`
*  :ref:`profile`
*  :ref:`resolution`
*  :ref:`button`
*  :ref:`led`

Changing settings on a device is a three-step process:

#. Change the various properties to the desired value
#. Invoke :func:`org.freedesktop.ratbag1.Device.Commit() <Commit>`
#. Optional: if an error occured writing the new data to the device,
   a :func:`org.freedesktop.ratbag1.Resync <Resync>` signal is emitted on the device and
   all properties are updated accordingly.

The time it takes to write settings to a device varies greatly, any caller
must be prepared to receive a :func:`org.freedesktop.ratbag1.Device.Resync
<Resync>` signal several seconds after
:func:`org.freedesktop.ratbag1.Device.Commit() <Commit>`.

Notes on the DBus API
---------------------

For easier debugging, objects paths are constructed from the device. e.g.
``/org/freedesktop/ratbag/button/event5/p0/b10`` is the button interface for
button 10 on profile 0 on event5. The naming is subject to change. Do not
rely on a constructed object path in your application.

Types
.....

Types used by these interfaces:

+----------+-----------------------------------+
| Type     | Description                       |
+==========+===================================+
| ``b``    | Bool                              |
+----------+-----------------------------------+
| ``o``    | Object path                       |
+----------+-----------------------------------+
| ``s``    | String                            |
+----------+-----------------------------------+
| ``u``    | Unsigned 32-bit integer           |
+----------+-----------------------------------+
|``(uuu)`` | A triplet of 32-bit integers      |
+----------+-----------------------------------+
| ``ao``   | Array of object paths             |
+----------+-----------------------------------+
| ``as``   | Array of strings                  |
+----------+-----------------------------------+
| ``au``   | Array of 32-bit integers          |
+----------+-----------------------------------+
| ``a(uu)``| Array of 2 32-bit integer tuples  |
+----------+-----------------------------------+

For details on each type, see the `DBus Specification
<https://dbus.freedesktop.org/doc/dbus-specification.html>`_.

Flags
.....

Properties marked as **constant** do not change for the lifetime of the
object. Properties marked as **mutable** may change, and a
``org.freedesktop.DBus.Properties.PropertyChanged`` signal is sent for those
unless otherwise specified.

.. _manager:

org.freedesktop.ratbag1.Manager
-------------------------------

The **org.freedesktop.ratbag1.Manager** interface is the entry point to
interact with ratbagd.

.. attribute:: APIVersion

        :type: i
        :flags: read-only,constant

        The DBus API version. This is a stopgap feature while the DBus API
        is still in flux. The version has no backwards or
        forward-compatibilty guarantees - your client must understand
        **exactly** the same version, it is not enough to support an older
        or a newer version.

        This API will be removed once the DBus API is declared stable.

.. attribute:: Devices

        :type: ao
{'fraction_non_alphanumeric': 0.26464769441485314, 'fraction_numerical': 0.007000456551514229, 'mean_word_length': 1.7112211221122111, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4685705', 'n_tokens_mistral': 1738, 'n_tokens_neox': 1622, 'n_words': 616}