107 lines
3.2 KiB
Markdown
107 lines
3.2 KiB
Markdown
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.
|
|
|
|
### 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
|
|
Format: 'm' + MAC + message length in bytes (u16) + message
|
|
|
|
Generated when backend receives a valid message.
|