Helium Hex Editor Documentation: Structures

Struct Viewer

The struct viewer dialog allows to quickly decode a struct
   - from any document type (file, memory, registry, OLE stream, ...)
   - at any address

Clicking a field highlights the field into the struct.

If the associated document is in Read/Write mode, double clicking field value (or representation value at the bottom) allows to quickly change the field value. Presse enter to validate the change, or escape to cancel the change.

   - Toolbar
   - Add / Edit Struct
   - Syntax
       User Types
       User Defines

Toolbar

	Add Structure
	Edit Structure Properties
	Remove Selected Structure(s)
	Remove All Structures
	Expand All Structures
	Collapse All Structures
	Save Structures List: save current strutures list into a file for future reloading
	Reload Structures List: reload a saved list of structures
	Open Structures Folder
	Open Defines Folder
	Reload Structures And Defines Definitions

Add / Edit Struct
After clicking the add or edit structure, the following dialog will allow you to
   - Select the structure
   - Specify the document associated to the structure
   - Specify the start offset of the structure

As processor type and endianess can have impact on struct parsing, you can specify them too.

Syntax
Notice : Structure definition files and user define types files are fully compatible with WinApiOverride

User Types
User Types are located into the "UserTypes" directory or "UserTypes\ModuleName" directory

The following user types are supported
   - enum
   - struct
   - union
   - bits fields

The content of the file is a C/C++ syntax, so you can make copy and paste from your source code.

For enum definitions, the following operations are allowed : +, -, *, /, ||, &&, !, |, &, ^, ~, <<, >> , ? :

If your type need subtypes, you could put subtypes in the same file, before the type definition, like in your source code.

Specific cases :
As file name can't have ":", "<" or ">" symbols, user type file name must follow the following replacement rules

- for "Class::Type" type, a "Class..Type.txt" file will be searched ( ":" replaced by ".")
- for "TemplateType<MyType>", "TemplateType(MyType).txt" file will be searched ( "<" replaced by "(" and ">" by ")")

Notice : You still can let "Class::Type" or "TemplateType<MyType>" type in your definitions content, the translation is done by Helium Hex Editor.
Only text file name needs to be affected

Example: supported syntax

typedef union 
{
    DWORD u1;
    BYTE  u2; 
    BYTE  u3; 
}UNION_1;
 
typedef struct
{
    UNION_1 u;
    DWORD* pdw;
    BYTE  bArray[5]; 
    char* str;
    DWORD dwArray[2][2];
    DWORD dw;
}STRUCT_1;
typedef STRUCT_1* PSTRUCT_1;
 
enum enum1
{
    FOO_1 = 0x123,
    FOO_2,
    FOO_3 = 2*FOO_1
};
enum enum2
{
    FOO_21 = 0x123,
    FOO_22,
    FOO_23 = 0x456
};
 
typedef struct
{
    STRUCT_1 S[2];
    DWORD dw1, dw2; 
    /* some comment
    *
    */
    union _u
    {
        DWORD LSB:1,
              b2:1,
              b3:1,
              b4:1,
              unused:27,
              MSB:1;
        DWORD RawValue;
        // 0x8000000A = 1000 0000 0000 0000 0000 0000 0000 1010
    }U;
    DWORD dw4;
 
 
    struct Date {
        DWORD nWeekDay  : 3;    // 0..7   (3 bits)
        DWORD nMonthDay : 6;    // 0..31  (6 bits)
        DWORD           : 0;    // Force alignment to next boundary.
        DWORD nMonth    : 5;    // 0..12  (5 bits)
        DWORD nYear     : 8;    // 0..100 (8 bits)
        DWORD Foo       : 30; // just to force another DWORD
    }d;
 
    enum1 e1[2];
    enum2 e2;
}STRUCT_2,*PSTRUCT_2;

#include : Include other user type files with #include
Allow to includes Types definition from another type definition.
This is usefull only if required type doesn't has a file associated.
If required type file exists it will be automatically parsed and you don't need #include
#include "OtherUserType.txt"

Supported Standard Pragma ( #pragma pack(push), #pragma pack(Value), #pragma pack(pop) )
The following #pragma pack are supported:
#pragma pack(push)
#pragma pack(X) // where X is a number
#pragma pack(pop)
#pragma pack(push,X) // where X is a number
#pragma pack(pop,X) // where X is a number

    #pragma pack(push)
    #pragma pack(1)  
    typedef struct
    {
        BYTE b;
        WORD w;
        DWORD dw;
    }STRUCT1;
    #pragma pack(pop)

Specific Pragma
The following pragmas are not standard and Helium Hex Editor / WinApiOverride defined only

#pragma next_field_define_values_file("File")
Using this pragma allows to provide the define text value instead of the raw value
File path provided is relative path from the "UserDefines" directory

        struct __tagVARIANT
        {
            #pragma next_field_define_values_file("VARTYPE_Defines.txt")
            VARTYPE vt;
            WORD wReserved1;
            WORD wReserved2;
            WORD wReserved3;
            ...
        }

when decoding something like VT_UI4 will displayed instead of 19

#pragma next_enum_size(X)
#pragma next_enum_size(X) // where X is a number which specifies the size of the enum in bytes
Allow to specify a size for a pseudo enum. This is usefull when UINT8,UINT16,... are used as enum.
The availability to specify an enum instead of such type provides you a quick decoding way.
Parameter will show the enum text instead of the raw value

        #pragma next_enum_size(1)
        typedef enum
        {
            E1_value0=0,
            E1_value1,
            E1_value2,
        }ENUM1;
    
        #pragma next_enum_size(2)
        typedef enum
        {
            E2_value0=0,
            E2_value1,
            E2_value2,
        }ENUM2;

#next_field_endianness(little_endian/big_endian)
The next field endianness is modified
By default if no endianness is specified, endianness is little_endian

        typedef struct
        {
            WORD w; // w will be parsed as little endian (default)
            
            #pragma next_field_endianness(big_endian)
            DWORD dw; // dw will be parsed as a big endian
            STRUCT2 Struct2;
        }STRUCT1;

#pragma next_struct_endianness(little_endian/big_endian[,true/false = false])
The second paramter, which is optional (default value=false), specifies if endianness applies to substructures (true) or not (false)
By default if no endianness is specified, endianness is little_endian

        #pragma next_struct_endianness(big_endian,true)
        typedef struct
        {
            WORD w;   // w will be parsed as a big endian
            DWORD dw; // dw will be parsed as a big endian
            STRUCT2 Struct2; // in this case, Struct2 will be parsed as a big endian struct as endianness applies to substructures
        }STRUCT1;
        All the fields and nested structs of the previous struct will be parsed as big endian
    
        #pragma next_struct_endianness(big_endian,false)
        typedef struct
        {
            WORD w;   // w will be parsed as a big endian
            DWORD dw; // dw will be parsed as a big endian
            STRUCT2 Struct2; // in this case, Struct2 will be parsed as a little endian struct as endianness doesn't apply to substructures
        }STRUCT3;

#pragma next_field_must_XXX
All the following #pragma next_field_must_XXX pragma are for quick field value checking.
The background color of the field is set to green (if field match condition) or red (field doesn't match condition)
The background color of owning struct is green if all fields with "#pragma next_field_must_XXX" conditions match,
and red as soon as at least a single child field doesn't match the condition

        typedef struct
        {
            WORD w;
            
            #pragma next_field_must_match(2)
            DWORD dw;
            
            STRUCT2 Struct2;
        }STRUCT1;

The background color of dw is green if dw==2, red else.
In this case as we get only one child with condition, the background color of STRUCT1 will be the same as the background color of dw

#pragma next_field_must_match(x)
The next field must match the provided content
3 kinds of type are supported : value, string or GUID. The format are the following
#pragma next_field_must_match(value)
#pragma next_field_must_match("string") for ascii or unicode string
#pragma next_field_must_match({GUID})

        typedef struct
        {
            ...
            #pragma next_field_must_match(2)
            DWORD dw;       
            
            #pragma next_field_must_match("Some String")
            LPCSTR String;
            
            #pragma next_field_must_match("Some String")
            LPWCSTR wString;
            
            #pragma next_field_must_match({00000000-0000-0000-C000-000000000046})
            GUID gGuid;
        };

#pragma next_field_must_match_one_of(v1,v2,v3,...,vN)
The next field must match one of the provided content in the list
3 kinds of type are supported : value, string or GUID. The format are the following
#pragma next_field_must_match_one_of(value1,value2,value3,...,valueN)
#pragma next_field_must_match_one_of("String1","String2","String3",...,"StringN") for ascii or unicode string
#pragma next_field_must_match_one_of({GUID1},{GUID2},{GUID3},...,{GUIDN})

        typedef struct
        {
            ...
            #pragma next_field_must_match_one_of(1,8,64,128,256,512,1024,2048)
            DWORD dw;
            
            #pragma next_field_must_match_one_of("AnsiString1","AnsiString2","AnsiString3")
            CHAR String[256];
    
            #pragma next_field_must_match_one_of("UnicodeString1","UnicodeString2","UnicodeString3")
            WCHAR wString[256];

            #pragma next_field_must_match_one_of({00000000-0000-0000-C000-000000000046},{00021401-0000-0000-C000-000000000046},{04731B67-D933-450a-90E6-4ACD2E9408FE})
            GUID gGuid;
        };

#pragma next_field_must_match_buffer({v1,v2,v3,...,vN})
The next field begin must match the provided array
That means your search motif size can be shorter than the next field array size.

        typedef struct
        {
            ...
            
            // for the following field, the full buffer content will be compared
            #pragma next_field_must_match_buffer({0x11,0x22,0x33,0x44,0x55})
            BYTE Array1[5];
               
            // for the following field, only buffer begin will be compared
            #pragma next_field_must_match_buffer({0x11,0x22,0x33,0x44,0x55})
            BYTE Array2[12];
            
            ...
        };

#pragma next_field_must_match_one_of_buffer({v1,v2,v3,...,vN},{v1b,v2b,v3b,...,vNb},{v1c,v2c,v3c,...,vNc},...)
The next field begin must match one of the provided array in the list
That means your search motif size can be shorter than the next field array size.

        typedef struct
        {
            ...
            
            // for the following field, the full buffer content will be compared
            #pragma next_field_must_match_one_of_buffer({0x11,0x22,0x33,0x44,0x55},{0x51,0x42,0x33,0x24,0x15},{0x21,0x32,0x43,0x54,0x65})
            BYTE Array1[5];
               
            // for the following field, only buffer begin will be compared
            #pragma next_field_must_match_one_of_buffer({0x11,0x22,0x33,0x44,0x55},{0x51,0x42,0x33,0x24,0x15},{0x21,0x32,0x43,0x54,0x65})
            BYTE Array2[12];
            
            ...
        };

#pragma next_field_must_be_less_or_equal(x)
#pragma next_field_must_be_less_or_equal(x) where x is a value the next field must be less or equal to x (Value<=x)

        typedef struct
        {
            ...
            #pragma next_field_must_be_less_or_equal(80)
            DWORD dw;
            
            #pragma next_field_must_be_less_or_equal(0x28)
            DWORD dw2;           
            ...
        };

#pragma next_field_must_be_greater_or_equal(x)
#pragma next_field_must_be_greater_or_equal(x) where x is a value the next field must be greater or equal to x (Value>=x)

        typedef struct
        {
            ...
            #pragma next_field_must_be_greater_or_equal(3)
            DWORD dw;
            
            #pragma next_field_must_be_greater_or_equal(0x28)
            DWORD dw2;        
            ...
        };

#pragma next_field_must_be_between_inclusive(x,y)
#pragma next_field_must_be_between_inclusive(x,y) where x and y are values the next field must be greater or equal to x and lower or equal to y ( x <= Value <= y )

        typedef struct
        {
            ...
            #pragma next_field_must_be_between_inclusive(10,56)
            DWORD dw;
            
            #pragma next_field_must_be_between_inclusive(2.7,2.95)
            double dbl; 
    
            #pragma next_field_must_be_between_inclusive(2.5,4.5)
            float f;        
            ...
        };

User Defines
User Defines are located into the "UserDefines" or "UserDefines\ModuleName" directory

Only integer defines are supported (no floats or strings support)

For defines content, the following operations are allowed : +, -, *, /, ||, &&, !, |, &, ^, ~, <<, >> , ? :, <,>, ==, <=,>=

Example of content :

#define FOO1 45
#define FOO2 1024
#define FOO3 32
#define FOO4 (FOO1+FOO3)
#define FOO5 3
#define FOO6 8
 
#define FOO11  (FOO1 +1 -5*(FOO1-FOO2) +( (1+ FOO2/FOO1) *2))
#define FOO12  (FOO1 | FOO3)
#define FOO13  (~FOO3)
#define FOO14  (FOO2^FOO1)
#define FOO15  ((FOO2<FOO1) ? FOO3 : 7)