From ebefdf903ceaefbc2ffc90a101c49fc8a0ab549a Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 6 Feb 2023 11:14:22 +1000 Subject: [PATCH] protocol: document the protocol better --- proto/protocol.xml | 146 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 113 insertions(+), 33 deletions(-) diff --git a/proto/protocol.xml b/proto/protocol.xml index 5fd38aa..61a515f 100644 --- a/proto/protocol.xml +++ b/proto/protocol.xml @@ -94,6 +94,13 @@ + + 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. + @@ -132,6 +139,13 @@ 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. @@ -140,28 +154,29 @@ - The highest supported version of this interface - by the EIS implementation. Any requests - send by the client must be provided in this version + The highest supported version of the ei_connection_setup + interface as supported by the EIS implementation. Any requests + sent by the client must be provided in this version or any lower version. This event is sent immediately after connection. 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 until the client announces - a higher version of this interface in the + 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 request. - + Provides the client with the connection object that is the top-level object for all future requests and events. - This event is sent immediately after the client sends the + + 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 @@ -180,8 +195,8 @@ - The core global object. This is a special singleton object. It - is used for internal ei protocol features. + The core connection object. This is the top-level object for any communication + with the EIS implementation. @@ -204,7 +219,13 @@ summary="callback object for the sync 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. + > @@ -215,13 +236,14 @@ - + This event may be sent by the EIS implementation immediately before the client is disconnected. - Where a client is disconnected by EIS directly, the reason is - disconnect_reason.disconnected and the explanation is NULL. + Where a client is disconnected 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 @@ -264,28 +286,57 @@ + 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. - + 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. + 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. - + @@ -307,7 +358,7 @@ A bitmask of the capabilities of this seat. - + @@ -339,14 +390,14 @@ - + - + - + @@ -430,17 +481,17 @@ - + - + - + - + @@ -541,7 +592,7 @@ - + Notification that the client is no longer interested in this keyboard. The EIS implementation will release any resources related to this keyboard and @@ -593,7 +644,7 @@ - + Notification that the client is no longer interested in this touch. The EIS implementation will release any resources related to this touch and @@ -601,19 +652,36 @@ - + + + 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. + - + + + 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. + - + + + 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. + @@ -624,19 +692,31 @@ - + + + See the ei_touchscreen.down request for details. This event is + for ei receiver contexts. + - + + + See the ei_touchscreen.motion request for details. This event is + for ei receiver contexts. + - + + + See the ei_touchscreen.up request for details. This event is + for ei receiver contexts. +