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