How to use the heap descriptor

- -

Some key points about heap descriptors:

For text data, it is usual to construct a <code>HBufC</code> type and allow the appropriate variant, either a <code>HBufC8</code> or a HBufC16 to be selected at build time.
For binary data, an explicit HBufC8 is used.
It is rare to use an explicit HBufC16.
Data cannot be changed through this descriptor although it can be - replaced using the assignment operators. -
If you need to pass an HBufC to a function that takes a TDesC& parameter, simply dereference the HBufC pointer.
If you need to modify the HBufC's data, use its Des() function to construct a TPtr/TPtr8/TPtr16 modifiable pointer descriptor for the buffer's data.
The size of the heap descriptor buffer can be replaced by - reallocating it with a new length. -

Although the following notes refer to the build independent types, they are equally valid for the 8 bit and 16 bit types.

- - -

- Constructing an <codeph>HBufC</codeph> -

- A heap descriptor can be constructed in one of two ways: -

- -

-
- using the static member functions New(), - NewL() or NewLC() -
-
-
- using the Alloc(), AllocL() or - AllocLC() functions of an existing descriptor -
-

- -

- The following code fragment constructs a heap descriptor which can hold up to 15 data items. The current length is zero. -

- HBufC* buf; -... -buf = HBufC::NewL(15); -

- The following code fragment constructs a heap descriptor from an existing descriptor. The new heap descriptor is initialised with the content of - buf1, i.e. the string: "Hello World!" -

- The source descriptor is a literal which is converted to descriptor type. -

- _LIT(KText,"Hello World!"); -TBufC<16> buf1(KText); -... -HBufC* hptr; -hptr = buf1.AllocL(); -... -

- -

- Replacing data and re-allocating -

- Although existing data within a heap descriptor cannot be modified, the - assignment operator can be used to replace that data. -

- _LIT(KText,"Hello World!"); -... -HBufC* buf; -... -buf = HBufC::NewL(15); -*buf = KText; -

- The source descriptor is a literal which is converted to descriptor - type. -

- To allow more than 15 characters or data items to be assigned into the - heap descriptor, it must be reallocated: -

- buf = buf->ReAllocL(20); -

- This permits the following assignment to be done without raising a - panic: -

- _LIT(KNewText,"Hello World! Morning"); -... -*buf = KNewText; -

- buf may or may not point to a different location in the - heap after reallocation. The location of the reallocated descriptor depends on - the heap fragmentation and the size of the new cell. It is always safer to - assume that the location changes. -

- -

- Changing data through a modifiable pointer descriptor. -

- The data contained by a heap descriptor can be changed by - constructing a TPtr modifiable pointer descriptor using the - Des() member function and then changing the data through that - TPtr. -

- The maximum length of the TPtr is determined from the size - of the cell allocated to the data area of the heap descriptor. -

- The following code fragment changes the data in the heap descriptor and - the length of the heap descriptor. -

- TPtr ptr = buf->Des(); -... -ptr.Delete((ptr.Length()-9),9); -ptr.Append(_LIT(" & Hi")); -

- Take particular care if a the heap descriptor is re-allocated after the - TPtr has been constructed. A TPtr created before - re-allocating the heap descriptor is not guaranteed to have a valid pointer - after re-allocation. Any attempt to modify data through the original - TPtr after re-allocation may have undefined consequences. -

it is a common error to use Des() to create a - TDesC& reference. While not incorrect, it is simpler and much - more efficient to simply dereference the heap descriptor. - -

+ + + + + +How to use the heap descriptor - HBufCHeap descriptors provide a buffer of fixed length, allocated on the heap. Descriptors are useful for holding constant strings or data, when the length of the data may not be known until run time. + +

Some key points about heap descriptors:

For text data, it is usual to construct a <code>HBufC</code> type and allow the appropriate variant, either a <code>HBufC8</code> or a HBufC16 to be selected at build time.
For binary data, an explicit HBufC8 is used.
It is rare to use an explicit HBufC16.
Data cannot be changed through this descriptor although it can be + replaced using the assignment operators. +
If you need to pass an HBufC to a function that takes a TDesC& parameter, simply dereference the HBufC pointer.
If you need to modify the HBufC's data, use its Des() function to construct a TPtr/TPtr8/TPtr16 modifiable pointer descriptor for the buffer's data.
The size of the heap descriptor buffer can be replaced by + reallocating it with a new length. +

Although the following notes refer to the build independent types, they are equally valid for the 8 bit and 16 bit types.

+ + +

+ Constructing an <codeph>HBufC</codeph> +

+ A heap descriptor can be constructed in one of two ways: +

+ +

+
+ using the static member functions New(), + NewL() or NewLC() +
+
+
+ using the Alloc(), AllocL() or + AllocLC() functions of an existing descriptor +
+

+ +

+ The following code fragment constructs a heap descriptor which can hold up to 15 data items. The current length is zero. +

+ HBufC* buf; +... +buf = HBufC::NewL(15); +

+ The following code fragment constructs a heap descriptor from an existing descriptor. The new heap descriptor is initialised with the content of + buf1, i.e. the string: "Hello World!" +

+ The source descriptor is a literal which is converted to descriptor type. +

+ _LIT(KText,"Hello World!"); +TBufC<16> buf1(KText); +... +HBufC* hptr; +hptr = buf1.AllocL(); +... +

+ +

+ Replacing data and re-allocating +

+ Although existing data within a heap descriptor cannot be modified, the + assignment operator can be used to replace that data. +

+ _LIT(KText,"Hello World!"); +... +HBufC* buf; +... +buf = HBufC::NewL(15); +*buf = KText; +

+ The source descriptor is a literal which is converted to descriptor + type. +

+ To allow more than 15 characters or data items to be assigned into the + heap descriptor, it must be reallocated: +

+ buf = buf->ReAllocL(20); +

+ This permits the following assignment to be done without raising a + panic: +

+ _LIT(KNewText,"Hello World! Morning"); +... +*buf = KNewText; +

+ buf may or may not point to a different location in the + heap after reallocation. The location of the reallocated descriptor depends on + the heap fragmentation and the size of the new cell. It is always safer to + assume that the location changes. +

+ +

+ Changing data through a modifiable pointer descriptor. +

+ The data contained by a heap descriptor can be changed by + constructing a TPtr modifiable pointer descriptor using the + Des() member function and then changing the data through that + TPtr. +

+ The maximum length of the TPtr is determined from the size + of the cell allocated to the data area of the heap descriptor. +

+ The following code fragment changes the data in the heap descriptor and + the length of the heap descriptor. +

+ TPtr ptr = buf->Des(); +... +ptr.Delete((ptr.Length()-9),9); +ptr.Append(_LIT(" & Hi")); +

+ Take particular care if a the heap descriptor is re-allocated after the + TPtr has been constructed. A TPtr created before + re-allocating the heap descriptor is not guaranteed to have a valid pointer + after re-allocation. Any attempt to modify data through the original + TPtr after re-allocation may have undefined consequences. +

it is a common error to use Des() to create a + TDesC& reference. While not incorrect, it is simpler and much + more efficient to simply dereference the heap descriptor. + +

\ No newline at end of file