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