Resizable -buffer descriptors

diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita --- a/Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +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 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.

+ + + + + +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 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.

\ No newline at end of file