Descriptors FAQ

Heap-based descriptors, HBufC<n>, can be used for dynamic allocation of string data whose size is not known at compile time. It should also be used to store string data too large for the stack. In effect, HBufC should be used where malloc’d data would be used in C.

Although the class representing these descriptors is HBufC, these descriptors are always referred to by pointer, HBufC*. The class doesn’t comply with the standard Symbian OS naming conventions, but then, it doesn’t really fit any of the standard Symbian OS types exactly. It is simply prefixed with H to indicate that the data is stored on the heap.

HBufC can be created using one of the static NewL() functions of the class. These may leave if there is insufficient memory available (the non-leaving version will return NULL). The heap buffers must be constructed using one of these methods or by using one of the Alloc() or AllocL() methods of the TDesC class to spawn an HBufC copy of any descriptor.

The ‘C’ suffix in the class name indicates that these descriptors are constant, although, in common with the stack-based non-modifiable buffer descriptors, the class has a set of assignment operators to allow the entire contents of the buffer to be replaced (as long as the new data does not exceed the length of the heap cell originally allocated). In addition, as with TBufC, the heap-based descriptors can be manipulated at runtime by creating a modifiable pointer descriptor, TPtr over the heap buffer, using the Des() method. For example:

_LIT(KFred, "Fred");
// Allocate an empty heap descriptor of max length 4
HBufC* heapBuf = HBufC::NewL(4);
// Copy in the contents of KFred
*heapBuf = KFred; // heapBuf now contains "Fred"
// Or, a more direct alternative:
HBufC* heapBuf = KFred().AllocL();

_LIT(KBert, "Bert");
TPtr ptr(heapBuf->Des()); // Modifiable TPtr over heapBuf data area
ptr = KBert(); // Copies "Bert" into heapBuf
delete heapBuf; // heapBuf deleted - ptr is now invalid

The heap descriptors can be created dynamically to the size required, but are not automatically resized when additional data storage is needed. Instead, you must make sure the buffer has sufficient memory before calling a modification operation. If necessary, you can reallocate the buffer, to grow it to the desired size, using the set of ReAllocL() methods. These may potentially move the buffer from its previous memory location. If there is insufficient memory, they will leave.

_LIT(KFred, "Fred");
// Allocate a heap descriptor of max length 4
HBufC* heapBuf = KFred().AllocLC();

_LIT(KCyril, "Cyril");
TPtr ptr(heapBuf->Des()); // Modifiable TPtr over heapBuf data area
ptr = KCyril(); // This would panic because max length (4) is exceeded

// Instead, we need to do a reallocation
// Leave on cleanup stack in case the realloc fails and a leave occurs
heapBuf = heapBuf->ReAllocL(5);

// Realloc succeeded, but heapBuf pointer may have changed
// We must update the pointer stored on the cleanup stack
CleanupStack::Pop(); // Push it off
// Push it back on again
CleanupStack::PushL(heapBuf);

// Since realloc may have changed the location in memory
// we must also reset ptr
ptr.Set(heapBuf->Des());
ptr = KCyril(); // Copies "Cyril" into heapBuf

CleanupStack::PopAndDestroy(heapBuf); // heapBuf destroyed

Moral of the story
Heap descriptors can be created dynamically but are not automatically resized should they need to be extended.