libei/proto/ei.proto

syntax = "proto3";

/**
 * EI Protocol Specification
 *
 * This protocol is an internal implementation detail and subject to change
 * at any time. This specification is for developers of libei only.
 *
 * ClientMessage → sent from the client to the server
 * ServerMessage → sent from the server to the client
 *
 * A normal sequence consists of:
 * [0.	  - proxy configures connection, see the section below]
 *  1.    - client establishes connection to server
 *  2.    - client sends "Connect"
 *    2.a - server replies with "Connected" or
 *    2.b - server replies with "Disconnected" and closes its end of the socket
 *  3.    - client sends "AddDevice"
 *    3.a - server replies with "DeviceAdded" or
 *    3.b - server replies with "DeviceRemoved"
 *  4.    - server sends "DeviceResumed"
 *  5.    - client sends "PointerRelative" or any other event
 *  6.    - client sends "RemoveDevice"
 *  7.    - client sends "Disconnect" and closes its end of the socket
 *
 * The server may send Disconnect at any time.
 * The server may send Removed for a device at any time after that device's
 * Accepted.
 *
 * Where a server does not accept a client's device it is up to the client
 * to decide whether to Disconnect.
 * Where a server does not accept a client's device the server may send Removed
 * for all current client devices and send Disconnected before closing the
 * connection. IOW a client trying to create a device may result in the
 * client being disconnected. This decision is up to server policy.
 *
 * Where a connection error occurs, the library (libei or libeis) will
 * unroll the state as seen from the API. i.e.
 *
 * Due to the server's ability to modify input device capabilities, the
 * initial requests cannot be batch-processed. Specifically: The AddDevice
 * request (3.) requires the EIS library implementation to query the caller
 * for the response. Until the caller performs the action (and this may
 * including waiting for user confirmation), libeis must discard any events
 * coming from the client for this device.
 *
 * Pre-configuring a connection
 * ----------------------------
 *
 * Where a proxy is in place (e.g. a portal), the client connection can be
 * preconfigured to match the permissions model. The proxy would open a
 * socket to the server, write the Configure* messages onto that socket and
 * then pass the fd to the client to create a libei context from that.
 *
 * The proxy can force a client name and/or restrict other options. This is
 * transparent to the client, it doesn't know what restrictions are in place
 * until it runs up against them (e.g. a device with a restricted capability
 * will not be added with that capability).
 *
 * Configure messages may come at any time but they can only ever *reduce*
 * the current capabilities, not increase them.
 */

/* ConfigureName *must* be sent before the Connect event */
message ConfigureName {
	string name = 1;
}

/* Changes the capability policy and allows or denies specific capabilities */
message ConfigureCapabilities {
	bool policy_is_allow = 1;
	uint32 allowed_capabilities = 2;
	uint32 denied_capabilities = 3;
}

message Connect {
	string name = 1;
}

message Disconnect {
}

message AddDevice {
	uint32 deviceid = 1;
	uint32 capabilities = 2;
	uint32 pointer_width = 3;
	uint32 pointer_height = 4;
	uint32 touch_width = 5;
	uint32 touch_height = 6;
	/* keymap is passed as fd if type is not none */
	uint32 keymap_type = 8;
	uint32 keymap_size = 9;
}

message RemoveDevice {
	uint32 deviceid = 1;
}

message PointerRelative {
	uint32 deviceid = 1;
	double x = 2;
	double y = 3;
}

message PointerButton {
	uint32 deviceid = 1;
	uint32 button = 2;
	bool state = 3;
}

message KeyboardKey {
	uint32 deviceid = 1;
	uint32 key = 2;
	bool state = 3;
}

message ClientMessage {
	oneof msg {
		Connect connect = 1;
		Disconnect disconnect = 2;
		AddDevice add_device = 3;
		RemoveDevice remove_device = 4;
		PointerRelative rel = 5;
		PointerButton button = 6;
		KeyboardKey key = 7;
		ConfigureName configure_name = 8;
		ConfigureCapabilities configure_caps = 9;
	}
}

message Connected {
}

message Disconnected {
}

message DeviceAdded {
	uint32 deviceid = 1;
	uint32 capabilities = 2;
	/* keymap is passed as fd if size is nonzero and type is not none */
	bool keymap_from_server = 3;
	uint32 keymap_type = 4;
	uint32 keymap_size = 5;
}

message DeviceRemoved {
	uint32 deviceid = 1;
}

message DeviceResumed {
	uint32 deviceid = 1;
}

message DeviceSuspended {
	uint32 deviceid = 1;
}

message ServerMessage {
	oneof msg {
		Connected connected = 2;
		Disconnected disconnected = 3;
		DeviceAdded device_added = 4;
		DeviceRemoved device_removed = 5;
		DeviceResumed device_resumed = 6;
		DeviceSuspended device_suspended = 7;
	}
}

/* Protobuf-C only works correctly if the length of the next message is
 * known, so we need to prefix *every* message with our packed size.
 * This message is used by server and client but it's an implementation
 * detail, not a part of the actual protocol.
 */
message Frame {
	fixed32 length = 1;
}