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

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