Resizable +buffer descriptors

diff -r 000000000000 -r 89d6a7a84779 Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita Thu Jan 21 18:18:20 2010 +0000 @@ -0,0 +1,89 @@ + + + + + +Resizable +buffer descriptorsDescribes 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 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.

+ \ No newline at end of file