Project

General

Profile

Htsmsgbinary » History » Version 4

Andreas Smas, 2011-05-01 18:32

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