libevdev  0.5
A wrapper library for evdev devices
 All Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Enumerations | Functions
Event handling

Functions to handle events and fetch the current state of the event. More...

Enumerations

enum  libevdev_read_flag { LIBEVDEV_READ_FLAG_SYNC, LIBEVDEV_READ_FLAG_NORMAL, LIBEVDEV_READ_FLAG_FORCE_SYNC, LIBEVDEV_READ_FLAG_BLOCKING }
 
enum  libevdev_read_status { LIBEVDEV_READ_STATUS_SUCCESS, LIBEVDEV_READ_STATUS_SYNC }
 

Functions

int libevdev_next_event (struct libevdev *dev, unsigned int flags, struct input_event *ev)
 Get the next event from the device. More...
 
int libevdev_has_event_pending (struct libevdev *dev)
 Check if there are events waiting for us. More...
 

Detailed Description

Functions to handle events and fetch the current state of the event.

Generally, libevdev updates its internal state as the event is processed and forwarded to the caller. Thus, the libevdev state of the device should always be identical to the caller's state. It may however lag behind the actual state of the device.

Enumeration Type Documentation

Enumerator
LIBEVDEV_READ_FLAG_SYNC 

Process data in sync mode.

LIBEVDEV_READ_FLAG_NORMAL 

Process data in normal mode.

LIBEVDEV_READ_FLAG_FORCE_SYNC 

Pretend the next event is a SYN_DROPPED and require the caller to sync.

LIBEVDEV_READ_FLAG_BLOCKING 

The fd is not in O_NONBLOCK and a read may block.

Enumerator
LIBEVDEV_READ_STATUS_SUCCESS 

libevdev_next_event() has finished without an error and an event is available for processing.

See Also
libevdev_next_event
LIBEVDEV_READ_STATUS_SYNC 

Depending on the libevdev_next_event() read flag:

  • libevdev received a SYN_DROPPED from the device, and the caller should now resync the device, or,
  • an event has been read in sync mode.
See Also
libevdev_next_event

Function Documentation

int libevdev_has_event_pending ( struct libevdev *  dev)

Check if there are events waiting for us.

This does not read an event off the fd and may not access the fd at all. If there are events queued internally this function will return non-zero. If the internal queue is empty, this function will poll the file descriptor for data.

This is a convenience function for simple processes, most complex programs are expected to use select(2) or poll(2) on the file descriptor. The kernel guarantees that if data is available, it is a multiple of sizeof(struct input_event), and thus calling libevdev_next_event() when select(2) or poll(2) return is safe. You do not need libevdev_has_event_pending() if you're using select(2) or poll(2).

Parameters
devThe evdev device, already initialized with libevdev_set_fd()
Returns
On failure, a negative errno is returned.
Return values
0No event is currently available
1One or more events are available on the fd
Note
This function is signal-safe.
int libevdev_next_event ( struct libevdev *  dev,
unsigned int  flags,
struct input_event *  ev 
)

Get the next event from the device.

This function operates in two different modes: normal mode or sync mode.

In normal mode, this function returns LIBEVDEV_READ_STATUS_SUCCESS and returns the event in the parameter ev. If no events are available at this time, it returns -EAGAIN and ev is undefined.

If a SYN_DROPPED is read from the device, this function returns LIBEVDEV_READ_STATUS_SYNC. The caller should now call this function with the LIBEVDEV_READ_FLAG_SYNC flag set, to get the set of events that make up the device state delta. This function returns LIBEVDEV_READ_STATUS_SYNC for each event part of that delta, until it returns -EAGAIN once all events have been synced.

If a device needs to be synced by the caller but the caller does not call with the LIBEVDEV_READ_STATUS_SYNC flag set, all events from the diff are dropped and event processing continues as normal.

Parameters
devThe evdev device, already initialized with libevdev_set_fd()
flagsSet of flags to determine behaviour. If LIBEVDEV_READ_FLAG_NORMAL is set, the next event is read in normal mode. If LIBEVDEV_READ_FLAG_SYNC is set, the next event is read in sync mode.
evOn success, set to the current event.
Returns
On failure, a negative errno is returned.
Return values
LIBEVDEV_READ_STATUS_SUCCESSOne or more events where read of the device
-EAGAINNo events are currently available on the device
LIBEVDEV_READ_STATUS_SYNCA SYN_DROPPED event was received, or a synced event was returned.
Note
This function is signal-safe.