Protocol docs

[KI4STU]

As a user, I want documentation outlining what FDLS expects for input and what it feeds back to the clients, so that I can understand what's going on.

[TinyFerret]

FDLS expects a string containing eight fields, separated by a semicolon (;), and terminated by a pound sign (#). The fields are, in order:

UUID (form 8-4-4-4-12, dashes required); Unix epoch time (11 digits, 0-9); ClientID (form A-000 or HLFDS); Band: WARC bands only (160M, 80M, 40M, 20M, 15M, 10M, 6M, 2M, 1.25M, 70CM, 33CM, 23CM) Mode: PHONE, CW, DIGITAL Call: other stations callsign Class: Station class, 1A, etc Section: 2-character alpha Operator: Operator's callsign

Example: 123e4567-e89b-12d3-a456-426655440011;01487099630;HLFDS;20M;PHONE;W1AW;1A;KS;W1AW;#

Entries are accepted once per connection only. Once an entry is sent, the connection must be closed, then re-opened. This applies to the SENDALLCONTACTS command as well.

[KI4STU]

It also, alternately, expects the string SENDALLCONTACTS. This is a command sent by a client when the client is requesting the server to send all log entries contained in the server database back to the client. The server does know how to respond to this and will successfully dump it's entire database back to the client. This actually ends up being quite useful: you can end up with the database effectively being replicated among all clients, limiting the chance of a failure causing lost data.

The ClientID is currently limited on the server-side only; this is based on the default/auto-generated values from HamLog clients and/or the HamLogFDS. The client-side seems to allow for much more free form ClientID values, so FDLS could easily be extended to support them. There could be desire for this in the form of tactical station names (e.g. Station1, Dig-1, FranktheCWmaster), but it is unknown if this will cause compatibility issues with the original HamLogFDS.

It is worth noting that the Operator field is not restricted to just callsigns; the operator's name or initials could easily be used as well (and are acceptable/common values).

It's also worth noting that "entries are accepted once per connection" isn't strictly true. The HamLog client has a "push all" function which will send all contacts in its local database to the server en masse. This results in a huge push of data, and is the main reason why single-byte parsing is done; it was impossible to define a large enough buffer to account for all cases, so when the buffer would get filled log entries would end up split between buffers making parsing quite difficult. By parsing a byte at a time the buffer is slowly built up until it matches an expected value (e.g. SENDALLCONTACTS, a single log entry, or something unknown). The "connection" (TCP session) actually remains open between sends. Interestingly enough, the connection is closed if the HamLog client is put into the background on an Android device (e.g. you switch to the home screen or another app momentarily). The connection is immediately established again when the HamLog client is brought back into focus.