CBufBase Class Reference

#include <e32base.h>

Link against: euser_v5.lib

class CBufBase : public CBase

Inherits from

Protected Attributes
TInt iExpandSize
TInt iSize
Public Member Functions
~CBufBase()
pure virtual TPtr8 BackPtr(TInt)
pure virtual voidCompress()
pure virtual voidDelete(TInt, TInt)
IMPORT_C voidExpandL(TInt, TInt)
IMPORT_C voidInsertL(TInt, const TDesC8 &)
IMPORT_C voidInsertL(TInt, const TDesC8 &, TInt)
IMPORT_C voidInsertL(TInt, const TAny *, TInt)
pure virtual TPtr8 Ptr(TInt)
IMPORT_C voidRead(TInt, TDes8 &)
IMPORT_C voidRead(TInt, TDes8 &, TInt)
IMPORT_C voidRead(TInt, TAny *, TInt)
IMPORT_C voidReset()
IMPORT_C voidResizeL(TInt)
TInt Size()
IMPORT_C voidWrite(TInt, const TDesC8 &)
IMPORT_C voidWrite(TInt, const TDesC8 &, TInt)
IMPORT_C voidWrite(TInt, const TAny *, TInt)
Protected Member Functions
CBufBase(TInt)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()

Detailed Description

Defines the interface for dynamic buffers.

The basic functions, InsertL(), Read(), Write(), Delete(), Reset() and Size(), transfer data between the buffer and other places, and allow that data to be deleted

The ExpandL() and Resize() functions allow some operations to be carried out with greater efficiency

A Compress() function frees (back to the heap) any space which may have been allocated, but not used

Ptr() and BackPtr() allow look-up of contiguous data from any given position, forward or backward

Member Attribute Documentation

iExpandSize

TInt iExpandSize[protected]

iSize

TInt iSize[protected]

Constructor & Destructor Documentation

CBufBase ( TInt )

IMPORT_CCBufBase(TIntanExpandSize)[protected]

~CBufBase ( )

IMPORT_C~CBufBase()

Destructor

Member Function Documentation

BackPtr ( TInt )

TPtr8 BackPtr(TIntaPos)[pure virtual]

Gets a pointer descriptor to represent data from just before the specified data byte backward to the beginning of the contiguous region containing that byte.

Derived classes provide the implementation.

See also: CBufFlat::BackPtr CBufSeg::BackPtr

Parameters
aPosBuffer position: must be in range zero to Size().
Return Value
Descriptor representing the back contiguous region. The address in the descriptor is the pointer to the bytes at the buffer position, unless the buffer position was at the beginning of a non-first segment in the buffer: in this case, the address is a pointer just beyond the last data byte in the previous segment. The length is the number of contiguous bytes from the address backwards to the beginning of the segment.

Compress ( )

voidCompress()[pure virtual]

Compresses the buffer so as to occupy minimal space.

Normally, you would call this when a buffer has reached its final size, or when you know it will not expand again for a while, or when an out-of-memory error has occurred and your program is taking measures to save space. Compression in these circumstances releases memory for other programs to use, but has no adverse effect on performance.

Derived classes provide the implementation.

See also: CBufFlat::Compress CBufSeg::Compress

Delete ( TInt, TInt )

voidDelete(TIntaPos,
TIntaLength
)[pure virtual]

Deletes data from the buffer.

Derived classes provide the implementation.

See also: CBufFlat::Delete CBufSeg::Delete

Parameters
aPosBuffer position where the deletion will begin; must be in the range zero to (Size() minus the length of the data to be deleted).
aLengthThe number of bytes to be deleted; must be non-negative.

ExpandL ( TInt, TInt )

IMPORT_C voidExpandL(TIntaPos,
TIntaLength
)

Inserts an uninitialised region into the buffer.

Data at and beyond the insertion position is moved to make way for the inserted region. Data before the insertion position remains in place.

Note:

1. The inserted region is not initialised. After using ExpandL(), you should then use a series of Write()s to fill this region with data.

2. Use ExpandL() followed by a series of Write()s when you know the amount of data to be inserted, in advance. It is more efficient than a series of InsertL()s. In addition, once the result of the ExpandL() has been checked, it is guaranteed that the Write()s do not leave, which can sometimes be useful.

Parameters
aPosBuffer position before which the region will be inserted; must be in range zero to Size().
aLengthThe length of the region to be inserted.

InsertL ( TInt, const TDesC8 & )

IMPORT_C voidInsertL(TIntaPos,
const TDesC8 &aDes
)

Inserts data into the buffer.

Data at and beyond the insertion position is moved to make way for the inserted data. Data before the insertion position remains in place.

Notes:

1. Insertion may require more buffer space to be allocated.

2. In the case of flat buffers, the buffer is extended by a ReAllocL() of the buffer's heap cell, to the smallest multiple of the granularity that will contain the data required. If this reallocation fails, the insertion is impossible and a leave occurs.

3. In the case of segmented buffers, a reallocation is performed if the segment containing the insertion position has insufficient space, and immediately-neighbouring segments cannot be used to contain the new data. As many new segments as are necessary to contain the inserted data are allocated. Each new segment's length is the buffer's granularity. If extension or new allocation fails, a leave occurs.

4. Insertion may also require data to be shuffled. In the case of flat buffers, data beyond the insertion point is shuffled up to create a gap; the new data is then inserted into this gap. In the case of segmented buffers, shuffling is minimised by inserting the new data into newly-allocated buffers, and shuffling only immediately-neighbouring buffers if possible. This may result in some wastage of space, but is much more time-efficient for large amounts of data.

Parameters
aPosBuffer position before which the data will be inserted; must be in range zero to Size().
aDesThe data to be inserted; the length of the data is the descriptor length.
Leave Codes
KErrNoMemoryIf the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

InsertL ( TInt, const TDesC8 &, TInt )

IMPORT_C voidInsertL(TIntaPos,
const TDesC8 &aDes,
TIntaLength
)

Inserts the specified number of bytes of data from a descriptor into the buffer.

aLength bytes of data from aDes are inserted into the buffer at aPos. Data at and beyond the insertion position is moved to make way for the inserted data. Data before the insertion position remains in place.

Notes:

1. Insertion may require more buffer space to be allocated.

2. In the case of flat buffers, the buffer is extended by a ReAllocL() of the buffer's heap cell, to the smallest multiple of the granularity that will contain the data required. If this reallocation fails, the insertion is impossible and a leave occurs.

3. In the case of segmented buffers, a reallocation is performed if the segment containing the insertion position has insufficient space, and immediately-neighbouring segments cannot be used to contain the new data. As many new segments as are necessary to contain the inserted data are allocated. Each new segment's length is the buffer's granularity. If extension or new allocation fails, a leave occurs.

4. Insertion may also require data to be shuffled. In the case of flat buffers, data beyond the insertion point is shuffled up to create a gap: the new data is then inserted into this gap. In the case of segmented buffers, shuffling is minimised by inserting the new data into newly-allocated buffers, and shuffling only immediately-neighbouring buffers if possible. This may result in some wastage of space, but is much more time-efficient for large amounts of data.

Parameters
aPosBuffer position before which the data will be inserted; must be in range zero to Size().
aDesThe data to be inserted.
aLengthThe length of data to be inserted.
Leave Codes
KErrNoMemoryIf the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

InsertL ( TInt, const TAny *, TInt )

IMPORT_C voidInsertL(TIntaPos,
const TAny *aPtr,
TIntaLength
)

Inserts bytes of data from the specified address into the buffer.

Inserts aLength bytes of data found at address aPtr into the buffer at aPos. Data at and beyond the insertion position is moved to make way for the inserted data. Data before the insertion position remains in place.

Notes:

1. Insertion may require more buffer space to be allocated.

2. In the case of flat buffers, the buffer is extended by a ReAllocL() of the buffer's heap cell, to the smallest multiple of the granularity that will contain the data required. If this reallocation fails, the insertion is impossible and a leave occurs.

2. In the case of segmented buffers, a reallocation is performed if the segment containing the insertion position has insufficient space, and immediately-neighbouring segments cannot be used to contain the new data. As many new segments as are necessary to contain the inserted data are allocated. Each new segment's length is the buffer's granularity. If extension or new allocation fails, a leave occurs.

4. Insertion may also require data to be shuffled. In the case of flat buffers, data beyond the insertion point is shuffled up to create a gap: the new data is then inserted into this gap. In the case of segmented buffers, shuffling is minimised by inserting the new data into newly-allocated buffers, and shuffling only immediately-neighbouring buffers if possible. This may result in some wastage of space, but is much more time-efficient for large amounts of data.

Parameters
aPosBuffer position before which the data will be inserted: must be in range zero to Size().
aPtrThe address of the data to be inserted.
aLengthThe length of the data to be inserted.
Leave Codes
KErrNoMemoryIf the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

Ptr ( TInt )

TPtr8 Ptr(TIntaPos)[pure virtual]

Gets a pointer descriptor to represent the data from the specified position to the end of the contiguous region containing that byte.

Derived classes provide the implementation.

See also: CBufFlat::Ptr CBufSeg::Ptr

Parameters
aPosBuffer position: must be in range zero to Size().
Return Value
Descriptor representing the data starting at aPos, and whose length indicates the number of contiguous bytes stored in the buffer, forward from that point. The length will be non-zero unless aPos==Size().

Read ( TInt, TDes8 & )

IMPORT_C voidRead(TIntaPos,
TDes8 &aDes
)const

Reads data from the buffer into a descriptor.

Data, starting at the specified buffer position is written to the descriptor, filling the descriptor.

Parameters
aPosBuffer position from which data is read: must be in range zero to Size().
aDesOn return, contains the data read from the buffer; its MaxLength() specifies the amount of data to be read.

Read ( TInt, TDes8 &, TInt )

IMPORT_C voidRead(TIntaPos,
TDes8 &aDes,
TIntaLength
)const

Reads the specified number of bytes of data from the buffer into a descriptor.

Parameters
aPosBuffer position from which data is read: must be in range zero to (Size() minus the length of the data to be read).
aDesOn return, contains data read from the buffer.
aLengthThe length of the data to be read.

Read ( TInt, TAny *, TInt )

IMPORT_C voidRead(TIntaPos,
TAny *aPtr,
TIntaLength
)const

Reads the specified number of bytes of data from the buffer into a specified address.

Parameters
aPosBuffer position from which data is read: must be in range zero to (Size() minus the length of the data to be read).
aPtrThe address into which the data should be read.
aLengthThe length of the data to be read.

Reset ( )

IMPORT_C voidReset()

Deletes all data in the buffer.

Its behaviour is the same as calling Delete(0,Size()). The buffer is compressed before the function returns.

ResizeL ( TInt )

IMPORT_C voidResizeL(TIntaSize)

Re-sizes the buffer to the specified size.

The new size can be larger or smaller than the existing size.

If the new size is larger than the existing size, the buffer is expanded by adding uninitialised data to the end of it.

If the new size is smaller than the existing size, the buffer is reduced; any data at the end of the buffer is lost.

Notes:

1. If the new size is larger than the existing size, the function is equivalent to Delete(aSize,Size()-aSize).

2. If the new size is smaller than the existing size, the function is equivalent to ExpandL((Size(),aSize-Size()).

3. The motivations for using ResizeL() are the same as those for using Delete() and ExpandL().

Parameters
aSizeThe new size of the buffer; this value must be greater than or equal to zero.

Size ( )

TInt Size()const [inline]

Gets the number of data bytes in the buffer.

Note that the number of heap bytes used by the buffer may be greater than its size, because there is typically extra room to allow for expansion. Use the Compress() function to reduce the extra allocation as much as possible.

Return Value
The number of data bytes in the buffer.

Write ( TInt, const TDesC8 & )

IMPORT_C voidWrite(TIntaPos,
const TDesC8 &aDes
)

Writes data from a descriptor to the buffer.

The data in the descriptor overwrites the data in the buffer from the insertion point onwards.

No new space is allocated; this function cannot fail (provided the parameters are specified within the bounds of the buffer and descriptor).

No shuffling occurs; new data is written to the memory locations occupied by the data it overwrites.

Parameters
aPosBuffer position at which data will begin to be written; must be in range zero to (Size() minus the length of the data to be written).
aDesContains the data to be written. The length of data to be written is the descriptor length.

Write ( TInt, const TDesC8 &, TInt )

IMPORT_C voidWrite(TIntaPos,
const TDesC8 &aDes,
TIntaLength
)

Writes the specified number of bytes of data from a descriptor to the buffer.

The data in the descriptor overwrites the data in the buffer from the insertion point onwards.

No new space is allocated; this function cannot fail (provided the parameters are specified within the bounds of the buffer and descriptor).

No shuffling occurs; new data is written to the memory locations occupied by the data it overwrites.

Parameters
aPosBuffer position at which data will begin to be written; must be in range zero to (Size() minus the length of the data to be written).
aDesContains the data to be written.
aLengthThe length of the data to be written.

Write ( TInt, const TAny *, TInt )

IMPORT_C voidWrite(TIntaPos,
const TAny *aPtr,
TIntaLength
)

Writes the specified number of bytes of data from the specified address to the buffer.

The data in the buffer is overwritten from the insertion point onwards.

No new space is allocated; this function cannot fail (provided the parameters are specified within the bounds of the buffer and descriptor).

No shuffling occurs: new data is written to the memory locations occupied by the data it overwrites.

Parameters
aPosBuffer position at which data will begin to be written; must be in range zero to (Size() minus the length of the data to be written).
aPtrThe address of the data to be written.
aLengthThe length of the data to be written.
Panic Codes
E32USER-CBase7, if aLength is not positive
E32USER-CBase5, if aPos + aLength is greater than the number of data bytes in the buffer, i.e. if the target appears to be outside the buffer.