2 * Copyright © 2013 Red Hat, Inc.
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.
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
23 #ifndef LIBEVDEV_UINPUT_H
24 #define LIBEVDEV_UINPUT_H
26 #include <libevdev/libevdev.h>
28 struct libevdev_uinput;
31 * @defgroup uinput uinput device creation
33 * Creation of uinput devices based on existing libevdev devices. These functions
34 * help to create uinput devices that emulate libevdev devices. In the simplest
35 * form it serves to duplicate an existing device:
40 * struct libevdev *dev;
41 * struct libevdev_uinput *uidev;
42 * struct input_event ev[2];
44 * err = libevdev_new_from_fd(&dev, fd);
48 * uifd = open("/dev/uinput", O_RDWR);
52 * err = libevdev_uinput_create_from_device(dev, uifd, &uidev);
56 * // post a REL_X event
57 * err = libevdev_uinput_write_event(uidev, EV_REL, REL_X, -1);
60 * libevdev_uinput_write_event(uidev, EV_SYN, SYN_REPORT, 0);
64 * libevdev_uinput_destroy(uidev);
69 * Alternatively, a device can be constructed from scratch:
73 * struct libevdev *dev;
74 * struct libevdev_uinput *uidev;
76 * dev = libevdev_new();
77 * libevdev_set_name(dev, "test device");
78 * libevdev_enable_event_type(dev, EV_REL);
79 * libevdev_enable_event_code(dev, EV_REL, REL_X);
80 * libevdev_enable_event_code(dev, EV_REL, REL_Y);
81 * libevdev_enable_event_type(dev, EV_KEY);
82 * libevdev_enable_event_code(dev, EV_KEY, BTN_LEFT);
83 * libevdev_enable_event_code(dev, EV_KEY, BTN_MIDDLE);
84 * libevdev_enable_event_code(dev, EV_KEY, BTN_RIGHT);
86 * err = libevdev_uinput_create_from_device(dev,
87 * LIBEVDEV_UINPUT_OPEN_MANAGED,
92 * // ... do something ...
94 * libevdev_uinput_destroy(uidev);
99 enum libevdev_uinput_open_mode {
100 /* intentionally -2 to avoid to avoid code like the below from accidentally working:
101 fd = open("/dev/uinput", O_RDWR); // fails, fd is -1
102 libevdev_uinput_create_from_device(dev, fd, &uidev); // may hide the error */
103 LIBEVDEV_UINPUT_OPEN_MANAGED = -2, /**< let libevdev open and close @c /dev/uinput */
109 * Create a uinput device based on the libevdev device given. The uinput device
110 * will be an exact copy of the libevdev device, minus the bits that uinput doesn't
113 * If uinput_fd is LIBEVDEV_UINPUT_OPEN_MANAGED, libevdev_uinput_create_from_device()
114 * will open @c /dev/uinput in read/write mode and manage the file descriptor.
115 * Otherwise, uinput_fd must be opened by the caller and opened with the
116 * appropriate permissions.
118 * The device's lifetime is tied to the uinput file descriptor, closing it will
119 * destroy the uinput device. You should call libevdev_uinput_destroy() before
120 * closing the file descriptor to free allocated resources.
121 * A file descriptor can only create one uinput device at a time; the second device
122 * will fail with -EINVAL.
124 * You don't need to keep the file descriptor variable around,
125 * libevdev_uinput_get_fd() will return it when needed.
127 * @note Due to limitations in the uinput kernel module, REP_DELAY and
128 * REP_PERIOD will default to the kernel defaults, not to the ones set in the
131 * @param dev The device to duplicate
132 * @param uinput_fd LIBEVDEV_UINPUT_OPEN_MANAGED or a file descriptor to @c /dev/uinput,
133 * @param[out] uinput_dev The newly created libevdev device.
135 * @return 0 on success or a negative errno on failure. On failure, the value of
136 * uinput_dev is unmodified.
138 * @see libevdev_uinput_destroy
140 int libevdev_uinput_create_from_device(const struct libevdev *dev,
142 struct libevdev_uinput **uinput_dev);
147 * Destroy a previously created uinput device and free associated memory.
149 * If the device was opened with LIBEVDEV_UINPUT_OPEN_MANAGED, libevdev_uinput_destroy()
150 * also closes the file descriptor. Otherwise, the fd is left as-is and
151 * must be closed by the caller.
153 * @param uinput_dev A previously created uinput device.
155 * @return 0 on success or a negative errno on failure
157 void libevdev_uinput_destroy(struct libevdev_uinput *uinput_dev);
162 * Return the file descriptor used to create this uinput device. This is the
163 * fd pointing to <strong>/dev/uinput</strong>. This file descriptor may be used to write
164 * events that are emitted by the uinput device.
165 * Closing this file descriptor will destroy the uinput device, you should
166 * call libevdev_uinput_destroy() first to free allocated resources.
168 * @param uinput_dev A previously created uinput device.
170 * @return The file descriptor used to create this device
172 int libevdev_uinput_get_fd(const struct libevdev_uinput *uinput_dev);
177 * Return the syspath representing this uinput device.
178 * As of 3.11, the uinput kernel device does not
179 * provide a way to get the syspath directly through uinput so libevdev must guess.
180 * In some cases libevdev is unable to derive the syspath. If the running kernel
181 * supports the UI_GET_SYSPATH ioctl, the syspath is retrieved through that and will
182 * be reliable and not be NULL.
184 * @note This function may return NULL. libevdev currently uses ctime and
185 * the device name to guess devices. To avoid false positives, wait at least
186 * wait at least 1.5s between creating devices that have the same name.
187 * @param uinput_dev A previously created uinput device.
188 * @return The syspath for this device, including preceding /sys.
190 * @see libevdev_uinput_get_devnode
192 const char*libevdev_uinput_get_syspath(struct libevdev_uinput *uinput_dev);
197 * Return the device node representing this uinput device.
199 * This relies on libevdev_uinput_get_syspath() to provide a valid syspath.
200 * See libevdev_uinput_get_syspath() for more details.
202 * @note This function may return NULL. libevdev currently has to guess the
203 * syspath and the device node. See libevdev_uinput_get_syspath() for details.
204 * @param uinput_dev A previously created uinput device.
205 * @return The device node for this device, in the form of /dev/input/eventN
207 * @see libevdev_uinput_get_syspath
209 const char* libevdev_uinput_get_devnode(struct libevdev_uinput *uinput_dev);
214 * Post an event through the uinput device. It is the caller's responsibility
215 * that any event sequence is terminated with an EV_SYN/SYN_REPORT/0 event.
216 * Otherwise, listeners on the device node will not see the events until the
217 * next EV_SYN event is posted.
219 * @param uinput_dev A previously created uinput device.
220 * @param type Event type (EV_ABS, EV_REL, etc.)
221 * @param code Event code (ABS_X, REL_Y, etc.)
222 * @param value The event value
223 * @return 0 on success or a negative errno on error
225 int libevdev_uinput_write_event(const struct libevdev_uinput *uinput_dev,
230 #endif /* LIBEVDEV_UINPUT_H */