2.3. Structure Definition
Concept
The structure definition is used to model the data structure you want to display in the editor.
A structure definition is a tree structure consisting of structure definition elements. There are two types of elements
: statements and data field definitions. A statement may contain other elements whereas a
data field definition is a leaf in the tree and may not contain other elements.
If the structure definition contains no errors it is compiled into a view.
Statements
A root statement is compiled into one data frame, the root frame of the resulting view.
- Root Statement
The RootStatement is the root element of the structure definition. There can only be one and you cannot delete
it. It contains infomation like author, view definition name and a short description.
A case statement is compiled into zero or one view elements.
- Case Statement
Case Statements are used to define a conditional branch in the compilation process.
A Case Statement contains a pointer into the data. This pointer is evaluated during
compilation and the resulting data is compared against the defined cases.
Each case is a data to structure definition element mapping. The structure definition elements used in the Case Statement
all have to be children of this Case Statement and can be either Statements or Data Field Definitions.
If no case matches the data the default case is choosen.
There is one special predefined case in each case statement named "--- None ---".
A repeat statement is compiled into 0-n data frames.
- Repeat Statement
You can think of a Repeat Statement as an array with variable length.
The length can be
- Static
Specifing the length of the array before the compilation, independent of the data.
- Pointer
Defines a pointer into the underlying data. The pointer is
then evaluated during compilation to yield the length
- Repeat Statement Until Offset
The compiler tries to fit in as many Frames as possible until a certain offset is reached.
The offset is calculated by a defining a location and an alignment.
maximal offset = location + (n * alignment).
The alignment can
- Static
Specifing the alignment before the compilation, independent of the data.
- Pointer
Defines a pointer into the underlying data. The pointer is
then evaluated during compilation to yield the alignment.
- Repeat Statement Until Delimiter
The compiler tries to fit in as many Frames as possible until a delimiter is reached.
If the delimiter has a size of zero bits, it is never found and the remaining bits,
till the end of the data are used.
Data Field Definitions
A Data Encoding Field Definition is compiled into exactly one Data Encoding Field.
- Data Encoding Field Definition
Field size is specified before compilation. Use it if you know the size of the
field beforehand.
- Static
Specifing the size of the array before the compilation.
- Pointer
Defines a pointer into the underlying data. The pointer is
then evaluated during compilation to yield the length
- Field Until Offset Definition
The compiler sizes the resulting field as large as necessary to align the next data frame
to a certain offset.
The offset is calculated by a defining a location and an alignment.
offset = location + (n * alignment).
The alignment can
- Static
Specifing the alignment before the compilation, indepent of the data.
- Pointer
Defines a pointer into the underlying data. The pointer is
then evaluated during compilation to yield the alignment.
Use: Use it to make sure the next fields starts at a certain alignment, e.g paddings of the transported data
in network packets.
- Field Until Delimiter Definition
The compiler looks for a certain bitcombination, the delimiter, starting from
the current offset. The resulting DataField is has a bitsize from the current
offset till the start of the delimiter.
If the delimiter has a size of zero bits, it is never found and the remaining bits,
till the end of the data are used.
Use: Used to model a datastream with an end marker, e.g. C-Style String delimited by '0'.
A Map Field Definition is compiled into one Map Field
- Map Field Definition
A MapField Definition is compiled into a MapField. You can define a String to Data
mapping which is then used to display and edit the data via a combobox.
Use: All map fields could be simulated using a DataEncodingField. But the map field
is more comftable to edit and provides more information in the form of a value name. Use it if
you want to model a field with a very small amount of sensible values where you want to tag
each value with a informative name. Instead of using a Data Encoding Field to display one bit flag
use a map field to describe the effect of the values.
View Definition Editing

Dynamic data views are recompiled after each change to the data. The
recompilation can be turned by disabling the "Compile View" checkbox.
Each data view has an offset where the structure definition starts. This offset is used as
the bitoffset of the first structure node when the structure is rendered. The
offset can be locked to the current selection offset by enabling the Lock checkbox.
If the offset is locked the offset of the structure is always the current selection offset
(If the offset change did not originate from this dataview).
If it is unlocked you can manually change the structure offset.
Clicking on a structure definition element will display the corresponding configuration dialog on the
right side. After changing the element click on the apply button to make the changes take effect or
on the cancel button to undo the changes.
New Insert ->
New Add Above ->
New Add Below
Cut
Copy
Paste (Insert)
Paste (Add Above)
Paste (Add Below)
Delete
On the buttom you can see two tabs
Validation
Before the structure definition is compiled into a view it has to be valid.
The validation tab displays a list of errors in the structure definition which have to be
corrected before the view is compiled. By clicking on the
error you can select the corresponding structure definition element in the structure tree.
Compiler Output
The compiler output tab provides detailed information about the compilation process. This can
be useful if you want to debug complex structure definitions.
By clicking on a compiler message you can select the corresponding structure definition element in the structure tree.
Element Configuration
Root Statement

Example:
Case Statement

The data offset has to be a structure definition element before this case statement.
The data size must be greater than 0 bits.
Example: The case statement evalutes the protocol field in an ip packet to chose correct
view definition. The protocol field has a length of 1 byte, and the defined cases are UDP
and TCP. If none of those two protocols are used the default branch is choosen.
Repeat Statement

This repeat statement is compiled into length
data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by
a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field
is evaluated as an unsigned big endian number.
Repeat Until Offset Statement

This repeat statement is compiled into length
data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by
a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field
is evaluated as an unsigned big endian number.
Repeat Until Delimiter Statement

Example:
Fields
Data Encoding Field Definition

Example:

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by
a multiplication and then an addition (subtraction).
The minimum bitSize is zero.
Example: The data encoding field displays the data inside an udp packet. The length
of the packet is stored int a field called length. The length is in bytes, so we
have to multiply by 8 to get bits. Then we have to substract the headersize of
the udp packet (8 bytes) to get the data size.
Repeat Until Offset Field Definition

Example:

Example:
Repeat Until Delimiter Field Definition

Example: This is the definition for a c-style string. The delimiter is 0x00
and we display the result in ascii. We want to include the delimiter in the displayed data
so we modify the calculated bitsize by adding 1 byte.
Map Field Definition

Example: The Operating System byte in the gzip structure. It is 1 byte long
and there are 8 possible mappings defined.