X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.databoard%2Fsrc-isv%2Fspec%2FBinary%20Format.mediawiki;h=b9e50304b2f8c96c676652e03a70992baa9d7208;hb=e0334c5555088193846c692743067db8e43548d6;hp=d97fa149f1c9aed09a587cec51ef5b109d7a17f5;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git diff --git a/bundles/org.simantics.databoard/src-isv/spec/Binary Format.mediawiki b/bundles/org.simantics.databoard/src-isv/spec/Binary Format.mediawiki index d97fa149f..b9e50304b 100644 --- a/bundles/org.simantics.databoard/src-isv/spec/Binary Format.mediawiki +++ b/bundles/org.simantics.databoard/src-isv/spec/Binary Format.mediawiki @@ -1,181 +1,181 @@ -=Binary Format= -''Binary serialization'' is used in files and network communication. -This document gives a specification how Datatypes and Datavalues are written in binary format. - -All numeric values are in [http://en.wikipedia.org/wiki/Endianness Big Endian] order, aka Network byte order. - -===Boolean=== -Boolean is an UINT8, with one of the following values. - -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Value''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|0 -|false -|- -|1 -|true -|- style="background-color: #f9f9f9;" -|2..255 -|''Invalid value'' -|} - -===Numbers=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Type''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|Byte -|Int8 -|- -|Integer -|Int32 -|- style="background-color: #f9f9f9;" -|Long -|Int64 -|- -|Float -|Float -|- style="background-color: #f9f9f9;" -|Double -|Double -|} - -===Optional=== -There is a Boolean that describes whether there is an actual value. -If false no data follows, true the content ensues. - -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|hasValue : Boolean -|Tells whether there is a ''value'' -|- -|''value'' -|The actual value, available only if hasValue == true. -|} - -===String=== -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]. - -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|length : Length -|Describes the number of bytes in the string using packed integer encoding (1-5 bytes). -|- -|''data'' -|Modified-UTF-8 encoded String. -|} - -The length is encoded as UInt32 of 1 to 5 bytes. -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Value''' -|'''Encoding''' -|- style="background-color: #f9f9f9;" -| 0x00000000..0x0000007F -| ''value'' (1 byte) -|- -| 0x00000080..0x00003FFF -| ''value & 0x3f | 0x80'', ''value>>6 & 0xff'' (2 bytes) -|- style="background-color: #f9f9f9;" -| 0x00004000..0x001FFFFF -| ''value & 0x1f | 0xC0'', ''value>>5 & 0xff'', ''value>>13 & 0xff'' (3 bytes) -|- -| 0x02000000..0x0FFFFFFF -| ''value & 0x1f | 0xE0'', ''value>>3 & 0xff'', ''value>>12 & 0xff'', ''value>>20 & 0xff'' (4 bytes) -|- style="background-color: #f9f9f9;" -| 0x10000000..0xFFFFFFFF -| ''value & 0x07 | 0xF0'', ''value>>3 & 0xff'', ''value>>11 & 0xff'', ''value>>19 & 0xff'', ''value>>27 & 0xff'' (5 bytes) -|} - - - -===Array=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|length : UInt32 -|Describes the number of elements as unsigned integer. This field is omited if the range is constant. -|- -|''<elements>'' -|Array elements -|} - -===Generic Record=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|''<fields>'' -|Component fields in the order specified in datatype. -|} - -===Referable Record=== -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. -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|recordId : Integer -|Identity that refers in this serialiation to this instance. -|- -|''<fields>'' -|Component fields in the order specified in datatype. -|} - -===Generic Union=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|tag : Byte, Short or Integer -|Number that indicates that type in the UnionType's ''components'' array. Type depends on the number of cases. -|- -|''value'' -|The value of the component type. -|} - -===Variant=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|type : DataType -|Describes the datatype of the following value. -|- -|''value'' -|The value serialized according to the type -|} - -===Map=== -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Field''' -|'''Description''' -|- style="background-color: #f9f9f9;" -|length : UInt32 -|Describes the number of entries in the map using integer encoding. -|- -|''<entries>'' -|Map Entries -|- style="background-color: #f9f9f9;" -|     key : K -|The key serializes according to the Key type -|- -|     value : V -|The value serialized according to the Value type -|} -Entries are written in ascending of the key (See [[typesystem.html#Comparison]]) - - -=File types= -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Extension''' -|'''Description''' -|- -|.dbb ||Databoard Binary File. Concatenation of Datatype + value -|} +=Binary Format= +''Binary serialization'' is used in files and network communication. +This document gives a specification how Datatypes and Datavalues are written in binary format. + +All numeric values are in [http://en.wikipedia.org/wiki/Endianness Big Endian] order, aka Network byte order. + +===Boolean=== +Boolean is an UINT8, with one of the following values. + +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Value''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|0 +|false +|- +|1 +|true +|- style="background-color: #f9f9f9;" +|2..255 +|''Invalid value'' +|} + +===Numbers=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Type''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|Byte +|Int8 +|- +|Integer +|Int32 +|- style="background-color: #f9f9f9;" +|Long +|Int64 +|- +|Float +|Float +|- style="background-color: #f9f9f9;" +|Double +|Double +|} + +===Optional=== +There is a Boolean that describes whether there is an actual value. +If false no data follows, true the content ensues. + +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|hasValue : Boolean +|Tells whether there is a ''value'' +|- +|''value'' +|The actual value, available only if hasValue == true. +|} + +===String=== +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]. + +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|length : Length +|Describes the number of bytes in the string using packed integer encoding (1-5 bytes). +|- +|''data'' +|Modified-UTF-8 encoded String. +|} + +The length is encoded as UInt32 of 1 to 5 bytes. +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Value''' +|'''Encoding''' +|- style="background-color: #f9f9f9;" +| 0x00000000..0x0000007F +| ''value'' (1 byte) +|- +| 0x00000080..0x00003FFF +| ''value & 0x3f | 0x80'', ''value>>6 & 0xff'' (2 bytes) +|- style="background-color: #f9f9f9;" +| 0x00004000..0x001FFFFF +| ''value & 0x1f | 0xC0'', ''value>>5 & 0xff'', ''value>>13 & 0xff'' (3 bytes) +|- +| 0x02000000..0x0FFFFFFF +| ''value & 0x1f | 0xE0'', ''value>>3 & 0xff'', ''value>>12 & 0xff'', ''value>>20 & 0xff'' (4 bytes) +|- style="background-color: #f9f9f9;" +| 0x10000000..0xFFFFFFFF +| ''value & 0x07 | 0xF0'', ''value>>3 & 0xff'', ''value>>11 & 0xff'', ''value>>19 & 0xff'', ''value>>27 & 0xff'' (5 bytes) +|} + + + +===Array=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|length : UInt32 +|Describes the number of elements as unsigned integer. This field is omited if the range is constant. +|- +|''<elements>'' +|Array elements +|} + +===Generic Record=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|''<fields>'' +|Component fields in the order specified in datatype. +|} + +===Referable Record=== +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. +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|recordId : Integer +|Identity that refers in this serialiation to this instance. +|- +|''<fields>'' +|Component fields in the order specified in datatype. +|} + +===Generic Union=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|tag : Byte, Short or Integer +|Number that indicates that type in the UnionType's ''components'' array. Type depends on the number of cases. +|- +|''value'' +|The value of the component type. +|} + +===Variant=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|type : DataType +|Describes the datatype of the following value. +|- +|''value'' +|The value serialized according to the type +|} + +===Map=== +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Field''' +|'''Description''' +|- style="background-color: #f9f9f9;" +|length : UInt32 +|Describes the number of entries in the map using integer encoding. +|- +|''<entries>'' +|Map Entries +|- style="background-color: #f9f9f9;" +|     key : K +|The key serializes according to the Key type +|- +|     value : V +|The value serialized according to the Value type +|} +Entries are written in ascending of the key (See [[typesystem.html#Comparison]]) + + +=File types= +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Extension''' +|'''Description''' +|- +|.dbb ||Databoard Binary File. Concatenation of Datatype + value +|}