The protocol is designed to connect two processes over a UNIX socket - an ei client and an EIS implementation (typically a Wayland compositor).
flowchart LR; subgraph EIS implementation socket[[ei.socket]] end c1[ei client 1] -- ei protocol --> socket c2[ei client 2] -- ei protocol --> socket
The protocol is asynchronous and object-oriented. Each object on the wire supports zero or more requests and zero or more events. Requests are messages sent from an ei client to an EIS implementation, events are messages sent from the EIS implementation to the client.
flowchart LR; ei -- request --> eis eis -- event --> ei
Objects are identified by a unique object ID, assigned at creation of the object.
The type of an object is defined by its interface
and agreed on at object creation. Each object has exactly one interface, but
there may be multiple objects with that interface. For example, a compositor
may create multiple objects with the
All data on the protocol (e.g. object IDs) is private to that client’s connection.
The ei protocol is modelled closely after the Wayland protocol, but it is not binary compatible.
The wire format consists of a 3-element header comprising the
the object, the length of the message and the opcode representing the message
byte: |0 |4 |8 |12 |16 content: |object-id |length |opcode |...
object-idis one 64-bit unsigned integer that uniquely identifies the object sending the request/event. The
object-id0 is reserved for the special
lengthis a 32-bit integer that specifies the length of the message in bytes, including the 16 header bytes for
opcodeis a 32-bit integer that specifies 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.
The header is followed by the message-specific arguments (if any). All arguments are 4 bytes or padded to a multiple of 4 bytes.
All integers are in the EIS implementation’s native byte order.
For objects to be created, the EIS implementation and the client must agree on a supported
version for each object. This agreement happens during the initial setup in
- the client notifies the EIS implementation of the highest supported version for an interface,
e.g. in the
- the EIS implementation responds by selecting the highest version the EIS
implementation supports but not higher than the client version. It may notify the
client of that version before
An exception to this is the
ei_handshake.handshake_version request and event where the
EIS implementation initializes the version exchange and thus the client picks the version number.
In both cases, the version number used is simply
v = min(eis_version, client_version).
Whenever an object is created, the version number of that object must be sent in the corresponding request or event.