1 /***************************************************************************** 2 * 3 * evemu - Kernel device emulation 4 * 5 * Copyright (C) 2010-2012 Canonical Ltd. 6 * 7 * This library is free software: you can redistribute it and/or modify it 8 * under the terms of the GNU Lesser General Public License version 3 9 * as published by the Free Software Foundation. 10 * 11 * This library is distributed in the hope that it will be useful, but 12 * WITHOUT ANY WARRANTY; without even the implied warranties of 13 * MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR 14 * PURPOSE. See the GNU Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public License 17 * along with this library. If not, see <http://www.gnu.org/licenses/>. 18 * 19 * Copyright (C) 2010 Henrik Rydberg <rydberg@euromail.se> 20 * 21 * Permission is hereby granted, free of charge, to any person obtaining a 22 * copy of this software and associated documentation files (the "Software"), 23 * to deal in the Software without restriction, including without limitation 24 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 25 * and/or sell copies of the Software, and to permit persons to whom the 26 * Software is furnished to do so, subject to the following conditions: 27 * 28 * The above copyright notice and this permission notice (including the next 29 * paragraph) shall be included in all copies or substantial portions of the 30 * Software. 31 * 32 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 33 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 34 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 35 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 36 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 37 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 38 * DEALINGS IN THE SOFTWARE. 39 * 40 ****************************************************************************/ 41 42 #ifndef EVEMU_H 43 #define EVEMU_H 44 45 #include <stdio.h> 46 #include <errno.h> 47 #include <linux/input.h> 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #define EVEMU_VERSION 0x00010000 54 55 /** 56 * evemu_new() - allocate a new evemu device 57 * @name: wanted input device name (or NULL to leave empty) 58 * 59 * This function allocates a new evemu device structure and 60 * initializes all fields to zero. If name is non-null and the length 61 * is sane, it is copied to the device name. 62 * 63 * Returns NULL in case of memory failure. 64 */ 65 struct evemu_device *evemu_new(const char *name); 66 67 /** 68 * evemu_delete() - free and allocated evemu device 69 * @dev: the device to free 70 * 71 * The device pointer is invalidated by this call. 72 */ 73 void evemu_delete(struct evemu_device *dev); 74 75 /** 76 * evemu_get_version() - get library version 77 * @dev: the device in use 78 * 79 * Returns the library version used to create this evemu instance. The 80 * version may differ from the value of EVEMU_VERSION in this header 81 * file. 82 */ 83 unsigned int evemu_get_version(const struct evemu_device *dev); 84 85 /** 86 * evemu_get_name() - get device name 87 * @dev: the device in use 88 * 89 * Returns the name of the device. The pointer is owned by the evemu 90 * instance and has evemu scope. 91 */ 92 const char *evemu_get_name(const struct evemu_device *dev); 93 94 /** 95 * evemu_set_name() - set device name 96 * @dev: the device in use 97 * 98 * Sets the name of the device. If name is non-null and the length is 99 * sane, it is copied to the device name. 100 */ 101 void evemu_set_name(struct evemu_device *dev, const char *name); 102 103 /** 104 * evemu_get_id_bustype() - get kernel device bustype 105 * @dev: the device in use 106 * 107 * Returns the kernel bus type used by the device. 108 */ 109 unsigned int evemu_get_id_bustype(const struct evemu_device *dev); 110 111 /** 112 * evemu_set_id_bustype() - set kernel bustype 113 * 114 * @dev: the device in use 115 * @bustype: the bustype value to set. 116 */ 117 void evemu_set_id_bustype(struct evemu_device *dev, unsigned int bustype); 118 119 /** 120 * evemu_get_id_vendor() - get kernel device vendor id 121 * @dev: the device in use 122 * 123 * Returns the kernel vendor id used by the device. 124 */ 125 unsigned int evemu_get_id_vendor(const struct evemu_device *dev); 126 127 /** 128 * evemu_set_id_vendor() - set kernel device vendor id 129 * 130 * @dev: the device in use 131 * @vendor: the vendor id value to set. 132 */ 133 void evemu_set_id_vendor(struct evemu_device *dev, unsigned int vendor); 134 135 /** 136 * evemu_get_id_product() - get kernel device product id 137 * @dev: the device in use 138 * 139 * Returns the kernel product id used by the device. 140 */ 141 unsigned int evemu_get_id_product(const struct evemu_device *dev); 142 143 /** 144 * evemu_set_id_product() - set kernel device product id 145 * 146 * @dev: the device in use 147 * @product: the product id value to set. 148 */ 149 void evemu_set_id_product(struct evemu_device *dev, unsigned int product); 150 151 /** 152 * evemu_get_id_version() - get kernel device id version 153 * @dev: the device in use 154 * 155 * Returns the kernel device id used by the device. 156 */ 157 unsigned int evemu_get_id_version(const struct evemu_device *dev); 158 159 /** 160 * evemu_set_id_version() - set kernel device id version 161 * 162 * @dev: the device in use 163 * @version: the version value to set. 164 */ 165 void evemu_set_id_version(struct evemu_device *dev, unsigned int version); 166 167 /** 168 * evemu_get_abs_minimum() - get kernel minimum value of event type 169 * @dev: the device in use 170 * @code: the event type code to query 171 * 172 * Returns the range minimum of the specified event type. 173 */ 174 int evemu_get_abs_minimum(const struct evemu_device *dev, int code); 175 176 /** 177 * evemu_set_abs_minimum() - set kernel minimum value of event type 178 * 179 * @dev: the device in use 180 * @code: the event type code to set 181 * @min: the minimum value to set 182 */ 183 void evemu_set_abs_minimum(struct evemu_device *dev, int code, int min); 184 185 /** 186 * evemu_get_abs_maximum() - get kernel maximum value of event type 187 * @dev: the device in use 188 * @code: the event type code to query 189 * 190 * Returns the range maximum of the specified event type. 191 */ 192 int evemu_get_abs_maximum(const struct evemu_device *dev, int code); 193 194 /** 195 * evemu_get_abs_current_value() - get kernel current value of event type 196 * @dev: the device in use 197 * @code: the event type code to query 198 * 199 * Returns the current value of the specified event type. 200 */ 201 int evemu_get_abs_current_value(const struct evemu_device *dev, int code); 202 203 204 /** 205 * evemu_set_abs_maximum() - set kernel maximum value of event type 206 * 207 * @dev: the device in use 208 * @code: the event type code to set 209 * @max: the maximum value to set 210 */ 211 void evemu_set_abs_maximum(struct evemu_device *dev, int code, int max); 212 213 /** 214 * evemu_get_abs_maximum() - get kernel filter fuzz of event type 215 * @dev: the device in use 216 * @code: the event type code to query 217 * 218 * Returns the filter fuzz of the specified event type. 219 */ 220 int evemu_get_abs_fuzz(const struct evemu_device *dev, int code); 221 222 /** 223 * evemu_set_abs_fuzz() - set kernel filter fuzz of event type 224 * 225 * @dev: the device in use 226 * @code: the event type code to set 227 * @fuzz: the fuzz value to set 228 */ 229 void evemu_set_abs_fuzz(struct evemu_device *dev, int code, int fuzz); 230 231 /** 232 * evemu_get_abs_maximum() - get kernel flat value of event type 233 * @dev: the device in use 234 * @code: the event type code to query 235 * 236 * Returns the flat value of the specified event type. Only used for 237 * joysticks. 238 */ 239 int evemu_get_abs_flat(const struct evemu_device *dev, int code); 240 241 /** 242 * evemu_set_abs_flat() - set kernel filter flat of event type 243 * 244 * @dev: the device in use 245 * @code: the event type code to set 246 * @flat: the flat value to set 247 */ 248 void evemu_set_abs_flat(struct evemu_device *dev, int code, int flat); 249 250 /** 251 * evemu_get_abs_resolution() - get kernel resolution of event type 252 * @dev: the device in use 253 * @code: the event type code to query 254 * 255 * Returns the resolution of the specified event type. Resolution is 256 * specified in units per millimeter (units/mm), or units per radian 257 * where appropriate. 258 */ 259 int evemu_get_abs_resolution(const struct evemu_device *dev, int code); 260 261 /** 262 * evemu_set_abs_resolution() - set kernel resolution of event type 263 * @dev: the device in use 264 * @code: the event type code to set 265 * @res: the resolution value to set. 266 * 267 * Resolution is specified in units per millimeter (units/mm), or units per 268 * radian where appropriate. 269 */ 270 void evemu_set_abs_resolution(struct evemu_device *dev, int code, int res); 271 272 /** 273 * evemu_has_prop() - check if device has a certain property 274 * @dev: the device in use 275 * @code: the property type code to query 276 * 277 * Returns true if the device has the given property. 278 */ 279 int evemu_has_prop(const struct evemu_device *dev, int code); 280 281 /** 282 * evemu_has_event() - check if device has a certain event type 283 * @dev: the device in use 284 * @code: the event type code to query 285 * 286 * Returns true if the event type is supported by the device. 287 */ 288 int evemu_has_event(const struct evemu_device *dev, int type, int code); 289 290 /** 291 * evemu_has_bit() - check if a device has a certain EV_* bit set 292 * @dev: the device in use 293 * @type: the EV_* bit to query 294 * 295 * Returns true if the event bit is supported by the device. 296 */ 297 int evemu_has_bit(const struct evemu_device *dev, int type); 298 299 /** 300 * evemu_extract() - configure evemu instance directly from the kernel device 301 * @dev: the device in use 302 * @fd: file descriptor of the kernel device to query 303 * 304 * Returns zero if successful, negative error otherwise. 305 */ 306 int evemu_extract(struct evemu_device *dev, int fd); 307 308 /** 309 * evemu_write() - write evemu configuration to a file 310 * @dev: the device in use 311 * @fp: file pointer to write the evemu configuration to 312 * 313 * Returns zero if successful, negative error otherwise. 314 */ 315 int evemu_write(const struct evemu_device *dev, FILE *fp); 316 317 /** 318 * evemu_read() - read evemu configuration from a file 319 * @dev: the device in use 320 * @fp: file pointer to read the evemu configuration from 321 * 322 * Returns a positive number if successful, zero or negative error 323 * otherwise. 324 */ 325 int evemu_read(struct evemu_device *dev, FILE *fp); 326 327 /** 328 * evemu_write_event() - write kernel event to file 329 * @fp: file pointer to write the event to 330 * @ev: pointer to the kernel event to write 331 * 332 * Writes the kernel event to the file. 333 * 334 * Returns a positive number if successful, zero or negative error 335 * otherwise. 336 */ 337 int evemu_write_event(FILE *fp, const struct input_event *ev); 338 339 /** 340 * evemu_create_event() - Create a single event 341 * @ev: pointer to the kernel event to be filled 342 * @type: the event type to set 343 * @code: the event code to set 344 * @value: the event value to set 345 */ 346 int evemu_create_event(struct input_event *ev, int type, int code, int value); 347 348 /** 349 * evemu_read_event() - read kernel event from file 350 * @fp: file pointer to read the event from 351 * @ev: pointer to the kernel event to be filled 352 * 353 * Reads a kernel event from the file. 354 * 355 * Returns a positive number if successful, zero or negative error 356 * otherwise. 357 */ 358 int evemu_read_event(FILE *fp, struct input_event *ev); 359 360 /** 361 * evemu_read_event_realtime() - read kernel events in realtime 362 * @fp: file pointer to read the event from 363 * @ev: pointer to the kernel event to be filled 364 * @evtime: pointer to a timeval struct 365 * 366 * The evtime struct should be cleared (zeroed) before the first call 367 * to this function. This function reads a kernel event from the file, 368 * and performs the microsleep necessary to deliver the event with the 369 * same timings as originally received. 370 * 371 * Returns a positive number if successful, zero or negative error 372 * otherwise. 373 */ 374 int evemu_read_event_realtime(FILE *fp, struct input_event *ev, 375 struct timeval *evtime); 376 377 /** 378 * evemu_record() - read events directly from a kernel device 379 * @fp: file pointer to write the events to 380 * @fd: file descriptor of kernel device to read from 381 * @ms: maximum time to wait for an event to appear before reading (ms) 382 * 383 * Continuously reads events from the kernel device and writes them to 384 * the file. The function terminates after ms milliseconds of 385 * inactivity. 386 * 387 * Returns zero if successful, negative error otherwise. 388 */ 389 int evemu_record(FILE *fp, int fd, int ms); 390 391 392 /** 393 * evemu_play_one() - play one event to kernel device 394 * @fd: file descriptor of kernel device to write to 395 * @ev: pointer to the kernel event to be played 396 * 397 * Returns zero if successful, negative error otherwise. 398 */ 399 int evemu_play_one(int fd, const struct input_event *ev); 400 401 /** 402 * evemu_play() - replay events from file to kernel device in realtime 403 * @fp: file pointer to read the events from 404 * @fd: file descriptor of kernel device to write to 405 * 406 * Contiuously reads events from the file and writes them to the 407 * kernel device, in realtime. The function terminates when end of 408 * file has been reached. 409 * 410 * Returns zero if successful, negative error otherwise. 411 */ 412 int evemu_play(FILE *fp, int fd); 413 414 /** 415 * evemu_create() - create a kernel device from the evemu configuration 416 * @dev: the device in use 417 * @fd: file descriptor of the special kernel uinput device 418 * 419 * Creates a new device with all the properties of the evemu device. 420 * 421 * Returns zero if successful, negative error otherwise. 422 */ 423 int evemu_create(struct evemu_device *dev, int fd); 424 425 /** 426 * evemu_create_managed() - create a kernel device from the evemu configuration 427 * @dev: the device in use 428 * 429 * Creates a new device with all the properties of the evemu device. 430 * Compared to evemu_create, evemu will take care of the handling of the uinput 431 * file descriptor. 432 * 433 * Returns zero if successful, negative error otherwise. 434 */ 435 int evemu_create_managed(struct evemu_device *dev); 436 437 /** 438 * evemu_get_devnode() - get device node 439 * @dev: the device in use 440 * 441 * Returns the input device node of the virtual device. The pointer is owned by 442 * the evemu instance and has evemu scope. 443 */ 444 const char *evemu_get_devnode(struct evemu_device *dev); 445 446 /** 447 * evemu_destroy() - destroy all created kernel devices 448 * @dev: the device to destroy 449 * 450 * Destroys all devices created using this file descriptor. 451 */ 452 void evemu_destroy(struct evemu_device *dev); 453 454 #ifdef __cplusplus 455 } 456 #endif 457 458 #endif 459