<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-89ADFC64-AF9F-51B1-AC5F-493897226270" xml:lang="en"><title>STRUCT
member types</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<codeblock xml:space="preserve">&lt;struct-member&gt;
struct-member ::= 
&lt;member-declaration&gt; [ = &lt;initialiser&gt; ]; &lt;member-declaration&gt;
member-declaration ::= 
&lt;type-name&gt; &lt;member-name&gt; | [ LEN [ BYTE ] ] &lt;type-name&gt; &lt;member-name&gt; [ ( &lt;length-limit&gt; ) ] [ [ [ &lt;array-size&gt; ] ] ] &lt;type-name&gt;
type-name ::= 
BYTE | WORD | LONG | TEXT | DOUBLE | LTEXT | BUF | BUF8 | BUF&lt;n&gt; | LINK | SRLINK | STRUCT </codeblock>
<p><b>Member declaration</b> </p>
<p>Each member of a struct is identified by a <varname>member-declaration</varname> followed
by an optional <varname>initialiser</varname>, and then a semi-colon.</p>
<p>The simplest form of <varname>member-declaration</varname> is to specify
a <varname>type-name</varname> and a <varname>member-name</varname> only:</p>
<codeblock id="GUID-1137C4C8-B450-5ECA-97E5-8DECB8ABBB20" xml:space="preserve">STRUCT TEST
 {
 WORD length;
 }</codeblock>
<p><b>Type name</b> </p>
<p>The <varname>type-name</varname> must be in upper case (<codeph>WORD</codeph> in
this example).</p>
<p>These are the valid types:</p>
<table id="GUID-0611DEBC-6A5E-565A-8BDB-317C2CCCA24F">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p><codeph>BYTE</codeph> </p> </entry>
<entry><p>A single byte. </p> <p>Can be treated as a signed integer (–128
to +127) or unsigned integer (0 to 255).</p> </entry>
</row>
<row>
<entry><p><codeph>WORD</codeph> </p> </entry>
<entry><p>Two bytes. </p> <p>Can be treated as a signed integer (–32,768 to
+32,767) or unsigned integer (0 to 65,535).</p> </entry>
</row>
<row>
<entry><p><codeph>LONG</codeph> </p> </entry>
<entry><p>Four bytes. </p> <p>Can be treated as a signed integer (–2,147,483,648
to 2147483647) or an unsigned integer (0 to 4,294,967,295).</p> </entry>
</row>
<row>
<entry><p><codeph>DOUBLE</codeph> </p> </entry>
<entry><p>Eight byte real for double precision floating point numbers (approximately
±1.7E±308).</p> </entry>
</row>
<row>
<entry><p><codeph>TEXT</codeph> </p> </entry>
<entry><p>A string, terminated by a null. </p> <p>This is deprecated: use <codeph>LTEXT</codeph> instead.</p> </entry>
</row>
<row>
<entry><p><codeph>LTEXT</codeph> </p> </entry>
<entry><p>A Unicode string with a leading byte which holds the length of the
string, and no terminating null. </p> </entry>
</row>
<row>
<entry><p><codeph>BUF</codeph> </p> </entry>
<entry><p>A Unicode string with no terminating null and no leading byte.</p> </entry>
</row>
<row>
<entry><p><codeph>BUF8</codeph> </p> </entry>
<entry><p>A string of 8-bit characters, with no terminating null and no leading
byte. Used for putting 8-bit data into a resource.</p> </entry>
</row>
<row>
<entry><p><codeph>BUF&lt;n&gt;</codeph> </p> </entry>
<entry><p>A Unicode string with no terminating null and no leading byte but
which has a maximum length <codeph>n</codeph>. </p> <p>This type is an alternative
to using the length-limit with <codeph>BUF</codeph> types.</p> </entry>
</row>
<row>
<entry><p><codeph>LINK</codeph> </p> </entry>
<entry><p>The ID of another resource (16 bits), rather like a pointer to that
resource.</p> </entry>
</row>
<row>
<entry><p><codeph>LLINK</codeph> </p> </entry>
<entry><p>The ID of another resource (32 bits).</p> </entry>
</row>
<row>
<entry><p><codeph>SRLINK</codeph> </p> </entry>
<entry><p>A self-referencing link. This is a 32 bit link which contains the
resource ID of the resource it is defined in.</p> <p>An <codeph>SRLINK</codeph> member
may not have an <codeph>initialiser</codeph> since it is self-referencing
and, therefore, only takes the value of the resource ID the struct is declared
in. This is assigned automatically by the resource compiler.</p> </entry>
</row>
<row>
<entry><p><codeph>STRUCT</codeph> </p> </entry>
<entry><p>Any struct, rather like including that struct as a member in this
struct. </p> <p><codeph>STRUCT</codeph> members are useful because it means
that once a struct has been defined it can be re-used for a variety of resources.</p> </entry>
</row>
</tbody>
</tgroup>
</table>
<p>Note that:</p>
<ul>
<li id="GUID-CFC06150-A2AB-50E1-A309-841FD7A14A1F"><p>Numbers more than one
byte long are stored little-endian: that is, their least significant byte
is stored first.</p> </li>
<li id="GUID-B3054853-8740-5891-B05B-7F45C7C0D154"><p><codeph>LINK</codeph> and <codeph>STRUCT</codeph> are
not type-safe: it is the responsibility of the user of a struct to ensure
that the correct resource type is linked or included. The definer of a struct
should give some idea, perhaps using a comment:</p> <codeblock id="GUID-748ECC10-244C-513B-A417-BC1FF38DDA56" xml:space="preserve">STRUCT TEST
 {
 WORD length;
 STRUCT text; // should be a STRING 
 }</codeblock> </li>
</ul>
<p><b>Length limits</b> </p>
<p>A length limit may be specified for members of string type (<codeph>BUF</codeph>, <codeph>TEXT</codeph> and <codeph>LTEXT</codeph>).
The length limit is enclosed in parentheses after the member name, for instance:</p>
<codeblock id="GUID-50C68BAE-63AD-50D6-A97F-8181478CACB2" xml:space="preserve">STRUCT TEST
 {
 TEXT string1(9);
 LTEXT string2(MAX);
 BUF string3;
 }</codeblock>
<ul>
<li id="GUID-495CC55D-94BD-5775-9ADA-C548CC7BCE9E"><p><codeph>string1</codeph> has
a maximum of 9 characters, <codeph>string2</codeph> a maximum of <codeph>MAX</codeph> characters
(where <codeph>MAX</codeph> has been <codeph>#defined</codeph> elsewhere)
and <codeph>string3</codeph> has no maximum length. Note that this maximum
applies only to the actual characters and does not take account of the terminating
zero (for <codeph>TEXT</codeph> members) or leading byte (for <codeph>LTEXT</codeph> members).</p> </li>
<li id="GUID-C853D58D-EE65-5BA8-9F15-1DE1A57AC93A"><p>Note that from v5 onwards, <codeph>TEXT</codeph> is
deprecated.</p> </li>
<li id="GUID-1D3ADFB6-CC80-5951-9D9F-4CEFF86A2726"><p>An alternative method
to using <varname>length-limit</varname> with a <codeph>BUF</codeph> type
is to use the type <codeph>BUF&lt;n&gt;</codeph>. For example, see the definition
of <codeph>TEST</codeph> and the resource definitions for <codeph>test1</codeph>, <codeph>test2</codeph> and <codeph>test3</codeph> in
the examples below.</p> </li>
</ul>
<p><b>Member name</b> </p>
<p>The <varname>member-name</varname> must be in lower case.</p>
<example><codeblock id="GUID-0268988A-BB90-5926-AF3D-97016E53DBAD" xml:space="preserve">STRUCT TEST
 {
 BUF&lt;4&gt; string;
 }</codeblock><codeblock id="GUID-563A42B3-3B7C-550E-BBF5-DA845FFA7F6C" xml:space="preserve">RESOURCE TEST test1
 {
 string="abcd";
 }</codeblock><codeblock id="GUID-E76C4FB4-14D2-5BC2-B9C5-8065472E8191" xml:space="preserve">RESOURCE TEST test2
 {
 string="ab";
 }</codeblock><codeblock id="GUID-60CA1CB6-B228-54AF-9086-C66C2E61D2E4" xml:space="preserve">RESOURCE TEST test3
 {
 string="abcdef";
 }</codeblock><ul>
<li id="GUID-D23F56A1-591D-5025-BE84-D8B2BF7BA521"><p><codeph>test1</codeph> generates <codeph>0x61
0x00 0x62 0x00 0x63 0x00 0x64 0x00</codeph> </p> </li>
<li id="GUID-3BB272D8-5BD1-5759-81B8-C2160CBAFB5A"><p><codeph>test2</codeph> generates <codeph>0x61
0x00 0x62 0x00</codeph> </p> </li>
<li id="GUID-7637A3EB-06BB-563C-A5D4-6F70755E22CF"><p>but <codeph>test3</codeph> generates
an error because the maximum length of <codeph>string</codeph> permitted by
the definition of the <codeph>STRUCT</codeph> is 4.</p> </li>
</ul></example>
</conbody></concept>