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

proto: more documentation improvements

Browse source
This commit is contained in:
Peter Hutterer 2023-03-06 10:49:35 +10:00
parent ebd7d102cd
commit 4a3efa913a
1 changed files with 74 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
proto/protocol.xml
View file

@ -31,12 +31,13 @@
<documentation>
<chapter title="Wire format">
Protocol wire format: [sender-id, length, opcode, ...]
Protocol wire format: `[sender-id, length, opcode, ...]`
Where:
- sender-id is one 64-bit integer
- length and opcode are 32-bit integers
- all integers are in the EIS implementation's native byte order.
- length is the length of the message in bytes, including the 16 header bytes
for sender-id, length and opcode.
- sender-id is the id of the object sending the request/event. The sender-id
0 is reserved for the special "ei_handshake" object.
- opcode is the event or request-specific opcode, starting at 0.
@ -54,9 +55,10 @@
- 'float': a 32-bit IEEE-754 float
- 'fd': a file descriptor. Zero bytes in the message itself, transmitted
in the overhead
- 'string': a length-prefix zero-terminated string. Encoded as
one 32-bit unsigned integer for the length followed by the string.
The string is padded to the nearest 4-byte units, for example the string
- 'string': a length-prefixed zero-terminated string. Encoded as
one 32-bit unsigned integer for the length followed by the string
itself.
The string is padded to the nearest multiple of 4-byte, for example the string
"hello" is of length 6 but is zero-padded to 8 bytes and with the 4-byte
length field thus takes 12 bytes in total. Full (le) encoding:
[0x06, 0x00, 0x00, 0x00, 'h', 'e', 'l', 'l', 'o', '\0', '\0\, '\0']
@ -66,9 +68,16 @@
than 0xff00000000000000.
- 'object_id': a previously allocated object id
All integers are in the EIS implementation's native byte order.
Object IDs:
Object IDs are unique, monotonically increasing and must not be re-used by the
client or the server.
client or the EIS implementation.
Interface names:
Interface names on the wire are always in the form "ei_foo". See e.g.
the ei_handshake.interface_version request and event where interface
names are used.
Serial numbers:
Some events have serial numbers assiged by the EIS implementation. A serial is
@ -87,26 +96,39 @@
Protocol XML:
- a request or event marked as type="destructor" causes the object to be
destroyed immediately after that message has been sent.
- an argument with an "enum" attribute carries a value of the corresponding enum
- an argument with an "interface" attribute indicates that an object in the same message is
of that interface type
- an enum labelled "bitfield" indicates a single-bit value.
- a "protocol violation" must result in the EIS implementation disconnecting
the client with an error or (if appropriate) the client immediately disconnecting
from the EIS implementation.
- each request, event or enum has a "since" tag to indicate the interface version this element was
introduced in
- each interface has a "version" tag to indicate the current version of this interface
</chapter>
<chapter title="Initial Connection Handshake">
Initial Connection:
The initial connection is a two-step process:
An ei_handshake object with the special ID 0 is guaranteed to
exists. The client must send the appropriate requests to set up
its connection, followed by the .finish request. The server replies
by creating the ei_connection object with the client-requested version
(or any lower version) that is the connection for the remainder of this
client.
its connection, followed by the ei_handshake.finish request. The EIS
implementation replies by creating the ei_connection object with the
client-requested version (or any lower version) that is the connection for the
remainder of this client.
Version negotiation for interfaces is also handled in the ei_handshake
object. The client announces which interfaces are supported and their
respective version, future server-created objects will use that version or any
lower version.
Immediately after connecting, the EIS implementation must send the
ei_handshake.handshake_version event. The client replies with the
ei_handshake.handshake_version request to negotiate the version
of the ei_handshake object.
Version negotiation for other interfaces is also handled in the ei_handshake
object. The client announces which interfaces it supports and their
respective version, the EIS implementation should subsequently notify
the client about the interface version it supports.
Any object created by either the client or the EIS implementation must
use the lower of client and EIS implementation supported version.
In summary, a typical client connection does:
- connect to the socket
@ -309,7 +331,7 @@
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"
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.
@ -476,8 +498,8 @@
ei client implementation after the callback is fired and as
such the client must not attempt to use it after that point.
Note that for a server to use this request the client must announce
support for this interface in ei_handshake.interface. It is
Note that for a EIS implementation to use this request the client must
announce support for this interface in ei_handshake.interface. It is
a protocol violation to send this event to a client without the
"ei_pingpong" interface.
</description>
@ -523,7 +545,7 @@
<request name="done" type="destructor" since="1">
<description summary="done event">
Notify the server when the related event is done. Immediately after this request
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.
</description>
@ -738,7 +760,7 @@
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_keyboard or ei_touchscreen has
been requested by the server.
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
@ -1128,11 +1150,11 @@
<description summary="Scroll stop request">
Generate a a scroll stop or cancel event on this pointer.
A scroll stop event notifies the server that the interaction causing a
A scroll stop event notifies the EIS implementation that the interaction causing a
scroll motion previously triggered with ei_pointer.scroll or
ei_pointer.scroll_discrete has stopped. For example, if all
fingers are lifted off a touchpad, two-finger scrolling has logically
stopped. The server may use this information to e.g. start kinetic scrolling
stopped. The EIS implementation may use this information to e.g. start kinetic scrolling
previously based on the previous finger speed.
If is_cancel is nonzero, the event represents a cancellation of the
@ -1155,6 +1177,9 @@
</request>
<enum name="button_state" since="1">
<description summary="Button state">
The logical state of a button.
</description>
<entry name="released" value="0" summary="the button is logically up"/>
<entry name="press" value="1" summary="the button is logically down"/>
</enum>
@ -1251,6 +1276,9 @@
It is a protocol violation to send this request for a client
of an ei_handshake.context_type other than receiver.
It is an EIS implementation bug to send more than one button request
for the same button within the same ei_device.frame.
</description>
<arg name="button" type="uint32"/>
<arg name="state" type="uint32" enum="button_state"/>
@ -1283,6 +1311,9 @@
</request>
<enum name="key_state" since="1">
<description summary="Key state">
The logical state of a key.
</description>
<entry name="released" value="0" summary="the key is logically up"/>
<entry name="press" value="1" summary="the key is logically down"/>
</enum>
@ -1356,6 +1387,9 @@
It is a protocol violation to send this request for a client
of an ei_handshake.context_type other than receiver.
It is a protocol violation to send a key down event in the same
frame as a key up event for the same key in the same frame.
</description>
<arg name="key" type="uint32"/>
<arg name="state" type="uint32" enum="key_state"/>
@ -1417,6 +1451,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.
It is a protocol violation to send a touch down in the same
frame as a touch motion or touch up.
</description>
<arg name="touchid" type="uint32" summary="a unique touch id to identify this touch"/>
<arg name="x" type="float" summary="touch x coordinate in logical pixels"/>
@ -1431,6 +1468,9 @@
The x/y coordinates must be within the device's regions or the event is
silently discarded.
It is a protocol violation to send a touch motion in the same
frame as a touch down or touch up.
</description>
<arg name="touchid" type="uint32" summary="a unique touch id to identify this touch"/>
<arg name="x" type="float" summary="touch x coordinate in logical pixels"/>
@ -1444,6 +1484,9 @@
sent with ei_touchscreen.down.
The touchid may be re-used after this request.
It is a protocol violation to send a touch up in the same
frame as a touch motion or touch down.
</description>
<arg name="touchid" type="uint32" summary="a unique touch id to identify this touch"/>
</request>
@ -1468,6 +1511,9 @@
It is a protocol violation to send this request for a client
of an ei_handshake.context_type other than receiver.
It is a protocol violation to send a touch down in the same
frame as a touch motion or touch up.
</description>
<arg name="touchid" type="uint32"/>
<arg name="x" type="float"/>
@ -1480,6 +1526,9 @@
It is a protocol violation to send this request for a client
of an ei_handshake.context_type other than receiver.
It is a protocol violation to send a touch motion in the same
frame as a touch down or touch up.
</description>
<arg name="touchid" type="uint32"/>
<arg name="x" type="float"/>
@ -1492,6 +1541,9 @@
It is a protocol violation to send this request for a client
of an ei_handshake.context_type other than receiver.
It is a protocol violation to send a touch up in the same
frame as a touch motion or touch down.
</description>
<arg name="touchid" type="uint32"/>
</event>