1 /* 2 * Copyright © 2013 Red Hat, Inc. 3 * 4 * Permission to use, copy, modify, distribute, and sell this software and its 5 * documentation for any purpose is hereby granted without fee, provided that 6 * the above copyright notice appear in all copies and that both that copyright 7 * notice and this permission notice appear in supporting documentation, and 8 * that the name of the copyright holders not be used in advertising or 9 * publicity pertaining to distribution of the software without specific, 10 * written prior permission. The copyright holders make no representations 11 * about the suitability of this software for any purpose. It is provided "as 12 * is" without express or implied warranty. 13 * 14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR 17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 20 * OF THIS SOFTWARE. 21 */ 22 23 #ifndef LIBEVDEV_H 24 #define LIBEVDEV_H 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #include <linux/input.h> 31 #include <stdarg.h> 32 33 #define LIBEVDEV_ATTRIBUTE_PRINTF(_format, _args) __attribute__ ((format (printf, _format, _args))) 34 35 /** 36 * @mainpage 37 * 38 * **libevdev** is a library for handling evdev kernel devices. It abstracts 39 * the \ref ioctls through type-safe interfaces and provides functions to change 40 * the appearance of the device. 41 * 42 * Development of libevdev is discussed on 43 * [input-tools@lists.freedesktop.org](http://lists.freedesktop.org/mailman/listinfo/input-tools) 44 * Please submit patches, questions or general comments there. 45 * 46 * Handling events and SYN_DROPPED 47 * =============================== 48 * 49 * libevdev provides an interface for handling events, including most notably 50 * SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the 51 * process does not read events fast enough and the kernel is forced to drop 52 * some events. This causes the device to get out of sync with the process' 53 * view of it. libevdev handles this by telling the caller that a SYN_DROPPED 54 * has been received and that the state of the device is different to what is 55 * to be expected. It then provides the delta between the previous state and 56 * the actual state of the device as a set of events. See 57 * libevdev_next_event() and @ref syn_dropped for more information on how 58 * SYN_DROPPED is handled. 59 * 60 * Signal safety 61 * ============= 62 * 63 * libevdev is signal-safe for the majority of its operations, i.e. many of 64 * its functions are safe to be called from within a signal handler. 65 * Check the API documentation to make sure, unless explicitly stated a call 66 * is <b>not</b> signal safe. 67 * 68 * Device handling 69 * =============== 70 * 71 * A libevdev context is valid for a given file descriptor and its 72 * duration. Closing the file descriptor will not destroy the libevdev device 73 * but libevdev will not be able to read further events. 74 * 75 * libevdev does not attempt duplicate detection. Initializing two libevdev 76 * devices for the same fd is valid and behaves the same as for two different 77 * devices. 78 * 79 * libevdev does not handle the file descriptors directly, it merely uses 80 * them. The caller is responsible for opening the file descriptors, setting 81 * them to O_NONBLOCK and handling permissions. A caller should drain any 82 * events pending on the file descriptor before passing it to libevdev. 83 * 84 * Where does libevdev sit? 85 * ======================== 86 * 87 * libevdev is essentially a `read(2)` on steroids for `/dev/input/eventX` 88 * devices. It sits below the process that handles input events, in between 89 * the kernel and that process. In the simplest case, e.g. an evtest-like tool 90 * the stack would look like this: 91 * 92 * kernel → libevdev → evtest 93 * 94 * For X.Org input modules, the stack would look like this: 95 * 96 * kernel → libevdev → xf86-input-evdev → X server → X client 97 * 98 * For Weston/Wayland, the stack would look like this: 99 * 100 * kernel → libevdev → Weston → Wayland client 101 * 102 * libevdev does **not** have knowledge of X clients or Wayland clients, it is 103 * too low in the stack. 104 * 105 * Example 106 * ======= 107 * Below is a simple example that shows how libevdev could be used. This example 108 * opens a device, checks for relative axes and a left mouse button and if it 109 * finds them monitors the device to print the event. 110 * 111 * @code 112 * struct libevdev *dev = NULL; 113 * int fd; 114 * int rc = 1; 115 * 116 * fd = open("/dev/input/event0", O_RDONLY|O_NONBLOCK); 117 * rc = libevdev_new_from_fd(fd, &dev); 118 * if (rc < 0) { 119 * fprintf(stderr, "Failed to init libevdev (%s)\n", strerror(-rc)); 120 * exit(1); 121 * } 122 * printf("Input device name: \"%s\"\n", libevdev_get_name(dev)); 123 * printf("Input device ID: bus %#x vendor %#x product %#x\n", 124 * libevdev_get_id_bustype(dev), 125 * libevdev_get_id_vendor(dev), 126 * libevdev_get_id_product(dev)); 127 * if (!libevdev_has_event_type(dev, EV_REL) || 128 * !libevdev_has_event_code(dev, EV_KEY, BTN_LEFT)) { 129 * printf("This device does not look like a mouse\n"); 130 * exit(1); 131 * } 132 * 133 * do { 134 * struct input_event ev; 135 * rc = libevdev_next_event(dev, LIBEVDEV_READ_FLAG_NORMAL, &ev); 136 * if (rc == 0) 137 * printf("Event: %s %s %d\n", 138 * libevdev_get_event_type_name(ev.type), 139 * libevdev_get_event_code_name(ev.type, ev.code), 140 * ev.value); 141 * } while (rc == 1 || rc == 0 || rc == -EAGAIN); 142 * @endcode 143 * 144 * A more complete example is available with the libevdev-events tool here: 145 * http://cgit.freedesktop.org/libevdev/tree/tools/libevdev-events.c 146 * 147 * Backwards compatibility with older kernel 148 * ========================================= 149 * libevdev attempts to build and run correctly on a number of kernel versions. 150 * If features required are not available, libevdev attempts to work around them 151 * in the most reasonable way. For more details see \ref backwardscompatibility. 152 * 153 * License information 154 * =================== 155 * libevdev is licensed under the 156 * [X11 license](http://cgit.freedesktop.org/libevdev/tree/COPYING). 157 * 158 * Reporting bugs 159 * ============== 160 * Please report bugs in the freedesktop.org bugzilla under the libevdev product: 161 * https://bugs.freedesktop.org/enter_bug.cgi?product=libevdev 162 */ 163 164 /** 165 * @page syn_dropped SYN_DROPPED handling 166 * 167 * This page describes how libevdev handles SYN_DROPPED events. 168 * 169 * Receiving SYN_DROPPED events 170 * ============================ 171 * 172 * The kernel sends evdev events separated by an event of type EV_SYN and 173 * code SYN_REPORT. Such an event marks the end of a frame of hardware 174 * events. The number of events between SYN_REPORT events is arbitrary and 175 * depends on the hardware. An example event sequence may look like this: 176 * @code 177 * EV_ABS ABS_X 9 178 * EV_ABS ABS_Y 8 179 * EV_SYN SYN_REPORT 0 180 * ------------------------ 181 * EV_ABS ABS_X 10 182 * EV_ABS ABS_Y 10 183 * EV_KEY BTN_TOUCH 1 184 * EV_SYN SYN_REPORT 0 185 * ------------------------ 186 * EV_ABS ABS_X 11 187 * EV_SYN SYN_REPORT 0 188 * @endcode 189 * 190 * Events are handed to the client buffer as they appear, the kernel adjusts 191 * the buffer size to handle at least one full event. In the normal case, 192 * the client reads the event and the kernel can place the next event in the 193 * buffer. If the client is not fast enough, the kernel places an event of 194 * type EV_SYN and code SYN_DROPPED into the buffer, effectively notifying 195 * the client that some events were lost. The above example event sequence 196 * may look like this (note the missing/repeated events): 197 * @code 198 * EV_ABS ABS_X 9 199 * EV_ABS ABS_Y 8 200 * EV_SYN SYN_REPORT 0 201 * ------------------------ 202 * EV_ABS ABS_X 10 203 * EV_ABS ABS_Y 10 204 * EV_SYN SYN_DROPPED 0 205 * EV_ABS ABS_Y 15 206 * EV_SYN SYN_REPORT 0 207 * ------------------------ 208 * EV_ABS ABS_X 11 209 * EV_KEY BTN_TOUCH 0 210 * EV_SYN SYN_REPORT 0 211 * @endcode 212 * 213 * A SYN_DROPPED event may be recieved at any time in the event sequence. 214 * When a SYN_DROPPED event is received, the client must: 215 * * discard all events since the last SYN_REPORT 216 * * discard all events until including the next SYN_REPORT 217 * These event are part of incomplete event frames. 218 * 219 * Synchronizing the state of the device 220 * ===================================== 221 * 222 * The handling of the device after a SYN_DROPPED depends on the available 223 * event codes. For all event codes of type EV_REL, no handling is 224 * necessary, there is no state attached. For all event codes of type 225 * EV_KEY, EV_SW, EV_LED and EV_SND, the matching @ref ioctls retrieve the 226 * current state. The caller must then compare the last-known state to the 227 * retrieved state and handle the deltas accordingly. 228 * libevdev simplifies this approach: if the state of the device has 229 * changed, libevdev generates an event for each code with the new value and 230 * passes it to the caller during libevdev_next_event() if 231 * @ref LIBEVDEV_READ_FLAG_SYNC is set. 232 * 233 * For events of type EV_ABS and an event code less than ABS_MT_SLOT, the 234 * handling of state changes is as described above. For events between 235 * ABS_MT_SLOT and ABS_MAX, the event handling differs. 236 * Slots are the vehicles to transport information for multiple simultaneous 237 * touchpoints on a device. Slots are re-used once a touchpoint has ended. 238 * The kernel sends an ABS_MT_SLOT event whenever the current slot 239 * changes; any event in the above axis range applies only to the currently 240 * active slot. 241 * Thus, an event sequence from a slot-capable device may look like this: 242 * @code 243 * EV_ABS ABS_MT_POSITION_Y 10 244 * EV_ABS ABS_MT_SLOT 1 245 * EV_ABS ABS_MT_POSITION_X 100 246 * EV_ABS ABS_MT_POSITION_Y 80 247 * EV_SYN SYN_REPORT 0 248 * @endcode 249 * Note the lack of ABS_MT_SLOT: the first ABS_MT_POSITION_Y applies to 250 * a slot opened previously, and is the only axis that changed for that 251 * slot. The touchpoint in slot 1 now has position 100/80. 252 * The kernel does not provide events if a value does not change, and does 253 * not send ABS_MT_SLOT events if the slot does not change, or none of the 254 * values within a slot changes. A client must thus keep the state for each 255 * slot. 256 * 257 * If a SYN_DROPPED is received, the client must sync all slots 258 * individually and update its internal state. libevdev simplifies this by 259 * generating multiple events: 260 * * for each slot on the device, libevdev generates an 261 * ABS_MT_SLOT event with the value set to the slot number 262 * * for each event code between ABS_MT_SLOT + 1 and ABS_MAX that changed 263 * state for this slot, libevdev generates an event for the new state 264 * * libevdev sends a final ABS_MT_SLOT event for the current slot as 265 * seen by the kernel 266 * * libevdev terminates this sequence with an EV_SYN SYN_REPORT event 267 * 268 * An example event sequence for such a sync may look like this: 269 * @code 270 * EV_ABS ABS_MT_SLOT 0 271 * EV_ABS ABS_MT_POSITION_Y 10 272 * EV_ABS ABS_MT_SLOT 1 273 * EV_ABS ABS_MT_POSITION_X 100 274 * EV_ABS ABS_MT_POSITION_Y 80 275 * EV_ABS ABS_MT_SLOT 2 276 * EV_ABS ABS_MT_POSITION_Y 8 277 * EV_ABS ABS_MT_PRESSURE 12 278 * EV_ABS ABS_MT_SLOT 1 279 * EV_SYN SYN_REPORT 0 280 * @endcode 281 * Note the terminating ABS_MT_SLOT event, this indicates that the kernel 282 * currently has slot 1 active. 283 * 284 * Synchronizing ABS_MT_TRACKING_ID 285 * ================================ 286 * 287 * The event code ABS_MT_TRACKING_ID is used to denote the start and end of 288 * a touch point within a slot. An ABS_MT_TRACKING_ID of zero or greater 289 * denotes the start of a touchpoint, an ABS_MT_TRACKING_ID of -1 denotes 290 * the end of a touchpoint within this slot. During SYN_DROPPED, a touch 291 * point may have ended and re-started within a slot - a client must check 292 * the ABS_MT_TRACKING_ID. libevdev simplifies this by emulating extra 293 * events if the ABS_MT_TRACKING_ID has changed: 294 * * if the ABS_MT_TRACKING_ID was valid and is -1, libevdev enqueues an 295 * ABS_MT_TRACKING_ID event with value -1. 296 * * if the ABS_MT_TRACKING_ID was -1 and is now a valid ID, libevdev 297 * enqueues an ABS_MT_TRACKING_ID event with the current value. 298 * * if the ABS_MT_TRACKING_ID was a valid ID and is now a different valid 299 * ID, libevev enqueues an ABS_MT_TRACKING_ID event with value -1 and 300 * another ABS_MT_TRACKING_ID event with the new value. 301 * 302 * An example event sequence for such a sync may look like this: 303 * @code 304 * EV_ABS ABS_MT_SLOT 0 305 * EV_ABS ABS_MT_TRACKING_ID -1 306 * EV_ABS ABS_MT_SLOT 2 307 * EV_ABS ABS_MT_TRACKING_ID -1 308 * EV_SYN SYN_REPORT 0 309 * ------------------------ 310 * EV_ABS ABS_MT_SLOT 1 311 * EV_ABS ABS_MT_POSITION_X 100 312 * EV_ABS ABS_MT_POSITION_Y 80 313 * EV_ABS ABS_MT_SLOT 2 314 * EV_ABS ABS_MT_TRACKING_ID 45 315 * EV_ABS ABS_MT_POSITION_Y 8 316 * EV_ABS ABS_MT_PRESSURE 12 317 * EV_ABS ABS_MT_SLOT 1 318 * EV_SYN SYN_REPORT 0 319 * @endcode 320 * Note how the touchpoint in slot 0 was terminated, the touchpoint in slot 321 * 2 was terminated and then started with a new ABS_MT_TRACKING_ID. The touchpoint 322 * in slot 1 maintained the same ABS_MT_TRACKING_ID and only updated the 323 * coordinates. Slot 1 is the currently active slot. 324 * 325 * In the case of a SYN_DROPPED event, a touch point may be invisible to a 326 * client if it started after SYN_DROPPED and finished before the client 327 * handles events again. The below example shows an example event sequence 328 * and what libevdev sees in the case of a SYN_DROPPED event: 329 * @code 330 * 331 * kernel | userspace 332 * | 333 * EV_ABS ABS_MT_SLOT 0 | EV_ABS ABS_MT_SLOT 0 334 * EV_ABS ABS_MT_TRACKING_ID -1 | EV_ABS ABS_MT_TRACKING_ID -1 335 * EV_SYN SYN_REPORT 0 | EV_SYN SYN_REPORT 0 336 * ------------------------ | ------------------------ 337 * EV_ABS ABS_MT_TRACKING_ID 30 | 338 * EV_ABS ABS_MT_POSITION_X 100 | 339 * EV_ABS ABS_MT_POSITION_Y 80 | 340 * EV_SYN SYN_REPORT 0 | SYN_DROPPED 341 * ------------------------ | 342 * EV_ABS ABS_MT_TRACKING_ID -1 | 343 * EV_SYN SYN_REPORT 0 | 344 * ------------------------ | ------------------------ 345 * EV_ABS ABS_MT_SLOT 1 | EV_ABS ABS_MT_SLOT 1 346 * EV_ABS ABS_MT_POSITION_X 90 | EV_ABS ABS_MT_POSITION_X 90 347 * EV_ABS ABS_MT_POSITION_Y 10 | EV_ABS ABS_MT_POSITION_Y 10 348 * EV_SYN SYN_REPORT 0 | EV_SYN SYN_REPORT 0 349 * @endcode 350 * If such an event sequence occurs, libevdev will send all updated axes 351 * during the sync process. Axis events may thus be generated for devices 352 * without a currently valid ABS_MT_TRACKING_ID. Specifically for the above 353 * example, the client would receive the following event sequence: 354 * @code 355 * EV_ABS ABS_MT_SLOT 0 ← LIBEVDEV_READ_FLAG_NORMAL 356 * EV_ABS ABS_MT_TRACKING_ID -1 357 * EV_SYN SYN_REPORT 0 358 * ------------------------ 359 * EV_SYN SYN_DROPPED 0 → LIBEVDEV_READ_STATUS_SYNC 360 * ------------------------ 361 * EV_ABS ABS_MT_POSITION_X 100 ← LIBEVDEV_READ_FLAG_SYNC 362 * EV_ABS ABS_MT_POSITION_Y 80 363 * EV_SYN SYN_REPORT 0 364 * ----------------------------- → -EGAIN 365 * EV_ABS ABS_MT_SLOT 1 ← LIBEVDEV_READ_FLAG_NORMAL 366 * EV_ABS ABS_MT_POSITION_X 90 367 * EV_ABS ABS_MT_POSITION_Y 10 368 * EV_SYN SYN_REPORT 0 369 * ------------------- 370 * @endcode 371 * The axis events do not reflect the position of a current touch point, a 372 * client must take care not to generate a new touch point based on those 373 * updates. 374 * 375 * Discarding events before synchronizing 376 * ===================================== 377 * 378 * The kernel implements the client buffer as a ring buffer. SYN_DROPPED 379 * events are handled when the buffer is full and a new event is received 380 * from a device. All existing events are discarded, a SYN_DROPPED is added 381 * to the buffer followed by the actual device event. Further events will be 382 * appended to the buffer until it is either read by the client, or filled 383 * again, at which point the sequence repeats. 384 * 385 * When the client reads the buffer, the buffer will thus always consist of 386 * exactly one SYN_DROPPED event followed by an unspecified number of real 387 * events. The data the ioctls return is the current state of the device, 388 * i.e. the state after all these events have been processed. For example, 389 * assume the buffer contains the following sequence: 390 * 391 * @code 392 * EV_SYN SYN_DROPPED 393 * EV_ABS ABS_X 1 394 * EV_SYN SYN_REPORT 0 395 * EV_ABS ABS_X 2 396 * EV_SYN SYN_REPORT 0 397 * EV_ABS ABS_X 3 398 * EV_SYN SYN_REPORT 0 399 * EV_ABS ABS_X 4 400 * EV_SYN SYN_REPORT 0 401 * EV_ABS ABS_X 5 402 * EV_SYN SYN_REPORT 0 403 * EV_ABS ABS_X 6 404 * EV_SYN SYN_REPORT 0 405 * @endcode 406 * An ioctl at any time in this sequence will return a value of 6 for ABS_X. 407 * 408 * libevdev discards all events after a SYN_DROPPED to ensure the events 409 * during @ref LIBEVDEV_READ_FLAG_SYNC represent the last known state of the 410 * device. This loses some granularity of the events especially as the time 411 * between the SYN_DROPPED and the sync process increases. It does however 412 * avoid spurious cursor movements. In the above example, the event sequence 413 * by libevdev is: 414 * @code 415 * EV_SYN SYN_DROPPED 416 * EV_ABS ABS_X 6 417 * EV_SYN SYN_REPORT 0 418 * @endcode 419 */ 420 421 /** 422 * @page backwardscompatibility Compatibility and Behavior across kernel versions 423 * 424 * This page describes libevdev's behavior when the build-time kernel and the 425 * run-time kernel differ in their feature set. 426 * 427 * With the exception of event names, libevdev defines features that may be 428 * missing on older kernels and building on such kernels will not disable 429 * features. Running libevdev on a kernel that is missing some feature will 430 * change libevdev's behavior. In most cases, the new behavior should be 431 * obvious, but it is spelled out below in detail. 432 * 433 * Minimum requirements 434 * ==================== 435 * libevdev requires a 2.6.36 kernel as minimum. Specifically, it requires 436 * kernel-support for ABS_MT_SLOT. 437 * 438 * Event and input property names 439 * ============================== 440 * Event names and input property names are defined at build-time by the 441 * linux/input.h shipped with libevdev. 442 * The list of event names is compiled at build-time, any events not defined 443 * at build time will not resolve. Specifically, 444 * libevdev_event_code_get_name() for an undefined type or code will 445 * always return NULL. Likewise, libevdev_property_get_name() will return NULL 446 * for properties undefined at build-time. 447 * 448 * Input properties 449 * ================ 450 * If the kernel does not support input properties, specifically the 451 * EVIOCGPROPS ioctl, libevdev does not expose input properties to the caller. 452 * Specifically, libevdev_has_property() will always return 0 unless the 453 * property has been manually set with libevdev_enable_property(). 454 * 455 * This also applies to the libevdev-uinput code. If uinput does not honor 456 * UI_SET_PROPBIT, libevdev will continue without setting the properties on 457 * the device. 458 * 459 * MT slot behavior 460 * ================= 461 * If the kernel does not support the EVIOCGMTSLOTS ioctl, libevdev 462 * assumes all values in all slots are 0 and continues without an error. 463 * 464 * SYN_DROPPED behavior 465 * ==================== 466 * A kernel without SYN_DROPPED won't send such an event. libevdev_next_event() 467 * will never require the switch to sync mode. 468 */ 469 470 /** 471 * @page ioctls evdev ioctls 472 * 473 * This page lists the status of the evdev-specific ioctls in libevdev. 474 * 475 * <dl> 476 * <dt>EVIOCGVERSION:</dt> 477 * <dd>supported, see libevdev_get_driver_version()</dd> 478 * <dt>EVIOCGID:</dt> 479 * <dd>supported, see libevdev_get_id_product(), libevdev_get_id_vendor(), 480 * libevdev_get_id_bustype(), libevdev_get_id_version()</dd> 481 * <dt>EVIOCGREP:</dt> 482 * <dd>supported, see libevdev_get_event_value())</dd> 483 * <dt>EVIOCSREP:</dt> 484 * <dd>supported, see libevdev_enable_event_code()</dd> 485 * <dt>EVIOCGKEYCODE:</dt> 486 * <dd>currently not supported</dd> 487 * <dt>EVIOCGKEYCODE:</dt> 488 * <dd>currently not supported</dd> 489 * <dt>EVIOCSKEYCODE:</dt> 490 * <dd>currently not supported</dd> 491 * <dt>EVIOCSKEYCODE:</dt> 492 * <dd>currently not supported</dd> 493 * <dt>EVIOCGNAME:</dt> 494 * <dd>supported, see libevdev_get_name()</dd> 495 * <dt>EVIOCGPHYS:</dt> 496 * <dd>supported, see libevdev_get_phys()</dd> 497 * <dt>EVIOCGUNIQ:</dt> 498 * <dd>supported, see libevdev_get_uniq()</dd> 499 * <dt>EVIOCGPROP:</dt> 500 * <dd>supported, see libevdev_has_property()</dd> 501 * <dt>EVIOCGMTSLOTS:</dt> 502 * <dd>supported, see libevdev_get_num_slots(), libevdev_get_slot_value()</dd> 503 * <dt>EVIOCGKEY:</dt> 504 * <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd> 505 * <dt>EVIOCGLED:</dt> 506 * <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd> 507 * <dt>EVIOCGSND:</dt> 508 * <dd>currently not supported</dd> 509 * <dt>EVIOCGSW:</dt> 510 * <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd> 511 * <dt>EVIOCGBIT:</dt> 512 * <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value()</dd> 513 * <dt>EVIOCGABS:</dt> 514 * <dd>supported, see libevdev_has_event_code(), libevdev_get_event_value(), 515 * libevdev_get_abs_info()</dd> 516 * <dt>EVIOCSABS:</dt> 517 * <dd>supported, see libevdev_kernel_set_abs_info()</dd> 518 * <dt>EVIOCSFF:</dt> 519 * <dd>currently not supported</dd> 520 * <dt>EVIOCRMFF:</dt> 521 * <dd>currently not supported</dd> 522 * <dt>EVIOCGEFFECTS:</dt> 523 * <dd>currently not supported</dd> 524 * <dt>EVIOCGRAB:</dt> 525 * <dd>supported, see libevdev_grab()</dd> 526 * <dt>EVIOCSCLOCKID:</dt> 527 * <dd>supported, see libevdev_set_clock_id()</dd> 528 * <dt>EVIOCREVOKE:</dt> 529 * <dd>currently not supported, see 530 * http://lists.freedesktop.org/archives/input-tools/2014-January/000688.html</dd> 531 * </dl> 532 * 533 */ 534 535 /** 536 * @page kernel_header Kernel header 537 * 538 * libevdev provides its own copy of the Linux kernel header file and 539 * compiles against the definitions define here. Event type and event code 540 * names, etc. are taken from the file below: 541 * @include linux/input.h 542 */ 543 544 /** 545 * @page static_linking Statically linking libevdev 546 * 547 * Statically linking libevdev.a is not recommended. Symbol visibility is 548 * difficult to control in a static library, so extra care must be taken to 549 * only use symbols that are explicitly exported. libevdev's API stability 550 * guarantee only applies to those symbols. 551 * 552 * If you do link libevdev statically, note that in addition to the exported 553 * symbols, libevdev reserves the <b>_libevdev_*</b> namespace. Do not use 554 * or create symbols with that prefix, they are subject to change at any 555 * time. 556 */ 557 558 /** 559 * @page testing libevdev-internal test suite 560 * 561 * libevdev's internal test suite uses the 562 * [Check unit testing framework](http://check.sourceforge.net/). Tests are 563 * divided into test suites and test cases. Most tests create a uinput device, 564 * so you'll need to run as root, and your kernel must have 565 * CONFIG_INPUT_UINPUT enabled. 566 * 567 * To run a specific suite only: 568 * 569 * export CK_RUN_SUITE="suite name" 570 * 571 * To run a specific test case only: 572 * 573 * export CK_RUN_TEST="test case name" 574 * 575 * To get a list of all suites or tests: 576 * 577 * git grep "suite_create" 578 * git grep "tcase_create" 579 * 580 * By default, Check forks, making debugging harder. The test suite tries to detect 581 * if it is running inside gdb and disable forking. If that doesn't work for 582 * some reason, run gdb as below to avoid forking. 583 * 584 * sudo CK_FORK=no CK_RUN_TEST="test case name" gdb ./test/test-libevdev 585 * 586 * A special target `make gcov-report.txt` exists that runs gcov and leaves a 587 * `libevdev.c.gcov` file. Check that for test coverage. 588 * 589 * `make check` is hooked up to run the test and gcov (again, needs root). 590 * 591 * The test suite creates a lot of devices, very quickly. Add the following 592 * xorg.conf.d snippet to avoid the devices being added as X devices (at the 593 * time of writing, mutter can't handle these devices and exits after getting 594 * a BadDevice error). 595 * 596 * $ cat /etc/X11/xorg.conf.d/99-ignore-libevdev-devices.conf 597 * Section "InputClass" 598 * Identifier "Ignore libevdev test devices" 599 * MatchProduct "libevdev test device" 600 * Option "Ignore" "on" 601 * EndSection 602 * 603 */ 604 605 /** 606 * @defgroup init Initialization and setup 607 * 608 * Initialization, initial setup and file descriptor handling. 609 * These functions are the main entry points for users of libevdev, usually a 610 * caller will use this series of calls: 611 * 612 * @code 613 * struct libevdev *dev; 614 * int err; 615 * 616 * dev = libevdev_new(); 617 * if (!dev) 618 * return ENOMEM; 619 * 620 * err = libevdev_set_fd(dev, fd); 621 * if (err < 0) { 622 * printf("Failed (errno %d): %s\n", -err, strerror(-err)); 623 * 624 * libevdev_free(dev); 625 * @endcode 626 * 627 * libevdev_set_fd() is the central call and initializes the internal structs 628 * for the device at the given fd. libevdev functions will fail if called 629 * before libevdev_set_fd() unless documented otherwise. 630 */ 631 632 /** 633 * @defgroup logging Library logging facilities 634 * 635 * libevdev provides two methods of logging library-internal messages. The 636 * old method is to provide a global log handler in 637 * libevdev_set_log_function(). The new method is to provide a per-context 638 * log handler in libevdev_set_device_log_function(). Developers are encouraged 639 * to use the per-context logging facilities over the global log handler as 640 * it provides access to the libevdev instance that caused a message, and is 641 * more flexible when libevdev is used from within a shared library. 642 * 643 * If a caller sets both the global log handler and a per-context log 644 * handler, each device with a per-context log handler will only invoke that 645 * log handler. 646 * 647 * @note To set a context-specific log handler, a context is needed. 648 * Thus developers are discouraged from using libevdev_new_from_fd() as 649 * important messages from the device initialization process may get lost. 650 * 651 * @note A context-specific handler cannot be used for libevdev's uinput 652 * devices. @ref uinput must use the global log handler. 653 */ 654 655 /** 656 * @defgroup bits Querying device capabilities 657 * 658 * Abstraction functions to handle device capabilities, specificially 659 * device properties such as the name of the device and the bits 660 * representing the events suppported by this device. 661 * 662 * The logical state returned may lag behind the physical state of the device. 663 * libevdev queries the device state on libevdev_set_fd() and then relies on 664 * the caller to parse events through libevdev_next_event(). If a caller does not 665 * use libevdev_next_event(), libevdev will not update the internal state of the 666 * device and thus returns outdated values. 667 */ 668 669 /** 670 * @defgroup mt Multi-touch related functions 671 * Functions for querying multi-touch-related capabilities. MT devices 672 * following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch 673 * points through so-called slots on the same axis. The slots are enumerated, 674 * a client reading from the device will first get an ABS_MT_SLOT event, then 675 * the values of axes changed in this slot. Multiple slots may be provided in 676 * before an EV_SYN event. 677 * 678 * As with @ref bits, the logical state of the device as seen by the library 679 * depends on the caller using libevdev_next_event(). 680 * 681 * The Linux kernel requires all axes on a device to have a semantic 682 * meaning, matching the axis names in linux/input.h. Some devices merely 683 * export a number of axes beyond the available axis list. For those 684 * devices, the multitouch information is invalid. Specfically, if a device 685 * provides the ABS_MT_SLOT axis AND also the (ABS_MT_SLOT - 1) axis, the 686 * device is not treated as multitouch device. No slot information is 687 * available and the ABS_MT axis range for these devices is treated as all 688 * other EV_ABS axes. 689 * 690 * Note that because of limitations in the kernel API, such fake multitouch 691 * devices can not be reliably synched after a SYN_DROPPED event. libevdev 692 * ignores all ABS_MT axis values during the sync process and instead 693 * relies on the device to send the current axis value with the first event 694 * after SYN_DROPPED. 695 */ 696 697 /** 698 * @defgroup kernel Modifying the appearance or capabilities of the device 699 * 700 * Modifying the set of events reported by this device. By default, the 701 * libevdev device mirrors the kernel device, enabling only those bits 702 * exported by the kernel. This set of functions enable or disable bits as 703 * seen from the caller. 704 * 705 * Enabling an event type or code does not affect event reporting - a 706 * software-enabled event will not be generated by the physical hardware. 707 * Disabling an event will prevent libevdev from routing such events to the 708 * caller. Enabling and disabling event types and codes is at the library 709 * level and thus only affects the caller. 710 * 711 * If an event type or code is enabled at kernel-level, future users of this 712 * device will see this event enabled. Currently there is no option of 713 * disabling an event type or code at kernel-level. 714 */ 715 716 /** 717 * @defgroup misc Miscellaneous helper functions 718 * 719 * Functions for printing or querying event ranges. The list of names is 720 * compiled into libevdev and is independent of the run-time kernel. 721 * Likewise, the max for each event type is compiled in and does not check 722 * the kernel at run-time. 723 */ 724 725 /** 726 * @defgroup events Event handling 727 * 728 * Functions to handle events and fetch the current state of the event. 729 * libevdev updates its internal state as the event is processed and forwarded 730 * to the caller. Thus, the libevdev state of the device should always be identical 731 * to the caller's state. It may however lag behind the actual state of the device. 732 */ 733 734 /** 735 * @ingroup init 736 * 737 * Opaque struct representing an evdev device. 738 */ 739 struct libevdev; 740 741 /** 742 * @ingroup events 743 */ 744 enum libevdev_read_flag { 745 LIBEVDEV_READ_FLAG_SYNC = 1, /**< Process data in sync mode */ 746 LIBEVDEV_READ_FLAG_NORMAL = 2, /**< Process data in normal mode */ 747 LIBEVDEV_READ_FLAG_FORCE_SYNC = 4, /**< Pretend the next event is a SYN_DROPPED and 748 require the caller to sync */ 749 LIBEVDEV_READ_FLAG_BLOCKING = 8 /**< The fd is not in O_NONBLOCK and a read may block */ 750 }; 751 752 /** 753 * @ingroup init 754 * 755 * Initialize a new libevdev device. This function only allocates the 756 * required memory and initializes the struct to sane default values. 757 * To actually hook up the device to a kernel device, use 758 * libevdev_set_fd(). 759 * 760 * Memory allocated through libevdev_new() must be released by the 761 * caller with libevdev_free(). 762 * 763 * @see libevdev_set_fd 764 * @see libevdev_free 765 */ 766 struct libevdev* libevdev_new(void); 767 768 /** 769 * @ingroup init 770 * 771 * Initialize a new libevdev device from the given fd. 772 * 773 * This is a shortcut for 774 * 775 * @code 776 * int err; 777 * struct libevdev *dev = libevdev_new(); 778 * err = libevdev_set_fd(dev, fd); 779 * @endcode 780 * 781 * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode. 782 * @param[out] dev The newly initialized evdev device. 783 * 784 * @return On success, 0 is returned and dev is set to the newly 785 * allocated struct. On failure, a negative errno is returned and the value 786 * of dev is undefined. 787 * 788 * @see libevdev_free 789 */ 790 int libevdev_new_from_fd(int fd, struct libevdev **dev); 791 792 /** 793 * @ingroup init 794 * 795 * Clean up and free the libevdev struct. After completion, the <code>struct 796 * libevdev</code> is invalid and must not be used. 797 * 798 * Note that calling libevdev_free() does not close the file descriptor 799 * currently asssociated with this instance. 800 * 801 * @param dev The evdev device 802 * 803 * @note This function may be called before libevdev_set_fd(). 804 */ 805 void libevdev_free(struct libevdev *dev); 806 807 /** 808 * @ingroup logging 809 */ 810 enum libevdev_log_priority { 811 LIBEVDEV_LOG_ERROR = 10, /**< critical errors and application bugs */ 812 LIBEVDEV_LOG_INFO = 20, /**< informational messages */ 813 LIBEVDEV_LOG_DEBUG = 30 /**< debug information */ 814 }; 815 816 /** 817 * @ingroup logging 818 * 819 * Logging function called by library-internal logging. 820 * This function is expected to treat its input like printf would. 821 * 822 * @param priority Log priority of this message 823 * @param data User-supplied data pointer (see libevdev_set_log_function()) 824 * @param file libevdev source code file generating this message 825 * @param line libevdev source code line generating this message 826 * @param func libevdev source code function generating this message 827 * @param format printf-style format string 828 * @param args List of arguments 829 * 830 * @see libevdev_set_log_function 831 */ 832 typedef void (*libevdev_log_func_t)(enum libevdev_log_priority priority, 833 void *data, 834 const char *file, int line, 835 const char *func, 836 const char *format, va_list args) 837 LIBEVDEV_ATTRIBUTE_PRINTF(6, 0); 838 839 /** 840 * @ingroup logging 841 * 842 * Set a printf-style logging handler for library-internal logging. The default 843 * logging function is to stdout. 844 * 845 * @note The global log handler is only called if no context-specific log 846 * handler has been set with libevdev_set_device_log_function(). 847 * 848 * @param logfunc The logging function for this device. If NULL, the current 849 * logging function is unset and no logging is performed. 850 * @param data User-specific data passed to the log handler. 851 * 852 * @note This function may be called before libevdev_set_fd(). 853 * 854 * @deprecated Use per-context logging instead, see 855 * libevdev_set_device_log_function(). 856 */ 857 void libevdev_set_log_function(libevdev_log_func_t logfunc, void *data); 858 859 /** 860 * @ingroup logging 861 * 862 * Define the minimum level to be printed to the log handler. 863 * Messages higher than this level are printed, others are discarded. This 864 * is a global setting and applies to any future logging messages. 865 * 866 * @param priority Minimum priority to be printed to the log. 867 * 868 * @deprecated Use per-context logging instead, see 869 * libevdev_set_device_log_function(). 870 */ 871 void libevdev_set_log_priority(enum libevdev_log_priority priority); 872 873 /** 874 * @ingroup logging 875 * 876 * Return the current log priority level. Messages higher than this level 877 * are printed, others are discarded. This is a global setting. 878 * 879 * @return the current log level 880 * 881 * @deprecated Use per-context logging instead, see 882 * libevdev_set_device_log_function(). 883 */ 884 enum libevdev_log_priority libevdev_get_log_priority(void); 885 886 /** 887 * @ingroup logging 888 * 889 * Logging function called by library-internal logging for a specific 890 * libevdev context. This function is expected to treat its input like 891 * printf would. 892 * 893 * @param dev The evdev device 894 * @param priority Log priority of this message 895 * @param data User-supplied data pointer (see libevdev_set_log_function()) 896 * @param file libevdev source code file generating this message 897 * @param line libevdev source code line generating this message 898 * @param func libevdev source code function generating this message 899 * @param format printf-style format string 900 * @param args List of arguments 901 * 902 * @see libevdev_set_log_function 903 * @since 1.3 904 */ 905 typedef void (*libevdev_device_log_func_t)(const struct libevdev *dev, 906 enum libevdev_log_priority priority, 907 void *data, 908 const char *file, int line, 909 const char *func, 910 const char *format, va_list args) 911 LIBEVDEV_ATTRIBUTE_PRINTF(7, 0); 912 913 /** 914 * @ingroup logging 915 * 916 * Set a printf-style logging handler for library-internal logging for this 917 * device context. The default logging function is NULL, i.e. the global log 918 * handler is invoked. If a context-specific log handler is set, the global 919 * log handler is not invoked for this device. 920 * 921 * @note This log function applies for this device context only, even if 922 * another context exists for the same fd. 923 * 924 * @param dev The evdev device 925 * @param logfunc The logging function for this device. If NULL, the current 926 * logging function is unset and logging falls back to the global log 927 * handler, if any. 928 * @param priority Minimum priority to be printed to the log. 929 * @param data User-specific data passed to the log handler. 930 * 931 * @note This function may be called before libevdev_set_fd(). 932 * @since 1.3 933 */ 934 void libevdev_set_device_log_function(struct libevdev *dev, 935 libevdev_device_log_func_t logfunc, 936 enum libevdev_log_priority priority, 937 void *data); 938 939 /** 940 * @ingroup init 941 */ 942 enum libevdev_grab_mode { 943 LIBEVDEV_GRAB = 3, /**< Grab the device if not currently grabbed */ 944 LIBEVDEV_UNGRAB = 4 /**< Ungrab the device if currently grabbed */ 945 }; 946 947 /** 948 * @ingroup init 949 * 950 * Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other 951 * clients (including kernel-internal ones such as rfkill) from receiving 952 * events from this device. 953 * 954 * This is generally a bad idea. Don't do this. 955 * 956 * Grabbing an already grabbed device, or ungrabbing an ungrabbed device is 957 * a noop and always succeeds. 958 * 959 * @param dev The evdev device, already initialized with libevdev_set_fd() 960 * @param grab If true, grab the device. Otherwise ungrab the device. 961 * 962 * @return 0 if the device was successfull grabbed or ungrabbed, or a 963 * negative errno in case of failure. 964 */ 965 int libevdev_grab(struct libevdev *dev, enum libevdev_grab_mode grab); 966 967 /** 968 * @ingroup init 969 * 970 * Set the fd for this struct and initialize internal data. 971 * The fd must be in O_RDONLY or O_RDWR mode. 972 * 973 * This function may only be called once per device. If the device changed and 974 * you need to re-read a device, use libevdev_free() and libevdev_new(). If 975 * you need to change the fd after closing and re-opening the same device, use 976 * libevdev_change_fd(). 977 * 978 * A caller should ensure that any events currently pending on the fd are 979 * drained before the file descriptor is passed to libevdev for 980 * initialization. Due to how the kernel's ioctl handling works, the initial 981 * device state will reflect the current device state *after* applying all 982 * events currently pending on the fd. Thus, if the fd is not drained, the 983 * state visible to the caller will be inconsistent with the events 984 * immediately available on the device. This does not affect state-less 985 * events like EV_REL. 986 * 987 * Unless otherwise specified, libevdev function behavior is undefined until 988 * a successfull call to libevdev_set_fd(). 989 * 990 * @param dev The evdev device 991 * @param fd The file descriptor for the device 992 * 993 * @return 0 on success, or a negative errno on failure 994 * 995 * @see libevdev_change_fd 996 * @see libevdev_new 997 * @see libevdev_free 998 */ 999 int libevdev_set_fd(struct libevdev* dev, int fd); 1000 1001 /** 1002 * @ingroup init 1003 * 1004 * Change the fd for this device, without re-reading the actual device. If the fd 1005 * changes after initializing the device, for example after a VT-switch in the 1006 * X.org X server, this function updates the internal fd to the newly opened. 1007 * No check is made that new fd points to the same device. If the device has 1008 * changed, libevdev's behavior is undefined. 1009 * 1010 * libevdev does not sync itself after changing the fd and keeps the current 1011 * device state. Use libevdev_next_event with the 1012 * @ref LIBEVDEV_READ_FLAG_FORCE_SYNC flag to force a re-sync. 1013 * 1014 * The example code below illustrates how to force a re-sync of the 1015 * library-internal state. Note that this code doesn't handle the events in 1016 * the caller, it merely forces an update of the internal library state. 1017 * @code 1018 * struct input_event ev; 1019 * libevdev_change_fd(dev, new_fd); 1020 * libevdev_next_event(dev, LIBEVDEV_READ_FLAG_FORCE_SYNC, &ev); 1021 * while (libevdev_next_event(dev, LIBEVDEV_READ_FLAG_SYNC, &ev) == LIBEVDEV_READ_STATUS_SYNC) 1022 * ; // noop 1023 * @endcode 1024 * 1025 * The fd may be open in O_RDONLY or O_RDWR. 1026 * 1027 * It is an error to call this function before calling libevdev_set_fd(). 1028 * 1029 * @param dev The evdev device, already initialized with libevdev_set_fd() 1030 * @param fd The new fd 1031 * 1032 * @return 0 on success, or -1 on failure. 1033 * 1034 * @see libevdev_set_fd 1035 */ 1036 int libevdev_change_fd(struct libevdev* dev, int fd); 1037 1038 /** 1039 * @ingroup init 1040 * 1041 * @param dev The evdev device 1042 * 1043 * @return The previously set fd, or -1 if none had been set previously. 1044 * @note This function may be called before libevdev_set_fd(). 1045 */ 1046 int libevdev_get_fd(const struct libevdev* dev); 1047 1048 /** 1049 * @ingroup events 1050 */ 1051 enum libevdev_read_status { 1052 /** 1053 * libevdev_next_event() has finished without an error 1054 * and an event is available for processing. 1055 * 1056 * @see libevdev_next_event 1057 */ 1058 LIBEVDEV_READ_STATUS_SUCCESS = 0, 1059 /** 1060 * Depending on the libevdev_next_event() read flag: 1061 * * libevdev received a SYN_DROPPED from the device, and the caller should 1062 * now resync the device, or, 1063 * * an event has been read in sync mode. 1064 * 1065 * @see libevdev_next_event 1066 */ 1067 LIBEVDEV_READ_STATUS_SYNC = 1 1068 }; 1069 1070 /** 1071 * @ingroup events 1072 * 1073 * Get the next event from the device. This function operates in two different 1074 * modes: normal mode or sync mode. 1075 * 1076 * In normal mode (when flags has @ref LIBEVDEV_READ_FLAG_NORMAL set), this 1077 * function returns @ref LIBEVDEV_READ_STATUS_SUCCESS and returns the event 1078 * in the argument @p ev. If no events are available at this 1079 * time, it returns -EAGAIN and ev is undefined. 1080 * 1081 * If the current event is an EV_SYN SYN_DROPPED event, this function returns 1082 * @ref LIBEVDEV_READ_STATUS_SYNC and ev is set to the EV_SYN event. 1083 * The caller should now call this function with the 1084 * @ref LIBEVDEV_READ_FLAG_SYNC flag set, to get the set of events that make up the 1085 * device state delta. This function returns @ref LIBEVDEV_READ_STATUS_SYNC for 1086 * each event part of that delta, until it returns -EAGAIN once all events 1087 * have been synced. For more details on what libevdev does to sync after a 1088 * SYN_DROPPED event, see @ref syn_dropped. 1089 * 1090 * If a device needs to be synced by the caller but the caller does not call 1091 * with the @ref LIBEVDEV_READ_FLAG_SYNC flag set, all events from the diff are 1092 * dropped after libevdev updates its internal state and event processing 1093 * continues as normal. Note that the current slot and the state of touch 1094 * points may have updated during the SYN_DROPPED event, it is strongly 1095 * recommended that a caller ignoring all sync events calls 1096 * libevdev_get_current_slot() and checks the ABS_MT_TRACKING_ID values for 1097 * all slots. 1098 * 1099 * If a device has changed state without events being enqueued in libevdev, 1100 * e.g. after changing the file descriptor, use the @ref 1101 * LIBEVDEV_READ_FLAG_FORCE_SYNC flag. This triggers an internal sync of the 1102 * device and libevdev_next_event() returns @ref LIBEVDEV_READ_STATUS_SYNC. 1103 * Any state changes are available as events as described above. If 1104 * @ref LIBEVDEV_READ_FLAG_FORCE_SYNC is set, the value of ev is undefined. 1105 * 1106 * @param dev The evdev device, already initialized with libevdev_set_fd() 1107 * @param flags Set of flags to determine behaviour. If @ref LIBEVDEV_READ_FLAG_NORMAL 1108 * is set, the next event is read in normal mode. If @ref LIBEVDEV_READ_FLAG_SYNC is 1109 * set, the next event is read in sync mode. 1110 * @param ev On success, set to the current event. 1111 * @return On failure, a negative errno is returned. 1112 * @retval LIBEVDEV_READ_STATUS_SUCCESS One or more events were read of the 1113 * device and ev points to the next event in the queue 1114 * @retval -EAGAIN No events are currently available on the device 1115 * @retval LIBEVDEV_READ_STATUS_SYNC A SYN_DROPPED event was received, or a 1116 * synced event was returned and ev points to the SYN_DROPPED event 1117 * 1118 * @note This function is signal-safe. 1119 */ 1120 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev); 1121 1122 /** 1123 * @ingroup events 1124 * 1125 * Check if there are events waiting for us. This function does not read an 1126 * event off the fd and may not access the fd at all. If there are events 1127 * queued internally this function will return non-zero. If the internal 1128 * queue is empty, this function will poll the file descriptor for data. 1129 * 1130 * This is a convenience function for simple processes, most complex programs 1131 * are expected to use select(2) or poll(2) on the file descriptor. The kernel 1132 * guarantees that if data is available, it is a multiple of sizeof(struct 1133 * input_event), and thus calling libevdev_next_event() when select(2) or 1134 * poll(2) return is safe. You do not need libevdev_has_event_pending() if 1135 * you're using select(2) or poll(2). 1136 * 1137 * @param dev The evdev device, already initialized with libevdev_set_fd() 1138 * @return On failure, a negative errno is returned. 1139 * @retval 0 No event is currently available 1140 * @retval 1 One or more events are available on the fd 1141 * 1142 * @note This function is signal-safe. 1143 */ 1144 int libevdev_has_event_pending(struct libevdev *dev); 1145 1146 /** 1147 * @ingroup bits 1148 * 1149 * Retrieve the device's name, either as set by the caller or as read from 1150 * the kernel. The string returned is valid until libevdev_free() or until 1151 * libevdev_set_name(), whichever comes earlier. 1152 * 1153 * @param dev The evdev device, already initialized with libevdev_set_fd() 1154 * 1155 * @return The device name as read off the kernel device. The name is never 1156 * NULL but it may be the empty string. 1157 * 1158 * @note This function is signal-safe. 1159 */ 1160 const char* libevdev_get_name(const struct libevdev *dev); 1161 1162 /** 1163 * @ingroup kernel 1164 * 1165 * Change the device's name as returned by libevdev_get_name(). This 1166 * function destroys the string previously returned by libevdev_get_name(), 1167 * a caller must take care that no references are kept. 1168 * 1169 * @param dev The evdev device 1170 * @param name The new, non-NULL, name to assign to this device. 1171 * 1172 * @note This function may be called before libevdev_set_fd(). A call to 1173 * libevdev_set_fd() will overwrite any previously set value. 1174 */ 1175 void libevdev_set_name(struct libevdev *dev, const char *name); 1176 1177 /** 1178 * @ingroup bits 1179 * 1180 * Retrieve the device's physical location, either as set by the caller or 1181 * as read from the kernel. The string returned is valid until 1182 * libevdev_free() or until libevdev_set_phys(), whichever comes earlier. 1183 * 1184 * Virtual devices such as uinput devices have no phys location. 1185 * 1186 * @param dev The evdev device, already initialized with libevdev_set_fd() 1187 * 1188 * @return The physical location of this device, or NULL if there is none 1189 * 1190 * @note This function is signal safe. 1191 */ 1192 const char * libevdev_get_phys(const struct libevdev *dev); 1193 1194 /** 1195 * @ingroup kernel 1196 * 1197 * Change the device's physical location as returned by libevdev_get_phys(). 1198 * This function destroys the string previously returned by 1199 * libevdev_get_phys(), a caller must take care that no references are kept. 1200 * 1201 * @param dev The evdev device 1202 * @param phys The new phys to assign to this device. 1203 * 1204 * @note This function may be called before libevdev_set_fd(). A call to 1205 * libevdev_set_fd() will overwrite any previously set value. 1206 */ 1207 void libevdev_set_phys(struct libevdev *dev, const char *phys); 1208 1209 /** 1210 * @ingroup bits 1211 * 1212 * Retrieve the device's unique identifier, either as set by the caller or 1213 * as read from the kernel. The string returned is valid until 1214 * libevdev_free() or until libevdev_set_uniq(), whichever comes earlier. 1215 * 1216 * @param dev The evdev device, already initialized with libevdev_set_fd() 1217 * 1218 * @return The unique identifier for this device, or NULL if there is none 1219 * 1220 * @note This function is signal safe. 1221 */ 1222 const char * libevdev_get_uniq(const struct libevdev *dev); 1223 1224 /** 1225 * @ingroup kernel 1226 * 1227 * Change the device's unique identifier as returned by libevdev_get_uniq(). 1228 * This function destroys the string previously returned by 1229 * libevdev_get_uniq(), a caller must take care that no references are kept. 1230 * 1231 * @param dev The evdev device 1232 * @param uniq The new uniq to assign to this device. 1233 * 1234 * @note This function may be called before libevdev_set_fd(). A call to 1235 * libevdev_set_fd() will overwrite any previously set value. 1236 */ 1237 void libevdev_set_uniq(struct libevdev *dev, const char *uniq); 1238 1239 /** 1240 * @ingroup bits 1241 * 1242 * @param dev The evdev device, already initialized with libevdev_set_fd() 1243 * 1244 * @return The device's product ID 1245 * 1246 * @note This function is signal-safe. 1247 */ 1248 int libevdev_get_id_product(const struct libevdev *dev); 1249 1250 /** 1251 * @ingroup kernel 1252 * 1253 * @param dev The evdev device 1254 * @param product_id The product ID to assign to this device 1255 * 1256 * @note This function may be called before libevdev_set_fd(). A call to 1257 * libevdev_set_fd() will overwrite any previously set value. 1258 */ 1259 void libevdev_set_id_product(struct libevdev *dev, int product_id); 1260 1261 /** 1262 * @ingroup bits 1263 * 1264 * @param dev The evdev device, already initialized with libevdev_set_fd() 1265 * 1266 * @return The device's vendor ID 1267 * 1268 * @note This function is signal-safe. 1269 */ 1270 int libevdev_get_id_vendor(const struct libevdev *dev); 1271 1272 /** 1273 * @ingroup kernel 1274 * 1275 * @param dev The evdev device 1276 * @param vendor_id The vendor ID to assign to this device 1277 * 1278 * @note This function may be called before libevdev_set_fd(). A call to 1279 * libevdev_set_fd() will overwrite any previously set value. 1280 */ 1281 void libevdev_set_id_vendor(struct libevdev *dev, int vendor_id); 1282 1283 /** 1284 * @ingroup bits 1285 * 1286 * @param dev The evdev device, already initialized with libevdev_set_fd() 1287 * 1288 * @return The device's bus type 1289 * 1290 * @note This function is signal-safe. 1291 */ 1292 int libevdev_get_id_bustype(const struct libevdev *dev); 1293 1294 /** 1295 * @ingroup kernel 1296 * 1297 * @param dev The evdev device 1298 * @param bustype The bustype to assign to this device 1299 * 1300 * @note This function may be called before libevdev_set_fd(). A call to 1301 * libevdev_set_fd() will overwrite any previously set value. 1302 */ 1303 void libevdev_set_id_bustype(struct libevdev *dev, int bustype); 1304 1305 /** 1306 * @ingroup bits 1307 * 1308 * @param dev The evdev device, already initialized with libevdev_set_fd() 1309 * 1310 * @return The device's firmware version 1311 * 1312 * @note This function is signal-safe. 1313 */ 1314 int libevdev_get_id_version(const struct libevdev *dev); 1315 1316 /** 1317 * @ingroup kernel 1318 * 1319 * @param dev The evdev device 1320 * @param version The version to assign to this device 1321 * 1322 * @note This function may be called before libevdev_set_fd(). A call to 1323 * libevdev_set_fd() will overwrite any previously set value. 1324 */ 1325 void libevdev_set_id_version(struct libevdev *dev, int version); 1326 1327 /** 1328 * @ingroup bits 1329 * 1330 * @param dev The evdev device, already initialized with libevdev_set_fd() 1331 * 1332 * @return The driver version for this device 1333 * 1334 * @note This function is signal-safe. 1335 */ 1336 int libevdev_get_driver_version(const struct libevdev *dev); 1337 1338 /** 1339 * @ingroup bits 1340 * 1341 * @param dev The evdev device, already initialized with libevdev_set_fd() 1342 * @param prop The input property to query for, one of INPUT_PROP_... 1343 * 1344 * @return 1 if the device provides this input property, or 0 otherwise. 1345 * 1346 * @note This function is signal-safe 1347 */ 1348 int libevdev_has_property(const struct libevdev *dev, unsigned int prop); 1349 1350 /** 1351 * @ingroup kernel 1352 * 1353 * @param dev The evdev device 1354 * @param prop The input property to enable, one of INPUT_PROP_... 1355 * 1356 * @return 0 on success or -1 on failure 1357 * 1358 * @note This function may be called before libevdev_set_fd(). A call to 1359 * libevdev_set_fd() will overwrite any previously set value. 1360 */ 1361 int libevdev_enable_property(struct libevdev *dev, unsigned int prop); 1362 1363 /** 1364 * @ingroup bits 1365 * 1366 * @param dev The evdev device, already initialized with libevdev_set_fd() 1367 * @param type The event type to query for, one of EV_SYN, EV_REL, etc. 1368 * 1369 * @return 1 if the device supports this event type, or 0 otherwise. 1370 * 1371 * @note This function is signal-safe. 1372 */ 1373 int libevdev_has_event_type(const struct libevdev *dev, unsigned int type); 1374 1375 /** 1376 * @ingroup bits 1377 * 1378 * @param dev The evdev device, already initialized with libevdev_set_fd() 1379 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.) 1380 * @param code The event code to query for, one of ABS_X, REL_X, etc. 1381 * 1382 * @return 1 if the device supports this event type and code, or 0 otherwise. 1383 * 1384 * @note This function is signal-safe. 1385 */ 1386 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code); 1387 1388 /** 1389 * @ingroup bits 1390 * 1391 * Get the minimum axis value for the given axis, as advertised by the kernel. 1392 * 1393 * @param dev The evdev device, already initialized with libevdev_set_fd() 1394 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1395 * 1396 * @return axis minimum for the given axis or 0 if the axis is invalid 1397 * 1398 * @note This function is signal-safe. 1399 */ 1400 int libevdev_get_abs_minimum(const struct libevdev *dev, unsigned int code); 1401 1402 /** 1403 * @ingroup bits 1404 * 1405 * Get the maximum axis value for the given axis, as advertised by the kernel. 1406 * 1407 * @param dev The evdev device, already initialized with libevdev_set_fd() 1408 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1409 * 1410 * @return axis maximum for the given axis or 0 if the axis is invalid 1411 * 1412 * @note This function is signal-safe. 1413 */ 1414 int libevdev_get_abs_maximum(const struct libevdev *dev, unsigned int code); 1415 1416 /** 1417 * @ingroup bits 1418 * 1419 * Get the axis fuzz for the given axis, as advertised by the kernel. 1420 * 1421 * @param dev The evdev device, already initialized with libevdev_set_fd() 1422 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1423 * 1424 * @return axis fuzz for the given axis or 0 if the axis is invalid 1425 * 1426 * @note This function is signal-safe. 1427 */ 1428 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code); 1429 1430 /** 1431 * @ingroup bits 1432 * 1433 * Get the axis flat for the given axis, as advertised by the kernel. 1434 * 1435 * @param dev The evdev device, already initialized with libevdev_set_fd() 1436 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1437 * 1438 * @return axis flat for the given axis or 0 if the axis is invalid 1439 * 1440 * @note This function is signal-safe. 1441 */ 1442 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code); 1443 1444 /** 1445 * @ingroup bits 1446 * 1447 * Get the axis resolution for the given axis, as advertised by the kernel. 1448 * 1449 * @param dev The evdev device, already initialized with libevdev_set_fd() 1450 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1451 * 1452 * @return axis resolution for the given axis or 0 if the axis is invalid 1453 * 1454 * @note This function is signal-safe. 1455 */ 1456 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code); 1457 1458 /** 1459 * @ingroup bits 1460 * 1461 * Get the axis info for the given axis, as advertised by the kernel. 1462 * 1463 * @param dev The evdev device, already initialized with libevdev_set_fd() 1464 * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc. 1465 * 1466 * @return The input_absinfo for the given code, or NULL if the device does 1467 * not support this event code. 1468 * 1469 * @note This function is signal-safe. 1470 */ 1471 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code); 1472 1473 /** 1474 * @ingroup bits 1475 * 1476 * Behaviour of this function is undefined if the device does not provide 1477 * the event. 1478 * 1479 * If the device supports ABS_MT_SLOT, the value returned for any ABS_MT_* 1480 * event code is the value of the currently active slot. You should use 1481 * libevdev_get_slot_value() instead. 1482 * 1483 * @param dev The evdev device, already initialized with libevdev_set_fd() 1484 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.) 1485 * @param code The event code to query for, one of ABS_X, REL_X, etc. 1486 * 1487 * @return The current value of the event. 1488 * 1489 * @note This function is signal-safe. 1490 * @note The value for ABS_MT_ events is undefined, use 1491 * libevdev_get_slot_value() instead 1492 * 1493 * @see libevdev_get_slot_value 1494 */ 1495 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code); 1496 1497 /** 1498 * @ingroup kernel 1499 * 1500 * Set the value for a given event type and code. This only makes sense for 1501 * some event types, e.g. setting the value for EV_REL is pointless. 1502 * 1503 * This is a local modification only affecting only this representation of 1504 * this device. A future call to libevdev_get_event_value() will return this 1505 * value, unless the value was overwritten by an event. 1506 * 1507 * If the device supports ABS_MT_SLOT, the value set for any ABS_MT_* 1508 * event code is the value of the currently active slot. You should use 1509 * libevdev_set_slot_value() instead. 1510 * 1511 * If the device supports ABS_MT_SLOT and the type is EV_ABS and the code is 1512 * ABS_MT_SLOT, the value must be a positive number less then the number of 1513 * slots on the device. Otherwise, libevdev_set_event_value() returns -1. 1514 * 1515 * @param dev The evdev device, already initialized with libevdev_set_fd() 1516 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.) 1517 * @param code The event code to set the value for, one of ABS_X, LED_NUML, etc. 1518 * @param value The new value to set 1519 * 1520 * @return 0 on success, or -1 on failure. 1521 * @retval -1 the device does not have the event type or code enabled, or the code is outside the 1522 * allowed limits for the given type, or the type cannot be set, or the 1523 * value is not permitted for the given code. 1524 * 1525 * @see libevdev_set_slot_value 1526 * @see libevdev_get_event_value 1527 */ 1528 int libevdev_set_event_value(struct libevdev *dev, unsigned int type, unsigned int code, int value); 1529 1530 /** 1531 * @ingroup bits 1532 * 1533 * Fetch the current value of the event type. This is a shortcut for 1534 * 1535 * @code 1536 * if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c)) 1537 * val = libevdev_get_event_value(dev, t, c); 1538 * @endcode 1539 * 1540 * @param dev The evdev device, already initialized with libevdev_set_fd() 1541 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.) 1542 * @param code The event code to query for, one of ABS_X, REL_X, etc. 1543 * @param[out] value The current value of this axis returned. 1544 * 1545 * @return If the device supports this event type and code, the return value is 1546 * non-zero and value is set to the current value of this axis. Otherwise, 1547 * 0 is returned and value is unmodified. 1548 * 1549 * @note This function is signal-safe. 1550 * @note The value for ABS_MT_ events is undefined, use 1551 * libevdev_fetch_slot_value() instead 1552 * 1553 * @see libevdev_fetch_slot_value 1554 */ 1555 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value); 1556 1557 /** 1558 * @ingroup mt 1559 * 1560 * Return the current value of the code for the given slot. 1561 * 1562 * The return value is undefined for a slot exceeding the available slots on 1563 * the device, for a code that is not in the permitted ABS_MT range or for a 1564 * device that does not have slots. 1565 * 1566 * @param dev The evdev device, already initialized with libevdev_set_fd() 1567 * @param slot The numerical slot number, must be smaller than the total number 1568 * of slots on this device 1569 * @param code The event code to query for, one of ABS_MT_POSITION_X, etc. 1570 * 1571 * @note This function is signal-safe. 1572 * @note The value for events other than ABS_MT_ is undefined, use 1573 * libevdev_fetch_value() instead 1574 * 1575 * @see libevdev_get_event_value 1576 */ 1577 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code); 1578 1579 /** 1580 * @ingroup kernel 1581 * 1582 * Set the value for a given code for the given slot. 1583 * 1584 * This is a local modification only affecting only this representation of 1585 * this device. A future call to libevdev_get_slot_value() will return this 1586 * value, unless the value was overwritten by an event. 1587 * 1588 * This function does not set event values for axes outside the ABS_MT range, 1589 * use libevdev_set_event_value() instead. 1590 * 1591 * @param dev The evdev device, already initialized with libevdev_set_fd() 1592 * @param slot The numerical slot number, must be smaller than the total number 1593 * of slots on this device 1594 * @param code The event code to set the value for, one of ABS_MT_POSITION_X, etc. 1595 * @param value The new value to set 1596 * 1597 * @return 0 on success, or -1 on failure. 1598 * @retval -1 the device does not have the event code enabled, or the code is 1599 * outside the allowed limits for multitouch events, or the slot number is outside 1600 * the limits for this device, or the device does not support multitouch events. 1601 * 1602 * @see libevdev_set_event_value 1603 * @see libevdev_get_slot_value 1604 */ 1605 int libevdev_set_slot_value(struct libevdev *dev, unsigned int slot, unsigned int code, int value); 1606 1607 /** 1608 * @ingroup mt 1609 * 1610 * Fetch the current value of the code for the given slot. This is a shortcut for 1611 * 1612 * @code 1613 * if (libevdev_has_event_type(dev, EV_ABS) && 1614 * libevdev_has_event_code(dev, EV_ABS, c) && 1615 * slot < device->number_of_slots) 1616 * val = libevdev_get_slot_value(dev, slot, c); 1617 * @endcode 1618 * 1619 * @param dev The evdev device, already initialized with libevdev_set_fd() 1620 * @param slot The numerical slot number, must be smaller than the total number 1621 * of slots on this * device 1622 * @param[out] value The current value of this axis returned. 1623 * 1624 * @param code The event code to query for, one of ABS_MT_POSITION_X, etc. 1625 * @return If the device supports this event code, the return value is 1626 * non-zero and value is set to the current value of this axis. Otherwise, or 1627 * if the event code is not an ABS_MT_* event code, 0 is returned and value 1628 * is unmodified. 1629 * 1630 * @note This function is signal-safe. 1631 */ 1632 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value); 1633 1634 /** 1635 * @ingroup mt 1636 * 1637 * Get the number of slots supported by this device. 1638 * 1639 * @param dev The evdev device, already initialized with libevdev_set_fd() 1640 * 1641 * @return The number of slots supported, or -1 if the device does not provide 1642 * any slots 1643 * 1644 * @note A device may provide ABS_MT_SLOT but a total number of 0 slots. Hence 1645 * the return value of -1 for "device does not provide slots at all" 1646 */ 1647 int libevdev_get_num_slots(const struct libevdev *dev); 1648 1649 /** 1650 * @ingroup mt 1651 * 1652 * Get the currently active slot. This may differ from the value 1653 * an ioctl may return at this time as events may have been read off the fd 1654 * since changing the slot value but those events are still in the buffer 1655 * waiting to be processed. The returned value is the value a caller would 1656 * see if it were to process events manually one-by-one. 1657 * 1658 * @param dev The evdev device, already initialized with libevdev_set_fd() 1659 * 1660 * @return the currently active slot (logically) 1661 * 1662 * @note This function is signal-safe. 1663 */ 1664 int libevdev_get_current_slot(const struct libevdev *dev); 1665 1666 /** 1667 * @ingroup kernel 1668 * 1669 * Change the minimum for the given EV_ABS event code, if the code exists. 1670 * This function has no effect if libevdev_has_event_code() returns false for 1671 * this code. 1672 * 1673 * @param dev The evdev device, already initialized with libevdev_set_fd() 1674 * @param code One of ABS_X, ABS_Y, ... 1675 * @param min The new minimum for this axis 1676 */ 1677 void libevdev_set_abs_minimum(struct libevdev *dev, unsigned int code, int min); 1678 1679 /** 1680 * @ingroup kernel 1681 * 1682 * Change the maximum for the given EV_ABS event code, if the code exists. 1683 * This function has no effect if libevdev_has_event_code() returns false for 1684 * this code. 1685 * 1686 * @param dev The evdev device, already initialized with libevdev_set_fd() 1687 * @param code One of ABS_X, ABS_Y, ... 1688 * @param max The new maxium for this axis 1689 */ 1690 void libevdev_set_abs_maximum(struct libevdev *dev, unsigned int code, int max); 1691 1692 /** 1693 * @ingroup kernel 1694 * 1695 * Change the fuzz for the given EV_ABS event code, if the code exists. 1696 * This function has no effect if libevdev_has_event_code() returns false for 1697 * this code. 1698 * 1699 * @param dev The evdev device, already initialized with libevdev_set_fd() 1700 * @param code One of ABS_X, ABS_Y, ... 1701 * @param fuzz The new fuzz for this axis 1702 */ 1703 void libevdev_set_abs_fuzz(struct libevdev *dev, unsigned int code, int fuzz); 1704 1705 /** 1706 * @ingroup kernel 1707 * 1708 * Change the flat for the given EV_ABS event code, if the code exists. 1709 * This function has no effect if libevdev_has_event_code() returns false for 1710 * this code. 1711 * 1712 * @param dev The evdev device, already initialized with libevdev_set_fd() 1713 * @param code One of ABS_X, ABS_Y, ... 1714 * @param flat The new flat for this axis 1715 */ 1716 void libevdev_set_abs_flat(struct libevdev *dev, unsigned int code, int flat); 1717 1718 /** 1719 * @ingroup kernel 1720 * 1721 * Change the resolution for the given EV_ABS event code, if the code exists. 1722 * This function has no effect if libevdev_has_event_code() returns false for 1723 * this code. 1724 * 1725 * @param dev The evdev device, already initialized with libevdev_set_fd() 1726 * @param code One of ABS_X, ABS_Y, ... 1727 * @param resolution The new axis resolution 1728 */ 1729 void libevdev_set_abs_resolution(struct libevdev *dev, unsigned int code, int resolution); 1730 1731 /** 1732 * @ingroup kernel 1733 * 1734 * Change the abs info for the given EV_ABS event code, if the code exists. 1735 * This function has no effect if libevdev_has_event_code() returns false for 1736 * this code. 1737 * 1738 * @param dev The evdev device, already initialized with libevdev_set_fd() 1739 * @param code One of ABS_X, ABS_Y, ... 1740 * @param abs The new absolute axis data (min, max, fuzz, flat, resolution) 1741 */ 1742 void libevdev_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs); 1743 1744 /** 1745 * @ingroup kernel 1746 * 1747 * Forcibly enable an event type on this device, even if the underlying 1748 * device does not support it. While this cannot make the device actually 1749 * report such events, it will now return true for libevdev_has_event_type(). 1750 * 1751 * This is a local modification only affecting only this representation of 1752 * this device. 1753 * 1754 * @param dev The evdev device, already initialized with libevdev_set_fd() 1755 * @param type The event type to enable (EV_ABS, EV_KEY, ...) 1756 * 1757 * @return 0 on success or -1 otherwise 1758 * 1759 * @see libevdev_has_event_type 1760 */ 1761 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type); 1762 1763 /** 1764 * @ingroup kernel 1765 * 1766 * Forcibly disable an event type on this device, even if the underlying 1767 * device provides it. This effectively mutes the respective set of 1768 * events. libevdev will filter any events matching this type and none will 1769 * reach the caller. libevdev_has_event_type() will return false for this 1770 * type. 1771 * 1772 * In most cases, a caller likely only wants to disable a single code, not 1773 * the whole type. Use libevdev_disable_event_code() for that. 1774 * 1775 * Disabling EV_SYN will not work. Don't shoot yourself in the foot. 1776 * It hurts. 1777 * 1778 * This is a local modification only affecting only this representation of 1779 * this device. 1780 * 1781 * @param dev The evdev device, already initialized with libevdev_set_fd() 1782 * @param type The event type to disable (EV_ABS, EV_KEY, ...) 1783 * 1784 * @return 0 on success or -1 otherwise 1785 * 1786 * @see libevdev_has_event_type 1787 * @see libevdev_disable_event_type 1788 */ 1789 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type); 1790 1791 /** 1792 * @ingroup kernel 1793 * 1794 * Forcibly enable an event code on this device, even if the underlying 1795 * device does not support it. While this cannot make the device actually 1796 * report such events, it will now return true for libevdev_has_event_code(). 1797 * 1798 * The last argument depends on the type and code: 1799 * - If type is EV_ABS, data must be a pointer to a struct input_absinfo 1800 * containing the data for this axis. 1801 * - If type is EV_REP, data must be a pointer to a int containing the data 1802 * for this axis 1803 * - For all other types, the argument must be NULL. 1804 * 1805 * This function calls libevdev_enable_event_type() if necessary. 1806 * 1807 * This is a local modification only affecting only this representation of 1808 * this device. 1809 * 1810 * If this function is called with a type of EV_ABS and EV_REP on a device 1811 * that already has the given event code enabled, the values in data 1812 * overwrite the previous values. 1813 * 1814 * @param dev The evdev device, already initialized with libevdev_set_fd() 1815 * @param type The event type to enable (EV_ABS, EV_KEY, ...) 1816 * @param code The event code to enable (ABS_X, REL_X, etc.) 1817 * @param data If type is EV_ABS, data points to a struct input_absinfo. If type is EV_REP, data 1818 * points to an integer. Otherwise, data must be NULL. 1819 * 1820 * @return 0 on success or -1 otherwise 1821 * 1822 * @see libevdev_enable_event_type 1823 */ 1824 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data); 1825 1826 /** 1827 * @ingroup kernel 1828 * 1829 * Forcibly disable an event code on this device, even if the underlying 1830 * device provides it. This effectively mutes the respective set of 1831 * events. libevdev will filter any events matching this type and code and 1832 * none will reach the caller. libevdev_has_event_code() will return false for 1833 * this code. 1834 * 1835 * Disabling all event codes for a given type will not disable the event 1836 * type. Use libevdev_disable_event_type() for that. 1837 * 1838 * This is a local modification only affecting only this representation of 1839 * this device. 1840 * 1841 * Disabling codes of type EV_SYN will not work. Don't shoot yourself in the 1842 * foot. It hurts. 1843 * 1844 * @param dev The evdev device, already initialized with libevdev_set_fd() 1845 * @param type The event type to disable (EV_ABS, EV_KEY, ...) 1846 * @param code The event code to disable (ABS_X, REL_X, etc.) 1847 * 1848 * @return 0 on success or -1 otherwise 1849 * 1850 * @see libevdev_has_event_code 1851 * @see libevdev_disable_event_type 1852 */ 1853 int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code); 1854 1855 /** 1856 * @ingroup kernel 1857 * 1858 * Set the device's EV_ABS axis to the value defined in the abs 1859 * parameter. This will be written to the kernel. 1860 * 1861 * @param dev The evdev device, already initialized with libevdev_set_fd() 1862 * @param code The EV_ABS event code to modify, one of ABS_X, ABS_Y, etc. 1863 * @param abs Axis info to set the kernel axis to 1864 * 1865 * @return 0 on success, or a negative errno on failure 1866 * 1867 * @see libevdev_enable_event_code 1868 */ 1869 int libevdev_kernel_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs); 1870 1871 /** 1872 * @ingroup kernel 1873 */ 1874 enum libevdev_led_value { 1875 LIBEVDEV_LED_ON = 3, /**< Turn the LED on */ 1876 LIBEVDEV_LED_OFF = 4 /**< Turn the LED off */ 1877 }; 1878 1879 /** 1880 * @ingroup kernel 1881 * 1882 * Turn an LED on or off. Convenience function, if you need to modify multiple 1883 * LEDs simultaneously, use libevdev_kernel_set_led_values() instead. 1884 * 1885 * @note enabling an LED requires write permissions on the device's file descriptor. 1886 * 1887 * @param dev The evdev device, already initialized with libevdev_set_fd() 1888 * @param code The EV_LED event code to modify, one of LED_NUML, LED_CAPSL, ... 1889 * @param value Specifies whether to turn the LED on or off 1890 * @return 0 on success, or a negative errno on failure 1891 */ 1892 int libevdev_kernel_set_led_value(struct libevdev *dev, unsigned int code, enum libevdev_led_value value); 1893 1894 /** 1895 * @ingroup kernel 1896 * 1897 * Turn multiple LEDs on or off simultaneously. This function expects a pair 1898 * of LED codes and values to set them to, terminated by a -1. For example, to 1899 * switch the NumLock LED on but the CapsLock LED off, use: 1900 * 1901 * @code 1902 * libevdev_kernel_set_led_values(dev, LED_NUML, LIBEVDEV_LED_ON, 1903 * LED_CAPSL, LIBEVDEV_LED_OFF, 1904 * -1); 1905 * @endcode 1906 * 1907 * If any LED code or value is invalid, this function returns -EINVAL and no 1908 * LEDs are modified. 1909 * 1910 * @note enabling an LED requires write permissions on the device's file descriptor. 1911 * 1912 * @param dev The evdev device, already initialized with libevdev_set_fd() 1913 * @param ... A pair of LED_* event codes and libevdev_led_value_t, followed by 1914 * -1 to terminate the list. 1915 * @return 0 on success, or a negative errno on failure 1916 */ 1917 int libevdev_kernel_set_led_values(struct libevdev *dev, ...); 1918 1919 /** 1920 * @ingroup kernel 1921 * 1922 * Set the clock ID to be used for timestamps. Further events from this device 1923 * will report an event time based on the given clock. 1924 * 1925 * This is a modification only affecting this representation of 1926 * this device. 1927 * 1928 * @param dev The evdev device, already initialized with libevdev_set_fd() 1929 * @param clockid The clock to use for future events. Permitted values 1930 * are CLOCK_MONOTONIC and CLOCK_REALTIME (the default). 1931 * @return 0 on success, or a negative errno on failure 1932 */ 1933 int libevdev_set_clock_id(struct libevdev *dev, int clockid); 1934 1935 /** 1936 * @ingroup misc 1937 * 1938 * Helper function to check if an event is of a specific type. This is 1939 * virtually the same as: 1940 * 1941 * ev->type == type 1942 * 1943 * with the exception that some sanity checks are performed to ensure type 1944 * is valid. 1945 * 1946 * @note The ranges for types are compiled into libevdev. If the kernel 1947 * changes the max value, libevdev will not automatically pick these up. 1948 * 1949 * @param ev The input event to check 1950 * @param type Input event type to compare the event against (EV_REL, EV_ABS, 1951 * etc.) 1952 * 1953 * @return 1 if the event type matches the given type, 0 otherwise (or if 1954 * type is invalid) 1955 */ 1956 int libevdev_event_is_type(const struct input_event *ev, unsigned int type); 1957 1958 /** 1959 * @ingroup misc 1960 * 1961 * Helper function to check if an event is of a specific type and code. This 1962 * is virtually the same as: 1963 * 1964 * ev->type == type && ev->code == code 1965 * 1966 * with the exception that some sanity checks are performed to ensure type and 1967 * code are valid. 1968 * 1969 * @note The ranges for types and codes are compiled into libevdev. If the kernel 1970 * changes the max value, libevdev will not automatically pick these up. 1971 * 1972 * @param ev The input event to check 1973 * @param type Input event type to compare the event against (EV_REL, EV_ABS, 1974 * etc.) 1975 * @param code Input event code to compare the event against (ABS_X, REL_X, 1976 * etc.) 1977 * 1978 * @return 1 if the event type matches the given type and code, 0 otherwise 1979 * (or if type/code are invalid) 1980 */ 1981 int libevdev_event_is_code(const struct input_event *ev, unsigned int type, unsigned int code); 1982 1983 /** 1984 * @ingroup misc 1985 * 1986 * @param type The event type to return the name for. 1987 * 1988 * @return The name of the given event type (e.g. EV_ABS) or NULL for an 1989 * invalid type 1990 * 1991 * @note The list of names is compiled into libevdev. If the kernel adds new 1992 * defines for new event types, libevdev will not automatically pick these up. 1993 */ 1994 const char * libevdev_event_type_get_name(unsigned int type); 1995 /** 1996 * @ingroup misc 1997 * 1998 * @param type The event type for the code to query (EV_SYN, EV_REL, etc.) 1999 * @param code The event code to return the name for (e.g. ABS_X) 2000 * 2001 * @return The name of the given event code (e.g. ABS_X) or NULL for an 2002 * invalid type or code 2003 * 2004 * @note The list of names is compiled into libevdev. If the kernel adds new 2005 * defines for new event codes, libevdev will not automatically pick these up. 2006 */ 2007 const char * libevdev_event_code_get_name(unsigned int type, unsigned int code); 2008 2009 /** 2010 * @ingroup misc 2011 * 2012 * @param prop The input prop to return the name for (e.g. INPUT_PROP_BUTTONPAD) 2013 * 2014 * @return The name of the given input prop (e.g. INPUT_PROP_BUTTONPAD) or NULL for an 2015 * invalid property 2016 * 2017 * @note The list of names is compiled into libevdev. If the kernel adds new 2018 * defines for new properties libevdev will not automatically pick these up. 2019 * @note On older kernels input properties may not be defined and 2020 * libevdev_property_get_name() will always return NULL 2021 */ 2022 const char* libevdev_property_get_name(unsigned int prop); 2023 2024 /** 2025 * @ingroup misc 2026 * 2027 * @param type The event type to return the maximum for (EV_ABS, EV_REL, etc.). No max is defined for 2028 * EV_SYN. 2029 * 2030 * @return The max value defined for the given event type, e.g. ABS_MAX for a type of EV_ABS, or -1 2031 * for an invalid type. 2032 * 2033 * @note The max value is compiled into libevdev. If the kernel changes the 2034 * max value, libevdev will not automatically pick these up. 2035 */ 2036 int libevdev_event_type_get_max(unsigned int type); 2037 2038 /** 2039 * @ingroup misc 2040 * 2041 * Look up an event-type by its name. Event-types start with "EV_" followed by 2042 * the name (eg., "EV_ABS"). The "EV_" prefix must be included in the name. It 2043 * returns the constant assigned to the event-type or -1 if not found. 2044 * 2045 * @param name A non-NULL string describing an input-event type ("EV_KEY", 2046 * "EV_ABS", ...), zero-terminated. 2047 * 2048 * @return The given type constant for the passed name or -1 if not found. 2049 * 2050 * @note EV_MAX is also recognized. 2051 */ 2052 int libevdev_event_type_from_name(const char *name); 2053 2054 /** 2055 * @ingroup misc 2056 * 2057 * Look up an event-type by its name. Event-types start with "EV_" followed by 2058 * the name (eg., "EV_ABS"). The "EV_" prefix must be included in the name. It 2059 * returns the constant assigned to the event-type or -1 if not found. 2060 * 2061 * @param name A non-NULL string describing an input-event type ("EV_KEY", 2062 * "EV_ABS", ...). 2063 * @param len The length of the passed string excluding any terminating 0 2064 * character. 2065 * 2066 * @return The given type constant for the passed name or -1 if not found. 2067 * 2068 * @note EV_MAX is also recognized. 2069 */ 2070 int libevdev_event_type_from_name_n(const char *name, size_t len); 2071 2072 /** 2073 * @ingroup misc 2074 * 2075 * Look up an event code by its type and name. Event codes start with a fixed 2076 * prefix followed by their name (eg., "ABS_X"). The prefix must be included in 2077 * the name. It returns the constant assigned to the event code or -1 if not 2078 * found. 2079 * 2080 * You have to pass the event type where to look for the name. For instance, to 2081 * resolve "ABS_X" you need to pass EV_ABS as type and "ABS_X" as string. 2082 * Supported event codes are codes starting with SYN_, KEY_, BTN_, REL_, ABS_, 2083 * MSC_, SND_, SW_, LED_, REP_, FF_. 2084 * 2085 * @param type The event type (EV_* constant) where to look for the name. 2086 * @param name A non-NULL string describing an input-event code ("KEY_A", 2087 * "ABS_X", "BTN_Y", ...), zero-terminated. 2088 * 2089 * @return The given code constant for the passed name or -1 if not found. 2090 */ 2091 int libevdev_event_code_from_name(unsigned int type, const char *name); 2092 2093 /** 2094 * @ingroup misc 2095 * 2096 * Look up an event code by its type and name. Event codes start with a fixed 2097 * prefix followed by their name (eg., "ABS_X"). The prefix must be included in 2098 * the name. It returns the constant assigned to the event code or -1 if not 2099 * found. 2100 * 2101 * You have to pass the event type where to look for the name. For instance, to 2102 * resolve "ABS_X" you need to pass EV_ABS as type and "ABS_X" as string. 2103 * Supported event codes are codes starting with SYN_, KEY_, BTN_, REL_, ABS_, 2104 * MSC_, SND_, SW_, LED_, REP_, FF_. 2105 * 2106 * @param type The event type (EV_* constant) where to look for the name. 2107 * @param name A non-NULL string describing an input-event code ("KEY_A", 2108 * "ABS_X", "BTN_Y", ...). 2109 * @param len The length of the string in @p name excluding any terminating 0 2110 * character. 2111 * 2112 * @return The given code constant for the name or -1 if not found. 2113 */ 2114 int libevdev_event_code_from_name_n(unsigned int type, const char *name, 2115 size_t len); 2116 2117 /** 2118 * @ingroup misc 2119 * 2120 * Look up an input property by its name. Properties start with the fixed 2121 * prefix "INPUT_PROP_" followed by their name (eg., "INPUT_PROP_POINTER"). 2122 * The prefix must be included in the name. It returns the constant assigned 2123 * to the property or -1 if not found. 2124 * 2125 * @param name A non-NULL string describing an input property 2126 * 2127 * @return The given code constant for the name or -1 if not found. 2128 */ 2129 int libevdev_property_from_name(const char *name); 2130 2131 /** 2132 * @ingroup misc 2133 * 2134 * Look up an input property by its name. Properties start with the fixed 2135 * prefix "INPUT_PROP_" followed by their name (eg., "INPUT_PROP_POINTER"). 2136 * The prefix must be included in the name. It returns the constant assigned 2137 * to the property or -1 if not found. 2138 * 2139 * @param name A non-NULL string describing an input property 2140 * @param len The length of the string in @p name excluding any terminating 0 2141 * character. 2142 * 2143 * @return The given code constant for the name or -1 if not found. 2144 */ 2145 int libevdev_property_from_name_n(const char *name, size_t len); 2146 2147 /** 2148 * @ingroup bits 2149 * 2150 * Get the repeat delay and repeat period values for this device. This 2151 * function is a convenience function only, EV_REP is supported by 2152 * libevdev_get_event_value(). 2153 * 2154 * @param dev The evdev device, already initialized with libevdev_set_fd() 2155 * @param delay If not null, set to the repeat delay value 2156 * @param period If not null, set to the repeat period value 2157 * 2158 * @return 0 on success, -1 if this device does not have repeat settings. 2159 * 2160 * @note This function is signal-safe 2161 * 2162 * @see libevdev_get_event_value 2163 */ 2164 int libevdev_get_repeat(const struct libevdev *dev, int *delay, int *period); 2165 2166 /********* DEPRECATED SECTION *********/ 2167 #if defined(__GNUC__) && __GNUC__ >= 4 2168 #define LIBEVDEV_DEPRECATED __attribute__ ((deprecated)) 2169 #else 2170 #define LIBEVDEV_DEPRECATED 2171 #endif 2172 2173 #ifdef __cplusplus 2174 } 2175 #endif 2176 2177 #endif /* LIBEVDEV_H */ 2178