Evfilter library documentation
Evfilter library documentation
Evfilter library consists of many api levels. This page explains complete evfilter api although you may need only small part of it. In this case scroll down to see only the high level inteface.
struct evf_filter *evf_filter_load(const char *name, char *params, union evf_err *err);
Create filter instance on the heap accordingly to it's name and parameters. Returns pointer on success otherwise NULL is returned and struct evf_err is filled with error description.
Note: the string params is modified during the parsing.void *evf_filter_free(struct evf_filter *filter);
Destroy filter, as filter could have additional cleanup function it's not safe to call just free(filter); even if it may work it's bad practice and may lead to memory leaks. The pointer returned by this function is used for internal purposes.
void *evf_filters_free(struct evf_filter *root);
Destroys linked list of filters.
const char *evf_filter_get_name(struct evf_filter *filter);
Returns pointer to filter name.
const char *evf_filter_get_desc(struct evf_filter *filter);
Returns pointer to short filter description.
struct evf_filter *evf_filters_last(struct evf_filter *root);
Returns pointer to the last filter in linked list.
struct evf_filter *evf_filters_merge(struct evf_filter *root, struct evf_filter *filters);
Merge two linked lists by appending second list after the first one.
void evf_filters_print(struct evf_filter *root);
Prints structure of linked list into stdout. Use for debugging only.
Functions that can ease work with linux input interface. To be able to use them include linux_input.h as this header is not included in evfilter.h.
int evf_input_get_version(int fd, int *version);
Wrapper to ioctl, returns 0 on success. Example to print actual version:
printf("%d %d %d", version>>16, version>>8 & 0xff, version & 0xff);
int evf_input_get_name(int fd, char *buf, size_t buf_len);
Wrapper to ioctl, returns 0 on success and copy up to buf_len characters of device name to buf. The string is always null terminated.
int evf_input_get_phys(int fd, char *buf, size_t buf_len);
Wrapper to ioctl, returns 0 on success and copy up to buf_len characters of device phys path to buf. The string is always null terminated.
int evf_input_compare(int fd, const char *path);
Compares minor and major number for file descriptor and file pointed to by path. Returns -1 on error, 0 for different devices, 1 for both pointing to the same device.
int evf_input_print(FILE *file, const char *prefix, struct input_event *ev);
Prints event in human-readable format to the file, prefixing every line with specified string. Example of output (" *** " are prefix):
*** ev->type: EV_REL
*** ev->code: REL_Y (1)
*** ev->value: 1
*** ev->type: EV_SYN
*** ev->type: EV_KEY
*** ev->code: Key_LeftCtrl (29)
*** ev->value: KEY_DOWN (1)
...
struct evf_filter *evf_load_system_profile(int fd, union evf_err *err);
Loads system profile and returns pointer to filter line. You should always check evf_err because NULL is correct return value.
struct evf_filter *evf_load_system_profile(const char *path, int fd, union evf_err *err);
Loads application defined profile and returns pointer to filter line. You should always check evf_err because NULL is correct return value here. For detailed profile description refer to profile documentation.
Functions for easier handling of hotplug events. Current implementation uses inotify watching /dev/input/.
int evf_hotplug_init(void (*device_plugged)(const char *dev), void (*device_unplugged)(const char *dev));
Initalize watch for /dev/input/ and set two callbacks. Device unplugged is more or less informational, because /dev/input/eventX are dynamically allocated and moreover cannot be opened at the time callback is called. Retruns file descriptor for use with select() or -1 on faillure.
int evf_hotplug_rescan(void);
Read hotplug events from file descriptor, call this function after select() has returned data available on file descriptor returned by evf_hotplug_init(). On success number of hotplug events is returned otherwise -1 is returned.
void evf_hotplug_rescan(void);
Close file descriptor and do other cleanups.
IO queue is abstraction to traditional unix select() call.
EVF_IO_QUEUE_OK - read was succesful EVF_IO_QUEUE_REM - remove member from queue EVF_IO_QUEUE_CLOSE - close file descriptor EVF_IO_QUEUE_DFREE - call free on void* priv
These flags should be returned by read callback. There are defined as bitfield so it's possible to combine some of them them for example EVF_IO_QUEUE_REM | EVF_IO_QUEUE_CLOSE which would remove descriptor from queue and close file descriptor.
EVF_IO_QUEUE_CLOSE and EVF_IO_QUEUE_DFREE could be also used as flag for evf_io_queue_destroy(). That would call free() and close() on every member in queue. Don't forget that calling free() on NULL pointer is correct.
struct evf_io_queue *evf_io_queue_new(void);
Allocate and initalize new queue, returns pointer to newly allocated queue or NULL in case of failure.
void evf_io_queue_destroy(struct evf_io_queue *queue, int flags);
Destroy queue. Flags could be one of following 0 or EVF_IO_QUEUE_DFREE and/or EVF_IO_QUEUE_CLOSE.
int evf_io_queue_wait(struct evf_io_queue *queue, struct timeval *timeout);
Wait for data on any descriptor in io queue. When timeout is not needed pass NULL as a second parameter.
int evf_io_queue_add(struct evf_io_queue *queue, int fd, int (*read)(struct evf_io_queue_memb *self), void *priv);
Add file descriptor fd into io queue as well as read callback and priv pointer to your data strucures. Read callback is called when data are ready on file descriptor and should return io_queue_flag.
int evf_io_queue_rem(struct evf_io_queue *queue, int fd);
Remove file descriptor from queue, beware that file descriptor is not closed automatically nor free() on void* priv is called.
unsigned int evf_io_queue_get_count(struct evf_io_queue *queue);
Returns number of file descriptors in queue.