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
Enum names are shown here in uppercase. The exact name depends on the language bindings.
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.
| Name | Value | Summary |
|---|---|---|
VIRTUAL |
1 | a virtual device |
PHYSICAL |
2 | representation of a physical device |
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)| Argument | Type | Summary |
|---|---|---|
| last_serial | uint32 |
the last serial sent by the EIS implementation |
| sequence | uint32 |
sequence number to identify this emulation sequence |
This request is only available for clients of ei_handshake.context_type.sender.
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)| Argument | Type | Summary |
|---|---|---|
| last_serial | uint32 |
the last serial sent by the EIS implementation |
This request is only available for clients of ei_handshake.context_type.sender.
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)| Argument | Type | Summary |
|---|---|---|
| last_serial | uint32 |
the last serial sent by the EIS implementation |
| timestamp | uint64 |
timestamp in microseconds |
This request is only available for clients of ei_handshake.context_type.sender.
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
Immediately after sending this request, the object is considered destroyed by the EIS implementation. It must no longer be used by the client.
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)| Argument | Type | Summary |
|---|---|---|
| name | string |
the device 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)| Argument | Type | Summary |
|---|---|---|
| device_type | uint32 |
the 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)| Argument | Type | Summary |
|---|---|---|
| width | uint32 |
the device physical width in mm |
| height | uint32 |
the device physical height in mm |
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)| Argument | Type | Summary |
|---|---|---|
| offset_x | uint32 |
region x offset in logical pixels |
| offset_y | uint32 |
region y offset in logical pixels |
| width | uint32 |
region width in logical pixels |
| hight | uint32 |
region height in logical pixels |
| scale | float |
the physical scale for this region |
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 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 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)| Argument | Type | Summary |
|---|---|---|
| object | new_id |
|
| interface_name | string |
the interface name |
| version | uint32 |
the interface version |
Notification that a new device has a sub-interface.
This event may be sent for the
- “
ei_pointer” interface if the device has theei_device.capabilities.pointercapability - “
ei_pointer_absolute” interface if the device has theei_device.capabilities.pointer_absolutecapability - “
ei_scroll” interface if the device has theei_device.capabilities.scrollcapability - “
ei_button” interface if the device has theei_device.capabilities.buttoncapability - “
ei_keyboard” interface if the device has theei_device.capabilities.keyboardcapability - “
ei_touchscreen” interface if the device has theei_device.capabilities.touchscreencapability The interface version is equal or less to the client-supported version inei_handshake.interface_versionfor the respective interface.
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
| sequence | uint32 |
This event is only available for clients of ei_handshake.context_type.receiver.
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
This event is only available for clients of ei_handshake.context_type.receiver.
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)| Argument | Type | Summary |
|---|---|---|
| serial | uint32 |
this event’s serial number |
| timestamp | uint64 |
timestamp in microseconds |
This event is only available for clients of ei_handshake.context_type.receiver.
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)| Argument | Type | Summary |
|---|---|---|
| mapping_id | string |
region 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.