fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2025-12-26 01:40:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
libei/proto/protocol.xml

1590 lines
72 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ei">
<copyright>
Copyright © 2008-2011 Kristian Høgsberg
Copyright © 2010-2011 Intel Corporation
Copyright © 2012-2013 Collabora, Ltd.
Copyright © 2023 Red Hat, Inc.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice (including the
next paragraph) shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
</copyright>
<documentation>
<chapter title="Protocol overview">
The ei protocol has three components: objects, requests and events. It is
designed to be connect two processes over a UNIX socket - an ei client and
an EIS implementation (typically a Wayland compositor). The protocol
is asynchronous and object-based.
Whenever a message (request or event) is sent, that message carries an
identifier for the object. The type of an object is defined by its interface -
the interfaces are detailed here in this protocol. Thus, when a message for an
object arrives, the client or EIS implementation can invoke the corresponding
function on the object.
An object has exactly one interface but there may be multiple objects with
the same interface (e.g. multiple devices all use the ei_device interface).
Requests are messages sent from an ei client to an EIS implementation, events
are messages sent from the EIS implementation to the client. This is the same
nomenclature that the Wayland protocol uses.
The ei protocol is modelled closely after the Wayland protocol, but it is not
binary compatible.
</chapter>
<chapter title="Wire format">
Protocol wire format: `[sender-id, length, opcode, ...]`
Where:
- sender-id is one 64-bit integer
- length and opcode are 32-bit integers
- all integers are in the EIS implementation's native byte order.
- length is the length of the message in bytes, including the 16 header bytes
for sender-id, length and opcode.
- sender-id is the id of the object sending the request/event. The sender-id
0 is reserved for the special "ei_handshake" object.
- opcode is the event or request-specific opcode, starting at 0.
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.
</chapter>
<chapter title="Protocol types">
Types:
- 'uint32': a 32-bit unsigned integer
- 'int32': a 32-bit signed integer
- 'uint64': a 64-bit unsigned integer
- 'int64': a 64-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-prefixed zero-terminated string. Encoded as
one 32-bit unsigned integer for the length followed by the string
itself.
The string is padded to the nearest multiple of 4-byte, for example the string
"hello" is of length 6 but is zero-padded to 8 bytes and with the 4-byte
length field thus takes 12 bytes in total. Full (le) encoding:
[0x06, 0x00, 0x00, 0x00, 'h', 'e', 'l', 'l', 'o', '\0', '\0\, '\0']
- 'new_id': an object id allocated by the caller. Client-allocated IDs begin
at 1 and must be less than 0xff00000000000000.
IDs allocated by the EIS implementation start at and must not be less
than 0xff00000000000000.
- 'object_id': a previously allocated object id
All integers are in the EIS implementation's native byte order.
Object IDs:
Object IDs are unique, monotonically increasing and must not be re-used by the
client or the EIS implementation.
Interface names:
Interface names on the wire are always in the form "ei_foo". See e.g.
the ei_handshake.interface_version request and event where interface
names are used.
Serial numbers:
Some events have serial numbers assiged by the EIS implementation. A serial is
a monotonically increasing unsigned 32-bit number (that wraps, clients must handle
this). Clients must use the most recently seen EIS serial number in requests that have
a last_serial argument.
The serial number aims to help a client track failure cases and the EIS
implementation to detect errors caused by the protocol's asynchronicity.
For example, if the EIS implementation removes a device at the serial number N,
client-initiated events for N-1 are caused by the client lagging behind and are not
a protocol violation.
</chapter>
<chapter title="Protocol XML description">
Protocol XML:
- a request or event marked as type="destructor" causes the object to be
destroyed immediately after that message has been sent.
- an argument with an "enum" attribute carries a value of the corresponding enum
- an argument with an "interface" attribute indicates that an object in the same message is
of that interface type
- an enum labelled "bitfield" indicates a single-bit value.
- a "protocol violation" must result in the EIS implementation disconnecting
the client with an error or (if appropriate) the client immediately disconnecting
from the EIS implementation.
- each request, event or enum has a "since" tag to indicate the interface version this element was
introduced in
- each interface has a "version" tag to indicate the current version of this interface
</chapter>
<chapter title="Initial Connection Handshake">
The initial connection is a two-step process:
An ei_handshake object with the special ID 0 is guaranteed to
exists. The client must send the appropriate requests to set up
its connection, followed by the ei_handshake.finish request. The EIS
implementation replies by creating the ei_connection object with the
client-requested version (or any lower version) that is the connection for the
remainder of this client.
Immediately after connecting, the EIS implementation must send the
ei_handshake.handshake_version event. The client replies with the
ei_handshake.handshake_version request to negotiate the version
of the ei_handshake object.
Version negotiation for other interfaces is also handled in the ei_handshake
object. The client announces which interfaces it supports and their
respective version, the EIS implementation should subsequently notify
the client about the interface version it supports.
Any object created by either the client or the EIS implementation must
use the lower of client and EIS implementation supported version.
In summary, a typical client connection does:
- connect to the socket
- read ei_handshake.handshake_version for object id 0
- send ei_handshake.handshake_version for object id 0
- send ei_handshake.interface_version for all other supported interfaces
- optionally: send ei_handshake.name and ei_handshake.context_type
- send ei_handshake.finish
- send ei_handshake.finish
- optionally: receive ei_handshake.interface_version for named interfaces
- receive the ei_connection.connection event and create that object
- receive ei_connection.seat (if any seats are available)
- ....
- receive ei_connection.disconnect and close the socket
As of version 1 for most interfaces, the typical object tree looks like this:
- ei_handshake (destroyed after .connection)
- ei_connection
- ei_seat
- ei_device
- ei_pointer
- ei_keyboard
- ei_device
- ei_touchscreen
- ei_device
- ei_seat
- ei_device
- ei_callback (destroyed after .done)
- ei_callback (destroyed after .done)
</chapter>
</documentation>
<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.
<!-- 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.
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"/>
</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" 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.
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="uint32" 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="uint32" 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
capabilities provided in the ei_seat.capabilities event. That event's capabilities
are used as a mask of capabilities that can be bound.
Note that available seat capabilities are defined in the ei_device
interface and not dependent on the seat interface version. In other
words, ei_seat.bind supports any capability available in the
client-announced ei_device interface version.
Binding capabilities 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 capabilities are dropped, the EIS implementation may
ei_device.remove devices that have these capabilities.
</description>
<arg name="capabilities" type="uint32" enum="ei_device.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="capabilities" since="1">
<description summary="Seat capability notification">
A bitmask of the capabilities of this seat. A client may ei_seat.bind to these
capabilies and an EIS implementation may then create device based on the bound
capabilities.
Note that available seat capabilities are defined in the ei_device
interface and not dependent on the seat interface version. In other
words, ei_seat.bind supports any capability available in the
client-announced ei_device interface version.
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.
Capabilities are only advertised once and are 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="capabilities" type="uint32" enum="ei_device.capabilities" summary="the seat capabilities"/>
</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="1">
<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">
<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">
<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">
<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_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="capabilities" since="1" bitfield="true">
<description summary="Device capabilities">
A set of capabilities available on this device.
</description>
<entry name="pointer" value="1" summary="the relative pointer capability"/>
<entry name="pointer_absolute" value="2" summary="the absolute pointer capability"/>
<entry name="keyboard" value="4" summary="the keyboard capability"/>
<entry name="touchscreen" value="8" summary="the touchscreen capability"/>
</enum>
<event name="capabilities" since="1">
<description summary="device capability notification">
A bitmask of the capabilities of this device. This mask is a subset of the
ei_seat.capabilities announced for the seat for this device.
Capabilities are only advertised once and are constant for the lifetime of the device.
For clients of ei_handshake.context_type.sender, the capabilities limit
the type of emulated input events a client can request. For example, a device
without the keyboard capability cannot emulate keyboard events.
For clients of ei_handshake.context_type.receiver, the capabilities limit
the type of emulated input events a client may receive from the EIS implementation.
For example, a device without the keyboard capability will ever generate keyboard events.
This event must be 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="capabilities" type="uint32" enum="capabilities" 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.
</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"/>
<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="pointer" since="1">
<description summary="device pointer interface notification">
Notification that a new device has a pointer interface.
This event is only sent if the device has the
ei_device.capabilities.pointer or
ei_device.capabilities.pointer_absolute capability.
This event is only sent if the client announced support for the
"ei_pointer" 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_pointer"
interface.
This event is optional and sent immediately after object creation.
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="pointer" type="new_id" interface="ei_pointer"/>
<arg name="version" type="uint32" summary="the interface version"/>
</event>
<event name="keyboard" since="1">
<description summary="device pointer interface notification">
Notification that a new device has a keyboard interface.
This event is only sent if the device has the
ei_device.capabilities.keyboard.
This event is only sent if the client announced support for the
"ei_keyboard" 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_keyboard"
interface.
This event is optional and sent immediately after object creation.
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="keyboard" type="new_id" interface="ei_keyboard"/>
<arg name="version" type="uint32" summary="the interface version"/>
</event>
<event name="touchscreen" since="1">
<description summary="device touchscreen interface notification">
Notification that a new device has a touchscreen interface.
This event is only sent if the device has the
ei_device.capabilities.touchscreen.
This event is only sent if the client announced support for the
"ei_touchscreen" 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_touchscreen"
interface.
This event is optional and sent immediately after object creation.
It is a protocol violation to send this event after the ei_device.done event.
</description>
<arg name="touchscreen" type="new_id" interface="ei_touchscreen"/>
<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">
<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">
<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">
<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>
</interface>
<interface name="ei_pointer" version="1">
<description summary="pointer object">
Interface for pointer and absolute pointer requests and events. This interface
is available on devices with the ei_device.capability pointer or pointer_absolute.
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">
<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>
<request name="motion_absolute" since="1">
<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>
<request name="scroll" since="1">
<description summary="Scroll request">
Generate a a smooth (pixel-precise) scroll event on this pointer.
Clients must not send ei_pointer.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">
<description summary="Scroll discrete request">
Generate a a discrete (e.g. wheel) scroll event on this pointer.
Clients must not send ei_pointer.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 multiple of 120"/>
<arg name="y" type="int32" summary="the y movement in fractions or multiple of 120"/>
</request>
<request name="scroll_stop" since="1">
<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_pointer.scroll or
ei_pointer.scroll_discrete has stopped. For example, if all
fingers are lifted off a touchpad, two-finger scrolling has logically
stopped. The 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_pointer.scroll or ei_pointer.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>
<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">
<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_pointer 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_pointer 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">
<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>
<event name="motion_absolute" since="1">
<description summary="Absolute motion event">
See the ei_pointer.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>
<event name="scroll" since="1">
<description summary="Scroll event">
See the ei_pointer.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">
<description summary="Discrete scroll event">
See the ei_pointer.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">
<description summary="Scroll stop event">
See the ei_pointer.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>
<event name="button" since="1">
<description summary="Button state change event">
See the ei_pointer.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">
<description summary="Key state change request">
Generate a key event on this keyboard. If the device has an
ei_device.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 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">
<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_device.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">
<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">
<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">
<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">
<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">
<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">
<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>
Reference in a new issue View git blame Copy permalink