Htsmsgbinary » History » Revision 2
Revision 1 (Andreas Smas, 2010-12-08 21:37) → Revision 2/5 (Andreas Smas, 2010-12-08 21:38)
= Message structure =
A message can be of either '''map''' 'map' or '''list''' 'list' type. In a '''map''' map each field has a name, in a '''list''' list the members do not have names, 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''' boolean nor '''null''' null type exist and HTSMSG supports '''binary''' 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'''. map.
== Root body ==
||Length||4 byte integer||Total length of message (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=[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.
=== 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.
A message can be of either '''map''' 'map' or '''list''' 'list' type. In a '''map''' map each field has a name, in a '''list''' list the members do not have names, 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''' boolean nor '''null''' null type exist and HTSMSG supports '''binary''' 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'''. map.
== Root body ==
||Length||4 byte integer||Total length of message (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=[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.
=== 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.