libei: doc/api/libei.h File Reference

libei 1.4.0 A library for Emulated Input

Typedefs | Enumerations | Functions
libei.h File Reference
`#include <stdbool.h>`
`#include <stdint.h>`
`#include <stddef.h>`

Go to the source code of this file.

## Typedefs
typedef void(* | ei_log_handler) (struct ei *ei, enum ei_log_priority priority, const char *message, struct ei_log_context *context)
| The log handler for library logging.
typedef uint64_t(* | ei_clock_now_func) (struct ei *ei)
| Optional override function for ei_now().

## Enumerations
enum | ei_device_type { EI_DEVICE_TYPE_VIRTUAL , EI_DEVICE_TYPE_PHYSICAL }
| The device type determines what the device represents. More...
enum | ei_device_capability { EI_DEVICE_CAP_POINTER , EI_DEVICE_CAP_POINTER_ABSOLUTE , EI_DEVICE_CAP_KEYBOARD , EI_DEVICE_CAP_TOUCH , EI_DEVICE_CAP_SCROLL , EI_DEVICE_CAP_BUTTON }
| The set of supported capabilities. More...
enum | ei_keymap_type { EI_KEYMAP_TYPE_XKB }
| The set of supported keymap types for a struct ei_keymap. More...
enum | ei_event_type { EI_EVENT_CONNECT , EI_EVENT_DISCONNECT , EI_EVENT_SEAT_ADDED , EI_EVENT_SEAT_REMOVED , EI_EVENT_DEVICE_ADDED , EI_EVENT_DEVICE_REMOVED , EI_EVENT_DEVICE_PAUSED , EI_EVENT_DEVICE_RESUMED , EI_EVENT_KEYBOARD_MODIFIERS , EI_EVENT_PONG , EI_EVENT_SYNC , EI_EVENT_FRAME , EI_EVENT_DEVICE_START_EMULATING , EI_EVENT_DEVICE_STOP_EMULATING , EI_EVENT_POINTER_MOTION , EI_EVENT_POINTER_MOTION_ABSOLUTE , EI_EVENT_BUTTON_BUTTON , EI_EVENT_SCROLL_DELTA , EI_EVENT_SCROLL_STOP , EI_EVENT_SCROLL_CANCEL , EI_EVENT_SCROLL_DISCRETE , EI_EVENT_KEYBOARD_KEY , EI_EVENT_TOUCH_DOWN , EI_EVENT_TOUCH_UP , EI_EVENT_TOUCH_MOTION }
| This enum is not exhaustive, future versions of this library may add new event types. More...
enum | ei_log_priority { EI_LOG_PRIORITY_DEBUG , EI_LOG_PRIORITY_INFO , EI_LOG_PRIORITY_WARNING , EI_LOG_PRIORITY_ERROR }

## Functions
const char * | ei_event_type_to_string (enum ei_event_type)
| This is a debugging helper to return a string of the name of the event type, or NULL if the event type is invalid.
struct ei * | ei_new (void *user_data)
| This is an alias for ei_new_sender.
struct ei * | ei_new_sender (void *user_data)
| Create a new sender ei context.
struct ei * | ei_new_receiver (void *user_data)
| Create a new receiver ei context.
struct ei * | ei_ref (struct ei *ei)
| Increase the refcount of this struct by one.
struct ei * | ei_unref (struct ei *ei)
| Decrease the refcount of this struct by one.
void | ei_set_user_data (struct ei *ei, void *user_data)
| Set a custom data pointer for this context.
void * | ei_get_user_data (struct ei *ei)
| Return the custom data pointer for this context.
bool | ei_is_sender (struct ei *ei)
| Returns true if the context is was created with ei_new_sender() or false otherwise.
unsigned int | ei_log_context_get_line (struct ei_log_context *ctx)
const char * | ei_log_context_get_file (struct ei_log_context *ctx)
const char * | ei_log_context_get_func (struct ei_log_context *ctx)
void | ei_log_set_handler (struct ei *ei, ei_log_handler log_handler)
| Change the log handler for this context.
void | ei_log_set_priority (struct ei *ei, enum ei_log_priority priority)
enum ei_log_priority | ei_log_get_priority (const struct ei *ei)
void | ei_clock_set_now_func (struct ei *, ei_clock_now_func func)
| Override the function that returns the current time ei_now().
void | ei_configure_name (struct ei *ei, const char *name)
| Set the name for this client.
int | ei_setup_backend_fd (struct ei *ei, int fd)
| Initialize the ei context on the given socket file descriptor.
int | ei_setup_backend_socket (struct ei *ei, const char *socketpath)
| Set this ei context to use the socket backend.
int | ei_get_fd (struct ei *ei)
| libei keeps a single file descriptor for all events.
struct ei_ping * | ei_new_ping (struct ei *ei)
| Create a new ei_ping object to trigger a round trip to the EIS implementation.
uint64_t | ei_ping_get_id (struct ei_ping *ping)
| Return a unique, increasing id for this struct.
struct ei_ping * | ei_ping_ref (struct ei_ping *ei_ping)
| Increase the refcount of this struct by one.
struct ei_ping * | ei_ping_unref (struct ei_ping *ei_ping)
| Decrease the refcount of this struct by one.
void | ei_ping_set_user_data (struct ei_ping *ei_ping, void *user_data)
| Set a custom data pointer for this struct.
void * | ei_ping_get_user_data (struct ei_ping *ei_ping)
| Return the custom data pointer for this struct.
void | ei_ping (struct ei_ping *ping)
| Issue a roundtrip request to the EIS implementation, resulting in an EI_EVENT_PONG event when this roundtrip has been processed.
void | ei_dispatch (struct ei *ei)
| Main event dispatching function.
struct ei_event * | ei_get_event (struct ei *ei)
| Return the next event from the event queue, removing it from the queue.
struct ei_event * | ei_peek_event (struct ei *ei)
| Returns the next event in the internal event queue (or `NULL`) without removing that event from the queue; the next call to ei_get_event() will return that same event.
uint64_t | ei_now (struct ei *ei)
void | ei_disconnect (struct ei *ei)
| Disconnect the current ei context from the EIS implementation.
void | ei_seat_set_user_data (struct ei_seat *seat, void *user_data)
| Set a custom data pointer for this context.
void * | ei_seat_get_user_data (struct ei_seat *seat)
| Return the custom data pointer for this context.
const char * | ei_seat_get_name (struct ei_seat *seat)
bool | ei_seat_has_capability (struct ei_seat *seat, enum ei_device_capability cap)
| Return true if the capabilitiy is available on this seat or false otherwise.
void | ei_seat_bind_capabilities (struct ei_seat *seat,...) __attribute__((sentinel))
| Bind this client to the given seat capabilities, terminated by `NULL`.
void | ei_seat_unbind_capabilities (struct ei_seat *seat,...) __attribute__((sentinel))
| Unbind a seat's capabilities, terminatd by `NULL`.
struct ei_seat * | ei_seat_ref (struct ei_seat *seat)
struct ei_seat * | ei_seat_unref (struct ei_seat *seat)
struct ei * | ei_seat_get_context (struct ei_seat *seat)
| Return the struct ei context this seat is associated with.
struct ei_event * | ei_event_unref (struct ei_event *event)
| Release resources associated with this event.
enum ei_event_type | ei_event_get_type (struct ei_event *event)
struct ei_device * | ei_event_get_device (struct ei_event *event)
| Return the device from this event.
uint64_t | ei_event_get_time (struct ei_event *event)
| Return the time for the event of type EI_EVENT_FRAME in microseconds.
struct ei_device * | ei_device_ref (struct ei_device *device)
| Increase the refcount of this struct by one.
struct ei_device * | ei_device_unref (struct ei_device *device)
| Decrease the refcount of this struct by one.
struct ei_seat * | ei_device_get_seat (struct ei_device *device)
void | ei_device_set_user_data (struct ei_device *device, void *user_data)
| Set a custom data pointer for this context.
void * | ei_device_get_user_data (struct ei_device *device)
| Return the custom data pointer for this context.
uint32_t | ei_device_get_width (struct ei_device *device)
| Return the width of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.
uint32_t | ei_device_get_height (struct ei_device *device)
| Return the height of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.
size_t | ei_keymap_get_size (struct ei_keymap *keymap)
enum ei_keymap_type | ei_keymap_get_type (struct ei_keymap *keymap)
| Returns the type for this keymap.
int | ei_keymap_get_fd (struct ei_keymap *keymap)
| Return a memmap-able file descriptor pointing to the keymap used by the device.
struct ei_device * | ei_keymap_get_device (struct ei_keymap *keymap)
| Return the device this keymap belongs to, or `NULL` if it has not yet been assigned to a device.
struct ei_keymap * | ei_keymap_ref (struct ei_keymap *keymap)
| Increase the refcount of this struct by one.
struct ei_keymap * | ei_keymap_unref (struct ei_keymap *keymap)
| Decrease the refcount of this struct by one.
void | ei_keymap_set_user_data (struct ei_keymap *keymap, void *user_data)
void * | ei_keymap_get_user_data (struct ei_keymap *keymap)
void | ei_device_close (struct ei_device *device)
| Notify the server that the client is no longer interested in this device.
const char * | ei_device_get_name (struct ei_device *device)
enum ei_device_type | ei_device_get_type (struct ei_device *device)
bool | ei_device_has_capability (struct ei_device *device, enum ei_device_capability cap)
| Return true if the device has the requested capability.
struct ei_region * | ei_device_get_region (struct ei_device *device, size_t index)
| Obtain a region from a device of type EI_DEVICE_TYPE_VIRTUAL.
struct ei_region * | ei_device_get_region_at (struct ei_device *device, double x, double y)
| Return the region that contains the given point x/y (in desktop-wide coordinates) or NULL if the coordinates are outside all regions.
struct ei_region * | ei_region_ref (struct ei_region *region)
struct ei_region * | ei_region_unref (struct ei_region *region)
void | ei_region_set_user_data (struct ei_region *region, void *user_data)
void * | ei_region_get_user_data (struct ei_region *region)
uint32_t | ei_region_get_x (struct ei_region *region)
uint32_t | ei_region_get_y (struct ei_region *region)
uint32_t | ei_region_get_width (struct ei_region *region)
uint32_t | ei_region_get_height (struct ei_region *region)
const char * | ei_region_get_mapping_id (struct ei_region *region)
| Get the unique identifier (representing an external resource) that is attached to this region, if any.
bool | ei_region_contains (struct ei_region *region, double x, double y)
| Return true if the point x/y (in desktop-wide coordinates) is within region.
bool | ei_region_convert_point (struct ei_region *region, double *x, double *y)
| Convert the point x/y in a desktop-wide coordinate system into the corresponding point relative to the offset of the given region.
double | ei_region_get_physical_scale (struct ei_region *region)
| Return the physical scale for this region.
struct ei_keymap * | ei_device_keyboard_get_keymap (struct ei_device *device)
| Return the keymap for this device or `NULL`.
struct ei_device * | ei_keymap_get_context (struct ei_keymap *keymap)
| Return the struct ei_device this keymap is associated with.
struct ei * | ei_device_get_context (struct ei_device *device)
| Return the struct ei context this device is associated with.
void | ei_device_start_emulating (struct ei_device *device, uint32_t sequence)
| Notify the EIS implementation that the given device is about to start sending events.
void | ei_device_stop_emulating (struct ei_device *device)
| Notify the EIS implementation that the given device is no longer sending events.
void | ei_device_frame (struct ei_device *device, uint64_t time)
| Generate a frame event to group the current set of events into a logical hardware event.
void | ei_device_pointer_motion (struct ei_device *device, double x, double y)
| Generate a relative motion event on a device with the EI_DEVICE_CAP_POINTER capability.
void | ei_device_pointer_motion_absolute (struct ei_device *device, double x, double y)
| Generate an absolute motion event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE capability.
void | ei_device_button_button (struct ei_device *device, uint32_t button, bool is_press)
| Generate a button event on a device with the EI_DEVICE_CAP_BUTTON capability.
void | ei_device_scroll_delta (struct ei_device *device, double x, double y)
| Generate a smooth (pixel-precise) scroll event on a device with the EI_DEVICE_CAP_SCROLL capability.
void | ei_device_scroll_discrete (struct ei_device *device, int32_t x, int32_t y)
| Generate a discrete scroll event on a device with the EI_DEVICE_CAP_SCROLL capability.
void | ei_device_scroll_stop (struct ei_device *device, bool stop_x, bool stop_y)
| Generate a scroll stop event on a device with the EI_DEVICE_CAP_SCROLL capability.
void | ei_device_scroll_cancel (struct ei_device *device, bool cancel_x, bool cancel_y)
| Generate a scroll cancel event on a device with the EI_DEVICE_CAP_SCROLL capability.
void | ei_device_keyboard_key (struct ei_device *device, uint32_t keycode, bool is_press)
| Generate a key event on a device with the EI_DEVICE_CAP_KEYBOARD capability.
struct ei_touch * | ei_device_touch_new (struct ei_device *device)
| Initiate a new touch on a device with the EI_DEVICE_CAP_TOUCH capability.
void | ei_touch_down (struct ei_touch *touch, double x, double y)
| This function can only be called once on an ei_touch object.
void | ei_touch_motion (struct ei_touch *touch, double x, double y)
| Move this touch to the new coordinates.
void | ei_touch_up (struct ei_touch *touch)
| Release this touch.
void | ei_touch_cancel (struct ei_touch *touch)
| Cancel this touch.
struct ei_touch * | ei_touch_ref (struct ei_touch *touch)
| Increase the refcount of this struct by one.
struct ei_touch * | ei_touch_unref (struct ei_touch *touch)
| Decrease the refcount of this struct by one.
void | ei_touch_set_user_data (struct ei_touch *touch, void *user_data)
| Set a custom data pointer for this context.
void * | ei_touch_get_user_data (struct ei_touch *touch)
| Return the custom data pointer for this context.
struct ei_device * | ei_touch_get_device (struct ei_touch *touch)
struct ei_seat * | ei_event_get_seat (struct ei_event *event)
| Return the seat from this event.
struct ei_ping * | ei_event_pong_get_ping (struct ei_event *event)
| Returns the associated ei_ping struct with this event.
uint32_t | ei_event_emulating_get_sequence (struct ei_event *event)
| For an event of type EI_EVENT_DEVICE_START_EMULATING, return the sequence number set by the EIS implementation.
uint32_t | ei_event_keyboard_get_xkb_mods_depressed (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_MODIFIERS, get the mask of currently logically pressed-down modifiers.
uint32_t | ei_event_keyboard_get_xkb_mods_latched (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_MODIFIERS, get the mask of currently logically latched modifiers.
uint32_t | ei_event_keyboard_get_xkb_mods_locked (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_MODIFIERS, get the mask of currently logically locked modifiers.
uint32_t | ei_event_keyboard_get_xkb_group (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_MODIFIERS, get the current effective group.
double | ei_event_pointer_get_dx (struct ei_event *event)
| For an event of type EI_EVENT_POINTER_MOTION return the relative x movement in logical pixels or mm, depending on the device type.
double | ei_event_pointer_get_dy (struct ei_event *event)
| For an event of type EI_EVENT_POINTER_MOTION return the relative y movement in logical pixels or mm, depending on the device type.
double | ei_event_pointer_get_absolute_x (struct ei_event *event)
| For an event of type EI_EVENT_POINTER_MOTION_ABSOLUTE return the x position in logical pixels or mm, depending on the device type.
double | ei_event_pointer_get_absolute_y (struct ei_event *event)
| For an event of type EI_EVENT_POINTER_MOTION_ABSOLUTE return the y position in logical pixels or mm, depending on the device type.
uint32_t | ei_event_button_get_button (struct ei_event *event)
| For an event of type EI_EVENT_BUTTON_BUTTON return the button code as defined in linux/input-event-codes.h.
bool | ei_event_button_get_is_press (struct ei_event *event)
| For an event of type EI_EVENT_BUTTON_BUTTON return true if the event is a button press, false for a release.
double | ei_event_scroll_get_dx (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_DELTA return the x scroll distance in logical pixels or mm, depending on the device type.
double | ei_event_scroll_get_dy (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_DELTA return the y scroll distance in logical pixels or mm, depending on the device type.
bool | ei_event_scroll_get_stop_x (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_CANCEL return whether the x axis has cancelled scrolling.
bool | ei_event_scroll_get_stop_y (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_STOP return whether the y axis has stopped scrolling.
int32_t | ei_event_scroll_get_discrete_dx (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_DISCRETE return the x scroll distance in fractions or multiples of 120.
int32_t | ei_event_scroll_get_discrete_dy (struct ei_event *event)
| For an event of type EI_EVENT_SCROLL_DISCRETE return the y scroll distance in fractions or multiples of 120.
uint32_t | ei_event_keyboard_get_key (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_KEY return the key code (as defined in include/linux/input-event-codes.h).
bool | ei_event_keyboard_get_key_is_press (struct ei_event *event)
| For an event of type EI_EVENT_KEYBOARD_KEY return true if the event is a key down, false for a release.
uint32_t | ei_event_touch_get_id (struct ei_event *event)
| For an event of type EI_EVENT_TOUCH_DOWN, EI_EVENT_TOUCH_MOTION, or EI_EVENT_TOUCH_UP, return the tracking ID of the touch.
double | ei_event_touch_get_x (struct ei_event *event)
| For an event of type EI_EVENT_TOUCH_DOWN, or EI_EVENT_TOUCH_MOTION, return the x coordinate of the touch in logical pixels or mm, depending on the device type.
double | ei_event_touch_get_y (struct ei_event *event)
| For an event of type EI_EVENT_TOUCH_DOWN, or EI_EVENT_TOUCH_MOTION, return the y coordinate of the touch in logical pixels or mm, depending on the device type.
bool | ei_event_touch_get_is_cancel (struct ei_event *event)
| For an event of type EI_EVENT_TOUCH_UP return true if the event was cancelled instead of logically released.