libei 1.4.0 A library for Emulated Input

Topics | Data Structures | Typedefs | Enumerations | Functions
🥚 EI - The client API

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

## Topics
| The logging API
| The API to control logging output.
| API for receiver clients
| The receiver client API is available only to clients created with ei_new_receiver().
| API for sender clients
| The sender client API is available only to clients created with ei_new_sender().
| The seat API
| The API to query and interact with a struct ei_seat.
| The device API
| The API to query and interact with a struct ei_device.
| The region API
| The API to query a struct ei_region for information.
| The keymap API
| The API to query a struct ei_keymap for information.

## 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...
struct | ei_touch
| A single touch initiated by a sender context. More...
struct | ei_ping
| A callback struct returned by ei_new_ping() to handle roundtrips to the EIS implementation. More...

## Typedefs
typedef uint64_t(* | ei_clock_now_func) (struct ei *ei)
| Optional override function for ei_now().

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

## 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.
struct ei_ping * | ei_new_ping (struct ei *ei)
| Create a new ei_ping object to trigger a round trip to the EIS implementation.
uint64_t | ei_ping_get_id (struct ei_ping *ping)
| Return a unique, increasing id for this struct.
struct ei_ping * | ei_ping_ref (struct ei_ping *ei_ping)
| Increase the refcount of this struct by one.
struct ei_ping * | ei_ping_unref (struct ei_ping *ei_ping)
| Decrease the refcount of this struct by one.
void | ei_ping_set_user_data (struct ei_ping *ei_ping, void *user_data)
| Set a custom data pointer for this struct.
void * | ei_ping_get_user_data (struct ei_ping *ei_ping)
| Return the custom data pointer for this struct.
void | ei_ping (struct ei_ping *ping)
| Issue a roundtrip request to the EIS implementation, resulting in an EI_EVENT_PONG event when this roundtrip has been processed.
void | ei_dispatch (struct ei *ei)
| Main event dispatching function.
struct ei_event * | ei_get_event (struct ei *ei)
| Return the next event from the event queue, removing it from the queue.
struct ei_event * | ei_peek_event (struct ei *ei)
| Returns the next event in the internal event queue (or `NULL`) without removing that event from the queue; the next call to ei_get_event() will return that same event.
uint64_t | ei_now (struct ei *ei)
void | ei_disconnect (struct ei *ei)
| Disconnect the current ei context from the EIS implementation.
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.
struct ei_ping * | ei_event_pong_get_ping (struct ei_event *event)
| Returns the associated ei_ping struct with this event.

## Detailed Description

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

- create a context with ei_new_sender() or ei_new_receiver()
- set up a backend with ei_setup_backend_fd() or ei_setup_backend_socket()
- register the ei_get_fd() with its own event loop
- call ei_dispatch() whenever the fd triggers
- call ei_get_event() and process incoming events

Those events are typically a sequence of

- EI_EVENT_CONNECT - notification that the client was connected
- EI_EVENT_SEAT_ADDED - notification that a ei_seat is available. The client should respond with ei_seat_bind_capabilities()
- EI_EVENT_DEVICE_ADDED - notification that a ei_device is available in a seat.
- EI_EVENT_DEVICE_RESUMED - notification that the ei_device is ready to emulate events. The client should respond with ei_device_start_emulating() and the required events to emulate input

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.

Note
  A libei context is restricted to either sender or receiver mode, not both. The EIS implementation however may accept both sender and receiver clients, and will work 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

## ◆ ei_clock_now_func

typedef uint64_t(* ei_clock_now_func) (struct ei *ei)

Optional override function for ei_now().

By default ei_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 libei-internal test suite.

## Enumeration Type Documentation

## ◆ ei_device_capability

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

Enumerator
EI_DEVICE_CAP_POINTER | The device can send relative motion events.
EI_DEVICE_CAP_POINTER_ABSOLUTE | The device can send absolute motion events.
EI_DEVICE_CAP_KEYBOARD | The device can send keyboard events.
EI_DEVICE_CAP_TOUCH | The device can send touch events.
EI_DEVICE_CAP_SCROLL | The device can send scroll events.
EI_DEVICE_CAP_BUTTON | The device can send button events.

## ◆ ei_device_type

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.

See also
  ei_device_get_width
  ei_device_get_height

Enumerator
EI_DEVICE_TYPE_VIRTUAL |
EI_DEVICE_TYPE_PHYSICAL |

## ◆ ei_event_type

enum ei_event_type

This enum is not exhaustive, future versions of this library may add new event types.

Unknown events must be released by the caller with ei_event_unref(), see ei_get_event().

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 any modifier state or effective group change, including where the change is triggered by a client call to ei_device_keyboard_key(). For receiver clients, this will always be properly ordered with EI_EVENT_KEYBOARD_KEY events, so each key event should be interpreted should using the most recently received modifier state. For sender clients, the this event is not inherently synchronized with calls to ei_device_keyboard_key(), but the client may call ei_ping() when synchronization is required. When the corresponding EI_EVENT_PONG event is received, all key events sent prior to the sync request are guaranteed to have been processed, and any directly-resulting modifiers events are guaranteed to have been received. Note, however, that it is still possible for indirectly-triggered state changes, such as via a keyboard shortcut not encoded in the keymap, to be reported after the done event. This event may arrive while a device is paused. Note: It was previously specified that a where a sender client triggers a modifier state change in response to ei_device_keyboard_key(), no MODIFIERS event would be sent. Clients were expected to mix calls to xkb_state_update_key() and xkb_state_update_mask() to track the state with libxkbcommon, which could lead to disagreements between the client and server as to the current state.
EI_EVENT_PONG | Returned in response to ei_ping(). Note that in the ei protocol, the matching client request is called `sync` but for consistency in the libeis/libei API the C API uses ei_ping() with `EI_EVENT_PONG` as return.
EI_EVENT_SYNC | This event represents a synchronization request (ping) from the EIS implementation. The corresponding reply (pong) will be sent when it is unref'd. It has no other API. The caller must ensure that any state changes triggered by messages received prior to this event have been resolved and communicated to the EIS implementation prior to calling ei_event_unref().
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. Note These events are only generated on a receiver ei context. See ei_device_frame() for the sender context API.
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 These events are only generated on a receiver ei context. See ei_device_start_emulating() for the sender context API. 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. Note These events are only generated on a receiver ei context. See ei_device_stop_emulating() for the sender context API.
EI_EVENT_POINTER_MOTION | A relative motion event with delta coordinates in logical pixels or mm, depending on the device type. Note This event is only generated on a receiver ei context. See ei_device_pointer_motion() for the sender context API.
EI_EVENT_POINTER_MOTION_ABSOLUTE | An absolute motion event with absolute position within the device's regions or size, depending on the device type. Note This event is only generated on a receiver ei context. See ei_device_pointer_motion_absolute() for the sender context API.
EI_EVENT_BUTTON_BUTTON | A button press or release event. Note This event is only generated on a receiver ei context. See ei_device_button_button() for the sender context API.
EI_EVENT_SCROLL_DELTA | A vertical and/or horizontal scroll event with logical-pixels or mm precision, depending on the device type. Note This event is only generated on a receiver ei context. See ei_device_scroll_delta() for the sender context API.
EI_EVENT_SCROLL_STOP | An ongoing scroll sequence stopped. Note This event is only generated on a receiver ei context. See ei_device_scroll_stop() for the sender context API.
EI_EVENT_SCROLL_CANCEL | An ongoing scroll sequence was cancelled. Note This event is only generated on a receiver ei context. See ei_device_scroll_cancel() for the sender context API.
EI_EVENT_SCROLL_DISCRETE | A vertical and/or horizontal scroll event with a discrete range in logical scroll steps, like a scroll wheel. Note This event is only generated on a receiver ei context. See ei_device_scroll_discrete() for the sender context API.
EI_EVENT_KEYBOARD_KEY | A key press or release event. Note This event is only generated on a receiver ei context. See ei_device_keyboard_key() for the sender context API.
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. Note This event is only generated on a receiver ei context. See ei_device_touch_new() and ei_touch_down() for the sender context API.
EI_EVENT_TOUCH_UP | Event for a single touch released from the device's logical surface. Note This event is only generated on a receiver ei context. See ei_device_touch_new() and ei_touch_up() for the sender context API.
EI_EVENT_TOUCH_MOTION | Event for a single currently-down touch changing position (or other properties). Note This event is only generated on a receiver ei context. See ei_device_touch_new() and ei_touch_motion() for the sender context API.

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

## Function Documentation

## ◆ ei_clock_set_now_func()

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.

## ◆ 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_fd() or ei_setup_backend_socket().

## ◆ ei_disconnect()

void ei_disconnect | ( | struct ei * | ei | ) |

Disconnect the current ei context from the EIS implementation.

After a call to ei_disconnect(), ei_get_event() will return events to remove resources (e.g. seats and devices) as if they had been removed by the EIS implementation. The last event returned by ei_get_event() is EI_EVENT_DISCONNECT after which the context should be considered inert and any remaining resources released with ei_unref().

This does not free the resources associated with the ei context, use ei_unref().

Since
  1.4

## ◆ ei_dispatch()

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

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

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

Note
  Only events of type EI_EVENT_FRAME carry a timestamp. For convenience, the timestamp for other device events is retrofitted by this library.

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

struct ei_ping * ei_event_pong_get_ping | ( | struct ei_event * | event | ) |

Returns the associated ei_ping struct with this event.

For events of type other than EI_EVENT_PONG this function returns NULL.

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

## ◆ ei_event_type_to_string()

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

## ◆ 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(), even if the event type is unknown to the caller.

## ◆ 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 ei_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_is_sender()

bool ei_is_sender | ( | struct ei * | ei | ) |

Returns true if the context is was created with ei_new_sender() or false otherwise.

## ◆ ei_new()

struct ei * ei_new | ( | void * | user_data | ) |

This is an alias for ei_new_sender.

## ◆ ei_new_ping()

struct ei_ping * ei_new_ping | ( | struct ei * | ei | ) |

Create a new ei_ping object to trigger a round trip to the EIS implementation.

See ei_ping() for details.

The returned ei_ping is refcounted, use ei_ping_unref() to drop the reference.

Since
  1.4

## ◆ ei_new_receiver()

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

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

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

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

uint64_t ei_now | ( | struct ei * | ei | ) |

Returns
  a timestamp in microseconds for the current time to pass into ei_device_frame().

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

## ◆ 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_ping()

void ei_ping | ( | struct ei_ping * | ping | ) |

Issue a roundtrip request to the EIS implementation, resulting in an EI_EVENT_PONG event when this roundtrip has been processed.

Client requests are processed in-order by the EIS implementation so this function can be used as synchronization point between requests.

If the client is disconnected before the roundtrip is complete, libei will emulate a EI_EVENT_PONG event before EI_EVENT_DISCONNECT.

Note that in the ei protocol, the client request is `ei_connection.sync` followed by `ei_callback.done`. For consistency with the libeis API the C API uses ei_ping() with and EI_EVENT_PONG as return event.

Since
  1.4

## ◆ ei_ping_get_id()

uint64_t ei_ping_get_id | ( | struct ei_ping * | ping | ) |

Return a unique, increasing id for this struct.

This ID is assigned at struct creation and constant for the lifetime of the struct. The ID does not exist at the protocol level.

This is a convenience API to make it easier to put this struct into e.g. a hashtable without having to use the pointer value itself.

The ID increases by an unspecified amount.

Since
  1.4

## ◆ ei_ping_get_user_data()

void * ei_ping_get_user_data | ( | struct ei_ping * | ei_ping | ) |

Return the custom data pointer for this struct.

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

Since
  1.4

## ◆ ei_ping_ref()

struct ei_ping * ei_ping_ref | ( | struct ei_ping * | ei_ping | ) |

Increase the refcount of this struct by one.

Use ei_ping_unref() to decrease the refcount.

Returns
  the argument passed into the function

Since
  1.4

## ◆ ei_ping_set_user_data()

void ei_ping_set_user_data | ( | struct ei_ping * | ei_ping,
|  | void * | user_data )

Set a custom data pointer for this struct.

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

Since
  1.4

## ◆ ei_ping_unref()

struct ei_ping * ei_ping_unref | ( | struct ei_ping * | ei_ping | ) |

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

Since
  1.4

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

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

Note
  This backend requires the socket to be accessible to connect to and forces the EIS implementation to to identification and access control for clients. In almost all cases, the EIS implementation should use pre-created fds per client and the client should instead use ei_setup_backend_fd(). This backend is primarily useful for testing and debugging.

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