Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c083 / 20.ddi / DOC.PAK / RESFMT.TXT < prev next >

Wrap

Text File | 1993-07-24 | 45.3 KB | 1,135 lines

Win32 Binary Resource Formats Author: Floyd Rogers Preface 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 1. Overview 1.1 Comparison to Windows 16 (Win 3.0/3.1) 1.2 Strings in UNICODE 1.3 DWORD Alignment 2. General information 2.1 New Statements 2.1.1 New Button statements 2.1.1.1 AUTO3STATE 2.1.1.2 AUTOCHECKBOX 2.1.1.3 AUTORADIOBUTTON 2.1.1.4 PUSHBOX 2.1.1.5 STATE3 (3STATE) 2.1.1.6 USERBUTTON 2.1.2 EXSTYLE statement 2.1.3 CHARACTERISTICS statement 2.1.4 VERSION statement 2.1.5 LANGUAGE statement 2.1.6 MESSAGETABLE statement 2.1.6 Additional syntax for UNICODE strings. 3. Resource Header Format 3.1 DataSize 3.2 HeaderSize 3.3 Type 3.4 Names 3.5 Additional Resource Header Information 3.5.1 DataVersion 3.5.2 MemoryFlags 3.5.3 LanguageId 3.5.4 Version and Characteristics 3.6 Differentiating 16 and 32-bit resource files 3.7 File alignment 4. Resource Data Format 4.1 Version Resources 4.2 Icon Resources 4.3 Menu Resources 4.4 Dialog Box Resources 4.5 Cursor Resources 4.6 Bitmap Resources 4.7 Font and Font Directory Resources 4.8 String Table Resources 4.9 Accelerator Table Resources 4.10 User Defined Resources and RCDATA 4.11 Name Table and Error Table Resources 4.12 Version Resourses 4.13 Messagetable Resources 5. Revision History 1. 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. 1.1 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. 1.2 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. 1.3 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. 2. 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. 2.1 New statements Several new statements have been added that the Windows 32 resource compiler processes. 2.1.1 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. 2.1.1.1 AUTO3STATE Allows declaration of an AUTO3STATE button. 2.1.1.2 AUTOCHECKBOX Allows declaration of an AUTOCHECKBOX button. 2.1.1.3 AUTORADIOBUTTON Allows declaration of an AUTORADIOBUTTON button. 2.1.1.5 PUSHBOX Allows declaration of a PUSHBOX button. 2.1.1.6 STATE3 Allows declaration of a 3STATE button (the 3 is at the end for syntax purposes). 2.1.1.7 USERBUTTON Allows declaration of a USERBUTTON user-defined button. 2.1.2 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] 2.1.3 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> 2.1.4 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> 2.1.5 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. 2.1.6 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> 2.1.7 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. 3. 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. 3.1 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. 3.2 HeaderSize The HeaderSize field gives the size of the resource header structure that follows. 3.3 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. 3.4 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. 3.5 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. 3.5.1 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. 3.5.2 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. 3.5.3 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. 3.5.4 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. 3.6 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. 3.7 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. 4. 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. 4.1 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; 4.2 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. 4.3 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. 4.4 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. 4.5 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. 4.6 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). 4.7 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[]; }; 4.8 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. 4.9 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; }; 4.10 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] 4.11 Name Table and Error Table Resources Name tables and error resources are no longer supported in the Windows binary resource file format. 4.12 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 */ }; 4.13 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.