Overview

The Structure Viewer and Add Structure dialog allow users to verify basic pre-conditions on structures (sanity check).  

While adding a structure, icons are displayed next to the structure definition to indicate the validation status.  Users can press the "Validation Status" to investigate which validation check failed.

Floating and locked structures also display a "verify failed" message in the Structure Viewer if any validation conditions fail.  The user can press the yellow warning icon button on the Structure Viewer toolbar to investigate.

For example, adding a ZIP format "LocalFileHeader" at the wrong offset tells the users that the signature doesn't match expectations.

Structure Definitions support two methods of declaring verification checks:

  1. __verify(<expression>) function

  2. #pragma verify

We recommend using the __verify(<expression>) method when possible as the #pragma method will be deprecated in future releases of Hex Workshop.

__verify(<expression>)

The __verify function allows users to define expressions to validate pre-conditions.  For example:

typedef struct tagBITMAPFILEHEADER

{

    WORD    bfType;

    DWORD   bfSize;

    WORD    bfReserved1;

    WORD    bfReserved2;

    DWORD   bfOffBits;
 

    // Verify that file header looks sane

    __verify(

            (bfType == 0x4D42)   &&        // Expected type: 'BM'

            (bfSize == __getDocSize()) &&  // header size matches file size

            (bfOffBits < __getDocSize())   // image offset within range

        ) ;

} BITMAPFILEHEADER ;

 

This method allows complex validation rules; however, presently does not support string comparisons.

#pragma verify

The pragma verify statement allows users to define integer and string comparisons.

The Syntax is as follows:

#pragma verify <<MATCHTYPE>>("<<VARIABLE>>", "<<VALUE>>")

 

NOTE: The variable and value must be quoted.

MATCHTYPE

Description

match_var_int

Compares a variable against the specified integer value.  8, 16, 32, and 64 bit values are supported.  The value can be declared in either decimal or hex.

Examples:

#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")

#pragma verify match_var_int("magic", "0xCAFEBABE")

 

match_var_str

Compares a variable against the specified string value.

Examples:

#pragma verify match_var_str("method", "add")

 

 

More Information on Structure Definitions

Definition Overview, Data Types, Enumerated Types, Arrays, Strings, Bitfields, Expressions, Conditionals, Functions, Verification, Library Settings, Structure Settings, and Reserved Words and Symbols.