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