ei_handshake

Handshake Object

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_handshake.connection event.

The ei_handshake version is 1 until:

  • the EIS implementation sends the interface_version event with a version other than 1, and, in response,
  • the client sends the interface_version request with a version equal or lower to the EIS implementation version.

The EIS implementation must send the interface_version event immediately once the physical connection has been established.

Once the ei_connection.connection event has been sent the handshake is destroyed by the EIS implementation.

Enums

Info

Enum names are shown here in uppercase. The exact name depends on the language bindings.

ei_handshake.context_type

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.

Name Value Summary
RECEIVER 1 this client receives events from the EIS implementation
SENDER 2 this client sends events to the EIS implementation

Requests

ei_handshake.handshake_version

Since Version1 Request Opcode0

ei_handshake.handshake_version(version)
Argument Type Summary
version uint32 the interface version

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.

Immediately after sending this request, the client must assume the negotiated version number for the ei_handshake interface and the EIS implementation may send events and process requests matching that version.

This request must be sent exactly once and it must be the first request the client sends.

ei_handshake.finish

Since Version1 Request Opcode1

ei_handshake.finish()

Notify 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.

ei_handshake.context_type

Since Version1 Request Opcode2

ei_handshake.context_type(context_type)
Argument Type Summary
context_type uint32 the client context type

Notify the EIS implementation of the type of this context. The context types defines whether the client will send events to or receive events from the EIS implementation.

Depending on the context type, certain requests must not be used and some events must not be sent by the EIS implementation.

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_handshake.finish.

ei_handshake.name

Since Version1 Request Opcode3

ei_handshake.name(name)
Argument Type Summary
name string the client name

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 permissions to connect).

There is no requirement for the EIS implementation to use this name. For example, where the client is managed through an XDG Desktop Portal an EIS implementation would typically use client identification information sent by the portal instead.

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_handshake.finish.

ei_handshake.interface_version

Since Version1 Request Opcode4

ei_handshake.interface_version(name, version)
Argument Type Summary
name string the interface name
version uint32 the interface version

Notify the EIS implementation that the 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).

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_handshake.finish.

This request must not be sent for the “ei_handshake” interface, use the ei_handshake.handshake_version request instead.

Note that an EIS implementation may consider some interfaces to be required and immediately ei_connection.disconnect a client not supporting those interfaces.

This request must not be sent more than once per interface and must be sent before ei_handshake.finish.

Events

ei_handshake.handshake_version

Since Version1 Event Opcode0

ei_handshake.handshake_version(version)
Argument Type Summary
version uint32 the interface version

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. See the ei_handshake.handshake_version request for details on what happens next.

ei_handshake.interface_version

Since Version1 Event Opcode1

ei_handshake.interface_version(name, version)
Argument Type Summary
name string the interface name
version uint32 the interface version

Notifies the client that the EIS implementation supports the given named interface with the given maximum version number.

This event must be sent by the EIS implementation for any interfaces that supports client-created objects (e.g. “ei_callback”) before the ei_handshake.connection event. The client must not assume those interfaces are supported unless and until those versions have been received.

This request must not be sent for the “ei_handshake” interface, use the handshake_version event instead.

This event may be sent by the EIS implementation for any other supported interface (but not necessarily all supported interfaces) before the ei_handshake.connection event.

ei_handshake.connection

Since Version1 Event Opcode2

ei_handshake.connection(serial, connection, version)
Argument Type Summary
serial uint32 this event’s serial number
connection new_id the connection object
version uint32 the version of the connection object
Destructor

Immediately after sending this request, the object is considered destroyed by the EIS implementation. It must no longer be used by the client.

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.

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 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.

The serial number is the start value of the EIS implementation’s serial number sequence. Clients must not assume any specific value for this serial number. Any future serial number in any event is monotonically increasing by an unspecified amount.