![Symbian Developer Library](../../../../../../../a_stock/images/mainheading.gif)
![]() |
![]() |
|
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 OS 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.