Document the frontend-backend protocol
This commit is contained in:
parent
ed6fb6c624
commit
8199a1cb58
|
@ -0,0 +1,106 @@
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
Loading…
Reference in New Issue