1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-E932B20C-5155-530F-9669-6F5BB1F1AD41" xml:lang="en"><title>STRUCT |
|
13 statement</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <codeblock xml:space="preserve"><struct-statement> |
|
15 struct-statement ::= |
|
16 STRUCT <struct-name> [ BYTE | WORD ] { <struct-member-list> } </codeblock> |
|
17 <p>A <codeph>STRUCT</codeph> statement defines the format of a struct; all |
|
18 resources are defined in terms of structs. The struct has a name designated |
|
19 by <varname>struct-name</varname>, and some items designated by <varname>struct-member-list</varname>.</p> |
|
20 <section><title>Struct names</title><p>The following rules must |
|
21 be observed for <varname>struct-names</varname>:</p><ul> |
|
22 <li id="GUID-E490ACC3-1A5E-5A93-97BC-EA13322F93B3"><p>they must be given in |
|
23 upper case</p> </li> |
|
24 <li id="GUID-A8237D56-9872-5869-9041-1F66130F1BCA"><p>they must begin with |
|
25 an alphabetic character, although subsequent characters may be numeric</p> </li> |
|
26 <li id="GUID-8F0B5DE9-C6B0-5637-A755-0BD408744898"><p>they may not begin with |
|
27 any of the 12 struct <varname>type-names</varname> (see <xref href="GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita">STRUCT |
|
28 members</xref>), or the keywords: <codeph>GLOBAL</codeph>, <codeph>STRUCT</codeph>, <codeph>LEN</codeph> or <codeph>RESOURCE</codeph>. |
|
29 This restriction applies only to the <varname>struct-name</varname>, not the <varname>member-name</varname> of |
|
30 any individual struct members.</p> <p>So the following struct definition will |
|
31 generate an error</p> <codeblock id="GUID-A2D5E9FB-1C45-52FE-8997-95D2117DFE05" xml:space="preserve">STRUCT BUFTHING |
|
32 { |
|
33 BUF buffer; |
|
34 }</codeblock> <p>whereas this struct definition will compile correctly</p> <codeblock id="GUID-6EEF6653-C2D9-559E-BA72-5C70E30B9633" xml:space="preserve">STRUCT ABUFTHING |
|
35 { |
|
36 BUF buffer; |
|
37 }</codeblock> </li> |
|
38 </ul></section> |
|
39 <section><title>Struct member list</title><p>The <varname>struct-member-list</varname> is |
|
40 a sequence of <varname>struct-member</varname> s where each member is terminated |
|
41 by a semi-colon. The complete list is enclosed within a pair of braces.</p><p>See <xref href="GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita">STRUCT members</xref> for |
|
42 more details.</p></section> |
|
43 <section><title>BYTE/WORD keywords</title><p><codeph>STRUCT</codeph> definitions |
|
44 allow resource instances to be of variable length, as the struct can allow |
|
45 default variables for its members. A resource’s entire length can be deduced |
|
46 from the position of the next resource; this information is available in a |
|
47 resource file’s index. If the resource is used as a member within an instance |
|
48 of another resource, however, its length <i>must</i> be identified another |
|
49 way.</p><ul> |
|
50 <li id="GUID-6EBE2158-D5F4-588F-B45E-94AB86D87547"><p>Use <codeph>BYTE</codeph> to |
|
51 prefix the struct with a single byte indicating its length (zero to 255 characters).</p> </li> |
|
52 <li id="GUID-43D2F295-C031-5812-A0BD-5F017C20918B"><p>Use <codeph>WORD</codeph> to |
|
53 prefix the struct with a word indicating its length (zero to 65,535 characters).</p> </li> |
|
54 </ul></section> |
|
55 <example><p>The following are valid <codeph>STRUCT</codeph> statements:</p><codeblock id="GUID-04C66589-84AC-591F-80A3-73FC1C973F4C" xml:space="preserve">STRUCT STRING |
|
56 { |
|
57 LTEXT str; |
|
58 }</codeblock><p>This defines a struct called <codeph>STRING</codeph> which |
|
59 contains a single <codeph>LTEXT</codeph> item.</p><codeblock id="GUID-C85D999C-4E6A-57B8-ACFB-E6A7DB51E960" xml:space="preserve">STRUCT TEST BYTE |
|
60 { |
|
61 WORD status; |
|
62 STRUCT text; |
|
63 }</codeblock><p>This defines a struct called <codeph>TEST</codeph> which |
|
64 contains a <codeph>WORD</codeph> and an embedded struct. The total length |
|
65 of <codeph>TEST</codeph> is unknown, but should not exceed 255 characters: |
|
66 the <codeph>BYTE</codeph> directive in the definition indicates that, when |
|
67 this struct is embedded within another, it should be preceded with a byte |
|
68 indicating its length (zero to 255 characters).</p></example> |
|
69 </conbody></concept> |
|