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 | eis |
struct | eis_client |
struct | eis_device |
struct | eis_seat |
struct | eis_event |
struct | eis_keymap |
struct | eis_touch |
struct | eis_region |
Regions are only available on devices of type EIS_DEVICE_TYPE_VIRTUAL. More... | |
Typedefs | |
typedef uint64_t(* | eis_clock_now_func) (struct eis *eis) |
Optional override function for eis_now(). | |
Enumerations | |
enum | eis_device_type { EIS_DEVICE_TYPE_VIRTUAL , EIS_DEVICE_TYPE_PHYSICAL } |
The device type determines what the device represents. More... | |
enum | eis_device_capability { EIS_DEVICE_CAP_POINTER , EIS_DEVICE_CAP_POINTER_ABSOLUTE , EIS_DEVICE_CAP_KEYBOARD , EIS_DEVICE_CAP_TOUCH , EIS_DEVICE_CAP_SCROLL , EIS_DEVICE_CAP_BUTTON } |
enum | eis_keymap_type { EIS_KEYMAP_TYPE_XKB } |
enum | eis_event_type { EIS_EVENT_CLIENT_CONNECT , EIS_EVENT_CLIENT_DISCONNECT , EIS_EVENT_SEAT_BIND , EIS_EVENT_DEVICE_CLOSED , EIS_EVENT_FRAME , EIS_EVENT_DEVICE_START_EMULATING , EIS_EVENT_DEVICE_STOP_EMULATING , EIS_EVENT_POINTER_MOTION , EIS_EVENT_POINTER_MOTION_ABSOLUTE , EIS_EVENT_BUTTON_BUTTON , EIS_EVENT_SCROLL_DELTA , EIS_EVENT_SCROLL_STOP , EIS_EVENT_SCROLL_CANCEL , EIS_EVENT_SCROLL_DISCRETE , EIS_EVENT_KEYBOARD_KEY , EIS_EVENT_TOUCH_DOWN , EIS_EVENT_TOUCH_UP , EIS_EVENT_TOUCH_MOTION } |
Functions | |
const char * | eis_event_type_to_string (enum eis_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 eis * | eis_new (void *user_data) |
Create a new libeis context with a refcount of 1. | |
void | eis_clock_set_now_func (struct eis *, eis_clock_now_func func) |
Override the function that returns the current time eis_now(). | |
struct eis * | eis_ref (struct eis *eis) |
struct eis * | eis_unref (struct eis *eis) |
void * | eis_get_user_data (struct eis *eis) |
void | eis_set_user_data (struct eis *eis, void *user_data) |
int | eis_setup_backend_fd (struct eis *ctx) |
Initialize the context that can take pre-configured socket file descriptors, see eis_backend_fd_add_client(). | |
int | eis_backend_fd_add_client (struct eis *ctx) |
Add a new client to a context set up with eis_setup_backend_fd(). | |
int | eis_setup_backend_socket (struct eis *ctx, const char *path) |
Initialize the context with a UNIX socket name. | |
int | eis_get_fd (struct eis *eis) |
libeis keeps a single file descriptor for all events. | |
void | eis_dispatch (struct eis *eis) |
Main event dispatching function. | |
struct eis_event * | eis_get_event (struct eis *eis) |
Returns the next event in the internal event queue (or NULL) and removes it from the queue. | |
struct eis_event * | eis_peek_event (struct eis *eis) |
Returns the next event in the internal event queue (or NULL) without removing that event from the queue, i.e. | |
struct eis_event * | eis_event_unref (struct eis_event *event) |
Release resources associated with this event. | |
enum eis_event_type | eis_event_get_type (struct eis_event *event) |
struct eis_client * | eis_event_get_client (struct eis_event *event) |
struct eis_seat * | eis_event_get_seat (struct eis_event *event) |
bool | eis_event_seat_has_capability (struct eis_event *event, enum eis_device_capability cap) |
For an event of type EIS_EVENT_SEAT_BIND, return the capabilities requested by the client. | |
struct eis_device * | eis_event_get_device (struct eis_event *event) |
Return the device from this event. | |
uint64_t | eis_event_get_time (struct eis_event *event) |
Return the time for the event of type EIS_EVENT_FRAME in microseconds. | |
struct eis_client * | eis_client_ref (struct eis_client *client) |
struct eis_client * | eis_client_unref (struct eis_client *client) |
void * | eis_client_get_user_data (struct eis_client *eis_client) |
void | eis_client_set_user_data (struct eis_client *eis_client, void *user_data) |
struct eis * | eis_client_get_context (struct eis_client *client) |
bool | eis_client_is_sender (struct eis_client *client) |
Returns true if the client is a sender, false otherwise. | |
const char * | eis_client_get_name (struct eis_client *client) |
Return the name set by this client. | |
void | eis_client_connect (struct eis_client *client) |
Allow connection from the client. | |
void | eis_client_disconnect (struct eis_client *client) |
Disconnect this client. | |
struct eis_seat * | eis_client_new_seat (struct eis_client *client, const char *name) |
Create a new logical seat with a given name. | |
uint64_t | eis_now (struct eis *eis) |
libeis is the server-side module. This API should be used by processes that have control over input devices, e.g. Wayland compositors.
For an example EIS implementation see the tools/
directory in the libei repository. At its core, an EIS implementation will
And for each client:
libei clients come in "sender" and "receiver" modes, depending on whether the client sends or receives events. A libeis context however may accept both sender and receiver clients, the EIS implementation works as corresponding receiver or sender for this client. It is up to the implementation to disconnect clients that it does not want to allow. See eis_client_is_sender() for details.
enum eis_device_type |
The device type determines what the device represents.
If the device type is EIS_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 EIS_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 | |
---|---|
EIS_DEVICE_TYPE_VIRTUAL | |
EIS_DEVICE_TYPE_PHYSICAL |
enum eis_event_type |
Enumerator | |
---|---|
EIS_EVENT_CLIENT_CONNECT | A client has connected. This is the first event from any new client. The server is expected to either call eis_client_connect() or eis_client_disconnect(). |
EIS_EVENT_CLIENT_DISCONNECT | The client has disconnected, any pending requests for this client should be discarded. |
EIS_EVENT_SEAT_BIND | The client wants to bind or unbind a capability on this seat. Devices associated with this seat should be sent to the client or removed if the capability is no longer bound |
EIS_EVENT_DEVICE_CLOSED | The client no longer listens to events from this device. The caller should released resources associated with this device. |
EIS_EVENT_FRAME | "Hardware" frame event. This event must be sent by the client and notifies the server that the previous set of events belong to the same logical hardware event. These events are only generated on a receiving EIS context. This event is most commonly used to implement multitouch (multiple touches may update within the same hardware scanout cycle). |
EIS_EVENT_DEVICE_START_EMULATING | The client is about to send events for a device. This event should be used by the server to clear the logical state of the emulated devices and/or provide UI to the user. These events are only generated on a receiving EIS context. Note that a client start multiple emulating sequences simultaneously, depending on the devices it received from the server. For example, in a synergy-like situation, the client may start emulating of pointer and keyboard once the remote device logically entered the screen. The server can cancel an ongoing emulating by suspending the device, see eis_device_suspend(). |
EIS_EVENT_DEVICE_STOP_EMULATING | Stop emulating events on this device, see EIS_EVENT_DEVICE_START_EMULATING. |
EIS_EVENT_POINTER_MOTION | A relative motion event with delta coordinates in logical pixels or mm, depending on the device type. |
EIS_EVENT_POINTER_MOTION_ABSOLUTE | An absolute motion event with absolute position within the device's regions or size, depending on the device type. |
EIS_EVENT_BUTTON_BUTTON | A button press or release event. |
EIS_EVENT_SCROLL_DELTA | A vertical and/or horizontal scroll event with logical-pixels or mm precision, depending on the device type. |
EIS_EVENT_SCROLL_STOP | An ongoing scroll sequence stopped. |
EIS_EVENT_SCROLL_CANCEL | An ongoing scroll sequence was cancelled. |
EIS_EVENT_SCROLL_DISCRETE | A vertical and/or horizontal scroll event with a discrete range in logical scroll steps, like a scroll wheel. |
EIS_EVENT_KEYBOARD_KEY | A key press or release event. |
EIS_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. |
EIS_EVENT_TOUCH_UP | Event for a single touch released from the device's logical surface. |
EIS_EVENT_TOUCH_MOTION | Event for a single currently-down touch changing position (or other properties). |
enum eis_keymap_type |
int eis_backend_fd_add_client | ( | struct eis * | ctx | ) |
Add a new client to a context set up with eis_setup_backend_fd().
Returns a file descriptor to be passed to ei_setup_backend_fd(), or a negative errno on failure.
void eis_client_connect | ( | struct eis_client * | client | ) |
Allow connection from the client.
This can only be done once, further calls to this functions are ignored.
When receiving an event of type EIS_EVENT_CLIENT_CONNECT, the server should connect client as soon as possible to allow communication with the server. If the client is not authorized to talk to the server, call eis_client_disconnect().
void eis_client_disconnect | ( | struct eis_client * | client | ) |
Disconnect this client.
Once disconnected the client may no longer talk to this context, all resources associated with this client should be released.
It is not necessary to call this function when an EIS_EVENT_CLIENT_DISCONNECT event is received.
struct eis * eis_client_get_context | ( | struct eis_client * | client | ) |
const char * eis_client_get_name | ( | struct eis_client * | client | ) |
Return the name set by this client.
The server is under no obligation to use this name.
void * eis_client_get_user_data | ( | struct eis_client * | eis_client | ) |
bool eis_client_is_sender | ( | struct eis_client * | client | ) |
Returns true if the client is a sender, false otherwise.
A sender client may send events to the EIS implementation, a receiver client expects to receive events from the EIS implementation.
struct eis_seat * eis_client_new_seat | ( | struct eis_client * | client, |
const char * | name ) |
Create a new logical seat with a given name.
Devices available to a client belong to a bound seat, or in other words: a client cannot receive events from a device until it binds to a seat and receives all devices from that seat.
This seat is not immediately active, use eis_seat_add() to bind this seat on the client and notify the client of it's availability.
The returned seat is refcounted, use eis_seat_unref() to drop the reference.
struct eis_client * eis_client_ref | ( | struct eis_client * | client | ) |
void eis_client_set_user_data | ( | struct eis_client * | eis_client, |
void * | user_data ) |
struct eis_client * eis_client_unref | ( | struct eis_client * | client | ) |
void eis_clock_set_now_func | ( | struct eis * | , |
eis_clock_now_func | func ) |
Override the function that returns the current time eis_now().
There is rarely a need to override this function. It exists for the libeis-internal test suite.
void eis_dispatch | ( | struct eis * | eis | ) |
Main event dispatching function.
Reads events of the file descriptors and processes them internally. Use eis_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 eis_get_fd().
struct eis_client * eis_event_get_client | ( | struct eis_event * | event | ) |
struct eis_device * eis_event_get_device | ( | struct eis_event * | event | ) |
Return the device from this event.
This does not increase the refcount of the device. Use eis_device_ref() to keep a reference beyond the immediate scope.
uint64_t eis_event_get_time | ( | struct eis_event * | event | ) |
Return the time for the event of type EIS_EVENT_FRAME in microseconds.
enum eis_event_type eis_event_get_type | ( | struct eis_event * | event | ) |
bool eis_event_seat_has_capability | ( | struct eis_event * | event, |
enum eis_device_capability | cap ) |
For an event of type EIS_EVENT_SEAT_BIND, return the capabilities requested by the client.
This is the set of all capabilities bound by the client as of this event, not just the changed ones.
const char * eis_event_type_to_string | ( | enum | eis_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 EIS_EVENT_TOUCH_UP this function returns the string "EIS_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. eis_event_unref() is provided for consistency (as opposed to, say, eis_event_free()).
Returns the next event in the internal event queue (or NULL) and removes it from the queue.
The returned event is refcounted, use eis_event_unref() to drop the reference.
You must not call this function while holding a reference to an event returned by eis_peek_event().
int eis_get_fd | ( | struct eis * | eis | ) |
libeis 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 eis_dispatch() immediately to process.
void * eis_get_user_data | ( | struct eis * | eis | ) |
struct eis * eis_new | ( | void * | user_data | ) |
Create a new libeis context with a refcount of 1.
uint64_t eis_now | ( | struct eis * | eis | ) |
By default, the returned timestamp is CLOCK_MONOTONIC for compatibility with evdev and libinput. This can be overridden with eis_clock_set_now_func().
Returns the next event in the internal event queue (or NULL) without removing that event from the queue, i.e.
the next call to eis_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 eis_peek_event() return the same event.
The returned event is refcounted, use eis_event_unref() to drop the reference.
A caller must not call eis_get_event() while holding a ref to an event returned by eis_peek_event().
void eis_set_user_data | ( | struct eis * | eis, |
void * | user_data ) |
int eis_setup_backend_fd | ( | struct eis * | ctx | ) |
Initialize the context that can take pre-configured socket file descriptors, see eis_backend_fd_add_client().
This is the preferred backend to use for EIS implementations as it keeps the file descriptors private for each client and is not subject to race conditions or unauthorized clients attempting to connect.
int eis_setup_backend_socket | ( | struct eis * | ctx, |
const char * | path ) |
Initialize the context with a UNIX socket name.
If the path does not start with / it is relative to $XDG_RUNTIME_DIR.
The socket will be accessible by any client with permissions to do so and it is up to the EIS implementation to authenticate clients. In almost all cases, the EIS implementation should use eis_setup_backend_fd() instead. This backend is primarily useful for testing and debugging.