| description |
|---|
Message Structure |
A message can be of either map or list type. In a map each field has a name, in a list the members do not have names, but the order should be preserved.
The field types are:
| Name | ID | Description |
|---|---|---|
| Map | 1 | Sub message of type map |
| S64 | 2 | Signed 64bit integer |
| Str | 3 | UTF-8 encoded string |
| Bin | 4 | Binary blob |
| List | 5 | Sub message of type list |
| Dbl | 6 | Double precision floating point |
| Bool | 7 | Boolean |
| UUID | 8 | 64 bit UUID in binary format |
All in all the message structure is quite similar to JSON but most notably; no boolean nor null type exist and HTSMSG supports binary objects.
The binary format is designed to for back-to-back transmission of messages over a network (TCP) connection.
The root message must always be of type map.
| Length | 4 byte integer | Total length of message (not including this length field itself) |
| Body | HTSMSG-Field * N | Fields in the root body |
| Type | 1 byte integer | Type of field (see field type IDs above) |
| Namelength | 1 byte integer | Length of name of field. If a field is part of a list message this must be 0 |
| Datalength | 4 byte integer | Length of field data |
| Name | N bytes | Field name, length as specified by Namelength |
| Data | N bytes | Field payload, for details see below |
The data is repeated HTSMSG-Fields exactly as the root body. Note the subtle difference in that for the root-message the length includes the 4 bytes of length field itself whereas in the field encoding the length written includes just the actual payload.
Integers are encoded using a very simple variable length encoding. All leading bytes that are 0 is discarded. So to encode the value 100, datalength should be 1 and the data itself should be just one byte [0x64]. To encode 1337; datalength=2, data=[0x39 0x05].
Note that there is no sign extension in this encoding scheme so if you need to encode -1 you need to set datalength=8 and data = [0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff]. This can certainly be thought of as a bug, but it is the way it is.
Datalength should be the length of the string (NOT including the null terminating character). Thus the null terminator should not be present in data either.
Datalength should be the length of the binary object. Data is the binary object itself.