Messaging API

Variable: peerSocket

The Messaging API allows a device and companion (peers) to communicate with each other.

import { peerSocket } from "messaging";
console.log("Max message size=" + peerSocket.MAX_MESSAGE_SIZE);
if (peerSocket.readyState === peerSocket.OPEN) {
   peerSocket.send("Hello");
}

Enum: CloseCode

Members

CONNECTION_LOST

PEER_INITIATED

SOCKET_ERROR

Class: CloseEvent

Close event

Properties

readonly CONNECTION_LOST

CloseCode.CONNECTION_LOST

readonly PEER_INITIATED

CloseCode.PEER_INITIATED

readonly SOCKET_ERROR

CloseCode.SOCKET_ERROR

readonly code

CloseCode

readonly defaultPrevented

boolean

Set to true when the default handling was prevented

readonly reason

string

readonly target

EventTarget or undefined

Target of the event

readonly type

string

Type of the event

readonly wasClean

boolean

Represents whether the connection was cleanly closed or not.

Enum: ErrorCode

Members

BUFFER_FULL

Class: ErrorEvent

Error event

Properties

readonly BUFFER_FULL

ErrorCode

readonly code

ErrorCode

readonly defaultPrevented

boolean

Set to true when the default handling was prevented

readonly message

string

readonly target

EventTarget or undefined

Target of the event

readonly type

string

Type of the event

Interface: MessageEvent

Properties

readonly data

any

readonly defaultPrevented

boolean

Set to true when the default handling was prevented

readonly target

EventTarget or undefined

Target of the event

readonly type

string

Type of the event

Class: MessageSocket

A MessageSocket allows a device and companion (peers) to communicate with each other.

Each peer endpoint can send messages to and receive messages from the other.

The API used for communication is a subset of the WebSocket API, with a few restrictions and one addition.

NOTE: There is no direct indication as to when the peer's message listener is invoked. The value of the session's bufferedAmount attribute only represents how much data has not been sent yet, not how much data has not been received yet.

Addition:

To allow the client to manage the fullness of the outgoing buffer efficiently, a new [bufferedamountdecrease] event (with an associated [onbufferedamountdecrease] EventListener attribute) is defined.

When the amount of data in the buffer (bufferedAmount) decreases, the [onbufferedamountdecrease] listener is called.

The number of [bufferedamountdecrease] events emitted after data has been buffered by the send method may vary, but at least one [bufferedamountdecrease] event is guaranteed to be emitted when bufferedAmount becomes 0.

NOTE:

binaryType attribute from WebSocket has no equivalent in MessageSocket.

extensions attribute from WebSocket has no equivalent in MessageSocket.

protocol attribute from WebSocket has no equivalent in MessageSocket.

url attribute from WebSocket has no equivalent in MessageSocket.

close() method from WebSocket has no equivalent in MessageSocket.

Properties

readonly CLOSED

ReadyState.CLOSED

readonly MAX_MESSAGE_SIZE

MessageConstants

Maximum message size in bytes.

readonly OPEN

ReadyState.OPEN

readonly bufferedAmount

number

The number of bytes of application data that have been queued using send() but that has not yet transmitted to the tracker.

onbufferedamountdecrease

((this: MessageSocket, event: Event) => any) or undefined

Will be invoked when a "bufferedamountdecrease" event is dispatched

onclose

((this: MessageSocket, event: CloseEvent) => any) or undefined

Will be invoked when a "close" event is dispatched

onerror

((this: MessageSocket, event: ErrorEvent) => any) or undefined

Will be invoked when an "error" event is dispatched

onmessage

((this: MessageSocket, event: MessageEvent) => any) or undefined

Will be invoked when a "message" event is dispatched

onopen

((this: MessageSocket, event: Event) => any) or undefined

Will be invoked when an "open" event is dispatched

readonly readyState

ReadyState

The current state of the connection; this is one of the ReadyState constants.

Methods

send()

send(data: any)

Returns: void

Transmit data to the peer using the connection.

The communication channel has a maximum message size of MAX_MESSAGE_SIZE bytes. If larger messages are needed, it is the responsibility of the endpoints to take care of this at the application layer, possibly using a library to deal with block-wise fragmentation and re-assembly. Internally, the messages may be transmitted through different mechanisms depending on their size, but that is transparent to the endpoints at the API level.

The properties of the communication channel are:

A message is sent in the context of a message session.
A message session exists while the endpoints are running, connected and can receive messages.
Messages are delivered and received in the order they are sent.
There is no message loss while the endpoints are connected. This means that there are no gaps. A message is either successfully transmitted, in order, or it failed to be delivered because the channel has been closed (endpoints disconnected). After a failure, the channel is closed and no messages can be exchanged until a new channel is opened. It is possible, however, that the last messages sent before disconnection will never be delivered.
Messages are asynchronous: a (small) number of messages may be queued, to allow the communication channel to be used at its maximum capacity.

data - Data to be sent. Any object that can be serialized to CBOR may be passed. See CBOR encode. Throws an InvalidStateError error if readyState is not OPEN. Throws an error if the data cannot be encoded to CBOR or if the CBOR encoding of the data is larger than MAX_MESSAGE_SIZE bytes.

Enum: MessageConstants

Members

MAX_MESSAGE_SIZE

Maximum message size in bytes.

Enum: ReadyState

Members

CLOSED

The connection has been closed or could not be opened

OPEN

The MessageSocket connection is established and communication is possible

Interface: EventMap

Properties