diff --git a/proto/protocol.xml b/proto/protocol.xml index 2220121..b3d3af2 100644 --- a/proto/protocol.xml +++ b/proto/protocol.xml @@ -52,12 +52,11 @@ - - 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. + + Informs 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 @@ -71,7 +70,7 @@ - Notify the EIS implementation that configuration is complete. + Informs 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. @@ -83,15 +82,15 @@ Context types for connections. The context type for a connection is set once in the ei_handshake.context_type request. - - + + - - Notify the EIS implementation of the type of this context. The context - type defines whether the client will send input events to the server or - receive input events from it. + + Informs the EIS implementation of the type of this context. The context + type defines whether the EI client will send input events to the EIS + implementation or receive input events from it. Depending on the context type, certain requests must not be used and some events must not be sent by the EIS implementation. @@ -104,11 +103,11 @@ - - 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 + + Informs 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 @@ -124,9 +123,9 @@ - - Notify the EIS implementation that the client supports the - given named interface with the given maximum version number. + + Informs the EIS implementation that the EI 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) @@ -152,9 +151,12 @@ - - This event is sent exactly once and immediately after connection - to the EIS implementation. + + Informs the client that the EIS implementation supports the given + version of the ei_handshake interface. + + 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. @@ -165,8 +167,8 @@ - Notifies the client that the EIS implementation supports - the given named interface with the given maximum version number. + Informs the client that the EIS implementation supports the given named + interface with the given maximum version number. The client must not assume those interfaces are supported unless and until those versions have been received. @@ -183,18 +185,18 @@ - + 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. + This event must be sent exactly once 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 ei_handshake object will be destroyed by the EIS implementation + immediately after this event has been sent, the client must not attempt + to use it after that point. - The version sent by the EIS implementation is the version of the "ei_connection" + 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. @@ -223,22 +225,22 @@ - 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. + Requests the EIS implementation to emit the ei_callback.done event on + the returned ei_callback object. Since requests are handled in-order + and events are delivered in-order, this can be used as a + synchronization point to ensure all previous requests and the resulting + events have been handled. The object returned by this request will be destroyed by the EIS implementation after the callback is fired and as such the client must not attempt to use it after that point. - The callback_data in the ei_callback.done event is always zero. + The callback_data in the ei_callback.done event must be zero. Note that for a client to use this request it must announce - support for the "ei_callback" interface in ei_handshake.interface_version. + 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 + `ei_callback` interface and the EIS implementation must disconnect the client. 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 an event by the server. + serial number used in an event by the EIS implementation. Where a client is disconnected by EIS on purpose, for example after a user interaction, the reason is disconnect_reason.disconnected (i.e. zero) @@ -311,8 +313,8 @@ - - Notification that a new seat has been added. + + Informs the client that a new seat has been added. A seat is a set of input devices that logically belong together. @@ -328,7 +330,7 @@ - Notification that an object ID used in an earlier request was + Informs the client 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 @@ -378,18 +380,16 @@ 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. - 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. + Informs the client that the associated request is finished. The EIS + implementation must destroy the ei_callback object immediately after + sending this event this event and as such the client must not attempt to + use it after that point. @@ -400,18 +400,16 @@ 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. - 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. + Informs the EIS implementation when the associated event is finished. + The client must destroy the ei_pingpong object immediately after this + request and as such the server must not attempt to use it after that + point. @@ -432,37 +430,39 @@ 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. - 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. + Informs the EIS implementation that the client is no longer interested + in this seat. The EIS implementation should release any resources + associated with this seat and send the ei_seat.destroyed event once + finished. - 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. + Note that releasing a seat does not guarantee that another seat becomes + available. In other words, in most single-seat cases, releasing the seat + means that the connection becomes effectively inert. - Bind to the bitmask of capabilities given. The bitmask is zero or more of the - masks representing an interface as provided in the ei_seat.capability event. - See the ei_seat.capability event documentation for examples. + Binds to the given bitmask of capabilities. Each one of the bit values + in the given bitmask must originate from one of the ei_seat.capability + events. See its documentation for more examples. - Binding masks that are not supported in the ei_device's interface version - is a client bug and may result in disconnection. + The EIS implementation should return compatible devices with + ei_seat.device events. - A client may send this request multiple times to adjust the capabilities it - is interested in. If previously-bound capabilities are dropped by the client, - the EIS implementation may ei_device.remove devices that have these capabilities. + Binding masks that are not supported in the ei_device's interface + version is a client bug and may result in disconnection. + + A client may send this request multiple times to adjust the capabilities + it is interested in. If previously-bound capabilities are dropped by the + client, the EIS implementation may ei_device.remove devices that have + these capabilities. @@ -471,8 +471,8 @@ - This seat has been removed and a client should release all - associated resources. + Informs the client that this seat has been removed, and that it should + release all associated resources. This ei_seat object will be destroyed by the EIS implementation immediately after after this event is sent and as such the client must not attempt to use @@ -493,33 +493,27 @@ - A notification that this seat supports devices with the given interface. - The interface is mapped to a bitmask by the EIS implementation. - A client may then binary OR these bitmasks in ei_seat.bind. - In response, the EIS implementation may then create device based on those - bound capabilities. + Informs the client that this seat supports devices with the given + interface. The interface must be mapped to a bitmask by the EIS + implementation. The client may apply the binary OR operation onto these + bitmasks in ei_seat.bind. In response, the EIS implementation may then + create devices based on those bound capabilities. - For example, an EIS implementation may map "ei_pointer" to 0x1, - "ei_keyboard" to 0x4 and "ei_touchscreen" to 0x8. A client may then - ei_seat.bind(0xc) to bind to keyboard and touchscreen but not pointer. - Note that as shown in this example the set of masks may be sparse. - The value of the mask is constant for the lifetime of the seat but may differ - between seats. + For example, an EIS implementation may advertise support for + `ei_pointer` devices at bitmask `0x1`, `ei_keyboard` devices at `0x4` + and `ei_touchscreen` devices at `0x8`. A client may then execute the + request `ei_seat.bind(0xC)` to bind to keyboard and touchscreen devices + but not pointing devices. - 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. + The EIS implementation must not advertise capabilities for interfaces + that have not been negotiated in the ei_handshake object. - Only interfaces that the client announced during ei_handshake.interface_version - can be a seat capability. + The EIS implementation may decide which capabilities a given seat has. + After ei_seat.done, the capabilities are constant for the lifetime of + the seat but may differ between seats. The masks may be sparse bitwise. - This event is sent multiple times - once per supported interface. - The set of capabilities is constant for the lifetime of the seat. - - It is a protocol violation to send this event after the ei_seat.done event. + This event is sent multiple time for each supported interface, finishing + with ei_seat.done. @@ -536,13 +530,14 @@ - Notification that a new device has been added. + Informs the client that a new device has been added to the seat. + + The EIS implementation must never announce devices that have not been bound to with ei_seat.bind. 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. + `ei_device` interface in ei_handshake.interface_version. The interface + version is less than or equal to the client-supported version in + ei_handshake.interface_version for the `ei_device` interface. @@ -560,9 +555,6 @@ 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. @@ -894,16 +886,12 @@ - Interface for relative pointer motion requests and events, originating - from physical devices like computer mice. + Interface for relative pointer motion requests and events. 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 released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version. @@ -965,9 +953,6 @@ requests ei_pointer_absolute.release the interface does not get re-initialized. An EIS implementation may adjust the behavior of the device (including removing the device) if the interface is released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version. @@ -1031,9 +1016,6 @@ requests ei_scroll.release the interface does not get re-initialized. An EIS implementation may adjust the behavior of the device (including removing the device) if the interface is released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version. @@ -1175,9 +1157,6 @@ requests ei_button.release the interface does not get re-initialized. An EIS implementation may adjust the behavior of the device (including removing the device) if the interface is released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version. @@ -1253,9 +1232,6 @@ 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 released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version. @@ -1326,7 +1302,7 @@ The keymap is constant for the lifetime of the device. - This event provides a file descriptor to the client which can be + This event provides a file descriptor to the client that 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. @@ -1371,10 +1347,10 @@ For receiver clients, modifiers events will always be properly ordered with received key events, so each key event should be interpreted using - the most recently-received modifier state. The server should send this - event immediately following the ei_device.frame event for the key press - that caused the change. If the state change impacts multiple keyboards, - this event should be sent for all of them. + the most recently-received modifier state. The EIS implementation should + send this event immediately following the ei_device.frame event for the + key press that caused the change. If the state change impacts multiple + keyboards, this event should be sent for all of them. For sender clients, the modifiers event is not inherently synchronized with key requests, but the client may send an ei_connection.sync request @@ -1397,10 +1373,10 @@ This event is only sent for devices with an ei_keyboard.keymap. Note: A previous version of the documentation instead specified that - this event should not be sent in response to ei_keyboard.key events - that change the group or modifier state according to the keymap. - However, this complicated client implementation and resulted in - situations where the client state could get out of sync with the server. + this event should not be sent in response to ei_keyboard.key events that + change the group or modifier state according to the keymap. However, + this complicated client implementation and resulted in situations where + the client state could get out of sync with the EIS implementation. @@ -1418,9 +1394,6 @@ 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 released. - - Note that for a client to receive objects of this type, it must announce - support for this interface in ei_handshake.interface_version.