This chapter provides the reference information for defining your own XML-based format for resources that are not already defined. This custom resource defines both the XML representation of the logical resource data as well as the physical resource format of the resulting binary data.
You can use the PalmRC
resource compiler to compile your custom resource data descriptions just as easily as using the pre-defined resource formats. In addition, the custom resource description can be used by other tools such as the Generate XRD resource decompiler.
This chapter consists of the following sections:
- "Reference Syntax" describes the XML format you use to define and refer to custom resources.
- "Custom Enumeration Description" describes the reference format for custom enum types.
- "Custom Structure Description" describes the reference format for custom struct types.
- "Custom Resource Description" describes the reference format for custom resource types.
- "Name Format Requirements" describes format requirements for names used in custom resources.
- "Data Model Objects" describes the additional data model objects you can use in your custom resource descriptions.
Reference Syntax
This section describes the XML syntax that you use to define custom types and that you use to refer to a custom type description.
Palm OS Custom Resource Type Description
Purpose
Use the Palm OS custom resource type element to define a custom resource type. There are three types that you can define:
- A custom enumeration description (see "Custom Enumeration Description" for more information)
- A custom structure description (see "Custom Structure Description" for more information)
- A custom resource description (see "Custom Resource Description" for more information)
Start Tag
<PALMOS_CUSTOM_RESOURCE_TYPES>
Child Elements
-
<DEFINE_ENUM_TYPE NAME=quoted_text> enum_defn
</DEFINE_ENUM_TYPE> - Defines a custom enumeration description, as described in "Custom Enumeration Description."
-
<DEFINE_STRUCT_TYPE NAME=quoted_text> struct_defn
</DEFINE_STRUCT_TYPE> - Defines a custom structure description, as described in "Custom Structure Description."
-
<DEFINE_RESOURCE_TYPE NAME=quoted_text> resource_defn </DEFINE_RESOURCE_TYPE>
- Defines a custom resource description, as described in "Custom Resource Description."
End Tag
Example
<PALMOS_CUSTOM_RESOURCE_TYPES> <DEFINE_STRUCT_TYPE NAME="POINT_TYPE"> <STRUCT_ITEMS> <FIELD_SINT16> <FIELD_NAME> "X" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> <FIELD_SINT16> <FIELD_NAME> "Y" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> </STRUCT_ITEMS> </DEFINE_STRUCT_TYPE> </PALMOS_CUSTOM_RESOURCE_TYPES> <PALMOS_CUSTOM_RESOURCE_TYPES> <DEFINE_RESOURCE_TYPE NAME="POINT_LIST"> <RES_TYPE> 'PLst' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <ARRAY_COUNT_UINT16> <ARRAY_FIELD> POINTS </ARRAY_FIELD> </ARRAY_COUNT_UINT16> <FIELD_ARRAY> <FIELD_NAME> "POINTS" </FIELD_NAME> <ARRAY_ITEM> <FIELD_STRUCT> <FIELD_NAME> "POINT" </FIELD_NAME> <STRUCT_TYPE> POINT_TYPE </STRUCT_TYPE> </FIELD_STRUCT> </ARRAY_ITEM> </FIELD_ARRAY> <STRING_TABLE> </STRING_TABLE> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE> </PALMOS_CUSTOM_RESOURCE_TYPES>
Palm OS Custom Resource Type Use
There are two elements that allow you to refer to a Palm OS custom resource type:
Custom Resource Element
Purpose
Use the custom resource element to refer to a previously defined custom resource by name.
Start Tag
<CUSTOM_RESOURCE RESOURCE_ID="resource_id">
Child Elements
-
<CUSTOM_RES_TYPE> resource_name </CUSTOM_RES_TYPE>
- Specifies the name of the custom resource type, which must conform to the rules described in "Name Format Requirements."
-
<CUSTOM_DATA> data_desc </CUSTOM_DATA>
- Specifies data in the format you defined by using the custom resource type's description.
End Tag
Example
<CUSTOM_RESOURCE RESOURCE_ID="1000"> <CUSTOM_RES_TYPE> POINT_LIST </CUSTOM_RES_TYPE> <CUSTOM_DATA> <POINTS> <POINT> <X> 10 </X> <Y> 10 </Y> </POINT> <POINT> <X> 50 </X> <Y> 10 </Y> </POINT> <POINT> <X> 50 </X> <Y> 50 </Y> </POINT> <POINT> <X> 10 </X> <Y> 50 </Y> </POINT> <POINT> <X> 10 </X> <Y> 10 </Y> </POINT> </POINTS> </CUSTOM_DATA> </CUSTOM_RESOURCE>
Custom Types Files Element
Purpose
Use the custom types files element to refer to custom types that are contained in a separate custom resource type descriptions file.
Start Tag
<CUSTOM_TYPES_FILES>
Child Elements
-
<CUSTOM_TYPES_FILE> ext_file </CUSTOM_TYPES_FILE>
- Specifies the name of the XRT file, the file that contains custom resource type descriptions.
End Tag
Example
<CUSTOM_TYPES_FILES> <CUSTOM_TYPES_FILE> "SimpleExample.xrt" </CUSTOM_TYPES_FILE> </CUSTOM_TYPES_FILES>
Comments
You can define one or more XRT files containing custom resource type descriptions. These XRT files are XML files that follow the Palm OS Custom Resource Types format, using the PALMOS_CUSTOM_RESOURCE_TYPES
document type.
You can reference one or more XRT files from XRD files by using the optional CUSTOM_TYPES_FILES
header block in the XRD file.
Each custom types file is specified in the same manner as other XRD external file references:
- If a custom types file is specified as a filename only, then the XRT file is expected to be in the same directory as the referencing XRD.
- If a custom types file is specified with a relative path URL syntax, then the XRT file is located using this path relative to the referencing XRD file
Example of an XRD file reference
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <PALMOS_RESOURCE_FILE> <COMMENT_TEXT> "CustomRes.xrd" </COMMENT_TEXT> <CUSTOM_TYPES_FILES> <CUSTOM_TYPES_FILE> "CustomResTypes.xrt" </CUSTOM_TYPES_FILE> <CUSTOM_TYPES_FILE> "CustomResTypes2.xrt" </CUSTOM_TYPES_FILE> </CUSTOM_TYPES_FILES> <CUSTOM_RESOURCE RESOURCE_ID="1000"> <CUSTOM_RES_TYPE> MY_RES_TYPE </CUSTOM_RES_TYPE> <CUSTOM_DATA> <X> 1941 </X> <Y> -235 </Y> </CUSTOM_DATA> </CUSTOM_RESOURCE> </PALMOS_RESOURCE_FILE>
Custom resource types must be defined before being used by CUSTOM_RESOURCE
descriptions.
Custom Enumeration Description
An enum description defines an integer field with a fixed set of labeled values. Subsequently a field of the enum type can be defined in a custom resource data structure. The field data in the custom resource XML must then be specified as one of the defined enum labels.
Define Enum Type Element
Purpose
Use the define enum type element to define a custom enumeration.
Start Tag
<DEFINE_ENUM_TYPE NAME=quoted_text>
- Specifies the name of the custom enum, which must conform to the rules described in "Name Format Requirements."
Child Elements
-
<ENUM_DATA_TYPE> data_type </ENUM_DATA_TYPE>
- Specifies the data type of the enum: either
UINT8
,UINT16
, orUINT32
. -
<ENUM_ITEMS> one or more ENUM_ITEM element
</ENUM_ITEMS> -
<ENUM_ITEM> enum_defn <ENUM_ITEM>
- where enum_defn consists of the following elements:
-
<ENUM_ITEM_VALUE>
integer
</ENUM_ITEM_VALUE> - integer is a unique integer value that fits in the enum data type.
-
<ENUM_ITEM_NAME>
quoted_text
</ENUM_ITEM_NAME> - quoted_text is a unique label, which must conform to the rules described in "Name Format Requirements."
End Tag
Example
Given an enum defined in C language as follows:
enum { opCode_MoveTo = 1, opCode_LineTo = 2, opCode_Text = 3 }; typedef uint16_t DrawingOpcode;
A corresponding custom types description might be:
<DEFINE_ENUM_TYPE NAME="DRAWING_OPCODE"> <COMMENT_TEXT> "DRAWING_OPCODE is an example of an \n" "enumerated value description." </COMMENT_TEXT> <ENUM_DATA_TYPE> UINT16 </ENUM_DATA_TYPE> <ENUM_ITEMS> <ENUM_ITEM> <ENUM_ITEM_VALUE> 1 </ENUM_ITEM_VALUE> <ENUM_ITEM_NAME> "OPCODE_MOVE_TO" </ENUM_ITEM_NAME> </ENUM_ITEM> <ENUM_ITEM> <ENUM_ITEM_VALUE> 2 </ENUM_ITEM_VALUE> <ENUM_ITEM_NAME> "OPCODE_LINE_TO" </ENUM_ITEM_NAME> </ENUM_ITEM> <ENUM_ITEM> <ENUM_ITEM_VALUE> 3 </ENUM_ITEM_VALUE> <ENUM_ITEM_NAME> "OPCODE_TEXT" </ENUM_ITEM_NAME> </ENUM_ITEM> </ENUM_ITEMS> </DEFINE_ENUM_TYPE>
Custom Structure Description
A struct description defines a named list of fields. Subsequently a field of the struct type can be defined in other custom resource data structures.
Define Struct Type Element
Purpose
Use the define struct type element to define a custom structure.
Start Tag
<DEFINE_STRUCT_TYPE NAME=quoted_text>
- Specifies the name of the custom structure, which must conform to the rules described in "Name Format Requirements."
Child Elements
-
<STRUCT_ITEMS> data_defns </STRUCT_ITEMS>
- Defines the data items in the structure, using data model objects described in "Data Model Objects."
End Tag
Example
Given a structure defined in C language as follows:
struct Rect { sint16_t top; sint16_t left; sint16_t bottom; sint16_t right; };
A corresponding custom types description might be:
<DEFINE_STRUCT_TYPE NAME="RECT"> <COMMENT_TEXT> "RECT is an example of a custom struct description.\n" "This example only uses simple field types." </COMMENT_TEXT> <STRUCT_ITEMS> <FIELD_SINT16> <FIELD_NAME> "TOP" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> <FIELD_SINT16> <FIELD_NAME> "LEFT" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> <FIELD_SINT16> <FIELD_NAME> "BOTTOM" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> <FIELD_SINT16> <FIELD_NAME> "RIGHT" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT16> </STRUCT_ITEMS> </DEFINE_STRUCT_TYPE>
Custom Resource Description
A resource type description defines a PRC resource type code, a default endianness, and the corresponding data structure. The data structure is defined the same way as for a struct type, namely as a named list of fields.
Define Resource Type Element
Purpose
Use the define resource type element to define a custom resource.
Start Tag
<DEFINE_RESOURCE_TYPE NAME=quoted_text>
- Specifies name of the custom resource, which must conform to the rules described in "Name Format Requirements."
Child Elements
-
<RES_TYPE> four_character_code </RES_TYPE>
- Specifies a four-character code representing the resource type for the custom resource.
-
<ENDIANNESS> enum </ENDIANNESS>
- Specifies the endianness of the custom resource, either
BIG_ENDIAN
orLITTLE_ENDIAN
. -
<STRUCT_ITEMS> data_defns </STRUCT_ITEMS>
- Defines the data items in the structure, using data model objects described in "Data Model Objects."
End Tag
Example
Given a resource type defined in C language as follows:
typedef struct { UInt16 count; // number of items UInt16 item[]; // variable length } WordListRscType;
A corresponding custom resource type description might be:
<DEFINE_RESOURCE_TYPE NAME="WORD_LIST"> <RES_TYPE> 'awrd' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <ARRAY_COUNT_UINT16> <ARRAY_FIELD> THE_ARRAY </ARRAY_FIELD> </ARRAY_COUNT_UINT16> <FIELD_ARRAY> <FIELD_NAME> "THE_ARRAY" </FIELD_NAME> <ARRAY_ITEM> <FIELD_UINT16> <FIELD_NAME> "ITEM" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_UINT16> </ARRAY_ITEM> </FIELD_ARRAY> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
Name Format Requirements
The names for enum types, enum value labels, struct types, and resource types are required to be a certain format:
- The names are allowed to use alphanumeric characters (lower case letters
'a'
through'z'
, uppercase letters'A'
through'Z'
, and numbers'0'
through'9'
) and the underscore character ('_'
). - The names must begin with a letter (lower case letters
'a'
through'z'
, uppercase letters'A'
through'Z'
) or with the underscore character ('_'
). A name cannot have a number as the first character. - Names are case-sensitive.
- Enum type names, struct type names, and resource type names must be globally unique. Field names must be unique within the defining data scope.
- For consistency with Palm OS Resource Type descriptions, it is recommended that all uppercase names be used, as this convention results in consistent appearance in the XML file. However this convention is purely a matter of style.
Data Model Objects
The following data model objects can be used for resource type and struct descriptions. There are three types of data model objects:
- Data field items
- Data field items define a named data field of a specific data type. When the resource data is declared, it must include a corresponding XML element with a data value of the corresponding data type. For example, if a
FIELD_UINT16
named"X"
is declared, the resource data must use a value declared similarly to this:<X> 42 </X>
- For more information about data field items, see "Data Field Items."
- Meta-data field items
- Meta-data fields are data field whose values are automatically calculated by the resource compiler and thus do not appear explicitly in the resource data. For example, if you define an
ARRAY_COUNT_UINT16
item, then the resource compiler automatically calculates the number of elements in the array field referenced. - For more information about meta-data field items, see "Meta-Data Field Items."
- Format control items
- Format control items are used to control the binary or compiler state when compiling and decompiling the binary data. For example, the
SET_ENDIANNESS
item is used to set whether integer data is output as big-endian or little-endian. The effect of format control items (items that affect the compiler state) is limited to the local resource or struct description and to any child field descriptions. - For more information about format control items, see "Format Control Items."
Data Field Items
A data field description consists of the element identifying the field data type, optionally followed by a COMMENT_TEXT
element, followed by a FIELD_NAME
element, followed by any elements specific to the data type.
You can use the following data field items in your custom resource descriptions:
- "Boolean Field"
- "Integer Fields"
- "Floating Point Fields"
- "Enum Fields"
- "String Fields"
- "String Table And Table String Fields"
- "Bitfield Fields"
- "Binary Fields"
- "Array Fields"
- "Struct Fields"
- "Variant Fields"
Boolean Field
A boolean field is stored in binary as a single byte with values 0 or 1. In the resource data XML, the value must be specified as FALSE or TRUE.
Example field description
<FIELD_BOOLEAN> <FIELD_NAME> "MY_BOOLEAN" </FIELD_NAME> </FIELD_BOOLEAN>
Example field data
<MY_BOOLEAN> TRUE </MY_BOOLEAN>
Integer Fields
An integer field specifies whether it is a signed or unsigned value and how many bits are used to store the value. The supported integer field types are:
Integer values are stored in the binary with the endianness specified by the resource type and compiler context.
You may optionally define the DISPLAY_FORMAT
as DECIMAL
, HEXADECIMAL
, or CHAR
. This element is used to format the data values for display when resource data is decompiled or viewed by tools such as GenerateXRD.
In the resource data XML, you may specify integer values as decimal, hexadecimal, or character constant values (regardless of the display format).
Example field description
<FIELD_SINT32> <FIELD_NAME> "MY_INTEGER" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_SINT32>
Example field data
<MY_INTEGER> 3 </MY_INTEGER>
Floating Point Fields
A floating point field is specified including how many bits are used to store the value. The supported floating point field types are FIELD_FLOAT32
and FIELD_FLOAT64
.
Floating point values are stored in the binary with the endianness specified by the resource type and compiler context.
Example field description
<FIELD_FLOAT32> <FIELD_NAME> "MY_FLOAT" </FIELD_NAME> </FIELD_FLOAT32>
Example field data
<MY_FLOAT> 3.14 </MY_FLOAT>
Enum Fields
An enum field is specified as a field using an enum type previously defined. The integer binary size is specified by the enum type description. The value is stored in the binary with the endianness specified by the resource type and compiler context.
Example enum field description
<FIELD_ENUM> <FIELD_NAME> "THE_DRAWING_OP" </FIELD_NAME> <ENUM_TYPE> DRAWING_OPCODE </ENUM_TYPE> </FIELD_ENUM>
Example field data
<THE_DRAWING_OP> OPCODE_LINE_TO </THE_DRAWING_OP>
String Fields
A string field stored a text value. Text is stored in resource binary as a null-terminated string in the text encoding specified by the compilation target. There are two string formats supported: FIELD_STRING
and FIELD_FIXED_STRING
.
FIELD_STRING
strings are stored with variable length in the binary data. For example, the string "CAT"
would be stored as 4 bytes (0x43
, 0x41
, 0x53
, 0x00
).
FIELD_FIXED_STRING
values are stored as a predefined fixed size in the binary data. The size is specified with BUFFER_SIZE
as the number of bytes for the string buffer size. This size must include 1 for the terminating null character. Any unused bytes in the string buffer are filled to 0.
For example, if the buffer size were specified as 6, the string "CAT"
would be stored as 6 bytes (0x43
, 0x41
, 0x53
, 0x00
, 0x00
, 0x00
). If the string, including the terminating null character, does not fit in the buffer at compile time, then resource compiler gives an error message.
Example string field description
<FIELD_STRING> <FIELD_NAME> "MY_STRING" </FIELD_NAME> </FIELD_STRING>
Example string field data
<MY_STRING> "Hello" </MY_STRING>
Example fixed string field description
<FIELD_FIXED_STRING> <FIELD_NAME> "MY_STRING2" </FIELD_NAME> <BUFFER_SIZE> 32 </BUFFER_SIZE> </FIELD_FIXED_STRING>
Example fixed string field data
<MY_STRING2> "Hello" </MY_STRING2>
String Table And Table String Fields
Regular string fields are stored as inline data with variable length. The array data structures can not be randomly accessed without iterating over the data at run-time, which can complicate working resource types that use arrays of records.
To help with this common problem, the custom resource types data model provides table string fields and a string table data model object.
When you use table string fields, the offset of the string is output to the binary data rather than having the string data being placed inline at the field. The offset is relative to the beginning of the resource and is stored as a fixed size integer as specified by the table string field (either FIELD_TABLE_STRING_UINT16
or FIELD_TABLE_STRING_UINT32
).
When you use table string fields, the resource type description also includes a string table data model object. The string table object is defined after all the table string fields in the resource. Typically the string table object will be defined as the last item in the custom resource type description.
NOTE: If the same string is defined by multiple table string fields, the string is only stored once in the string table and both table string fields will have the same offset.
Example custom resource type description using string table
<DEFINE_RESOURCE_TYPE NAME="MY_STRING_LIST"> <RES_TYPE> 'Strs' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <ARRAY_COUNT_UINT16> <ARRAY_FIELD> STRINGS </ARRAY_FIELD> </ARRAY_COUNT_UINT16> <FIELD_ARRAY> <FIELD_NAME> "STRINGS" </FIELD_NAME> <ARRAY_ITEM> <FIELD_TABLE_STRING_UINT16> <FIELD_NAME> "STRING" </FIELD_NAME> </FIELD_TABLE_STRING_UINT16> </ARRAY_ITEM> </FIELD_ARRAY> <STRING_TABLE> </STRING_TABLE> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
Example custom resource data
<CUSTOM_RESOURCE RESOURCE_ID="1000"> <CUSTOM_RES_TYPE> MY_STRING_LIST </CUSTOM_RES_TYPE> <CUSTOM_DATA> <STRINGS> <STRING> "CAT" </STRING> <STRING> "DOG" </STRING> </STRINGS> </CUSTOM_DATA> </CUSTOM_RESOURCE>
Resulting resource binary data
00: 00 02 // count of strings 02: 00 0A // offset of first string = "CAT" 04: 00 0E // offset of second string = "DOG" 06: 00 00 00 08 // string table starts with size 0A: 43 41 54 00 // "CAT" 0E: 44 4F 47 00 // "DOG" 12:
Bitfield Fields
A bitfield field is an integer field where individual bits or sequences of the bits are treated as separate logical values. A bitfield field is specified including how many bits are used to store the value. The supported bitfield field types are:
The bitfield field is defined as a sequence of bitfield items. Bitfield items may be defined as BITFIELD_BOOL
or BITFIELD_UINT
n where n is a number from 1 to 31. Bitfield items are defined from most significant bit down to least significant bit.
Note that the conglomerate integer value is stored in the binary with the endianness specified by the resource type and compiler context. Bitfield items must be defined to use exactly the number of bits stored in the bitfield field.
Example field description
<FIELD_BITFIELD_UINT8> <FIELD_NAME> "ATTRIBUTES" </FIELD_NAME> <BITFIELDS> <BITFIELD_BOOL> <FIELD_NAME> "HI_BIT" </FIELD_NAME> </BITFIELD_BOOL> <BITFIELD_UINT3> <FIELD_NAME> "RESERVED" </FIELD_NAME> </BITFIELD_UINT3> <BITFIELD_UINT4> <FIELD_NAME> "CATEGORY" </FIELD_NAME> </BITFIELD_UINT4> </BITFIELDS> </FIELD_BITFIELD_UINT8>
Example resource data
<ATTRIBUTES> <HI_BIT> TRUE </HI_BIT> <RESERVED> 0 </RESERVED> <CATEGORY> 2 </CATEGORY> </ATTRIBUTES>
Binary Fields
Binary fields are used to store arbitrary raw binary data. There are two formats of binary supported: FIELD_BINARY
and FIELD_FIXED_BINARY
.
FIELD_BINARY
fields are stored with variable length in the binary data. That is, you can specify any amount of data in the resource data description.
FIELD_FIXED_BINARY
fields are stored with a specific length in the binary data. You specify the size in bytes with the BUFFER_SIZE
element. In this case, the amount of data you specify in the resource data description must match exactly the expected size.
Binary data is specified in the custom resource data as hexadecimal encoded binary.
Example binary field description
<FIELD_BINARY> <FIELD_NAME> "A_BLOB" </FIELD_NAME> </FIELD_BINARY>
Example binary field data
<A_BLOB> 80 FF 00 01 </A_BLOB>
Example fixed-size binary field description
<FIELD_FIXED_BINARY> <FIELD_NAME> "B_BLOB" </FIELD_NAME> <BUFFER_SIZE> 8 </BUFFER_SIZE> </FIELD_FIXED_BINARY>
Example field data
<B_BLOB> 01 02 03 04 05 06 07 08 </B_BLOB>
Note that there is a related meta-data field object class named BINARY_SIZE
which can be used to store the size of a binary data field in a separate integer field.
Array Fields
Array fields are used to store homogeneous arrays of data fields. The array item type is defined in the ARRAY_ITEM
element. This element must contain a single data field specifier, which may be either a simple field type or a conglomerate field type such as a FIELD_STRUCT
. Array items are not required to be homogeneous size in the binary data.
Example array field description
<FIELD_ARRAY> <FIELD_NAME> "MY_ARRAY" </FIELD_NAME> <ARRAY_ITEM> <FIELD_UINT16> <FIELD_NAME> "CHAR_CODE" </FIELD_NAME> <DISPLAY_FORMAT> HEXADECIMAL </DISPLAY_FORMAT> </FIELD_UINT16> </ARRAY_ITEM> </FIELD_ARRAY>
Example array data description
<MY_ARRAY> <CHAR_CODE> 0x1122 </CHAR_CODE> <CHAR_CODE> 0x3344 </CHAR_CODE> </MY_ARRAY>
Note that there is a related meta-data field object class named ARRAY_COUNT
which can be used to store the number of items in an array in a separate integer field.
Struct Fields
A struct field is used to define a field with data type corresponding to a previously defined struct type. The struct type is specified with the STRUCT_TYPE
element.
Example struct field description
<FIELD_STRUCT> <FIELD_NAME> "POINT" </FIELD_NAME> <STRUCT_TYPE> POINT_TYPE </STRUCT_TYPE> </FIELD_STRUCT>
Example struct data description
<POINT> <X> 20 </X> <Y> 30 </Y> </POINT>
Variant Fields
A variant field is used to define a data description which varies depending on the value of a key field. The variant field specifies the key field (which must have been previously defined in the same scope) and a list of key values and corresponding data descriptions. You define the data description for each variant by using a STRUCT_ITEMS
element in the same fashion as a DEFINE_STRUCT_TYPE
description. Note that the data description for a variant may be empty.
Example of custom resource type using inline descriptions for field variants
<DEFINE_RESOURCE_TYPE NAME="TEST_VARIANT"> <RES_TYPE> 'TVar' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <FIELD_UINT32> <FIELD_NAME> "FORMAT" </FIELD_NAME> <DISPLAY_FORMAT> CHAR </DISPLAY_FORMAT> </FIELD_UINT32> <FIELD_UINT16> <FIELD_NAME> "VERSION" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_UINT16> <FIELD_UINT16> <FIELD_NAME> "RESERVED" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_UINT16> <FIELD_VARIANT> <FIELD_NAME> "DATA" </FIELD_NAME> <KEY_FIELD> VERSION </KEY_FIELD> <VARIANTS> <VARIANT> <KEY_VALUE> 1 </KEY_VALUE> <STRUCT_ITEMS> </STRUCT_ITEMS> </VARIANT> <VARIANT> <KEY_VALUE> 2 </KEY_VALUE> <STRUCT_ITEMS> <FIELD_UINT32> <FIELD_NAME> "X" </FIELD_NAME> </FIELD_UINT32> </STRUCT_ITEMS> </VARIANT> </VARIANTS> </FIELD_VARIANT> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
Example of corresponding resource data with 'VERSION = 1'
<CUSTOM_RESOURCE RESOURCE_ID="4101"> <CUSTOM_RES_TYPE> TEST_VARIANT </CUSTOM_RES_TYPE> <CUSTOM_DATA> <FORMAT> 'TEST' </FORMAT> <VERSION> 1 </VERSION> <RESERVED> 0 </RESERVED> <DATA> </DATA> </CUSTOM_DATA> </CUSTOM_RESOURCE>
Example of corresponding resource data with 'VERSION = 2'
<CUSTOM_RESOURCE RESOURCE_ID="4102"> <CUSTOM_RES_TYPE> TEST_VARIANT </CUSTOM_RES_TYPE> <CUSTOM_DATA> <FORMAT> 'test' </FORMAT> <VERSION> 2 </VERSION> <RESERVED> 0 </RESERVED> <DATA> <X> 0x12345678 </X> </DATA> </CUSTOM_DATA> </CUSTOM_RESOURCE>
Example of custom resource type using separate structs for field variants
<DEFINE_RESOURCE_TYPE NAME="TEST_SILK_SCREEN"> <RES_TYPE> 'silk' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <FIELD_UINT16> <FIELD_NAME> "VERSION" </FIELD_NAME> <DISPLAY_FORMAT> DECIMAL </DISPLAY_FORMAT> </FIELD_UINT16> <FIELD_VARIANT> <FIELD_NAME> "VERSIONED_DATA" </FIELD_NAME> <KEY_FIELD> VERSION </KEY_FIELD> <VARIANTS> <VARIANT> <KEY_VALUE> 1 </KEY_VALUE> <STRUCT_ITEMS> <FIELD_STRUCT> <FIELD_NAME> "SILK_SCREEN_V1" </FIELD_NAME> <STRUCT_TYPE> SILK_SCREEN_V1 </STRUCT_TYPE> </FIELD_STRUCT> </STRUCT_ITEMS> </VARIANT> <VARIANT> <KEY_VALUE> 2 </KEY_VALUE> <STRUCT_ITEMS> <FIELD_STRUCT> <FIELD_NAME> "SILK_SCREEN_V2" </FIELD_NAME> <STRUCT_TYPE> SILK_SCREEN_V2 </STRUCT_TYPE> </FIELD_STRUCT> </STRUCT_ITEMS> </VARIANT> </VARIANTS> </FIELD_VARIANT> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
Meta-Data Field Items
You can use the following meta-data field items in your custom resource descriptions:
Array Count Fields
An array count field is used to define an integer field containing the number of elements in the referenced array field. An array count field is specified including how many bits are used to store the value. The supported array count field types are:
Array count values are stored in the binary with the endianness specified by the resource type and compiler context.
Note that array count values are calculated by the resource compiler at compile time and thus do not appear in the resource data explicitly.
Note also that only one array count object is allowed per array field.
For the purposes of viewing and decompiling data, the array count object must occur before the corresponding array. If an array count object is not specified, arrays are assumed to use all subsequent data in the resource binary.
Example array count field description
<ARRAY_COUNT_UINT16> <ARRAY_FIELD> MY_ARRAY </ARRAY_FIELD> </ARRAY_COUNT_UINT16>
Binary Size Fields
A binary size field is used to define an integer field containing the size in bytes of the referenced binary field. A binary size field is specified including how many bits are used to store the value. The supported binary size field types are:
Binary size values are stored in the resource binary with the endianness specified by the resource type and compiler context.
Note that binary size values are calculated by the resource compiler at compile time and thus do not appear in the resource data explicitly.
Note also that only one binary size object is allowed per binary field.
For the purposes of viewing and decompiling data, the binary size object must occur before the corresponding binary field. If a binary size object is not specified, binary fields are assumed to use all subsequent data in the resource binary.
Example binary size field description
<BINARY_SIZE_UINT16> <BINARY_FIELD> A_BLOB </BINARY_FIELD> </BINARY_SIZE_UINT16>
Format Control Items
You can use the following format control items in your custom resource descriptions:
Align
The ALIGN
object is used to pad the binary data stream to a certain alignment. This is done by outputting bytes with value 0 if necessary until the binary data offset is a multiple of the specified value.
Example alignment field description
<ALIGN> 2 </ALIGN>
Example of ALIGN in a resource type description
<DEFINE_RESOURCE_TYPE NAME="TEST_ALIGN"> <RES_TYPE> 'TAln' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <FIELD_SINT8> <FIELD_NAME> "X" </FIELD_NAME> </FIELD_SINT8> <ALIGN> 2 </ALIGN> <FIELD_UINT16> <FIELD_NAME> "COUNT" </FIELD_NAME> </FIELD_UINT16> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
In this example, field X
is a single byte at offset 0, thus advancing the binary data offset to 1. Because this is not a multiple of 2, the ALIGN
description then emits a pad byte to advance the binary offset to 2. The field COUNT
is then a 2-byte integer at offset 0, thus advancing the binary data offset and total resource length to 4.
Set Endianness
The SET_ENDIANNESS element is used to specify the format of multi-byte integer and floating point values in the resource binary data. The value may be specified as BIG_ENDIAN
or LITTLE_ENDIAN
. The endianness format is normally specified by the resource type and used consistently for the entire resource, but can be overridden for individual fields or structs if desired.
The endianness change is restricted to the scope of the resource type or struct type.
Example endianness field description
<SET_ENDIANNESS> LITTLE_ENDIAN </SET_ENDIANNESS>
Example of SET_ENDIANNESS in a resource type description
<DEFINE_RESOURCE_TYPE NAME="TEST_ENDIANNESS"> <RES_TYPE> 'TEnd' </RES_TYPE> <ENDIANNESS> BIG_ENDIAN </ENDIANNESS> <STRUCT_ITEMS> <FIELD_UINT16> <FIELD_NAME> "N0" </FIELD_NAME> </FIELD_UINT16> <SET_ENDIANNESS> LITTLE_ENDIAN </SET_ENDIANNESS> <FIELD_UINT16> <FIELD_NAME> "N1" </FIELD_NAME> </FIELD_UINT16> <FIELD_UINT16> <FIELD_NAME> "N2" </FIELD_NAME> </FIELD_UINT16> </STRUCT_ITEMS> </DEFINE_RESOURCE_TYPE>
In this example, the resource type is specified as big-endian. Thus the first integer value N0
is written to the binary data as big-endian. This is next overridden by the SET_ENDIANNESS
specifier so that the subsequent N1
and N2
fields are written to the binary data as little-endian.