libevdev/libevdev.h

   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 #include <config.h>
  27 #include <linux/input.h>
  28 #include <stdarg.h>
  29
  30 /**
  31  * @mainpage
  32  *
  33  * **libevdev** is a library for handling evdev kernel devices. It abstracts
  34  * the ioctls through type-safe interfaces and provides functions to change
  35  * the appearance of the device.
  36  *
  37  * Handling events and SYN_DROPPED
  38  * ===============================
  39  *
  40  * libevdev provides an interface for handling events, including most notably
  41  * SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the
  42  * process does not read events fast enough and the kernel is forced to drop
  43  * some events. This causes the device to get out of sync with the process'
  44  * view of it. libevdev handles this by telling the caller that a SYN_DROPPED
  45  * has been received and that the state of the device is different to what is
  46  * to be expected. It then provides the delta between the previous state and
  47  * the actual state of the device as a set of events. See
  48  * libevdev_next_event() for more information.
  49  *
  50  * Signal safety
  51  * =============
  52  *
  53  * libevdev is signal-safe for the majority of its operations. Check the API
  54  * documentation to make sure, unless explicitly stated a call is <b>not</b>
  55  * signal safe.
  56  *
  57  * Device handling
  58  * ===============
  59  *
  60  * libevdev does not attempt duplicate detection. Initializing two libevdev
  61  * devices for the same fd is valid and behaves the same as for two different
  62  * devices.
  63  *
  64  * libevdev does not handle the file descriptors directly, it merely uses
  65  * them. The caller is responsible for opening the file descriptors, setting
  66  * them to O_NONBLOCK and handling permissions.
  67  *
  68  * Where does libevdev sit?
  69  * ========================
  70  *
  71  * libevdev is essentially a read(2) on steroids for /dev/input/eventX
  72  * devices. It sits below the process that handles input events, in between
  73  * the kernel and that process. In the simplest case, e.g. an evtest-like tool
  74  * the stack would look like this:
  75  *
  76  * kernel → libevdev → evtest
  77  *
  78  * For X.Org input modules, the stack would look like this:
  79  *
  80  * kernel → libevdev → xf86-input-evdev → X server → X client
  81  *
  82  * For Weston/Wayland, the stack would look like this:
  83  *
  84  * kernel → libevdev → Weston → Wayland client
  85  *
  86  * libevdev does **not** have knowledge of X clients or Wayland clients, it is
  87  * too low in the stack.
  88  */
  89
  90 /**
  91  * @defgroup init Initialization and setup
  92  *
  93  * Initialization, initial setup and file descriptor handling.
  94  * These functions are the main entry points for users of libevdev, usually a
  95  * caller will use this series of calls:
  96  *
  97  * @code
  98  * struct libevdev *dev;
  99  * int err;
 100  *
 101  * dev = libevdev_new();
 102  * if (!dev)
 103  *    return ENOSPC;
 104
 105  * err = libevdev_set_fd(dev, fd);
 106  * if (err < 0) {
 107  *      printf("Failed (errno %d): %s\n", -err, strerror(-err));
 108  *
 109  * libevdev_free(dev);
 110  * @endcode
 111  *
 112  * libevdev_set_fd() is the central call and initializes the internal structs
 113  * for the device at the given fd. libevdev functions will fail if called
 114  * before libevdev_set_fd() unless documented otherwise.
 115  */
 116
 117 /**
 118  * @defgroup bits Querying device capabilities
 119  *
 120  * Abstraction functions to handle device capabilities, specificially
 121  * device propeties such as the name of the device and the bits
 122  * representing the events suppported by this device.
 123  *
 124  * The logical state returned may lag behind the physical state of the device.
 125  * libevdev queries the device state on libevdev_set_fd() and then relies on
 126  * the caller to parse events through libevdev_next_fd(). If a caller does not
 127  * use libevdev_next_fd(), libevdev will not update the internal state of the
 128  * device and thus returns outdated values.
 129  */
 130
 131 /**
 132  * @defgroup mt Multi-touch related functions
 133  * Functions for querying multi-touch-related capabilities. MT devices
 134  * following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch
 135  * points through so-called slots on the same axis. The slots are enumerated,
 136  * a client reading from the device will first get an ABS_MT_SLOT event, then
 137  * the values of axes changed in this slot. Multiple slots may be provided in
 138  * before an EV_SYN event.
 139  *
 140  * As with @ref bits, the logical state of the device as seen by the library
 141  * depends on the caller using libevdev_next_event().
 142  */
 143
 144 /**
 145  * @defgroup kernel Modifying the appearance or capabilities of the device
 146  *
 147  * Modifying the set of events reported by this device. By default, the
 148  * libevdev device mirrors the kernel device, enabling only those bits
 149  * exported by the kernel. This set of functions enable or disable bits as
 150  * seen from the caller.
 151  *
 152  * Enabling an event type or code does not affect event reporting - a
 153  * software-enabled event will not be generated by the physical hardware.
 154  * Disabling an event will prevent libevdev from routing such events to the
 155  * caller. Enabling and disabling event types and codes is at the library
 156  * level and thus only affects the caller.
 157  *
 158  * If an event type or code is enabled at kernel-level, future users of this
 159  * device will see this event enabled. Currently there is no option of
 160  * disabling an event type or code at kernel-level.
 161  */
 162
 163 /**
 164  * @defgroup misc Miscellaneous helper functions
 165  *
 166  * Functions for printing or querying event ranges. The list of names is
 167  * compiled into libevdev and will not change when the kernel changes. Adding
 168  * or removing names requires a re-compilation of libevdev. Likewise, the max
 169  * for each event type is compiled in and does not check the underlying
 170  * kernel.
 171  */
 172
 173 /**
 174  * @defgroup events Event handling
 175  *
 176  * Functions to handle events and fetch the current state of the event. Generally,
 177  * libevdev updates its internal state as the event is processed and forwarded
 178  * to the caller. Thus, the libevdev state of the device should always be identical
 179  * to the caller's state. It may however lag behind the actual state of the device.
 180  */
 181
 182 /**
 183  * @ingroup init
 184  *
 185  * Opaque struct representing an evdev device.
 186  */
 187 struct libevdev;
 188
 189 enum EvdevReadFlags {
 190         LIBEVDEV_READ_SYNC              = 1, /**< Process data in sync mode */
 191         LIBEVDEV_READ_NORMAL            = 2, /**< Process data in normal mode */
 192         LIBEVDEV_FORCE_SYNC             = 4, /**< Pretend the next event is a SYN_DROPPED. There is
 193                                                   no reason to ever use this except for
 194                                                   automated tests, so don't. */
 195 };
 196
 197 /**
 198  * @ingroup init
 199  *
 200  * Initialize a new libevdev device. This function only allocates the
 201  * required memory and initializes the struct to sane default values.
 202  * To actually hook up the device to a kernel device, use
 203  * libevdev_set_fd().
 204  *
 205  * Memory allocated through libevdev_new() must be released by the
 206  * caller with libevdev_free().
 207  *
 208  * @see libevdev_set_fd
 209  * @see libevdev_free
 210  */
 211 struct libevdev* libevdev_new(void);
 212
 213 /**
 214  * @ingroup init
 215  *
 216  * Initialize a new libevdev device from the given fd.
 217  *
 218  * This is a shortcut for
 219  *
 220  * @code
 221  * int err;
 222  * struct libevdev *dev = libevdev_new();
 223  * err = libevdev_set_fd(dev, fd);
 224  * @endcode
 225  *
 226  * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
 227  *
 228  * @return On success, zero is returned and dev is set to the newly
 229  * allocated struct. On failure, a negative errno is returned and the value
 230  * of dev is undefined.
 231  *
 232  * @see libevdev_free
 233  */
 234 int libevdev_new_from_fd(int fd, struct libevdev **dev);
 235
 236 /**
 237  * @ingroup init
 238  *
 239  * Clean up and free the libevdev struct. After completion, the <code>struct
 240  * libevdev</code> is invalid and must not be used.
 241  *
 242  * @note This function may be called before libevdev_set_fd().
 243  */
 244 void libevdev_free(struct libevdev *dev);
 245
 246 /**
 247  * Logging function called by library-internal logging.
 248  * This function is expected to treat it's input like printf would.
 249  *
 250  * @param format printf-style format string
 251  * @param args List of arguments
 252  *
 253  * @see libevdev_set_log_handler
 254  */
 255 typedef void (*libevdev_log_func_t)(const char *format, va_list args);
 256
 257 /**
 258  * Set a printf-style logging handler for library-internal logging.
 259  *
 260  * @note This function may be called before libevdev_set_fd().
 261  */
 262 void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc);
 263
 264
 265 enum EvdevGrabModes {
 266         LIBEVDEV_GRAB = 3,
 267         LIBEVDEV_UNGRAB = 4,
 268 };
 269
 270 /**
 271  * Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other
 272  * clients (including kernel-internal ones such as rfkill) from receiving
 273  * events from this device.
 274  *
 275  * This is generally a bad idea. Don't do this.
 276  *
 277  * Grabbing an already grabbed device, or ungrabbing an ungrabbed device is
 278  * a noop and always succeeds.
 279  *
 280  * @param grab If true, grab the device. Otherwise ungrab the device.
 281  *
 282  * @return 0 if the device was successfull grabbed or ungrabbed, or a
 283  * negative errno in case of failure.
 284  */
 285 int libevdev_grab(struct libevdev *dev, int grab);
 286
 287 /**
 288  * @ingroup init
 289  *
 290  * Set the fd for this struct and initialize internal data.
 291  * The fd must be in O_RDONLY or O_RDWR mode.
 292  *
 293  * This function may only be called once per device. If the device changed and
 294  * you need to re-read a device, use libevdev_free() and libevdev_new(). If
 295  * you need to change the fd after closing and re-opening the same device, use
 296  * libevdev_change_fd().
 297  *
 298  * Unless otherwise specified, libevdev function behavior is undefined until
 299  * a successfull call to libevdev_set_fd().
 300  *
 301  * @param fd The file descriptor for the device
 302  *
 303  * @return 0 on success, or a negative error code on failure
 304  *
 305  * @see libevdev_change_fd
 306  * @see libevdev_new
 307  * @see libevdev_free
 308  */
 309 int libevdev_set_fd(struct libevdev* dev, int fd);
 310
 311 /**
 312  * @ingroup init
 313  *
 314  * Change the fd for this device, without re-reading the actual device. If the fd
 315  * changes after initializing the device, for example after a VT-switch in the
 316  * X.org X server, this function updates the internal fd to the newly opened.
 317  * No check is made that new fd points to the same device. If the device has
 318  * changed, libevdev's behavior is undefined.
 319  *
 320  * The fd may be open in O_RDONLY or O_RDWR.
 321  *
 322  * It is an error to call this function before calling libevdev_set_fd().
 323  *
 324  * @param fd The new fd
 325  *
 326  * @return 0 on success, or -1 on failure.
 327  *
 328  * @see libevdev_set_fd
 329  */
 330 int libevdev_change_fd(struct libevdev* dev, int fd);
 331
 332 /**
 333  *
 334  * @return The previously set fd, or -1 if none had been set previously.
 335  * @note This function may be called before libevdev_set_fd().
 336  */
 337 int libevdev_get_fd(const struct libevdev* dev);
 338
 339 /**
 340  * @ingroup events
 341  *
 342  * Get the next event from the device. This function operates in two different
 343  * modes: normal mode or sync mode.
 344  *
 345  * In normal mode, this function returns 0 and returns the event in the
 346  * parameter ev. If no events are available at this time, it returns -EAGAIN
 347  * and ev is undefined.
 348  *
 349  * If a SYN_DROPPED is read from the device, this function returns 1. The
 350  * caller should now call this function with the LIBEVDEV_READ_SYNC flag set,
 351  * to get the set of events that make up the device state delta. This function
 352  * returns 1 for each event part of that delta, until it returns -EAGAIN once
 353  * all events have been synced.
 354  *
 355  * If a device needs to be synced by the caller but the caller does not call
 356  * with the LIBEVDEV_READ_SYNC flag set, all events from the diff are dropped
 357  * and event processing continues as normal.
 358  *
 359  * @param flags Set of flags to determine behaviour. If LIBEVDEV_READ_NORMAL
 360  * is set, the next event is read in normal mode. If LIBEVDEV_READ_SYNC is
 361  * set, the next event is read in sync mode.
 362  * @param ev On success, set to the current event.
 363  * @return On failure, a negative errno is returned.
 364  * @retval 0 One or more events where read of the device
 365  * @retval -EAGAIN No events are currently available on the device
 366  * @retval 1 A SYN_DROPPED event was received, or a synced event was
 367  * returned.
 368  *
 369  * @note This function is signal-safe.
 370  */
 371 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev);
 372
 373 /**
 374  * @ingroup bits
 375  *
 376  * @return The device name as read off the kernel device. The name is never
 377  * NULL but it may be the empty string.
 378  *
 379  * @note This function is signal-safe.
 380  */
 381 const char* libevdev_get_name(const struct libevdev *dev);
 382
 383 /**
 384  * @ingroup bits
 385  *
 386  * Virtual devices such as uinput devices have no phys location.
 387  *
 388  * @return The physical location of this device, or NULL if there is none
 389  *
 390  * @note This function is signal safe.
 391  */
 392 const char * libevdev_get_phys(const struct libevdev *dev);
 393
 394 /**
 395  * @ingroup bits
 396  *
 397  * @return The unique identifier for this device, or NULL if there is none
 398  *
 399  * @note This function is signal safe.
 400  */
 401 const char * libevdev_get_uniq(const struct libevdev *dev);
 402
 403 /**
 404  * @ingroup bits
 405  *
 406  * @return The device's product ID
 407  *
 408  * @note This function is signal-safe.
 409  */
 410 int libevdev_get_product_id(const struct libevdev *dev);
 411
 412 /**
 413  * @ingroup bits
 414  *
 415  * @return The device's vendor ID
 416  *
 417  * @note This function is signal-safe.
 418  */
 419 int libevdev_get_vendor_id(const struct libevdev *dev);
 420
 421 /**
 422  * @ingroup bits
 423  *
 424  * @return The device's bus type
 425  *
 426  * @note This function is signal-safe.
 427  */
 428 int libevdev_get_bustype(const struct libevdev *dev);
 429
 430 /**
 431  * @ingroup bits
 432  *
 433  * @return The device's firmware version
 434  *
 435  * @note This function is signal-safe.
 436  */
 437 int libevdev_get_version(const struct libevdev *dev);
 438
 439 /**
 440  * @ingroup bits
 441  *
 442  * @return The driver version for this device
 443  *
 444  * @note This function is signal-safe.
 445  */
 446 int libevdev_get_driver_version(const struct libevdev *dev);
 447
 448 /**
 449  * @ingroup bits
 450  *
 451  * @return 1 if the device provides this input property, or 0 otherwise.
 452  *
 453  * @note This function is signal-safe
 454  */
 455 int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
 456
 457 /**
 458  * @ingroup bits
 459  *
 460  * @return 1 if the device supports this event type, or 0 otherwise.
 461  *
 462  * @note This function is signal-safe.
 463  */
 464 int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
 465
 466 /**
 467  * @ingroup bits
 468  *
 469  * @return 1 if the device supports this event type and code, or 0 otherwise.
 470  *
 471  * @note This function is signal-safe.
 472  */
 473 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code);
 474
 475 /**
 476  * @ingroup bits
 477  *
 478  * @return axis minimum for the given axis or 0 if the axis is invalid
 479  */
 480 int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code);
 481 /**
 482  * @ingroup bits
 483  *
 484  * @return axis maximum for the given axis or 0 if the axis is invalid
 485  */
 486 int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code);
 487 /**
 488  * @ingroup bits
 489  *
 490  * @return axis fuzz for the given axis or 0 if the axis is invalid
 491  */
 492 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code);
 493 /**
 494  * @ingroup bits
 495  *
 496  * @return axis flat for the given axis or 0 if the axis is invalid
 497  */
 498 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code);
 499 /**
 500  * @ingroup bits
 501  *
 502  * @return axis resolution for the given axis or 0 if the axis is invalid
 503  */
 504 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code);
 505
 506 /**
 507  * @ingroup bits
 508  *
 509  * @return The input_absinfo for the given code, or NULL if the device does
 510  * not support this event code.
 511  */
 512 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code);
 513
 514 /**
 515  * @ingroup bits
 516  *
 517  * Behaviour of this function is undefined if the device does not provide
 518  * the event.
 519  *
 520  * @return The current value of the event.
 521  *
 522  * @note This function is signal-safe.
 523  * @note The value for ABS_MT_ events is undefined, use
 524  * libevdev_get_slot_value() instead
 525  *
 526  * @see libevdev_get_slot_value
 527  */
 528 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code);
 529
 530 /**
 531  * @ingroup bits
 532  *
 533  * Fetch the current value of the event type. This is a shortcut for
 534  *
 535  * @code
 536  *   if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
 537  *       val = libevdev_get_event_value(dev, t, c);
 538  * @endcode
 539  *
 540  * @return If the device supports this event type and code, the return value is
 541  * non-zero and value is set to the current value of this axis. Otherwise,
 542  * zero is returned and value is unmodified.
 543  *
 544  * @note This function is signal-safe.
 545  * @note The value for ABS_MT_ events is undefined, use
 546  * libevdev_fetch_slot_value() instead
 547  *
 548  * @see libevdev_fetch_slot_value
 549  */
 550 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value);
 551
 552 /**
 553  * @ingroup mt
 554  *
 555  * Return the current value of the code for the given slot.
 556  *
 557  * The return value is undefined for a slot exceeding the available slots on
 558  * the device, for a code that is not in the permitted ABS_MT range or for a
 559  * device that does not have slots.
 560  *
 561  * @note This function is signal-safe.
 562  * @note The value for events other than ABS_MT_ is undefined, use
 563  * libevdev_fetch_value() instead
 564  *
 565  * @see libevdev_get_value
 566  */
 567 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code);
 568
 569 /**
 570  * @ingroup mt
 571  *
 572  * Fetch the current value of the code for the given slot. This is a shortcut for
 573  *
 574  * @code
 575  *   if (libevdev_has_event_type(dev, EV_ABS) &&
 576  *       libevdev_has_event_code(dev, EV_ABS, c) &&
 577  *       slot < device->number_of_slots)
 578  *       val = libevdev_get_slot_value(dev, slot, c);
 579  * @endcode
 580  *
 581  * @return If the device supports this event code, the return value is
 582  * non-zero and value is set to the current value of this axis. Otherwise, or
 583  * if the event code is not an ABS_MT_* event code, zero is returned and value
 584  * is unmodified.
 585  *
 586  * @note This function is signal-safe.
 587  */
 588 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
 589
 590 /**
 591  * @ingroup mt
 592  *
 593  * Get the number of slots supported by this device.
 594  *
 595  * @return The number of slots supported, or -1 if the device does not provide
 596  * any slots
 597  *
 598  * @note A device may provide ABS_MT_SLOT but a total number of 0 slots. Hence
 599  * the return value of -1 for "device does not provide slots at all"
 600  */
 601 int libevdev_get_num_slots(const struct libevdev *dev);
 602
 603 /**
 604  * @ingroup mt
 605  *
 606  * Get the currently active slot. This may differ from the value
 607  * an ioctl may return at this time as events may have been read off the fd
 608  * since changing the slot value but those events are still in the buffer
 609  * waiting to be processed. The returned value is the value a caller would
 610  * see if it were to process events manually one-by-one.
 611  *
 612  * @return the currently active slot (logically)
 613  */
 614 int libevdev_get_current_slot(const struct libevdev *dev);
 615
 616 /**
 617  * @ingroup kernel
 618  *
 619  * Forcibly enable an event type on this device, even if the underlying
 620  * device does not support it. While this cannot make the device actually
 621  * report such events, it will now return true for libevdev_has_event_type().
 622  *
 623  * This is a local modification only affecting only this representation of
 624  * this device.
 625  *
 626  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 627  *
 628  * @return 0 on success or -1 otherwise
 629  *
 630  * @see libevdev_has_event_type
 631  */
 632 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
 633
 634 /**
 635  * @ingroup kernel
 636  *
 637  * Forcibly disable an event type on this device, even if the underlying
 638  * device provides it, effectively muting all keys or axes. libevdev will
 639  * filter any events matching this type and none will reach the caller.
 640  * libevdev_has_event_type() will return false for this type.
 641  *
 642  * In most cases, a caller likely only wants to disable a single code, not
 643  * the whole type. Use libevdev_disable_event_code() for that.
 644  *
 645  * This is a local modification only affecting only this representation of
 646  * this device.
 647  *
 648  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
 649  *
 650  * @return 0 on success or -1 otherwise
 651  *
 652  * @see libevdev_has_event_type
 653  * @see libevdev_disable_event_type
 654  */
 655 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
 656
 657 /**
 658  * @ingroup kernel
 659  *
 660  * Forcibly enable an event type on this device, even if the underlying
 661  * device does not support it. While this cannot make the device actually
 662  * report such events, it will now return true for libevdev_has_event_code().
 663  *
 664  * The last argument depends on the type and code:
 665  * - If type is EV_ABS, the vararg must be a pointer to a struct input_absinfo
 666  * containing the data for this axis.
 667  * - For all other types, the argument is ignored.
 668  *
 669  * This function calls libevdev_enable_event_type() if necessary.
 670  *
 671  * This is a local modification only affecting only this representation of
 672  * this device.
 673  *
 674  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 675  * @param code The event code to enable (ABS_X, REL_X, etc.)
 676  * @param data Axis/key data, depending on type and code
 677  *
 678  * @return 0 on success or -1 otherwise
 679  *
 680  * @see libevdev_enable_event_type
 681  */
 682 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
 683
 684 /**
 685  * @ingroup kernel
 686  *
 687  * Forcibly disable an event code on this device, even if the underlying
 688  * device provides it, effectively muting this key or axis. libevdev will
 689  * filter any events matching this type and code and none will reach the
 690  * caller.
 691  * libevdev_has_event_code() will return false for this code combination.
 692  *
 693  * Disabling all event codes for a given type will not disable the event
 694  * type. Use libevdev_disable_event_type() for that.
 695  *
 696  * This is a local modification only affecting only this representation of
 697  * this device.
 698  *
 699  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
 700  * @param code The event code to disable (ABS_X, REL_X, etc.)
 701  *
 702  * @return 0 on success or -1 otherwise
 703  *
 704  * @see libevdev_has_event_code
 705  * @see libevdev_disable_event_type
 706  */
 707 int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code);
 708
 709
 710 /**
 711  * @ingroup kernel
 712  *
 713  * Forcibly enable an event type on this device, even if the underlying
 714  * device does not support it. While this cannot make the device actually
 715  * report such events, it will now return true for libevdev_has_event_code().
 716  *
 717  * This will be written to the kernel.
 718  *
 719  * This cannot be undone, the kernel only allows to enable axes, not disable
 720  * them.
 721  *
 722  * This function calls libevdev_kernel_enable_event_type() if necessary.
 723  *
 724  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 725  */
 726 int libevdev_kernel_enable_event_type(struct libevdev *dev, unsigned int type);
 727
 728 /**
 729  * @ingroup kernel
 730  *
 731  * Forcibly enable an event code on this device, even if the underlying
 732  * device does not support it. While this cannot make the device actually
 733  * report such events, it will now return true for libevdev_has_event_code().
 734  *
 735  * This will be written to the kernel.
 736  *
 737  * This cannot be undone, the kernel only allows to enable axes, not disable
 738  * them.
 739  *
 740  * The last argument depends on the type and code:
 741  * - If type is EV_ABS, the vararg must be a pointer to a struct input_absinfo
 742  * containing the data for this axis.
 743  * - For all other types, the argument is ignored.
 744  *
 745  * This function calls libevdev_kernel_enable_event_type() if necessary.
 746  *
 747  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 748  * @param code The event code to enable (ABS_X, REL_X, etc.)
 749  * @param data Axis/key data, depending on type and code
 750  */
 751 int libevdev_kernel_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
 752
 753 /**
 754  * @ingroup kernel
 755  *
 756  * Set the device's EV_ABS axis to the value defined in the abs
 757  * parameter. This will be written to the kernel.
 758  *
 759  * @return zero on success, or a negative errno on failure
 760  *
 761  * @see libevdev_enable_event_code
 762  */
 763 int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
 764
 765 /**
 766  * @ingroup misc
 767  *
 768  * @return The name of the given event type (e.g. EV_ABS) or NULL for an
 769  * invalid type
 770  *
 771  * @note The list of names is compiled into libevdev. If the kernel adds new
 772  * defines for new properties libevdev will not automatically pick these up.
 773  */
 774 const char * libevdev_get_event_type_name(unsigned int type);
 775 /**
 776  * @ingroup misc
 777  *
 778  * @return The name of the given event code (e.g. ABS_X) or NULL for an
 779  * invalid type or code
 780  *
 781  * @note The list of names is compiled into libevdev. If the kernel adds new
 782  * defines for new properties libevdev will not automatically pick these up.
 783  */
 784 const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
 785
 786 /**
 787  * @ingroup misc
 788  *
 789  * @return The name of the given input prop (e.g. INPUT_PROP_BUTTONPAD) or NULL for an
 790  * invalid property
 791  *
 792  * @note The list of names is compiled into libevdev. If the kernel adds new
 793  * defines for new properties libevdev will not automatically pick these up.
 794  * @note On older kernels input properties may not be defined and
 795  * libevdev_get_input_prop_name() will always return NULL
 796  */
 797 const char * libevdev_get_input_prop_name(unsigned int prop);
 798
 799 /**
 800  * @ingroup misc
 801  *
 802  * @return The max value defined for the given event type, e.g. ABS_MAX for a type of EV_ABS, or -1
 803  * for an invalid type.
 804  *
 805  * @note The max value is compiled into libevdev. If the kernel changes the
 806  * max value, libevdev will not automatically pick these up.
 807  */
 808 int libevdev_get_event_type_max(unsigned int type);
 809
 810 /**
 811  * @ingroup bits
 812  *
 813  * Get the repeat delay and repeat period values for this device.
 814  *
 815  * @param delay If not null, set to the repeat delay value
 816  * @param period If not null, set to the repeat period value
 817  *
 818  * @return 0 on success, -1 if this device does not have repeat settings.
 819  *
 820  * @note This function is signal-safe
 821  */
 822 int libevdev_get_repeat(struct libevdev *dev, int *delay, int *period);
 823
 824 #endif /* libevdev_H */