libei 1.3.0
A library for Emulated Input
🍦 EIS - The server API

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 eiseis_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 eiseis_ref (struct eis *eis)
 
struct eiseis_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_eventeis_get_event (struct eis *eis)
 Returns the next event in the internal event queue (or NULL) and removes it from the queue.
 
struct eis_eventeis_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_eventeis_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_clienteis_event_get_client (struct eis_event *event)
 
struct eis_seateis_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_deviceeis_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_clienteis_client_ref (struct eis_client *client)
 
struct eis_clienteis_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 eiseis_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_seateis_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)
 

Detailed Description

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.

Typedef Documentation

◆ eis_clock_now_func

typedef uint64_t(* eis_clock_now_func) (struct eis *eis)

Optional override function for eis_now().

By default eis_now() returns the current timestamp in CLOCK_MONOTONIC. This may be overridden by a caller to provide a different timestamp.

There is rarely a need to override this function. It exists for the libeis-internal test suite.

Enumeration Type Documentation

◆ eis_device_capability

Enumerator
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 

◆ 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.

See also
eis_device_get_width
eis_device_get_height
Enumerator
EIS_DEVICE_TYPE_VIRTUAL 
EIS_DEVICE_TYPE_PHYSICAL 

◆ 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).

◆ eis_keymap_type

Enumerator
EIS_KEYMAP_TYPE_XKB 

Function Documentation

◆ 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().

Returns a file descriptor to be passed to ei_setup_backend_fd(), or a negative errno on failure.

◆ eis_client_connect()

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().

◆ 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.

◆ eis_client_get_context()

struct eis * eis_client_get_context ( struct eis_client * client)

◆ eis_client_get_name()

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.

◆ eis_client_get_user_data()

void * eis_client_get_user_data ( struct eis_client * eis_client)

◆ eis_client_is_sender()

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.

◆ eis_client_new_seat()

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.

◆ eis_client_ref()

struct eis_client * eis_client_ref ( struct eis_client * client)

◆ eis_client_set_user_data()

void eis_client_set_user_data ( struct eis_client * eis_client,
void * user_data )

◆ eis_client_unref()

struct eis_client * eis_client_unref ( struct eis_client * client)

◆ eis_clock_set_now_func()

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.

◆ eis_dispatch()

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().

◆ eis_event_get_client()

struct eis_client * eis_event_get_client ( struct eis_event * event)

◆ eis_event_get_device()

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.

◆ eis_event_get_seat()

struct eis_seat * eis_event_get_seat ( struct eis_event * event)

◆ eis_event_get_time()

uint64_t eis_event_get_time ( struct eis_event * event)

Return the time for the event of type EIS_EVENT_FRAME in microseconds.

Note
: Only events of type EIS_EVENT_FRAME carry a timestamp. For convenience, the timestamp for other device events is retrofitted by this library.
Returns
the event time in microseconds

◆ eis_event_get_type()

enum eis_event_type eis_event_get_type ( struct eis_event * event)

◆ eis_event_seat_has_capability()

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.

◆ eis_event_type_to_string()

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".

◆ eis_event_unref()

struct eis_event * eis_event_unref ( struct eis_event * event)

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()).

◆ eis_get_event()

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.

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().

◆ eis_get_fd()

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.

◆ eis_get_user_data()

void * eis_get_user_data ( struct eis * eis)

◆ eis_new()

struct eis * eis_new ( void * user_data)

Create a new libeis context with a refcount of 1.

◆ eis_now()

uint64_t eis_now ( struct eis * eis)
Returns
a timestamp for the current time to pass into eis_device_frame().

By default, the returned timestamp is CLOCK_MONOTONIC for compatibility with evdev and libinput. This can be overridden with eis_clock_set_now_func().

◆ eis_peek_event()

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.

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().

◆ eis_ref()

struct eis * eis_ref ( struct eis * eis)

◆ eis_set_user_data()

void eis_set_user_data ( struct eis * eis,
void * user_data )

◆ eis_setup_backend_fd()

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.

◆ eis_setup_backend_socket()

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.

◆ eis_unref()

struct eis * eis_unref ( struct eis * eis)