Querying and manipulating devices

Device configuration is managed by "profiles" (see Device profiles). More...

Data Structures

struct  ratbag_device
 A ratbag context represents one single device. More...
 

Enumerations

enum  ratbag_device_capability {
  RATBAG_DEVICE_CAP_NONE, RATBAG_DEVICE_CAP_SWITCHABLE_RESOLUTION, RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE, RATBAG_DEVICE_CAP_BUTTON_KEY,
  RATBAG_DEVICE_CAP_LED, RATBAG_DEVICE_CAP_BUTTON_MACROS, RATBAG_DEVICE_CAP_DEFAULT_PROFILE, RATBAG_DEVICE_CAP_QUERY_CONFIGURATION,
  RATBAG_DEVICE_CAP_DISABLE_PROFILE
}
 

Functions

struct ratbag_deviceratbag_device_ref (struct ratbag_device *device)
 Add a reference to the device. More...
 
struct ratbag_deviceratbag_device_unref (struct ratbag_device *device)
 Dereference the ratbag device. More...
 
void ratbag_device_set_user_data (struct ratbag_device *device, void *userdata)
 Set caller-specific data associated with this device. More...
 
void * ratbag_device_get_user_data (const struct ratbag_device *device)
 Get the caller-specific data associated with this device, if any. More...
 
const char * ratbag_device_get_name (const struct ratbag_device *device)
 
const char * ratbag_device_get_svg_name (const struct ratbag_device *device)
 
int ratbag_device_has_capability (const struct ratbag_device *device, enum ratbag_device_capability cap)
 Note that a device may not support any of the capabilities but still initialize fine otherwise. More...
 
enum ratbag_error_code ratbag_device_commit (struct ratbag_device *device)
 Write any changes to the device. More...
 
unsigned int ratbag_device_get_num_profiles (struct ratbag_device *device)
 Return the number of profiles supported by this device. More...
 
unsigned int ratbag_device_get_num_buttons (struct ratbag_device *device)
 Return the number of buttons available on this device. More...
 
unsigned int ratbag_device_get_num_leds (struct ratbag_device *device)
 Return the number of LEDs available on this device. More...
 

Detailed Description

Device configuration is managed by "profiles" (see Device profiles).

In the simplest case, a device has a single profile that can be fetched, queried and manipulated and then re-applied to the device. Other devices may have multiple profiles, each of which can be queried and managed independently.

Enumeration Type Documentation

◆ ratbag_device_capability

Enumerator
RATBAG_DEVICE_CAP_NONE 
RATBAG_DEVICE_CAP_SWITCHABLE_RESOLUTION 

The device can change resolution, either software-controlled or by a hardware button.

FIXME: what about devices that only have hw buttons? can we query that, even if we can't switch it ourselves? Maybe better to have a separate cap for that then.

RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE 

The device can switch between hardware profiles.

A device with this capability can store multiple profiles in the hardware and provides the ability to switch between the profiles, possibly with a button. Devices without this capability will only have a single profile.

RATBAG_DEVICE_CAP_BUTTON_KEY 

The device supports assigning button numbers, key events or key + modifier combinations.

RATBAG_DEVICE_CAP_LED 

The device supports assigning LED colors and effects.

RATBAG_DEVICE_CAP_BUTTON_MACROS 

The device supports user-defined key or button sequences.

RATBAG_DEVICE_CAP_DEFAULT_PROFILE 

The device can have one profile assigned as a default profile.

A default profile is the profile that is selected when the device is plugged in. Devices without this capability may select the last-used profile or a specific profile (usually the first).

RATBAG_DEVICE_CAP_QUERY_CONFIGURATION 

The device has the capability to query the current hardware configuration.

If this capability is missing, libratbag cannot query the device for its current configuration and the configured resolutions and button mappings are unknown. libratbag will still provide information about the structure of the device such as the number of buttons and resolutions. Clients that encounter a device without this resolution are encouraged to upload a configuration stored on-disk to the device to reset the device to a known state.

Any changes uploaded to the device will be cached in libratbag, once a client has sent a full configuration to the device libratbag can be used to query the device as normal.

RATBAG_DEVICE_CAP_DISABLE_PROFILE 

The device has the capability to disable and enable profiles.

While profiles are not immediately deleted after being disabled, it is not guaranteed that the device will remember any disabled profiles the next time ratbag runs. Furthermore, the order of profiles may get changed the next time ratbag runs if profiles are disabled.

Function Documentation

◆ ratbag_device_commit()

enum ratbag_error_code ratbag_device_commit ( struct ratbag_device device)

Write any changes to the device.

Depending on the device, this may take a couple of seconds.

Parameters
deviceA previously initialized ratbag device
Returns
0 on success or an error code otherwise

◆ ratbag_device_get_name()

const char* ratbag_device_get_name ( const struct ratbag_device device)
Parameters
deviceA previously initialized ratbag device
Returns
The name of the device associated with the given ratbag.

◆ ratbag_device_get_num_buttons()

unsigned int ratbag_device_get_num_buttons ( struct ratbag_device device)

Return the number of buttons available on this device.

Parameters
deviceA previously initialized ratbag device
Returns
The number of buttons available on this device.

◆ ratbag_device_get_num_leds()

unsigned int ratbag_device_get_num_leds ( struct ratbag_device device)

Return the number of LEDs available on this device.

Parameters
deviceA previously initialized ratbag device
Returns
The number of LEDs available on this device.

◆ ratbag_device_get_num_profiles()

unsigned int ratbag_device_get_num_profiles ( struct ratbag_device device)

Return the number of profiles supported by this device.

Note that the number of profiles available may be different to the number of profiles currently active. This function returns the maximum number of profiles available and is static for the lifetime of the device.

A device that does not support profiles in hardware provides a single profile that reflects the current settings of the device.

Parameters
deviceA previously initialized ratbag device
Returns
The number of profiles available on this device.

◆ ratbag_device_get_svg_name()

const char* ratbag_device_get_svg_name ( const struct ratbag_device device)
Parameters
deviceA previously initialized ratbag device
Returns
The file name of the svg drawing associated with the given ratbag. If there is no file associated to the device, NULL is returned.

◆ ratbag_device_get_user_data()

void* ratbag_device_get_user_data ( const struct ratbag_device device)

Get the caller-specific data associated with this device, if any.

Parameters
deviceA previously initialized ratbag device
Returns
The caller-specific data previously assigned in ratbag_device_set_user_data().

◆ ratbag_device_has_capability()

int ratbag_device_has_capability ( const struct ratbag_device device,
enum ratbag_device_capability  cap 
)

Note that a device may not support any of the capabilities but still initialize fine otherwise.

This is the case for devices that have no configurable options set, or for devices that have some configuration options but none that are currently exposed by libratbag. A client is expected to handle this situation.

Return values
1The device has the capability
0The device does not have the capability

◆ ratbag_device_ref()

struct ratbag_device* ratbag_device_ref ( struct ratbag_device device)

Add a reference to the device.

A device is destroyed whenever the reference count reaches 0. See ratbag_device_unref.

Parameters
deviceA previously initialized valid ratbag device
Returns
The passed ratbag device

◆ ratbag_device_set_user_data()

void ratbag_device_set_user_data ( struct ratbag_device device,
void *  userdata 
)

Set caller-specific data associated with this device.

libratbag does not manage, look at, or modify this data. The caller must ensure the data is valid.

Parameters
deviceA previously initialized device
userdataCaller-specific data passed to the various callback interfaces.

◆ ratbag_device_unref()

struct ratbag_device* ratbag_device_unref ( struct ratbag_device device)

Dereference the ratbag device.

When the internal refcount reaches zero, all resources associated with this object are released. The object must be considered invalid once unref is called.

Parameters
deviceA previously initialized ratbag device
Returns
Always NULL