3.4 KiB

Raw Blame History

Frontend-Backend Protocol

This document describes how the frontend-backend protocol works. It is not contractual, and the protocol may change in incompatible ways without prior announcements.

Definitions

'c' refers to the ASCII value of the given character encoded as a byte.

MAC is a MAC address as a 6 byte binary value.

status is a one-byte value that can be either 0 (available), 1 (unavailable) or 2 (offline)).

msgid is an unsigned 16 bit value that is used to identify targets of ACKs. You can treat it as more or less an opaque identifier that is valid at least as long the backend stays running or until you get another Msgid event with the same msgid.

nick is the nick encoded as utf-8. It is allowed to have all valid Unicode code points other than C0 and C1 control characters and the characters U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR. nick can be at maximum 255 bytes long.

message is the message encoded as utf-8. It is allowed to have all the codepoints that nick is, plus U+0A LINE FEED which is used to separate lines in a multi-line message. message can be at maximum 1494 bytes long.

All multibyte integer values are big-endian a.k.a. network byte order.

Commands

Frontend sends commands to the backend.

Quit

Format: 'q'

Tells the backend to exit normally, doing cleanup.

Status request

Format: 'r' + MAC

Tells the backend to send an EtherMess status request message to the given MAC address. No caching will be used, and one status request command corresponds to one status request message sent.

Set status

Format: 's' + status + nick length in bytes (u8) + nick

Tells the backend to change its stored values of nick and status, and broadcast the new values to the network. A message will be sent even if you provide the same nick and status that are already set.

Send message

Format: 'm' + MAC + message length in bytes (u16) + message

Tells the backend to queue this message for sending.

Note that only one message can be queued at once, so you should wait until you receive an event either telling you of a failure to send message (Msgid failed, ACK failed) or telling you it has been succesfully received (ACK) before sending another message.

Events

Frontend receives events from the backend.

Speak version

Format: 'v' + MAC + version (u8)

Generated when an EtherMess Speak version packet is received by the backend.

Status

Format: 's' + MAC + status + nick length in bytes (u8) + nick

Generated when an EtherMess status message is received by the backend.

Msgid

Format: 'i' + msgid

Generated when backend is able to give the queued message a msgid.

Msgid failed

Format: 'I'

Generated when backend is unable to give the queued message a msgid. You should consider the most recently queued message to have failed to send.

ACK

Format: 'a' + MAC + msgid

Generated when an EtherMess ACK is received by the backend.

Make sure to pay attention to the msgid, because there is no guarantees it refers to the most recently sent message or to a message you have sent at all.

ACK failed

Format: 'A'

Generated when backend times out on waiting for ACK for the most recently queued message. You should consider the message to have failed to send.

Message received