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
  29 struct libevdev;
  30
  31 enum EvdevReadFlags {
  32     ER_SINGLE           = 1, /**< Read until including the first EV_SYN or EAGAIN */
  33     ER_SYNC             = 2, /**< Process data in sync mode */
  34     ER_ALL              = 4, /**< Read until EAGAIN */
  35 };
  36
  37
  38 /**
  39  * Initialize a new libevdev struct.
  40  *
  41  * @param fd If fd >= 0, the device is initialised for the fd. Otherwise, a
  42  * caller must call evdev_set_fd() before attempting to read events.
  43  *
  44  * @see libevdev_set_fd
  45  */
  46 struct libevdev* libevdev_new(int fd);
  47
  48 /**
  49  * Clean up and free the libevdev struct.
  50  *
  51  * @note This function may be called before libevdev_set_fd.
  52  */
  53 void libevdev_free(struct libevdev *dev);
  54
  55 /**
  56  * Logging function called by library-internal logging.
  57  * This function is expected to treat it's input like printf would.
  58  *
  59  * @param format printf-style format string
  60  * @param args List of arguments
  61  *
  62  * @see libevdev_set_log_handler
  63  */
  64 typedef void (*libevdev_log_func_t)(const char *format, va_list args);
  65
  66 /**
  67  * Set a printf-style logging handler for library-internal logging.
  68  *
  69  * @note This function may be called before libevdev_set_fd.
  70  */
  71 void libevdev_set_log_handler(struct libevdev *dev, libevdev_log_func_t logfunc);
  72
  73 /**
  74  * Grab or ungrab the device through a kernel EVIOCGRAB. This prevents other
  75  * clients (including kernel-internal ones such as rfkill) from receiving
  76  * events from this device.
  77  *
  78  * This is generally a bad idea. Don't do this.
  79  *
  80  * Grabbing an already grabbed device, or ungrabbing an ungrabbed device is
  81  * a noop and always succeeds.
  82  *
  83  * @param grab If true, grab the device. Otherwise ungrab the device.
  84  *
  85  * @return 0 if the device was successfull grabbed or ungrabbed, or a
  86  * negative errno in case of failure.
  87  */
  88 int libevdev_grab(struct libevdev *dev, int grab);
  89
  90 /**
  91  * Set the fd for this struct and initialize internal data.
  92  * The fd must be open for reading and ioctl.
  93  *
  94  * This function may only be called once per device. If you need to re-read
  95  * a device, use libevdev_free and libevdev_new. If you need to change the
  96  * fd, use libevdev_change_fd.
  97  *
  98  * Unless otherwise specified, libevdev function behavior is undefined until
  99  * a successfull call to libevdev_set_fd.
 100  *
 101  * @param fd The file descriptor for the device
 102  *
 103  * @return 0 on success, or a negative error code on failure
 104  *
 105  * @see libevdev_change_fd
 106  * @see libevdev_new
 107  * @see libevdev_free
 108  */
 109 int libevdev_set_fd(struct libevdev* dev, int fd);
 110
 111 /**
 112  * Change the fd for this device, without re-reading the actual device.
 113  *
 114  * It is an error to call this function before calling libevdev_set_fd.
 115  *
 116  * @param fd The new fd
 117  *
 118  * @return 0 on success, or -1 on failure.
 119  *
 120  * @see libevdev_set_fd
 121  */
 122 int libevdev_change_fd(struct libevdev* dev, int fd);
 123
 124 /**
 125  *
 126  * @return The previously set fd, or -1 if none had been set previously.
 127  * @note This function may be called before libevdev_set_fd.
 128  */
 129 int libevdev_get_fd(const struct libevdev* dev);
 130
 131 /**
 132  * Get the next event from the device.
 133  *
 134  * In normal mode, this function returns 0 and returns the event in the
 135  * parameter ev. If no events are available at this time, it returns -EAGAIN
 136  * and ev is undefined.
 137  *
 138  * If a SYN_DROPPED is read from the device, this function returns 1. The
 139  * caller should now call this function with the ER_SYNC flag set, to get
 140  * the set of events that make up the device state diff. This function
 141  * returns 1 for each event part of that diff, until it returns -EAGAIN once
 142  * all events have been synced.
 143  *
 144  * If a device needs to be synced by the caller but the caller does not call
 145  * with the ER_SYNC flag set, all events from the diff are dropped and event
 146  * processing continues as normal.
 147  *
 148  * @return On failure, a negative errno is returned.
 149  * @retval 0 One or more events where read of the device
 150  * @retval -EAGAIN No events are currently available on the device
 151  * @retval 1 A SYN_DROPPED event was received, or a synced event was
 152  * returned.
 153  *
 154  * @note This function is signal-safe.
 155  */
 156 int libevdev_next_event(struct libevdev *dev, unsigned int flags, struct input_event *ev);
 157
 158 /**
 159  * @return The device name as read off the kernel device
 160  *
 161  * @note This function is signal-safe.
 162  */
 163 const char* libevdev_get_name(const struct libevdev *dev);
 164
 165 /**
 166  * @return The device's product ID
 167  *
 168  * @note This function is signal-safe.
 169  */
 170 int libevdev_get_pid(const struct libevdev *dev);
 171 /**
 172  * @return The device's vendor ID
 173  *
 174  * @note This function is signal-safe.
 175  */
 176 int libevdev_get_vid(const struct libevdev *dev);
 177
 178 /**
 179  * @return The device's bus type
 180  *
 181  * @note This function is signal-safe.
 182  */
 183 int libevdev_get_bustype(const struct libevdev *dev);
 184
 185 /**
 186  * @return 1 if the device supports this event type, or 0 otherwise.
 187  *
 188  * @note This function is signal-safe
 189  */
 190 int libevdev_has_property(const struct libevdev *dev, unsigned int prop);
 191
 192 /**
 193  * @return 1 if the device supports this event type, or 0 otherwise.
 194  *
 195  * @note This function is signal-safe.
 196  */
 197 int libevdev_has_event_type(const struct libevdev *dev, unsigned int type);
 198
 199 /**
 200  * @return 1 if the device supports this event type, or 0 otherwise.
 201  *
 202  * @note This function is signal-safe.
 203  */
 204 int libevdev_has_event_code(const struct libevdev *dev, unsigned int type, unsigned int code);
 205
 206 /**
 207  * @return axis minimum for the given axis or 0 if the axis is invalid
 208  */
 209 int libevdev_get_abs_min(const struct libevdev *dev, unsigned int code);
 210 /**
 211  * @return axis maximum for the given axis or 0 if the axis is invalid
 212  */
 213 int libevdev_get_abs_max(const struct libevdev *dev, unsigned int code);
 214 /**
 215  * @return axis fuzz for the given axis or 0 if the axis is invalid
 216  */
 217 int libevdev_get_abs_fuzz(const struct libevdev *dev, unsigned int code);
 218 /**
 219  * @return axis flat for the given axis or 0 if the axis is invalid
 220  */
 221 int libevdev_get_abs_flat(const struct libevdev *dev, unsigned int code);
 222 /**
 223  * @return axis resolution for the given axis or 0 if the axis is invalid
 224  */
 225 int libevdev_get_abs_resolution(const struct libevdev *dev, unsigned int code);
 226
 227 /**
 228  * @return The input_absinfo for the given code, or NULL if the device does
 229  * not support this event code.
 230  */
 231 const struct input_absinfo* libevdev_get_abs_info(const struct libevdev *dev, unsigned int code);
 232
 233 /**
 234  * Behaviour of this function is undefined if the device does not provide
 235  * the event.
 236  *
 237  * @return The current value of the event.
 238  *
 239  * @note This function is signal-safe.
 240  * @note The value for ABS_MT_ events is undefined, use
 241  * libevdev_get_slot_value instead
 242  *
 243  * @see libevdev_get_slot_value
 244  */
 245 int libevdev_get_event_value(const struct libevdev *dev, unsigned int type, unsigned int code);
 246
 247 /**
 248  * Fetch the current value of the event type. This is a shortcut for
 249  *
 250  * <pre>
 251  *   if (libevdev_has_event_type(dev, t) && libevdev_has_event_code(dev, t, c))
 252  *       val = libevdev_get_event_value(dev, t, c);
 253  * </pre>
 254  *
 255  * @return non-zero if the device supports this event code, or zero
 256  * otherwise. On return of zero, value is unmodified.
 257  *
 258  * @note This function is signal-safe.
 259  * @note The value for ABS_MT_ events is undefined, use
 260  * libevdev_fetch_slot_value instead
 261  *
 262  * @see libevdev_fetch_slot_value
 263  */
 264 int libevdev_fetch_event_value(const struct libevdev *dev, unsigned int type, unsigned int code, int *value);
 265
 266 /**
 267  * Return the current value of the code for the given slot.
 268  *
 269  * The return value is undefined for a slot exceeding the available slots on
 270  * the device, or for a device that does not have slots.
 271  *
 272  * @note This function is signal-safe.
 273  * @note The value for events other than ABS_MT_ is undefined, use
 274  * libevdev_fetch_value instead
 275  *
 276  * @see libevdev_get_value
 277  */
 278 int libevdev_get_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code);
 279
 280 /**
 281  * Fetch the current value of the code for the given slot. This is a shortcut for
 282  *
 283  * <pre>
 284  *   if (libevdev_has_event_type(dev, EV_ABS) &&
 285  *       libevdev_has_event_code(dev, EV_ABS, c) &&
 286  *       slot < device->number_of_slots)
 287  *       val = libevdev_get_slot_value(dev, slot, c);
 288  * </pre>
 289  *
 290  * @return non-zero if the device supports this event code, or zero
 291  * otherwise. On return of zero, value is unmodified.
 292  *
 293  * @note This function is signal-safe.
 294  * @note The value for ABS_MT_ events is undefined, use
 295  * libevdev_fetch_slot_value instead
 296  *
 297  * @see libevdev_fetch_slot_value
 298  */
 299 int libevdev_fetch_slot_value(const struct libevdev *dev, unsigned int slot, unsigned int code, int *value);
 300
 301 /**
 302  * Get the number of slots supported by this device.
 303  *
 304  * Note that the slot offset may be non-zero, use libevdev_get_abs_min() or
 305  * libevdev_get_abs_info() to get the minimum slot number.
 306  *
 307  * @return The number of slots supported, or -1
 308  */
 309 int libevdev_get_num_slots(const struct libevdev *dev);
 310
 311 /**
 312  * Get the currently active slot. This may differ from the value
 313  * an ioctl may return at this time as events may have been read off the fd
 314  * since changing the slot value but those events are still in the buffer
 315  * waiting to be processed. The returned value is the value a caller would
 316  * see if it were to process events manually one-by-one.
 317  *
 318  * @return the currently active slot (logically)
 319  */
 320 int libevdev_get_current_slot(const struct libevdev *dev);
 321
 322 /**
 323  * Forcibly enable an event type on this device, even if the underlying
 324  * device does not support it. While this cannot make the device actually
 325  * report such events, it will now return true for libevdev_has_event_type.
 326  *
 327  * This is a local modification only affecting only this process and only
 328  * this device.
 329  *
 330  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 331  *
 332  * @return 0 on success or -1 otherwise
 333  *
 334  * @see libevdev_has_event_type
 335  */
 336 int libevdev_enable_event_type(struct libevdev *dev, unsigned int type);
 337
 338 /**
 339  * Forcibly disable an event type on this device, even if the underlying
 340  * device provides it, effectively muting all keys or axes. libevdev will
 341  * filter any events matching this type and none will reach the caller.
 342  * libevdev_has_event_type will return false for this type.
 343  *
 344  * In most cases, a caller likely only wants to disable a single code, not
 345  * the whole type. Use libevdev_disable_event_code for that.
 346  *
 347  * This is a local modification only affecting only this process and only
 348  * this device.
 349  *
 350  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 351  *
 352  * @return 0 on success or -1 otherwise
 353  *
 354  * @see libevdev_has_event_type
 355  * @see libevdev_disable_event_type
 356  */
 357 int libevdev_disable_event_type(struct libevdev *dev, unsigned int type);
 358
 359 /**
 360  * Forcibly enable an event type on this device, even if the underlying
 361  * device does not support it. While this cannot make the device actually
 362  * report such events, it will now return true for libevdev_has_event_code.
 363  *
 364  * The last argument depends on the type and code:
 365  * - If type is EV_ABS, the vararg must be a pointer to a struct input_absinfo
 366  * containing the data for this axis.
 367  * - For all other types, the argument is ignored.
 368  *
 369  * This function calls libevdev_enable_event_type if necessary.
 370  *
 371  * This is a local modification only affecting only this process and only
 372  * this device.
 373  *
 374  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 375  * @param code The event code to enable (ABS_X, REL_X, etc.)
 376  * @param data Axis/key data, depending on type and code
 377  *
 378  * @return 0 on success or -1 otherwise
 379  *
 380  * @see libevdev_enable_event_type
 381  */
 382 int libevdev_enable_event_code(struct libevdev *dev, unsigned int type, unsigned int code, const void *data);
 383
 384 /**
 385  * Forcibly disable an event code on this device, even if the underlying
 386  * device provides it, effectively muting this key or axis. libevdev will
 387  * filter any events matching this type and code and none will reach the
 388  * caller.
 389  * libevdev_has_event_code will return false for this code combination.
 390  *
 391  * Disabling all event codes for a given type will not disable the event
 392  * type. Use libevdev_disable_event_type for that.
 393  *
 394  * This is a local modification only affecting only this process and only
 395  * this device.
 396  *
 397  * @param type The event type to enable (EV_ABS, EV_KEY, ...)
 398  * @param code The event code to enable (ABS_X, REL_X, etc.)
 399  *
 400  * @return 0 on success or -1 otherwise
 401  *
 402  * @see libevdev_has_event_code
 403  * @see libevdev_disable_event_type
 404  */
 405 int libevdev_disable_event_code(struct libevdev *dev, unsigned int type, unsigned int code);
 406
 407 /**
 408  * Set the device's EV_ABS/<code> axis to the value defined in the abs
 409  * parameter. This will be written to the kernel.
 410  *
 411  * @return zero on success, or a negative errno on failure
 412  *
 413  * @see libevdev_enable_event_code
 414  */
 415 int libevdev_kernel_set_abs_value(struct libevdev *dev, unsigned int code, const struct input_absinfo *abs);
 416
 417 #endif /* libevdev_H */