DrathOrg/libratbag-plus
1
0
Fork 0
forked from drath/libratbag
Code Pull Requests Activity
Files
13736d0ced2d6d873c1cac5ac840e58dfce83f64
libratbag-plus/DBusInterface.md
Peter Hutterer 13736d0ced DBus: thighten the definition of the 'Id' for a device 
We can't guarantee it's a sysname even though that is what we use for evdev
devices. Future devices may just be some custom-assigned name for a remote
dbus API

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
2017-10-11 09:13:44 +02:00

8.7 KiB
Raw Blame History

The ratbagd DBus-Interface

Note: the DBus interface is subject to change

Interfaces:

  • org.freedesktop.ratbag1.Manager
  • org.freedesktop.ratbag1.Device
  • org.freedesktop.ratbag1.Profile
  • org.freedesktop.ratbag1.Resolution
  • org.freedesktop.ratbag1.Button
  • org.freedesktop.ratbag1.Led

For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html

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.

All setters (whether implicit for read-write properties or explicit) return success instead of the internal return value because DBus does not like non-standard error values. Upon a ratbag error, the Resync signal is emitted on the device, indicating that clients should resync their values.

org.freedesktop.ratbag1.Manager

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

Properties:

Devices

  • type ao, read-only, mutable

Provides the object paths of all current devices, see org.freedesktop.ratbag1.Device

Themes

  • type as, read-only, constant

Provides the list of available theme names. This list is guaranteed to have one theme available ('default'). Other themes are implementation defined. A theme listed here is only a guarantee that the theme is known to libratbag and that SVGs may exist, it is not a guarantee that the SVG for any specific device exists. In other words, a device may not have an SVG for a specific theme.

This list is static for the lifetime of ratbagd.

org.freedesktop.ratbag1.Device

The org.freedesktop.ratbag1.Device interface describes a single device known to ratbagd.

Properties:

Id

  • type: s, read-only, constant

An ID describing this device. This ID should not be used for presentation to the user. This ID is unique for the device for the lifetime of the device but may be recycled when the device is removed. No guarantee is given for the content of the ID, the client should treat it as an opaque string.

Description

  • type: s, read-only, constant

The device's name, suitable for presentation to the user.

Capabilities

  • type: au, read-only, constant

The capabilities supported by this device. see enum ratbag_device_capability in libratbag.h for the list of permissible capabilities.

Svg

  • type: s, read-only, constant

The device's SVG file name, without path.

Profiles

  • type: ao, read-only, mutable

This property is mutable if the device supports adding and removing profiles.

Provides the list of profile paths for all profiles on this device, see org.freedesktop.ratbag1.Profile.

Methods:

Commit() → ()

Commits the changes to the device. Changes to the device are batched; they are not written to the hardware until Commit() is invoked.

GetSvg(s) → (s)

Returns the full path to the SVG for the given theme or an empty string if none is available. The theme must be one of org.freedesktop.ratbag1.Manager.Themes. The theme 'default' is guaranteed to be available. ratbagd may return the path to a file that doesn't exist. This is the case if the device has SVGs available but not for the given theme.

Signals:

Resync()

Emitted when an internal error occurs. Upon receiving this signal, clients are expected to resync their values with ratbagd.

org.freedesktop.ratbag1.Profile

Properties:

Index

  • type: u, read-only, constant

The index of this profile

Name

  • type: s, read-write, mutable

The name of this profile.

Enabled

  • type: b, read-write, mutable

True if this is the profile is enabled, false otherwise.

Note that a disabled profile might not have correct bindings, so it's a good thing to rebind everything before calling Commit() on the org.freedesktop.ratbag1.Device.

Resolutions

  • type: ao, read-only, mutable

This property is mutable if the device supports adding and removing resolutions.

Provides the object paths of all resolutions in this profile, see org.freedesktop.ratbag1.Resolution

Buttons

  • type: ao, read-only, constant

Provides the object paths of all buttons in this profile, see org.freedesktop.ratbag1.Button

Leds

  • type: ao, read-only, constant

Provides the object paths of all LEDs in this profile, see org.freedesktop.ratbag1.Led

IsActive

  • type: b, read-only, mutable

True if this is the currently active profile, false otherwise.

Profiles can only be set to active, but never to not active - at least one profile must be active at all times. This property is read-only, use the SetActive() method to activate a profile.

Methods:

SetActive() → ()

Set this profile to be the active profile

org.freedesktop.ratbag1.Resolution

Properties:

Index

  • type: u, read-only, constant

Index of the resolution

Capabilities

  • type: au, read-only, constant

Array of uints with the capabilities enum from libratbag

IsActive

  • type: b, read-only, mutable

True if this is the currently active resolution, false otherwise.

Resolutions can only be set to active, but never to not active - at least one resoultion must be active at all times. This property is read-only, use the SetActive() method to set a resolution as the active resolution.

IsDefault

  • type: b, read-only, mutable

True if this is the currently default resolution, false otherwise. If the device does not have the default resolution capability, this property is always false.

Resolutions can only be set to default, but never to not default - at least one resolution must be default at all times. This property is read-only, use the SetDefault() method to set a resolution as the default resolution.

Resolution

  • type: uu, read-write, mutable

uint for the x and y resolution assigned to this entry, respectively

ReportRate

  • type: u, read-write, mutable

uint for the report rate in Hz assigned to this entry

Maximum

  • type: u, read-only, constant

uint for the maximum possible resolution

Minimum

  • type: u, read-only, constant

uint for the minimum possible resolution

Methods:

SetDefault() → ()

Set this resolution to be the default

SetActive() → ()

Set this resolution to be the active one

org.freedesktop.ratbag1.Button

Properties:

Index

  • type: u, read-only, constant

Index of the button

Type

  • type: u, read-only, constant

Enum describing the button physical type. This type is unrelated to the logical button mapping and serves to easily identify the button on the device.

ButtonMapping

  • type: u, read-write, mutable

uint of the current button mapping (if mapping to button)

SpecialMapping

  • type: u, read-write, mutable

Enum describing the current special mapping (if mapped to special)

Macro

-type: a(uu), read-write, mutable

Array of (type, keycode), where type may be one of RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RELEASED.

ActionType

  • type: u, read-only, mutable

An enum describing the action type of the button, see ratbag_button_get_action_type for the list of enums. This decides which Mapping property has a value.

ActionTypes

  • type: au, read-only, constant Array of enum ratbag_button_action_type, possible values for ActionType on the current device

Methods:

Disable() → ()

Disable this button

org.freedesktop.ratbag1.Led

Properties:

Index

  • type: u, read-only, constant

Index of the LED

Mode

  • type: u, read-write, mutable

uint mapping to the mode enum from libratbag

Type

  • type: u, read-only, mutable

enum describing the LED type

Color

  • type: (uuu), read-write, mutable uint triplet (RGB) of the LED's color

ColorDepth

  • type: u, read-only, constant

The color depth of this LED as one of the constants in libratbag.h

EffectRate

  • type: u, read-write, mutable

The effect rate in Hz, possible values are in the range 100 - 20000

Brightness

  • type: u, read-write, mutable

The brightness of the LED, possible values are in the range 0 - 255

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.

View Git Blame Copy Permalink