Skip to content

Client API

Jump to bottom
Andrei Tomashpolskiy edited this page Jun 18, 2019 · 4 revisions

Let me propose the following API for interaction between the mobile device and server:

rpc GetHeadsets (GetHeadsetsRequest) returns (GetHeadsetsResponse);
rpc CreateSession (CreateSessionRequest) returns (CreateSessionResponse);
rpc Sync (stream ClientSyncMessage) returns (stream ServerSyncMessage);
rpc UpdateState (UpdateStateRequest) returns (UpdateStateResponse) {};

Refer to server_api.proto for details.

GetHeadsets

Retrieves the list of headsets. The response will contain an array of Headset objects, each of which will have two fields: id (factory headset identifier) and code (short, human-readable identifier).

CreateSession

Creates a new session for the headset, that this participant has been given. Valid session is required to be able to receive notifications about the state of the headset and to send updates on the participant's mood.

The server will check, if the headset code in the request is (a) valid and (b) not used by someone else. If some of the checks fail, then the server will terminate the exchange by returning an error response with code io.grpc.Status.Code.FAILED_PRECONDITION and description of the problem. Otherwise the server will return a (new or existing) session for the client to use in future requests.

Sync

Sync call establishes a bi-directional message stream.

First message in the stream MUST be a Session message, containing the session object, that has been received from the server during the CreateSession call. The server will check, if the session is valid. If the session is not valid, then the server will terminate the exchange by returning an error response with code io.grpc.Status.Code.UNAUTHENTICATED and description of the problem. Otherwise the exchange is considered established, and the client should listen for incoming messages from the server.

The two kinds of message, that the server may send to the client, are SyncTimeRequest and Notification.

SyncTimeRequest

Initiates a time synchronization procedure. The server will repeatedly send instances of SyncTimeRequest, each of which will contain a single field seqnum of type int64. To each instance of SyncTimeRequest the client MUST respond with exactly one instance of SyncTimeResponse, containing two fields:

  • request's seqnum
  • received_time_utc of type int64, containing the EXACT time, at which the request has been received, in epoch millis (which means that the System.currentTimeMillis() call must be performed IMMEDIATELY upon receiving the request)

Failure to return a response with matching seqnum will lead to termination of the exchange with io.grpc.Status.Code.INVALID_ARGUMENT.

The client can expect the server to send no more than a single SyncTimeRequest at a time (i.e. the server will wait for the client's response before sending the next request).

Notification

A one-off message, containing auxiliary information like headset signal strength, battery level, etc. Content of this message type is subject to change.

The client MUST be prepared to receive a Notification message at ANY time (including, perhaps, during other message exchanges, like SyncTimeRequest/SyncTimeResponse exchange, without affecting them; i.e. it would make sense to process received instances of Notification asynchronously outside of the message receiving thread).

Currently there are the following types of notification:

  • ExperienceStartedEvent (no content)
  • ExperienceStoppedEvent (no content)
  • DevEvent (contains information about headset overall signal quality, individual contact quality and battery level; see contents in server_api.proto)

UpdateState

The client may call UpdateState at ANY time. In the request it must provide the following information:

  • a valid Session object
  • time of state change, in epoch millis
  • enum value of one of four possible states

The client SHOULD NOT perform more than one UpdateState call at a time (i.e. it should wait for the server's response before making another call). Doing otherwise may result in some of the messages being ignored and the information being lost (e.g. when the server is outputting data on the fly).

Clone this wiki locally