RBuf8 Class Reference

#include <e32des8.h>

class RBuf8 : public TDes8

Inherits from

Public Attributes
HBufC8 *iEBufCPtrType
TUint8 *iEPtrType
Protected Attributes
union RBuf8::@4@5
__DECLARE_TEST
Public Member Functions
RBuf8()
RBuf8(HBufC8 *)
IMPORT_C voidAssign(const RBuf8 &)
IMPORT_C voidAssign(TUint8 *, TInt)
IMPORT_C voidAssign(TUint8 *, TInt, TInt)
IMPORT_C voidAssign(HBufC8 *)
IMPORT_C voidCleanupClosePushL()
IMPORT_C voidClose()
IMPORT_C TIntCreate(TInt)
IMPORT_C TIntCreate(const TDesC8 &)
IMPORT_C TIntCreate(const TDesC8 &, TInt)
IMPORT_C voidCreateL(TInt)
voidCreateL(RReadStream &, TInt)
IMPORT_C voidCreateL(const TDesC8 &)
IMPORT_C voidCreateL(const TDesC8 &, TInt)
IMPORT_C TIntCreateMax(TInt)
IMPORT_C voidCreateMaxL(TInt)
IMPORT_C TIntReAlloc(TInt)
IMPORT_C voidReAllocL(TInt)
IMPORT_C voidSwap(RBuf8 &)
RBuf8 &operator=(const TUint8 *)
RBuf8 &operator=(const TDesC8 &)
RBuf8 &operator=(const RBuf8 &)
Protected Member Functions
RBuf8(TInt, TInt, TInt)
RBuf8(const RBuf8 &)
Inherited Attributes
TDes8::iMaxLength
Inherited Functions
TDes8::Append(TChar)
TDes8::Append(const TDesC16 &)
TDes8::Append(const TDesC8 &)
TDes8::Append(const TUint8 *,TInt)
TDes8::AppendFill(TChar,TInt)
TDes8::AppendFormat(TRefByValue< const TDesC8 >,...)
TDes8::AppendFormat(TRefByValue< const TDesC8 >,TDes8Overflow *,...)
TDes8::AppendFormatList(const TDesC8 &,VA_LIST,TDes8Overflow *)
TDes8::AppendJustify(const TDesC8 &,TInt,TAlign,TChar)
TDes8::AppendJustify(const TDesC8 &,TInt,TInt,TAlign,TChar)
TDes8::AppendJustify(const TUint8 *,TInt,TAlign,TChar)
TDes8::AppendJustify(const TUint8 *,TInt,TInt,TAlign,TChar)
TDes8::AppendNum(TInt64)
TDes8::AppendNum(TReal,const TRealFormat &)
TDes8::AppendNum(TUint64,TRadix)
TDes8::AppendNumFixedWidth(TUint,TRadix,TInt)
TDes8::AppendNumFixedWidthUC(TUint,TRadix,TInt)
TDes8::AppendNumUC(TUint64,TRadix)
TDes8::Capitalize()
TDes8::Collapse()
TDes8::Collate()
TDes8::Copy(const TDesC16 &)
TDes8::Copy(const TDesC8 &)
TDes8::Copy(const TUint8 *)
TDes8::Copy(const TUint8 *,TInt)
TDes8::CopyC(const TDesC8 &)
TDes8::CopyCP(const TDesC8 &)
TDes8::CopyF(const TDesC8 &)
TDes8::CopyLC(const TDesC8 &)
TDes8::CopyUC(const TDesC8 &)
TDes8::Delete(TInt,TInt)
TDes8::DoAppendNum(TUint64,TRadix,TUint,TInt)
TDes8::DoPadAppendNum(TInt,TInt,const TUint8 *)
TDes8::Expand()
TDes8::Fill(TChar)
TDes8::Fill(TChar,TInt)
TDes8::FillZ()
TDes8::FillZ(TInt)
TDes8::Fold()
TDes8::Format(TRefByValue< const TDesC8 >,...)
TDes8::FormatList(const TDesC8 &,VA_LIST)
TDes8::Insert(TInt,const TDesC8 &)
TDes8::Justify(const TDesC8 &,TInt,TAlign,TChar)
TDes8::LeftTPtr(TInt)const
TDes8::LowerCase()
TDes8::MaxLength()const
TDes8::MaxSize()const
TDes8::MidTPtr(TInt)const
TDes8::MidTPtr(TInt,TInt)const
TDes8::Num(TInt64)
TDes8::Num(TReal,const TRealFormat &)
TDes8::Num(TUint64,TRadix)
TDes8::NumFixedWidth(TUint,TRadix,TInt)
TDes8::NumFixedWidthUC(TUint,TRadix,TInt)
TDes8::NumUC(TUint64,TRadix)
TDes8::PtrZ()
TDes8::Repeat(const TDesC8 &)
TDes8::Repeat(const TUint8 *,TInt)
TDes8::Replace(TInt,TInt,const TDesC8 &)
TDes8::RightTPtr(TInt)const
TDes8::SetLength(TInt)
TDes8::SetMax()
TDes8::Swap(TDes8 &)
TDes8::TDes8()
TDes8::TDes8(TInt,TInt,TInt)
TDes8::Trim()
TDes8::TrimAll()
TDes8::TrimLeft()
TDes8::TrimRight()
TDes8::UpperCase()
TDes8::WPtr()const
TDes8::Zero()
TDes8::ZeroTerminate()
TDes8::operator+=(const TDesC8 &)
TDes8::operator=(const TDes8 &)
TDes8::operator[](TInt)
TDes8::operator[](TInt)const
TDesC8::Alloc()const
TDesC8::AllocL()const
TDesC8::AllocLC()const
TDesC8::AtC(TInt)const
TDesC8::Compare(const TDesC8 &)const
TDesC8::CompareC(const TDesC8 &)const
TDesC8::CompareF(const TDesC8 &)const
TDesC8::DoSetLength(TInt)
TDesC8::Find(const TDesC8 &)const
TDesC8::Find(const TUint8 *,TInt)const
TDesC8::FindC(const TDesC8 &)const
TDesC8::FindC(const TUint8 *,TInt)const
TDesC8::FindF(const TDesC8 &)const
TDesC8::FindF(const TUint8 *,TInt)const
TDesC8::Left(TInt)const
TDesC8::Length()const
TDesC8::Locate(TChar)const
TDesC8::LocateF(TChar)const
TDesC8::LocateReverse(TChar)const
TDesC8::LocateReverseF(TChar)const
TDesC8::Match(const TDesC8 &)const
TDesC8::MatchC(const TDesC8 &)const
TDesC8::MatchF(const TDesC8 &)const
TDesC8::Mid(TInt)const
TDesC8::Mid(TInt,TInt)const
TDesC8::Ptr()const
TDesC8::Right(TInt)const
TDesC8::Size()const
TDesC8::TDesC8()
TDesC8::TDesC8(TInt,TInt)
TDesC8::Type()const
TDesC8::operator!=(const TDesC8 &)const
TDesC8::operator<(const TDesC8 &)const
TDesC8::operator<=(const TDesC8 &)const
TDesC8::operator==(const TDesC8 &)const
TDesC8::operator>(const TDesC8 &)const
TDesC8::operator>=(const TDesC8 &)const

Detailed Description

8 bit resizable buffer descriptor.

The class provides a buffer that contains, accesses and manipulates TUint8 data. The buffer itself is on the heap, and is managed by the class.

Internally, RBuf8 behaves in one of two ways:

  • as a TPtr8 descriptor type, where the buffer just contains data

  • as a pointer to a heap descriptor, an HBufC8* type, where the buffer contains both descriptor information and the data.

Note that the handling of the distinction is hidden from view.

An RBuf8 object can allocate its own buffer. Alternatively, it can take ownership of a pre-existing section of allocated memory, or it can take ownership of a pre-existing heap descriptor. It can also reallocate the buffer to resize it. Regardless of the way in which the buffer has been allocated, the RBuf8 object is responsible for freeing memory when the object itself is closed.

The class is intended for instantiation.

The class is derived from TDes8, which means that data can be both accessed and modified. The base classes provide the functions through which the data is accessed. In addition, an RBuf8 object can be passed to any function that is prototyped to take a TDes8 or a TDesC8 type.

See also: TBuf8 TPtr8 HBufC8 TDesC8 TDes8

Member Attribute Documentation

@5

union RBuf8::@4@5[protected]

__DECLARE_TEST

__DECLARE_TEST[protected]

iEBufCPtrType

HBufC8 *iEBufCPtrType

iEPtrType

TUint8 *iEPtrType

Constructor & Destructor Documentation

RBuf8 ( )

IMPORT_CRBuf8()

Default constructor.

Constructs a zero-length 8-bit resizable buffer descriptor.

Note that the object owns no allocated memory.

RBuf8 ( HBufC8 * )

IMPORT_CRBuf8(HBufC8 *aHBuf)[explicit]

Constructor.

Constructs an 8-bit resizable buffer descriptor, transferring ownership of the specified heap descriptor to this object.

ParameterDescription
aHBufThe heap descriptor to be transferred to this object. This pointer can be NULL, which means that a zero length 8-bit resizable buffer descriptor is constructed, and the object will not own any allocated memory.

RBuf8 ( TInt, TInt, TInt )

IMPORT_CRBuf8(TIntaType,
TIntaLength,
TIntaMaxLength
)[protected]

Protected constructor.

RBuf8 ( const RBuf8 & )

RBuf8(const RBuf8 &)[protected]

Member Function Documentation

Assign ( const RBuf8 & )

IMPORT_C voidAssign(const RBuf8 &aRBuf)

Transfers ownership of the specified 8-bit resizable buffer descriptor's buffer to this object.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: RBuf8::Close()

ParameterDescription
aRBufThe source 8-bit resizable buffer. The ownership of this object's buffer is to be transferred.

Assign ( TUint8 *, TInt )

IMPORT_C voidAssign(TUint8 *aHeapCell,
TIntaMaxLength
)

Assigns ownership of the specified allocated memory to this object.

The allocated memory forms the buffer for this descriptor. The current length of the descriptor is set to zero.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

panic
USER 20 If the specified maximum length is greater then the size of the allocated heap cell, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

See also: TDesC8::Length() TDes8::MaxLength() RBuf8::Close()

ParameterDescription
aHeapCellThe allocated memory to be assigned to this object. This pointer can be NULL, which means that a zero length 8-bit resizable buffer descriptor is created.
aMaxLengthThe maximum length of the descriptor.

Assign ( TUint8 *, TInt, TInt )

IMPORT_C voidAssign(TUint8 *aHeapCell,
TIntaLength,
TIntaMaxLength
)

Assigns ownership of the specified allocated memory to this object.

The allocated memory forms the buffer for this descriptor. The current length of the descriptor is set to the value of the second parameter.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

panic
USER 20 If the specified maximum length is greater then the size of the allocated heap cell, or the specified length is greater then the specified maximum length, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

See also: TDesC8::Length() TDes8::MaxLength() RBuf8::Close()

ParameterDescription
aHeapCellThe allocated memory to be assigned to this object.
aLengthThe length of the descriptor.
aMaxLengthThe maximum length of the descriptor.

Assign ( HBufC8 * )

IMPORT_C voidAssign(HBufC8 *aHBuf)

Transfers ownership of the specified heap descriptor to this object.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: RBuf8::Close()

ParameterDescription
aHBufThe heap descriptor to be transferred to this object. This pointer can be NULL, which means that a zero length 8-bit resizable buffer descriptor is created.

CleanupClosePushL ( )

IMPORT_C voidCleanupClosePushL()

Pushes a cleanup item for this object onto the cleanup stack.

The effect of this is to cause Close() to be called on this 8-bit resizable buffer descriptor, when CleanupStack::PopAndDestroy() is called at some later time.

...
RBuf8 x;
....
x.CleanupClosePushL();
...
CleanupStack::PopAndDestroy();
...

See also: RBuf8::Close()

Close ( )

IMPORT_C voidClose()

Deallocates memory assigned to this object, and re-initializes the object as a zero-length descriptor.

Create ( TInt )

IMPORT_C TIntCreate(TIntaMaxLength)

Creates an 8-bit resizable buffer descriptor.

The function allocates sufficient memory to contain descriptor data up to the specified maximum length.

The current length of the descriptor is set to zero. The maximum length of the descriptor is set to the specified value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: TDesC8::Length() TDes8::MaxLength() RBuf8::Close()

ParameterDescription
aMaxLengthThe maximum length of the descriptor.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

Create ( const TDesC8 & )

IMPORT_C TIntCreate(const TDesC8 &aDes)

Creates a 8-bit resizable buffer descriptor to contain a copy of the specified (source) descriptor.

The function allocates sufficient memory so that this descriptor's maximum length is the same as the length of the source descriptor. Both the current length and the maximum length of this descriptor are set to the length of the source descriptor.

The data contained in the source descriptor is copied into this descriptor.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: TDesC8::Length() TDes8::MaxLength() TDes8::Copy() RBuf8::Close()

ParameterDescription
aDesSource descriptor to be copied into this object.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

Create ( const TDesC8 &, TInt )

IMPORT_C TIntCreate(const TDesC8 &aDes,
TIntaMaxLength
)

Creates an 8-bit resizable buffer descriptor to contain a copy of the specified (source) descriptor.

The function allocates sufficient memory so that this descriptor's maximum length is the same as the value of the aMaxLength parameter.

The data contained in the source descriptor is copied into this descriptor. The length of data copied is either

  • the length of the source descriptor aDes

or

  • the value of the aMaxLength parameter

whichever is the smaller value. The current length of this descriptor is also set to the smaller value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: TDesC8::Length() TDes8::MaxLength() TDes8::Copy() RBuf8::Close()

ParameterDescription
aDesSource descriptor to be copied into this object.
aMaxLengthThe maximum length of this descriptor.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

CreateL ( TInt )

IMPORT_C voidCreateL(TIntaMaxLength)

Creates an 8-bit resizable buffer descriptor, and leaves on failure.

The function allocates sufficient memory to contain descriptor data up to the specified maximum length.

The current length of the descriptor is set to zero. The maximum length of the descriptor is set to the specified value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

leave
KErrNoMemory If there is insufficient memory.

See also: TDesC8::Length() TDes8::MaxLength() RBuf8::Close()

ParameterDescription
aMaxLengthThe length and the maximum length of the descriptor.

CreateL ( RReadStream &, TInt )

voidCreateL(RReadStream &aStream,
TIntaMaxLength
)[inline]

Creates an 8-bit resizable buffer descriptor that has been initialised with data from the specified read stream; leaves on failure.

Data is assigned to the new descriptor from the specified stream. This variant assumes that the stream contains the length of the data followed by the data itself.

The function is implemented by calling the HBufC8::NewL(RReadStream&,TInt) variant and then assigning the resulting heap descriptor using the RBuf8::Assign(HBufC8*) variant. The comments that describe the HBufC8::NewL() variant also apply to this RBuf8::CreateL() function.

The function may leave with one of the system-wide error codes, specifically KErrOverflow, if the length of the data as read from the stream is greater than the upper limit as specified by the aMaxLength parameter.

ParameterDescription
aStreamThe stream from which the data length and the data to be assigned to the new descriptor, are taken.
aMaxLengthThe upper limit on the length of data that the descriptor is to represent. The value of this parameter must be non-negative otherwise the underlying function will panic.

CreateL ( const TDesC8 & )

IMPORT_C voidCreateL(const TDesC8 &aDes)

Creates an 8-bit resizable buffer descriptor to contain a copy of the specified (source) descriptor, and leaves on failure.

The function allocates sufficient memory so that this descriptor's maximum length is the same as the length of the source descriptor.Both the current length and the maximum length of this descriptor are set to the length of the source descriptor.

The data contained in the source descriptor is copied into this descriptor.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

leave
KErrNoMemory If there is insufficient memory.

See also: TDesC8::Length() TDes8::MaxLength() TDes8::Copy() RBuf8::Close()

ParameterDescription
aDesSource descriptor to be copied into this object.

CreateL ( const TDesC8 &, TInt )

IMPORT_C voidCreateL(const TDesC8 &aDes,
TIntaMaxLength
)

Creates an 8-bit resizable buffer descriptor to contain a copy of the specified (source) descriptor, and leaves on failure.

The function allocates sufficient memory so that this descriptor's maximum length is the same as the value of the aMaxLength parameter.

The data contained in the source descriptor is copied into this descriptor. The length of data copied is either

  • the length of the source descriptor aDes

or

  • the value of the aMaxLength parameter

whichever is the smaller value. The current length of this descriptor is also set to the smaller value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

leave
KErrNoMemory If there is insufficient memory.

See also: TDesC8::Length() TDes8::MaxLength() TDes8::Copy() RBuf8::Close()

ParameterDescription
aDesSource descriptor to be copied into this object.
aMaxLengthThe maximum length of this descriptor.

CreateMax ( TInt )

IMPORT_C TIntCreateMax(TIntaMaxLength)

Creates an 8-bit resizable buffer descriptor.

The function allocates sufficient memory to contain descriptor data up to the specified maximum length.

Both the current length and the maximum length of the descriptor are set to the specified value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

See also: RBuf8::Close()

ParameterDescription
aMaxLengthThe length and the maximum length of the descriptor.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

CreateMaxL ( TInt )

IMPORT_C voidCreateMaxL(TIntaMaxLength)

Creates an 8-bit resizable buffer descriptor, and leaves on failure.

The function allocates sufficient memory to contain descriptor data up to the specified maximum length.

Both the current length and the maximum length of the descriptor are set to the specified value.

Note that the function assumes that this descriptor does not already own any allocated memory. It does not check, nor does it free any pre-existing owned allocated memory. If this descriptor does already own allocated memory, RBuf8::Close() should be invoked on this descriptor before this function is invoked.

leave
KErrNoMemory If there is insufficient memory.

See also: TDesC8::Length() TDes8::MaxLength() RBuf8::Close()

ParameterDescription
aMaxLengthThe length and the maximum length of the descriptor.

ReAlloc ( TInt )

IMPORT_C TIntReAlloc(TIntaMaxLength)

Resizes this 8-bit resizable buffer descriptor.

The length and contents of the descriptor are unchanged.

If the buffer descriptor was created from a zero-length heap descriptor HBufC, this method might leak memory (the heap descriptor is not freed). It is possible to avoid this by calling the Close() method prior to ReAlloc(), but this should be done only in this situation (otherwise the buffer contents will be lost).

For example, add
    if (desc.MaxLength() == 0) desc.Close();
before the call to ReAlloc().
panic
USER 26 If the new maximum length is less then the current descriptor length.
ParameterDescription
aMaxLengthThe new maximum length of the descriptor. This can be zero, which results in a descriptor with zero maximum length and no allocated memory.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

ReAllocL ( TInt )

IMPORT_C voidReAllocL(TIntaMaxLength)

Resizes this 8-bit resizable buffer descriptor, leaving on failure.

The length and contents of the descriptor are unchanged.

If the buffer descriptor was created from a zero-length heap descriptor HBufC, this method might leak memory (the heap descriptor is not freed). It is possible to avoid this by calling the Close() method prior to ReAllocL(), but this should be done only in this situation (otherwise the buffer contents will be lost).

For example, add
    if (desc.MaxLength() == 0) desc.Close();
before the call to ReAlloc().
panic
USER 26 If the new maximum length is less then the current descriptor length.
ParameterDescription
aMaxLengthThe new maximum length of the descriptor. This can be zero, which results in a descriptor with zero maximum length and no allocated memory.

Returns: KErrNone, if successful; KErrNoMemory, if there is insufficient memory.

Swap ( RBuf8 & )

IMPORT_C voidSwap(RBuf8 &aRBuf)

Swaps the content of two 8-bit resizable buffer descriptors.

ParameterDescription
aRBufThe 8-bit resizable buffer descriptor whose contents are to be swapped with this one.

operator= ( const TUint8 * )

RBuf8 &operator=(const TUint8 *aString)[inline]

Copies data into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

panic
USER 11, if the length of the string, excluding the zero terminator, is greater than the maximum length of this (target) descriptor.
ParameterDescription
aStringA pointer to a zero-terminated string.

Returns: A reference to this, the target descriptor.

operator= ( const TDesC8 & )

RBuf8 &operator=(const TDesC8 &aDes)[inline]

Copies data into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

panic
USER 11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.
ParameterDescription
aDesAn 8-bit non-modifiable descriptor.

Returns: A reference to this, the target descriptor.

operator= ( const RBuf8 & )

RBuf8 &operator=(const RBuf8 &aDes)[inline]

Copies data into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

panic
USER 11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.
ParameterDescription
aDesA 8-bit buffer descriptor.

Returns: A reference to this, the target descriptor.