bundles/org.simantics.databoard/src-isv/spec/Binary Format.mediawiki

   1 =Binary Format=
   2 ''Binary serialization'' is used in files and network communication.
   3 This document gives a specification how Datatypes and Datavalues are written in binary format.
   4
   5 All numeric values are in [http://en.wikipedia.org/wiki/Endianness Big Endian] order, aka Network byte order.
   6
   7 ===Boolean===
   8 Boolean is an <code>UINT8</code>, with one of the following values.
   9
  10 {| border="1" cellpadding="3" cellspacing="0" align="center"
  11 |'''Value'''
  12 |'''Description'''
  13 |- style="background-color: #f9f9f9;"
  14 |<code>0</code>
  15 |false
  16 |-
  17 |<code>1</code>
  18 |true
  19 |- style="background-color: #f9f9f9;"
  20 |<code>2..255</code>
  21 |''Invalid value''
  22 |}
  23
  24 ===Numbers===
  25 {| border="1" cellpadding="3" cellspacing="0" align="center"
  26 |'''Type'''
  27 |'''Description'''
  28 |- style="background-color: #f9f9f9;"
  29 |Byte
  30 |Int8
  31 |-
  32 |Integer
  33 |Int32
  34 |- style="background-color: #f9f9f9;"
  35 |Long
  36 |Int64
  37 |-
  38 |Float
  39 |Float
  40 |- style="background-color: #f9f9f9;"
  41 |Double
  42 |Double
  43 |}
  44
  45 ===Optional===
  46 There is a Boolean that describes whether there is an actual value.
  47 If false no data follows, true the content ensues.
  48
  49 {| border="1" cellpadding="3" cellspacing="0" align="center"
  50 |'''Field'''
  51 |'''Description'''
  52 |- style="background-color: #f9f9f9;"
  53 |<code>hasValue : Boolean</code>
  54 |Tells whether there is a ''value''
  55 |-
  56 |''value''
  57 |The actual value, available only if hasValue == true.
  58 |}
  59
  60 ===String===
  61 String is a series of bytes encoded as [http://download.oracle.com/javase/6/docs/api/java/io/DataInput.html#modified-utf-8 Modified-UTF-8].
  62
  63 {| border="1" cellpadding="3" cellspacing="0" align="center"
  64 |'''Field'''
  65 |'''Description'''
  66 |- style="background-color: #f9f9f9;"
  67 |<code>length : Length</code>
  68 |Describes the number of bytes in the string using packed integer encoding (1-5 bytes).
  69 |-
  70 |''data''
  71 |Modified-UTF-8 encoded String.
  72 |}
  73
  74 The length is encoded as UInt32 of 1 to 5 bytes.
  75 {| border="1" cellpadding="3" cellspacing="0" align="center"
  76 |'''Value'''
  77 |'''Encoding'''
  78 |- style="background-color: #f9f9f9;"
  79 | <code>0x00000000..0x0000007F</code>
  80 | ''value'' (1 byte)
  81 |-
  82 | <code>0x00000080..0x00003FFF</code>
  83 | ''value & 0x3f | 0x80'', ''value>>6 & 0xff'' (2 bytes)
  84 |- style="background-color: #f9f9f9;"
  85 | <code>0x00004000..0x001FFFFF</code>
  86 | ''value & 0x1f | 0xC0'', ''value>>5 & 0xff'', ''value>>13 & 0xff'' (3 bytes)
  87 |-
  88 | <code>0x02000000..0x0FFFFFFF</code>
  89 | ''value & 0x1f | 0xE0'', ''value>>3 & 0xff'', ''value>>12 & 0xff'', ''value>>20 & 0xff'' (4 bytes)
  90 |- style="background-color: #f9f9f9;"
  91 | <code>0x10000000..0xFFFFFFFF</code>
  92 | ''value & 0x07 | 0xF0'', ''value>>3 & 0xff'', ''value>>11 & 0xff'', ''value>>19 & 0xff'', ''value>>27 & 0xff'' (5 bytes)
  93 |}
  94
  95
  96
  97 ===Array===
  98 {| border="1" cellpadding="3" cellspacing="0" align="center"
  99 |'''Field'''
 100 |'''Description'''
 101 |- style="background-color: #f9f9f9;"
 102 |<code>length : UInt32</code>
 103 |Describes the number of elements as unsigned integer. This field is omited if the range is constant.
 104 |-
 105 |''&lt;elements&gt;''
 106 |Array elements
 107 |}
 108
 109 ===Generic Record===
 110 {| border="1" cellpadding="3" cellspacing="0" align="center"
 111 |'''Field'''
 112 |'''Description'''
 113 |- style="background-color: #f9f9f9;"
 114 |''&lt;fields&gt;''
 115 |Component fields in the order specified in datatype.
 116 |}
 117
 118 ===Referable Record===
 119 Referable records are objects that are referenced else where in the datavalue. The way they are serialized is that, when a record is serialized the first time, a 0 is written and then the actual record value. The serializer object gives it a next id number and takes a note of it. Id is not written, it is implicit and only interpretable by reading the stream. When a refereable record the second time, or afterwards, only it's id number is written, not the whole content.
 120 {| border="1" cellpadding="3" cellspacing="0" align="center"
 121 |'''Field'''
 122 |'''Description'''
 123 |- style="background-color: #f9f9f9;"
 124 |<code>recordId : Integer</code>
 125 |Identity that refers in this serialiation to this instance.
 126 |-
 127 |''&lt;fields&gt;''
 128 |Component fields in the order specified in datatype.
 129 |}
 130
 131 ===Generic Union===
 132 {| border="1" cellpadding="3" cellspacing="0" align="center"
 133 |'''Field'''
 134 |'''Description'''
 135 |- style="background-color: #f9f9f9;"
 136 |<code>tag : Byte, Short or Integer</code>
 137 |Number that indicates that type in the UnionType's ''components'' array. Type depends on the number of cases.
 138 |-
 139 |''value''
 140 |The value of the component type.
 141 |}
 142
 143 ===Variant===
 144 {| border="1" cellpadding="3" cellspacing="0" align="center"
 145 |'''Field'''
 146 |'''Description'''
 147 |- style="background-color: #f9f9f9;"
 148 |<code>type : DataType</code>
 149 |Describes the datatype of the following value.
 150 |-
 151 |''value''
 152 |The value serialized according to the type
 153 |}
 154
 155 ===Map===
 156 {| border="1" cellpadding="3" cellspacing="0" align="center"
 157 |'''Field'''
 158 |'''Description'''
 159 |- style="background-color: #f9f9f9;"
 160 |<code>length : UInt32</code>
 161 |Describes the number of entries in the map using integer encoding.
 162 |-
 163 |''&lt;entries&gt;''
 164 |Map Entries
 165 |- style="background-color: #f9f9f9;"
 166 |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>key : K</code>
 167 |The key serializes according to the Key type
 168 |-
 169 |&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>value : V</code>
 170 |The value serialized according to the Value type
 171 |}
 172 Entries are written in ascending of the key (See [[typesystem.html#Comparison]])
 173
 174
 175 =File types=
 176 {| border="1" cellpadding="3" cellspacing="0" align="center"
 177 |'''Extension'''
 178 |'''Description'''
 179 |-
 180 |<tt>.dbb</tt> ||Databoard Binary File. Concatenation of Datatype + value
 181 |}