Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]

#include <e32des16.h>
Link against: euser.lib

Class RBuf16

class RBuf16 : public TDes16;

Description

16 bit resizable buffer descriptor.

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

Internally, RBuf16 behaves in one of two ways:

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

An RBuf16 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 RBuf16 object is responsible for freeing memory when the object itself is closed.

The class is intended for instantiation.

The class is derived from TDes16, 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 RBuf16 object can be passed to any function that is prototyped to take a TDes16 or a TDesC16 type.

Derivation

Members

Defined in RBuf16:

Inherited from TDes16:

Inherited from TDesC16:

See also:


Construction and destruction


RBuf16()

IMPORT_C RBuf16();

Description

Default constructor.

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

Note that the object owns no allocated memory.


RBuf16(HBufC16 *)

IMPORT_C RBuf16(HBufC16 *aHBuf);

Description

Constructor.

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

Parameters

HBufC16 *aHBuf

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


RBuf16(TInt,TInt,TInt)

protected: IMPORT_C RBuf16(TInt aType, TInt aLength, TInt aMaxLength);

Description

Protected constructor.

Parameters

TInt aType

TInt aLength

TInt aMaxLength

[Top]


Member functions


operator=(const TUint16 *)

inline RBuf16& operator=(const TUint16 *aString);

Description

Copies data into this descriptor replacing any existing data.

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

Parameters

const TUint16 *aString

A pointer to a zero-terminated string.

Return value

RBuf16 &

A reference to this, the target descriptor.

Panic codes

USER

11, if the length of the string, excluding the zero terminator, is greater than the maximum length of this (target) descriptor.


operator=(const TDesC16 &)

inline RBuf16& operator=(const TDesC16 &aDes);

Description

Copies data into this descriptor replacing any existing data.

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

Parameters

const TDesC16 &aDes

A 16-bit non-modifiable descriptor.

Return value

RBuf16 &

A reference to this, the target descriptor.

Panic codes

USER

11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.


operator=(const RBuf16 &)

inline RBuf16& operator=(const RBuf16 &aDes);

Description

Copies data into this descriptor replacing any existing data.

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

Parameters

const RBuf16 &aDes

A 16-bit buffer descriptor.

Return value

RBuf16 &

A reference to this, the target descriptor.

Panic codes

USER

11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.


Assign(const RBuf16 &)

IMPORT_C void Assign(const RBuf16 &aRBuf);

Description

Transfers ownership of the specified 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

const RBuf16 &aRBuf

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

See also:


Assign(TUint16 *,TInt)

IMPORT_C void Assign(TUint16 *aHeapCell, TInt aMaxLength);

Description

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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TUint16 *aHeapCell

The allocated memory to be assigned to this object. This pointer can be NULL, which means that a zero length 16-bit resizable buffer descriptor is created.

TInt aMaxLength

The maximum length of the descriptor.

Panic codes

USER

8 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:


Assign(TUint16 *,TInt,TInt)

IMPORT_C void Assign(TUint16 *aHeapCell, TInt aLength, TInt aMaxLength);

Description

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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TUint16 *aHeapCell

The allocated memory to be assigned to this object.

TInt aLength

The length of the descriptor.

TInt aMaxLength

The maximum length of the descriptor.

Panic codes

USER

8 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:


Assign(HBufC16 *)

IMPORT_C void Assign(HBufC16 *aHBuf);

Description

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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

HBufC16 *aHBuf

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

See also:


Swap(RBuf16 &)

IMPORT_C void Swap(RBuf16 &aRBuf);

Description

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

Parameters

RBuf16 &aRBuf

The 16-bit resizable buffer descriptor whose contents are to be swapped with this one.


Create(TInt)

IMPORT_C TInt Create(TInt aMaxLength);

Description

Creates a 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TInt aMaxLength

The maximum length of the descriptor.

Return value

TInt

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

See also:


CreateL(TInt)

IMPORT_C void CreateL(TInt aMaxLength);

Description

Creates 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TInt aMaxLength

The maximum length of the descriptor.

Leave codes

KErrNoMemory

If there is insufficient memory.

See also:


CreateMax(TInt)

IMPORT_C TInt CreateMax(TInt aMaxLength);

Description

Creates a 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TInt aMaxLength

The length and the maximum length of the descriptor.

Return value

TInt

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

See also:


CreateMaxL(TInt)

IMPORT_C void CreateMaxL(TInt aMaxLength);

Description

Creates a 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

TInt aMaxLength

The length and the maximum length of the descriptor.

Leave codes

KErrNoMemory

If there is insufficient memory.

See also:


CreateL(RReadStream &,TInt)

inline void CreateL(RReadStream &aStream, TInt aMaxLength);

Description

Creates a 16-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 HBufC16::NewL(TInt)(RReadStream&,TInt) variant and then assigning the resulting heap descriptor using the RBuf16::Assign(HBufC16 *) variant. The comments that describe the HBufC16::NewL(TInt) variant also apply to this RBuf16::CreateL(TInt) 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.

Parameters

RReadStream &aStream

The stream from which the data length and the data to be assigned to the new descriptor, are taken.

TInt aMaxLength

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


Create(const TDesC16 &)

IMPORT_C TInt Create(const TDesC16 &aDes);

Description

Creates a 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

const TDesC16 &aDes

Source descriptor to be copied into this object.

Return value

TInt

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

See also:


CreateL(const TDesC16 &)

IMPORT_C void CreateL(const TDesC16 &aDes);

Description

Creates a 16-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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

const TDesC16 &aDes

Source descriptor to be copied into this object.

Leave codes

KErrNoMemory

If there is insufficient memory.

See also:


Create(const TDesC16 &,TInt)

IMPORT_C TInt Create(const TDesC16 &aDes, TInt aMaxLength);

Description

Creates a 16-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

or

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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

const TDesC16 &aDes

Source descriptor to be copied into this object.

TInt aMaxLength

The maximum length of this descriptor.

Return value

TInt

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

See also:


CreateL(const TDesC16 &,TInt)

IMPORT_C void CreateL(const TDesC16 &aDes, TInt aMaxLength);

Description

Creates a 16-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

or

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, RBuf16::Close() should be invoked on this descriptor before this function is invoked.

Parameters

const TDesC16 &aDes

Source descriptor to be copied into this object.

TInt aMaxLength

The maximum length of this descriptor.

Leave codes

KErrNoMemory

If there is insufficient memory.

See also:


ReAlloc(TInt)

IMPORT_C TInt ReAlloc(TInt aMaxLength);

Description

Resizes this 16-bit resizable buffer descriptor.

The length and contents of the descriptor are unchanged.

Parameters

TInt aMaxLength

The new maximum length of the descriptor. This can be zero, which results in a descriptor with zero maximum length and no allocated memory.

Return value

TInt

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

Panic codes

USER

14 If the new maximum length is less then the current descriptor length.


ReAllocL(TInt)

IMPORT_C void ReAllocL(TInt aMaxLength);

Description

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

The length and contents of the descriptor are unchanged.

Parameters

TInt aMaxLength

The new maximum length of the descriptor. This can be zero, which results in a descriptor with zero maximum length and no allocated memory.

Panic codes

USER

14 If the new maximum length is less then the current descriptor length.


Close()

IMPORT_C void Close();

Description

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


CleanupClosePushL()

IMPORT_C void CleanupClosePushL();

Description

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

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

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

See also:

[Top]


Member data


iEPtrType

protected: TUint16 * iEPtrType;

Description


iEBufCPtrType

protected: HBufC16 * iEBufCPtrType;

Description


__DECLARE_TEST

protected: __DECLARE_TEST;

Description