Symbian OS Developers

Using RBuf

• Project Management Template Kit

RBuf objects can be instantiated using the Create(), CreateMax() or CreateL() methods to specify the maximum length of descriptor data that can be stored. It is also possible to instantiate an RBuf and copy the contents of another descriptor into it, as follows:

CreateL() allocates a buffer for the RBuf to reference. If that RBuf previously owned a buffer, CreateL() will not clean it up before assigning the new buffer reference, so this must be done first by calling Close() to free any pre-existing owned memory.

Alternatively, an RBuf can be instantiated and take ownership of a pre-existing section of memory using the Assign() method.

Assign() will also orphan any data already owned by the RBuf, so Close() should be called before reassignment, to avoid memory leaks.

The RBuf class doesn't manage the size of the buffer or reallocate it if more memory is required for a particular operation. If a modification method, such as Append(), is called on an RBuf object for which there is insufficient memory available, a panic will occur. As a programmer, you are responsible for making sure that the RBuf object has sufficient space in its internal buffer, by using the ReAllocL() method if necessary:

// myRBuf is the buffer to be resized e.g. for an Append() operation myRBuf.CleanupClosePushL(); // push onto cleanup stack for leave-safety myRBuf.ReAllocL(newLength); // extend to newLength CleanupStack::Pop(); // remove from cleanup stack

Note that the previous example uses the CleanupClosePushL() method of the RBuf class to push it onto the cleanup stack. As is usual for other R classes, cleanup is performed by calling Close() (or CleanupStack::PopAndDestroy() if the RBuf was pushed onto the cleanup stack by a call to RBuf::CleanupClosePushL()).