Tvheadend

h1. 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

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.

h1. 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*.

h2. Root body

 ||Length||4 byte integer||Total length of message (including this length field itself)

 ||Body||HTSMSG-Field * N||Fields in the root body

h2. 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

h3. 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.

h3. 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=[0x05 0x39].

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.

h3. 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.

h3. Field encoding for type: bin

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