libei 1.3.0
A library for Emulated Input
|
Topics | |
The logging API | |
API for receiver clients | |
API for sender clients | |
The seat API | |
The device API | |
The region API | |
The keymap API | |
Data Structures | |
struct | ei |
The main context to interact with libei. More... | |
struct | ei_device |
A single device to generate input events from. More... | |
struct | ei_seat |
A logical seat for a group of devices. More... | |
struct | ei_event |
An event received from the EIS implementation. More... | |
struct | ei_keymap |
An keymap for a device with the EI_DEVICE_CAP_KEYBOARD capability. More... | |
struct | ei_region |
A rectangular region, defined by an x/y offset and a width and a height. More... | |
Typedefs | |
typedef uint64_t(* | ei_clock_now_func) (struct ei *ei) |
Optional override function for ei_now(). | |
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. | |
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. | |
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) |
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_seat * | ei_event_get_seat (struct ei_event *event) |
Return the seat from this event. | |
libei is the client-side module. This API should be used by processes that need to emulate devices or capture logical events from existing devices.
For an example client see the tools/
directory in the libei repository. At its core, a libei client will
Those events are typically a sequence of
libei clients come in sender and receiver modes, depending on whether the client sends or receives events from the EIS implementation. See API for sender clients and API for receiver clients for API calls specific to either mode.
enum ei_device_capability |
The set of supported capabilities.
A device may have zero or more capabilities, a device with perceived zero capabilities is typically a device with capabilities unsupported by the client - such a device should be closed immediately by the client.
The EIS implementation decides which capabilities may exist on a seat and which capabilities exist on any individual seat. However, a device may only have capabilities the client has bound to, see ei_seat_bind_capabilities().
For example, a client may bind to a seat with the pointer and keyboard capability but a given device only has the pointer capability. Keyboard events sent through that device will be treated as client bug.
If a client calls ei_seat_unbind_capabilities() for a capability, the EIS implementation may remove any or all devices that have that capability.
See ei_device_has_capability().
enum ei_device_type |
The device type determines what the device represents.
If the device type is EI_DEVICE_TYPE_VIRTUAL, the device is a virtual device representing input as applied on the EIS implementation's screen. A relative virtual device generates input events in logical pixels, an absolute virtual device generates input events in logical pixels on one of the device's regions. Virtual devices do not have a size.
If the device type is EI_DEVICE_TYPE_PHYSICAL, the device is a representation of a physical device as if connected to the EIS implementation's host computer. A relative physical device generates input events in mm, an absolute physical device generates input events in mm within the device's specified physical size. Physical devices do not have regions.
Enumerator | |
---|---|
EI_DEVICE_TYPE_VIRTUAL | |
EI_DEVICE_TYPE_PHYSICAL |
enum ei_event_type |
Enumerator | |
---|---|
EI_EVENT_CONNECT | The server has approved the connection to this client. Where the server does not approve the connection, EI_EVENT_DISCONNECT is sent instead. This event is only sent once after the initial connection request. |
EI_EVENT_DISCONNECT | The server has disconnected this client - all resources left to reference this server are now obsolete. Once this event has been received, the struct ei and all its associated resources should be released. This event may occur at any time after the connection has been made and is the last event to be received by this ei instance. libei guarantees that a EI_EVENT_DISCONNECT is provided to the caller even where the server does not send one. |
EI_EVENT_SEAT_ADDED | The server has added a seat available to this client. libei guarantees that any seat added has a corresponding EI_EVENT_SEAT_REMOVED event before EI_EVENT_DISCONNECT. libei guarantees that any device in this seat generates a EI_EVENT_DEVICE_REMOVED event before the EI_EVENT_SEAT_REMOVED event. |
EI_EVENT_SEAT_REMOVED | The server has removed a seat previously available to this client. The caller should release the struct ei_seat and all its associated resources. No devices will be added to this seat anymore. libei guarantees that any device in this seat generates a EI_EVENT_DEVICE_REMOVED event before the EI_EVENT_SEAT_REMOVED event. |
EI_EVENT_DEVICE_ADDED | The server has added a device for this client. The capabilities of the device may be a subset of the seat capabilities - it is up to the client to verify the minimum required capabilities are indeed set. libei guarantees that any device added has a corresponding EI_EVENT_DEVICE_REMOVED event before EI_EVENT_DISCONNECT. |
EI_EVENT_DEVICE_REMOVED | The server has removed a device belonging to this client. The caller should release the struct ei_device and all its associated resources. Any events sent through a removed device are discarded. When this event is received, the device is already removed. A caller does not need to call ei_device_close() event on this device. |
EI_EVENT_DEVICE_PAUSED | Any events sent from this device will be discarded until the next resume. The state of a device is not expected to change between pause/resume - for any significant state changes the server is expected to remove the device instead. |
EI_EVENT_DEVICE_RESUMED | The client may send events. |
EI_EVENT_KEYBOARD_MODIFIERS | The server has changed the modifier state on the device's keymap. See ei_event_keyboard_get_xkb_mods_depressed(), ei_event_keyboard_get_xkb_mods_latched(), ei_event_keyboard_get_xkb_mods_locked(), and ei_event_keyboard_get_xkb_group(). This event is sent in response to an external modifier state change. Where the client triggers a modifier state change in response to ei_device_keyboard_key(), no such event is sent. This event may arrive while a device is paused. |
EI_EVENT_FRAME | "Hardware" frame event. This event must be sent by the server and notifies the client that the previous set of events belong to the same logical hardware event.
|
EI_EVENT_DEVICE_START_EMULATING | The server is about to send events for a device. This event should be used by the client to clear the logical state of the emulated devices and/or provide UI to the user.
Note that a server start multiple emulating sequences simultaneously, depending on the devices available. For example, in a synergy-like situation, the server may start sending pointer and keyboard once the remote device logically entered the screen. |
EI_EVENT_DEVICE_STOP_EMULATING | The server stopped emulating events on this device, see EIS_EVENT_DEVICE_START_EMULATING.
|
EI_EVENT_POINTER_MOTION | A relative motion event with delta coordinates in logical pixels or mm, depending on the device type.
|
EI_EVENT_POINTER_MOTION_ABSOLUTE | An absolute motion event with absolute position within the device's regions or size, depending on the device type.
|
EI_EVENT_BUTTON_BUTTON | A button press or release event.
|
EI_EVENT_SCROLL_DELTA | A vertical and/or horizontal scroll event with logical-pixels or mm precision, depending on the device type.
|
EI_EVENT_SCROLL_STOP | An ongoing scroll sequence stopped.
|
EI_EVENT_SCROLL_CANCEL | An ongoing scroll sequence was cancelled.
|
EI_EVENT_SCROLL_DISCRETE | A vertical and/or horizontal scroll event with a discrete range in logical scroll steps, like a scroll wheel.
|
EI_EVENT_KEYBOARD_KEY | A key press or release event.
|
EI_EVENT_TOUCH_DOWN | Event for a single touch set down on the device's logical surface. A touch sequence is always down/up with an optional motion event in between. On multitouch capable devices, several touchs eqeuences may be active at any time.
|
EI_EVENT_TOUCH_UP | Event for a single touch released from the device's logical surface.
|
EI_EVENT_TOUCH_MOTION | Event for a single currently-down touch changing position (or other properties).
|
enum ei_keymap_type |
The set of supported keymap types for a struct ei_keymap.
Enumerator | |
---|---|
EI_KEYMAP_TYPE_XKB | A libxkbcommon-compatible XKB keymap. |
void ei_clock_set_now_func | ( | struct ei * | , |
ei_clock_now_func | func ) |
Override the function that returns the current time ei_now().
There is rarely a need to override this function. It exists for the libei-internal test suite.
void ei_configure_name | ( | struct ei * | ei, |
const char * | name ) |
Set the name for this client.
This is a suggestion to the server only and may not be honored.
The client name may be used for display to the user, for example in an authorization dialog that requires the user to approve a connection to the EIS implementation.
This function must be called immediately after ei_new() and before setting up a backend with ei_setup_backend_fd() or ei_setup_backend_socket().
void ei_dispatch | ( | struct ei * | ei | ) |
Main event dispatching function.
Reads events of the file descriptors and processes them internally. Use ei_get_event() to retrieve the events.
Dispatching does not necessarily queue events. This function should be called immediately once data is available on the file descriptor returned by libei_get_fd().
Return the device from this event.
For events of type EI_EVENT_CONNECT and EI_EVENT_DISCONNECT, this function returns NULL.
This does not increase the refcount of the device. Use eis_device_ref() to keep a reference beyond the immediate scope.
Return the seat from this event.
For events of type EI_EVENT_CONNECT and EI_EVENT_DISCONNECT, this function returns NULL.
This does not increase the refcount of the seat. Use eis_seat_ref() to keep a reference beyond the immediate scope.
uint64_t ei_event_get_time | ( | struct ei_event * | event | ) |
Return the time for the event of type EI_EVENT_FRAME in microseconds.
enum ei_event_type ei_event_get_type | ( | struct ei_event * | event | ) |
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.
For example, for EI_EVENT_TOUCH_UP this function returns the string "EI_EVENT_TOUCH_UP".
Release resources associated with this event.
This function always returns NULL.
The caller cannot increase the refcount of an event. Events should be considered transient data and not be held longer than required. ei_event_unref() is provided for consistency (as opposed to, say, ei_event_free()).
Return the next event from the event queue, removing it from the queue.
The returned object must be released by the caller with ei_event_unref()
int ei_get_fd | ( | struct ei * | ei | ) |
libei keeps a single file descriptor for all events.
This fd should be monitored for events by the caller's mainloop, e.g. using select(). When events are available on this fd, call ei_dispatch() immediately to process.
void * ei_get_user_data | ( | struct ei * | ei | ) |
Return the custom data pointer for this context.
libei will not look at or modify the pointer. Use ei_set_user_data() to change the user data.
bool ei_is_sender | ( | struct ei * | ei | ) |
Returns true if the context is was created with ei_new_sender() or false otherwise.
struct ei * ei_new | ( | void * | user_data | ) |
This is an alias for ei_new_sender.
struct ei * ei_new_receiver | ( | void * | user_data | ) |
Create a new receiver ei context.
The context is refcounted and must be released with ei_unref().
A receiver ei context receives events from the EIS implementation but cannot send events.
A context supports exactly one backend, set up with one of ei_setup_backend_fd() or ei_setup_backend_socket().
user_data | An opaque pointer to be returned with ei_get_user_data() |
struct ei * ei_new_sender | ( | void * | user_data | ) |
Create a new sender ei context.
The context is refcounted and must be released with ei_unref().
A sender ei context sends events to the EIS implementation but cannot receive events.
A context supports exactly one backend, set up with one of ei_setup_backend_fd() or ei_setup_backend_socket().
user_data | An opaque pointer to be returned with ei_get_user_data() |
uint64_t ei_now | ( | struct ei * | ei | ) |
By default, the returned timestamp is CLOCK_MONOTONIC for compatibility with evdev and libinput. This can be overridden with ei_clock_set_now_func().
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.
This call is useful for checking whether there is an event and/or what type of event it is.
Repeated calls to ei_peek_event() return the same event.
The returned event is refcounted, use ei_event_unref() to drop the reference.
A caller must not call ei_get_event() while holding a ref to an event returned by ei_peek_event(). Doing so is undefined behavior.
Increase the refcount of this struct by one.
Use ei_unref() to decrease the refcount.
void ei_set_user_data | ( | struct ei * | ei, |
void * | user_data ) |
Set a custom data pointer for this context.
libei will not look at or modify the pointer. Use ei_get_user_data() to retrieve a previously set user data.
int ei_setup_backend_fd | ( | struct ei * | ei, |
int | fd ) |
Initialize the ei context on the given socket file descriptor.
The ei context will initiate the conversation with the EIS server listening on the other end of this socket.
This is the preferred entry point for libei and should be the default used in new clients. It allows for private-by-default socket file descriptors and the policy on how the socket is created is delegated to the caller.
If the connection was successful, an event of type EI_EVENT_CONNECT or EI_EVENT_DISCONNECT will become available after a future call to ei_dispatch().
If the connection failed, use ei_unref() to release the data allocated for this context.
This function takes ownership of the file descriptor, and will close it when tearing down.
int ei_setup_backend_socket | ( | struct ei * | ei, |
const char * | socketpath ) |
Set this ei context to use the socket backend.
The ei context will connect to the socket at the given path and initiate the conversation with the EIS server listening on that socket.
If socketpath is NULL
, the value of the environment variable LIBEI_SOCKET
is used. If socketpath does not start with '/', it is relative to $XDG_RUNTIME_DIR
. If XDG_RUNTIME_DIR
is not set, this function fails.
If the connection was successful, an event of type EI_EVENT_CONNECT or EI_EVENT_DISCONNECT will become available after a future call to ei_dispatch().
If the connection failed, use ei_unref() to release the data allocated for this context.