mirror of
https://gitlab.freedesktop.org/libinput/libei.git
synced 2025-12-25 14:00:06 +01:00
5331dc0bf2
A device may not have a keymap in which case it just sends scancodes hoping they'll be mapped to something sensible.
1517 lines
69 KiB
XML
1517 lines
69 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>
|
|
|
|
<interface name="ei_handshake" version="1">
|
|
<description summary="handshake 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_handshake.connection event.
|
|
|
|
The ei_handshake version is 1 until:
|
|
- the EIS implementation sends the interface_version event with
|
|
a version other than 1, and, in response,
|
|
- the client sends the interface_version request with a
|
|
version equal or lower to the EIS implementation version.
|
|
|
|
The EIS implementation must send the interface_version event immediately
|
|
once the physical connection has been established.
|
|
|
|
Once the ei_connection.connection event has been sent the handshake
|
|
is destroyed by the EIS implementation.
|
|
</description>
|
|
|
|
<!-- 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.
|
|
|
|
Immediately after sending this request, the client must assume the negotiated
|
|
version number for the ei_handshake interface and the EIS implementation
|
|
may send events and process requests matching that version.
|
|
|
|
This request must be sent exactly once and it must be the first request
|
|
the client sends.
|
|
</description>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</request>
|
|
|
|
<request name="finish" since="1">
|
|
<description summary="setup completion request">
|
|
Notify 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.
|
|
</description>
|
|
</request>
|
|
|
|
<enum name="context_type" since="1">
|
|
<description summary="context type">
|
|
This enum denotes context types for the libei context.
|
|
|
|
A context type of receiver is a libei context receiving events
|
|
from the EIS implementation. A context type of sender is a libei context
|
|
sending events to the EIS implementation.
|
|
</description>
|
|
<entry name="receiver" value="1" summary="this client receives events from the EIS implementation"/>
|
|
<entry name="sender" value="2" summary="this client sends events to the EIS implementation"/>
|
|
</enum>
|
|
|
|
<request name="context_type" since="1">
|
|
<description summary="context type request">
|
|
Notify the EIS implementation of the type of this context. The context types
|
|
defines whether the client will send events to or receive events from the
|
|
EIS implementation.
|
|
|
|
Depending on the context type, certain requests must not be used and some
|
|
events must not be sent by the EIS implementation.
|
|
|
|
This request is optional, the default client type is context_type.receiver.
|
|
This request must not be sent more than once and must be sent before
|
|
ei_handshake.finish.
|
|
</description>
|
|
<arg name="context_type" type="uint32" enum="context_type" summary="the client context type"/>
|
|
</request>
|
|
|
|
<request name="name" since="1">
|
|
<description summary="context name request">
|
|
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
|
|
permissions to connect).
|
|
|
|
There is no requirement for the EIS implementation to use this name. For
|
|
example, where the client is managed through an XDG Desktop Portal an EIS
|
|
implementation would typically use client identification information sent
|
|
by the portal instead.
|
|
|
|
This request is optional, the default client name is implementation-defined.
|
|
This request must not be sent more than once and must be sent before
|
|
ei_handshake.finish.
|
|
</description>
|
|
<arg name="name" type="string" summary="the client name"/>
|
|
</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.
|
|
|
|
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_handshake.finish.
|
|
|
|
This request must not be sent for the "ei_handshake" interface, use
|
|
the ei_handshake.handshake_version request instead.
|
|
|
|
Note that an EIS implementation may consider some interfaces to
|
|
be required and immediately ei_connection.disconnect a client
|
|
not supporting those interfaces.
|
|
|
|
This request must not be sent more than once per interface and must be
|
|
sent before ei_handshake.finish.
|
|
</description>
|
|
<arg name="name" type="string" summary="the interface name"/>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</request>
|
|
|
|
<!-- 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.
|
|
|
|
In response, the client must send the ei_handshake.handshake_version request
|
|
with any version up to including the version provided in this event.
|
|
See the ei_handshake.handshake_version request for details on what happens next.
|
|
</description>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</event>
|
|
|
|
<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.
|
|
|
|
This event must be sent by the EIS implementation for any
|
|
interfaces that supports client-created objects (e.g. "ei_callback")
|
|
before the ei_handshake.connection event.
|
|
The client must not assume those interfaces are supported unless
|
|
and until those versions have been received.
|
|
|
|
This request must not be sent for the "ei_handshake" interface, use
|
|
the handshake_version event instead.
|
|
|
|
This event may be sent by the EIS implementation for any
|
|
other supported interface (but not necessarily all supported
|
|
interfaces) before the ei_handshake.connection event.
|
|
</description>
|
|
<arg name="name" type="string" summary="the interface name"/>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</event>
|
|
|
|
<event name="connection" type="destructor" since="1">
|
|
<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 exactly once at some unspecified time 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 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.
|
|
|
|
The serial number is the start value of the EIS implementation's serial
|
|
number sequence. Clients must not assume any specific value for this
|
|
serial number. Any future serial number in any event is monotonically
|
|
increasing by an unspecified amount.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
<arg name="connection" type="new_id" interface="ei_connection"
|
|
summary="the connection object" />
|
|
<arg name="version" type="uint32" summary="the version of the connection object"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_connection" version="1">
|
|
<description summary="core global object">
|
|
The core connection object. This is the top-level object for any communication
|
|
with the EIS implementation.
|
|
|
|
Note that for a client to receive this object, it must announce
|
|
support for this interface in ei_handshake.interface_version.
|
|
</description>
|
|
|
|
<!-- ei_connection client requests version 1 -->
|
|
|
|
<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.
|
|
|
|
The callback_data in the ei_callback.done event is always zero.
|
|
|
|
Note that for a client to use this request it must announce
|
|
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
|
|
the client.
|
|
</description>
|
|
<arg name="callback" type="new_id" interface="ei_callback"
|
|
summary="callback object for the sync request"/>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</request>
|
|
|
|
<request name="disconnect" type="destructor" since="1">
|
|
<description summary="disconnection request">
|
|
A request to the EIS implementation that this client should be disconnected.
|
|
This is a courtesy request to allow the EIS implementation to distinquish
|
|
between a client disconnecting on purpose and one disconnecting through the
|
|
socket becoming invalid.
|
|
|
|
Immediately after sending this request, the client may destroy the
|
|
ei_connection object and it should close the socket. The EIS implementation
|
|
will treat the connection as already disconnected on receipt and does not
|
|
send the ei_connection.disconnect event in response to this request.
|
|
</description>
|
|
</request>
|
|
|
|
<!-- ei_connection events version 1 -->
|
|
|
|
<enum name="disconnect_reason" since="1">
|
|
<description summary="disconnection reason">
|
|
A reason why a client was disconnected. This enum is intended to
|
|
provide information to the client on whether it was disconnected as
|
|
part of normal operations or as result of an error on either the client
|
|
or EIS implementation side.
|
|
|
|
A nonzero value describes an error, with the generic value "error" (1) reserved
|
|
as fallback.
|
|
|
|
This enum may be extended in the future, clients must be able to handle
|
|
values that are not in their supported version of this enum.
|
|
</description>
|
|
<entry name="disconnected" value="0" summary="client was purposely disconnected"/>
|
|
<entry name="error" value="1" summary="an error caused the disconnection"/>
|
|
<entry name="mode" value="2" summary="sender/receiver client sent request for receiver/sender mode"/>
|
|
<entry name="protocol" value="3" summary="client committed a protocol violation"/>
|
|
<entry name="value" value="4" summary="client sent an invalid value"/>
|
|
<entry name="transport" value="5" summary="error on the transport layer"/>
|
|
</enum>
|
|
|
|
<event name="disconnected" type="destructor" since="1">
|
|
<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 a request by the client or zero if the client has not
|
|
yet issued a request.
|
|
|
|
Where a client is disconnected by EIS on purpose, for example after
|
|
a user interaction, the reason is disconnect_reason.disconnected (i.e. zero)
|
|
and the explanation is NULL.
|
|
|
|
Where a client is disconnected due to some invalid request or other
|
|
protocol error, the reason is one of disconnect_reason (i.e. nonzero) and
|
|
explanation may contain a string explaining why. This string is
|
|
intended to help debugging only and is not guaranteed to stay constant.
|
|
|
|
The ei_connection 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.
|
|
|
|
There is no guarantee this event is sent - the connection may be closed
|
|
without a disconnection event.
|
|
</description>
|
|
<arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
|
|
<arg name="reason" type="uint32" enum="disconnect_reason" summary="the reason for being disconnected"/>
|
|
<arg name="explanation" type="string" allow-null="true" summary="an explanation for debugging purposes"/>
|
|
</event>
|
|
|
|
<event name="seat" since="1">
|
|
<description summary="Seat presence notification">
|
|
Notification that a new seat has been added.
|
|
|
|
A seat is a set of input devices that logically belong together.
|
|
|
|
This event is only sent if the client announced support for the
|
|
"ei_seat" 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_seat"
|
|
interface.
|
|
</description>
|
|
<arg name="seat" type="new_id" interface="ei_seat"/>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</event>
|
|
|
|
<event name="invalid_object" since="1">
|
|
<description summary="Invalid object in request notification">
|
|
Notification 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
|
|
does not exist as seen by the EIS implementation. The protocol is
|
|
asynchronous and this may occur e.g. when the EIS implementation
|
|
destroys an object at the same time as the client requests functionality
|
|
from that object. For example, an EIS implementation may send
|
|
ei_device.destroyed and destroy the device's resources (and protocol object)
|
|
at the same time as the client attempts to ei_device.start_emulating
|
|
on that object.
|
|
|
|
It is the client's responsibilty to unwind any state changes done
|
|
to the object since the last successful message.
|
|
</description>
|
|
<arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
|
|
<arg name="invalid_id" type="uint64" />
|
|
</event>
|
|
|
|
<event name="ping" since="1">
|
|
<description summary="ping event">
|
|
The ping event asks the client to emit the 'done' event
|
|
on the provided 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 must be destroyed by the
|
|
ei client 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 resulting ei_pingpong.done request is
|
|
ignored by the EIS implementation.
|
|
|
|
Note that for a EIS implementation to use this request the client must
|
|
announce support for this interface in ei_handshake.interface_version. It is
|
|
a protocol violation to send this event to a client without the
|
|
"ei_pingpong" interface.
|
|
</description>
|
|
<arg name="ping" type="new_id" interface="ei_pingpong"
|
|
summary="callback object for the ping request"/>
|
|
<arg name="version" type="uint32" summary="the version of the callback object"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_callback" version="1">
|
|
<description summary="callback object">
|
|
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.
|
|
</description>
|
|
<arg name="callback_data" type="uint64" summary="request-specific data for the callback"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_pingpong" version="1">
|
|
<description summary="callback object">
|
|
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.
|
|
</description>
|
|
<arg name="callback_data" type="uint64" summary="request-specific data for the callback"/>
|
|
</request>
|
|
|
|
<!-- ei_pingpong events version 1 -->
|
|
</interface>
|
|
|
|
<interface name="ei_seat" version="1">
|
|
<description summary="seat object">
|
|
An ei_seat represents a set of input devices that logically belong together. In most
|
|
cases only one seat is present and all input devices on that seat share the same
|
|
pointer and keyboard focus.
|
|
|
|
A seat has potential capabilities, a client is expected to bind to those capabilities.
|
|
The EIS implementation then creates logical input devices based on the capabilities the
|
|
client is interested in.
|
|
|
|
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.
|
|
|
|
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.
|
|
</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.
|
|
|
|
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>
|
|
|
|
<!-- ei_seat events version 1 -->
|
|
|
|
<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.
|
|
|
|
This ei_seat object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</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.
|
|
|
|
It is a protocol violation to send this event after the ei_seat.done event.
|
|
</description>
|
|
<arg name="name" type="string" summary="the seat name"/>
|
|
</event>
|
|
|
|
<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.
|
|
|
|
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 contant for the lifetime of the seat but may differ
|
|
between seats.
|
|
|
|
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.
|
|
|
|
Only interfaces that the client announced during ei_handshake.interface_version
|
|
can be a seat capability.
|
|
|
|
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.
|
|
</description>
|
|
<arg name="mask" type="uint64" summary="the mask representing this capability"/>
|
|
<arg name="interface" type="string" summary="the interface name for this capability"/>
|
|
</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.
|
|
|
|
It is a protocol violation to send this event more than once.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="device" since="1">
|
|
<description summary="Device presence notification">
|
|
Notification that a new device has been added.
|
|
|
|
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.
|
|
</description>
|
|
<arg name="device" type="new_id" interface="ei_device" summary="the new device"/>
|
|
<arg name="version" type="uint32" summary="the interface version"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_device" version="2">
|
|
<description summary="device object">
|
|
An ei_device represents a single logical input devices. Like physical input devices
|
|
an ei_device may have multiple capabilities and may e.g. function as pointer
|
|
and keyboard.
|
|
|
|
Depending on the ei_handshake.context_type, an ei_device can
|
|
emulate events via client requests or receive events. It is a protocol violation
|
|
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 -->
|
|
|
|
<request name="release" since="1">
|
|
<description summary="Device removal request">
|
|
Notification that the client is no longer interested in this device.
|
|
|
|
Note that releasing a device does not guarantee another device becomes available.
|
|
|
|
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" since="1" context-type="sender">
|
|
<description summary="Device start emulating request">
|
|
Notify the EIS implementation that the given device is about to start
|
|
sending events. This should be seen more as a transactional boundary than a
|
|
time-based boundary. The primary use-cases for this are to allow for setup on
|
|
the EIS implementation side and/or UI updates to indicate that a device is
|
|
sending events now and for out-of-band information to sync with a given event
|
|
sequence.
|
|
|
|
There is no actual requirement that events start immediately once emulation
|
|
starts and there is no requirement that a client calls ei_device.stop_emulating
|
|
after the most recent events.
|
|
For example, in a remote desktop use-case the client would call
|
|
ei_device.start_emulating once the remote desktop session starts (rather than when
|
|
the device sends events) and ei_device.stop_emulating once the remote desktop
|
|
session stops.
|
|
|
|
The sequence number identifies this transaction between start/stop emulating.
|
|
It must go up by at least 1 on each call to ei_device.start_emulating.
|
|
Wraparound must be handled by the EIS implementation but callers must ensure
|
|
that detection of wraparound is possible.
|
|
|
|
It is a protocol violation to request ei_device.start_emulating after
|
|
ei_device.start_emulating without an intermediate stop_emulating.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
|
|
<arg name="sequence" type="uint32" summary="sequence number to identify this emulation sequence"/>
|
|
</request>
|
|
|
|
<request name="stop_emulating" since="1" context-type="sender">
|
|
<description summary="Device start emulating request">
|
|
Notify the EIS implementation that the given device is no longer sending
|
|
events. See ei_device.start_emulating for details.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
|
|
</request>
|
|
|
|
<request name="frame" since="1" context-type="sender">
|
|
<description summary="Device frame request">
|
|
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_pointer_absolute,
|
|
ei_scroll, ei_button, ei_keyboard or ei_touchscreen has
|
|
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
|
|
a key within the same frame is a logical noop.
|
|
|
|
The given timestamp applies to all events in the current frame.
|
|
The timestamp must be in microseconds of CLOCK_MONOTONIC.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="last_serial" type="uint32" summary="the last serial sent by the EIS implementation"/>
|
|
<arg name="timestamp" type="uint64" summary="timestamp in microseconds"/>
|
|
</request>
|
|
|
|
<!-- ei_device events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Device removal notification">
|
|
This device has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This ei_device object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</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.
|
|
|
|
It is a protocol violation to send this event after the ei_device.done event.
|
|
</description>
|
|
<arg name="name" type="string" summary="the device name"/>
|
|
</event>
|
|
|
|
<enum name="device_type" since="1">
|
|
<description summary="device type">
|
|
If the device type is ei_device.device_type.virtual, the device is a
|
|
virtual device representing input as applied on the EIS implementation's
|
|
screen. A relative virtual device generates input events in logical pixels,
|
|
an absolute virtual device generates input events in logical pixels on one
|
|
of the device's regions. Virtual devices do not have a ei_device.dimension but
|
|
it may have an ei_device.region.
|
|
|
|
If the device type is ei_device.device_type.physical, the device is a
|
|
representation of a physical device as if connected to the EIS
|
|
implementation's host computer. A relative physical device generates input
|
|
events in mm, an absolute physical device generates input events in mm
|
|
within the device's specified physical size. Physical devices do not have
|
|
regions and no ei_device.region events are sent for such devices.
|
|
</description>
|
|
<entry name="virtual" value="1" summary="a virtual device"/>
|
|
<entry name="physical" value="2" summary="representation of a physical device"/>
|
|
</enum>
|
|
|
|
<event name="device_type" since="1">
|
|
<description summary="device type notification">
|
|
The device type, one of virtual or physical.
|
|
|
|
Devices of type ei_device.device_type.physical are supported only clients of
|
|
type ei_handshake.context_type.receiver.
|
|
|
|
This event is sent once immediately after object creation.
|
|
It is a protocol violation to send this event after the ei_device.done event.
|
|
</description>
|
|
<arg name="device_type" type="uint32" enum="device_type" summary="the device type"/>
|
|
</event>
|
|
|
|
<event name="dimensions" since="1">
|
|
<description summary="device dimensions notification">
|
|
The device dimensions in mm. This event is optional and sent once immediately
|
|
after object creation.
|
|
|
|
This event is only sent for devices of ei_device.device_type.physical.
|
|
|
|
It is a protocol violation to send this event after the ei_device.done event.
|
|
</description>
|
|
<arg name="width" type="uint32" summary="the device physical width in mm"/>
|
|
<arg name="height" type="uint32" summary="the device physical height in mm"/>
|
|
</event>
|
|
|
|
<event name="region" since="1">
|
|
<description summary="device dimensions notification">
|
|
Notifies the client of one region. The number of regions is constant for a device
|
|
and all regions are announced immediately after object creation.
|
|
|
|
A region is rectangular and defined by an x/y offset and a width and a height.
|
|
A region defines the area on an EIS desktop layout that is accessible by
|
|
this device - this region may not be the full area of the desktop.
|
|
Input events may only be sent for points within the regions.
|
|
|
|
The use of regions is private to the EIS compositor and coordinates may not
|
|
match the size of the actual desktop. For example, a compositor may set a
|
|
1920x1080 region to represent a 4K monitor and transparently map input
|
|
events into the respective true pixels.
|
|
|
|
Absolute devices may have different regions, it is up to the libei client
|
|
to send events through the correct device to target the right pixel. For
|
|
example, a dual-head setup my have two absolute devices, the first with a
|
|
zero offset region spanning the left screen, the second with a nonzero
|
|
offset spanning the right screen.
|
|
|
|
The physical scale denotes a constant factor that needs to be applied to
|
|
any relative movement on this region for that movement to match the same
|
|
*physical* movement on another region.
|
|
|
|
It is an EIS implementation bug to advertise the absolute pointer capability
|
|
on a device_type.virtual device without advertising an ei_region for this device.
|
|
|
|
This event is optional and sent immediately after object creation. Where a device
|
|
has multiple regions, this event is sent once for each region.
|
|
It is a protocol violation to send this event after the ei_device.done event.
|
|
|
|
Note: the fourth argument ('hight') was misspelled when the protocol was declared
|
|
stable but changing the name is an API breaking change.
|
|
</description>
|
|
<arg name="offset_x" type="uint32" summary="region x offset in logical pixels"/>
|
|
<arg name="offset_y" type="uint32" summary="region y offset in logical pixels"/>
|
|
<arg name="width" type="uint32" summary="region width in logical pixels"/>
|
|
<!-- note the typo: hight -->
|
|
<arg name="hight" type="uint32" summary="region height in logical pixels"/>
|
|
<arg name="scale" type="float" summary="the physical scale for this region"/>
|
|
</event>
|
|
|
|
<event name="interface" since="1">
|
|
<description summary="device capability notification">
|
|
Notification that a new device has a sub-interface.
|
|
|
|
This event may be sent for the
|
|
- "ei_pointer" interface if the device has the
|
|
ei_device.capabilities.pointer capability
|
|
- "ei_pointer_absolute" interface if the device has the
|
|
ei_device.capabilities.pointer_absolute capability
|
|
- "ei_scroll" interface if the device has the
|
|
ei_device.capabilities.scroll capability
|
|
- "ei_button" interface if the device has the
|
|
ei_device.capabilities.button capability
|
|
- "ei_keyboard" interface if the device has the
|
|
ei_device.capabilities.keyboard capability
|
|
- "ei_touchscreen" interface if the device has the
|
|
ei_device.capabilities.touchscreen capability
|
|
The interface version is equal or less to the client-supported
|
|
version in ei_handshake.interface_version for the respective interface.
|
|
|
|
This event is optional and sent immediately after object creation
|
|
and at most once per interface.
|
|
It is a protocol violation to send this event after the ei_device.done event.
|
|
</description>
|
|
<arg name="object" type="new_id" interface_arg="interface_name" />
|
|
<arg name="interface_name" type="string" summary="the interface name" />
|
|
<arg name="version" type="uint32" 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.
|
|
|
|
It is a protocol violation to send this event more than once per device.
|
|
</description>
|
|
</event>
|
|
|
|
<event name="resumed" since="1">
|
|
<description summary="device resumed notification">
|
|
Notification that the device has been resumed by the EIS implementation
|
|
and (depending on the ei_handshake.context_type) the client may request
|
|
ei_device.start_emulating or the EIS implementation may
|
|
ei_device.start_emulating events.
|
|
|
|
It is a client bug to request emulation of events on a device that is
|
|
not resumed. The EIS implementation may silently discard such events.
|
|
|
|
A newly advertised device is in the ei_device.paused state.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="paused" since="1">
|
|
<description summary="device paused notification">
|
|
Notification that the device has been paused by the EIS implementation
|
|
and no futher events will be accepted on this device until
|
|
it is resumed again.
|
|
|
|
For devices of ei_device_setup.context_type sender, the client thus does
|
|
not need to request ei_device.stop_emulating and may request
|
|
ei_device.start_emulating after a subsequent ei_device.resumed.
|
|
|
|
For devices of ei_device_setup.context_type receiver and where
|
|
the EIS implementation did not send a ei_device.stop_emulating
|
|
prior to this event, the device may send a ei_device.start_emulating
|
|
event after a subsequent ei_device.resumed event.
|
|
|
|
Pausing a device resets the logical state of the device to neutral.
|
|
This includes:
|
|
- any buttons or keys logically down are released
|
|
- any modifiers logically down are released
|
|
- any touches logically down are released
|
|
|
|
It is a client bug to request emulation of events on a device that is
|
|
not resumed. The EIS implementation may silently discard such events.
|
|
|
|
A newly advertised device is in the ei_device.paused state.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="start_emulating" since="1" context-type="receiver">
|
|
<description summary="Device start emulating event">
|
|
See the ei_device.start_emulating request for details.
|
|
|
|
It is a protocol violation to send this event for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
<arg name="sequence" type="uint32"/>
|
|
</event>
|
|
|
|
<event name="stop_emulating" since="1" context-type="receiver">
|
|
<description summary="Device stop emulating event">
|
|
See the ei_device.stop_emulating request for details.
|
|
|
|
It is a protocol violation to send this event for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="frame" since="1" context-type="receiver">
|
|
<description summary="Device frame event">
|
|
See the ei_device.frame request for details.
|
|
|
|
It is a protocol violation to send this event for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
<arg name="timestamp" type="uint64" summary="timestamp in microseconds"/>
|
|
</event>
|
|
|
|
<!-- ei_device events version 2 -->
|
|
|
|
<event name="region_mapping_id" since="2">
|
|
<description summary="region id notification">
|
|
Notifies the client that the region specified in the next ei_device.region
|
|
event is to be assigned the given mapping_id.
|
|
|
|
This ID can be used by the client to identify an external resource that has a
|
|
relationship with this region.
|
|
For example the client may receive a data stream with the video
|
|
data that this region represents. By attaching the same identifier to the data
|
|
stream and this region the EIS implementation can inform the client
|
|
that the video data stream and the region represent paired data.
|
|
|
|
This event is optional and sent immediately after object creation but before
|
|
the corresponding ei_device.region event. Where a device has multiple regions,
|
|
this event may be sent zero or one time for each region.
|
|
It is a protocol violation to send this event after the ei_device.done event or
|
|
to send this event without a corresponding following ei_device.region event.
|
|
</description>
|
|
<arg name="mapping_id" type="string" summary="region mapping id"/>
|
|
</event>
|
|
|
|
</interface>
|
|
|
|
<interface name="ei_pointer" version="1">
|
|
<description summary="pointer object">
|
|
Interface for pointer motion requests and events. This interface
|
|
is available on devices with the ei_device.capability pointer.
|
|
|
|
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 releasd.
|
|
|
|
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 -->
|
|
|
|
<request name="release" since="1">
|
|
<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" context-type="sender">
|
|
<description summary="Relative motion request">
|
|
Generate a relative motion event on this pointer.
|
|
|
|
It is a client bug to send this request more than once
|
|
within the same ei_device.frame.
|
|
|
|
It is a client bug to send this request on a device without
|
|
the ei_device.capabilities.pointer capability.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="x" type="float" summary="the x movement in logical pixels"/>
|
|
<arg name="y" type="float" summary="the y movement in logical pixels"/>
|
|
</request>
|
|
|
|
<!-- ei_pointer events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Pointer removal notification">
|
|
This object has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="motion_relative" since="1" context-type="receiver">
|
|
<description summary="Relative motion event">
|
|
See the ei_pointer.motion_relative request for details.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_pointer_absolute" version="1">
|
|
<description summary="absolute pointer object">
|
|
Interface for absolute pointer requests and events. This interface
|
|
is available on devices with the ei_device.capability pointer_absolute.
|
|
|
|
This interface is only provided once per device and where a client
|
|
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 releasd.
|
|
|
|
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 -->
|
|
|
|
<request name="release" since="1">
|
|
<description summary="Pointer absolute removal request">
|
|
Notification that the client is no longer interested in this object.
|
|
The EIS implementation will release any resources related to this object and
|
|
send the ei_pointer_absolute.destroyed event once complete.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="motion_absolute" since="1" context-type="sender">
|
|
<description summary="Absolute motion request">
|
|
Generate an absolute motion event on this pointer. The x/y
|
|
coordinates must be within the device's regions or the event
|
|
is silently discarded.
|
|
|
|
It is a client bug to send this request more than once
|
|
within the same ei_device.frame.
|
|
|
|
It is a client bug to send this request on a device without
|
|
the ei_device.capabilities.pointer_absolute capability.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="x" type="float" summary="the x position in logical pixels"/>
|
|
<arg name="y" type="float" summary="the y position in logical pixels"/>
|
|
</request>
|
|
|
|
<!-- ei_pointer_absolute events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Pointer absolute removal notification">
|
|
This object has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="motion_absolute" since="1" context-type="receiver">
|
|
<description summary="Absolute motion event">
|
|
See the ei_pointer_absolute.motion_absolute request for details.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_scroll" version="1">
|
|
<description summary="scroll object">
|
|
Interface for scroll requests and events. This interface
|
|
is available on devices with the ei_device.capability scroll.
|
|
|
|
This interface is only provided once per device and where a client
|
|
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 releasd.
|
|
|
|
Note that for a client to receive objects of this type, it must announce
|
|
support for this interface in ei_handshake.interface_version.
|
|
</description>
|
|
|
|
<request name="release" since="1">
|
|
<description summary="Scroll removal request">
|
|
Notification that the client is no longer interested in this object.
|
|
The EIS implementation will release any resources related to this object and
|
|
send the ei_scroll.destroyed event once complete.
|
|
</description>
|
|
</request>
|
|
|
|
<request name="scroll" since="1" context-type="sender">
|
|
<description summary="Scroll request">
|
|
Generate a a smooth (pixel-precise) scroll event on this pointer.
|
|
Clients must not send ei_scroll.scroll_discrete events for the same event,
|
|
the EIS implementation is responsible for emulation of discrete
|
|
scroll events.
|
|
|
|
It is a client bug to send this request more than once
|
|
within the same ei_device.frame.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="x" type="float" summary="the x movement in logical pixels"/>
|
|
<arg name="y" type="float" summary="the y movement in logical pixels"/>
|
|
</request>
|
|
|
|
<request name="scroll_discrete" since="1" context-type="sender">
|
|
<description summary="Scroll discrete request">
|
|
Generate a a discrete (e.g. wheel) scroll event on this pointer.
|
|
Clients must not send ei_scroll.scroll events for the same event,
|
|
the EIS implementation is responsible for emulation of smooth
|
|
scroll events.
|
|
|
|
A discrete scroll event is based logical scroll units (equivalent to one
|
|
mouse wheel click). The value for one scroll unit is 120, a fraction or
|
|
multiple thereof represents a fraction or multiple of a wheel click.
|
|
|
|
It is a client bug to send this request more than once
|
|
within the same ei_device.frame.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="x" type="int32" summary="the x movement in fractions or multiples of 120"/>
|
|
<arg name="y" type="int32" summary="the y movement in fractions or multiples of 120"/>
|
|
</request>
|
|
|
|
<request name="scroll_stop" since="1" context-type="sender">
|
|
<description summary="Scroll stop request">
|
|
Generate a a scroll stop or cancel event on this pointer.
|
|
|
|
A scroll stop event notifies the EIS implementation that the interaction causing a
|
|
scroll motion previously triggered with ei_scroll.scroll or
|
|
ei_scroll.scroll_discrete has stopped. For example, if all
|
|
fingers are lifted off a touchpad, two-finger scrolling has logically
|
|
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
|
|
current interaction. This indicates that the interaction has stopped to the
|
|
point where further (server-emulated) scroll events from this device are wrong.
|
|
|
|
It is a client bug to send this request more than once
|
|
within the same ei_device.frame.
|
|
|
|
It is a client bug to send this request for an axis that
|
|
had a a nonzero value in either ei_scroll.scroll or ei_scroll.scroll_discrete
|
|
in the current frame.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="x" type="uint32" summary="nonzero if this axis stopped scrolling"/>
|
|
<arg name="y" type="uint32" summary="nonzero if this axis stopped scrolling"/>
|
|
<arg name="is_cancel" type="uint32" summary="nonzero to indicate this is a cancel event"/>
|
|
</request>
|
|
|
|
<!-- ei_scroll events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Scroll removal notification">
|
|
This object has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="scroll" since="1" context-type="receiver">
|
|
<description summary="Scroll event">
|
|
See the ei_scroll.scroll request for details.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="x" type="float"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="scroll_discrete" since="1" context-type="receiver">
|
|
<description summary="Discrete scroll event">
|
|
See the ei_scroll.scroll_discrete request for details.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="x" type="int32"/>
|
|
<arg name="y" type="int32"/>
|
|
</event>
|
|
|
|
<event name="scroll_stop" since="1" context-type="receiver">
|
|
<description summary="Scroll stop event">
|
|
|
|
See the ei_scroll.scroll_stop request for details.
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than receiver.
|
|
</description>
|
|
<arg name="x" type="uint32"/>
|
|
<arg name="y" type="uint32"/>
|
|
<arg name="is_cancel" type="uint32"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_button" version="1">
|
|
<description summary="button object">
|
|
Interface for button requests and events. This interface
|
|
is available on devices with the ei_device.capability button.
|
|
|
|
This interface is only provided once per device and where a client
|
|
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 releasd.
|
|
|
|
Note that for a client to receive objects of this type, it must announce
|
|
support for this interface in ei_handshake.interface_version.
|
|
</description>
|
|
|
|
<request name="release" since="1">
|
|
<description summary="Button removal request">
|
|
Notification that the client is no longer interested in this object.
|
|
The EIS implementation will release any resources related to this object and
|
|
send the ei_button.destroyed event once complete.
|
|
</description>
|
|
</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>
|
|
|
|
<request name="button" since="1" context-type="sender">
|
|
<description summary="Button state change request">
|
|
Generate a button event on this pointer.
|
|
|
|
The button codes must match the defines in linux/input-event-codes.h.
|
|
|
|
It is a client bug to send more than one button request for the same button
|
|
within the same ei_device.frame.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="button" type="uint32" summary="button code"/>
|
|
<arg name="state" type="uint32" enum="button_state"/>
|
|
</request>
|
|
|
|
<!-- ei_button events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Pointer removal notification">
|
|
This pointer has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This ei_scroll object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="button" since="1" context-type="receiver">
|
|
<description summary="Button state change event">
|
|
See the ei_scroll.button request for details.
|
|
|
|
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"/>
|
|
</event>
|
|
|
|
</interface>
|
|
|
|
<interface name="ei_keyboard" version="1">
|
|
<description summary="keyboard object">
|
|
Interface for keyboard requests and events. This interface
|
|
is available on devices with the ei_device.capability keyboard.
|
|
|
|
This interface is only provided once per device and where a client
|
|
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 releasd.
|
|
|
|
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 -->
|
|
|
|
<request name="release" since="1">
|
|
<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="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>
|
|
|
|
<request name="key" since="1" context-type="sender">
|
|
<description summary="Key state change request">
|
|
Generate a key event on this keyboard. If the device has an
|
|
ei_keyboard.keymap, the key code corresponds to that keymap.
|
|
|
|
The key codes must match the defines in linux/input-event-codes.h.
|
|
|
|
It is a client bug to send more than one key request for the same key
|
|
within the same ei_device.frame.
|
|
|
|
It is a protocol violation to send this request for a client
|
|
of an ei_handshake.context_type other than sender.
|
|
</description>
|
|
<arg name="key" type="uint32" summary="the key code"/>
|
|
<arg name="state" type="uint32" enum="key_state" summary="logical state of the key"/>
|
|
</request>
|
|
|
|
<!-- ei_keyboard events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Keyboard removal notification">
|
|
This keyboard has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This ei_keyboard object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<enum name="keymap_type" since="1">
|
|
<description summary="the keymap type">
|
|
The keymap type describes how the keymap in the ei_keyboard.keymap event
|
|
should be parsed.
|
|
</description>
|
|
<entry name="xkb" value="1" summary="a libxkbcommon-compatible XKB keymap" />
|
|
</enum>
|
|
|
|
<event name="keymap" since="1">
|
|
<description summary="keymap notification">
|
|
Notification that this device has a keymap. Future key events must be
|
|
interpreted by the client according to this keymap. For clients
|
|
of ei_handshake.context_type sender it is the client's
|
|
responsibility to send the correct ei_keyboard.key keycodes to
|
|
generate the expected keysym in the EIS implementation.
|
|
|
|
The keymap is constant for the lifetime of the device.
|
|
|
|
This event provides a file descriptor to the client which 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.
|
|
|
|
This event is optional and only sent immediately after the ei_keyboard object is created
|
|
and before the ei_device.done event. It is a protocol violation to send this
|
|
event after the ei_device.done event.
|
|
</description>
|
|
<arg name="keymap_type" type="uint32" enum="keymap_type" summary="the keymap type"/>
|
|
<arg name="size" type="uint32" summary="the keymap size in bytes"/>
|
|
<arg name="keymap" type="fd" summary="file descriptor to the keymap"/>
|
|
</event>
|
|
|
|
<event name="key" since="1" context-type="receiver">
|
|
<description summary="Key state change event">
|
|
See the ei_keyboard.key request for details.
|
|
|
|
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"/>
|
|
</event>
|
|
|
|
<event name="modifiers" since="1">
|
|
<description summary="Modifier change event">
|
|
Notification that the EIS implementation has changed modifier
|
|
states on this device. Future ei_keyboard.key requests must take the
|
|
new modifier state into account.
|
|
|
|
A client must assume that all modifiers are lifted when it
|
|
receives an ei_device.paused event. The EIS implementation
|
|
must send this event after ei_device.resumed to notify the client
|
|
of any nonzero modifier state.
|
|
|
|
This event does not reqire an ei_device.frame and should
|
|
be processed immediately by the client.
|
|
|
|
This event is only sent for devices with an ei_keyboard.keymap.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
<arg name="depressed" type="uint32" summary="depressed modifiers"/>
|
|
<arg name="locked" type="uint32" summary="locked modifiers"/>
|
|
<arg name="latched" type="uint32" summary="latched modifiers"/>
|
|
<arg name="group" type="uint32" summary="the keyboard group (layout)"/>
|
|
</event>
|
|
</interface>
|
|
|
|
<interface name="ei_touchscreen" version="1">
|
|
<description summary="touchscreen object">
|
|
Interface for touchscreen requests and events. This interface
|
|
is available on devices with the ei_device.capability touchscreen.
|
|
|
|
This interface is only provided once per device and where a client
|
|
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 releasd.
|
|
|
|
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 -->
|
|
|
|
<request name="release" since="1">
|
|
<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" since="1" context-type="sender">
|
|
<description summary="touch down request">
|
|
Notifies the EIS implementation about a new touch logically down at the
|
|
given coordinates. The touchid is a unique id for this touch. Touchids
|
|
may be re-used after ei_touchscreen.up.
|
|
|
|
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"/>
|
|
<arg name="y" type="float" summary="touch y coordinate in logical pixels"/>
|
|
</request>
|
|
|
|
<request name="motion" since="1" context-type="sender">
|
|
<description summary="touch motion request">
|
|
Notifies the EIS implementation about an existing touch changing position to
|
|
the given coordinates. The touchid is the unique id for this touch previously
|
|
sent with ei_touchscreen.down.
|
|
|
|
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"/>
|
|
<arg name="y" type="float" summary="touch y coordinate in logical pixels"/>
|
|
</request>
|
|
|
|
<request name="up" since="1" context-type="sender">
|
|
<description summary="touch up request">
|
|
Notifies the EIS implementation about an existing touch being logically
|
|
up. The touchid is the unique id for this touch previously
|
|
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>
|
|
|
|
<!-- ei_touchscreen events version 1 -->
|
|
|
|
<event name="destroyed" type="destructor" since="1">
|
|
<description summary="Touchscreen removal notification">
|
|
This touch has been removed and a client should release all
|
|
associated resources.
|
|
|
|
This ei_touchscreen object will be destroyed by the EIS implementation immmediately after
|
|
after this event is sent and as such the client must not attempt to use
|
|
it after that point.
|
|
</description>
|
|
<arg name="serial" type="uint32" summary="this event's serial number"/>
|
|
</event>
|
|
|
|
<event name="down" since="1" context-type="receiver">
|
|
<description summary="touch down request">
|
|
See the ei_touchscreen.down request for details.
|
|
|
|
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"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="motion" since="1" context-type="receiver">
|
|
<description summary="touch motion request">
|
|
See the ei_touchscreen.motion request for details.
|
|
|
|
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"/>
|
|
<arg name="y" type="float"/>
|
|
</event>
|
|
|
|
<event name="up" since="1" context-type="receiver">
|
|
<description summary="touch motion request">
|
|
See the ei_touchscreen.up request for details.
|
|
|
|
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>
|
|
</interface>
|
|
</protocol>
|