Structure Definition Overview
A Hex Workshop structure closely resembles a structure definition the C programming language, which is familiar to many developers and easily learned by others. Future versions of Hex Workshop will incorporate a structure building tool along with the ability to extract structures from existing C/C++ source files.
The following is an example of a Hex Workshop Structure definition. Both C++ comments ("// COMMENT") and C comments( "/* COMMENT */") are supported.
/*
* LocalFileHeader for a .ZIP compressed file.
*/
struct LocalFileHeader
{
char Signature[4]; // PK<0x03><0x04>
#pragma verify match_var_int("Signature[0]", "0x50")
#pragma verify match_var_int("Signature[1]", "0x4B")
#pragma verify match_var_int("Signature[2]", "0x03")
#pragma verify match_var_int("Signature[3]", "0x04")
WORD VersionNeededToExtract;
WORD GeneralPurposeBitFlag;
WORD CompressionMethod;
DOSTIME LastModFileTime;
DOSDATE LastModFileDate;
DWORD Crc32;
DWORD CompressedSize;
DWORD UncompressedSize;
WORD FileNameLength;
WORD ExtraFieldLength;
};
The general format of a structure is as follows:
struct <<STRUCTURE_NAME>>
{
<<DATA_TYPES_AND_NAMES>>
};
A structure definition begins with the key word "struct" followed by the structure name. The structure name cannot contain any tabs or spaces. An opening brace "{" marks the beginning of the data declaration and a closing brace "}" marks its end. Lastly, a semicolon ";" marks the end of the structure definition.
Data types are declared in the following form:
<<DATA_TYPE>> <<VARIABLE_NAME>;
A trailing semicolon is required and variable names cannot contain tabs or spaces.
For a list of basic built-in data types, see Basic Structure Data Types. Additional data types are provided in the standard-type library included with Hex Workshop.
You can nest one structure within another by using a command of the following form:
struct <<STRUCTURE_NAME>> <<VARIABLE_NAME>>;
In the following example, an ARGB structure is defined and followed by the definition of a palette structure, which as defined below contains an array of 256 ARGB structures.
struct ARGB
{
BYTE alpha;
BYTE red;
BYTE green;
BYTE blue;
};
struct palette
{
struct ARGB entries[256];
};
The typedef keyword allows users to create and name new data types. Each new data type must map to a basic built-in data type or a pre-defined type. The following example creates two 8 bit signed integer data types named "BYTE" and "byte". The struct myTypedefExample then uses a basic type and the newly created data types to create a structure with three 8 bit signed values (b1, b2, and b3).
typedef signed __int8 BYTE;
typedef BYTE byte;
struct myTypedefExample
{
signed __int8 b1;
BYTE b2;
byte b3;
} ;
Users can also typedef structures and enumerations. Typedef must be specified as part of the declaration. The example below defines a new data type POINT and LINE structure. The LINE structure defines the start and end points of the line by naming the full structure (struct tagPOINT) and the typedef name (POINT):
typedef struct tagPOINT
{
LONG x;
LONG y;
} POINT;
struct LINE
{
struct tagPOINT start;
POINT end;
};
By adding a #include directive to a structure library definition file, Hex Workshop will insert the literal contents of the designated structure library (#include parameter) into your current structure library file where the #include is defined. For example, all of the sample structure libraries included with Hex Workshop reference a common library that consists of common and standard data types. The #include directive used in the sample libraries is provided below.
#include "standard-types.hsl"
The __this__ and __parent__ variables are used to reference data from the base of the structure or parent structure.
__parent__
Considering having a nested structure that references a length variable within two different parent structures. One might want to define a structure that is based off a relative address from the start of a parent instead of the actual variable name. In the example below, the length variable is defined with different names in PARENT_1 and PARENT_2
typedef struct NESTED
{
WORD someData[ushortAt(addrof(__parent__))] ;
} NESTED ;
typedef struct PARENT_1
{
WORD parent1Length;
NESTED nested ;
} PARENT_1;
typedef struct PARENT_2
{
WORD parent2Length;
NESTED nested ;
} PARENT_2;
In the example above, the "NESTED" structure defines an array of WORDs where the array length hard-coded to the first WORD in any parent structure. This allows users to use this structure in definitions where the parent variable name may differ. In this case, PARENT_1's length is "parent1Length" and PARENT_2's length is "parent2Length".
__this__
The __this__ keyword references the begin of a structure. Consider a case where one has a WORD length followed by N number of words. You can define a structure to display this data this in multiple ways:
typedef struct TYPICAL
{
WORD length;
WORD data[length];
} TYPICAL;
typedef struct ALTERNATIVE
{
WORD data[ushortAt(addrof(__this__))+1];
} ALTERNATIVE;
In this example, the "ALTERNATIVE" structure's length is defined as effectively at the data[0] position. The "TYPICAL" structure is clearly preferred; however, cases exist where using __this__ is useful.
Definition Overview, Data Types, Enumerated Types, Arrays, Strings, Bitfields, Expressions, Conditionals, Functions, Verification, Library Settings, Structure Settings, and Reserved Words and Symbols.