Win32 binary resource formats

From HashVB
Revision as of 16:53, 11 June 2006 by Dee (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Author: Floyd Rogers

This document was taken from http://www.csn.ul.ie/~caolan/publink/winresdump/winresdump/doc/resfmt.txt and I am unsure of the copyright.

This document was edited and released by Microsoft Developer Support. It describes the binary format of resources in Win32. The information is provided at this point because we feel it will make the work of application development easier. Unfortunately, the information in this document may change before the final release of Windows NT. Microsoft is NOT committing to stay with these formats by releasing this document. Questions or follow-ups for any of the information presented here should be posted to CompuServe MSWIN32 forum, section 4. --Steve Firebaugh, Microsoft Developer Support

Overview

This document details the structure of the resource binary file (.res) format for the Windows 32 API (Windows NT 3.1 and Win32s). The structure is similar to the existing Windows 16 (Win 3.0/3.1) structure, but supports essential new features such as UNICODE strings, version headers, and DWORD alignment. To support these changes, the file format written by the resource compiler must be changed from that used by Windows 16.

Comparison between Windows 3.0/3.1 and Windows 32

The Windows 16 resource file is a file containing one or more binary resources. Each resource is preceded by a variable length structure containing: Type, Name, Flags, Size. The Type and Name fields are either a string identifying the Type or Name, or a WORD value specifying the ordinal identity of the resource. The Flags field specifies to the system how to load into memory the resource, and the size specifies the size in bytes of the resource. The size, therefore, points to the next resource in the file.

The Windows 32 (both NT and Win32s) resource file retains this structure, while expanding the header information with several additional values. It also adds a few fields to some of the pre- defined resources (Menu and Dialog, for instance), aligns all fields within the predefined resources on WORD or DWORD boundaries, and adds UNICODE (16-bit character) support to the data structures.

One additional difference in resource files for Windows 32 is worth noting. This does not directly affect the structure of the resource file, but is rather a difference in how resource files are handled and incorporated into an executable image (dll or exe). Windows NT uses COFF format objects. Because of this, and the fact that the Windows 32 exe format is much different than the Windows 16 format, the SDK provides a utility named CVTRES that converts a resource file into a COFF object. The linker then incorporates this object directly into the resulting executable image. No provision is made (as in Windows 16) for running the second pass of the resource compiler multiple times to update the resources: relinking the image is required.

However, the Windows 32 API provides a set of APIs that allow a program to enumerate all resources within an executable image, and update individual resources in the image.

Strings in UNICODE

All strings in a resource file are now stored in UNICODE format. In this format, all characters are represented by a 16-bit (WORD) value. The first 128 characters are identical to the 128 characters in the Windows ANSI character set (although the characters are represented by 16 bits each rather than 8bits). The characters in positions 160- 254 are similar to the characters in the standard Windows character set (note that the characters 128-159 are illegal Unicode codepoints). This means that they are terminated with a UNICODE_NULL symbol rather than a single NULL. The resource compiler translates all normal ASCII strings into UNICODE by calling the MultiByteToWideChar function provided by the Windows API. All escaped characters are stored directly, and are assumed to be valid UNICODE characters for the resource. If these strings are read in later by an application as ASCII (for instance, by calling the LoadString api), they will be converted back from UNICODE to ASCII transparently by the loader.

The only exception to the rule is strings in RCDATA statements. These psuedo-strings are not real strings, but merely a convenient notation for a collection of bytes. Users may overlay a structure over the data from an RCDATA statement, and expect certain data to be at certain offsets. If a psuedo-string gets automatically changed into a UNICODE string, it things would inadvertently change the offsets of things in the structure and break those applications. Hence, these psuedo-strings must be left as ASCII bytes. To specify a UNICODE string inside an RCDATA statement, the user should use the explicit L-quoted string.

DWORD alignment

To make resource binary files easier to read under Windows 32, all objects within the file are to be DWORD aligned. This includes headers, as well as data entries. This does not usually entail changes in the order of the fields of resource data structures, but does entail the need for some padding between fields.

The single exception to this rule is the font and fontdir structures. The reason for the exception is that these two structures are copied directly from other files, and are not used by RC.

General information

The resource file is created by the resource compiler (RC) while parsing the resource script file (.RC) and including any other resource data files (eg. .ICO, .CUR, .BMP, .FNT). The resource file contains all information necessary to build the resource table in the executable image. The main purpose of the resource file is to speed the edit-compile-link cycle by not always forcing resource to be recompiled.

There are currently about a dozen pre-defined resource types. These include Menus, Dialogs, Accelerators, Strings, Icons, Cursors, Bitmaps, Fonts and Version. These resources are used by the Windows system to define the appearance of the application window. The resource script allows the application writer to represent these features in an easily editable form. Other type ranges are reserved for use by the application for application-specific data. No attempt is made by the resource compiler to modify this user-defined data from 16-bit to 32-bit format.

The executable image file for Windows 32 is not a Segmented image. In the 16-bit executable image file, each resource was placed into a separate segment in the image file. The Windows 32 image file places all resources into a single Object or section. The Windows 32 image file also provides a binary-sorted resource table that allows fast lookup of a particular resource, rather than a table that must be searched linearly, as in the 16-bit image file. Because this Windows 32 image file format is more complex that the Windows 16 format, making it harder to update directly, the Windows 32 API provides methods of modifying the resource data directly.

The CVTRES conversion utility that converts the resource file into a COFF object creates the resource table. This table contains three directories, indexed by Type, Name and Language, in that order. The Type and Name directories consist of two parts: the part dedicated to resources whose types or names are represented by strings, an those represented by ordinal WORD values. Because the use of strings as resource type and name identifiers takes considerably more room than ordinal identifiers, Microsoft recommends that they not be used.

Note that, as all strings in a resource file (including the strings used to identify the type and name of resources) are UNICODE, the corresponding strings in the program that are being passed to LoadBitmap, etc., must also be UNICODE (only if the application is using the UNICODE set of apis rather than the ASCII set). This is facilitated by use of the TEXT macro provided in winnt.h.

The third level, language, provides the capability for the application developer to ship a single executable image that supports more than one language. For instance, one image providing French, French-Canadian and French-Belgium could be easily shipped in one image file. An application could also be shipped with support for all languages supported by the UNICODE standard, although this would make the image prohibitively large. However, since the system provides facilities to modify the resources within an image, a setup program could customize the application's image file for each specific user, eliminating unneeded language support to save space in the image file.

New statements

Several new statements have been added that the Windows 32 resource compiler processes.

New Button statements

These statements allow the application developer the same freedom of expression that the PUSHBUTTON, DEFPUSHBUTTON, etc., statements do, and correspond to the appropriate button style.

They all have syntax identical to that of PUSHBUTTON, etc.

AUTO3STATE

Allows declaration of an AUTO3STATE button.

AUTOCHECKBOX

Allows declaration of an AUTOCHECKBOX button.

AUTORADIOBUTTON

Allows declaration of an AUTORADIOBUTTON button.

PUSHBOX

Allows declaration of a PUSHBOX button.

STATE3

Allows declaration of a 3STATE button (the 3 is at the end for syntax purposes).

USERBUTTON

Allows declaration of a USERBUTTON user-defined button.

EXSTYLE statement

This statement allows the application developer to designate one of the extended (WS_EX_xxx) styles for a dialog or control window. There are three methods, depending upon what is needed.

It may be placed just below the DIALOG statement to apply to the dialog window (like the CAPTION or STYLE statements). 

EXSTYLE <flags>

It may be placed on the DIALOG statement with the memory flags. 

FOOBAR DIALOG [MemFlags...] [EXSTYLE=<flags>] x, y, dx, dy

It may also be placed on the individual CONTROL, PUSHBUTTON, LTEXT, etc. statements at the end of the statement. 

AUTOCHECKBOX "autocheckbox", id, x, y, dx, dy 
[styleflags][exstyleflags]

CHARACTERISTICS statement

This statement allows the application developer to specify information about the resource that may be of use to tools that read and write resource files. It has no significance to the system and is not stored in the image file. 

CHARACTERISTICS <user defined DWORD value>

VERSION statement

This statement is intended to allow the application to specify a version number of the resource in the resource file (for those tools that read and write resource files.) It has no significance to the system and is not stored in the image file. 

VERSION <user defined DWORD value>

LANGUAGE statement

The LANGUAGE statement is used to specify the language the resource file, or section of resource file, is written in. It may be placed anywhere within the resource script file that a single-line statement (such as ICON, CURSOR, BITMAP) may be placed. The scope of the language specified by a LANGUAGE statement is from that point in the script file to the next LANGUAGE statement, or the end of the file. 

LANGUAGE <majornumber>,<minornumber>

where <majornumber> represents the language id, and <minornumber> the sub-language identifiers. The values specified in winnt.h should be used.

The LANGUAGE statement may also be placed before the BEGIN statement for MENU, DIALOG, STRINGTABLE, ACCELERATOR and RCDATA resources, along with other optional statements like CAPTION, STYLE, etc. If the statement is placed here, it's scope is limited to the resource being defined.

MESSAGETABLE statement

The MESSAGETABLE statement is used to include a message table. A message table is a special-purpose string table that is used to contain error or informational messages, and may contain formatting information. The format is: 

<nameid> MESSAGETABLE <filename>

Additional syntax for UNICODE strings

Quoted strings in the resource script are treated as ASCII strings (in the current codepage) unless preceeded by a "L" or "l" character, eg: 

L"This is a Unicode string"

Declaring a string UNICODE with this syntax has two effects. In a RCDATA statement, this causes the compiler to store the string as UNICODE rather than ASCII. In all cases using this syntax, escapes embedded within the string become UNICODE codepoint escapes resulting in a 16-bit UNICODE character, eg: 

L"This is the first line,\x2028and this is the second"

where the 0x2028 UNICODE character is the Line Separator character. Any UNICODE character may be embedded within any resource script string in this manner.

Resource header format

The general format of the entire file is simply a number of resource file entries concatenated together. Each resource contains the information about a single resource, such as a dialog or a string table.

Each entry consists of a resource header followed by the data for that resource. A resource header (which is DWORD aligned) is composed of four elements: two dwords containing the size of the header and the size of the resource data, the resource type, the resource name, and additional resource information. The data for the resource follows the resource header and is specific to each particular type of resource.

DataSize

This field gives the size of the data that follows the header, not including any file padding between this resource and any resource that follows this resource in the resource file.

HeaderSize

The HeaderSize field gives the size of the resource header structure that follows.

Type

The type field can either be a number or a null-terminated UNICODE string specifying the name of the type. This variable kind of type is known as a `Name or Ordinal' field, and is used in most places in a resource file where an ID may appear.

The first WORD of a Name or Ordinal field identifies whether the field is a number or a string. If the first WORD is 0xffff (an invalid UNICODE character), then the following WORD of information is the type number. Otherwise, the field is specified by a UNICODE string.

If the type field is a number, then the number specifies a standard or user-defined resource type. All standard Windows resource types have been assigned numbers, which are listed below. This list is taken from the header file used to make RC and contains the type number of the various resource types: 

/* Predefined resource types */ 
#define    RT_NEWRESOURCE      0x2000 
#define    RT_ERROR            0x7fff 
#define    RT_CURSOR           1 
#define    RT_BITMAP           2 
#define    RT_ICON             3 
#define    RT_MENU             4 
#define    RT_DIALOG           5 
#define    RT_STRING           6 
#define    RT_FONTDIR          7 
#define    RT_FONT             8 
#define    RT_ACCELERATORS     9 
#define    RT_RCDATA           10 
#define    RT_MESSAGETABLE     11 
#define    RT_GROUP_CURSOR     12 
#define    RT_GROUP_ICON       14 
#define    RT_VERSION          16 
#define    RT_NEWBITMAP        (RT_BITMAP|RT_NEWRESOURCE) 
#define    RT_NEWMENU          (RT_MENU|RT_NEWRESOURCE) 
#define    RT_NEWDIALOG        (RT_DIALOG|RT_NEWRESOURCE)

If the type field is a string, then the type is a user-defined type.

Names

A name identifies the particular resource. A name (like a type) may be a number or a string, and they are distinguished in the same way as numbers and strings are distinguished in the type field.

Note that no padding (for DWORD alignment) is needed between the Type and Name fields, as they contain only WORD data and hence the Name field will always be properly aligned. However, there may need to be a WORD of padding after the Name field to align the rest of the header on DWORD boundaries.

Additional header information

The additional information contains more information about the particular resource data, including size and language ID. The structure of the Header, plus it's additional information is as follows: 

struct tagResource { 
  DWORD  DataSize;           // size of data without header 
  DWORD  HeaderSize;         // Length of the additional header 
  [Ordinal or name TYPE]     // type identifier, id or string 
  [Ordinal or name NAME]     // name identifier, id or string 
  DWORD  DataVersion;        // predefined resource data version 
  WORD   MemoryFlags;        // state of the resource 
  WORD   LanguageId;         // UNICODE support for NLS 
  DWORD  Version;            // Version of the resource data 
  DWORD  Characteristics;    // Characteristics of the data 
} ;

The additional information structure will always begin on a DWORD boundary within the resource file, which may require adding some padding in between the name field and the ResAdditional structure.

DataVersion

The DataVersion field determines the format of the information within the resource header that follows. This may be used in the future to allow additional information to be entered into the predefined formats.

MemoryFlags

The field wMemoryFlags contains flags telling the state of a given resource. These attributes are given to a given resource by modifiers in the .RC script. The script identifiers inject the following flag values: 

#define    MOVEABLE            0x0010 
#define    FIXED               ~MOVEABLE 
#define    PURE                0x0020 
#define    IMPURE              ~PURE 
#define    PRELOAD             0x0040 
#define    LOADONCALL          ~PRELOAD 
#define    DISCARDABLE         0x1000

The resource compiler for NT always ignores the setting of the MOVEABLE, IMPURE, and PRELOAD flags.

LanguageId

The language ID is included in each resource to specify the language that the strings are written with when they need to be translated back to a single byte strings. As well, there may be multiple resources of exactly the same type and name which differ in only the language of the strings within the resources.

The language IDs are documented in Appendix A of the NLS specification, or in winnt.h. The language of a resource or set of resources is specified by the LANGUAGE statement.

Version and Characteristics

Currently, there is space in the resource file format for version and characteristic information of the resource. These values can be set by the resource compiler by using the VERSION or CHARACTERISTICS statements.

Differentiating 16 and 32-bit resource files

Because it might be desirable for an ISV's tool that reads and writes resource files to be able to read either the older Windows 16 format files and the new Windows 32 format, Microsoft has devised a method to do this using illegal type and name ordinal numbers.

The method involved is to place an illegal resource in the resource file. The following eight bytes were chosen: 

0x00 0x00 0x00 0x00 0x20 0x00 0x00 0x00

Assume that it is a 16-bit file. In that case, the Type is illegal since the first 0x00 says string, but a zero-length string is an illegal string. This, then is an illegal 16-bit resource header, indicating that the file is a 32-bit file.

Assume that it is a 32-bit file. Given that, the size of the data is zero, which surely will never be the case.

The Windows 32 resource compiler prefaces each 32-bit resource file with this string of data (followed by an additional data structure describing a zero-length resource with 0 ordinal type and 0 ordinal name), allowing differentiation of 16 and 32-bit resource files. Any tools reading resource files should ignore this resource.

File alignment

Because it is sometimes useful to separate resources into several scripts and then concatenate them after compiling the resource files separately, it is necessary to specify that resource files are padded to a dword size. If this padding were not included, it could result in the first resource of the second and/or subsequent resource files not aligning upon a dword boundary.

Resource data format

For any of the pre-defined data types, all structures are DWORD aligned, including the bitmap, icon, and font header structures. As well, the data will always begin on a DWORD boundary.

Version resources

Version resources are used to record the version of the application using the resource file. Version resources contain a fixed amount of information. The structure of the version resource is as follows: 

typedef struct tagVS_FIXEDFILEINFO { 
  DWORD  dwSignature;        // e.g.  0xfeef04bd 
  DWORD  dwStrucVersion;     // e.g.  0x00000042 = "0.42" 
  DWORD  dwFileVersionMS;    // e.g.  0x00030075 = "3.75" 
  DWORD  dwFileVersionLS;    // e.g.  0x00000031 = "0.31" 
  DWORD  dwProductVersionMS; // e.g.  0x00030010 = "3.10" 
  DWORD  dwProductVersionLS; // e.g.  0x00000031 = "0.31" 
  DWORD  dwFileFlagsMask;    // = 0x3F for version "0.42" 
  DWORD  dwFileFlags;        // e.g.  VFF_DEBUG | VFF_PRERELEASE 
  DWORD  dwFileOS;           // e.g.  VOS_DOS_WINDOWS16 
  DWORD  dwFileType;         // e.g.  VFT_DRIVER 
  DWORD  dwFileSubtype;      // e.g.  VFT2_DRV_KEYBOARD 
  DWORD  dwFileDateMS;       // e.g.  0 
  DWORD  dwFileDateLS;       // e.g.  0 
} VS_FIXEDFILEINFO;

Icon resources

The ICON statement in the .RC script does not create a single resource object, but creates a group of resources. This allows Windows programs a degree of device-independence through the use of different pixel bitmaps on hardware configurations with differing capabilities. Icons, most often designed for differing numbers of pixel planes and pixel counts, are grouped and treated by Windows as a single resource. In the .RES and .EXE files, however, they are stored as a group of resources. These groups are stored in a .RES file with the components first (in this case the different icons [type 3]) and a group header following (Type 14). The group header contains the information necessary to allow Windows to select the proper icon to display.

The components have the following structure: 

[Resource header (type = 3)] 

[DIB Header] 
[Color DIBits of icon XOR mask] 
[Monochrome DIBits of AND mask]

Each component is given an ordinal ID that is unique from all other icon components.

The Device Independent Bitmap (DIB) header's fields represent the masks' information separately with two exceptions. First, the height field represents both the XOR and AND masks. Before converting the two DIBs to Device Dependent Bitmaps (DDB), the height should be divided by two. The masks are always the same size and are one-half the size given in the DIB header. Second, the number of bits per pixel and bit count refer to the XOR mask. The AND mask is always monochrome and should be interpreted as having one plane and one bit per pixel. Before using an icon with Windows refer to the SDK reference materials for more information on DIBs. Since the format of an icon component closely resembles the format of the .ICO file, the documentation in section 9.2 of the Windows SDK Reference is useful. DDBs should not be used for Windows 32 applications.

The group header is described here: 

[Resource header (type = 14)] 

struct IconHeader { 
  WORD   wReserved;          // Currently zero 
  WORD   wType;              // 1 for icons 
  WORD   wCount;             // Number of components 
  WORD   padding;            // filler for DWORD alignment 
};

The next portion is repeated for each component resource: 

struct ResourceDirectory { 
  BYTE   bWidth; 
  BYTE   bHeight; 
  BYTE   bColorCount; 
  BYTE   bReserved; 
  WORD   wPlanes; 
  WORD   wBitCount; 
  DWORD  lBytesInRes; 
  WORD   wNameOrdinal;       // Points to component 
  WORD   padding;            // filler for DWORD alignment 
};

Notice that the group header consists of a fixed header and data that repeats for each group component. Both of these parts are fixed length allowing for random access of the group component information.

This group header contains all of the data from the .ICO header and from the individual resource descriptors.

Menu resources

Menu resources are composed of a menu header followed by a sequential list of menu items. There are two types of menu items: popups and normal menu items. The MENUITEM SEPARATOR is a special case of a normal menu item with an empty name, zero ID, and zero flags. The format for these types is shown here: 

[Resource header (type = 4)] 

struct MenuHeader { 
  WORD   wVersion;           // Currently zero 
  WORD   cbHeaderSize;       // Also zero 
};

These next items are repeated for every menu item.

Popup menu items (signalled by fItemFlags & POPUP): 

struct PopupMenuItem { 
  WORD   fItemFlags; 
  WCHAR  szItemText[]; 
};

Normal menu items (signalled by !(fItemFlags & POPUP)): 

struct NormalMenuItem { 
  WORD   fItemFlags; 
  WORD   wMenuID; 
  WCHAR  szItemText[]; 
};

The wVersion and cbHeaderSize structure members identify the version of the menu template. They are both zero for Windows 3.0 but may be incremented with future changes to the menu template.

The WORD fItemFlags is a set of flags describing the menu item. If the POPUP bit is set, the item is a POPUP. Otherwise, it is a normal menu component. There are several other flag bits that may be set. Their values are as follows: 

#define    GRAYED         0x0001   // 'GRAYED' keyword 
#define    INACTIVE       0x0002   // 'INACTIVE' keyword 
#define    BITMAP         0x0004   // 'BITMAP' keyword 
#define    OWNERDRAW      0x0100   // 'OWNERDRAW' keyword 
#define    CHECKED        0x0008   // 'CHECKED' keyword 
#define    POPUP          0x0010   // Used internally 
#define    MENUBARBREAK   0x0020   // 'MENUBARBREAK' keyword 
#define    MENUBREAK      0x0040   // 'MENUBREAK' keyword 
#define    ENDMENU        0x0080   // Used internally

The fItemFlags portion of the last menu item in a given POPUP is flagged by OR'ing it with ENDMENU. It is important to note that since popups can be nested, there may be multiple levels of items with ENDMENU set. When menus are nested, the items are inserted sequentially. A program can traverse this hierarchy by checking for the item with the ENDMENU flag set.

Dialog Box resources

A dialog box is contained in a single resource and has a header and a portion repeated for each control in the dialog box. The header is as follows: 

[Resource header (type = 5)] 

struct DialogBoxHeader { 
  DWORD  lStyle; 
  DWORD  lExtendedStyle;     // new for NT 
  WORD   NumberOfItems; 
  WORD   x; 
  WORD   y; 
  WORD   cx; 
  WORD   cy; 
  [Name or Ordinal] MenuName; 
  [Name or Ordinal] ClassName; 
  WCHAR  szCaption[]; 
  WORD   wPointSize;         // Only here if FONT set for dialog 
  WCHAR  szFontName[];       // This too 
};

The item DWORD lStyle is a standard window style composed of flags found in WINDOWS.H. The default style for a dialog box is: 

WS_POPUP | WS_BORDER | WS_SYSMENU

The lExtendedStyle DWORD is used to specify the extended window style flags. If an extended style is specified on the DIALOG statement, or with the other optional modifier statements, this DWORD is set to that value.

The items marked `Name or Ordinal' are the same format used throughout the resource file (most notably in each resource header) to store a name or an ordinal ID. As before, if the first byte is an 0xffff, the next two bytes contain an ordinal ID. Otherwise, the first 1 or more WORDS contain a null-terminated string. An empty string is represented by a single WORD zero in the first location.

The WORD wPointSize and WCHAR szFontName entries are present if the FONT statement was included for the dialog box. This can be detected by checking the entry lStyle. if lStyle & DS_SETFONT (DS_SETFONT = 0x40), then these entries will be present.

The data for each control starts on a DWORD boundary (which may require some padding from the previous control), and its format is as follows: 

struct ControlData { 
  DWORD  lStyle; 
  DWORD  lExtendedStyle; 
  WORD   x; 
  WORD   y; 
  WORD   cx; 
  WORD   cy; 
  WORD   wId; 
  [Name or Ordinal] ClassId; 
  [Name or Ordinal] Text; 
  WORD   nExtraStuff; 
};

As before, the item DWORD lStyle is a standard window style composed of the flags found in WINDOWS.H. The type of control is determined by the class. The class is either given by a zero-terminated string, or in the case of many common Windows classes, is given a one word code to save space and speed processing. Because UNICODE allows 0x8000 as a legal character, the ordinal classes are prefaced with a of 0xFFFF, similar to the ordinal Type and Name fields. The one word classes are listed here: 

#define    BUTTON              0x8000 
#define    EDIT                0x8100 
#define    STATIC              0x8200 
#define    LISTBOX             0x8300 
#define    SCROLLBAR           0x8400 
#define    COMBOBOX            0x8500

The lExtendedStyle DWORD is used to specify the extended style flags to be used for this control. The extended style flags are placed at the end of the CONTROL (or other control statements) statement following the coordinates

The extra information at the end of the control data structure is currently not used, but is intended for extra information that may be needed for menu items in the future. Usually it is zero length.

The various statements used in a dialog script are all mapped to these classes along with certain modifying styles. The values for these styles can be found in WINDOWS.H. All dialog controls have the default styles of WS_CHILD and WS_VISIBLE. A list of the default styles used to make the script statements follows: 

Statement       Default Class  Default Styles 
CONTROL         None           WS_CHILD|WS_VISIBLE 
LTEXT           STATIC         ES_LEFT 
RTEXT           STATIC         ES_RIGHT 
CTEXT           STATIC         ES_CENTER 
LISTBOX         LISTBOX        WS_BORDER | LBS_NOTIFY 
CHECKBOX        BUTTON         BS_CHECKBOX | WS_TABSTOP 
PUSHBUTTON      BUTTON         BS_PUSHBUTTON | WS_TABSTOP 
GROUPBOX        BUTTON         BS_GROUPBOX 
DEFPUSHBUTTON   BUTTON         BS_DEFPUSHBUTTON | WS_TABSTOP 
RADIOBUTTON     BUTTON         BS_RADIOBUTTON 
AUTOCHECKBOX    BUTTON         BS_AUTOCHECKBOX 
AUTO3STATE      BUTTON         BS_AUTO3STATE 
AUTORADIOBUTTON BUTTON         BS_AUTORADIOBUTTON 
PUSHBOX         BUTTON         BS_PUSHBOX 
STATE3          BUTTON         BS_3STATE 
EDITTEXT        EDIT           ES_LEFT|WS_BORDER|WS_TABSTOP 
COMBOBOX        COMBOBOX       None 
ICON            STATIC         SS_ICON 
SCROLLBAR       SCROLLBAR      None

The control text is stored in the `Name or Ordinal' format described in detail above.

Cursor resources

Cursor resources are very much like icon resources. They are formed in groups with the components preceding the header. This header also employs a fixed-length component index that allows random access of the individual components. The structure of the cursor header is as follows: 

[Resource header (type = 12)] 

struct CursorHeader { 
  WORD   wReserved;          // Currently zero 
  WORD   wType;              // 2 for cursors 
  WORD   cwCount;            // Number of components 
  WORD   padding;            // filler for DWORD alignment 
};

The next portion is repeated for each component resource, and starts on a DWORD boundary. 

struct ResourceDirectory { 
  WORD   wWidth; 
  WORD   wHeight; 
  WORD   wPlanes; 
  WORD   wBitCount; 
  DWORD  lBytesInRes; 
  WORD   wNameOrdinal;       // Points to component 
  WORD   padding;            // filler for DWORD alignment 
};

Each cursor component is also similar to each icon component. There is, however, one significant difference between the two: cursors have the concept of a `hotspot' where icons do not. Here is the component structure: 

[Resource header (Type = 1)] 

struct CursorComponent { 
  short  xHotspot; 
  short  yHotspot; 
} 
[Monochrome XOR mask] 
[Monochrome AND mask]

These masks are bitmaps copied from the .CUR file. The main difference from icons in this regard is that cursors do not have color DIBs used for XOR masks like cursors. Although the bitmaps are monochrome and do not have DIB headers or color tables, the bits are still in DIB format with respect to alignment and direction. See the SDK Reference for more information on DIB formats.

Bitmap resources

Windows 32 can read two types of device-independent bitmaps. The normal type of DIB is the Windows 3.0 DIB format. The other type of DIB is that used for OS/2 versions 1.1 and 1.2. The bitmap resource consists of a single device-independent bitmap and accordingly, this DIB can be of either format. The two DIBs are distinguished by their header structures. They both have the size of their respective structures as the first DWORD in the header. Both these structures are documented in the Windows SDK Reference Version 3.0 volume 2, section 7. The header structure for the normal DIB is BITMAPINFOHEADER while the OS/2 DIB header is called BITMAPCOREHEADER. The correct size (as a DWORD) must be in the first entry of the structure. 

[Normal resource header (type = 2)] 

[BITMAPINFOHEADER or BITMAPCOREHEADER] 
[Color table if not 24 bits per pixel] 
[Packed-pixel bitmap]

Note that the color table is optional. All but 24 bit color bitmaps have a color table attached next. This table's length can be computed by 2#BitsPerPixel * 3 bytes for OS/2 bitmaps or 2#BitsPerPixel * 4 bytes for Windows bitmaps. The bitmap image data is placed immediately following the color table.

Note that the bitmap file has an unaligned header structure (BITMAPFILEHEADER structure). This header is not, however, stored in the resource file, as it serves only to identify the type of file (DIB or DDB).

Font and Font Directory resources

Font resources are different from the other types of resources in that they are not added to the resources of a specific application program. Font resources are added to .EXE files that are renamed to be .FON files. These files are libraries as opposed to applications.

Font resources use a resource group structure. Individual fonts are the components of a font group. Each component is defined by a FONT statement in the .RC file. The group header follows all components and contains all information necessary to access a specific font. The format of a font component resource is as follows: 

[Normal resource header (type = 8)] 

[Complete contents of the .FNT file follow as the resource body - 
- See the Windows SDK Reference for the format of the .FNT file]

The group header for the fonts is normally last in the .RES file. Note that unlike cursor and icon groups, the font group need not be contiguous in the .RES file. Font declarations may be placed in the .RC file mixed with other resource declarations. The group header is added automatically by RC at the end of the .RES file. Programs generating .RES files must add the FONTDIR entry manually. The group header has the following structure: 

[Normal resource header (type = 7)] 

WORD NumberOfFonts; // Total number in .RES file

The remaining data is repeated for every font in the .RES file. 

WORD fontOrdinal; 
struct FontDirEntry { 
  WORD   dfVersion; 
  DWORD  dfSize; 
  char   dfCopyright[60]; 
  WORD   dfType; 
  WORD   dfPoints; 
  WORD   dfVertRes; 
  WORD   dfHorizRes; 
  WORD   dfAscent; 
  WORD   dfInternalLeading; 
  WORD   dfExternalLeading; 
  BYTE   dfItalic; 
  BYTE   dfUnderline; 
  BYTE   dfStrikeOut; 
  WORD   dfWeight; 
  BYTE   dfCharSet; 
  WORD   dfPixWidth; 
  WORD   dfPixHeight; 
  BYTE   dfPitchAndFamily; 
  WORD   dfAvgWidth; 
  WORD   dfMaxWidth; 
  BYTE   dfFirstChar; 
  BYTE   dfLastChar; 
  BYTE   dfDefaultChar; 
  BYTE   dfBreakChar; 
  WORD   dfWidthBytes; 
  DWORD  dfDevice; 
  DWORD  dfFace; 
  DWORD  dfReserved; 
  char   szDeviceName[]; 
  char   szFaceName[]; 
};

String Table resources

These tables are constructed in blocks of 16 strings. The organization of these blocks of 16 is determined by the IDs given to the various strings. The lowest four bits of the ID determine a string's position in the block. The upper twelve bits determine which block the string is in. Each block of 16 strings is stored as one resource entry. Each string or error table resource block is stored as follows: 

[Normal resource header (type = 6 for strings)] 

[Block of 16 strings.  The strings are Pascal style with a WORD 
length preceding the string.  16 strings are always written, even 
if not all slots are full.  Any slots in the block with no string 
have a zero WORD for the length.]

It is important to note that the various blocks need not be written out in numerical order in the resource file. Each block is assigned an ordinal ID. This ID is the high 12 bits of the string IDs in the block plus one (ordinal IDs can't be zero). The blocks are written to the .RES file in the order the blocks are encountered in the .RC file, while the CVTRES utility will cause them to become ordered in the COFF object, and hence the image file.

Accelerator Table resources

An accelerator table is stored as a single resource. Multiple accelerator tables are also allowed. The format of an accelerator table is very simple. No header for the table is used. Each entry in the table has a single four word entry. The last entry in the table is flaged by the hex value 0x0080 (fFlags |= 0x0080). Since all entries are fixed length, random access can be done because the number of elements in the table can be computed by dividing the length of the resource by eight. Here is the structure of the table entries: 

[Normal resource header (type = 9)]

The following structure is repeated for all accelerator table entries. 

struct AccelTableEntry { 
  WORD   fFlags; 
  WORD   wAscii; 
  WORD   wId; 
  WORD   padding; 
};

User Defined Resources and RCDATA

RC allows the programmer to include resources not defined in Windows. The user may choose a name not defined as a standard type and use it to include data that is to be used as a resource. This data may be taken from an external file or may be placed between BEGIN and END statements. As an option, the programmer can define the type as RCDATA with the same results.

As might be imagined, the format of this resource is very simple because the resource compiler knows nothing about the logical structure of the data. Here is the organization: 

[Normal resource header (type = 10 for RCDATA, named types 
represent user-defined types)] 

[The data from the BEGIN ...  END or from the external file is 
included without translation into the .RES file]

Name Table and Error Table resources

Name tables and error resources are no longer supported in the Windows binary resource file format.

Version resources

Version resources specify information that can be used by setup programs to discover which of several versions of a program or dynamic link library to install into the system. There is also a set of api's to query the version resources. There are three major types of information stored in version resources: the main information in a VS_FIXEDFILEINFO structure, Language information data in a variable file information structure (VarFileInfo), and user defined string information in StringFileInfo structures. For Windows 32, the strings within the version information resource is stored in Unicode, providing localization of the resoruces. Each block of information is dword aligned.

The structure of a version resource is depicted by the VS_VERSION_INFO structure. 

VS_VERSION_INFO { 
  WORD wLength;             /* Length of the version resource */ 
  WORD wValueLength;        /* Length of the value field for this block */ 
  WORD wType;               /* type of information:  1==string, 0==binary */ 
  WCHAR szKey[];            /* Unicode string KEY field */ 
  [WORD Padding1;]          /* possible word of padding */ 
  VS_FIXEDFILEINFO Value;   /* Fixed File Info Structure */ 
  BYTE Children[];      /* position of VarFileInfo or StringFileInfo data */ 
};

The Fixed File Info structure contains basic information about the version, including version numbers for the product and file, and type of the file. 

typedef struct tagVS_FIXEDFILEINFO { 
  DWORD dwSignature;        /* signature - always 0xfeef04bd */ 
  DWORD dwStrucVersion;     /* structure version - currently 0 */ 
  DWORD dwFileVersionMS;    /* Most Significant file version dword */ 
  DWORD dwFileVersionLS;    /* Least Significant file version dword */ 
  DWORD dwProductVersionMS; /* Most Significant product version */ 
  DWORD dwProductVersionLS; /* Least Significant product version */ 
  DWORD dwFileFlagMask;     /* file flag mask */ 
  DWORD dwFileFlags;        /*  debug/retail/prerelease/... */ 
  DWORD dwFileOS;           /* OS type.  Will always be Windows32 value */ 
  DWORD dwFileType;         /* Type of file (dll/exe/drv/... )*/ 
  DWORD dwFileSubtype;      /* file subtype */ 
  DWORD dwFileDateMS;       /* Most Significant part of date */ 
  DWORD dwFileDateLS;       /* Least Significant part of date */ 
} VS_FIXEDFILEINFO;

The user defined string information is contained within the StringFileInfo structure, which is a set of two strings: the key and the information itself. 

StringFileInfo { 
  WCHAR       szKey[];      /* Unicode "StringFileInfo" */ 
  [WORD        padding;]    /* possible padding */ 
  StringTable Children[]; 
}; 

StringTable { 
  WCHAR      szKey[];   /* Unicode string denoting the language - 8 bytes */ 
  String Children[];    /* array of children String structures */ 
} 

String { 
  WCHAR   szKey[];          /* arbitrary Unicode encoded KEY string */ 
                            /* note that there is a list of pre-defined keys */ 
  [WORD   padding;]         /* possible padding */ 
  WCHAR Value[];            /* Unicode-encoded value for KEY */ 
} String;

The variable file info (VarFileInfo) block contains a list of languages supported by this version of the application/dll. 

VarFileInfo { 
  WCHAR szKey[];            /* Unicode "VarFileInfo" */ 
  [WORD padding;];          /* possible padding */ 
  Var        Children[];    /* children array */ 
}; 

Var { 
  WCHAR szKey[];       /* Unicode "Translation" (or other user key) */ 
  [WORD padding;]      /* possible padding */ 
  WORD  Value[];       /* one or more values, normally language id's */ 
};

Messagetable resources

A message table is a resource that contains formatted text that is used to display an error message or messagebox. It has taken the place of the error table resource (which was never used). The data consists of a MESSAGE_RESOURCE_DATA structure, which contains one or more MESSAGE_RESOURCE_BLOCKS, which in turn may consist of one or more MESSAGE_RESOURCE_ENTRY structures. The structure is similar to that of the STRINGTABLE resource. 

typedef struct _MESSAGE_RESOURCE_DATA { 
  ULONG NumberOfBlocks; 
  MESSAGE_RESOURCE_BLOCK Blocks[]; 
} MESSAGE_RESOURCE_DATA, *PMESSAGE_RESOURCE_DATA; 

typedef struct _MESSAGE_RESOURCE_BLOCK { 
  ULONG LowId; 
  ULONG HighId; 
  ULONG OffsetToEntries; 
} MESSAGE_RESOURCE_BLOCK, *PMESSAGE_RESOURCE_BLOCK; 

typedef struct _MESSAGE_RESOURCE_ENTRY { 
  USHORT Length; 
  USHORT Flags; 
  UCHAR Text[]; 
} MESSAGE_RESOURCE_ENTRY, *PMESSAGE_RESOURCE_ENTRY;

If the Flags USHORT is MESSAGE_RESOURCE_UNICODE (value 0x0001), the string is encoded in UNICODE rather than ASCII in the current codepage.

Retrieved from "http://hashvb.earlsoft.co.uk/index.php?title=Win32_binary_resource_formats&oldid=2373"