PageRenderTime 24ms CodeModel.GetById 19ms app.highlight 3ms RepoModel.GetById 0ms app.codeStats 0ms

/packages/fcl-res/xml/externaltypes.xml

https://github.com/slibre/freepascal
XML | 311 lines | 254 code | 32 blank | 25 comment | 0 complexity | a30ca0cf0e0f966c031539fbef299728 MD5 | raw file
Possible License(s): LGPL-2.0, LGPL-2.1, LGPL-3.0
  1<?xml version="1.0" encoding="ISO-8859-1"?>
  2<fpdoc-descriptions>
  3<package name="fcl-res">
  4
  5<!--
  6  ====================================================================
  7    externaltypes
  8  ====================================================================
  9-->
 10
 11<module name="externaltypes">
 12<short>Contains types and constants used by external resource reader and writer</short>
 13<descr>
 14<p>These types are used internally by <link id="externalreader.TExternalResourceReader">TExternalResourceReader</link> and <link id="externalwriter.TExternalResourceWriter">TExternalResourceWriter</link>.</p>
 15<p>Two constants are of interest: <link id="EXT_ENDIAN_BIG"/> and <link id="EXT_ENDIAN_LITTLE"/>.</p>
 16</descr>
 17
 18<topic name="Description of external resource file format">
 19<short>Description of external resource file format</short>
 20<descr>
 21<p><b>Introduction</b></p>
 22<p>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.</p>
 23<p>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.</p>
 24<p>For internal resources details, see <link id ="Format of resources in object files"/></p>
 25<p><b>File layout</b></p>
 26<p>An external resource file consists of these parts:</p>
 27<ul>
 28<li>The initial header, containing various file information</li>
 29<li>The resource tree, in the form of nodes</li>
 30<li>The string table, which can be optional</li>
 31<li>The resource data</li>
 32</ul>
 33<p>The header is made up by initial header, resource tree and string table (if present).</p>
 34<p><b>Conventions</b></p>
 35<p>In this document, data sizes are specified with pascal-style data types. They are the following:</p>
 36<table>
 37<th><td>Name</td><td>Meaning</td></th>
 38<tr><td><var>byte</var></td><td>Unsigned 8 bit integer.</td></tr>
 39<tr><td><var>longword</var></td><td>Unsigned 32 bit integer.</td></tr>
 40<tr><td><var>qword</var></td><td>Unsigned 64 bit integer.</td></tr>
 41</table>
 42<p>Byte order used in the file is specified in the initial header.</p>
 43<p>All data structures in the file must be aligned on qword boundaries.</p>
 44
 45<p><b>The initial header</b></p>
 46<p>An external resource file starts with this header:</p>
 47<table>
 48	<th><td>Name</td><td>Offset</td><td>Length</td><td>Description</td></th>
 49 	<tr>
 50		<td>magic</td>
 51		<td>0</td>
 52		<td>6</td>
 53		<td>Six ASCII characters that form the string <var>FPCRES</var></td>
 54	</tr>
 55
 56	<tr>
 57		<td>version</td>
 58		<td>6</td>
 59		<td>byte</td>
 60		<td>File format version. Currently it is <var>1</var>.</td>
 61	</tr>
 62	<tr>
 63		<td>endianess</td>
 64		<td>7</td>
 65		<td>byte</td>
 66		<td>Byte order. <var>1</var> for big endian, <var>2</var> for little endian</td>
 67	</tr>
 68	<tr>
 69		<td>count</td>
 70		<td>8</td>
 71		<td>longword</td>
 72		<td>Number of resources in the file</td>
 73	</tr>
 74	<tr>
 75		<td>nodesize</td>
 76		<td>12</td>
 77		<td>longword</td>
 78		<td>Size of header up to the string table, excluded</td>
 79	</tr>
 80	<tr>
 81		<td>hdrsize</td>
 82		<td>16</td>
 83		<td>longword</td>
 84		<td>Full size of header (up to the string table, included)</td>
 85	</tr>
 86	<tr>
 87		<td>reserved</td>
 88		<td>20</td>
 89		<td>12</td>
 90		<td>Must be zero</td>
 91	</tr>
 92</table>
 93<p>Note that byte order of the file can be read in the <var>endianess</var> field of the header. All data fields longer than a byte are written with the byte order specified in <var>endianess</var>.</p>
 94<p>If no resource name or type is identified by strings, string table is optional. When this is the case, <var>nodesize</var> and <var>hdrsize</var> have the same value.</p>
 95
 96<p><b>The resource tree</b></p>
 97<p>Immediately following the initial header, the resource tree comes. It is made up by nodes that represent resource types, names and language ids.</p>
 98<p>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.</p>
 99<p>Given a node, its sub-nodes are ordered as follows:</p>
100<ul>
101<li>First the "named" nodes (nodes that use a string as identifier) come, then the id ones (nodes that use an integer as identifier).</li>
102<li>Named nodes are alphabetically sorted, in ascending order.</li>
103<li>Id nodes are sorted in ascending order.</li>
104</ul>
105<p>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.</p>
106<p><b>Example:</b></p>
107<p>There are three resources:</p>
108<ol>
109<li>a <var>BITMAP</var> resource with name <var>MYBITMAP</var> and language id <var>$0409</var></li>
110<li>a <var>BITMAP</var> resource with name <var>1</var> and language id <var>0</var></li>
111<li>a resource with type <var>MYTYPE</var> and name <var>1</var> and language id <var>0</var></li>
112</ol>
113<p>Nodes are laid out this way (note that <var>BITMAP</var> resources have type <var>2</var>):</p>
114<pre>
115 
116root | MYTYPE 2 | 1 | 0 | MYBITMAP 1 | $0409 | 0
117</pre>
118<p>That is, types (<var>MYTYPE</var> is a string, so it comes before <var>2</var> which is <var>BITMAP</var>), then names for <var>MYTYPE</var> (<var>1</var>), then language id for resource 3 (<var>0</var>), then names for <var>BITMAP</var> (<var>MYBITMAP</var> and <var>1</var>), then language id for resource 1 (<var>$0409</var>), then language id for resource 2 (<var>0</var>).</p>
119
120<p><b>Node format</b></p>
121<table>
122	<th><td>Name</td><td>Offset</td><td>Length</td><td>Description</td></th>
123	<tr>
124		<td>nameid</td>
125		<td>0</td>
126		<td>longword</td>
127		<td>name offset, integer id or language id</td>
128	</tr>
129	<tr>
130		<td>ncount</td>
131		<td>4</td>
132		<td>longword</td>
133		<td>named sub-nodes count</td>
134	</tr>
135	<tr>
136		<td>idcountsize</td>
137		<td>8</td>
138		<td>longword</td>
139		<td>id sub-nodes count or resource size</td>
140	</tr>
141	<tr>
142		<td>subptr</td>
143		<td>12</td>
144		<td>longword</td>
145		<td>offset to first sub-node</td>
146	</tr>
147</table>
148<p>Note that all offset are always relative to the beginning of the file.</p>
149<p>If the node is identified by a string, <var>nameid</var> is an offset to the null-terminated string holding the name. If it is identified by an id, <var>nameid</var> is that id. Language id nodes are always identified by and ID.</p>
150<p><var>ncount</var> is the number of named sub-nodes of this node (nodes that are identified by a string).</p>
151<p><var>idcountsize</var> 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.</p>
152<p><var>subptr</var> 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, <var>subptr</var> is the offset to the resource data.</p>
153
154<p><b>The string table</b></p>
155<p>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.</p>
156<p>The string table simply contains null-terminated strings, one after the other.</p>
157<p>If present, the string table always contains a <var>0</var> (zero) at the beginning. This way, the empty string is located at the offset of the string table (whose value is held in <var>nodesize</var> field of the initial header).</p>
158
159<p><b>The resource data</b></p>
160<p>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.</p>
161</descr>
162</topic>
163
164<!-- array type Visibility: default -->
165<element name="TExternalResMagic">
166<short>Type used for the magic identifier in external resource files</short>
167<seealso>
168<link id="EXTERNAL_RESMAGIC"/>
169</seealso>
170</element>
171
172<!-- record type Visibility: default -->
173<element name="TExtHeader">
174<short>Header of an external resource file</short>
175<descr>
176<p>This header describes the data structure present at the beginning of an external resource file.</p>
177</descr>
178<seealso>
179<link id="EXTERNAL_RESMAGIC"/>
180<link id="EXT_CURRENT_VERSION"/>
181<link id="EXT_ENDIAN_BIG"/>
182<link id="EXT_ENDIAN_LITTLE"/>
183</seealso>
184</element>
185
186<!-- variable Visibility: default -->
187<element name="TExtHeader.magic">
188<short>String identifying the file format</short>
189</element>
190
191<!-- variable Visibility: default -->
192<element name="TExtHeader.version">
193<short>File format version</short>
194</element>
195
196<!-- variable Visibility: default -->
197<element name="TExtHeader.endianess">
198<short>Byte order of the file</short>
199</element>
200
201<!-- variable Visibility: default -->
202<element name="TExtHeader.count">
203<short>Number of resources in the file</short>
204</element>
205
206<!-- variable Visibility: default -->
207<element name="TExtHeader.nodesize">
208<short>Size of header up to string table, excluded</short>
209</element>
210
211<!-- variable Visibility: default -->
212<element name="TExtHeader.hdrsize">
213<short>Size of header up to string table, included</short>
214</element>
215
216<!-- variable Visibility: default -->
217<element name="TExtHeader.reserved1">
218<short>Unused as of version 1</short>
219</element>
220
221<!-- variable Visibility: default -->
222<element name="TExtHeader.reserved2">
223<short>Unused as of version 1</short>
224</element>
225
226<!-- variable Visibility: default -->
227<element name="TExtHeader.reserved3">
228<short>Unused as of version 1</short>
229</element>
230
231<!-- record type Visibility: default -->
232<element name="TResInfoNode">
233<short>A node of a resource tree</short>
234<descr>
235<p>This record represents a node used in a resource tree. A node contains information about a certain resource type, name or language id.</p>
236</descr>
237<seealso>
238</seealso>
239</element>
240
241<!-- variable Visibility: default -->
242<element name="TResInfoNode.nameid">
243<short>Name or ID of the node</short>
244</element>
245
246<!-- variable Visibility: default -->
247<element name="TResInfoNode.ncount">
248<short>Number of named sub-entries</short>
249</element>
250
251<!-- variable Visibility: default -->
252<element name="TResInfoNode.idcountsize">
253<short>Number of ID sub-entries or resource size</short>
254</element>
255
256<!-- variable Visibility: default -->
257<element name="TResInfoNode.subptr">
258<short>Offset to first subnode or resource data</short>
259</element>
260
261<!-- constant Visibility: default -->
262<element name="EXTERNAL_RESMAGIC">
263<short>Magic identifier for the external resource file type</short>
264<descr>
265<p>This value is used for <link id="TExtHeader.magic"/>.</p>
266</descr>
267<seealso>
268<link id="TExternalResMagic"/>
269<link id="TExtHeader"/>
270</seealso>
271</element>
272
273<!-- constant Visibility: default -->
274<element name="EXT_CURRENT_VERSION">
275<short>Current version of file format</short>
276<descr>
277<p>This value is used for <link id="TExtHeader.version"/>.</p>
278</descr>
279<seealso>
280<link id="TExtHeader"/>
281</seealso>
282</element>
283
284<!-- constant Visibility: default -->
285<element name="EXT_ENDIAN_BIG">
286<short>The file uses big endian byte order</short>
287<descr>
288<p>This value is used for <link id="TExtHeader.endianess"/>.</p>
289</descr>
290<seealso>
291<link id="TExtHeader"/>
292<link id="EXT_ENDIAN_LITTLE"/>
293</seealso>
294</element>
295
296<!-- constant Visibility: default -->
297<element name="EXT_ENDIAN_LITTLE">
298<short>The file uses little endian byte order</short>
299<descr>
300<p>This value is used for <link id="TExtHeader.endianess"/>.</p>
301</descr>
302<seealso>
303<link id="TExtHeader"/>
304<link id="EXT_ENDIAN_BIG"/>
305</seealso>
306</element>
307
308</module> <!-- externaltypes -->
309
310</package>
311</fpdoc-descriptions>