Contains types and constants used by external resource reader and writer

These types are used internally by TExternalResourceReader and TExternalResourceWriter.

Two constants are of interest: and .

Description of external resource file format

Introduction

An external resource file (.fpcres extension) provides resource support for those systems where a resource format suitable to be embedded in an object file isn't available.

The file format is designed in a way similar to other internal resource formats. The file is opened at program startup and is mapped in the program address space. Offsets in the file are easily converted to pointers at runtime since those offsets represent a displacement from a base address (the starting address where the file is mapped). Differences from an internal file format hence lie in the fact that resources aren't mapped in the program address space by the program loader but by Free Pascal RTL, and data must be accessed with a displacement mechanism instead of absolute pointers.

For internal resources details, see

File layout

An external resource file consists of these parts:

  • The initial header, containing various file information
  • The resource tree, in the form of nodes
  • The string table, which can be optional
  • The resource data

The header is made up by initial header, resource tree and string table (if present).

Conventions

In this document, data sizes are specified with pascal-style data types. They are the following:

NameMeaning
byteUnsigned 8 bit integer.
longwordUnsigned 32 bit integer.
qwordUnsigned 64 bit integer.

Byte order used in the file is specified in the initial header.

All data structures in the file must be aligned on qword boundaries.

The initial header

An external resource file starts with this header:

NameOffsetLengthDescription
magic 0 6 Six ASCII characters that form the string FPCRES
version 6 byte File format version. Currently it is 1.
endianess 7 byte Byte order. 1 for big endian, 2 for little endian
count 8 longword Number of resources in the file
nodesize 12 longword Size of header up to the string table, excluded
hdrsize 16 longword Full size of header (up to the string table, included)
reserved 20 12 Must be zero

Note that byte order of the file can be read in the endianess field of the header. All data fields longer than a byte are written with the byte order specified in endianess.

If no resource name or type is identified by strings, string table is optional. When this is the case, nodesize and hdrsize have the same value.

The resource tree

Immediately following the initial header, the resource tree comes. It is made up by nodes that represent resource types, names and language ids.

Data is organized so that resource information (type, name and language id) is represented by a tree: root node contains resource types, that in turn contain resource names, which contain language ids, which describe resource data.

Given a node, its sub-nodes are ordered as follows:

  • First the "named" nodes (nodes that use a string as identifier) come, then the id ones (nodes that use an integer as identifier).
  • Named nodes are alphabetically sorted, in ascending order.
  • Id nodes are sorted in ascending order.

In the file, all sub-nodes of a node are written in the order described above. Then, all sub-nodes of the first sub-node are written, and so on.

Example:

There are three resources:

  1. a BITMAP resource with name MYBITMAP and language id $0409
  2. a BITMAP resource with name 1 and language id 0
  3. a resource with type MYTYPE and name 1 and language id 0

Nodes are laid out this way (note that BITMAP resources have type 2):

 
root | MYTYPE 2 | 1 | 0 | MYBITMAP 1 | $0409 | 0

That is, types (MYTYPE is a string, so it comes before 2 which is BITMAP), then names for MYTYPE (1), then language id for resource 3 (0), then names for BITMAP (MYBITMAP and 1), then language id for resource 1 ($0409), then language id for resource 2 (0).

Node format

NameOffsetLengthDescription
nameid 0 longword name offset, integer id or language id
ncount 4 longword named sub-nodes count
idcountsize 8 longword id sub-nodes count or resource size
subptr 12 longword offset to first sub-node

Note that all offset are always relative to the beginning of the file.

If the node is identified by a string, nameid is an offset to the null-terminated string holding the name. If it is identified by an id, nameid is that id. Language id nodes are always identified by and ID.

ncount is the number of named sub-nodes of this node (nodes that are identified by a string).

idcountsize is the number of id sub-nodes of this node (nodes that are identified by an integer id). For language id nodes, this field holds the size of the resource data.

subptr is an offset to the first subnode of this node. Note that it allows to access every subnode of this node, since subnodes of a node always come one after the other. For language id nodes, subptr is the offset to the resource data.

The string table

The string table is used to store strings used for resource types and names. If all resources use integer ids for name and types, it may not be present in the file.

The string table simply contains null-terminated strings, one after the other.

If present, the string table always contains a 0 (zero) at the beginning. This way, the empty string is located at the offset of the string table (whose value is held in nodesize field of the initial header).

The resource data

This part of the file contains raw resource data. As written before, all data structures must be aligned on qword boundaries, so if a resource data size is not a multiple of 8, bytes of padding must be inserted after that resource data.

Type used for the magic identifier in external resource files Header of an external resource file

This header describes the data structure present at the beginning of an external resource file.

String identifying the file format File format version Byte order of the file Number of resources in the file Size of header up to string table, excluded Size of header up to string table, included Unused as of version 1 Unused as of version 1 Unused as of version 1 A node of a resource tree

This record represents a node used in a resource tree. A node contains information about a certain resource type, name or language id.

Name or ID of the node Number of named sub-entries Number of ID sub-entries or resource size Offset to first subnode or resource data Magic identifier for the external resource file type

This value is used for .

Current version of file format

This value is used for .

The file uses big endian byte order

This value is used for .

The file uses little endian byte order

This value is used for .