Categories: Symbian C++ | Essential Idioms

This page was last modified 09:11, 11 December 2007.

From Forum Nokia Wiki

The set of descriptors described are those originally included in Symbian OS. These provide for a wide range of requirements and situations: constant, unmodifiable descriptors for strings embedded in applications, stack-based descriptors for manipulating short strings, heap-based descriptors for strings that may grow or shrink, pointer descriptors for ROM-based resources etc. Of the five concrete descriptor classes initially available, the only omission was that of a modifiable heap-based descriptor. Thus, just as TBufC has the modifiable TBuf, and similarly TPtrC has TPtr, a companion for HBufC was required. Although there is a way to modify the data in an HBufC, (using the Des() method and maintaining a companion TPtr), the RBuf descriptor, which is derived from TDes as shown below, was introduced in version 8.0 (and documented in the Symbian Developer Library from version 8.1)..

An RBuf is particularly useful as all those temporary or companion TPtrs (required to alter the contents of an HBufC) become completely unnecessary, because RBuf both acts as a TPtr, but also owns the underlying heap object, hence replaces the HBufC*.

Similarly to an HBufC, an RBuf object can allocate its own buffer on construction. It can also take ownership of a pre-existing section of allocated memory or a pre-existing heap descriptor. Since it’s derived from TDes, an RBuf object can easily be modified, and additionally can be passed to any function where a TDes or TDesC parameter is specified.

Internally, RBuf behaves in one of two ways: • as a TPtr descriptor type, where the buffer just contains data • as a pointer to a heap descriptor (an HBufC* type) where the buffer contains both descriptor information and the data. The handling of the distinction is hidden from view. Since RBuf behaves like an HBufC, it’s possible to create an RBuf from an existing HBufC, making it easy to move code over to the new class.

RBuf descriptors can live on the stack, but maintain a pointer to memory in the heap. On the stack, they take up 8 bytes more than an HBufC* (i.e. 3 words rather than 1), but will generally take up 4 bytes less heap space (if not constructed from an existing HBufC). The new descriptor is not named HBuf because, unlike HBufC, objects of this type are not themselves directly created on the heap (the H prefix stands for heap); choosing an R<class> name carries the implication that the class owns the resources (in this case a Buf) that it manages and is responsible for freeing the memory when it closes. RBuf descriptors were introduced in Symbian OS v9 and backported to v8.1 and v8.0.

Information on RBuf can get from here http://developer.symbian.com/main/downloads/papers/RBuf/Introduction_to_RBuf_v1.0.pdf.