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 <linux/input.h>
  27 #include <stdarg.h>
  28
  29 /**
  30  * @mainpage
  31  *
  32  * **libevdev** is a library for handling evdev kernel devices. It abstracts
  33  * the ioctls through type-safe interfaces and provides functions to change
  34  * the appearance of the device.
  35  *
  36  * Development of libevdev is discussed on
  37  * [input-tools@lists.freedesktop.org](http://lists.freedesktop.org/mailman/listinfo/input-tools)
  38  * Please submit patches, questions or general comments there.
  39  *
  40  * Handling events and SYN_DROPPED
  41  * ===============================
  42  *
  43  * libevdev provides an interface for handling events, including most notably
  44  * SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the
  45  * process does not read events fast enough and the kernel is forced to drop
  46  * some events. This causes the device to get out of sync with the process'
  47  * view of it. libevdev handles this by telling the caller that a SYN_DROPPED
  48  * has been received and that the state of the device is different to what is
  49  * to be expected. It then provides the delta between the previous state and
  50  * the actual state of the device as a set of events. See
  51  * libevdev_next_event() for more information.
  52  *
  53  * Signal safety
  54  * =============
  55  *
  56  * libevdev is signal-safe for the majority of its operations. Check the API
  57  * documentation to make sure, unless explicitly stated a call is <b>not</b>
  58  * signal safe.
  59  *
  60  * Device handling
  61  * ===============
  62  *
  63  * libevdev does not attempt duplicate detection. Initializing two libevdev
  64  * devices for the same fd is valid and behaves the same as for two different
  65  * devices.
  66  *
  67  * libevdev does not handle the file descriptors directly, it merely uses
  68  * them. The caller is responsible for opening the file descriptors, setting
  69  * them to O_NONBLOCK and handling permissions.
  70  *
  71  * Where does libevdev sit?
  72  * ========================
  73  *
  74  * libevdev is essentially a `read(2)` on steroids for `/dev/input/eventX
  75  * devices. It sits below the process that handles input events, in between
  76  * the kernel and that process. In the simplest case, e.g. an evtest-like tool
  77  * the stack would look like this:
  78  *
  79  *      kernel → libevdev → evtest
  80  *
  81  * For X.Org input modules, the stack would look like this:
  82  *
  83  *      kernel → libevdev → xf86-input-evdev → X server → X client
  84  *
  85  * For Weston/Wayland, the stack would look like this:
  86  *
  87  *      kernel → libevdev → Weston → Wayland client
  88  *
  89  * libevdev does **not** have knowledge of X clients or Wayland clients, it is
  90  * too low in the stack.
  91  *
  92  * Example
  93  * =======
  94  * Below is a simple example that shows how libevdev could be used. This example
  95  * opens a device, checks for relative axes and a left mouse button and if it
  96  * finds them monitors the device to print the event.
  97  *
  98  * @code
  99  *      struct libevdev *dev = NULL;
 100  *      int fd;
 101  *      int rc = 1;
 102  *
 103  *      fd = open("/dev/input/event0", O_RDONLY|O_NONBLOCK);
 104  *      rc = libevdev_new_from_fd(fd, &dev);
 105  *      if (rc < 0) {
 106  *              fprintf(stderr, "Failed to init libevdev (%s)\n", strerror(-rc));
 107  *              exit(1);
 108  *      }
 109  *      printf("Input device name: \"%s\"\n", libevdev_get_name(dev));
 110  *      printf("Input device ID: bus %#x vendor %#x product %#x\n",
 111  *             libevdev_get_bustype(dev),
 112  *             libevdev_get_vendor_id(dev),
 113  *             libevdev_get_product_id(dev));
 114  *      if (!libevdev_has_event_type(dev, EV_REL) ||
 115  *          !libevdev_has_event_code(dev, EV_KEY, BTN_LEFT)) {
 116  *              printf("This device does not look like a mouse\n");
 117  *              exit(1);
 118  *      }
 119  *
 120  *      do {
 121  *              struct input_event ev;
 122  *              rc = libevdev_next_event(dev, LIBEVDEV_READ_NORMAL, &ev);
 123  *              if (rc == 0)
 124  *                      printf("Event: %s %s %d\n",
 125  *                             libevdev_get_event_type_name(ev.type),
 126  *                             libevdev_get_event_code_name(ev.type, ev.code),
 127  *                             ev.value);
 128  *      } while (rc == 1 || rc == 0 || rc == -EAGAIN);
 129  * @endcode
 130  *
 131  * A more complete example is available with the libevdev-events tool here:
 132  * http://cgit.freedesktop.org/libevdev/tree/tools/libevdev-events.c
 133  *
 134  * libevdev internal test suite
 135  * ============================
 136  *
 137  * libevdev's internal test suite uses the
 138  * [Check unit testing framework](http://check.sourceforge.net/). Tests are
 139  * divided into test suites and test cases. Most tests create a uinput device,
 140  * so you'll need to run as root.
 141  *
 142  * To run a specific suite only:
 143  *
 144  *     export CK_RUN_SUITE="suite name"
 145  *
 146  * To run a specific test case only:
 147  *
 148  *     export CK_RUN_TEST="test case name"
 149  *
 150  * To get a list of all suites or tests:
 151  *
 152  *     git grep "suite_create"
 153  *     git grep "tcase_create"
 154  *
 155  * By default, check forks, making debugging harder. Run gdb as below to avoid
 156  * forking.
 157  *
 158  *     sudo CK_FORK=no CK_RUN_TEST="test case name" gdb ./test/test-libevdev
 159  *
 160  * A special target `make gcov-report.txt` exists that runs gcov and leaves a
 161  * `libevdev.c.gcov` file. Check that for test coverage.
 162  *
 163  * `make check` is hooked up to run the test and gcov (again, needs root).
 164  *
 165  * The test suite creates a lot of devices, very quickly. Add the following
 166  * xorg.conf.d snippet to avoid the devices being added as X devices (at the
 167  * time of writing, mutter can't handle these devices and exits after getting
 168  * a BadDevice error).
 169  *
 170  *     $ cat /etc/X11/xorg.conf.d/99-ignore-libevdev-devices.conf
 171  *     Section "InputClass"
 172  *             Identifier "Ignore libevdev test devices"
 173  *             MatchProduct "libevdev test device"
 174  *             Option "Ignore" "on"
 175  *     EndSection
 176  *
 177  * License information
 178  * ===================
 179  * libevdev is licensed under the
 180  * [X11 license](http://cgit.freedesktop.org/libevdev/tree/COPYING).
 181  *
 182  * Reporting bugs
 183  * ==============
 184  * Please report bugs in the freedesktop.org bugzilla under the libevdev product:
 185  * https://bugs.freedesktop.org/enter_bug.cgi?product=libevdev
 186  */
 187
 188 /**
 189  * @defgroup init Initialization and setup
 190  *
 191  * Initialization, initial setup and file descriptor handling.
 192  * These functions are the main entry points for users of libevdev, usually a
 193  * caller will use this series of calls:
 194  *
 195  * @code
 196  * struct libevdev *dev;
 197  * int err;
 198  *
 199  * dev = libevdev_new();
 200  * if (!dev)
 201  *         return ENOSPC;
 202  *
 203  * err = libevdev_set_fd(dev, fd);
 204  * if (err < 0) {
 205  *         printf("Failed (errno %d): %s\n", -err, strerror(-err));
 206  *
 207  * libevdev_free(dev);
 208  * @endcode
 209  *
 210  * libevdev_set_fd() is the central call and initializes the internal structs
 211  * for the device at the given fd. libevdev functions will fail if called
 212  * before libevdev_set_fd() unless documented otherwise.
 213  */
 214
 215 /**
 216  * @defgroup bits Querying device capabilities
 217  *
 218  * Abstraction functions to handle device capabilities, specificially
 219  * device propeties such as the name of the device and the bits
 220  * representing the events suppported by this device.
 221  *
 222  * The logical state returned may lag behind the physical state of the device.
 223  * libevdev queries the device state on libevdev_set_fd() and then relies on
 224  * the caller to parse events through libevdev_next_fd(). If a caller does not
 225  * use libevdev_next_fd(), libevdev will not update the internal state of the
 226  * device and thus returns outdated values.
 227  */
 228
 229 /**
 230  * @defgroup mt Multi-touch related functions
 231  * Functions for querying multi-touch-related capabilities. MT devices
 232  * following the kernel protocol B (using ABS_MT_SLOT) provide multiple touch
 233  * points through so-called slots on the same axis. The slots are enumerated,
 234  * a client reading from the device will first get an ABS_MT_SLOT event, then
 235  * the values of axes changed in this slot. Multiple slots may be provided in
 236  * before an EV_SYN event.
 237  *
 238  * As with @ref bits, the logical state of the device as seen by the library
 239  * depends on the caller using libevdev_next_event().
 240  */
 241
 242 /**
 243  * @defgroup kernel Modifying the appearance or capabilities of the device
 244  *
 245  * Modifying the set of events reported by this device. By default, the
 246  * libevdev device mirrors the kernel device, enabling only those bits
 247  * exported by the kernel. This set of functions enable or disable bits as
 248  * seen from the caller.
 249  *
 250  * Enabling an event type or code does not affect event reporting - a
 251  * software-enabled event will not be generated by the physical hardware.
 252  * Disabling an event will prevent libevdev from routing such events to the
 253  * caller. Enabling and disabling event types and codes is at the library
 254  * level and thus only affects the caller.
 255  *
 256  * If an event type or code is enabled at kernel-level, future users of this
 257  * device will see this event enabled. Currently there is no option of
 258  * disabling an event type or code at kernel-level.
 259  */
 260
 261 /**
 262  * @defgroup misc Miscellaneous helper functions
 263  *
 264  * Functions for printing or querying event ranges. The list of names is
 265  * compiled into libevdev and will not change when the kernel changes. Adding
 266  * or removing names requires a re-compilation of libevdev. Likewise, the max
 267  * for each event type is compiled in and does not check the underlying
 268  * kernel.
 269  */
 270
 271 /**
 272  * @defgroup events Event handling
 273  *
 274  * Functions to handle events and fetch the current state of the event. Generally,
 275  * libevdev updates its internal state as the event is processed and forwarded
 276  * to the caller. Thus, the libevdev state of the device should always be identical
 277  * to the caller's state. It may however lag behind the actual state of the device.
 278  */
 279
 280 /**
 281  * @ingroup init
 282  *
 283  * Opaque struct representing an evdev device.
 284  */
 285 struct libevdev;
 286
 287 enum EvdevReadFlags {
 288         LIBEVDEV_READ_SYNC              = 1, /**< Process data in sync mode */
 289         LIBEVDEV_READ_NORMAL            = 2, /**< Process data in normal mode */
 290         LIBEVDEV_FORCE_SYNC             = 4, /**< Pretend the next event is a SYN_DROPPED. There is
 291                                                   no reason to ever use this except for
 292                                                   automated tests, so don't. */
 293         LIBEVDEV_READ_BLOCKING          = 8, /**< The fd is not in O_NONBLOCK and a read may block */
 294 };
 295
 296 /**
 297  * @ingroup init
 298  *
 299  * Initialize a new libevdev device. This function only allocates the
 300  * required memory and initializes the struct to sane default values.
 301  * To actually hook up the device to a kernel device, use
 302  * libevdev_set_fd().
 303  *
 304  * Memory allocated through libevdev_new() must be released by the
 305  * caller with libevdev_free().
 306  *
 307  * @see libevdev_set_fd
 308  * @see libevdev_free
 309  */
 310 struct libevdev* libevdev_new(void);
 311
 312 /**
 313  * @ingroup init
 314  *
 315  * Initialize a new libevdev device from the given fd.
 316  *
 317  * This is a shortcut for
 318  *
 319  * @code
 320  * int err;
 321  * struct libevdev *dev = libevdev_new();
 322  * err = libevdev_set_fd(dev, fd);
 323  * @endcode
 324  *
 325  * @param fd A file descriptor to the device in O_RDWR or O_RDONLY mode.
 326  * @param[out] dev The newly initialized evdev device.
 327  *
 328  * @return On success, zero is returned and dev is set to the newly
 329  * allocated struct. On failure, a negative errno is returned and the value
 330  * of dev is undefined.
 331  *
 332  * @see libevdev_free
 333  */
 334 int libevdev_new_from_fd(int fd, struct libevdev **dev);
 335
 336 /**
 337  * @ingroup init
 338  *
 339  * Clean up and free the libevdev struct. After completion, the <code>struct
 340  * libevdev</code> is invalid and must not be used.
 341  *
 342  * @param dev The evdev device
 343  *
 344  * @note This function may be called before libevdev_set_fd().
 345  */
 346 void libevdev_free(struct libevdev *dev);
 347
 348 /**
 349  * Logging function called by library-internal logging.
 350  * This function is expected to treat it's input like printf would.
 351  *
 352  * @param format printf-style format string
 353  * @param args List of arguments
 354  *
 355  * @see libevdev_set_log_handler
 356  */
 357 typedef void (*libevdev_log_func_t)(const char *format, va_list args);
 358
 359 /**
 360  * Set a printf-style logging handler for library-internal logging. The default
 361  * logging function is a noop.
 362  *
 363  * @param dev The evdev device
 364  * @param logfunc The logging function for this device. If NULL, the current
 365  * logging function is unset.
 366  *
 367  * @note This function may be called before libevdev_set_fd().
 368  */
 369 void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc);
 370
 371
 372 enum EvdevGrabModes {
 373         LIBEVDEV_GRAB = 3,
 374         LIBEVDEV_UNGRAB = 4,
 375 };
 376
 377 /**
 378  * Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other
 379  * clients (including kernel-internal ones such as rfkill) from receiving
 380  * events from this device.
 381  *
 382  * This is generally a bad idea. Don't do this.
 383  *
 384  * Grabbing an already grabbed device, or ungrabbing an ungrabbed device is
 385  * a noop and always succeeds.
 386  *
 387  * @param dev The evdev device, already initialized with libevdev_set_fd()
 388  * @param grab If true, grab the device. Otherwise ungrab the device.
 389  *
 390  * @return 0 if the device was successfull grabbed or ungrabbed, or a
 391  * negative errno in case of failure.
 392  */
 393 int libevdev_grab(struct libevdev *dev, int grab);
 394
 395 /**
 396  * @ingroup init
 397  *
 398  * Set the fd for this struct and initialize internal data.
 399  * The fd must be in O_RDONLY or O_RDWR mode.
 400  *
 401  * This function may only be called once per device. If the device changed and
 402  * you need to re-read a device, use libevdev_free() and libevdev_new(). If
 403  * you need to change the fd after closing and re-opening the same device, use
 404  * libevdev_change_fd().
 405  *
 406  * Unless otherwise specified, libevdev function behavior is undefined until
 407  * a successfull call to libevdev_set_fd().
 408  *
 409  * @param dev The evdev device
 410  * @param fd The file descriptor for the device
 411  *
 412  * @return 0 on success, or a negative error code on failure
 413  *
 414  * @see libevdev_change_fd
 415  * @see libevdev_new
 416  * @see libevdev_free
 417  */
 418 int libevdev_set_fd(struct libevdev* dev, int fd);
 419
 420 /**
 421  * @ingroup init
 422  *
 423  * Change the fd for this device, without re-reading the actual device. If the fd
 424  * changes after initializing the device, for example after a VT-switch in the
 425  * X.org X server, this function updates the internal fd to the newly opened.
 426  * No check is made that new fd points to the same device. If the device has
 427  * changed, libevdev's behavior is undefined.
 428  *
 429  * The fd may be open in O_RDONLY or O_RDWR.
 430  *
 431  * It is an error to call this function before calling libevdev_set_fd().
 432  *
 433  * @param dev The evdev device, already initialized with libevdev_set_fd()
 434  * @param fd The new fd
 435  *
 436  * @return 0 on success, or -1 on failure.
 437  *
 438  * @see libevdev_set_fd
 439  */
 440 int libevdev_change_fd(struct libevdev* dev, int fd);
 441
 442 /**
 443  * @param dev The evdev device
 444  *
 445  * @return The previously set fd, or -1 if none had been set previously.
 446  * @note This function may be called before libevdev_set_fd().
 447  */
 448 int libevdev_get_fd(const struct libevdev* dev);
 449
 450 /**
 451  * @ingroup events
 452  *
 453  * Get the next event from the device. This function operates in two different
 454  * modes: normal mode or sync mode.
 455  *
 456  * In normal mode, this function returns 0 and returns the event in the
 457  * parameter ev. If no events are available at this time, it returns -EAGAIN
 458  * and ev is undefined.
 459  *
 460  * If a SYN_DROPPED is read from the device, this function returns 1. The
 461  * caller should now call this function with the LIBEVDEV_READ_SYNC flag set,
 462  * to get the set of events that make up the device state delta. This function
 463  * returns 1 for each event part of that delta, until it returns -EAGAIN once
 464  * all events have been synced.
 465  *
 466  * If a device needs to be synced by the caller but the caller does not call
 467  * with the LIBEVDEV_READ_SYNC flag set, all events from the diff are dropped
 468  * and event processing continues as normal.
 469  *
 470  * @param dev The evdev device, already initialized with libevdev_set_fd()
 471  * @param flags Set of flags to determine behaviour. If LIBEVDEV_READ_NORMAL
 472  * is set, the next event is read in normal mode. If LIBEVDEV_READ_SYNC is
 473  * set, the next event is read in sync mode.
 474  * @param ev On success, set to the current event.
 475  * @return On failure, a negative errno is returned.
 476  * @retval 0 One or more events where read of the device
 477  * @retval -EAGAIN No events are currently available on the device
 478  * @retval 1 A SYN_DROPPED event was received, or a synced event was
 479  * returned.
 480  *
 481  * @note This function is signal-safe.
 482  */
 483 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev);
 484
 485 /**
 486  * @ingroup events
 487  *
 488  * Check if there are events waiting for us. This does not read an event off
 489  * the fd and may not access the fd at all. If there are events queued
 490  * internally this function will return non-zero. If the internal queue is empty,
 491  * this function will poll the file descriptor for data.
 492  *
 493  * This is a convenience function for simple processes, most complex programs
 494  * are expected to use select(2) or poll(2) on the file descriptor. The kernel
 495  * guarantees that if data is available, it is a multiple of sizeof(struct
 496  * input_event), and thus calling libevdev_next_event() when select(2) or
 497  * poll(2) return is safe. You do not need libevdev_has_event_pending() if
 498  * you're using select(2) or poll(2).
 499  *
 500  * @param dev The evdev device, already initialized with libevdev_set_fd()
 501  * @return On failure, a negative errno is returned.
 502  * @retval 0 No event is currently available
 503  * @retval 1 One or more events are available on the fd
 504  *
 505  * @note This function is signal-safe.
 506  */
 507 int libevdev_has_event_pending(struct libevdev *dev);
 508
 509 /**
 510  * @ingroup bits
 511  *
 512  * @param dev The evdev device, already initialized with libevdev_set_fd()
 513  *
 514  * @return The device name as read off the kernel device. The name is never
 515  * NULL but it may be the empty string.
 516  *
 517  * @note This function is signal-safe.
 518  */
 519 const char* libevdev_get_name(const struct libevdev *dev);
 520
 521 /**
 522  * @ingroup kernel
 523  *
 524  * @param dev The evdev device
 525  * @param name The new, non-NULL, name to assign to this device.
 526  *
 527  * @note This function may be called before libevdev_set_fd(). A call to
 528  * libevdev_set_fd() will overwrite any previously set value.
 529  */
 530 void libevdev_set_name(struct libevdev *dev, const char *name);
 531
 532 /**
 533  * @ingroup bits
 534  *
 535  * Virtual devices such as uinput devices have no phys location.
 536  *
 537  * @param dev The evdev device, already initialized with libevdev_set_fd()
 538  *
 539  * @return The physical location of this device, or NULL if there is none
 540  *
 541  * @note This function is signal safe.
 542  */
 543 const char * libevdev_get_phys(const struct libevdev *dev);
 544
 545 /**
 546  * @ingroup kernel
 547  *
 548  * @param dev The evdev device
 549  * @param phys The new, non-NULL, phys to assign to this device.
 550  *
 551  * @note This function may be called before libevdev_set_fd(). A call to
 552  * libevdev_set_fd() will overwrite any previously set value.
 553  */
 554 void libevdev_set_phys(struct libevdev *dev, const char *phys);
 555
 556 /**
 557  * @ingroup bits
 558  *
 559  * @param dev The evdev device, already initialized with libevdev_set_fd()
 560  *
 561  * @return The unique identifier for this device, or NULL if there is none
 562  *
 563  * @note This function is signal safe.
 564  */
 565 const char * libevdev_get_uniq(const struct libevdev *dev);
 566
 567 /**
 568  * @ingroup kernel
 569  *
 570  * @param dev The evdev device
 571  * @param uniq The new, non-NULL, uniq to assign to this device.
 572  *
 573  * @note This function may be called before libevdev_set_fd(). A call to
 574  * libevdev_set_fd() will overwrite any previously set value.
 575  */
 576 void libevdev_set_uniq(struct libevdev *dev, const char *uniq);
 577
 578 /**
 579  * @ingroup bits
 580  *
 581  * @param dev The evdev device, already initialized with libevdev_set_fd()
 582  *
 583  * @return The device's product ID
 584  *
 585  * @note This function is signal-safe.
 586  */
 587 int libevdev_get_id_product(const struct libevdev *dev);
 588
 589 /**
 590  * @ingroup kernel
 591  *
 592  * @param dev The evdev device
 593  * @param product_id The product ID to assign to this device
 594  *
 595  * @note This function may be called before libevdev_set_fd(). A call to
 596  * libevdev_set_fd() will overwrite any previously set value.
 597  */
 598 void libevdev_set_id_product(struct libevdev *dev, int product_id);
 599
 600 /**
 601  * @ingroup bits
 602  *
 603  * @param dev The evdev device, already initialized with libevdev_set_fd()
 604  *
 605  * @return The device's vendor ID
 606  *
 607  * @note This function is signal-safe.
 608  */
 609 int libevdev_get_id_vendor(const struct libevdev *dev);
 610
 611 /**
 612  * @ingroup kernel
 613  *
 614  * @param dev The evdev device
 615  * @param vendor_id The vendor ID to assign to this device
 616  *
 617  * @note This function may be called before libevdev_set_fd(). A call to
 618  * libevdev_set_fd() will overwrite any previously set value.
 619  */
 620 void libevdev_set_id_vendor(struct libevdev *dev, int vendor_id);
 621
 622 /**
 623  * @ingroup bits
 624  *
 625  * @param dev The evdev device, already initialized with libevdev_set_fd()
 626  *
 627  * @return The device's bus type
 628  *
 629  * @note This function is signal-safe.
 630  */
 631 int libevdev_get_id_bustype(const struct libevdev *dev);
 632
 633 /**
 634  * @ingroup kernel
 635  *
 636  * @param dev The evdev device
 637  * @param bustype The bustype to assign to this device
 638  *
 639  * @note This function may be called before libevdev_set_fd(). A call to
 640  * libevdev_set_fd() will overwrite any previously set value.
 641  */
 642 void libevdev_set_id_bustype(struct libevdev *dev, int bustype);
 643
 644 /**
 645  * @ingroup bits
 646  *
 647  * @param dev The evdev device, already initialized with libevdev_set_fd()
 648  *
 649  * @return The device's firmware version
 650  *
 651  * @note This function is signal-safe.
 652  */
 653 int libevdev_get_id_version(const struct libevdev *dev);
 654
 655 /**
 656  * @ingroup kernel
 657  *
 658  * @param dev The evdev device
 659  * @param version The version to assign to this device
 660  *
 661  * @note This function may be called before libevdev_set_fd(). A call to
 662  * libevdev_set_fd() will overwrite any previously set value.
 663  */
 664 void libevdev_set_id_version(struct libevdev *dev, int version);
 665
 666 /**
 667  * @ingroup bits
 668  *
 669  * @param dev The evdev device, already initialized with libevdev_set_fd()
 670  *
 671  * @return The driver version for this device
 672  *
 673  * @note This function is signal-safe.
 674  */
 675 int libevdev_get_driver_version(const struct libevdev *dev);
 676
 677 /**
 678  * @ingroup bits
 679  *
 680  * @param dev The evdev device, already initialized with libevdev_set_fd()
 681  * @param prop The input property to query for, one of INPUT_PROP_...
 682  *
 683  * @return 1 if the device provides this input property, or 0 otherwise.
 684  *
 685  * @note This function is signal-safe
 686  */
 687 int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
 688
 689 /**
 690  * @ingroup kernel
 691  *
 692  * @param dev The evdev device
 693  * @param prop The input property to enable, one of INPUT_PROP_...
 694  *
 695  * @return 0 on success or -1 on failure
 696  *
 697  * @note This function may be called before libevdev_set_fd(). A call to
 698  * libevdev_set_fd() will overwrite any previously set value.
 699  */
 700 int libevdev_enable_property(struct libevdev *dev, unsigned int prop);
 701
 702 /**
 703  * @ingroup bits
 704  *
 705  * @param dev The evdev device, already initialized with libevdev_set_fd()
 706  * @param type The event type to query for, one of EV_SYN, EV_REL, etc.
 707  *
 708  * @return 1 if the device supports this event type, or 0 otherwise.
 709  *
 710  * @note This function is signal-safe.
 711  */
 712 int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
 713
 714 /**
 715  * @ingroup bits
 716  *
 717  * @param dev The evdev device, already initialized with libevdev_set_fd()
 718  * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
 719  * @param code The event code to query for, one of ABS_X, REL_X, etc.
 720  *
 721  * @return 1 if the device supports this event type and code, or 0 otherwise.
 722  *
 723  * @note This function is signal-safe.
 724  */
 725 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code);
 726
 727 /**
 728  * @ingroup bits
 729  *
 730  * Get the minimum axis value for the given axis, as advertised by the kernel.
 731  *
 732  * @param dev The evdev device, already initialized with libevdev_set_fd()
 733  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 734  *
 735  * @return axis minimum for the given axis or 0 if the axis is invalid
 736  */
 737 int libevdev_get_abs_minimum(const struct libevdev *dev, unsigned int code);
 738 /**
 739  * @ingroup bits
 740  *
 741  * Get the maximum axis value for the given axis, as advertised by the kernel.
 742  *
 743  * @param dev The evdev device, already initialized with libevdev_set_fd()
 744  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 745  *
 746  * @return axis maximum for the given axis or 0 if the axis is invalid
 747  */
 748 int libevdev_get_abs_maximum(const struct libevdev *dev, unsigned int code);
 749 /**
 750  * @ingroup bits
 751  *
 752  * Get the axis fuzz for the given axis, as advertised by the kernel.
 753  *
 754  * @param dev The evdev device, already initialized with libevdev_set_fd()
 755  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 756  *
 757  * @return axis fuzz for the given axis or 0 if the axis is invalid
 758  */
 759 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code);
 760 /**
 761  * @ingroup bits
 762  *
 763  * Get the axis flat for the given axis, as advertised by the kernel.
 764  *
 765  * @param dev The evdev device, already initialized with libevdev_set_fd()
 766  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 767  *
 768  * @return axis flat for the given axis or 0 if the axis is invalid
 769  */
 770 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code);
 771 /**
 772  * @ingroup bits
 773  *
 774  * Get the axis resolution for the given axis, as advertised by the kernel.
 775  *
 776  * @param dev The evdev device, already initialized with libevdev_set_fd()
 777  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 778  *
 779  * @return axis resolution for the given axis or 0 if the axis is invalid
 780  */
 781 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code);
 782
 783 /**
 784  * @ingroup bits
 785  *
 786  * Get the axis info for the given axis, as advertised by the kernel.
 787  *
 788  * @param dev The evdev device, already initialized with libevdev_set_fd()
 789  * @param code The EV_ABS event code to query for, one of ABS_X, ABS_Y, etc.
 790  *
 791  * @return The input_absinfo for the given code, or NULL if the device does
 792  * not support this event code.
 793  */
 794 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code);
 795
 796 /**
 797  * @ingroup bits
 798  *
 799  * Behaviour of this function is undefined if the device does not provide
 800  * the event.
 801  *
 802  * @param dev The evdev device, already initialized with libevdev_set_fd()
 803  * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
 804  * @param code The event code to query for, one of ABS_X, REL_X, etc.
 805  *
 806  * @return The current value of the event.
 807  *
 808  * @note This function is signal-safe.
 809  * @note The value for ABS_MT_ events is undefined, use
 810  * libevdev_get_slot_value() instead
 811  *
 812  * @see libevdev_get_slot_value
 813  */
 814 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code);
 815
 816 /**
 817  * @ingroup bits
 818  *
 819  * Fetch the current value of the event type. This is a shortcut for
 820  *
 821  * @code
 822  *   if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
 823  *       val = libevdev_get_event_value(dev, t, c);
 824  * @endcode
 825  *
 826  * @param dev The evdev device, already initialized with libevdev_set_fd()
 827  * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
 828  * @param code The event code to query for, one of ABS_X, REL_X, etc.
 829  * @param[out] value The current value of this axis returned.
 830  *
 831  * @return If the device supports this event type and code, the return value is
 832  * non-zero and value is set to the current value of this axis. Otherwise,
 833  * zero is returned and value is unmodified.
 834  *
 835  * @note This function is signal-safe.
 836  * @note The value for ABS_MT_ events is undefined, use
 837  * libevdev_fetch_slot_value() instead
 838  *
 839  * @see libevdev_fetch_slot_value
 840  */
 841 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value);
 842
 843 /**
 844  * @ingroup mt
 845  *
 846  * Return the current value of the code for the given slot.
 847  *
 848  * The return value is undefined for a slot exceeding the available slots on
 849  * the device, for a code that is not in the permitted ABS_MT range or for a
 850  * device that does not have slots.
 851  *
 852  * @param dev The evdev device, already initialized with libevdev_set_fd()
 853  * @param slot The numerical slot number, must be smaller than the total number
 854  * of slots on this device
 855  * @param code The event code to query for, one of ABS_MT_POSITION_X, etc.
 856  *
 857  * @note This function is signal-safe.
 858  * @note The value for events other than ABS_MT_ is undefined, use
 859  * libevdev_fetch_value() instead
 860  *
 861  * @see libevdev_get_value
 862  */
 863 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code);
 864
 865 /**
 866  * @ingroup mt
 867  *
 868  * Fetch the current value of the code for the given slot. This is a shortcut for
 869  *
 870  * @code
 871  *   if (libevdev_has_event_type(dev, EV_ABS) &&
 872  *       libevdev_has_event_code(dev, EV_ABS, c) &&
 873  *       slot < device->number_of_slots)
 874  *       val = libevdev_get_slot_value(dev, slot, c);
 875  * @endcode
 876  *
 877  * @param dev The evdev device, already initialized with libevdev_set_fd()
 878  * @param slot The numerical slot number, must be smaller than the total number
 879  * of slots on this * device
 880  * @param[out] value The current value of this axis returned.
 881  *
 882  * @param code The event code to query for, one of ABS_MT_POSITION_X, etc.
 883  * @return If the device supports this event code, the return value is
 884  * non-zero and value is set to the current value of this axis. Otherwise, or
 885  * if the event code is not an ABS_MT_* event code, zero is returned and value
 886  * is unmodified.
 887  *
 888  * @note This function is signal-safe.
 889  */
 890 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
 891
 892 /**
 893  * @ingroup mt
 894  *
 895  * Get the number of slots supported by this device.
 896  *
 897  * @param dev The evdev device, already initialized with libevdev_set_fd()
 898  *
 899  * @return The number of slots supported, or -1 if the device does not provide
 900  * any slots
 901  *
 902  * @note A device may provide ABS_MT_SLOT but a total number of 0 slots. Hence
 903  * the return value of -1 for "device does not provide slots at all"
 904  */
 905 int libevdev_get_num_slots(const struct libevdev *dev);
 906
 907 /**
 908  * @ingroup mt
 909  *
 910  * Get the currently active slot. This may differ from the value
 911  * an ioctl may return at this time as events may have been read off the fd
 912  * since changing the slot value but those events are still in the buffer
 913  * waiting to be processed. The returned value is the value a caller would
 914  * see if it were to process events manually one-by-one.
 915  *
 916  * @param dev The evdev device, already initialized with libevdev_set_fd()
 917  *
 918  * @return the currently active slot (logically)
 919  */
 920 int libevdev_get_current_slot(const struct libevdev *dev);
 921
 922 /**
 923  * @ingroup kernel
 924  *
 925  * Change the minimum for the given EV_ABS event code, if the code exists.
 926  * This function has no effect if libevdev_has_event_code() returns false for
 927  * this code.
 928  */
 929 void libevdev_set_abs_minimum(struct libevdev *dev, unsigned int code, int min);
 930
 931 /**
 932  * @ingroup kernel
 933  *
 934  * Change the maximum for the given EV_ABS event code, if the code exists.
 935  * This function has no effect if libevdev_has_event_code() returns false for
 936  * this code.
 937  */
 938 void libevdev_set_abs_maximum(struct libevdev *dev, unsigned int code, int max);
 939
 940 /**
 941  * @ingroup kernel
 942  *
 943  * Change the fuzz for the given EV_ABS event code, if the code exists.
 944  * This function has no effect if libevdev_has_event_code() returns false for
 945  * this code.
 946  */
 947 void libevdev_set_abs_fuzz(struct libevdev *dev, unsigned int code, int fuzz);
 948
 949 /**
 950  * @ingroup kernel
 951  *
 952  * Change the flat for the given EV_ABS event code, if the code exists.
 953  * This function has no effect if libevdev_has_event_code() returns false for
 954  * this code.
 955  */
 956 void libevdev_set_abs_flat(struct libevdev *dev, unsigned int code, int flat);
 957
 958 /**
 959  * @ingroup kernel
 960  *
 961  * Change the resolution for the given EV_ABS event code, if the code exists.
 962  * This function has no effect if libevdev_has_event_code() returns false for
 963  * this code.
 964  */
 965 void libevdev_set_abs_resolution(struct libevdev *dev, unsigned int code, int resolution);
 966
 967 /**
 968  * @ingroup kernel
 969  *
 970  * Change the abs info for the given EV_ABS event code, if the code exists.
 971  * This function has no effect if libevdev_has_event_code() returns false for
 972  * this code.
 973  */
 974 void libevdev_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
 975
 976 /**
 977  * @ingroup kernel
 978  *
 979  * Forcibly enable an event type on this device, even if the underlying
 980  * device does not support it. While this cannot make the device actually
 981  * report such events, it will now return true for libevdev_has_event_type().
 982  *
 983  * This is a local modification only affecting only this representation of
 984  * this device.
 985  *
 986  * @param dev The evdev device, already initialized with libevdev_set_fd()
 987  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 988  *
 989  * @return 0 on success or -1 otherwise
 990  *
 991  * @see libevdev_has_event_type
 992  */
 993 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
 994
 995 /**
 996  * @ingroup kernel
 997  *
 998  * Forcibly disable an event type on this device, even if the underlying
 999  * device provides it. This effectively mutes the respective set of
1000  * events. libevdev will filter any events matching this type and none will
1001  * reach the caller. libevdev_has_event_type() will return false for this
1002  * type.
1003  *
1004  * In most cases, a caller likely only wants to disable a single code, not
1005  * the whole type. Use libevdev_disable_event_code() for that.
1006  *
1007  * Disabling EV_SYN will not work. Don't shoot yourself in the foot.
1008  * It hurts.
1009  *
1010  * This is a local modification only affecting only this representation of
1011  * this device.
1012  *
1013  * @param dev The evdev device, already initialized with libevdev_set_fd()
1014  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
1015  *
1016  * @return 0 on success or -1 otherwise
1017  *
1018  * @see libevdev_has_event_type
1019  * @see libevdev_disable_event_type
1020  */
1021 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
1022
1023 /**
1024  * @ingroup kernel
1025  *
1026  * Forcibly enable an event type on this device, even if the underlying
1027  * device does not support it. While this cannot make the device actually
1028  * report such events, it will now return true for libevdev_has_event_code().
1029  *
1030  * The last argument depends on the type and code:
1031  * - If type is EV_ABS, data must be a pointer to a struct input_absinfo
1032  * containing the data for this axis.
1033  * - For all other types, the argument must be NULL.
1034  *
1035  * This function calls libevdev_enable_event_type() if necessary.
1036  *
1037  * This is a local modification only affecting only this representation of
1038  * this device.
1039  *
1040  * @param dev The evdev device, already initialized with libevdev_set_fd()
1041  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
1042  * @param code The event code to enable (ABS_X, REL_X, etc.)
1043  * @param data If type is EV_ABS, data points to a struct input_absinfo. If type is EV_REP, data
1044  * points to an integer. Otherwise, data must be NULL.
1045  *
1046  * @return 0 on success or -1 otherwise
1047  *
1048  * @see libevdev_enable_event_type
1049  */
1050 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
1051
1052 /**
1053  * @ingroup kernel
1054  *
1055  * Forcibly disable an event code on this device, even if the underlying
1056  * device provides it. This effectively mutes the respective set of
1057  * events. libevdev will filter any events matching this type and code and
1058  * none will reach the caller. libevdev_has_event_code() will return false for
1059  * this code.
1060  *
1061  * Disabling all event codes for a given type will not disable the event
1062  * type. Use libevdev_disable_event_type() for that.
1063  *
1064  * This is a local modification only affecting only this representation of
1065  * this device.
1066  *
1067  * Disabling EV_SYN will not work. Don't shoot yourself in the foot.
1068  * It hurts.
1069  *
1070  * @param dev The evdev device, already initialized with libevdev_set_fd()
1071  * @param type The event type to disable (EV_ABS, EV_KEY, ...)
1072  * @param code The event code to disable (ABS_X, REL_X, etc.)
1073  *
1074  * @return 0 on success or -1 otherwise
1075  *
1076  * @see libevdev_has_event_code
1077  * @see libevdev_disable_event_type
1078  */
1079 int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code);
1080
1081 /**
1082  * @ingroup kernel
1083  *
1084  * Set the device's EV_ABS axis to the value defined in the abs
1085  * parameter. This will be written to the kernel.
1086  *
1087  * @param dev The evdev device, already initialized with libevdev_set_fd()
1088  * @param code The EV_ABS event code to modify, one of ABS_X, ABS_Y, etc.
1089  * @param abs Axis info to set the kernel axis to
1090  *
1091  * @return zero on success, or a negative errno on failure
1092  *
1093  * @see libevdev_enable_event_code
1094  */
1095 int libevdev_kernel_set_abs_info(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
1096
1097 /**
1098  * @ingroup misc
1099  *
1100  * Helper function to check if an event is of a specific type. This is
1101  * virtually the same as:
1102  *
1103  *      ev->type == type
1104  *
1105  * with the exception that some sanity checks are performed to ensure type
1106  * is valid.
1107  *
1108  * @param ev The input event to check
1109  * @param type Input event type to compare the event against (EV_REL, EV_ABS,
1110  * etc.)
1111  *
1112  * @return 1 if the event type matches the given type, 0 otherwise (or if
1113  * type is invalid)
1114  */
1115 int libevdev_is_event_type(const struct input_event *ev, unsigned int type);
1116
1117 /**
1118  * @ingroup misc
1119  *
1120  * Helper function to check if an event is of a specific type and code. This
1121  * is virtually the same as:
1122  *
1123  *      ev->type == type && ev->code == code
1124  *
1125  * with the exception that some sanity checks are performed to ensure type and
1126  * code are valid.
1127  *
1128  * @param ev The input event to check
1129  * @param type Input event type to compare the event against (EV_REL, EV_ABS,
1130  * etc.)
1131  * @param code Input event code to compare the event against (ABS_X, REL_X,
1132  * etc.)
1133  *
1134  * @return 1 if the event type matches the given type and code, 0 otherwise
1135  * (or if type/code are invalid)
1136  */
1137 int libevdev_is_event_code(const struct input_event *ev, unsigned int type, unsigned int code);
1138
1139 /**
1140  * @ingroup misc
1141  *
1142  * @param type The event type to return the name for.
1143  *
1144  * @return The name of the given event type (e.g. EV_ABS) or NULL for an
1145  * invalid type
1146  *
1147  * @note The list of names is compiled into libevdev. If the kernel adds new
1148  * defines for new properties libevdev will not automatically pick these up.
1149  */
1150 const char * libevdev_get_event_type_name(unsigned int type);
1151 /**
1152  * @ingroup misc
1153  *
1154  * @param type The event type for the code to query (EV_SYN, EV_REL, etc.)
1155  * @param code The event code to return the name for (e.g. ABS_X)
1156  *
1157  * @return The name of the given event code (e.g. ABS_X) or NULL for an
1158  * invalid type or code
1159  *
1160  * @note The list of names is compiled into libevdev. If the kernel adds new
1161  * defines for new properties libevdev will not automatically pick these up.
1162  */
1163 const char * libevdev_get_event_code_name(unsigned int type, unsigned int code);
1164
1165 /**
1166  * @ingroup misc
1167  *
1168  * @param prop The input prop to return the name for (e.g. INPUT_PROP_BUTTONPAD)
1169  *
1170  * @return The name of the given input prop (e.g. INPUT_PROP_BUTTONPAD) or NULL for an
1171  * invalid property
1172  *
1173  * @note The list of names is compiled into libevdev. If the kernel adds new
1174  * defines for new properties libevdev will not automatically pick these up.
1175  * @note On older kernels input properties may not be defined and
1176  * libevdev_get_input_prop_name() will always return NULL
1177  */
1178 const char* libevdev_get_property_name(unsigned int prop);
1179
1180 /**
1181  * @ingroup misc
1182  *
1183  * @param type The event type to return the maximum for (EV_ABS, EV_REL, etc.). No max is defined for
1184  * EV_SYN.
1185  *
1186  * @return The max value defined for the given event type, e.g. ABS_MAX for a type of EV_ABS, or -1
1187  * for an invalid type.
1188  *
1189  * @note The max value is compiled into libevdev. If the kernel changes the
1190  * max value, libevdev will not automatically pick these up.
1191  */
1192 int libevdev_get_event_type_max(unsigned int type);
1193
1194 /**
1195  * @ingroup bits
1196  *
1197  * Get the repeat delay and repeat period values for this device.
1198  *
1199  * @param dev The evdev device, already initialized with libevdev_set_fd()
1200  * @param delay If not null, set to the repeat delay value
1201  * @param period If not null, set to the repeat period value
1202  *
1203  * @return 0 on success, -1 if this device does not have repeat settings.
1204  *
1205  * @note This function is signal-safe
1206  */
1207 int libevdev_get_repeat(struct libevdev *dev, int *delay, int *period);
1208
1209
1210 /********* DEPRECATED SECTION *********/
1211 #if defined(__GNUC__) && __GNUC__ >= 4
1212 #define LIBEVDEV_DEPRECATED __attribute__ ((deprecated))
1213 #else
1214 #define LIBEVDEV_DEPRECATED
1215 #endif
1216
1217 /* replacement: libevdev_get_abs_minimum */
1218 int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code) LIBEVDEV_DEPRECATED;
1219 /* replacement: libevdev_get_abs_maximum */
1220 int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code) LIBEVDEV_DEPRECATED;
1221
1222 /* replacement: libevdev_get_property_name */
1223 const char* libevdev_get_input_prop_name(unsigned int prop) LIBEVDEV_DEPRECATED;
1224
1225 int libevdev_get_product_id(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1226 int libevdev_get_vendor_id(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1227 int libevdev_get_bustype(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1228 int libevdev_get_version(const struct libevdev *dev) LIBEVDEV_DEPRECATED;
1229
1230 /* replacement: libevdev_kernel_set_abs_info */
1231 int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs) LIBEVDEV_DEPRECATED;
1232
1233
1234 /**************************************/
1235 #endif /* LIBEVDEV_H */