Descriptors Overview

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

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