<?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 ::= 

<member-declaration> [ = <initialiser> ]; <member-declaration>

member-declaration ::= 

<type-name> <member-name> | [ LEN [ BYTE ] ] <type-name> <member-name> [ ( <length-limit> ) ] [ [ [ <array-size> ] ] ] <type-name>

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<4> 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>