mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2026-01-03 20:50:12 +01:00
db786c7822
This replaces the connect/connect_done and version/get_version requests. Immediately after connecting, the server sends an ei_protocol_setup event to the client with the ID of the object and the server's highest supported version number (of this object). This is a one-shot object that the client can use to configure its name and whether it is a sender or receiver context. Once .done is sent, the object is discarded. The server version is sent along to the client to allow for requests to be added to this object in the future. As a fixme left: the client now assumes to be connected as soon as the .done request is sent and the following sync event is received. The EIS implementation will not have actually eis_client_connect()ed the client yet, but it's good enough for now. Arguably, the CONNECTED event is superfluous anyway since *any* event other than DISCONNECTED indicates connected status. CONNECTED is a leftover from when the client created devices and needed to know if it's worth doing so.
394 lines
13 KiB
XML
394 lines
13 KiB
XML
<?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" 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
|
|
- 'uint': 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. Full (le) encoding:
|
|
[0x06, 0x00, 0x00, 0x00, 'h', 'e', 'l', 'l', 'o', '\0', '\0\, '\0']
|
|
|
|
-->
|
|
|
|
<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>
|
|
|
|
<request name="bind_seat">
|
|
<arg name="seat_id" type="uint"/>
|
|
<arg name="capabilities" type="uint"/>
|
|
</request>
|
|
|
|
<request name="close_device">
|
|
<arg name="device_id" type="uint"/>
|
|
</request>
|
|
|
|
<request name="pointer_relative">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</request>
|
|
|
|
<request name="pointer_absolute">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</request>
|
|
|
|
<request name="pointer_scroll">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</request>
|
|
|
|
<request name="pointer_scroll_discrete">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="int"/>
|
|
<arg name="y" type="int"/>
|
|
</request>
|
|
|
|
<request name="pointer_scroll_stop">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="uint"/>
|
|
<arg name="y" type="uint"/>
|
|
<arg name="is_cancel" type="uint"/>
|
|
</request>
|
|
|
|
<request name="pointer_button">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="button" type="uint"/>
|
|
<arg name="state" type="uint"/>
|
|
</request>
|
|
|
|
<request name="keyboard_key">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="key" type="uint"/>
|
|
<arg name="state" type="uint"/>
|
|
</request>
|
|
|
|
<request name="touch_down">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</request>
|
|
|
|
<request name="touch_motion">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</request>
|
|
|
|
<request name="touch_up">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
</request>
|
|
|
|
<request name="start_emulating">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="sequence" type="uint"/>
|
|
</request>
|
|
|
|
<request name="stop_emulating">
|
|
<arg name="device_id" type="uint"/>
|
|
</request>
|
|
|
|
<request name="frame">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="timestamp" type="uint"/>
|
|
<arg name="micros" type="uint"/>
|
|
</request>
|
|
|
|
<event name="connection_setup">
|
|
<description summary="initial connection setup">
|
|
Provides the client with an object to initialize and setup the connection.
|
|
This event is sent immediately after the client connects to the EIS
|
|
implementation.
|
|
|
|
A client should configure itself through that object, if applicable,
|
|
and complete this configuration with the ei_connection_setup.done event.
|
|
The object returned by this request will be destroyed by the
|
|
EIS implementation after that done event and a client must not
|
|
attempt to use it after that point.
|
|
|
|
The version sent by the server is the highest supported version
|
|
of the connection setup interface. A client must only use
|
|
requests supported by that version (or any lower version).
|
|
</description>
|
|
<arg name="setup" type="new_id" interface="ei_connection_setup"
|
|
summary="the connection setup object" />
|
|
<arg name="version" type="uint" summary="the version of the connection setup object"/>
|
|
</event>
|
|
|
|
<event name="disconnected">
|
|
</event>
|
|
|
|
<event name="seat_added">
|
|
<arg name="seat_id" type="uint"/>
|
|
<arg name="capabilities" type="uint"/>
|
|
<arg name="name" type="string"/>
|
|
</event>
|
|
|
|
<event name="seat_removed">
|
|
<arg name="seat_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="device_added">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="capabilities" type="uint"/>
|
|
<arg name="name" type="string"/>
|
|
<arg name="seat_id" type="uint"/>
|
|
<arg name="type" type="uint"/>
|
|
<arg name="width" type="uint"/>
|
|
<arg name="height" type="uint"/>
|
|
</event>
|
|
|
|
<event name="device_keymap">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="keymap_type" type="uint"/>
|
|
<arg name="keymap_size" type="uint"/>
|
|
<arg name="keymap" type="fd"/>
|
|
</event>
|
|
|
|
<event name="device_region">
|
|
<arg name="device_id" type="uint"/>
|
|
<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="device_done">
|
|
<arg name="device_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="device_removed">
|
|
<arg name="device_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="device_resumed">
|
|
<arg name="device_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="device_paused">
|
|
<arg name="device_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="pointer_relative">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="pointer_absolute">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="pointer_scroll">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="pointer_scroll_discrete">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="int"/>
|
|
<arg name="y" type="int"/>
|
|
</event>
|
|
|
|
<event name="pointer_scroll_stop">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="x" type="uint"/>
|
|
<arg name="y" type="uint"/>
|
|
<arg name="is_cancel" type="uint"/>
|
|
</event>
|
|
|
|
<event name="pointer_button">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="button" type="uint"/>
|
|
<arg name="state" type="uint"/>
|
|
</event>
|
|
|
|
<event name="keyboard_key">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="key" type="uint"/>
|
|
<arg name="state" type="uint"/>
|
|
</event>
|
|
|
|
<event name="keyboard_modifiers">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="depressed" type="uint"/>
|
|
<arg name="locked" type="uint"/>
|
|
<arg name="latched" type="uint"/>
|
|
<arg name="group" type="uint"/>
|
|
</event>
|
|
|
|
<event name="touch_down">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="touch_motion">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="touch_up">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="touchid" type="uint"/>
|
|
</event>
|
|
|
|
<event name="start_emulating">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="sequence" type="uint"/>
|
|
</event>
|
|
|
|
<event name="stop_emulating">
|
|
<arg name="device_id" type="uint"/>
|
|
</event>
|
|
|
|
<event name="frame">
|
|
<arg name="device_id" type="uint"/>
|
|
<arg name="timestamp" type="uint"/>
|
|
<arg name="micros" type="uint"/>
|
|
</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_connection_setup" version="1">
|
|
<description summary="connection setup object">
|
|
</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>
|
|
</interface>
|
|
|
|
</protocol>
|
|
|