--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,168 @@
+<?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"><struct-member>
+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<n> | 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<n></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<n></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>
\ No newline at end of file