Htsmsgbinary » History » Version 1
Andreas Smas, 2010-12-08 21:37
1 | 1 | Andreas Smas | = Message structure = |
---|---|---|---|
2 | |||
3 | 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. |
||
4 | |||
5 | The field types are: |
||
6 | |||
7 | ||Name||ID||Description |
||
8 | ||Map||1||Sub message of type map |
||
9 | ||S64||2||Signed 64bit integer |
||
10 | ||Str||3||UTF-8 encoded string |
||
11 | ||Bin||4||Binary blob |
||
12 | ||List||5||Sub message of type list |
||
13 | |||
14 | 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. |
||
15 | |||
16 | = HTSMSG binary format = |
||
17 | |||
18 | The binary format is designed to for back-to-back transmission of messages over a network (TCP) connection. |
||
19 | |||
20 | The root message must always be of type map. |
||
21 | |||
22 | == Root body == |
||
23 | |||
24 | ||Length||4 byte integer||Total length of message (including this length field itself) |
||
25 | ||Body||HTSMSG-Field * N||Fields in the root body |
||
26 | |||
27 | == HTSMSG-Field == |
||
28 | |||
29 | ||Type||1 byte integer||Type of field (see field type IDs above) |
||
30 | ||Namelength||1 byte integer||Length of name of field. If a field is part of a list message this must be 0 |
||
31 | ||Datalength||4 byte integer||Length of field data |
||
32 | ||Name||N bytes||Field name, length as specified by Namelength |
||
33 | ||Data||N bytes||Field payload, for details see below |
||
34 | |||
35 | === Field encoding for type: map and list === |
||
36 | |||
37 | 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. |
||
38 | |||
39 | === Field encoding for type: s64 === |
||
40 | |||
41 | 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]. |
||
42 | |||
43 | 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. |
||
44 | |||
45 | === Field encoding for type: str === |
||
46 | |||
47 | 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. |
||
48 | |||
49 | === Field encoding for type: bin === |
||
50 | |||
51 | Datalength should be the length of the binary object. Data is the binary object itself. |
||
52 | |||
53 |