ei_device

Device Object

An ei_device represents a single logical input devices. Like physical input devices an ei_device may have multiple capabilities and may e.g. function as pointer and keyboard.

Depending on the ei_handshake.context_type, an ei_device can emulate events via client requests or receive events. It is a protocol violation to emulate certain events on a receiver device, or for the EIS implementation to send certain events to the device. See the individual request/event documentation for details.

Note that for a client to receive objects of this type, it must announce support for this interface in ei_handshake.interface_version.

Enums

ei_device.device_type

If the device type is ei_device.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 ei_device.dimension but it may have an ei_device.region.

If the device type is ei_device.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 and no ei_device.region events are sent for such devices.

Requests

ei_device.release

Since Version1 Request Opcode0

ei_device.release()

Notification that the client is no longer interested in this device.

Note that releasing a device does not guarantee another device becomes available.

The EIS implementation will release any resources related to this device and send the ei_device.destroyed event once complete.

ei_device.start_emulating

Since Version1 Request Opcode1

ei_device.start_emulating(last_serial, sequence)

Notify the EIS implementation that the given device is about to start sending events. This should be seen more as a transactional boundary than a time-based boundary. The primary use-cases for this are to allow for setup on the EIS implementation side and/or UI updates to indicate that a device is sending events now and for out-of-band information to sync with a given event sequence.

There is no actual requirement that events start immediately once emulation starts and there is no requirement that a client calls ei_device.stop_emulating after the most recent events. For example, in a remote desktop use-case the client would call ei_device.start_emulating once the remote desktop session starts (rather than when the device sends events) and ei_device.stop_emulating once the remote desktop session stops.

The sequence number identifies this transaction between start/stop emulating. It must go up by at least 1 on each call to ei_device.start_emulating. Wraparound must be handled by the EIS implementation but callers must ensure that detection of wraparound is possible.

It is a protocol violation to request ei_device.start_emulating after ei_device.start_emulating without an intermediate stop_emulating.

It is a protocol violation to send this request for a client of an ei_handshake.context_type other than sender.

ei_device.stop_emulating

Since Version1 Request Opcode2

ei_device.stop_emulating(last_serial)

Notify the EIS implementation that the given device is no longer sending events. See ei_device.start_emulating for details.

It is a protocol violation to send this request for a client of an ei_handshake.context_type other than sender.

ei_device.frame

Since Version1 Request Opcode3

ei_device.frame(last_serial, timestamp)

Generate a frame event to group the current set of events into a logical hardware event. This function must be called after one or more events on any of ei_pointer, ei_pointer_absolute, ei_scroll, ei_button, ei_keyboard or ei_touchscreen has been requested by the EIS implementation.

The EIS implementation should not process changes to the device state until the ei_device.frame event. For example, pressing and releasing a key within the same frame is a logical noop.

The given timestamp applies to all events in the current frame. The timestamp must be in microseconds of CLOCK_MONOTONIC.

It is a protocol violation to send this request for a client of an ei_handshake.context_type other than sender.

Events

ei_device.destroyed

Since Version1 Event Opcode0

ei_device.destroyed(serial)

This device has been removed and a client should release all associated resources.

This ei_device object will be destroyed by the EIS implementation immmediately after after this event is sent and as such the client must not attempt to use it after that point.

ei_device.name

Since Version1 Event Opcode1

ei_device.name(name)

The name of this device, if any. This event is optional and sent once immediately after object creation.

It is a protocol violation to send this event after the ei_device.done event.

ei_device.device_type

Since Version1 Event Opcode2

ei_device.device_type(device_type)

The device type, one of virtual or physical.

Devices of type ei_device.device_type.physical are supported only clients of type ei_handshake.context_type.receiver.

This event is sent once immediately after object creation. It is a protocol violation to send this event after the ei_device.done event.

ei_device.dimensions

Since Version1 Event Opcode3

ei_device.dimensions(width, height)

The device dimensions in mm. This event is optional and sent once immediately after object creation.

This event is only sent for devices of ei_device.device_type.physical.

It is a protocol violation to send this event after the ei_device.done event.

ei_device.region

Since Version1 Event Opcode4

ei_device.region(offset_x, offset_y, width, hight, scale)

Notifies the client of one region. The number of regions is constant for a device and all regions are announced immediately after object creation.

A region is rectangular and defined by an x/y offset and a width and a height. A region defines the area on an EIS desktop layout that is accessible by this device - this region may not be the full area of the desktop. Input events may only be sent for points within the regions.

The use of regions is private to the EIS compositor and coordinates may not match the size of the actual desktop. For example, a compositor may set a 1920x1080 region to represent a 4K monitor and transparently map input events into the respective true pixels.

Absolute devices may have different regions, it is up to the libei client to send events through the correct device to target the right pixel. For example, a dual-head setup my have two absolute devices, the first with a zero offset region spanning the left screen, the second with a nonzero offset spanning the right screen.

The physical scale denotes a constant multiplication factor that needs to be applied to any relative movement on this region for that movement to match the same physical movement on another region.

It is an EIS implementation bug to advertise the touch and/or absolute pointer capability on a device_type.virtual device without advertising an ei_region for this device.

This event is optional and sent immediately after object creation. Where a device has multiple regions, this event is sent once for each region. It is a protocol violation to send this event after the ei_device.done event.

Note: the fourth argument (‘hight’) was misspelled when the protocol was declared stable but changing the name is an API breaking change.

ei_device.interface

Since Version1 Event Opcode5

ei_device.interface(object, interface_name, version)

Notification that a new device has a sub-interface.

This event may be sent for the following interfaces:

• “ei_pointer”
• “ei_pointer_absolute”
• “ei_scroll”
• “ei_button”
• “ei_keyboard”
• “ei_touchscreen” The interface version is equal or less to the client-supported version in ei_handshake.interface_version for the respective interface.

It is a protocol violation to send a notification for an interface that the client has not bound to with ei_seat.bind.

This event is optional and sent immediately after object creation and at most once per interface. It is a protocol violation to send this event after the ei_device.done event.

ei_device.done

Since Version1 Event Opcode6

ei_device.done()

Notification that the initial burst of events is complete and the client can set up this device now.

It is a protocol violation to send this event more than once per device.

ei_device.resumed

Since Version1 Event Opcode7

ei_device.resumed(serial)

Notification that the device has been resumed by the EIS implementation and (depending on the ei_handshake.context_type) the client may request ei_device.start_emulating or the EIS implementation may ei_device.start_emulating events.

It is a client bug to request emulation of events on a device that is not resumed. The EIS implementation may silently discard such events.

A newly advertised device is in the ei_device.paused state.

ei_device.paused

Since Version1 Event Opcode8

ei_device.paused(serial)

Notification that the device has been paused by the EIS implementation and no futher events will be accepted on this device until it is resumed again.

For devices of ei_device_setup.context_type sender, the client thus does not need to request ei_device.stop_emulating and may request ei_device.start_emulating after a subsequent ei_device.resumed.

For devices of ei_device_setup.context_type receiver and where the EIS implementation did not send a ei_device.stop_emulating prior to this event, the device may send a ei_device.start_emulating event after a subsequent ei_device.resumed event.

Pausing a device resets the logical state of the device to neutral. This includes:

• any buttons or keys logically down are released
• any modifiers logically down are released
• any touches logically down are released

It is a client bug to request emulation of events on a device that is not resumed. The EIS implementation may silently discard such events.

A newly advertised device is in the ei_device.paused state.

ei_device.start_emulating

Since Version1 Event Opcode9

ei_device.start_emulating(serial, sequence)

See the ei_device.start_emulating request for details.

It is a protocol violation to send this event for a client of an ei_handshake.context_type other than receiver.

ei_device.stop_emulating

Since Version1 Event Opcode10

ei_device.stop_emulating(serial)

See the ei_device.stop_emulating request for details.

It is a protocol violation to send this event for a client of an ei_handshake.context_type other than receiver.

ei_device.frame

Since Version1 Event Opcode11

ei_device.frame(serial, timestamp)

See the ei_device.frame request for details.

It is a protocol violation to send this event for a client of an ei_handshake.context_type other than receiver.

ei_device.region_mapping_id

Since Version2 Event Opcode12

ei_device.region_mapping_id(mapping_id)

Notifies the client that the region specified in the next ei_device.region event is to be assigned the given mapping_id.

This ID can be used by the client to identify an external resource that has a relationship with this region. For example the client may receive a data stream with the video data that this region represents. By attaching the same identifier to the data stream and this region the EIS implementation can inform the client that the video data stream and the region represent paired data.

This event is optional and sent immediately after object creation but before the corresponding ei_device.region event. Where a device has multiple regions, this event may be sent zero or one time for each region. It is a protocol violation to send this event after the ei_device.done event or to send this event without a corresponding following ei_device.region event.