Contents
Contents
*
Introduction
*
Basic application concepts
*
Nodes and more nodes
*
The need for speed
*
Moving around the application GUI
*
The Main Screen
*
Designing a simple file structure
*
Adding a Node
*
Configuring a Node
*
The Root Node
*
Saving your diagram
*
Export diagram
*
Glossary
*
Introduction
Struct-A-File
is a "Binary File Format Builder Application". In other
words, allows for the user to design and configure a complete
binary file structure using a friendly GUI.
In this document we’ll start by specifying
the main application concepts. This allows the user to
visualise how he will strip down his binary file components.
The next step is to fully explain the application GUI that is
obviously proceeded by an example of how one can structure the
wanted binary file. Only then, the user will be ready to
export it into its DataNode format representation.
Also, the example files used in this
document can be found on the project under the
"./doc/examples" directory.
Basic application
concepts
Nodes and more nodes
Everything is a Node! Well… almost… the
application itself is not. Each application is based in the
very simple concepts of modularity and scalability. To achieve
this it was imperative to separate the main application from
the node configuration.
Basically, the application provides the
context to work in which can be either configuration or
visualisation. On the other hand, the node visitor provides
the information in how to configure it and in how it should be
rendered for visualisation. In this case, Struct-A-File
provides the application configuration context.
Currently there are a small number of
different node types that can be found in the "pool"
subdirectory of each application.
The following table shows the currently
available nodes under its type.
Literal |
Description |
Size in bytes |
ByteNode |
Signed 1 Byte Node |
1 |
UbyteNode |
Unsigned 1 Byte Node |
1 |
IntegerNode |
Signed Integer Node |
System dependent
(norm. 4) |
Integer2Node |
Signed 2 Byte Integer Node |
2 |
Integer4Node |
Signed 4 Byte Integer Node |
4 |
Integer8Node |
Signed 8 Byte Integer Node |
8 |
UintegerNode |
Unsigned Integer Node |
System dependent
(norm. 4) |
UInteger2Node |
Unsigned 2 Byte Integer Node |
2 |
UInteger4Node |
Unsigned 4 Byte Integer Node |
4 |
UInteger8Node |
Unsigned 8 Byte Integer Node |
8 |
FloatNode |
Single Precision Node |
4 |
DoubleNode |
Double Precision Node |
8 |
StringNode |
Character Array Node |
User defined |
|
|
|
Grouping |
|
|
Class |
Groups common elements. |
0 |
|
|
|
Collection |
|
|
Collection |
Maintains a list of several elements of
the same Node type. |
0 |
|
|
|
Switching |
|
|
Switch |
Depending on a previously read Node
value selects which node is to be used to continue reading
the binary file. |
0 |
|
|
|
Literal: The most basic type of node
that normally does not depend from any other and his fully
autonomous on its own.
Grouping: Classifies the nodes under a
common context in the same way that a C "struct" classifies a
group of int, char arrays or float types under a common name.
Collection: Maintains a collection or
list of elements of the same node type.
Switching: Selects one of the child
nodes depending on the value of a dependent node.
The need for speed
Another important thing was to implement a
reading scheme that would not need to read the all binary file
contents while trying to keep it fast to access for file
inspection. So, the only solution I could come up with was to
develop a scheme that would keep track of the file offsets at
points that could interfere with the file reading. After
analysing the basic nodes, one is able to understand that the
main points of interests to keep a file offset are either in
the ClassNode, SwitchNode or mainly at the CollectionNode. In
the majority of the times, this is a quite good solution,
although some specific configurations maintaining the offset
or the literal value itself would cost the same.
Moving around the
application GUI
Ok, just reached my favourite part of
documentation… it’s just because I really like to do Screen
Dumps! :-)
So, here it goes…
The Main Screen
Symbol |
Icon help |
Description |
|
New DataNode diagram |
Creates a new DataNode diagram.
Currently the user can only have one diagram open.
Although, you may run the application several times and
open one diagram per application. |
|
Open saved .bbf file |
Opens a saved BBF file and replaces the
current one with the opened diagram. |
|
Save to .bbf file |
Quick save of displayed diagram. If no
file as being set then the it will use a Save As option to
request the user for a filename for the diagram. |
|
Export to .dnf file |
Export the diagram into a DataNode
format file. |
|
DataNode |
When selected, the user will be able to
add new nodes to the diagram. For that to happen it is
only required to left-click on the diagram canvas and a
new node will be added into the clicked canvas
co-ordinates. |
|
Dependence |
When selected will allow the user to
add dependencies to the node. So, the user has to
left-click on the node, and if this node allows for
dependencies (e.g. ClassNode) then by maintaining
pressed-down the CTRL (Control) key and by left-clicking
on the wanted node/s an arrow will be displayed for each
and everyone of the clicked nodes. |
|
Remove DataNode or Dependence |
Whan left-clicked removes from the
diagram the currently selected node/s and/or dependencies. |
Designing a simple
file structure
Adding a Node
Just select
and
press on canvas.
Configuring a Node
Right click on node and select Edit DataNode.
The configuration window should pop-up.
Give it a name and change type to
ClassNode.
As you may have noticed, the are in blue is
the actually the DataNode type specific configuration area.
Select Accept.
Now add another three nodes and change
their names. Once finished left-click again on the
button
and now left-click on the
button.
This is the Dependencies button and we will now add the three
added DataNodes to the ClassNode. Select the ClassNode by
left-clicking on it. Then while pressing the CTRL key
left-click on the other three nodes. Three arrows should have
been added to the ClassNode. Right-click on the ClassNode and
select Edit DataNode. Now you should see the three elements
added and you can select the order of reading (1st
one-1st).
The Root Node
In order to save it you need to select the
Root Node. I’ll explain later why one needs to set the root
node. So, just select the ClassNode and, once again,
right-click on it. A "set root node" option should appear on
the pop-up menu. Select it and you will notice that the root
node will be displayed in a different colour as shown in the
next image.
Saving your diagram
At this time you’re now able to save your
application. Left-click on the
save
button. You’ll notice that a new window will come up. This
happens because the diagram is being saved for the first time.
Select the directory where you want to save your diagram and
give it a name. Once finished left-click on the Save button.
Notice that the diagram file extension is BBF (.bbf) You can
now left-click on the
new
diagram button to clear the diagram canvas and then left-click
on the
open
button. Browse the directory structure and fetch the diagram
you’ve saved. Et voila!
Export diagram
Exporting is actually just the generation
of another file but, this time in the DataNode Format, a DNF
(.dnf) file. This file does not keep data related with the
diagram, like X, Y positions of the nodes in the canvas, etc.
Instead, all it has his the DataNode configuration for each
node and how they relate to each other’s.
This when the "Root Node" concept comes in.
When exporting the diagram, the application will start by the
Root Node and export the all node configuration tree that he’s
the root of. So, in the previous example, you’ve selected the
ClassNode has the root node, which means that would be reading
binary files that are composed by a String, a Integer and a
Double Node.
If, you wanted to jest read a string, then
you could set the StringNode has the root node and export it
to a DNF file.
Once you have exported your binary file
format, you’re now ready use it with the File-A-Nyzer
application.