diff --git a/proto/protocol.xml b/proto/protocol.xml index 9679716..a65e954 100644 --- a/proto/protocol.xml +++ b/proto/protocol.xml @@ -31,12 +31,13 @@ - Protocol wire format: [sender-id, length, opcode, ...] + 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. @@ -54,9 +55,10 @@ - 'float': a 32-bit IEEE-754 float - 'fd': a file descriptor. Zero bytes in the message itself, transmitted in the overhead - - 'string': a length-prefix zero-terminated string. Encoded as - one 32-bit unsigned integer for the length followed by the string. - The string is padded to the nearest 4-byte units, for example the string + - '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'] @@ -66,9 +68,16 @@ 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 server. + 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 @@ -87,26 +96,39 @@ 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 - Initial Connection: - 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 .finish request. The server 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. + 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. - Version negotiation for interfaces is also handled in the ei_handshake - object. The client announces which interfaces are supported and their - respective version, future server-created objects will use that version or any - lower version. + 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 @@ -309,7 +331,7 @@ 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" + 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. @@ -476,8 +498,8 @@ 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_handshake.interface. It is + Note that for a EIS implementation to use this request the client must + announce support for this interface in ei_handshake.interface. It is a protocol violation to send this event to a client without the "ei_pingpong" interface. @@ -523,7 +545,7 @@ - Notify the server when the related event is done. Immediately after this request + 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. @@ -738,7 +760,7 @@ 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 server. + 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 @@ -1128,11 +1150,11 @@ Generate a a scroll stop or cancel event on this pointer. - A scroll stop event notifies the server that the interaction causing a + 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 server may use this information to e.g. start kinetic scrolling + 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 @@ -1155,6 +1177,9 @@ + + The logical state of a button. + @@ -1251,6 +1276,9 @@ 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. @@ -1283,6 +1311,9 @@ + + The logical state of a key. + @@ -1356,6 +1387,9 @@ 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. @@ -1417,6 +1451,9 @@ 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. @@ -1431,6 +1468,9 @@ 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. @@ -1444,6 +1484,9 @@ 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. @@ -1468,6 +1511,9 @@ 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. @@ -1480,6 +1526,9 @@ 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. @@ -1492,6 +1541,9 @@ 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.