fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2026-01-08 14:00:19 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
libei/proto/protocol.xml
Peter Hutterer 0a347f433f protocol: make the connection setup the zero object with a proper handover 
This changes the initial connection negotiation to have the
ei_connection_setup as the pre-existing object id 0. Once the client has
sent all the data to set up the connection, the EIS implementation
replies with a new object ID that is the ei_connection protocol object,
i.e. the main object.

This allows for version negotiation of our main protocol object.
2023-03-03 11:21:26 +10:00

644 lines
23 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ei">
<copyright>
Copyright © 2008-2011 Kristian Høgsberg
Copyright © 2010-2011 Intel Corporation
Copyright © 2012-2013 Collabora, Ltd.
Copyright © 2023 Red Hat, Inc.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice (including the
next paragraph) shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
</copyright>
<!--
Protocol wire format: [length, sender-id, opcode, ...]
Where:
- length, sender-id and opcode are 32-bit integers in the
EIS implementation's native byte order.
- length is the length of the message in bytes, including the 12 header bytes
- sender-id is the id of the object sending the request/event. The sender-id
0 is reserved for the special "ei_connection_setup" object.
- opcode is the event or requeset-specific opcode, starting at 0
requests and events have overlapping opcode ranges, i.e. the first request
and the first event both have opcode 0.
- arguments is a variable number of arguments specific to the message.
Types:
- 'uint': a 32-bit unsigned integer
- 'int': a 32-bit signed integer
- '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
"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']
- 'new_id': an object id allocated by the caller. Client-allocated IDs begin
at 1 and must be less than 0xff000000.
IDs allocated by the EIS implementation start at and must not be less
than 0xff000000.
- 'object_id': a previously allocated object id
The initial connection is a two-step process:
An ei_connection_setup 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 .done 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.
-->
<interface name="ei_connection_setup" version="1">
<description summary="connection setup object">
This is a special interface to setup the client as seen by the EIS
implementation. The object for this interface has the fixed object
id 0 and only exists until the connection has been set up, see the
ei_connection_setup.connection event.
Once set up, the connection setup hands over to the main
ei_connection object which is the top-level object for all future
requests and events.
</description>
<request name="done" since="1">
<description summary="done request">
Notify the EIS implementation that configuration is complete.
The ei_conection_setup object will be destroyed by the
EIS implementation after this request is processed and
the client must not attempt to use it after that point.
</description>
</request>
<enum name="context_type" since="1">
<entry name="receiver" value="0"/>
<entry name="sender" value="1"/>
</enum>
<request name="type" since="1">
<description summary="type request">
Notify the EIS implementation of the type of this context.
This request is optional, the default client type is context_type.receiver.
This request must not be sent more than once.
</description>
<arg name="context_type" type="uint" enum="context_type" summary="the client context type"/>
</request>
<request name="name" since="1">
<description summary="type request">
Notify the EIS implementation of the client name. The name is a
human-presentable UTF-8 string. There is no requirement
for the EIS implementation to use this name.
This request is optional, the default client name is implementation-defined.
This request must not be sent more than once.
</description>
<arg name="name" type="string" summary="the client name"/>
</request>
<request name="interface" 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.
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 not be sent more than once per interface.
</description>
<arg name="name" type="string" summary="the interface name"/>
<arg name="version" type="uint" summary="the interface version"/>
</request>
<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
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
ei_connection_setup.interface request.
</description>
<arg name="version" type="uint"
summary="the highest version supported by the EIS implementation"/>
</event>
<event name="connection">
<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
ei_connection_setup.done request to the EIS implementation.
The ei_connection_setup 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 version sent by the server is the version of the ei_connection
interface as announced by ei_connection_setup.interface, or any
lower version.
</description>
<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"/>
</event>
</interface>
<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.
</description>
<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.
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.
<!-- FIXME: this needs to be something useful, but we don't have anything
useful to send yet -->
The callback_data passed in the callback is always zero.
</description>
<arg name="callback" type="new_id" interface="ei_callback"
summary="callback object for the sync request"/>
</request>
<request name="disconnect">
</request>
<enum name="disconnect_reason">
<description summary="disconnection reason">
A reason why a client was disconnected.
</description>
<entry name="disconnected" value="0" help="client was purposely disconnected"/>
<entry name="error" value="1" help="an error caused the disconnection"/>
</enum>
<event name="disconnected">
<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 due to some invalid request or other
protocol error, the reason is disconnect_reason.error and
explanation may contain a string explaining why. This string is
intended to help debugging only and is not guaranteed to stay constant.
There is no guarantee this event is sent - the connection may be closed
without a disconnection event.
</description>
<arg name="reason" type="uint" enum="disconnect_reason"/>
<arg name="explanation" type="string"/>
</event>
<event name="seat" since="1">
<description summary="Seat presence notification">
Notification that a new seat has been added.
The interface version is equal or less to the client-supported
version in ei_connection_setup.interface for the "ei_seat"
interface.
</description>
<arg name="seat" type="new_id" interface="ei_seat"/>
<arg name="version" type="uint" summary="the interface version"/>
</event>
</interface>
<interface name="ei_callback" version="1">
<description summary="callback object">
Clients can handle the 'done' event to get notified when
the related request is done.
</description>
<event name="done" type="destructor">
<description summary="done event">
Notify the client when the related request is done.
</description>
<arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
</event>
</interface>
<interface name="ei_seat" version="1">
<description summary="seat object">
</description>
<request name="release">
<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.
</description>
</request>
<enum name="capabilities" since="1">
<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">
<description summary="Seat binding">
Bind to the bitmask of capabilities given.
</description>
<arg name="capabilities" type="uint"/>
</request>
<event name="destroyed" since="1">
<description summary="Seat removal notification">
This seat has been removed and a client should release all
associated resources.
</description>
</event>
<event name="name" since="1">
<description summary="Seat name notification">
The name of this seat, if any. This event is optional and sent once immediately
after object creation.
</description>
<arg name="name" type="string" help="the seat name"/>
</event>
<event name="capabilities" since="1">
<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"/>
</event>
<event name="done" since="1">
<description summary="Seat setup completion notification">
Notification that the initial burst of events is complete and
the client can set up this seat now.
</description>
</event>
<event name="device" since="1">
<description summary="Device presence notification">
Notification that a new device has been added.
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="version" type="uint" summary="the interface version"/>
</event>
</interface>
<interface name="ei_device" version="1">
<request name="release">
<description summary="Device removal request">
Notification that the client is no longer interested in this device.
The EIS implementation will release any resources related to this device and
send the ei_device.destroyed event once complete.
</description>
</request>
<request name="start_emulating">
<arg name="sequence" type="uint"/>
</request>
<request name="stop_emulating">
</request>
<request name="frame">
<arg name="timestamp" type="uint"/>
<arg name="micros" type="uint"/>
</request>
<event name="destroyed" since="1">
<description summary="Device removal notification">
This device has been removed and a client should release all
associated resources.
</description>
</event>
<event name="name" since="1">
<description summary="device name notification">
The name of this device, if any. This event is optional and sent once immediately
after object creation.
</description>
<arg name="name" type="string" help="the device name"/>
</event>
<enum name="capabilities" since="1">
<entry name="pointer" value="2"/>
<entry name="pointer_absolute" value="4"/>
<entry name="keyboard" value="8"/>
<entry name="touch" value="16"/>
</enum>
<event name="capabilities" since="1">
<description summary="device capability notification">
A bitmask of the capabilties of this device.
</description>
<arg name="capabilities" type="uint" enum="capabilities" help="the device name"/>
</event>
<enum name="device_type" since="1">
<entry name="virtual" value="1"/>
<entry name="physical" value="2"/>
</enum>
<event name="type" since="1">
<description summary="device type notification">
The device type, one of virtual or physical.
</description>
<arg name="type" type="uint" enum="device_type" help="the device type"/>
</event>
<event name="dimensions" since="1">
<description summary="device dimensions notification">
The device dimensions in mm.
</description>
<arg name="width" type="uint" help="the device physical width"/>
<arg name="height" type="uint" help="the device physical height"/>
</event>
<event name="region" since="1">
<arg name="offset_x" type="uint"/>
<arg name="offset_y" type="uint"/>
<arg name="width" type="uint"/>
<arg name="hight" type="uint"/>
<arg name="scale" type="float"/>
</event>
<event name="pointer" since="1">
<arg name="pointer" type="new_id" interface="ei_pointer"/>
<arg name="version" type="uint" summary="the interface version"/>
</event>
<event name="keyboard" since="1">
<arg name="keyboard" type="new_id" interface="ei_keyboard"/>
<arg name="version" type="uint" summary="the interface version"/>
</event>
<event name="touchscreen" since="1">
<arg name="touchscreen" type="new_id" interface="ei_touchscreen"/>
<arg name="version" type="uint" summary="the interface version"/>
</event>
<event name="done" since="1">
<description summary="device setup completion notification">
Notification that the initial burst of events is complete and
the client can set up this device now.
</description>
</event>
<event name="resumed">
</event>
<event name="paused">
</event>
<event name="start_emulating">
<arg name="sequence" type="uint"/>
</event>
<event name="stop_emulating">
</event>
<event name="frame" since="1">
<arg name="timestamp" type="uint"/>
<arg name="micros" type="uint"/>
</event>
</interface>
<interface name="ei_pointer" version="1">
<description summary="pointer object">
</description>
<request name="release">
<description summary="Pointer removal request">
Notification that the client is no longer interested in this pointer.
The EIS implementation will release any resources related to this pointer and
send the ei_pointer.destroyed event once complete.
</description>
</request>
<request name="motion_relative" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="motion_absolute" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="scroll" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="scroll_discrete" since="1">
<arg name="x" type="int"/>
<arg name="y" type="int"/>
</request>
<request name="scroll_stop" since="1">
<arg name="x" type="uint"/>
<arg name="y" type="uint"/>
<arg name="is_cancel" type="uint"/>
</request>
<enum name="button_state" since="1">
<entry name="released" value="0"/>
<entry name="press" value="1"/>
</enum>
<request name="button" since="1">
<arg name="button" type="uint"/>
<arg name="state" type="uint" enum="button_state"/>
</request>
<event name="destroyed" since="1">
<description summary="Seat removal notification">
This pointer has been removed and a client should release all
associated resources.
</description>
</event>
<event name="motion_relative" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="motion_absolute" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="scroll" since="1">
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="scroll_discrete" since="1">
<arg name="x" type="int"/>
<arg name="y" type="int"/>
</event>
<event name="scroll_stop" since="1">
<arg name="x" type="uint"/>
<arg name="y" type="uint"/>
<arg name="is_cancel" type="uint"/>
</event>
<event name="button" since="1">
<arg name="button" type="uint"/>
<arg name="state" type="uint" enum="button_state"/>
</event>
</interface>
<interface name="ei_keyboard" version="1">
<description summary="keyboard object">
</description>
<request name="release">
<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
send the ei_keyboard.destroyed event once complete.
</description>
</request>
<enum name="keymap_type" since="1">
<entry name="xkb" value="1" help="an XKB keymap" />
</enum>
<event name="keymap" since="1">
<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"/>
</enum>
<request name="key" since="1">
<arg name="key" type="uint"/>
<arg name="state" type="uint" enum="key_state"/>
</request>
<event name="destroyed" since="1">
<description summary="Seat removal notification">
This keyboard has been removed and a client should release all
associated resources.
</description>
</event>
<event name="key" since="1">
<arg name="key" type="uint"/>
<arg name="state" type="uint" enum="key_state"/>
</event>
<event name="modifiers" since="1">
<arg name="depressed" type="uint"/>
<arg name="locked" type="uint"/>
<arg name="latched" type="uint"/>
<arg name="group" type="uint"/>
</event>
</interface>
<interface name="ei_touchscreen" version="1">
<description summary="touchscreen object">
</description>
<request name="release">
<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
send the ei_touch.destroyed event once complete.
</description>
</request>
<request name="down">
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="motion">
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</request>
<request name="up">
<arg name="touchid" type="uint"/>
</request>
<event name="destroyed" since="1">
<description summary="Seat removal notification">
This touch has been removed and a client should release all
associated resources.
</description>
</event>
<event name="down">
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="motion">
<arg name="touchid" type="uint"/>
<arg name="x" type="float"/>
<arg name="y" type="float"/>
</event>
<event name="up">
<arg name="touchid" type="uint"/>
</event>
</interface>
</protocol>
Reference in a new issue View git blame Copy permalink