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