Resizable buffer descriptors

Describes descriptor behaviour and resizable buffer descriptors.

A resizable buffer descriptor provides a buffer, allocated on the heap, to contain and access data. The data is not part of the descriptor object.

The data represented by this descriptor can be both accessed and changed through the descriptor itself. Data is accessed through functions provided by the base class. The size of the buffer used by this descriptor can also be changed. Note that unlike dynamic buffers, reallocation is not done automatically; the descriptor provides an API that allows you to do reallocation.

The descriptor has similarities to the standard heap descriptor, HBufC, but is easier to use. The standard heap descriptor is recommended for use when the data it represents rarely changes. The resizable buffer descriptor is recommended for use when the data changes frequently.

This descriptor also has the following additional useful behaviour:

• ownership of an existing heap descriptor can be transferred to a resizable buffer descriptor.

• ownership of memory that has already been allocated elsewhere can be transferred to a resizable buffer descriptor; this memory becomes the buffer used by the descriptor.

• ownership of memory owned by a resizable buffer descriptor can be transferred to another resizable buffer descriptor.

The important point is that the user of the class need not be concerned about the 'origins' of the memory.

A resizable buffer descriptor is supplied in two variants:

• a 16-bit variant, a RBuf16, to contain wide strings, and 16-bit wide data.

• an 8-bit variant, a RBuf8, to contain narrow strings and binary data.

There is also a build independent type, RBuf. This is the type that is most commonly used in program code; this is set (i.e. typedef) to the appropriate 'real' variant at build time, and by default equates to RBuf16.

You would use an explicit 8-bit variant for binary data. An explicit 16-bit variant is rarely used.

When discussing a resizable buffer descriptor, we normally refer to RBuf, rather than RBuf8 or RBuf16. We only refer to RBuf8 or RBuf16 when they explicitly need to be used.

The following drawing shows how an RBuf type is constructed. It is derived from TDes and TDesC; the member data of these base classes hold the length and maximum length for the descriptor data. RBuf itself only contains a single pointer. The pointer is interpreted in one of two ways, depending on how its buffer has been set up:

• as a simple pointer to memory on the heap.

• as a pointer to a previously created HBufC heap descriptor; ownership of the HBufC descriptor buffer will have been transferred to the RBuf.

The way descriptors in Symbian platform are implemented allows RBuf to distinguish between the two.

The following drawing shows the internal representation of an RBuf object initialised with a string of five characters representing the English word "Hello". There are two possibilities:

• the case where the buffer consists of simple memory, either allocated directly by the object itself, or assigned to it after having been allocated elsewhere.

• the case where the buffer was originally allocated as a standard heap descriptor, a HBufC type, and whose ownership has been transferred.

Remember that RBuf is derived from both TDes and TDesC, and these classes provide the data members the contain the maximum length and the current length of the data.

While an RBuf descriptor has similarities to a heap descriptor, it behaves more like a standard 'R' type resource class, i.e. as a handle to a real resource maintained elsewhere.