Descriptors +Overview

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.