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

docs: Fix issues and make some language clearer

Browse source 
Part-of: <https://gitlab.freedesktop.org/libinput/libei/-/merge_requests/344>
This commit is contained in:
Axel Karjalainen 2025-07-25 00:23:44 +03:00 • committed by Marge Bot
parent 70c3348dfe
commit 525d55a532
1 changed files with 109 additions and 136 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

245
proto/protocol.xml
View file

@ -52,12 +52,11 @@
<!-- ei_handshake client requests version 1 -->
<request name="handshake_version" since="1">
<description summary="handshake version notification request">
Notifies the EIS implementation that this client supports the
given version of the ei_handshake interface. The version number
must be less than or equal to the version in the
handshake_version event sent by the EIS implementation when
the connection was established.
<description summary="handshake version information from EI client">
Informs the EIS implementation that this client supports the given
version of the ei_handshake interface. The version number must be less
than or equal to the version in the handshake_version event sent by the
EIS implementation when the connection was established.
Immediately after sending this request, the client must assume the negotiated
version number for the ei_handshake interface and the EIS implementation
@ -71,7 +70,7 @@
<request name="finish" since="1">
<description summary="setup completion request">
Notify the EIS implementation that configuration is complete.
Informs the EIS implementation that configuration is complete.
In the future (and possibly after requiring user interaction),
the EIS implementation responds by sending the ei_handshake.connection event.
@ -83,15 +82,15 @@
Context types for connections. The context type for a connection is set
once in the ei_handshake.context_type request.
</description>
<entry name="receiver" value="1" summary="the client receives input events from the server"/>
<entry name="sender" value="2" summary="the client sends input events to the server"/>
<entry name="receiver" value="1" summary="the EI client receives input events from the EIS implementation"/>
<entry name="sender" value="2" summary="the EI client sends input events to the EIS implementation"/>
</enum>
<request name="context_type" since="1">
<description summary="context type notification">
Notify the EIS implementation of the type of this context. The context
type defines whether the client will send input events to the server or
receive input events from it.
<description summary="context type information">
Informs the EIS implementation of the type of this context. The context
type defines whether the EI client will send input events to the EIS
implementation or receive input events from it.
Depending on the context type, certain requests must not be used and some
events must not be sent by the EIS implementation.
@ -104,11 +103,11 @@
</request>
<request name="name" since="1">
<description summary="client name notification">
Notify the EIS implementation of the client name. The name is a
human-presentable UTF-8 string and should represent the client name
as accurately as possible. This name may be presented to the user
for identification of this client (e.g. to confirm the client has
<description summary="client name">
Informs the EIS implementation of the client name. The name is a
human-presentable UTF-8 string and should represent the client name as
accurately as possible. This name may be presented to the user for
identification of this client (e.g. to confirm the client has
permissions to connect).
There is no requirement for the EIS implementation to use this name. For
@ -124,9 +123,9 @@
</request>
<request name="interface_version" since="1">
<description summary="interface support notification">
Notify the EIS implementation that the client supports the
given named interface with the given maximum version number.
<description summary="interface support information">
Informs the EIS implementation that the EI client supports the given
named interface with the given maximum version number.
Future objects created by the EIS implementation will
use the respective interface version (or any lesser version)
@ -152,9 +151,12 @@
<!-- ei_handshake events version 1 -->
<event name="handshake_version" since="1">
<description summary="handshake version notification event">
This event is sent exactly once and immediately after connection
to the EIS implementation.
<description summary="handshake version information from EIS implementation">
Informs the client that the EIS implementation supports the given
version of the ei_handshake interface.
This event is sent exactly once and immediately after connection to the
EIS implementation.
In response, the client must send the ei_handshake.handshake_version request
with any version up to including the version provided in this event.
@ -165,8 +167,8 @@
<event name="interface_version" since="1">
<description summary="interface support event">
Notifies the client that the EIS implementation supports
the given named interface with the given maximum version number.
Informs the client that the EIS implementation supports the given named
interface with the given maximum version number.
The client must not assume those interfaces are supported unless
and until those versions have been received.
@ -183,18 +185,18 @@
</event>
<event name="connection" type="destructor" since="1">
<description summary="initialization of the connection object">
<description summary="provides 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 exactly once at some unspecified time after the client
sends the ei_handshake.finish request to the EIS implementation.
This event must be sent exactly once after the client sends the
ei_handshake.finish request to the EIS implementation.
The ei_handshake object will be destroyed by the
EIS implementation immediately after this event has been sent, a
client must not attempt to use it after that point.
The ei_handshake object will be destroyed by the EIS implementation
immediately after this event has been sent, the client must not attempt
to use it after that point.
The version sent by the EIS implementation is the version of the "ei_connection"
The version sent by the EIS implementation is the version of the `ei_connection`
interface as announced by ei_handshake.interface_version, or any
lower version.
@ -223,22 +225,22 @@
<request name="sync" since="1">
<description summary="asynchronous roundtrip">
The sync request asks the EIS implementation to emit the 'done' event
on the returned ei_callback object. Since requests are
handled in-order and events are delivered in-order, this can
be used as a synchronization point to ensure all previous requests and the
resulting events have been handled.
Requests the EIS implementation to emit the ei_callback.done event on
the returned ei_callback object. Since requests are handled in-order
and events are delivered in-order, this can be used as a
synchronization point to ensure all previous requests and the resulting
events have been handled.
The object returned by this request will be destroyed by the
EIS implementation after the callback is fired and as such the client must not
attempt to use it after that point.
The callback_data in the ei_callback.done event is always zero.
The callback_data in the ei_callback.done event must be zero.
Note that for a client to use this request it must announce
support for the "ei_callback" interface in ei_handshake.interface_version.
support for the `ei_callback` interface in ei_handshake.interface_version.
It is a protocol violation to request sync without having announced the
"ei_callback" interface and the EIS implementation must disconnect
`ei_callback` interface and the EIS implementation must disconnect
the client.
</description>
<arg name="callback" type="new_id" interface="ei_callback"
@ -287,7 +289,7 @@
<description summary="disconnection event">
This event may be sent by the EIS implementation immediately before
the client is disconnected. The last_serial argument is set to the last
serial number used in an event by the server.
serial number used in an event by the EIS implementation.
Where a client is disconnected by EIS on purpose, for example after
a user interaction, the reason is disconnect_reason.disconnected (i.e. zero)
@ -311,8 +313,8 @@
</event>
<event name="seat" since="1">
<description summary="Seat presence notification">
Notification that a new seat has been added.
<description summary="Seat presence information">
Informs the client that a new seat has been added.
A seat is a set of input devices that logically belong together.
@ -328,7 +330,7 @@
<event name="invalid_object" since="1">
<description summary="Invalid object in request notification">
Notification that an object ID used in an earlier request was
Informs the client that an object ID used in an earlier request was
invalid and does not exist.
This event is sent by the EIS implementation when an object that
@ -378,18 +380,16 @@
Interface for ensuring a roundtrip to the EIS implementation.
Clients can handle the 'done' event to get notified when
the related request that created the ei_callback object is done.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_callback events version 1 -->
<event name="done" type="destructor" since="1">
<description summary="done event">
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.
Informs the client that the associated request is finished. The EIS
implementation must destroy the ei_callback object immediately after
sending this event this event and as such the client must not attempt to
use it after that point.
</description>
<arg name="callback_data" type="uint64" summary="request-specific data for the callback"/>
</event>
@ -400,18 +400,16 @@
Interface for ensuring a roundtrip to the client implementation.
This interface is identical to ei_callback but is intended for
the EIS implementation to enforce a roundtrip to the client.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_pingpong client requests version 1 -->
<request name="done" type="destructor" since="1">
<description summary="done event">
Notify the EIS implementation when the related event is done. Immediately after this request
the ei_pingpong object is destroyed by the client and as such must not be used
any further.
Informs the EIS implementation when the associated event is finished.
The client must destroy the ei_pingpong object immediately after this
request and as such the server must not attempt to use it after that
point.
</description>
<arg name="callback_data" type="uint64" summary="request-specific data for the callback"/>
</request>
@ -432,37 +430,39 @@
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.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_seat client requests version 1 -->
<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.
Informs the EIS implementation that the client is no longer interested
in this seat. The EIS implementation should release any resources
associated with this seat and send the ei_seat.destroyed event once
finished.
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.
Note that releasing a seat does not guarantee that another seat becomes
available. In other words, in most single-seat cases, releasing the seat
means that the connection becomes effectively inert.
</description>
</request>
<request name="bind" since="1">
<description summary="Seat binding">
Bind to the bitmask of capabilities given. The bitmask is zero or more of the
masks representing an interface as provided in the ei_seat.capability event.
See the ei_seat.capability event documentation for examples.
Binds to the given bitmask of capabilities. Each one of the bit values
in the given bitmask must originate from one of the ei_seat.capability
events. See its documentation for more examples.
Binding masks that are not supported in the ei_device's interface version
is a client bug and may result in disconnection.
The EIS implementation should return compatible devices with
ei_seat.device events.
A client may send this request multiple times to adjust the capabilities it
is interested in. If previously-bound capabilities are dropped by the client,
the EIS implementation may ei_device.remove devices that have these capabilities.
Binding masks that are not supported in the ei_device'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 previously-bound capabilities are dropped by the
client, the EIS implementation may ei_device.remove devices that have
these capabilities.
</description>
<arg name="capabilities" type="uint64" summary="bitmask of the capabilities"/>
</request>
@ -471,8 +471,8 @@
<event name="destroyed" type="destructor" since="1">
<description summary="Seat removal notification">
This seat has been removed and a client should release all
associated resources.
Informs the client that this seat has been removed, and that it should
release all associated resources.
This ei_seat object will be destroyed by the EIS implementation immediately after
after this event is sent and as such the client must not attempt to use
@ -493,33 +493,27 @@
<event name="capability" since="1">
<description summary="Seat capability notification">
A notification that this seat supports devices with the given interface.
The interface is mapped to a bitmask by the EIS implementation.
A client may then binary OR these bitmasks in ei_seat.bind.
In response, the EIS implementation may then create device based on those
bound capabilities.
Informs the client that this seat supports devices with the given
interface. The interface must be mapped to a bitmask by the EIS
implementation. The client may apply the binary OR operation onto these
bitmasks in ei_seat.bind. In response, the EIS implementation may then
create devices based on those bound capabilities.
For example, an EIS implementation may map "ei_pointer" to 0x1,
"ei_keyboard" to 0x4 and "ei_touchscreen" to 0x8. A client may then
ei_seat.bind(0xc) to bind to keyboard and touchscreen but not pointer.
Note that as shown in this example the set of masks may be sparse.
The value of the mask is constant for the lifetime of the seat but may differ
between seats.
For example, an EIS implementation may advertise support for
`ei_pointer` devices at bitmask `0x1`, `ei_keyboard` devices at `0x4`
and `ei_touchscreen` devices at `0x8`. A client may then execute the
request `ei_seat.bind(0xC)` to bind to keyboard and touchscreen devices
but not pointing devices.
Note that seat capabilities only represent a mask of possible capabilities on
devices in this seat. A capability that is not available on the seat cannot
ever be available on any device in this seat. For example, a seat that only has the
pointer and keyboard capabilities can never have a device with the touchscreen
capability. It is up to the EIS implementation to decide how many (if any) devices
with any given capability exist in this seat.
The EIS implementation must not advertise capabilities for interfaces
that have not been negotiated in the ei_handshake object.
Only interfaces that the client announced during ei_handshake.interface_version
can be a seat capability.
The EIS implementation may decide which capabilities a given seat has.
After ei_seat.done, the capabilities are constant for the lifetime of
the seat but may differ between seats. The masks may be sparse bitwise.
This event is sent multiple times - once per supported interface.
The set of capabilities is constant for the lifetime of the seat.
It is a protocol violation to send this event after the ei_seat.done event.
This event is sent multiple time for each supported interface, finishing
with ei_seat.done.
</description>
<arg name="mask" type="uint64" summary="the mask representing this capability"/>
<arg name="interface" type="string" summary="the interface name for this capability"/>
@ -536,13 +530,14 @@
<event name="device" since="1">
<description summary="Device presence notification">
Notification that a new device has been added.
Informs the client that a new device has been added to the seat.
The EIS implementation must never announce devices that have not been bound to with ei_seat.bind.
This event is only sent if the client announced support for the
"ei_device" interface in ei_handshake.interface_version.
The interface version is equal or less to the client-supported
version in ei_handshake.interface_version for the "ei_device"
interface.
`ei_device` interface in ei_handshake.interface_version. The interface
version is less than or equal to the client-supported version in
ei_handshake.interface_version for the `ei_device` interface.
</description>
<arg name="device" type="new_id" interface="ei_device" summary="the new device"/>
<arg name="version" type="uint32" summary="the interface version"/>
@ -560,9 +555,6 @@
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.
</description>
<!-- ei_device client requests version 1 -->
@ -894,16 +886,12 @@
<interface name="ei_pointer" version="1">
<description summary="device sub-interface for relative pointer motion">
Interface for relative pointer motion requests and events, originating
from physical devices like computer mice.
Interface for relative pointer motion requests and events.
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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_pointer client requests version 1 -->
@ -965,9 +953,6 @@
requests ei_pointer_absolute.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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_pointer_absolute client requests version 1 -->
@ -1031,9 +1016,6 @@
requests ei_scroll.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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_scroll client requests version 1 -->
@ -1175,9 +1157,6 @@
requests ei_button.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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_button client requests version 1 -->
@ -1253,9 +1232,6 @@
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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_keyboard client requests version 1 -->
@ -1326,7 +1302,7 @@
The keymap is constant for the lifetime of the device.
This event provides a file descriptor to the client which can be
This event provides a file descriptor to the client that can be
memory-mapped in read-only mode to provide a keyboard mapping
description. The fd must be mapped with MAP_PRIVATE by
the recipient, as MAP_SHARED may fail.
@ -1371,10 +1347,10 @@
For receiver clients, modifiers events will always be properly ordered
with received key events, so each key event should be interpreted using
the most recently-received modifier state. The server should send this
event immediately following the ei_device.frame event for the key press
that caused the change. If the state change impacts multiple keyboards,
this event should be sent for all of them.
the most recently-received modifier state. The EIS implementation should
send this event immediately following the ei_device.frame event for the
key press that caused the change. If the state change impacts multiple
keyboards, this event should be sent for all of them.
For sender clients, the modifiers event is not inherently synchronized
with key requests, but the client may send an ei_connection.sync request
@ -1397,10 +1373,10 @@
This event is only sent for devices with an ei_keyboard.keymap.
Note: A previous version of the documentation instead specified that
this event should not be sent in response to ei_keyboard.key events
that change the group or modifier state according to the keymap.
However, this complicated client implementation and resulted in
situations where the client state could get out of sync with the server.
this event should not be sent in response to ei_keyboard.key events that
change the group or modifier state according to the keymap. However,
this complicated client implementation and resulted in situations where
the client state could get out of sync with the EIS implementation.
</description>
<arg name="serial" type="uint32" summary="this event's serial number"/>
<arg name="depressed" type="uint32" summary="depressed modifiers"/>
@ -1418,9 +1394,6 @@
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 released.
Note that for a client to receive objects of this type, it must announce
support for this interface in ei_handshake.interface_version.
</description>
<!-- ei_touchscreen client requests version 1 -->