diff -r 80ef3a206772 -r 48780e181b38 Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita --- a/Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita Fri Jul 16 17:23:46 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita Tue Jul 20 12:00:49 2010 +0100 @@ -1,86 +1,80 @@ - - - - - -Descriptors -OverviewThis document provides an overview of descriptors. -
Purpose

Manipulates -string and data buffers.

-
Description

Descriptors -are a family of classes that are used in Symbian platform for string handling. -They are used in preference to NULL-terminated C strings. The same classes -are used for general binary data.

The basic classification of descriptor -types is given below. Concrete descriptor classes implement variations on -these basic types for different data widths and for different abilities to -modify the data. The names of the concrete classes follow certain naming conventions -that modify the basic name given in the table.

Basic -classification

- - - -

Type

-

Description

-

Basic name

- - -

abstract

-

Base interface: allows descriptors of different types to be use -polymorphically

-

TDes

- - -

buffer

-

Stack based: contains the data as part of itself. Buffer descriptors -have a maximum length set at compile time.

-

TBuf

- - -

pointer

-

Refer to data stored elsewhere that is not owned by the descriptor

-

TPtr

- - -

heap

-

Refers to data stored on the heap that is owned by the descriptor. -The maximum length of this data can be set and changed dynamically.

-

HBufC

RBuf

- - - -

Width

Descriptor -types can store 8-bit or 16-bit data. These types are indicated by the convention -of appending 8 or 16 on the basic name, e.g. TDes16. In -practice, the basic names correspond to 16-bit types, for example TBuf is -defined to be TBuf16.

Modifiable and non-modifiable

Modifiable descriptor types -have an interface that allows callers to alter their contents, such as appending -characters.

Non-modifiable descriptor types can have their contents -reset, but not modified. The convention is for non-modifiable types to append -a C on the basic name, e.g. TBufC.

Heap type descriptors -are an exceptional case: they are available only in the non-modifiable form, -but can, nevertheless, be modified through use of a pointer: see HBufC::Des(). -Alternatively, you can use the RBuf descriptor, which is -simpler to use than HBufC. The general rule is:

    -

  • use HBufC for -data that rarely changes.

    • -

  • Use RBuf for -data that changes frequently.

    • -

Example code

For -examples, see:

    -

  • Descriptor Example -Code

    • -

  • Descriptors -Cookbook at the Symbian Foundation.

    • -

  • S60 Platform: Descriptor Example v2.1 on Forum Nokia.

    • -
-
See also

Character Representation -Of Real Numbers Overview

Dynamic -Buffers Overview

Literals -Overview

+ + + + + +Descriptors OverviewThis document provides an overview of descriptors. +
Purpose

Manipulates string and data buffers.

+
Description

Descriptors are a family of classes that are used in Symbian +platform for string handling. They are used in preference to NULL-terminated +C strings. The same classes are used for general binary data.

The basic classification of descriptor types is given below. +Concrete descriptor classes implement variations on these basic types +for different data widths and for different abilities to modify the +data. The names of the concrete classes follow certain naming conventions +that modify the basic name given in the table.

Basic classification

+ + + + +

Type

+

Description

+

Basic name

+ + +

abstract

+

Base interface: allows descriptors of different types to +be use polymorphically

+

TDes

+ + +

buffer

+

Stack based: contains the data as part of itself. Buffer +descriptors have a maximum length set at compile time.

+

TBuf

+ + +

pointer

+

Refer to data stored elsewhere that is not owned by the +descriptor

+

TPtr

+ + +

heap

+

Refers to data stored on the heap that is owned by the descriptor. +The maximum length of this data can be set and changed dynamically.

+

HBufC

RBuf

+ + + +

Width

Descriptor types can store 8-bit or 16-bit data. +These types are indicated by the convention of appending 8 or 16 on +the basic name, e.g. TDes16. In practice, the basic +names correspond to 16-bit types, for example TBuf is defined to be TBuf16.

Modifiable and non-modifiable

Modifiable descriptor +types have an interface that allows callers to alter their contents, +such as appending characters.

Non-modifiable descriptor types +can have their contents reset, but not modified. The convention is +for non-modifiable types to append a C on the basic name, e.g. TBufC.

Heap type descriptors are an exceptional +case: they are available only in the non-modifiable form, but can, +nevertheless, be modified through use of a pointer: see HBufC::Des(). Alternatively, you can use the RBuf descriptor, +which is simpler to use than HBufC. The general rule +is:

    +

  • Use HBufC for data that rarely changes.

    • +

  • Use RBuf for data that changes frequently.

    • +

Example code

For +examples, see:

    +

  • Descriptor +Example Code

    • +

  • Descriptors Cookbook at the Symbian Foundation.

    • +

  • S60 Platform: Descriptor Example v2.1 on Forum +Nokia.

    • +
+
See +also

Character Representation Of Real Numbers Overview

Dynamic Buffers +Overview

Literals Overview

\ No newline at end of file