ABOUT
Home
 What is it?
Struct-A-File User Guide
File-A-Nyzer User Guide
 DEVELOPMENT
Current Status
The next step
 DOWNLOAD
Requirements
Download package
Installing
SourceForge.net Logo

 

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.

 

 
 

© Copyright 2004 File-Spector Team   
Distributed under the GNU General Public Licence