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-89ADFC64-AF9F-51B1-AC5F-493897226270" xml:lang="en"><title>STRUCT |
|
13 member types</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <codeblock xml:space="preserve"><struct-member> |
|
15 struct-member ::= |
|
16 <member-declaration> [ = <initialiser> ]; <member-declaration> |
|
17 member-declaration ::= |
|
18 <type-name> <member-name> | [ LEN [ BYTE ] ] <type-name> <member-name> [ ( <length-limit> ) ] [ [ [ <array-size> ] ] ] <type-name> |
|
19 type-name ::= |
|
20 BYTE | WORD | LONG | TEXT | DOUBLE | LTEXT | BUF | BUF8 | BUF<n> | LINK | SRLINK | STRUCT </codeblock> |
|
21 <p><b>Member declaration</b> </p> |
|
22 <p>Each member of a struct is identified by a <varname>member-declaration</varname> followed |
|
23 by an optional <varname>initialiser</varname>, and then a semi-colon.</p> |
|
24 <p>The simplest form of <varname>member-declaration</varname> is to specify |
|
25 a <varname>type-name</varname> and a <varname>member-name</varname> only:</p> |
|
26 <codeblock id="GUID-1137C4C8-B450-5ECA-97E5-8DECB8ABBB20" xml:space="preserve">STRUCT TEST |
|
27 { |
|
28 WORD length; |
|
29 }</codeblock> |
|
30 <p><b>Type name</b> </p> |
|
31 <p>The <varname>type-name</varname> must be in upper case (<codeph>WORD</codeph> in |
|
32 this example).</p> |
|
33 <p>These are the valid types:</p> |
|
34 <table id="GUID-0611DEBC-6A5E-565A-8BDB-317C2CCCA24F"> |
|
35 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
36 <tbody> |
|
37 <row> |
|
38 <entry><p><codeph>BYTE</codeph> </p> </entry> |
|
39 <entry><p>A single byte. </p> <p>Can be treated as a signed integer (–128 |
|
40 to +127) or unsigned integer (0 to 255).</p> </entry> |
|
41 </row> |
|
42 <row> |
|
43 <entry><p><codeph>WORD</codeph> </p> </entry> |
|
44 <entry><p>Two bytes. </p> <p>Can be treated as a signed integer (–32,768 to |
|
45 +32,767) or unsigned integer (0 to 65,535).</p> </entry> |
|
46 </row> |
|
47 <row> |
|
48 <entry><p><codeph>LONG</codeph> </p> </entry> |
|
49 <entry><p>Four bytes. </p> <p>Can be treated as a signed integer (–2,147,483,648 |
|
50 to 2147483647) or an unsigned integer (0 to 4,294,967,295).</p> </entry> |
|
51 </row> |
|
52 <row> |
|
53 <entry><p><codeph>DOUBLE</codeph> </p> </entry> |
|
54 <entry><p>Eight byte real for double precision floating point numbers (approximately |
|
55 ±1.7E±308).</p> </entry> |
|
56 </row> |
|
57 <row> |
|
58 <entry><p><codeph>TEXT</codeph> </p> </entry> |
|
59 <entry><p>A string, terminated by a null. </p> <p>This is deprecated: use <codeph>LTEXT</codeph> instead.</p> </entry> |
|
60 </row> |
|
61 <row> |
|
62 <entry><p><codeph>LTEXT</codeph> </p> </entry> |
|
63 <entry><p>A Unicode string with a leading byte which holds the length of the |
|
64 string, and no terminating null. </p> </entry> |
|
65 </row> |
|
66 <row> |
|
67 <entry><p><codeph>BUF</codeph> </p> </entry> |
|
68 <entry><p>A Unicode string with no terminating null and no leading byte.</p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p><codeph>BUF8</codeph> </p> </entry> |
|
72 <entry><p>A string of 8-bit characters, with no terminating null and no leading |
|
73 byte. Used for putting 8-bit data into a resource.</p> </entry> |
|
74 </row> |
|
75 <row> |
|
76 <entry><p><codeph>BUF<n></codeph> </p> </entry> |
|
77 <entry><p>A Unicode string with no terminating null and no leading byte but |
|
78 which has a maximum length <codeph>n</codeph>. </p> <p>This type is an alternative |
|
79 to using the length-limit with <codeph>BUF</codeph> types.</p> </entry> |
|
80 </row> |
|
81 <row> |
|
82 <entry><p><codeph>LINK</codeph> </p> </entry> |
|
83 <entry><p>The ID of another resource (16 bits), rather like a pointer to that |
|
84 resource.</p> </entry> |
|
85 </row> |
|
86 <row> |
|
87 <entry><p><codeph>LLINK</codeph> </p> </entry> |
|
88 <entry><p>The ID of another resource (32 bits).</p> </entry> |
|
89 </row> |
|
90 <row> |
|
91 <entry><p><codeph>SRLINK</codeph> </p> </entry> |
|
92 <entry><p>A self-referencing link. This is a 32 bit link which contains the |
|
93 resource ID of the resource it is defined in.</p> <p>An <codeph>SRLINK</codeph> member |
|
94 may not have an <codeph>initialiser</codeph> since it is self-referencing |
|
95 and, therefore, only takes the value of the resource ID the struct is declared |
|
96 in. This is assigned automatically by the resource compiler.</p> </entry> |
|
97 </row> |
|
98 <row> |
|
99 <entry><p><codeph>STRUCT</codeph> </p> </entry> |
|
100 <entry><p>Any struct, rather like including that struct as a member in this |
|
101 struct. </p> <p><codeph>STRUCT</codeph> members are useful because it means |
|
102 that once a struct has been defined it can be re-used for a variety of resources.</p> </entry> |
|
103 </row> |
|
104 </tbody> |
|
105 </tgroup> |
|
106 </table> |
|
107 <p>Note that:</p> |
|
108 <ul> |
|
109 <li id="GUID-CFC06150-A2AB-50E1-A309-841FD7A14A1F"><p>Numbers more than one |
|
110 byte long are stored little-endian: that is, their least significant byte |
|
111 is stored first.</p> </li> |
|
112 <li id="GUID-B3054853-8740-5891-B05B-7F45C7C0D154"><p><codeph>LINK</codeph> and <codeph>STRUCT</codeph> are |
|
113 not type-safe: it is the responsibility of the user of a struct to ensure |
|
114 that the correct resource type is linked or included. The definer of a struct |
|
115 should give some idea, perhaps using a comment:</p> <codeblock id="GUID-748ECC10-244C-513B-A417-BC1FF38DDA56" xml:space="preserve">STRUCT TEST |
|
116 { |
|
117 WORD length; |
|
118 STRUCT text; // should be a STRING |
|
119 }</codeblock> </li> |
|
120 </ul> |
|
121 <p><b>Length limits</b> </p> |
|
122 <p>A length limit may be specified for members of string type (<codeph>BUF</codeph>, <codeph>TEXT</codeph> and <codeph>LTEXT</codeph>). |
|
123 The length limit is enclosed in parentheses after the member name, for instance:</p> |
|
124 <codeblock id="GUID-50C68BAE-63AD-50D6-A97F-8181478CACB2" xml:space="preserve">STRUCT TEST |
|
125 { |
|
126 TEXT string1(9); |
|
127 LTEXT string2(MAX); |
|
128 BUF string3; |
|
129 }</codeblock> |
|
130 <ul> |
|
131 <li id="GUID-495CC55D-94BD-5775-9ADA-C548CC7BCE9E"><p><codeph>string1</codeph> has |
|
132 a maximum of 9 characters, <codeph>string2</codeph> a maximum of <codeph>MAX</codeph> characters |
|
133 (where <codeph>MAX</codeph> has been <codeph>#defined</codeph> elsewhere) |
|
134 and <codeph>string3</codeph> has no maximum length. Note that this maximum |
|
135 applies only to the actual characters and does not take account of the terminating |
|
136 zero (for <codeph>TEXT</codeph> members) or leading byte (for <codeph>LTEXT</codeph> members).</p> </li> |
|
137 <li id="GUID-C853D58D-EE65-5BA8-9F15-1DE1A57AC93A"><p>Note that from v5 onwards, <codeph>TEXT</codeph> is |
|
138 deprecated.</p> </li> |
|
139 <li id="GUID-1D3ADFB6-CC80-5951-9D9F-4CEFF86A2726"><p>An alternative method |
|
140 to using <varname>length-limit</varname> with a <codeph>BUF</codeph> type |
|
141 is to use the type <codeph>BUF<n></codeph>. For example, see the definition |
|
142 of <codeph>TEST</codeph> and the resource definitions for <codeph>test1</codeph>, <codeph>test2</codeph> and <codeph>test3</codeph> in |
|
143 the examples below.</p> </li> |
|
144 </ul> |
|
145 <p><b>Member name</b> </p> |
|
146 <p>The <varname>member-name</varname> must be in lower case.</p> |
|
147 <example><codeblock id="GUID-0268988A-BB90-5926-AF3D-97016E53DBAD" xml:space="preserve">STRUCT TEST |
|
148 { |
|
149 BUF<4> string; |
|
150 }</codeblock><codeblock id="GUID-563A42B3-3B7C-550E-BBF5-DA845FFA7F6C" xml:space="preserve">RESOURCE TEST test1 |
|
151 { |
|
152 string="abcd"; |
|
153 }</codeblock><codeblock id="GUID-E76C4FB4-14D2-5BC2-B9C5-8065472E8191" xml:space="preserve">RESOURCE TEST test2 |
|
154 { |
|
155 string="ab"; |
|
156 }</codeblock><codeblock id="GUID-60CA1CB6-B228-54AF-9086-C66C2E61D2E4" xml:space="preserve">RESOURCE TEST test3 |
|
157 { |
|
158 string="abcdef"; |
|
159 }</codeblock><ul> |
|
160 <li id="GUID-D23F56A1-591D-5025-BE84-D8B2BF7BA521"><p><codeph>test1</codeph> generates <codeph>0x61 |
|
161 0x00 0x62 0x00 0x63 0x00 0x64 0x00</codeph> </p> </li> |
|
162 <li id="GUID-3BB272D8-5BD1-5759-81B8-C2160CBAFB5A"><p><codeph>test2</codeph> generates <codeph>0x61 |
|
163 0x00 0x62 0x00</codeph> </p> </li> |
|
164 <li id="GUID-7637A3EB-06BB-563C-A5D4-6F70755E22CF"><p>but <codeph>test3</codeph> generates |
|
165 an error because the maximum length of <codeph>string</codeph> permitted by |
|
166 the definition of the <codeph>STRUCT</codeph> is 4.</p> </li> |
|
167 </ul></example> |
|
168 </conbody></concept> |
|