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 handshake_version event with a version other than 1, and, in response,
• the client sends the handshake_version request with a version equal or lower to the EIS implementation version.

The EIS implementation must send the handshake_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

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.

Requests

ei_handshake.handshake_version

Since Version1 Request Opcode0

ei_handshake.handshake_version(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)

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)

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)

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) as announced by the ei_connection.interface_version event.

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)

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)

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

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)

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.