Initialization and manipulation of ratbag contexts

Data Structures

struct  ratbag
 A handle for accessing ratbag contexts. More...
 
struct  ratbag_interface
 libratbag does not open file descriptors to devices directly, instead open_restricted() and close_restricted() are called for each path that must be opened. More...
 

Typedefs

typedef void(* ratbag_log_handler) (struct ratbag *ratbag, enum ratbag_log_priority priority, const char *format, va_list args) LIBRATBAG_ATTRIBUTE_PRINTF(3
 Log handler type for custom logging. More...
 
typedef void(*) voi ratbag_log_set_priority) (struct ratbag *ratbag, enum ratbag_log_priority priority)
 Set the log priority for the ratbag context. More...
 

Enumerations

enum  ratbag_error_code {
  RATBAG_SUCCESS, RATBAG_ERROR_DEVICE, RATBAG_ERROR_CAPABILITY, RATBAG_ERROR_VALUE,
  RATBAG_ERROR_SYSTEM, RATBAG_ERROR_IMPLEMENTATION
}
 Error codes used by libratbag. More...
 
enum  ratbag_log_priority { RATBAG_LOG_PRIORITY_RAW, RATBAG_LOG_PRIORITY_DEBUG, RATBAG_LOG_PRIORITY_INFO, RATBAG_LOG_PRIORITY_ERROR }
 Log priority for internal logging messages. More...
 

Functions

enum ratbag_log_priority ratbag_log_get_priority (const struct ratbag *ratbag)
 Get the context's log priority. More...
 
void ratbag_log_set_handler (struct ratbag *ratbag, ratbag_log_handler log_handler)
 Set the context's log handler. More...
 
struct ratbagratbag_create_context (const struct ratbag_interface *interface, void *userdata)
 Create a new ratbag context. More...
 
void ratbag_set_user_data (struct ratbag *ratbag, void *userdata)
 Set caller-specific data associated with this context. More...
 
void * ratbag_get_user_data (const struct ratbag *ratbag)
 Get the caller-specific data associated with this context, if any. More...
 
struct ratbagratbag_ref (struct ratbag *ratbag)
 Add a reference to the context. More...
 
struct ratbagratbag_unref (struct ratbag *ratbag)
 Dereference the ratbag context. More...
 
enum ratbag_error_code ratbag_device_new_from_udev_device (struct ratbag *ratbag, struct udev_device *udev_device, struct ratbag_device **device)
 Create a new ratbag context from the given udev device. More...
 

Detailed Description

Typedef Documentation

typedef void(* ratbag_log_handler) (struct ratbag *ratbag, enum ratbag_log_priority priority, const char *format, va_list args) LIBRATBAG_ATTRIBUTE_PRINTF(3

Log handler type for custom logging.

Parameters
ratbagThe ratbag context
priorityThe priority of the current message
formatMessage format in printf-style
argsMessage arguments
See also
ratbag_log_set_priority
ratbag_log_get_priority
ratbag_log_set_handler
typedef void(*) voi ratbag_log_set_priority) (struct ratbag *ratbag, enum ratbag_log_priority priority)

Set the log priority for the ratbag context.

Messages with priorities equal to or higher than the argument will be printed to the context's log handler.

The default log priority is RATBAG_LOG_PRIORITY_ERROR.

Parameters
ratbagA previously initialized ratbag context
priorityThe minimum priority of log messages to print.
See also
ratbag_log_set_handler
ratbag_log_get_priority

Enumeration Type Documentation

Error codes used by libratbag.

Enumerator
RATBAG_SUCCESS 
RATBAG_ERROR_DEVICE 

An error occured on the device.

Either the device is not a libratbag device or communication with the device failed.

RATBAG_ERROR_CAPABILITY 

Insufficient capabilities.

This error occurs when a requestd change is beyond the device's capabilities.

RATBAG_ERROR_VALUE 

Invalid value or value range.

The provided value or value range is outside of the legal or supported range.

RATBAG_ERROR_SYSTEM 

A low-level system error has occured, e.g.

a failure to access files that should be there. This error is usually unrecoverable and libratbag will print a log message with details about the error.

RATBAG_ERROR_IMPLEMENTATION 

Implementation bug, either in libratbag or in the caller.

This error is usually unrecoverable and libratbag will print a log message with details about the error.

Log priority for internal logging messages.

Enumerator
RATBAG_LOG_PRIORITY_RAW 

Raw protocol messages.

Using this log level results in a lot of output.

RATBAG_LOG_PRIORITY_DEBUG 
RATBAG_LOG_PRIORITY_INFO 
RATBAG_LOG_PRIORITY_ERROR 

Function Documentation

struct ratbag* ratbag_create_context ( const struct ratbag_interface interface,
void *  userdata 
)

Create a new ratbag context.

The context is refcounted with an initial value of at least 1. Use ratbag_unref() to release the context.

Returns
An initialized ratbag context or NULL on error
enum ratbag_error_code ratbag_device_new_from_udev_device ( struct ratbag ratbag,
struct udev_device *  udev_device,
struct ratbag_device **  device 
)

Create a new ratbag context from the given udev device.

The device is refcounted with an initial value of at least 1. Use ratbag_device_unref() to release the device.

Parameters
ratbagA previously initialized ratbag context
udev_deviceThe udev device that points at the device
deviceSet to a new device based on the udev device.
Returns
0 on success or the error.
Return values
RATBAG_ERROR_DEVICEThe given device does not exist or is not supported by libratbag.
void* ratbag_get_user_data ( const struct ratbag ratbag)

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

Parameters
ratbagA previously initialized ratbag context
Returns
The caller-specific data previously assigned in ratbag_create_context (or ratbag_set_user_data()).
enum ratbag_log_priority ratbag_log_get_priority ( const struct ratbag ratbag)

Get the context's log priority.

Messages with priorities equal to or higher than the argument will be printed to the current log handler.

The default log priority is RATBAG_LOG_PRIORITY_ERROR.

Parameters
ratbagA previously initialized ratbag context
Returns
The minimum priority of log messages to print.
See also
ratbag_log_set_handler
ratbag_log_set_priority
void ratbag_log_set_handler ( struct ratbag ratbag,
ratbag_log_handler  log_handler 
)

Set the context's log handler.

Messages with priorities equal to or higher than the context's log priority will be passed to the given log handler.

The default log handler prints to stderr.

Parameters
ratbagA previously initialized ratbag context
log_handlerThe log handler for library messages.
See also
ratbag_log_set_priority
ratbag_log_get_priority
struct ratbag* ratbag_ref ( struct ratbag ratbag)

Add a reference to the context.

A context is destroyed whenever the reference count reaches 0. See ratbag_unref.

Parameters
ratbagA previously initialized valid ratbag context
Returns
The passed ratbag context
void ratbag_set_user_data ( struct ratbag ratbag,
void *  userdata 
)

Set caller-specific data associated with this context.

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

Setting userdata overrides the one provided to ratbag_create_context().

Parameters
ratbagA previously initialized ratbag context
userdataCaller-specific data passed to the various callback interfaces.
struct ratbag* ratbag_unref ( struct ratbag ratbag)

Dereference the ratbag context.

After this, the context may have been destroyed, if the last reference was dereferenced. If so, the context is invalid and may not be interacted with.

Parameters
ratbagA previously initialized ratbag context
Returns
Always NULL