diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita --- a/Symbian3/PDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,86 +1,86 @@ - - - - - -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