Defines the interface for dynamic buffers. More...

#include <e32base.h>

Inheritance diagram for CBufBase:

Public Member Functions
IMPORT_C	~CBufBase ()
	Destructor.

TInt	Size () const
	Gets the number of data bytes in the buffer.

IMPORT_C void	Reset ()
	Deletes all data in the buffer.

IMPORT_C void	Read (TInt aPos, TDes8 &aDes) const
	Reads data from the buffer into a descriptor.

IMPORT_C void	Read (TInt aPos, TDes8 &aDes, TInt aLength) const
	Reads the specified number of bytes of data from the buffer into a descriptor.

IMPORT_C void	Read (TInt aPos, TAny *aPtr, TInt aLength) const
	Reads the specified number of bytes of data from the buffer into a specified address.

IMPORT_C void	Write (TInt aPos, const TDesC8 &aDes)
	Writes data from a descriptor to the buffer.

IMPORT_C void	Write (TInt aPos, const TDesC8 &aDes, TInt aLength)
	Writes the specified number of bytes of data from a descriptor to the buffer.

IMPORT_C void	Write (TInt aPos, const TAny *aPtr, TInt aLength)
	Writes the specified number of bytes of data from the specified address to the buffer.

IMPORT_C void	InsertL (TInt aPos, const TDesC8 &aDes)
	Inserts data into the buffer.

IMPORT_C void	InsertL (TInt aPos, const TDesC8 &aDes, TInt aLength)
	Inserts the specified number of bytes of data from a descriptor into the buffer.

IMPORT_C void	InsertL (TInt aPos, const TAny *aPtr, TInt aLength)
	Inserts bytes of data from the specified address into the buffer.

IMPORT_C void	ExpandL (TInt aPos, TInt aLength)
	Inserts an uninitialised region into the buffer.

IMPORT_C void	ResizeL (TInt aSize)
	Re-sizes the buffer to the specified size.

virtual void	Compress ()=0
	Compresses the buffer so as to occupy minimal space.

virtual void	Delete (TInt aPos, TInt aLength)=0
	Deletes data from the buffer.

virtual TPtr8	Ptr (TInt aPos)=0
	Gets a pointer descriptor to represent the data from the specified position to the end of the contiguous region containing that byte.

virtual TPtr8	BackPtr (TInt aPos)=0
	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.

Public Member Functions inherited from CBase
	CBase ()
	Default constructor.

virtual IMPORT_C	~CBase ()
	Virtual destructor.

TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.

TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Protected Member Functions
IMPORT_C	CBufBase (TInt anExpandSize)
	Constructor.

Protected Member Functions inherited from CBase
virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)
	Extension function.

Protected Attributes
TInt	iSize

TInt	iExpandSize

Additional Inherited Members
Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

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

API status: Published to all clients. Released API.

Definition at line 86 of file e32base.h.

Constructor & Destructor Documentation

◆ ~CBufBase()

IMPORT_C CBufBase::~CBufBase ( )

Destructor.

(generated from Symbian Developer Library)

◆ CBufBase()

IMPORT_C CBufBase::CBufBase ( TInt anExpandSize )

protected

Constructor.

API status

(generated from Original Symbian implementation)

API status: Internal component API.

Member Function Documentation

◆ BackPtr()

virtual TPtr8 CBufBase::BackPtr ( TInt aPos )

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.

Parameters

aPos	Buffer position: must be in range zero to Size().

Returns: 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.

See also: CBufFlat::BackPtr; CBufSeg::BackPtr

Implemented in CBufFlat, and CBufSeg.

◆ Compress()

virtual void CBufBase::Compress ( )

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

Implemented in CBufFlat, and CBufSeg.

◆ Delete()

virtual void CBufBase::Delete	(	TInt	aPos,
		TInt	aLength
	)

pure virtual

Deletes data from the buffer.

Derived classes provide the implementation.

Parameters

aPos	Buffer position where the deletion will begin; must be in the range zero to (Size() minus the length of the data to be deleted).
aLength	The number of bytes to be deleted; must be non-negative.

See also: CBufFlat::Delete; CBufSeg::Delete

Implemented in CBufFlat, and CBufSeg.

◆ ExpandL()

IMPORT_C void CBufBase::ExpandL	(	TInt	aPos,
		TInt	aLength
	)

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:

The inserted region is not initialised. After using ExpandL(), you should then use a series of Write()s to fill this region with data.
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

aPos	Buffer position before which the region will be inserted; must be in range zero to Size().
aLength	The length of the region to be inserted.

(generated from Symbian Developer Library)

◆ InsertL() [1/3]

IMPORT_C void CBufBase::InsertL	(	TInt	aPos,
		const TAny *	aPtr,
		TInt	aLength
	)

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:

Insertion may require more buffer space to be allocated.
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.

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

aPos	Buffer position before which the data will be inserted: must be in range zero to Size().
aPtr	The address of the data to be inserted.
aLength	The length of the data to be inserted.

Leave condition: KErrNoMemory If the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

(generated from Symbian Developer Library)

◆ InsertL() [2/3]

IMPORT_C void CBufBase::InsertL	(	TInt	aPos,
		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:

Insertion may require more buffer space to be allocated.
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.
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.
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

aPos	Buffer position before which the data will be inserted; must be in range zero to Size().
aDes	The data to be inserted; the length of the data is the descriptor length.

Leave condition: KErrNoMemory If the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

(generated from Symbian Developer Library)

◆ InsertL() [3/3]

IMPORT_C void CBufBase::InsertL	(	TInt	aPos,
		const TDesC8 &	aDes,
		TInt	aLength
	)

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:

Insertion may require more buffer space to be allocated.
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.
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.
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

aPos	Buffer position before which the data will be inserted; must be in range zero to Size().
aDes	The data to be inserted.
aLength	The length of data to be inserted.

Leave condition: KErrNoMemory If the insertion requires a bigger buffer, and the necessary allocation or re-allocation fails.

(generated from Symbian Developer Library)

◆ Ptr()

virtual TPtr8 CBufBase::Ptr ( TInt aPos )

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.

Parameters

aPos	Buffer position: must be in range zero to Size().

Returns: 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().

See also: CBufFlat::Ptr; CBufSeg::Ptr

Implemented in CBufFlat, and CBufSeg.

◆ Read() [1/3]

IMPORT_C void CBufBase::Read	(	TInt	aPos,
		TAny *	aPtr,
		TInt	aLength
	)		const

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

Parameters

aPos	Buffer position from which data is read: must be in range zero to (Size() minus the length of the data to be read).
aPtr	The address into which the data should be read.
aLength	The length of the data to be read.

(generated from Symbian Developer Library)

◆ Read() [2/3]

IMPORT_C void CBufBase::Read	(	TInt	aPos,
		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

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

(generated from Symbian Developer Library)

◆ Read() [3/3]

IMPORT_C void CBufBase::Read	(	TInt	aPos,
		TDes8 &	aDes,
		TInt	aLength
	)		const

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

Parameters

aPos	Buffer position from which data is read: must be in range zero to (Size() minus the length of the data to be read).
aDes	On return, contains data read from the buffer.
aLength	The length of the data to be read.

(generated from Symbian Developer Library)

◆ Reset()

IMPORT_C void CBufBase::Reset ( )

Deletes all data in the buffer.

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

(generated from Symbian Developer Library)

◆ ResizeL()

IMPORT_C void CBufBase::ResizeL ( TInt aSize )

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:

If the new size is larger than the existing size, the function is equivalent to Delete(aSize,Size()-aSize).
If the new size is smaller than the existing size, the function is equivalent to ExpandL((Size(),aSize-Size()).
The motivations for using ResizeL() are the same as those for using Delete() and ExpandL().

Parameters

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

(generated from Symbian Developer Library)

◆ Size()

TInt CBufBase::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.

(generated from Symbian Developer Library)

◆ Write() [1/3]

IMPORT_C void CBufBase::Write	(	TInt	aPos,
		const TAny *	aPtr,
		TInt	aLength
	)

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

aPos	Buffer 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).
aPtr	The address of the data to be written.
aLength	The length of the data to be written.

Panic condition: E32USER-CBase 7, if aLength is not positive

Panic condition: E32USER-CBase 5, 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.

(generated from Symbian Developer Library)

◆ Write() [2/3]

IMPORT_C void CBufBase::Write	(	TInt	aPos,
		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

aPos	Buffer 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).
aDes	Contains the data to be written. The length of data to be written is the descriptor length.

(generated from Symbian Developer Library)

◆ Write() [3/3]

IMPORT_C void CBufBase::Write	(	TInt	aPos,
		const TDesC8 &	aDes,
		TInt	aLength
	)

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

aPos	Buffer 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).
aDes	Contains the data to be written.
aLength	The length of the data to be written.

(generated from Symbian Developer Library)

Member Data Documentation

◆ iExpandSize

TInt CBufBase::iExpandSize

protected

Definition at line 197 of file e32base.h.

◆ iSize

TInt CBufBase::iSize

protected

Definition at line 196 of file e32base.h.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~CBufBase()

◆ CBufBase()

Member Function Documentation

◆ BackPtr()

◆ Compress()

◆ Delete()

◆ ExpandL()

◆ InsertL() [1/3]

◆ InsertL() [2/3]

◆ InsertL() [3/3]

◆ Ptr()

◆ Read() [1/3]

◆ Read() [2/3]

◆ Read() [3/3]

◆ Reset()

◆ ResizeL()

◆ Size()

◆ Write() [1/3]

◆ Write() [2/3]

◆ Write() [3/3]

Member Data Documentation

◆ iExpandSize

◆ iSize