STRUCT +member types

diff -r 000000000000 -r 89d6a7a84779 Symbian3/SDK/Source/GUID-89ADFC64-AF9F-51B1-AC5F-493897226270.dita --- /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 @@ + + + + + +STRUCT +member types +<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 +

Member declaration

Each member of a struct is identified by a member-declaration followed +by an optional initialiser, and then a semi-colon.

The simplest form of member-declaration is to specify +a type-name and a member-name only:

+STRUCT TEST + { + WORD length; + } +

Type name

The type-name must be in upper case (WORD in +this example).

These are the valid types:

+ + + + +

BYTE

A single byte.

Can be treated as a signed integer (–128 +to +127) or unsigned integer (0 to 255).

+ + +

WORD

Two bytes.

Can be treated as a signed integer (–32,768 to ++32,767) or unsigned integer (0 to 65,535).

+ + +

LONG

Four bytes.

Can be treated as a signed integer (–2,147,483,648 +to 2147483647) or an unsigned integer (0 to 4,294,967,295).

+ + +

DOUBLE

Eight byte real for double precision floating point numbers (approximately +±1.7E±308).

+ + +

TEXT

A string, terminated by a null.

This is deprecated: use LTEXT instead.

+ + +

LTEXT

A Unicode string with a leading byte which holds the length of the +string, and no terminating null.

+ + +

BUF

A Unicode string with no terminating null and no leading byte.

+ + +

BUF8

A string of 8-bit characters, with no terminating null and no leading +byte. Used for putting 8-bit data into a resource.

+ + +

BUF<n>

A Unicode string with no terminating null and no leading byte but +which has a maximum length n.

This type is an alternative +to using the length-limit with BUF types.

+ + +

LINK

The ID of another resource (16 bits), rather like a pointer to that +resource.

+ + +

LLINK

The ID of another resource (32 bits).

+ + +

SRLINK

A self-referencing link. This is a 32 bit link which contains the +resource ID of the resource it is defined in.

An SRLINK member +may not have an initialiser 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.

+ + +

STRUCT

Any struct, rather like including that struct as a member in this +struct.

STRUCT members are useful because it means +that once a struct has been defined it can be re-used for a variety of resources.

+ + + +

Note that:

Numbers more than one +byte long are stored little-endian: that is, their least significant byte +is stored first.
LINK and STRUCT 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:
STRUCT TEST + { + WORD length; + STRUCT text; // should be a STRING + }

Length limits

A length limit may be specified for members of string type (BUF, TEXT and LTEXT). +The length limit is enclosed in parentheses after the member name, for instance:

+STRUCT TEST + { + TEXT string1(9); + LTEXT string2(MAX); + BUF string3; + } +

string1 has +a maximum of 9 characters, string2 a maximum of MAX characters +(where MAX has been #defined elsewhere) +and string3 has no maximum length. Note that this maximum +applies only to the actual characters and does not take account of the terminating +zero (for TEXT members) or leading byte (for LTEXT members).
Note that from v5 onwards, TEXT is +deprecated.
An alternative method +to using length-limit with a BUF type +is to use the type BUF<n>. For example, see the definition +of TEST and the resource definitions for test1, test2 and test3 in +the examples below.

Member name

The member-name must be in lower case.

+STRUCT TEST + { + BUF<4> string; + }RESOURCE TEST test1 + { + string="abcd"; + }RESOURCE TEST test2 + { + string="ab"; + }RESOURCE TEST test3 + { + string="abcdef"; + }

test1 generates 0x61 +0x00 0x62 0x00 0x63 0x00 0x64 0x00
test2 generates 0x61 +0x00 0x62 0x00
but test3 generates +an error because the maximum length of string permitted by +the definition of the STRUCT is 4.

+ \ No newline at end of file