fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2025-12-31 20:30:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

protocol: document the protocol better

Browse source
This commit is contained in:
Peter Hutterer 2023-02-06 11:14:22 +10:00
parent 0a347f433f
commit ebefdf903c
1 changed files with 113 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

146
proto/protocol.xml
View file

@ -94,6 +94,13 @@
</request>
<enum name="context_type" since="1">
<description summary="context type">
This enum denotes context types for the libei context.
A context type of receiver is a libei context receiving events
from the EIS implementation. A context type of sender is a libei context
sending events to the EIS implementation.
</description>
<entry name="receiver" value="0"/>
<entry name="sender" value="1"/>
</enum>
@ -132,6 +139,13 @@
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
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.
This request must not be sent more than once per interface.
</description>
<arg name="name" type="string" summary="the interface name"/>
@ -140,28 +154,29 @@
<event name="version" since="1">
<description summary="the connection setup version">
The highest supported version of this interface
by the EIS implementation. Any requests
send by the client must be provided in this version
The highest supported version of the ei_connection_setup
interface as supported by the EIS implementation. Any requests
sent by the client must be provided in this version
or any lower version.
This event is sent immediately after connection. A client
should not issue any requests until processing this version.
Note that the EIS implementation assumes that the supported
client version of this interface is 1 until the client announces
a higher version of this interface in the
client version of this interface is 1 unless and until the client
announces a higher version of this interface in the
ei_connection_setup.interface request.
</description>
<arg name="version" type="uint"
summary="the highest version supported by the EIS implementation"/>
</event>
<event name="connection">
<event name="connection" since="1">
<description summary="the core connection object">
Provides the client with the connection object that is the top-level
object for all future requests and events.
This event is sent immediately after the client sends the
This event is sent at some unspecified time after the client sends the
ei_connection_setup.done request to the EIS implementation.
The ei_connection_setup object will be destroyed by the
@ -180,8 +195,8 @@
<interface name="ei_connection" version="1">
<description summary="core global object">
The core global object. This is a special singleton object. It
is used for internal ei protocol features.
The core connection object. This is the top-level object for any communication
with the EIS implementation.
</description>
<request name="sync" since="1">
@ -204,7 +219,13 @@
summary="callback object for the sync request"/>
</request>
<request name="disconnect">
<request name="disconnect" since="1">
<description summary="disconnection request">
A request to the EIS implementation that this client should be disconnected.
This is a courtesy request to allow the EIS implementation to distinquish
between a client disconnecting on purpose and one disconnecting through the
socket becoming invalid.
</description>>
</request>
<enum name="disconnect_reason">
@ -215,13 +236,14 @@
<entry name="error" value="1" help="an error caused the disconnection"/>
</enum>
<event name="disconnected">
<event name="disconnected" since="1">
<description summary="disconnection event">
This event may be sent by the EIS implementation immediately before
the client is disconnected.
Where a client is disconnected by EIS directly, the reason is
disconnect_reason.disconnected and the explanation is NULL.
Where a client is disconnected by EIS on purpose, for example after
a user interaction, the reason is disconnect_reason.disconnected and
the explanation is NULL.
Where a client is disconnected due to some invalid request or other
protocol error, the reason is disconnect_reason.error and
@ -264,28 +286,57 @@
<interface name="ei_seat" version="1">
<description summary="seat object">
An ei_seat represents a set of input devices that logically belong together. In most
cases only one seat is present and all input devices on that seat share the same
pointer and keyboard focus.
A seat has potential capabilities, a client is expected to bind to those capabilities.
The EIS implementation then creates logical input devices based on the capabilities the
client is interested in.
Immediately after creation of the ei_seat object, the EIS implementation sends a burst
of events with information about this seat. This burst of events is terminated by the
ei_seat.done event.
</description>
<request name="release">
<request name="release" since="1">
<description summary="Seat removal request">
Notification that the client is no longer interested in this seat.
The EIS implementation will release any resources related to this seat and
send the ei_seat.destroyed event once complete.
Note that releasing a seat does not guarantee another seat becomes available.
In other words, in most single-seat cases, releasing the seat means the
connection becomes effectively inert.
</description>
</request>
<enum name="capabilities" since="1">
<description summary="Seat capabilities">
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.
</description>
<entry name="pointer" value="2"/>
<entry name="pointer_absolute" value="4"/>
<entry name="keyboard" value="8"/>
<entry name="touch" value="16"/>
</enum>
<request name="bind">
<request name="bind" since="1">
<description summary="Seat binding">
Bind to the bitmask of capabilities given.
Bind to the bitmask of capabilities given. The bitmask is zero or more of the
capabilities provided in the ei_seat.capabilities event. That event's capabilities
are used as a mask of capabilities that can be bound.
Binding capabilities that are not supported in the ei_seat's interface version
is a client bug and may result in disconnection.
A client may send this request multiple times to adjust the capabilities it
is interested in. If capabilities are dropped, the EIS implementation may
ei_device.remove devices that have these capabilities.
</description>
<arg name="capabilities" type="uint"/>
<arg name="capabilities" type="uint" enum="capabilities"/>
</request>
<event name="destroyed" since="1">
@ -307,7 +358,7 @@
<description summary="Seat capability notification">
A bitmask of the capabilities of this seat.
</description>
<arg name="capabilities" type="uint" enum="capabilities" help="the seat name"/>
<arg name="capabilities" type="uint" enum="capabilities" help="the seat capabilities"/>
</event>
<event name="done" since="1">
@ -339,14 +390,14 @@
</description>
</request>
<request name="start_emulating">
<request name="start_emulating" since="1">
<arg name="sequence" type="uint"/>
</request>
<request name="stop_emulating">
<request name="stop_emulating" since="1">
</request>
<request name="frame">
<request name="frame" since="1">
<arg name="timestamp" type="uint"/>
<arg name="micros" type="uint"/>
</request>
@ -430,17 +481,17 @@
</description>
</event>
<event name="resumed">
<event name="resumed" since="1">
</event>
<event name="paused">
<event name="paused" since="1">
</event>
<event name="start_emulating">
<event name="start_emulating" since="1">
<arg name="sequence" type="uint"/>
</event>
<event name="stop_emulating">
<event name="stop_emulating" since="1">
</event>
<event name="frame" since="1">
@ -541,7 +592,7 @@
<description summary="keyboard object">
</description>
<request name="release">
<request name="release" since="1">
<description summary="keyboard removal request">
Notification that the client is no longer interested in this keyboard.
The EIS implementation will release any resources related to this keyboard and
@ -593,7 +644,7 @@
<description summary="touchscreen object">
</description>
<request name="release">
<request name="release" since="1">
<description summary="touch removal request">
Notification that the client is no longer interested in this touch.
The EIS implementation will release any resources related to this touch and
@ -601,19 +652,36 @@
</description>
</request>
<request name="down">
<request name="down" since="1">
<description summary="touch down request">
Notifies the EIS implementation about a new touch logically down at the
given coordinates. The touchid is a unique id for this touch. Touchids
may be re-used after ei_touchscreen.up.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="motion">
<request name="motion" since="1">
<description summary="touch motion request">
Notifies the EIS implementation about an existing touch changing position to
the given coordinates. The touchid is the unique id for this touch previously
sent with ei_touchscreen.down.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="up">
<request name="up" since="1">
<description summary="touch up request">
Notifies the EIS implementation about an existing touch being logically
up. The touchid is the unique id for this touch previously
sent with ei_touchscreen.down.
The touchid may be re-used after this request.
</description>
<arg name="touchid" type="uint"/>
</request>
@ -624,19 +692,31 @@
</description>
</event>
<event name="down">
<event name="down" since="1">
<description summary="touch down request">
See the ei_touchscreen.down request for details. This event is
for ei receiver contexts.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="motion">
<event name="motion" since="1">
<description summary="touch motion request">
See the ei_touchscreen.motion request for details. This event is
for ei receiver contexts.
</description>
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="up">
<event name="up" since="1">
<description summary="touch motion request">
See the ei_touchscreen.up request for details. This event is
for ei receiver contexts.
</description>
<arg name="touchid" type="uint"/>
</event>
</interface>