HTSMSG Binary Format

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.

HTSMSG Binary Format

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.

Root body

Length	4 byte integer	Total length of message (not including this length field itself)
Body	HTSMSG-Field * N	Fields in the root body

HTSMSG-Field

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

Field encoding for type: map and list

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.

Field encoding for type: s64

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.

Field encoding for type: str

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.

Field encoding for type: bin

Datalength should be the length of the binary object. Data is the binary object itself.