libei: The device API

libei 1.3.0 A library for Emulated Input

Functions
The device API
🥚 EI - The client API

## Functions
struct ei_device * | ei_device_ref (struct ei_device *device)
| Increase the refcount of this struct by one.
struct ei_device * | ei_device_unref (struct ei_device *device)
| Decrease the refcount of this struct by one.
struct ei_seat * | ei_device_get_seat (struct ei_device *device)
void | ei_device_set_user_data (struct ei_device *device, void *user_data)
| Set a custom data pointer for this context.
void * | ei_device_get_user_data (struct ei_device *device)
| Return the custom data pointer for this context.
uint32_t | ei_device_get_width (struct ei_device *device)
| Return the width of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.
uint32_t | ei_device_get_height (struct ei_device *device)
| Return the height of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.
void | ei_device_close (struct ei_device *device)
| Notify the server that the client is no longer interested in this device.
const char * | ei_device_get_name (struct ei_device *device)
enum ei_device_type | ei_device_get_type (struct ei_device *device)
bool | ei_device_has_capability (struct ei_device *device, enum ei_device_capability cap)
| Return true if the device has the requested capability.
struct ei_region * | ei_device_get_region (struct ei_device *device, size_t index)
| Obtain a region from a device of type EI_DEVICE_TYPE_VIRTUAL.
struct ei_region * | ei_device_get_region_at (struct ei_device *device, double x, double y)
| Return the region that contains the given point x/y (in desktop-wide coordinates) or NULL if the coordinates are outside all regions.
struct ei_keymap * | ei_device_keyboard_get_keymap (struct ei_device *device)
| Return the keymap for this device or `NULL`.
struct ei * | ei_device_get_context (struct ei_device *device)
| Return the struct ei context this device is associated with.

## Detailed Description

The API to query and interact with a struct ei_device

## Function Documentation

## ◆ ei_device_close()

void ei_device_close | ( | struct ei_device * | device | ) |

Notify the server that the client is no longer interested in this device.

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_close() was called before the EI_EVENT_DISCONNECT event. 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_get_context()

struct ei * ei_device_get_context | ( | struct ei_device * | device | ) |

Return the struct ei context this device is associated with.

## ◆ ei_device_get_height()

uint32_t ei_device_get_height | ( | struct ei_device * | device | ) |

Return the height of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.

## ◆ ei_device_get_name()

const char * ei_device_get_name | ( | struct ei_device * | device | ) |

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

## ◆ ei_device_get_region()

struct ei_region * ei_device_get_region | ( | struct ei_device * | device,
|  | size_t | index )

Obtain a region from a device of type EI_DEVICE_TYPE_VIRTUAL.

The number of regions is constant for a device and the indices of any region remains the same for the lifetime of the device.

Regions are shared between all capabilities. Where two capabilities need different regions, the EIS implementation must create multiple devices with individual capabilities and regions. For example, two touchscreens that are mapped to two screens would typically show up as two separate devices with one region each.

This function returns the given region or NULL if the index is larger than the number of regions available.

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

Devices of type EI_DEVICE_TYPE_PHYSICAL do not have regions.

## ◆ ei_device_get_region_at()

struct ei_region * ei_device_get_region_at | ( | struct ei_device * | device,
|  | double | x,
|  | double | y )

Return the region that contains the given point x/y (in desktop-wide coordinates) or NULL if the coordinates are outside all regions.

Since
  1.1

## ◆ ei_device_get_seat()

struct ei_seat * ei_device_get_seat | ( | struct ei_device * | device | ) |

## ◆ ei_device_get_type()

enum ei_device_type ei_device_get_type | ( | struct ei_device * | device | ) |

Returns
  the device type

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

uint32_t ei_device_get_width | ( | struct ei_device * | device | ) |

Return the width of the device in mm if the device is of type EI_DEVICE_TYPE_PHYSICAL, otherwise zero.

## ◆ 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 for the lifetime of the device and always a subset of the capabilities bound to by ei_seat_bind_capabilities().

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

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