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. This is a special interface to setup the client as seen by the EIS implementation. The object for this interface has the fixed object id 0 and only exists until the connection has been set up, see the ei_connection_setup.connection event. Once the ei_connection.connection event has been sent the connection setup is destroyed by the EIS implementation. Notify the EIS implementation that configuration is complete. In the future, the EIS implementation responds by sending the ei_connection_setup.connection event. 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. Notify the EIS implementation of the type of this context. This request is optional, the default client type is context_type.receiver. This request must not be sent more than once and must be sent before ei_connection_setup.done. Notify the EIS implementation of the client name. The name is a human-presentable UTF-8 string. There is no requirement for the EIS implementation to use this name. This request is optional, the default client name is implementation-defined. This request must not be sent more than once and must be sent before ei_connection_setup.done. Notify the EIS implementation that the client supports the given named interface with the given maximum version number. In the future, objects created by the EIS implementation will use the respective interface version (or any lesser version). This request must be sent for the ei_connection interface, failing to do so will result in the EIS implementation disconnecting the client on ei_connection_setup.done. If the ei_connection_setup version is given, the interface of this object is upgraded to the given version. Otherwise, the ei_connection_setup version defaults to 1. A client must not provide a ei_connection_setup version higher than ei_connection_setup.version. This request must not be sent more than once per interface and must be sent before ei_connection_setup.done. Notifies the client that the EIS implementation supports the given named interface with the given maximum version number. This event is sent immediately after connection to the EIS implementation for the "ei_connection_setup" interface. Any requests for this interface sent by the client must be provided in the version provided or any lower version. A client should not issue any requests until processing this version. Note that the EIS implementation assumes that the supported client version of this interface is 1 unless and until the client announces a higher version of this interface in the ei_connection_setup.interface_version request. This event may be sent by the EIS implementation for any other supported interface (but not necessarily all supported interfaces) before the ei_connection_setup.connection event. Provides the client with the connection object that is the top-level object for all future requests and events. This event is sent at some unspecified time after the client sends the ei_connection_setup.done request to the EIS implementation. The ei_connection_setup object will be destroyed by the EIS implementation immediately after this event has been sent, a client must not attempt to use it after that point. The version sent by the server is the version of the ei_connection interface as announced by ei_connection_setup.interface, or any lower version. The core connection object. This is the top-level object for any communication with the EIS implementation. Note that for a client to receive objects of this type, it must announce support for this interface in ei_connection_setup.interface. 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 passed in the callback is always zero. Note that for a client to use this request it must announce support for this interface in ei_connection_setup.interface. It is a protocol violation to request sync without having announced the "ei_callback" interface and the EIS implementation must disconnect the client. 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. > 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. This event may be sent by the EIS implementation immediately before the client is disconnected. Where a client is disconnected by EIS on purpose, for example after a user interaction, the reason is disconnect_reason.disconnected and the explanation is NULL. Where a client is disconnected due to some invalid request or other protocol error, the reason is disconnect_reason.error and explanation may contain a string explaining why. This string is intended to help debugging only and is not guaranteed to stay constant. 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. 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_connection_setup.interface. The interface version is equal or less to the client-supported version in ei_connection_setup.interface for the "ei_seat" interface. Notification that an object ID used in a prior 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 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 server to use this request the client must announce support for this interface in ei_connection_setup.interface. It is a protocol violation to send this event to a client without the "ei_callback" interface. 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_connection_setup.interface. 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. This event may only be sent on an ei_callback object that was created by the client. 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_connection_setup.interface. Notify the server when the related event is done. Immediately after this event the ei_callback object is destroyed by the client and as such must not be used any further. This request may only be called on an ei_callback object that was created by the EIS implementation. 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_connection_setup.interface. 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. A set of capabilities possible available on this seat. A client may bind to these capabilies and an EIS implementation may then create device based on the bound capabilities. 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. Binding capabilities that are not supported in the ei_seat'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. 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. 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. A bitmask of the capabilities of this seat. It is a protocol violation to send this event after the ei_seat.done event. 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. 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_connection_setup.interface. The interface version is equal or less to the client-supported version in ei_connection_setup.interface for the "ei_device" interface. Note that for a client to receive objects of this type, it must announce support for this interface in ei_connection_setup.interface. 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. 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 synergy-like use-case the client would call ei_device.start_emulating once the pointer moves into the the screen and ei_device.stop_emulating once the pointer moves out of the screen. 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 reasonably. It is a protocol violation to request start_emulating after start_emulating without an intermediate stop_emulating. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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_connection_setup.context_type other than sender. Generate a frame event to group the current set of events into a logical hardware event. This function must be called after any other event on any of ei_pointer, ei_keyboard or ei_touchscreen has been generated. 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_connection_setup.context_type other than sender. 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. 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. A bitmask of the capabilties of this device. 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. If the device type is 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 size. If the device type is 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. The device type, one of virtual or physical. 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. The device dimensions in mm. 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. 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 first screen, the second with a nonzero offset spanning the second 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. 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. Notification that a new device has a pointer interface. This event is only sent if the client announced support for the "ei_pointer" interface in ei_connection_setup.interface. The interface version is equal or less to the client-supported version in ei_connection_setup.interface 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. Notification that a new device has a keyboard interface. This event is only sent if the client announced support for the "ei_keyboard" interface in ei_connection_setup.interface. The interface version is equal or less to the client-supported version in ei_connection_setup.interface 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. Notification that a new device has a keyboard interface. This event is only sent if the client announced support for the "ei_touchscreen" interface in ei_connection_setup.interface. The interface version is equal or less to the client-supported version in ei_connection_setup.interface 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. 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. See the ei_device.start_emulating request for details. It is a protocol violation to send this event for a client of an ei_connection_setup.context_type other than receiver. > See the ei_device.stop_emulating request for details. It is a protocol violation to send this event for a client of an ei_connection_setup.context_type other than receiver. See the ei_device.frame request for details. It is a protocol violation to send this event for a client of an ei_connection_setup.context_type other than receiver. Interface for pointer and absolute pointer requests and events. This interface is available on devices with the ei_device.capability pointer or pointer_absolute. Note that for a client to receive objects of this type, it must announce support for this interface in ei_connection_setup.interface. 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. Generate a relative motion event on this pointer. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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 protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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 protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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 protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. Generate a a scroll stop or cancel event on this pointer. A scroll stop event notifies the server 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 server 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 protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. Generate a button event on this pointer. The button codes must match the defines in linux/input-event-codes.h. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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. See the ei_pointer.motion_relative request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_pointer.motion_absolute request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_pointer.scroll request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_pointer.scroll_discrete request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_pointer.scroll_stop request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_pointer.button request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. Interface for keyboard requests and events. This interface is available on devices with the ei_device.capability keyboard. Note that for a client to receive objects of this type, it must announce support for this interface in ei_connection_setup.interface. 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. Notification that this device has a keymap. The keymap is constant for the lifetime of the device. Key events on this device correspond to the given keymap. 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. Generate a key event on this keyboard. The key codes must match the defines in linux/input-event-codes.h. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than sender. 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. See the ei_keyboard.key request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. 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. Interface for touchscreen requests and events. This interface is available on devices with the ei_device.capability touchscreen. Note that for a client to receive objects of this type, it must announce support for this interface in ei_connection_setup.interface. 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. 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. 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. 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. 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. See the ei_touchscreen.down request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_touchscreen.motion request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver. See the ei_touchscreen.up request for details. It is a protocol violation to send this request for a client of an ei_connection_setup.context_type other than receiver.