libei is the client-side module. More...

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

Typedefs
typedef void(*	ei_log_handler) (struct ei ei, enum ei_log_priority priority, const char message, bool is_continuation)
	The log handler for library logging. More...

Enumerations
enum	ei_device_capability { EI_DEVICE_CAP_POINTER, EI_DEVICE_CAP_POINTER_ABSOLUTE, EI_DEVICE_CAP_KEYBOARD, EI_DEVICE_CAP_TOUCH }
	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_keymap_source { EI_KEYMAP_SOURCE_CLIENT, EI_KEYMAP_SOURCE_SERVER }
	Identifies who provided 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_SUSPENDED, EI_EVENT_DEVICE_RESUMED }

enum	ei_log_priority { EI_LOG_PRIORITY_DEBUG, EI_LOG_PRIORITY_INFO, EI_LOG_PRIORITY_WARNING, EI_LOG_PRIORITY_ERROR }

Functions
struct ei *	ei_new (void *user_data)
	Create a new ei context. More...

void	ei_log_set_handler (struct ei *ei, ei_log_handler log_handler)
	Change the log handler for this context. More...

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_configure_name (struct ei ei, const char name)
	Set the name for this client. More...

int	ei_setup_backend_socket (struct ei ei, const char socketpath)
	Set this ei context to use the socket backend. More...

int	ei_setup_backend_fd (struct ei *ei, int fd)
	Initialize the ei context on the given socket. More...

int	ei_setup_backend_portal (struct ei *ei)
	Connect to the `org.freedesktop.portal.Desktop` portal. More...

int	ei_setup_backend_portal_busname (struct ei ei, const char busname)
	Connect to an `org.freedesktop.portal.Desktop` implementation on the given busname. More...

struct ei *	ei_ref (struct ei *ei)
	Increase the refcount of this struct by one. More...

struct ei *	ei_unref (struct ei *ei)
	Decrease the refcount of this struct by one. More...

void	ei_set_user_data (struct ei ei, void user_data)
	Set a custom data pointer for this context. More...

void *	ei_get_user_data (struct ei *ei)
	Return the custom data pointer for this context. More...

int	ei_get_fd (struct ei *ei)
	libei keeps a single file descriptor for all events. More...

void	ei_dispatch (struct ei *ei)
	Main event dispatching function. More...

struct ei_event *	ei_get_event (struct ei *ei)
	Return the next event from the event queue, removing it from the queue. More...

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

struct ei_event *	ei_event_unref (struct ei_event *event)
	Release resources associated with this event. More...

const char *	ei_seat_get_name (struct ei_seat *seat)

bool	ei_seat_has_capability (struct ei_seat *seat, enum ei_device_capability cap)

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 - the client implementation context this seat is associated with. More...

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

uint64_t	ei_event_get_time (struct ei_event *event)

struct ei_device *	ei_device_ref (struct ei_device *device)
	Increase the refcount of this struct by one. More...

struct ei_device *	ei_device_unref (struct ei_device *device)
	Decrease the refcount of this struct by one. More...

struct ei_device *	ei_device_new (struct ei_seat *ei_seat)
	Create a new device in the given seat. More...

struct ei_seat *	ei_device_get_seat (struct ei_device *device)

void	ei_seat_set_user_data (struct ei_seat seat, void user_data)
	Set a custom data pointer for this context. More...

void *	ei_seat_get_user_data (struct ei_seat *seat)
	Return the custom data pointer for this context. More...

void	ei_device_set_user_data (struct ei_device device, void user_data)
	Set a custom data pointer for this context. More...

void *	ei_device_get_user_data (struct ei_device *device)
	Return the custom data pointer for this context. More...

void	ei_device_configure_name (struct ei_device device, const char name)
	Set the name for this device. More...

bool	ei_device_configure_capability (struct ei_device *device, enum ei_device_capability cap)
	Enable the given capability on this device. More...

void	ei_device_pointer_configure_range (struct ei_device *device, uint32_t width, uint32_t height)
	Set the range of the absolute pointer device in logical pixels. More...

void	ei_device_touch_configure_range (struct ei_device *device, uint32_t width, uint32_t height)
	Set the range of the touch device in logical pixels. More...

struct ei_keymap *	ei_keymap_new (enum ei_keymap_type type, int fd, size_t size)
	Create a new keymap of the given `type`. More...

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

int	ei_keymap_get_fd (struct ei_keymap *keymap)
	Return a memmap-able file descriptor pointing to the keymap used by the device. More...

enum ei_keymap_source	ei_keymap_get_source (struct ei_keymap *keymap)
	Returns the source for the keymap on this device, if any. More...

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

struct ei_keymap *	ei_keymap_ref (struct ei_keymap *keymap)
	Increase the refcount of this struct by one. More...

struct ei_keymap *	ei_keymap_unref (struct ei_keymap *keymap)
	Decrease the refcount of this struct by one. More...

void	ei_device_keyboard_configure_keymap (struct ei_device device, struct ei_keymap keymap)
	Request this keymap for this device with the EI_DEVICE_CAP_KEYBOARD capability. More...

void	ei_device_add (struct ei_device *device)
	Request that the device be added to the server. More...

void	ei_device_remove (struct ei_device *device)
	Notify the server that the device should be removed. More...

const char *	ei_device_get_name (struct ei_device *device)
	Return the name of this device. More...

bool	ei_device_has_capability (struct ei_device *device, enum ei_device_capability cap)
	Return true if the device has the requested capability. More...

uint32_t	ei_device_pointer_get_width (struct ei_device *device)
	Return the requested width for an EI_DEVICE_CAP_POINTER_ABSOLUTE device. More...

uint32_t	ei_device_pointer_get_height (struct ei_device *device)
	Return the requested height for an EI_DEVICE_CAP_POINTER_ABSOLUTE device. More...

uint32_t	ei_device_touch_get_width (struct ei_device *device)
	Return the requested width for an EI_DEVICE_CAP_TOUCH device. More...

uint32_t	ei_device_touch_get_height (struct ei_device *device)
	Return the requested height for an EI_DEVICE_CAP_TOUCH device. More...

struct ei_keymap *	ei_device_keyboard_get_keymap (struct ei_device *device)
	Return the keymap for this device or `NULL`. More...

struct ei_device *	ei_keymap_get_context (struct ei_keymap *keymap)
	Return the struct ei_device this keymap is associated with. More...

struct ei *	ei_device_get_context (struct ei_device *device)
	Return the struct EI - the client implementation context this device is associated with. More...

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

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

void	ei_device_pointer_button (struct ei_device *device, uint32_t button, bool is_press)
	Generate a button event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability. More...

void	ei_device_pointer_scroll (struct ei_device *device, double x, double y)
	Generate a scroll event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability. More...

void	ei_device_pointer_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_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability. More...

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

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

void	ei_touch_down (struct ei_touch *touch, double x, double y)
	This function can only be called once on an ei_touch object. More...

void	ei_touch_motion (struct ei_touch *touch, double x, double y)
	Move this touch to the new coordinates. More...

void	ei_touch_up (struct ei_touch *touch)
	Release this touch. More...

struct ei_touch *	ei_touch_ref (struct ei_touch *touch)
	Increase the refcount of this struct by one. More...

struct ei_touch *	ei_touch_unref (struct ei_touch *touch)
	Decrease the refcount of this struct by one. More...

void	ei_touch_set_user_data (struct ei_touch touch, void user_data)
	Return the custom data pointer for this context. More...

void *	ei_touch_get_user_data (struct ei_touch *touch)
	Set a custom data pointer for this context. More...

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

Detailed Description

libei is the client-side module.

This API should be used by processes that need to emulate devices.

Typedef Documentation

◆ ei_log_handler

typedef void(* ei_log_handler) (struct ei *ei, enum ei_log_priority priority, const char *message, bool is_continuation)

The log handler for library logging.

This handler is only called for messages with a log level equal or greater than than the one set in ei_log_set_priority().

Parameters

message	The log message as a null-terminated string
is_continuation	The message is a continuation of the previous message. The caller should skip any per-line-based prefixes.

Enumeration Type Documentation

◆ ei_device_capability

enum ei_device_capability

The set of supported capabilities.

A device may have one or more capabilities but never zero - a EIS implementation must reject any device with zero capabilities.

Capabilities are requested by the client but the EIS implementation may further reduce the capabilities. For example, a client may request the pointer and keyboard capability but only the former is permitted by the server. Any keyboard events sent by such a device events will be treated as client bug and discarded.

See eis_device_has_capability().

Enumerator
EI_DEVICE_CAP_POINTER
EI_DEVICE_CAP_POINTER_ABSOLUTE
EI_DEVICE_CAP_KEYBOARD
EI_DEVICE_CAP_TOUCH

◆ ei_event_type

enum ei_event_type

Enumerator
EI_EVENT_CONNECT	The server has approved the connection to this client. The client may now add devices with ei_device_add(). 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 - the client implementation 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 can be created through 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 not match the requested capabilities - it is up to the client to verify the minimum required capabilities are indeed set. Where the server refuses to add a specific device or the intersection of requested capabilities and allowed capabilities is zero, the server sends EI_EVENT_DEVICE_REMOVED instead. 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_remove() event on this device.
EI_EVENT_DEVICE_SUSPENDED	Any events sent from this device will be discarded until the next resume.
EI_EVENT_DEVICE_RESUMED	The client may send events.

◆ ei_keymap_source

enum ei_keymap_source

Identifies who provided a struct ei_keymap.

Enumerator
EI_KEYMAP_SOURCE_CLIENT	The keymap is the one provided by the client.
EI_KEYMAP_SOURCE_SERVER	The keymap is provided by the server.

◆ ei_keymap_type

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.

◆ ei_log_priority

enum ei_log_priority

Enumerator
EI_LOG_PRIORITY_DEBUG
EI_LOG_PRIORITY_INFO
EI_LOG_PRIORITY_WARNING
EI_LOG_PRIORITY_ERROR

Function Documentation

◆ ei_configure_name()

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_socket() or ei_setup_backend_fd().

◆ ei_device_add()

void ei_device_add ( struct ei_device * device )

Request that the device be added to the server.

The server will respond with an EI_EVENT_DEVICE_ADDED or EI_EVENT_DEVICE_REMOVED event once the request has been processed.

A client can assume that an EI_EVENT_DEVICE_REMOVED event is sent for any device for which ei_device_add() was called before the EI_EVENT_DISCONNECT. Where a client gets disconnected libei will emulate that event.

A client may not send events through this device until it has been added by the server.

Devices should only be added once all events from ei_get_event() have been processed. It is considered a client bug to add a device to a seat after the SEAT_REMOVED has been received by libei.

◆ ei_device_configure_capability()

bool ei_device_configure_capability	(	struct ei_device *	device,
		enum ei_device_capability	cap
	)

Enable the given capability on this device.

This is a suggestion only, the server may ignore this capability. Use ei_device_has_capability() upon receiving EI_EVENT_DEVICE_ADDED to check for the actual capabilities of the device.

This function has no effect if called after ei_device_add()

Parameters

device	The EI device
cap	The capability to enable

◆ ei_device_configure_name()

void ei_device_configure_name	(	struct ei_device *	device,
		const char *	name
	)

Set the name for this device.

This is a suggestion only, the server may ignore the name and assign a different one (or none). Use ei_device_get_name() upon receiving EI_EVENT_DEVICE_ADDED to get the server-assigned name.

This function has no effect if called after ei_device_add()

libei may quietly ignore names of unreasonable length. This is not something a normal caller ever needs to worry about.

Parameters

device	The EI device
name	A name suggestion for the device

◆ ei_device_get_context()

struct ei* ei_device_get_context ( struct ei_device * device )

Return the struct EI - the client implementation context this device is associated with.

◆ ei_device_get_name()

const char* ei_device_get_name ( struct ei_device * device )

Return the name of this device.

The return value of this function is constant after receiving the EI_EVENT_DEVICE_ADDED event. Before then, the returned string may be freed at any time, callers must strdup() the returned value if they need to keep the name around.

Returns: the name of the device (if any) or NULL

◆ ei_device_get_seat()

struct ei_seat* ei_device_get_seat ( struct ei_device * device )

◆ ei_device_get_user_data()

void* ei_device_get_user_data ( struct ei_device * device )

Return the custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_device_get_user_data() to change the user data.

◆ ei_device_has_capability()

bool ei_device_has_capability	(	struct ei_device *	device,
		enum ei_device_capability	cap
	)

Return true if the device has the requested capability.

Device capabilities are constant after the EI_EVENT_DEVICE_ADDED event.

To change a device's capability, the device must be removed and a new device with the different capabilities must be added.

◆ ei_device_keyboard_configure_keymap()

void ei_device_keyboard_configure_keymap	(	struct ei_device *	device,
		struct ei_keymap *	keymap
	)

Request this keymap for this device with the EI_DEVICE_CAP_KEYBOARD capability.

The keymap for this device is a suggestion to the server, the actual keymap used by this device is provided with the EI_EVENT_DEVICE_ADDED event. It is the client's responsibility to handle the situation where the server assigns a specific keymap (or none) that differs to the requested keymap.

Note that keymap handling for individual input devices is largely left to private implementation details in the server. For example, modifier state or group handling may differ between server implementations.

A keymap can only be used once and for one device only. Once a keymap has been assigned to a device, the caller may drop remaining references using ei_keymap_unref().

This function can only be called once per device, further calls are ignored.

This function has no effect if called after ei_device_add(). To change the keymap, the device must be removed and re-added with a different keymap.

Parameters

device	The EI device
keymap	A non-`NULL` keymap

◆ ei_device_keyboard_get_keymap()

struct ei_keymap* ei_device_keyboard_get_keymap ( struct ei_device * device )

Return the keymap for this device or NULL.

The keymap is constant for the lifetime of the device after the EI_EVENT_DEVICE_ADDED was received and applies to this device individually.

If this function returns NULL, this device does not have an individual keymap assigned. What keymap applies to the device in this case is a server implementation detail.

This does not increase the refcount of the keymap. Use ei_keymap_ref() to keep a reference beyond the immediate scope.

FIXME: the current API makes it impossible to know when the keymap has been consumed so the file stays open forever.

◆ ei_device_keyboard_key()

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.

Keys use the evdev scan codes as defined in linux/input-event-codes.h

Parameters

device	The EI device
keycode	The key code
is_press	true for key down, false for key up

◆ ei_device_new()

struct ei_device* ei_device_new ( struct ei_seat * ei_seat )

Create a new device in the given seat.

This device is a proxy representing the server's device and should be used for initial device configuration. It does not represent the server-created device until the EI_EVENT_DEVICE_ADDED for this device has been received.

Use the configure API (e.g. ei_device_configure_capability()) to set up the device, then call ei_device_add() to request creation of the device by the server.

Note: A caller that does not want to add a created device to a seat must call ei_device_remove() for this device to ensure the resources are released.

The returned object must be released by the caller with ei_event_unref()

◆ ei_device_pointer_button()

void ei_device_pointer_button	(	struct ei_device *	device,
		uint32_t	button,
		bool	is_press
	)

Generate a button event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability.

Button codes must match the defines in linux/input-event-codes.h

Parameters

device	The EI device
button	The button code
is_press	true for button press, false for button release

◆ ei_device_pointer_configure_range()

void ei_device_pointer_configure_range	(	struct ei_device *	device,
		uint32_t	width,
		uint32_t	height
	)

Set the range of the absolute pointer device in logical pixels.

The allowable range for absolute pointer motion is [0, max) for each axis, i.e. zero inclusive, max exclusive. Coordinates outside this range may be discarded or clipped silently by the library.

The pointer range is constant. Where the pointer range is no longer applicable, the client needs to remove the device and create and add a new device with the updated pointer range.

The server may use this in mapping heuristics. For example, a pointer device with a pixel range of 1920x1200 may be automatically mapped by the server to the monitor with this range, or a pointer device with a ratio of R may be mapped to the monitor with the same ratio. This is not a guarantee, the mapping policy is a private implementation detail in the server. It is assumed that the client has other communication channels (e.g. Wayland) to obtain the pointer range it needs to emulate input on a device and channels to notify the server of desired mappings (e.g. gsettings).

It is a client bug to send pointer values outside this range. It is a client bug to call this function on a device without the EI_DEVICE_CAP_POINTER_ABSOLUTE capability.

This function has no effect if called after ei_device_add()

Parameters

device	The EI device
width	The maximum (exclusive) x value in logical pixels
height	The maximum (exclusive) y value in logical pixels

◆ ei_device_pointer_get_height()

uint32_t ei_device_pointer_get_height ( struct ei_device * device )

Return the requested height for an EI_DEVICE_CAP_POINTER_ABSOLUTE device.

The width and height is constant after the EI_EVENT_DEVICE_ADDED event.

◆ ei_device_pointer_get_width()

uint32_t ei_device_pointer_get_width ( struct ei_device * device )

Return the requested width for an EI_DEVICE_CAP_POINTER_ABSOLUTE device.

The width and height is constant after the EI_EVENT_DEVICE_ADDED event.

◆ ei_device_pointer_motion()

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.

Parameters

device	The EI device
x	The x movement in logical pixels
y	The y movement in logical pixels

◆ ei_device_pointer_motion_absolute()

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.

The required conditions are:

0 <= x < width
0 <= y < height If these conditions are not met, the event is silently discarded.

Parameters

device	The EI device
x	The x position in logical pixels
y	The y position in logical pixels

◆ ei_device_pointer_scroll()

void ei_device_pointer_scroll	(	struct ei_device *	device,
		double	x,
		double	y
	)

Generate a scroll event on a device with the EI_DEVICE_CAP_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability.

Note: The server is responsible for emulateing discrete scrolling based on the pixel value, do not call ei_device_pointer_scroll_discrete() for the same input event.

Parameters

device	The EI device
x	The x scroll distance in logical pixels
y	The y scroll distance in logical pixels

See also: ei_device_pointer_scroll_discrete

◆ ei_device_pointer_scroll_discrete()

void ei_device_pointer_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_POINTER_ABSOLUTE or EI_DEVICE_CAP_POINTER capability.

A discrete scroll event is based logical scroll units (equivalent to one mouse wheel click). The value for one scroll unit is 120, a fraction or multiple thereof represents a fraction or multiple of a wheel click.

Note: The server is responsible for emulating pixel-based scrolling based on the discrete value, do not call ei_device_pointer_scroll() for the same input event.

Parameters

device	The EI device
x	The x scroll distance in fractions or multiples of 120
y	The y scroll distance in fractions or multiples of 120

See also: ei_device_pointer_scroll

◆ ei_device_ref()

struct ei_device* ei_device_ref ( struct ei_device * device )

Increase the refcount of this struct by one.

Use ei_device_unref() to decrease the refcount.

Returns: the argument passed into the function

◆ ei_device_remove()

void ei_device_remove ( struct ei_device * device )

Notify the server that the device should be removed.

Due to the asynchronous nature of the client-server interaction, events for this device may still be in transit. The server will send an EI_EVENT_DEVICE_REMOVED event for this device. After that event, device is considered removed by the server.

A client can assume that an EI_EVENT_DEVICE_REMOVED event is sent for any device for which ei_device_remove() was called before the EI_EVENT_DISCONNECT. Where a client gets disconnected libei will emulate that event.

This does not release any resources associated with this device, use ei_device_unref() for any references held by the client.

◆ ei_device_set_user_data()

void ei_device_set_user_data	(	struct ei_device *	device,
		void *	user_data
	)

Set a custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_device_get_user_data() to retrieve a previously set user data.

◆ ei_device_touch_configure_range()

void ei_device_touch_configure_range	(	struct ei_device *	device,
		uint32_t	width,
		uint32_t	height
	)

Set the range of the touch device in logical pixels.

This function is identical to ei_device_pointer_configure_range() but configures the touch range instead.

◆ ei_device_touch_get_height()

uint32_t ei_device_touch_get_height ( struct ei_device * device )

Return the requested height for an EI_DEVICE_CAP_TOUCH device.

The width and height is constant after the EI_EVENT_DEVICE_ADDED event.

◆ ei_device_touch_get_width()

uint32_t ei_device_touch_get_width ( struct ei_device * device )

Return the requested width for an EI_DEVICE_CAP_TOUCH device.

The width and height is constant after the EI_EVENT_DEVICE_ADDED event.

◆ ei_device_touch_new()

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.

This touch does not immediately send events, use ei_touch_down(), ei_touch_motion(), and ei_touch_up().

The returned touch has a refcount of at least 1, use ei_touch_unref() to release resources associated with this touch

◆ ei_device_unref()

struct ei_device* ei_device_unref ( struct ei_device * device )

Decrease the refcount of this struct by one.

When the refcount reaches zero, the context disconnects from the server and all allocated resources are released.

Returns: always NULL

◆ ei_dispatch()

void ei_dispatch ( struct ei * ei )

Main event dispatching function.

Reads events of the file descriptors and processes them internally. Use libei_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().

◆ ei_event_get_device()

struct ei_device* ei_event_get_device ( struct ei_event * event )

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.

◆ ei_event_get_seat()

struct ei_seat* ei_event_get_seat ( struct ei_event * event )

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.

◆ ei_event_get_time()

uint64_t ei_event_get_time ( struct ei_event * event )

Returns: the event time in microseconds

◆ ei_event_get_type()

enum ei_event_type ei_event_get_type ( struct ei_event * event )

Returns: the type of this event

◆ ei_event_unref()

struct ei_event* ei_event_unref ( struct ei_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. ei_event_unref() is provided for consistency (as opposed to, say, ei_event_free()).

◆ ei_get_event()

struct ei_event* ei_get_event ( struct ei * ei )

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

◆ ei_get_fd()

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 libei_dispatch() immediately to process.

◆ ei_get_user_data()

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.

◆ ei_keymap_get_context()

struct ei_device* ei_keymap_get_context ( struct ei_keymap * keymap )

Return the struct ei_device this keymap is associated with.

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

Between ei_device_keyboard_configure_keymap() and libei processing an EI_EVENT_DEVICE_ADDED event, the returned device is the one provided in ei_device_keyboard_configure_keymap().

After processing and if the server changed the keymap or set the keymap to NULL, this keymap may no longer be in use by the device and future calls to this function return NULL.

◆ ei_keymap_get_fd()

int ei_keymap_get_fd ( struct ei_keymap * keymap )

Return a memmap-able file descriptor pointing to the keymap used by the device.

The keymap is constant for the lifetime of the device and assigned to this device individually.

◆ ei_keymap_get_size()

size_t ei_keymap_get_size ( struct ei_keymap * keymap )

Returns: the size of the keymap in bytes

◆ ei_keymap_get_source()

enum ei_keymap_source ei_keymap_get_source ( struct ei_keymap * keymap )

Returns the source for the keymap on this device, if any.

This is a convenience function for the client to check if its keymap was accepted.

Where ei_device_keyboard_get_keymap() returns a value other NULL and this function returns EI_KEYMAP_SOURCE_CLIENT, the keymap is the one provided with ei_device_keyboard_configure_keymap().

Where ei_device_keyboard_get_keymap() returns a value other than NULL and this function returns EI_KEYMAP_SOURCE_SERVER, the keymap is one created by the server and not the one provided with ei_device_keyboard_configure_keymap().

◆ ei_keymap_get_type()

enum ei_keymap_type ei_keymap_get_type ( struct ei_keymap * keymap )

Returns the type for this keymap.

The type specifies how to interpret the data at the file descriptor returned by ei_keymap_get_fd().

◆ ei_keymap_new()

struct ei_keymap* ei_keymap_new	(	enum ei_keymap_type	type,
		int	fd,
		size_t	size
	)

Create a new keymap of the given type.

This keymap does not immediately apply to the device, use ei_device_keyboard_configure_keymap() to apply this keymap. A keymap may only be applied once and to a single device.

The returned keymap has a refcount of at least 1, use ei_keymap_unref() to release resources associated with this keymap.

Parameters

type	The type of the keymap.
fd	A memmap-able file descriptor of size `size` pointing to the keymap used by this device. `fd` can be closed by the caller after this function completes.
size	The size of the data at `fd` in bytes

Returns: A keymap object or NULL on failure.

◆ ei_keymap_ref()

struct ei_keymap* ei_keymap_ref ( struct ei_keymap * keymap )

Increase the refcount of this struct by one.

Use ei_keymap_unref() to decrease the refcount.

Returns: the argument passed into the function

◆ ei_keymap_unref()

struct ei_keymap* ei_keymap_unref ( struct ei_keymap * keymap )

Decrease the refcount of this struct by one.

When the refcount reaches zero, the context disconnects from the server and all allocated resources are released.

Returns: always NULL

◆ ei_log_get_priority()

enum ei_log_priority ei_log_get_priority ( const struct ei * ei )

◆ ei_log_set_handler()

void ei_log_set_handler	(	struct ei *	ei,
		ei_log_handler	log_handler
	)

Change the log handler for this context.

If the log handler is NULL, the built-in default log function is used.

Parameters

ei	The EI context
log_handler	The log handler or NULL to use the default log handler.

◆ ei_log_set_priority()

void ei_log_set_priority	(	struct ei *	ei,
		enum ei_log_priority	priority
	)

◆ ei_new()

struct ei* ei_new ( void * user_data )

Create a new ei context.

The context is refcounted and must be released with ei_unref().

A context supports exactly one backend, set up with one of ei_setup_backend_socket() or ei_setup_backend_fd().

Parameters

user_data An opaque pointer to be returned with ei_get_user_data()

See also: ei_set_user_data; ei_get_user_data; ei_setup_backend_fd; ei_setup_backend_socket

◆ ei_peek_event()

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.

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.

◆ ei_ref()

struct ei* ei_ref ( struct ei * ei )

Increase the refcount of this struct by one.

Use ei_unref() to decrease the refcount.

Returns: the argument passed into the function

◆ ei_seat_get_context()

struct ei* ei_seat_get_context ( struct ei_seat * seat )

Return the struct EI - the client implementation context this seat is associated with.

◆ ei_seat_get_name()

const char* ei_seat_get_name ( struct ei_seat * seat )

◆ ei_seat_get_user_data()

void* ei_seat_get_user_data ( struct ei_seat * seat )

Return the custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_seat_get_user_data() to change the user data.

◆ ei_seat_has_capability()

bool ei_seat_has_capability	(	struct ei_seat *	seat,
		enum ei_device_capability	cap
	)

◆ ei_seat_ref()

struct ei_seat* ei_seat_ref ( struct ei_seat * seat )

◆ ei_seat_set_user_data()

void ei_seat_set_user_data	(	struct ei_seat *	seat,
		void *	user_data
	)

Set a custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_seat_get_user_data() to retrieve a previously set user data.

◆ ei_seat_unref()

struct ei_seat* ei_seat_unref ( struct ei_seat * seat )

◆ ei_set_user_data()

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.

◆ ei_setup_backend_fd()

int ei_setup_backend_fd	(	struct ei *	ei,
		int	fd
	)

Initialize the ei context on the given socket.

The ei context will initiate the conversation with the EIS server listening on the other end of this socket.

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.

Returns: zero on success or a negative errno on failure

◆ ei_setup_backend_portal()

int ei_setup_backend_portal ( struct ei * ei )

Connect to the org.freedesktop.portal.Desktop portal.

Returns: 0 on success or a negative errno on failure

◆ ei_setup_backend_portal_busname()

int ei_setup_backend_portal_busname	(	struct ei *	ei,
		const char *	busname
	)

Connect to an org.freedesktop.portal.Desktop implementation on the given busname.

Outside of testing environments, there is usually no reason to use this function, use ei_setup_backend_portal() instead.

Returns: 0 on success or a negative errno on failure

◆ ei_setup_backend_socket()

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.

Returns: zero on success or a negative errno on failure

◆ ei_touch_down()

void ei_touch_down	(	struct ei_touch *	touch,
		double	x,
		double	y
	)

This function can only be called once on an ei_touch object.

Further calls to ei_touch_down() on the same object are silently ignored.

The required conditions are:

0 <= x < width
0 <= y < height

Parameters

touch	A newly created touch
x	The x position in logical pixels
y	The y position in logical pixels

◆ ei_touch_get_device()

struct ei_device* ei_touch_get_device ( struct ei_touch * touch )

Returns: the device this touch originates on

◆ ei_touch_get_user_data()

void* ei_touch_get_user_data ( struct ei_touch * touch )

Set a custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_touch_get_user_data() to retrieve a previously set user data.

◆ ei_touch_motion()

void ei_touch_motion	(	struct ei_touch *	touch,
		double	x,
		double	y
	)

Move this touch to the new coordinates.

◆ ei_touch_ref()

struct ei_touch* ei_touch_ref ( struct ei_touch * touch )

Increase the refcount of this struct by one.

Use ei_touch_unref() to decrease the refcount.

Returns: the argument passed into the function

◆ ei_touch_set_user_data()

void ei_touch_set_user_data	(	struct ei_touch *	touch,
		void *	user_data
	)

Return the custom data pointer for this context.

libei will not look at or modify the pointer. Use ei_touch_set_user_data() to change the user data.

◆ ei_touch_unref()

struct ei_touch* ei_touch_unref ( struct ei_touch * touch )

Decrease the refcount of this struct by one.

When the refcount reaches zero, the context disconnects from the server and all allocated resources are released.

Returns: always NULL

◆ ei_touch_up()

void ei_touch_up ( struct ei_touch * touch )

Release this touch.

After this call, the touch event becomes inert and no longer responds to either ei_touch_down(), ei_touch_motion() or ei_touch_up() and the caller should call ei_touch_unref().

◆ ei_unref()

struct ei* ei_unref ( struct ei * ei )

Decrease the refcount of this struct by one.

When the refcount reaches zero, the context disconnects from the server and all allocated resources are released.

Returns: always NULL

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ei_log_handler

Enumeration Type Documentation

◆ ei_device_capability

◆ ei_event_type

◆ ei_keymap_source

◆ ei_keymap_type

◆ ei_log_priority

Function Documentation

◆ ei_configure_name()

◆ ei_device_add()

◆ ei_device_configure_capability()

◆ ei_device_configure_name()

◆ ei_device_get_context()

◆ ei_device_get_name()

◆ ei_device_get_seat()

◆ ei_device_get_user_data()

◆ ei_device_has_capability()

◆ ei_device_keyboard_configure_keymap()

◆ ei_device_keyboard_get_keymap()

◆ ei_device_keyboard_key()

◆ ei_device_new()

◆ ei_device_pointer_button()

◆ ei_device_pointer_configure_range()

◆ ei_device_pointer_get_height()

◆ ei_device_pointer_get_width()

◆ ei_device_pointer_motion()

◆ ei_device_pointer_motion_absolute()

◆ ei_device_pointer_scroll()

◆ ei_device_pointer_scroll_discrete()

◆ ei_device_ref()

◆ ei_device_remove()

◆ ei_device_set_user_data()

◆ ei_device_touch_configure_range()

◆ ei_device_touch_get_height()

◆ ei_device_touch_get_width()

◆ ei_device_touch_new()

◆ ei_device_unref()

◆ ei_dispatch()

◆ ei_event_get_device()

◆ ei_event_get_seat()

◆ ei_event_get_time()

◆ ei_event_get_type()

◆ ei_event_unref()

◆ ei_get_event()

◆ ei_get_fd()

◆ ei_get_user_data()

◆ ei_keymap_get_context()

◆ ei_keymap_get_device()

◆ ei_keymap_get_fd()

◆ ei_keymap_get_size()

◆ ei_keymap_get_source()

◆ ei_keymap_get_type()

◆ ei_keymap_new()

◆ ei_keymap_ref()

◆ ei_keymap_unref()

◆ ei_log_get_priority()

◆ ei_log_set_handler()

◆ ei_log_set_priority()

◆ ei_new()

◆ ei_peek_event()

◆ ei_ref()

◆ ei_seat_get_context()

◆ ei_seat_get_name()

◆ ei_seat_get_user_data()

◆ ei_seat_has_capability()

◆ ei_seat_ref()

◆ ei_seat_set_user_data()

◆ ei_seat_unref()

◆ ei_set_user_data()

◆ ei_setup_backend_fd()

◆ ei_setup_backend_portal()

◆ ei_setup_backend_portal_busname()

◆ ei_setup_backend_socket()

◆ ei_touch_down()