mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2025-12-29 18:20:09 +01:00
fadc1853c9
Sitting nested below the ei_seat, the client gets a notification for a device through the ei_seat.device event.
542 lines
19 KiB
XML
542 lines
19 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="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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
</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>
|
|
|
|
<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="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>
|
|
|
|
<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="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>
|
|
|
|
</interface>
|
|
</protocol>
|
|
|