Protocol Types

Protocol Types

The protocol types are described as used in the protocol specification.

All types are encoded in the EIS implementation’s native byte order.

String encoding

Strings are encoded as a length-prefixed zero-terminated UTF-8 string. Each string is prefixed by one 32-bit unsigned integer that specifies the length of the string including the trailing null byte. Then follows the string itself, zero-padded to the nearest multiple of 4 bytes.

A NULL-string is thus 4 bytes long in the protocol, with a length of zero and no string:

[0x00, 0x00, 0x00, 0x00]

The empty string ("") is 8 bytes long, with a length of 1 and 4 bytes of zeros for the string null byte and 3 bytes of padding. Full (le) encoding:

[0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]

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']

Object IDs

Object IDs are unique, monotonically increasing 64-bit integers that must not be re-used by the client or the EIS implementation. Object IDs created by the client start at 1 and must be less than 0xff00000000000000. Object IDs allocated by the EIS implementation start at and must not be less than 0xff00000000000000.

Where a request or event specifies a new_id argument, it is the caller’s responsibility to create a new Object ID and map that to the corresponding object. For example, in the ei_handshake.connection event, the EIS implementation will allocate an object in the permitted range and send it to the client. Both client and EIS implementation must refer to this object with this allocated ID. Once the object is destroyed, the ID is discarded and must not be re-used.

Special items in the protocol

Interface names

Some requests and events, for example ei_handshake.interface_version require arguments that represent interface names. Interface names on the wire are always in the form “ei_foo”, i.e. lowercase snake_case spelling, as used in the protocol specification.

Serial numbers

Some events have a serial argument corresponding to a serial number assigned by the EIS implementation. The serial number is a monotonically increasing unsigned 32-bit number (that wraps, clients must handle this). Some requests have a last_serial argument that clients must set to the most recently seen EIS serial number.

The serial number aims to help a client track failure cases and the EIS implementation to detect errors caused by the protocol’s asynchronicity. For example, if the EIS implementation pauses a device at the serial number N and subsequently receives an event with a last_serial of N-1, the EIS implementation knows that the events were caused by the client lagging behind and are not a protocol violation. The events can thus be discarded but the client does not need to be disconnected.