ei_connection

Core Global Object

The core connection object. This is the top-level object for any communication with the EIS implementation.

Note that for a client to receive this object, it must announce support for this interface in ei_handshake.interface_version.

Enums

ei_connection.disconnect_reason

A reason why a client was disconnected. This enum is intended to provide information to the client on whether it was disconnected as part of normal operations or as result of an error on either the client or EIS implementation side.

A nonzero value describes an error, with the generic value “error” (1) reserved as fallback.

This enum may be extended in the future, clients must be able to handle values that are not in their supported version of this enum.

Requests

ei_connection.sync

Since Version1 Request Opcode0

ei_connection.sync(callback, version)

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.

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.

Note that for a client to use this request it must announce 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 the client.

ei_connection.disconnect

Since Version1 Request Opcode1

ei_connection.disconnect()

A request to the EIS implementation that this client should be disconnected. This is a courtesy request to allow the EIS implementation to distinquish between a client disconnecting on purpose and one disconnecting through the socket becoming invalid.

Immediately after sending this request, the client may destroy the ei_connection object and it should close the socket. The EIS implementation will treat the connection as already disconnected on receipt and does not send the ei_connection.disconnect event in response to this request.

Events

ei_connection.disconnected

Since Version1 Event Opcode0

ei_connection.disconnected(last_serial, reason, explanation)

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 a request by the client or zero if the client has not yet issued a request.

Where a client is disconnected by EIS on purpose, for example after a user interaction, the reason is disconnect_reason.disconnected (i.e. zero) and the explanation is NULL.

Where a client is disconnected due to some invalid request or other protocol error, the reason is one of disconnect_reason (i.e. nonzero) and explanation may contain a string explaining why. This string is intended to help debugging only and is not guaranteed to stay constant.

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

There is no guarantee this event is sent - the connection may be closed without a disconnection event.

ei_connection.seat

Since Version1 Event Opcode1

ei_connection.seat(seat, version)

Notification that a new seat has been added.

A seat is a set of input devices that logically belong together.

This event is only sent if the client announced support for the “ei_seat” 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_seat” interface.

ei_connection.invalid_object

Since Version1 Event Opcode2

ei_connection.invalid_object(last_serial, invalid_id)

Notification 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 does not exist as seen by the EIS implementation. The protocol is asynchronous and this may occur e.g. when the EIS implementation destroys an object at the same time as the client requests functionality from that object. For example, an EIS implementation may send ei_device.destroyed and destroy the device’s resources (and protocol object) at the same time as the client attempts to ei_device.start_emulating on that object.

It is the client’s responsibilty to unwind any state changes done to the object since the last successful message.

ei_connection.ping

Since Version1 Event Opcode3

ei_connection.ping(ping, version)

The ping event asks the client to emit the ‘done’ event on the provided ei_pingpong 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 must be destroyed by the ei client 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 resulting ei_pingpong.done request is ignored by the EIS implementation.

Note that for a EIS implementation to use this request the client must announce support for this interface in ei_handshake.interface_version. It is a protocol violation to send this event to a client without the “ei_pingpong” interface.