libratbag.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2015 Red Hat, Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and associated documentation files (the "Software"),
6  * to deal in the Software without restriction, including without limitation
7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8  * and/or sell copies of the Software, and to permit persons to whom the
9  * Software is furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice (including the next
12  * paragraph) shall be included in all copies or substantial portions of the
13  * Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21  * DEALINGS IN THE SOFTWARE.
22  */
23 
24 #ifndef LIBRATBAG_H
25 #define LIBRATBAG_H
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 #include <stdlib.h>
32 #include <stdarg.h>
33 #include <libudev.h>
34 
35 #define LIBRATBAG_ATTRIBUTE_PRINTF(_format, _args) \
36  __attribute__ ((format (printf, _format, _args)))
37 #define LIBRATBAG_ATTRIBUTE_DEPRECATED __attribute__ ((deprecated))
38 
83 struct ratbag;
84 
93 
104 
115 
127 
137 struct ratbag_button_macro;
138 
146 
152 
158 
164 
172 
180 };
181 
196 };
197 
212 typedef void (*ratbag_log_handler)(struct ratbag *ratbag,
213  enum ratbag_log_priority priority,
214  const char *format, va_list args)
216 
232 void
233 ratbag_log_set_priority(struct ratbag *ratbag,
234  enum ratbag_log_priority priority);
235 
251 ratbag_log_get_priority(const struct ratbag *ratbag);
252 
268 void
269 ratbag_log_set_handler(struct ratbag *ratbag,
270  ratbag_log_handler log_handler);
271 
272 
295  int (*open_restricted)(const char *path, int flags, void *user_data);
303  void (*close_restricted)(int fd, void *user_data);
304 };
305 
316 struct ratbag *
317 ratbag_create_context(const struct ratbag_interface *interface,
318  void *userdata);
319 
333 void
334 ratbag_set_user_data(struct ratbag *ratbag, void *userdata);
335 
345 void*
346 ratbag_get_user_data(const struct ratbag *ratbag);
347 
357 struct ratbag *
358 ratbag_ref(struct ratbag *ratbag);
359 
370 struct ratbag *
371 ratbag_unref(struct ratbag *ratbag);
372 
390 ratbag_device_new_from_udev_device(struct ratbag *ratbag,
391  struct udev_device *udev_device,
392  struct ratbag_device **device);
393 
403 struct ratbag_device *
404 ratbag_device_ref(struct ratbag_device *device);
405 
416 struct ratbag_device *
417 ratbag_device_unref(struct ratbag_device *device);
418 
430 void
431 ratbag_device_set_user_data(struct ratbag_device *device, void *userdata);
432 
442 void*
443 ratbag_device_get_user_data(const struct ratbag_device *device);
444 
451 const char *
452 ratbag_device_get_name(const struct ratbag_device* device);
453 
461 const char *
462 ratbag_device_get_svg_name(const struct ratbag_device* device);
463 
486 
492 
497 
505 
522 };
523 
536 int
537 ratbag_device_has_capability(const struct ratbag_device *device,
538  enum ratbag_device_capability cap);
539 
555 unsigned int
557 
566 unsigned int
568 
578 struct ratbag_profile *
579 ratbag_profile_ref(struct ratbag_profile *profile);
580 
591 struct ratbag_profile *
592 ratbag_profile_unref(struct ratbag_profile *profile);
593 
605 void
606 ratbag_profile_set_user_data(struct ratbag_profile *profile, void *userdata);
607 
617 void*
618 ratbag_profile_get_user_data(const struct ratbag_profile *profile);
619 
638 struct ratbag_profile *
639 ratbag_device_get_profile(struct ratbag_device *device, unsigned int index);
640 
652 int
654 
666 
682 unsigned int
684 
707 struct ratbag_resolution *
708 ratbag_profile_get_resolution(struct ratbag_profile *profile, unsigned int idx);
709 
719 struct ratbag_resolution *
720 ratbag_resolution_ref(struct ratbag_resolution *resolution);
721 
732 struct ratbag_resolution *
733 ratbag_resolution_unref(struct ratbag_resolution *resolution);
734 
746 void
747 ratbag_resolution_set_user_data(struct ratbag_resolution *resolution, void *userdata);
748 
758 void*
759 ratbag_resolution_get_user_data(const struct ratbag_resolution *resolution);
760 
768 
773 };
774 
782 int
785 
806  unsigned int dpi);
807 
832  unsigned int x, unsigned int y);
833 
848 int
849 ratbag_resolution_get_dpi(struct ratbag_resolution *resolution);
850 
865 int
867 
882 int
884 
902  unsigned int hz);
903 
920 int
922 
938 
952 int
953 ratbag_resolution_is_active(const struct ratbag_resolution *resolution);
954 
972 
987 int
988 ratbag_resolution_is_default(const struct ratbag_resolution *resolution);
989 
1008 struct ratbag_button*
1009 ratbag_profile_get_button(struct ratbag_profile *profile, unsigned int index);
1010 
1022 void
1023 ratbag_button_set_user_data(struct ratbag_button *button, void *userdata);
1024 
1034 void*
1035 ratbag_button_get_user_data(const struct ratbag_button *button);
1036 
1044 
1045  /* mouse buttons */
1066 
1067  /* DPI switch */
1071 
1072  /* Profile */
1076 };
1077 
1094 enum ratbag_button_type
1095 ratbag_button_get_type(struct ratbag_button *button);
1096 
1128 };
1129 
1137 
1155 int
1157  enum ratbag_button_action_type action_type);
1158 
1168 
1170 
1171  /* Wheel mappings */
1177 
1178  /* DPI switch */
1184 
1185  /* Profile */
1189 
1190  /* second mode for buttons */
1192 
1193  /* battery level */
1195 
1196 };
1197 
1217 unsigned int
1218 ratbag_button_get_button(struct ratbag_button *button);
1219 
1232 enum ratbag_error_code
1234  unsigned int btn);
1235 
1251 
1264 enum ratbag_error_code
1266  enum ratbag_button_action_special action);
1267 
1288 unsigned int
1289 ratbag_button_get_key(struct ratbag_button *button,
1290  unsigned int *modifiers,
1291  size_t *sz);
1292 
1308 enum ratbag_error_code
1309 ratbag_button_set_key(struct ratbag_button *button,
1310  unsigned int key,
1311  unsigned int *modifiers,
1312  size_t sz);
1313 
1322 enum ratbag_error_code
1323 ratbag_button_disable(struct ratbag_button *button);
1324 
1336 };
1337 
1345 const char *
1346 ratbag_button_macro_get_name(struct ratbag_button_macro *macro);
1347 
1355 unsigned int
1356 ratbag_button_macro_get_num_events(struct ratbag_button_macro *macro);
1357 
1373 ratbag_button_macro_get_event_type(struct ratbag_button_macro *macro,
1374  unsigned int index);
1375 
1392 int
1393 ratbag_button_macro_get_event_key(struct ratbag_button_macro*macro,
1394  unsigned int index);
1395 
1411 int
1412 ratbag_button_macro_get_event_timeout(struct ratbag_button_macro *macro,
1413  unsigned int index);
1414 
1431 enum ratbag_error_code
1432 ratbag_button_set_macro(struct ratbag_button *button,
1433  const struct ratbag_button_macro *macro);
1434 
1451 struct ratbag_button_macro *
1452 ratbag_button_macro_new(const char *name);
1453 
1467 struct ratbag_button_macro *
1468 ratbag_button_get_macro(struct ratbag_button *button);
1469 
1479 enum ratbag_error_code
1480 ratbag_button_macro_set_event(struct ratbag_button_macro *macro,
1481  unsigned int index,
1482  enum ratbag_macro_event_type type,
1483  unsigned int data);
1484 
1494 struct ratbag_button_macro *
1495 ratbag_button_macro_ref(struct ratbag_button_macro *macro);
1496 
1507 struct ratbag_button_macro *
1508 ratbag_button_macro_unref(struct ratbag_button_macro *macro);
1509 
1519 struct ratbag_button *
1520 ratbag_button_ref(struct ratbag_button *button);
1521 
1532 struct ratbag_button *
1533 ratbag_button_unref(struct ratbag_button *button);
1534 
1535 #ifdef __cplusplus
1536 }
1537 #endif
1538 #endif /* LIBRATBAG_H */
Definition: libratbag.h:1052
struct ratbag_device * ratbag_device_ref(struct ratbag_device *device)
Add a reference to the device.
ratbag_macro_event_type
Macro event types describing the event.
Definition: libratbag.h:1330
enum ratbag_error_code ratbag_resolution_set_report_rate(struct ratbag_resolution *resolution, unsigned int hz)
Set the the report rate in Hz for the resolution mode.
A button to toggle the wheel from free-spinning to click-based.
Definition: libratbag.h:1061
enum ratbag_button_action_type ratbag_button_get_action_type(struct ratbag_button *button)
Definition: libratbag.h:145
struct ratbag_profile * ratbag_profile_ref(struct ratbag_profile *profile)
Add a reference to the profile.
int ratbag_resolution_get_dpi(struct ratbag_resolution *resolution)
Get the resolution in DPI for the resolution mode.
Definition: libratbag.h:1047
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...
enum ratbag_error_code ratbag_button_set_special(struct ratbag_button *button, enum ratbag_button_action_special action)
This function sets the special function assigned to this button.
Definition: libratbag.h:1063
Definition: libratbag.h:1191
const char * ratbag_button_macro_get_name(struct ratbag_button_macro *macro)
ratbag_resolution_capability
Definition: libratbag.h:761
This button is not set up for a special action.
Definition: libratbag.h:1166
int ratbag_resolution_is_active(const struct ratbag_resolution *resolution)
Check if the resolution mode is the currently active one.
Definition: libratbag.h:1335
int ratbag_button_macro_get_event_timeout(struct ratbag_button_macro *macro, unsigned int index)
If the event stored at the given index is RATBAG_MACRO_EVENT_WAIT, this function returns the timeout ...
int ratbag_resolution_get_dpi_x(struct ratbag_resolution *resolution)
Get the x resolution in DPI for the resolution mode.
unsigned int ratbag_button_macro_get_num_events(struct ratbag_button_macro *macro)
enum ratbag_button_type ratbag_button_get_type(struct ratbag_button *button)
Return the type of the physical button.
int ratbag_button_has_action_type(struct ratbag_button *button, enum ratbag_button_action_type action_type)
Check if a button supports a specific action type.
unsigned int ratbag_button_get_button(struct ratbag_button *button)
If a button&#39;s action is RATBAG_BUTTON_ACTION_TYPE_BUTTON, this function returns the logical button nu...
enum ratbag_error_code ratbag_button_disable(struct ratbag_button *button)
enum ratbag_log_priority ratbag_log_get_priority(const struct ratbag *ratbag)
Get the context&#39;s log priority.
Raw protocol messages.
Definition: libratbag.h:192
Definition: libratbag.h:1055
The device supports user-defined key or button sequences.
Definition: libratbag.h:496
The device can switch between hardware profiles.
Definition: libratbag.h:485
Definition: libratbag.h:1173
Definition: libratbag.h:1054
An error occured on the device.
Definition: libratbag.h:151
enum ratbag_error_code ratbag_button_macro_set_event(struct ratbag_button_macro *macro, unsigned int index, enum ratbag_macro_event_type type, unsigned int data)
Sets the macro&#39;s event at the given index to the given type with the key code or timeout given...
The resolution can be set for x and y separately.
Definition: libratbag.h:772
enum ratbag_macro_event_type ratbag_button_macro_get_event_type(struct ratbag_button_macro *macro, unsigned int index)
Returns the macro event type configured for the event at the given index.
int ratbag_resolution_get_report_rate(struct ratbag_resolution *resolution)
Get the the report rate in Hz for the resolution mode.
Definition: libratbag.h:1331
The device can change resolution, either software-controlled or by a hardware button.
Definition: libratbag.h:477
struct ratbag_resolution * ratbag_profile_get_resolution(struct ratbag_profile *profile, unsigned int idx)
Return the resolution in DPI and the report rate in Hz for the resolution mode identified by the give...
enum ratbag_error_code ratbag_profile_set_active(struct ratbag_profile *profile)
Make the given profile the currently active profile.
Button action is unknown.
Definition: libratbag.h:1106
Definition: libratbag.h:1174
enum ratbag_error_code ratbag_resolution_set_default(struct ratbag_resolution *resolution)
Set the default resolution mode for the associated profile.
int ratbag_profile_is_active(struct ratbag_profile *profile)
Check if the given profile is the currently active one.
void ratbag_profile_set_user_data(struct ratbag_profile *profile, void *userdata)
Set caller-specific data associated with this profile.
ratbag_device_capability
Definition: libratbag.h:467
Definition: libratbag.h:1051
const char * ratbag_device_get_svg_name(const struct ratbag_device *device)
void * ratbag_profile_get_user_data(const struct ratbag_profile *profile)
Get the caller-specific data associated with this profile, if any.
Represents a resolution setting on the device.
Definition: libratbag.h:114
enum ratbag_error_code ratbag_resolution_set_dpi_xy(struct ratbag_resolution *resolution, unsigned int x, unsigned int y)
Set the x and y resolution in DPI for the resolution mode.
Definition: libratbag.h:194
Definition: libratbag.h:1062
ratbag_button_action_special
Definition: libratbag.h:1162
struct ratbag_button * ratbag_button_unref(struct ratbag_button *button)
Dereference the ratbag button.
struct ratbag_profile * ratbag_device_get_profile(struct ratbag_device *device, unsigned int index)
This function creates if necessary and returns a profile for the given index.
struct ratbag_resolution * ratbag_resolution_ref(struct ratbag_resolution *resolution)
Add a reference to the resolution.
Definition: libratbag.h:1069
Definition: libratbag.h:1074
A low-level system error has occured, e.g.
Definition: libratbag.h:171
unsigned int ratbag_profile_get_num_resolutions(struct ratbag_profile *profile)
Get the number of ratbag_resolution available in this profile.
void ratbag_resolution_set_user_data(struct ratbag_resolution *resolution, void *userdata)
Set caller-specific data associated with this resolution.
Definition: libratbag.h:195
void ratbag_device_set_user_data(struct ratbag_device *device, void *userdata)
Set caller-specific data associated with this device.
unsigned int ratbag_button_get_key(struct ratbag_button *button, unsigned int *modifiers, size_t *sz)
If a button&#39;s action is RATBAG_BUTTON_ACTION_TYPE_KEY, this function returns the key or button config...
void * ratbag_device_get_user_data(const struct ratbag_device *device)
Get the caller-specific data associated with this device, if any.
enum ratbag_button_action_special ratbag_button_get_special(struct ratbag_button *button)
If a button&#39;s action is RATBAG_BUTTON_ACTION_TYPE_SPECIAL, this function returns the special function...
struct ratbag_button_macro * ratbag_button_macro_ref(struct ratbag_button_macro *macro)
Add a reference to the macro.
void(* close_restricted)(int fd, void *user_data)
Close the file descriptor.
Definition: libratbag.h:303
void ratbag_log_set_handler(struct ratbag *ratbag, ratbag_log_handler log_handler)
Set the context&#39;s log handler.
ratbag_log_priority
Log priority for internal logging messages.
Definition: libratbag.h:187
struct ratbag_button * ratbag_button_ref(struct ratbag_button *button)
Add a reference to the button.
The report rate can be set per resolution mode.
Definition: libratbag.h:767
Definition: libratbag.h:1053
enum ratbag_error_code ratbag_button_set_key(struct ratbag_button *button, unsigned int key, unsigned int *modifiers, size_t sz)
Definition: libratbag.h:1332
unsigned int ratbag_device_get_num_profiles(struct ratbag_device *device)
Return the number of profiles supported by this device.
Definition: libratbag.h:1175
struct ratbag * ratbag_create_context(const struct ratbag_interface *interface, void *userdata)
Create a new ratbag context.
Button sends a key or key + modifier combination.
Definition: libratbag.h:1123
void ratbag_set_user_data(struct ratbag *ratbag, void *userdata)
Set caller-specific data associated with this context.
struct ratbag_resolution * ratbag_resolution_unref(struct ratbag_resolution *resolution)
Dereference the ratbag resolution.
struct ratbag_button_macro * ratbag_button_macro_new(const char *name)
Initialize a new button macro.
Implementation bug, either in libratbag or in the caller.
Definition: libratbag.h:179
Button is disabled.
Definition: libratbag.h:1110
Definition: libratbag.h:1169
Definition: libratbag.h:1070
The device can have one profile assigned as a default profile.
Definition: libratbag.h:504
enum ratbag_error_code ratbag_resolution_set_dpi(struct ratbag_resolution *resolution, unsigned int dpi)
Set the resolution in DPI for the resolution mode.
void(*) voi ratbag_log_set_priority)(struct ratbag *ratbag, enum ratbag_log_priority priority)
Set the log priority for the ratbag context.
Definition: libratbag.h:233
A handle to a profile context on devices with the RATBAG_DEVICE_CAP_SWITCHABLE_PROFILE capability...
Definition: libratbag.h:92
int ratbag_resolution_has_capability(struct ratbag_resolution *resolution, enum ratbag_resolution_capability cap)
Check if a resolution has a specific capability.
Definition: libratbag.h:1049
Definition: libratbag.h:1048
libratbag does not open file descriptors to devices directly, instead open_restricted() and close_res...
Definition: libratbag.h:283
void ratbag_button_set_user_data(struct ratbag_button *button, void *userdata)
Set caller-specific data associated with this button.
The device has the capability to query the current hardware configuration.
Definition: libratbag.h:521
void * ratbag_resolution_get_user_data(const struct ratbag_resolution *resolution)
Get the caller-specific data associated with this resolution, if any.
Definition: libratbag.h:1050
Button triggers a mouse-specific special function.
Definition: libratbag.h:1119
Definition: libratbag.h:1068
struct ratbag_device * ratbag_device_unref(struct ratbag_device *device)
Dereference the ratbag device.
The device supports assigning button numbers, key events or key + modifier combinations.
Definition: libratbag.h:491
int ratbag_resolution_is_default(const struct ratbag_resolution *resolution)
Check if the resolution mode is the default one in this profile.
Definition: libratbag.h:468
Definition: libratbag.h:1172
enum ratbag_error_code ratbag_resolution_set_active(struct ratbag_resolution *resolution)
Activate the given resolution mode.
ratbag_button_action_type
The type assigned to a button.
Definition: libratbag.h:1102
Definition: libratbag.h:1056
int(* open_restricted)(const char *path, int flags, void *user_data)
Open the device at the given path with the flags provided and return the fd.
Definition: libratbag.h:295
int ratbag_button_macro_get_event_key(struct ratbag_button_macro *macro, unsigned int index)
If the event stored at the given index is RATBAG_MACRO_EVENT_KEY_PRESSED or RATBAG_MACRO_EVENT_KEY_RE...
Definition: libratbag.h:1057
void * ratbag_button_get_user_data(const struct ratbag_button *button)
Get the caller-specific data associated with this button, if any.
Definition: libratbag.h:1065
Definition: libratbag.h:1188
struct ratbag * ratbag_unref(struct ratbag *ratbag)
Dereference the ratbag context.
Definition: libratbag.h:1333
enum ratbag_error_code ratbag_button_set_button(struct ratbag_button *button, unsigned int btn)
See ratbag_button_get_button() for a description of the button number.
Definition: libratbag.h:1043
Definition: libratbag.h:1180
const char * ratbag_device_get_name(const struct ratbag_device *device)
struct ratbag_button * ratbag_profile_get_button(struct ratbag_profile *profile, unsigned int index)
Return a reference to the button given by the index.
#define LIBRATBAG_ATTRIBUTE_PRINTF(_format, _args)
Definition: libratbag.h:35
A ratbag context represents one single device.
Definition: libratbag.h:83
Definition: libratbag.h:1075
enum ratbag_error_code ratbag_button_set_macro(struct ratbag_button *button, const struct ratbag_button_macro *macro)
Sets the button&#39;s action to RATBAG_BUTTON_ACTION_TYPE_MACRO and assigns the given macro to this butto...
Definition: libratbag.h:1334
unsigned int ratbag_device_get_num_buttons(struct ratbag_device *device)
Return the number of buttons available on this device.
int ratbag_resolution_get_dpi_y(struct ratbag_resolution *resolution)
Get the y resolution in DPI for the resolution mode.
Definition: libratbag.h:1064
struct ratbag * ratbag_ref(struct ratbag *ratbag)
Add a reference to the context.
struct ratbag_button_macro * ratbag_button_macro_unref(struct ratbag_button_macro *macro)
Dereference the ratbag button macro.
struct ratbag_profile * ratbag_profile_unref(struct ratbag_profile *profile)
Dereference the ratbag profile.
Insufficient capabilities.
Definition: libratbag.h:157
Definition: libratbag.h:1046
A handle for accessing ratbag contexts.
ratbag_button_type
Button types describing the physical button.
Definition: libratbag.h:1042
Definition: libratbag.h:1073
Invalid value or value range.
Definition: libratbag.h:163
void * ratbag_get_user_data(const struct ratbag *ratbag)
Get the caller-specific data associated with this context, if any.
Definition: libratbag.h:1194
Button sends numeric button events.
Definition: libratbag.h:1114
Definition: libratbag.h:1187
ratbag_error_code
Error codes used by libratbag.
Definition: libratbag.h:144
Represents a button on the device.
Definition: libratbag.h:103
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.
Definition: libratbag.h:212
Button sends a user-defined key or button sequence.
Definition: libratbag.h:1127
struct ratbag_button_macro * ratbag_button_get_macro(struct ratbag_button *button)
If a button&#39;s action is RATBAG_BUTTON_ACTION_TYPE_MACRO, this function returns the current button mac...
Definition: libratbag.h:1167
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.
Definition: libratbag.h:193