libevdev/libevdev-uinput.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_UINPUT_H
  24 #define LIBEVDEV_UINPUT_H
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 #include <libevdev/libevdev.h>
  31
  32 struct libevdev_uinput;
  33
  34 /**
  35  * @defgroup uinput uinput device creation
  36  *
  37  * Creation of uinput devices based on existing libevdev devices. These functions
  38  * help to create uinput devices that emulate libevdev devices. In the simplest
  39  * form it serves to duplicate an existing device:
  40  *
  41  * @code
  42  * int err;
  43  * int new_fd;
  44  * struct libevdev *dev;
  45  * struct libevdev_uinput *uidev;
  46  * struct input_event ev[2];
  47  *
  48  * err = libevdev_new_from_fd(&dev, fd);
  49  * if (err != 0)
  50  *     return err;
  51  *
  52  * uifd = open("/dev/uinput", O_RDWR);
  53  * if (uidev < 0)
  54  *     return -errno;
  55  *
  56  * err = libevdev_uinput_create_from_device(dev, uifd, &uidev);
  57  * if (err != 0)
  58  *     return err;
  59  *
  60  * // post a REL_X event
  61  * err = libevdev_uinput_write_event(uidev, EV_REL, REL_X, -1);
  62  * if (err != 0)
  63  *     return err;
  64  * libevdev_uinput_write_event(uidev, EV_SYN, SYN_REPORT, 0);
  65  * if (err != 0)
  66  *     return err;
  67  *
  68  * libevdev_uinput_destroy(uidev);
  69  * close(uifd);
  70  *
  71  * @endcode
  72  *
  73  * Alternatively, a device can be constructed from scratch:
  74  *
  75  * @code
  76  * int err;
  77  * struct libevdev *dev;
  78  * struct libevdev_uinput *uidev;
  79  *
  80  * dev = libevdev_new();
  81  * libevdev_set_name(dev, "test device");
  82  * libevdev_enable_event_type(dev, EV_REL);
  83  * libevdev_enable_event_code(dev, EV_REL, REL_X);
  84  * libevdev_enable_event_code(dev, EV_REL, REL_Y);
  85  * libevdev_enable_event_type(dev, EV_KEY);
  86  * libevdev_enable_event_code(dev, EV_KEY, BTN_LEFT);
  87  * libevdev_enable_event_code(dev, EV_KEY, BTN_MIDDLE);
  88  * libevdev_enable_event_code(dev, EV_KEY, BTN_RIGHT);
  89  *
  90  * err = libevdev_uinput_create_from_device(dev,
  91  *                                          LIBEVDEV_UINPUT_OPEN_MANAGED,
  92  *                                          &uidev);
  93  * if (err != 0)
  94  *     return err;
  95  *
  96  * // ... do something ...
  97  *
  98  * libevdev_uinput_destroy(uidev);
  99  *
 100  * @endcode
 101  */
 102
 103 enum libevdev_uinput_open_mode {
 104         /* intentionally -2 to avoid to avoid code like the below from accidentally working:
 105                 fd = open("/dev/uinput", O_RDWR); // fails, fd is -1
 106                 libevdev_uinput_create_from_device(dev, fd, &uidev); // may hide the error */
 107         LIBEVDEV_UINPUT_OPEN_MANAGED = -2, /**< let libevdev open and close @c /dev/uinput */
 108 };
 109
 110 /**
 111  * @ingroup uinput
 112  *
 113  * Create a uinput device based on the libevdev device given. The uinput device
 114  * will be an exact copy of the libevdev device, minus the bits that uinput doesn't
 115  * allow to be set.
 116  *
 117  * If uinput_fd is LIBEVDEV_UINPUT_OPEN_MANAGED, libevdev_uinput_create_from_device()
 118  * will open @c /dev/uinput in read/write mode and manage the file descriptor.
 119  * Otherwise, uinput_fd must be opened by the caller and opened with the
 120  * appropriate permissions.
 121  *
 122  * The device's lifetime is tied to the uinput file descriptor, closing it will
 123  * destroy the uinput device. You should call libevdev_uinput_destroy() before
 124  * closing the file descriptor to free allocated resources.
 125  * A file descriptor can only create one uinput device at a time; the second device
 126  * will fail with -EINVAL.
 127  *
 128  * You don't need to keep the file descriptor variable around,
 129  * libevdev_uinput_get_fd() will return it when needed.
 130  *
 131  * @note Due to limitations in the uinput kernel module, REP_DELAY and
 132  * REP_PERIOD will default to the kernel defaults, not to the ones set in the
 133  * source device.
 134  *
 135  * @param dev The device to duplicate
 136  * @param uinput_fd LIBEVDEV_UINPUT_OPEN_MANAGED or a file descriptor to @c /dev/uinput,
 137  * @param[out] uinput_dev The newly created libevdev device.
 138  *
 139  * @return 0 on success or a negative errno on failure. On failure, the value of
 140  * uinput_dev is unmodified.
 141  *
 142  * @see libevdev_uinput_destroy
 143  */
 144 int libevdev_uinput_create_from_device(const struct libevdev *dev,
 145                                        int uinput_fd,
 146                                        struct libevdev_uinput **uinput_dev);
 147
 148 /**
 149  * @ingroup uinput
 150  *
 151  * Destroy a previously created uinput device and free associated memory.
 152  *
 153  * If the device was opened with LIBEVDEV_UINPUT_OPEN_MANAGED, libevdev_uinput_destroy()
 154  * also closes the file descriptor. Otherwise, the fd is left as-is and
 155  * must be closed by the caller.
 156  *
 157  * @param uinput_dev A previously created uinput device.
 158  *
 159  * @return 0 on success or a negative errno on failure
 160  */
 161 void libevdev_uinput_destroy(struct libevdev_uinput *uinput_dev);
 162
 163 /**
 164  * @ingroup uinput
 165  *
 166  * Return the file descriptor used to create this uinput device. This is the
 167  * fd pointing to <strong>/dev/uinput</strong>. This file descriptor may be used to write
 168  * events that are emitted by the uinput device.
 169  * Closing this file descriptor will destroy the uinput device, you should
 170  * call libevdev_uinput_destroy() first to free allocated resources.
 171  *
 172  * @param uinput_dev A previously created uinput device.
 173  *
 174  * @return The file descriptor used to create this device
 175  */
 176 int libevdev_uinput_get_fd(const struct libevdev_uinput *uinput_dev);
 177
 178 /**
 179  * @ingroup uinput
 180  *
 181  * Return the syspath representing this uinput device.
 182  * As of 3.11, the uinput kernel device does not
 183  * provide a way to get the syspath directly through uinput so libevdev must guess.
 184  * In some cases libevdev is unable to derive the syspath. If the running kernel
 185  * supports the UI_GET_SYSPATH ioctl, the syspath is retrieved through that and will
 186  * be reliable and not be NULL.
 187  *
 188  * @note This function may return NULL. libevdev currently uses ctime and
 189  * the device name to guess devices. To avoid false positives, wait at least
 190  * wait at least 1.5s between creating devices that have the same name.
 191  * @param uinput_dev A previously created uinput device.
 192  * @return The syspath for this device, including preceding /sys.
 193  *
 194  * @see libevdev_uinput_get_devnode
 195  */
 196 const char*libevdev_uinput_get_syspath(struct libevdev_uinput *uinput_dev);
 197
 198 /**
 199  * @ingroup uinput
 200  *
 201  * Return the device node representing this uinput device.
 202  *
 203  * This relies on libevdev_uinput_get_syspath() to provide a valid syspath.
 204  * See libevdev_uinput_get_syspath() for more details.
 205  *
 206  * @note This function may return NULL. libevdev currently has to guess the
 207  * syspath and the device node. See libevdev_uinput_get_syspath() for details.
 208  * @param uinput_dev A previously created uinput device.
 209  * @return The device node for this device, in the form of /dev/input/eventN
 210  *
 211  * @see libevdev_uinput_get_syspath
 212  */
 213 const char* libevdev_uinput_get_devnode(struct libevdev_uinput *uinput_dev);
 214
 215 /**
 216  * @ingroup uinput
 217  *
 218  * Post an event through the uinput device. It is the caller's responsibility
 219  * that any event sequence is terminated with an EV_SYN/SYN_REPORT/0 event.
 220  * Otherwise, listeners on the device node will not see the events until the
 221  * next EV_SYN event is posted.
 222  *
 223  * @param uinput_dev A previously created uinput device.
 224  * @param type Event type (EV_ABS, EV_REL, etc.)
 225  * @param code Event code (ABS_X, REL_Y, etc.)
 226  * @param value The event value
 227  * @return 0 on success or a negative errno on error
 228  */
 229 int libevdev_uinput_write_event(const struct libevdev_uinput *uinput_dev,
 230                                 unsigned int type,
 231                                 unsigned int code,
 232                                 int value);
 233 #ifdef __cplusplus
 234 }
 235 #endif
 236
 237 #endif /* LIBEVDEV_UINPUT_H */