fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2026-05-05 15:58:02 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

protocol: more explanations

Browse source
This commit is contained in:
Peter Hutterer 2023-02-23 09:47:57 +10:00
parent 2227690287
commit 5c860507e5
1 changed files with 307 additions and 147 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

454
proto/protocol.xml
View file

@ -132,9 +132,14 @@
id 0 and only exists until the connection has been set up, see the
ei_connection_setup.connection event.
The ei_connection_setup version is 1 until and unless a client
sends the ei_connection_setup.interface_version request for the
"ei_connection_setup" interface.
The ei_connection_setup version is 1 until:
- the EIS implementation sends the interface_version event with
a version other than 1, and, in response,
- the client sends the interface_version request with a
version equal or lower to the EIS implementation version.
The EIS implementation must send the interface_version event immediately
once the physical connection has been established.
Once the ei_connection.connection event has been sent the connection setup
is destroyed by the EIS implementation.
@ -159,13 +164,18 @@
from the EIS implementation. A context type of sender is a libei context
sending events to the EIS implementation.
</description>
<entry name="receiver" value="1"/>
<entry name="sender" value="2"/>
<entry name="receiver" value="1" summary="this client receives events from the EIS implementation"/>
<entry name="sender" value="2" summary="this client sends events to the EIS implementation"/>
</enum>
<request name="context_type" since="1">
<description summary="context type request">
Notify the EIS implementation of the type of this context.
Notify the EIS implementation of the type of this context. The context types
defines whether the client will send events to or receive events from the
EIS implementation.
Depending on the context type, certain requests must not be used and some
events must not be sent by the EIS implementation.
This request is optional, the default client type is context_type.receiver.
This request must not be sent more than once and must be sent before
@ -195,16 +205,20 @@
In the future, objects created by the EIS implementation will
use the respective interface version (or any lesser version).
This request must be sent for the ei_connection interface, failing to do
so will result in the EIS implementation disconnecting the client
on ei_connection_setup.done.
This request must be sent for the "ei_connection" interface,
failing to do so will result in the EIS implementation disconnecting
the client on ei_connection_setup.done.
If the ei_connection_setup version is given, the interface of this
If the "ei_connection_setup" version is given, the interface of this
object is upgraded to the given version. Otherwise, the
ei_connection_setup version defaults to 1.
A client must not provide a ei_connection_setup version higher
than ei_connection_setup.version.
A client must not provide a "ei_connection_setup" version higher
than the EIS implementation sent immediately after connection.
Note that an EIS implementation may consider some interfaces to
be required and immediately ei_connection.disconnect a client
not supporting those interfaces.
This request must not be sent more than once per interface and must be
sent before ei_connection_setup.done.
@ -221,21 +235,25 @@
the given named interface with the given maximum version number.
This event is sent immediately after connection to the EIS implementation
for the "ei_connection_setup" interface. Any requests for this interface
sent by the client must be provided in the version provided
or any lower version.
for the "ei_connection_setup" interface. In response, the client may
send the interface_version request for the "ei_connection_setup" interface
with any version up to including the version provided in that event.
Once the request has been sent, the client must assume the negotiated
version number for the ei_connection_setup interface and the server
may send events and process requests matching that version.
A client should not issue any requests until processing the version for
A client should not issue any requests until negotiating the version for
the "ei_connection_setup" interface.
Note that the EIS implementation assumes that the supported
client version of the ei_connection_setup interface is 1 unless and
client version of the "ei_connection_setup" interface is 1 unless and
until the client announces a higher version of this interface in the
ei_connection_setup.interface_version request.
This event must be sent by the EIS implementation for any
interfaces that supports client-created objects (e.g. ei_callback).
The client may not assume those interfaces are supported.
interfaces that supports client-created objects (e.g. "ei_callback").
The client must not assume those interfaces are supported unless
and until those versions have been received.
This event may be sent by the EIS implementation for any
other supported interface (but not necessarily all supported
@ -257,11 +275,11 @@
EIS implementation immediately after this event has been sent, a
client must not attempt to use it after that point.
The version sent by the server is the version of the ei_connection
interface as announced by ei_connection_setup.interface, or any
The version sent by the server is the version of the "ei_connection"
interface as announced by ei_connection_setup.interface_version, or any
lower version.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
<arg name="connection" type="new_id" interface="ei_connection"
summary="the connection object" />
<arg name="version" type="uint" summary="the version of the connection object"/>
@ -296,8 +314,8 @@
The callback_data passed in the callback is always zero.
Note that for a client to use this request it must announce
support for this interface in ei_connection_setup.interface. It is
a protocol violation to request sync without having announced the
support for the "ei_callback" interface in ei_connection_setup.interface.
It is a protocol violation to request sync without having announced the
"ei_callback" interface and the EIS implementation must disconnect
the client.
</description>
@ -316,7 +334,7 @@
ei_connection object and it should close the socket. The EIS implementation
will treat the connection as already disconnected on receipt and does not
send the ei_connection.disconnect event in response to this request.
</description>>
</description>
</request>
<!-- ei_connection events version 1 -->
@ -332,14 +350,14 @@
as fallback.
This enum may be extended in the future, clients must be able to handle
values that are not in their supproted version of this enum.
values that are not in their supported version of this enum.
</description>
<entry name="disconnected" value="0" help="client was purposely disconnected"/>
<entry name="error" value="1" help="an error caused the disconnection"/>
<entry name="mode" value="2" help="sender/receiver client sent request for receiver/sender mode"/>
<entry name="protocol" value="3" help="client committed a protocol violation"/>
<entry name="value" value="4" help="client sent an invalid value"/>
<entry name="transport" value="5" help="error on the transport layer"/>
<entry name="disconnected" value="0" summary="client was purposely disconnected"/>
<entry name="error" value="1" summary="an error caused the disconnection"/>
<entry name="mode" value="2" summary="sender/receiver client sent request for receiver/sender mode"/>
<entry name="protocol" value="3" summary="client committed a protocol violation"/>
<entry name="value" value="4" summary="client sent an invalid value"/>
<entry name="transport" value="5" summary="error on the transport layer"/>
</enum>
<event name="disconnected" type="destructor" since="1">
@ -365,9 +383,9 @@
There is no guarantee this event is sent - the connection may be closed
without a disconnection event.
</description>
<arg name="last_serial" type="uint" help="the last serial sent by the EIS implementation"/>
<arg name="reason" type="uint" enum="disconnect_reason"/>
<arg name="explanation" type="string"/>
<arg name="last_serial" type="uint" summary="the last serial sent by the EIS implementation"/>
<arg name="reason" type="uint" enum="disconnect_reason" summary="the reason for being disconnected"/>
<arg name="explanation" type="string" summary="an explanation for debugging purposes"/>
</event>
<event name="seat" since="1">
@ -392,9 +410,18 @@
invalid and does not exist.
This event is sent by the EIS implementation when an object that
does not exist as seen by the EIS implementation.
does not exist as seen by the EIS implementation. The protocol is
asynchronous and this may occur e.g. when the EIS implementation
destroys an object at the same time as the client requests functionality
from that object. For example, an EIS implementation may send
ei_device.destroyed and destroy the device's resources (and protocol object)
at the same time as the client attempts to ei_device.start_emulating
on that object.
It is the client's responsibilty to unwind any state changes done
to the object since the last successful message.
</description>
<arg name="last_serial" type="uint" help="the last serial sent by the EIS implementation"/>
<arg name="last_serial" type="uint" summary="the last serial sent by the EIS implementation"/>
<arg name="invalid_id" type="uint" />
</event>
@ -413,7 +440,7 @@
Note that for a server to use this request the client must announce
support for this interface in ei_connection_setup.interface. It is
a protocol violation to send this event to a client without the
"ei_callback" interface.
"ei_pingpong" interface.
</description>
<arg name="ping" type="new_id" interface="ei_pingpong"
summary="callback object for the ping request"/>
@ -438,9 +465,6 @@
Notify the client when the related request is done. Immediately after this event
the ei_callback object is destroyed by the EIS implementation and as such the
client must not attempt to use it after that point.
This event may only be sent on an ei_callback object that was created by the
client.
</description>
<arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
</event>
@ -463,9 +487,6 @@
Notify the server when the related event is done. Immediately after this event
the ei_callback object is destroyed by the client and as such must not be used
any further.
This request may only be called on an ei_callback object that was created by the
EIS implementation.
</description>
<arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
</request>
@ -510,11 +531,13 @@
A set of capabilities possible available on this seat. A client may bind to these
capabilies and an EIS implementation may then create device based on the bound
capabilities.
These capabilities are binary compatible with ei_device.capabilities.
</description>
<entry name="pointer" value="2"/>
<entry name="pointer_absolute" value="4"/>
<entry name="keyboard" value="8"/>
<entry name="touchscreen" value="16"/>
<entry name="pointer" value="2" summary="the relative pointer capability"/>
<entry name="pointer_absolute" value="4" summary="the absolute pointer capability"/>
<entry name="keyboard" value="8" summary="the keyboard capability"/>
<entry name="touchscreen" value="16" summary="the touchscreen capability"/>
</enum>
<request name="bind" since="1">
@ -544,7 +567,7 @@
after this event is sent and as such the client must not attempt to use
it after that point.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="name" since="1">
@ -554,16 +577,20 @@
It is a protocol violation to send this event after the ei_seat.done event.
</description>
<arg name="name" type="string" help="the seat name"/>
<arg name="name" type="string" summary="the seat name"/>
</event>
<event name="capabilities" since="1">
<description summary="Seat capability notification">
A bitmask of the capabilities of this seat.
A bitmask of the capabilities of this seat. A client may ei_seat.bind to these
capabilies and an EIS implementation may then create device based on the bound
capabilities.
These capabilities are binary compatible with ei_device.capabilities.
It is a protocol violation to send this event after the ei_seat.done event.
</description>
<arg name="capabilities" type="uint" enum="capabilities" help="the seat capabilities"/>
<arg name="capabilities" type="uint" enum="capabilities" summary="the seat capabilities"/>
</event>
<event name="done" since="1">
@ -580,18 +607,28 @@
Notification that a new device has been added.
This event is only sent if the client announced support for the
"ei_device" interface in ei_connection_setup.interface.
"ei_device" interface in ei_connection_setup.interface_version.
The interface version is equal or less to the client-supported
version in ei_connection_setup.interface for the "ei_device"
interface.
</description>
<arg name="device" type="new_id" interface="ei_device"/>
<arg name="device" type="new_id" interface="ei_device" summary="the new device"/>
<arg name="version" type="uint" summary="the interface version"/>
</event>
</interface>
<interface name="ei_device" version="1">
<description summary="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_connection_setup.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_connection_setup.interface.
</description>
@ -621,13 +658,13 @@
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 synergy-like use-case the client would call
ei_device.start_emulating once the pointer moves into the the screen and
ei_device.stop_emulating once the pointer moves out of the screen.
For example, in a input-capture use-case the client would call
ei_device.start_emulating once the input capture starts (rather than when
the device sends events) and ei_device.stop_emulating once the input capture 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
Wraparound must be handled by the EIS implementation but callers must ensure
that detection of wraparound is reasonably.
It is a protocol violation to request start_emulating after start_emulating without an
@ -636,7 +673,7 @@
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="last_serial" type="uint" help="the last serial sent by the EIS implementation"/>
<arg name="last_serial" type="uint" summary="the last serial sent by the EIS implementation"/>
<arg name="sequence" type="uint"/>
</request>
@ -648,14 +685,19 @@
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="last_serial" type="uint" help="the last serial sent by the EIS implementation"/>
<arg name="last_serial" type="uint" summary="the last serial sent by the EIS implementation"/>
</request>
<request name="frame" since="1">
<description summary="Device frame request">
Generate a frame event to group the current set of events
into a logical hardware event. This function must be called after any
other event on any of ei_pointer, ei_keyboard or ei_touchscreen has been generated.
into a logical hardware event. This function must be called after one
or more events on any of ei_pointer, ei_keyboard or ei_touchscreen has
been requested by the server.
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.
@ -663,9 +705,9 @@
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="last_serial" type="uint" help="the last serial sent by the EIS implementation"/>
<arg name="timestamp" type="uint" help="timestamp in milliseconds"/>
<arg name="micros" type="uint" help="microseconds in addition to the millis"/>
<arg name="last_serial" type="uint" summary="the last serial sent by the EIS implementation"/>
<arg name="timestamp" type="uint" summary="timestamp in milliseconds"/>
<arg name="micros" type="uint" summary="microseconds in addition to the millis"/>
</request>
<!-- ei_device events version 1 -->
@ -679,7 +721,7 @@
after this event is sent and as such the client must not attempt to use
it after that point.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="name" since="1">
@ -689,24 +731,27 @@
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="name" type="string" help="the device name"/>
<arg name="name" type="string" summary="the device name"/>
</event>
<enum name="capabilities" since="1" type="bitmask">
<entry name="pointer" value="2"/>
<entry name="pointer_absolute" value="4"/>
<entry name="keyboard" value="8"/>
<entry name="touchscreen" value="16"/>
<description summary="Device capabilities">
These capabilities are binary compatible with ei_seat.capabilities.
</description>
<entry name="pointer" value="2" summary="the relative pointer capability"/>
<entry name="pointer_absolute" value="4" summary="the absolute pointer capability"/>
<entry name="keyboard" value="8" summary="the keyboard capability"/>
<entry name="touchscreen" value="16" summary="the touchscreen capability"/>
</enum>
<event name="capabilities" since="1">
<description summary="device capability notification">
A bitmask of the capabilties of this device.
A bitmask of the capabilities of this device.
This event must be is sent once immediately after object creation.
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="capabilities" type="uint" enum="capabilities" help="the device name"/>
<arg name="capabilities" type="uint" enum="capabilities" summary="the device name"/>
</event>
<enum name="device_type" since="1">
@ -724,18 +769,18 @@
within the device's specified physical size. Physical devices do not have
regions and no ei_device.region events are sent for such devices.
</description>
<entry name="virtual" value="1"/>
<entry name="physical" value="2"/>
<entry name="virtual" value="1" summary="a virtual device"/>
<entry name="physical" value="2" summary="representation of a physical device"/>
</enum>
<event name="type" since="1">
<description summary="device type notification">
The device type, one of virtual or physical.
This event must be is sent once immediately after object creation.
This event is sent once immediately after object creation.
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="type" type="uint" enum="device_type" help="the device type"/>
<arg name="type" type="uint" enum="device_type" summary="the device type"/>
</event>
<event name="dimensions" since="1">
@ -743,10 +788,12 @@
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.
</description>
<arg name="width" type="uint" help="the device physical width"/>
<arg name="height" type="uint" help="the device physical height"/>
<arg name="width" type="uint" summary="the device physical width in mm"/>
<arg name="height" type="uint" summary="the device physical height in mm"/>
</event>
<event name="region" since="1">
@ -767,28 +814,35 @@
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 first screen, the second with a nonzero
offset spanning the second screen.
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.
</description>
<arg name="offset_x" type="uint" help="region x offset in logical pixels"/>
<arg name="offset_y" type="uint" help="region y offset in logical pixels"/>
<arg name="width" type="uint" help="region width in logical pixels"/>
<arg name="hight" type="uint" help="region height in logical pixels"/>
<arg name="scale" type="float" help="the physical scale for this region"/>
<arg name="offset_x" type="uint" summary="region x offset in logical pixels"/>
<arg name="offset_y" type="uint" summary="region y offset in logical pixels"/>
<arg name="width" type="uint" summary="region width in logical pixels"/>
<arg name="hight" type="uint" summary="region height in logical pixels"/>
<arg name="scale" type="float" summary="the physical scale for this region"/>
</event>
<event name="pointer" since="1">
<description summary="device pointer interface notification">
Notification that a new device has a pointer interface.
This event is only sent if the device has the
ei_device.capabilities.pointer or
ei_device.capabilities.pointer_absolute capability.
This event is only sent if the client announced support for the
"ei_pointer" interface in ei_connection_setup.interface.
The interface version is equal or less to the client-supported
@ -806,6 +860,9 @@
<description summary="device pointer interface notification">
Notification that a new device has a keyboard interface.
This event is only sent if the device has the
ei_device.capabilities.keyboard.
This event is only sent if the client announced support for the
"ei_keyboard" interface in ei_connection_setup.interface.
The interface version is equal or less to the client-supported
@ -821,7 +878,10 @@
<event name="touchscreen" since="1">
<description summary="device touchscreen interface notification">
Notification that a new device has a keyboard interface.
Notification that a new device has a touchscreen interface.
This event is only sent if the device has the
ei_device.capabilities.touchscreen.
This event is only sent if the client announced support for the
"ei_touchscreen" interface in ei_connection_setup.interface.
@ -846,11 +906,47 @@
</event>
<event name="resumed" since="1">
<arg name="serial" type="uint" help="this events serial number"/>
<description summary="device resumed notification">
Notification that the device has been resumed by the EIS implementation
and (depending on the ei_connection_setup.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.
</description>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="paused" since="1">
<arg name="serial" type="uint" help="this events serial number"/>
<description summary="device paused notification">
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.
</description>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="start_emulating" since="1">
@ -860,7 +956,7 @@
It is a protocol violation to send this event for a client
of an ei_connection_setup.context_type other than receiver.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
<arg name="sequence" type="uint"/>
</event>
@ -871,7 +967,7 @@
It is a protocol violation to send this event for a client
of an ei_connection_setup.context_type other than receiver.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="frame" since="1">
@ -881,9 +977,9 @@
It is a protocol violation to send this event for a client
of an ei_connection_setup.context_type other than receiver.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="timestamp" type="uint" help="timestamp in milliseconds"/>
<arg name="micros" type="uint" help="microseconds in addition to the millis"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
<arg name="timestamp" type="uint" summary="timestamp in milliseconds"/>
<arg name="micros" type="uint" summary="microseconds in addition to the millis"/>
</event>
</interface>
@ -892,6 +988,11 @@
Interface for pointer and absolute pointer requests and events. This interface
is available on devices with the ei_device.capability pointer or pointer_absolute.
This interface is only provided once per device and where a client
requests ei_pointer.release the interface does not get re-initialized. An
EIS implementation may adjust the behavior of the device (including removing
the device) if the interface is releasd.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_connection_setup.interface.
</description>
@ -910,11 +1011,17 @@
<description summary="Relative motion request">
Generate a relative motion event on this pointer.
It is a client bug to send this request more than once
within the same ei_device.frame.
It is a client bug to send this request on a device without
the ei_device.capabilities.pointer capability.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="x" type="float" help="the x movement in logical pixels"/>
<arg name="y" type="float" help="the y movement in logical pixels"/>
<arg name="x" type="float" summary="the x movement in logical pixels"/>
<arg name="y" type="float" summary="the y movement in logical pixels"/>
</request>
<request name="motion_absolute" since="1">
@ -923,11 +1030,17 @@
coordinates must be within the device's regions or the event
is silently discarded.
It is a client bug to send this request more than once
within the same ei_device.frame.
It is a client bug to send this request on a device without
the ei_device.capabilities.pointer_absolute capability.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="x" type="float" help="the x position in logical pixels"/>
<arg name="y" type="float" help="the y position in logical pixels"/>
<arg name="x" type="float" summary="the x position in logical pixels"/>
<arg name="y" type="float" summary="the y position in logical pixels"/>
</request>
<request name="scroll" since="1">
@ -937,11 +1050,14 @@
the EIS implementation is responsible for emulation of discrete
scroll events.
It is a client bug to send this request more than once
within the same ei_device.frame.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="x" type="float" help="the x movement in logical pixels"/>
<arg name="y" type="float" help="the y movement in logical pixels"/>
<arg name="x" type="float" summary="the x movement in logical pixels"/>
<arg name="y" type="float" summary="the y movement in logical pixels"/>
</request>
<request name="scroll_discrete" since="1">
@ -955,11 +1071,14 @@
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.
It is a client bug to send this request more than once
within the same ei_device.frame.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="x" type="int" help="the x movement in fractions or multiple of 120"/>
<arg name="y" type="int" help="the y movement in fractions or multiple of 120"/>
<arg name="x" type="int" summary="the x movement in fractions or multiple of 120"/>
<arg name="y" type="int" summary="the y movement in fractions or multiple of 120"/>
</request>
<request name="scroll_stop" since="1">
@ -977,17 +1096,24 @@
current interaction. This indicates that the interaction has stopped to the
point where further (server-emulated) scroll events from this device are wrong.
It is a client bug to send this request more than once
within the same ei_device.frame.
It is a client bug to send this request for an axis that
had a a nonzero value in either ei_pointer.scroll or ei_pointer.scroll_discrete
in the current frame.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="x" type="uint" help="nonzero if this axis stopped scrolling"/>
<arg name="y" type="uint" help="nonzero if this axis stopped scrolling"/>
<arg name="is_cancel" type="uint" help="nonzero to indicate this is a cancel event"/>
<arg name="x" type="uint" summary="nonzero if this axis stopped scrolling"/>
<arg name="y" type="uint" summary="nonzero if this axis stopped scrolling"/>
<arg name="is_cancel" type="uint" summary="nonzero to indicate this is a cancel event"/>
</request>
<enum name="button_state" since="1">
<entry name="released" value="0"/>
<entry name="press" value="1"/>
<entry name="released" value="0" summary="the button is logically up"/>
<entry name="press" value="1" summary="the button is logically down"/>
</enum>
<request name="button" since="1">
@ -996,10 +1122,13 @@
The button codes must match the defines in linux/input-event-codes.h.
It is a client bug to send more than one button request for the same button
within the same ei_device.frame.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="button" type="uint" help="button code"/>
<arg name="button" type="uint" summary="button code"/>
<arg name="state" type="uint" enum="button_state"/>
</request>
@ -1014,7 +1143,7 @@
after this event is sent and as such the client must not attempt to use
it after that point.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="motion_relative" since="1">
@ -1091,6 +1220,11 @@
Interface for keyboard requests and events. This interface
is available on devices with the ei_device.capability keyboard.
This interface is only provided once per device and where a client
requests ei_keyboard.release the interface does not get re-initialized. An
EIS implementation may adjust the behavior of the device (including removing
the device) if the interface is releasd.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_connection_setup.interface.
</description>
@ -1105,42 +1239,26 @@
</description>
</request>
<enum name="keymap_type" since="1">
<entry name="xkb" value="1" help="a libxkbcommon-compatible XKB keymap" />
</enum>
<event name="keymap" since="1">
<description summary="keymap notification">
Notification that this device has a keymap.
The keymap is constant for the lifetime of the device. Key events on
this device correspond to the given keymap.
This event is sent immediately after the ei_keyboard object is created
and before the ei_device.done event. It is a protocol violation to send this
event after the ei_device.done event.
</description>
<arg name="type" type="uint" enum="keymap_type" help="the keymap type"/>
<arg name="size" type="uint" help="the keymap size in bytes"/>
<arg name="keymap" type="fd" help="file descriptor to the keymap"/>
</event>
<enum name="key_state" since="1">
<entry name="released" value="0"/>
<entry name="press" value="1"/>
<entry name="released" value="0" summary="the key is logically up"/>
<entry name="press" value="1" summary="the key is logically down"/>
</enum>
<request name="key" since="1">
<description summary="Key state change request">
Generate a key event on this keyboard.
Generate a key event on this keyboard. If the device has an
ei_device.keymap, the key code corresponds to that keymap.
The key codes must match the defines in linux/input-event-codes.h.
It is a client bug to send more than one key request for the same key
within the same ei_device.frame.
It is a protocol violation to send this request for a client
of an ei_connection_setup.context_type other than sender.
</description>
<arg name="key" type="uint"/>
<arg name="state" type="uint" enum="key_state"/>
<arg name="key" type="uint" summary="the key code"/>
<arg name="state" type="uint" enum="key_state" summary="logical state of the key"/>
</request>
<!-- ei_keyboard events version 1 -->
@ -1154,7 +1272,34 @@
after this event is sent and as such the client must not attempt to use
it after that point.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<enum name="keymap_type" since="1">
<description summary="the keymap type">
The keymap type describes how the keymap in the ei_keyboard.keymap event
should be parsed.
</description>
<entry name="xkb" value="1" summary="a libxkbcommon-compatible XKB keymap" />
</enum>
<event name="keymap" since="1">
<description summary="keymap notification">
Notification that this device has a keymap. Future key events must be
interpreted by the client according to this keymap. For clients
of ei_connection_setup.context_type sender it is the client's
responsibility to send the correct ei_keyboard.key keycodes to
generate the expected keysym in the EIS implementation.
The keymap is constant for the lifetime of the device.
This event is sent immediately after the ei_keyboard object is created
and before the ei_device.done event. It is a protocol violation to send this
event after the ei_device.done event.
</description>
<arg name="type" type="uint" enum="keymap_type" summary="the keymap type"/>
<arg name="size" type="uint" summary="the keymap size in bytes"/>
<arg name="keymap" type="fd" summary="file descriptor to the keymap"/>
</event>
<event name="key" since="1">
@ -1173,11 +1318,21 @@
Notification that the EIS implementation has changed modifier
states on this device. Future ei_keyboard.key requests must take the
new modifier state into account.
A client must assume that all modifiers are lifted when it
receives an ei_device.paused event. The EIS implementation
must send this event after ei_device.resumed to notify the client
of any nonzero modifier state.
This event does not reqire an ei_device.frame and should
be processed immediately by the client.
This event is only sent for devices with an ei_device.keymap.
</description>
<arg name="depressed" type="uint"/>
<arg name="locked" type="uint"/>
<arg name="latched" type="uint"/>
<arg name="group" type="uint"/>
<arg name="depressed" type="uint" summary="depressed modifiers"/>
<arg name="locked" type="uint" summary="locked modifiers"/>
<arg name="latched" type="uint" summary="latched modifiers"/>
<arg name="group" type="uint" summary="the keyboard group (layout)"/>
</event>
</interface>
@ -1186,6 +1341,11 @@
Interface for touchscreen requests and events. This interface
is available on devices with the ei_device.capability touchscreen.
This interface is only provided once per device and where a client
requests ei_touchscreen.release the interface does not get re-initialized. An
EIS implementation may adjust the behavior of the device (including removing
the device) if the interface is releasd.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_connection_setup.interface.
</description>
@ -1209,9 +1369,9 @@
The x/y coordinates must be within the device's regions or the event and future
ei_touchscreen.motion events with the same touchid are silently discarded.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float" help="touch x coordinate in logical pixels"/>
<arg name="y" type="float" help="touch y coordinate in logical pixels"/>
<arg name="touchid" type="uint" summary="a unique touch id to identify this touch"/>
<arg name="x" type="float" summary="touch x coordinate in logical pixels"/>
<arg name="y" type="float" summary="touch y coordinate in logical pixels"/>
</request>
<request name="motion" since="1">
@ -1223,9 +1383,9 @@
The x/y coordinates must be within the device's regions or the event is
silently discarded.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float" help="touch x coordinate in logical pixels"/>
<arg name="y" type="float" help="touch y coordinate in logical pixels"/>
<arg name="touchid" type="uint" summary="a unique touch id to identify this touch"/>
<arg name="x" type="float" summary="touch x coordinate in logical pixels"/>
<arg name="y" type="float" summary="touch y coordinate in logical pixels"/>
</request>
<request name="up" since="1">
@ -1236,7 +1396,7 @@
The touchid may be re-used after this request.
</description>
<arg name="touchid" type="uint"/>
<arg name="touchid" type="uint" summary="a unique touch id to identify this touch"/>
</request>
<!-- ei_touchscreen events version 1 -->
@ -1250,7 +1410,7 @@
after this event is sent and as such the client must not attempt to use
it after that point.
</description>
<arg name="serial" type="uint" help="this events serial number"/>
<arg name="serial" type="uint" summary="this event's serial number"/>
</event>
<event name="down" since="1">