Class TResourceReader

TResourceReader

Support

Supported from 5.0

Description

Interprets resource data read from a resource file.

To use an instance of this class, pass the buffer containing the resource data to it by calling SetBuffer().

The buffer containing the resource data is created by AllocReadLC() or AllocReadL() which reads the specified resource into it.

The current position within the buffer is always maintained and any request for data is always supplied from the current position. The current position is always updated .

Defined in TResourceReader:
Advance(), HBufC8*, Ptr(), Read(), ReadDesC16ArrayL(), ReadDesC8ArrayL(), ReadDesCArrayL(), ReadHBufC16L(), ReadHBufC8L(), ReadHBufCL(), ReadInt16(), ReadInt32(), ReadInt8(), ReadReal64(), ReadTPtrC(), ReadTPtrC16(), ReadTPtrC8(), ReadUint16(), ReadUint32(), ReadUint8(), Rewind(), SetBuffer()

See also:

• TResourceReader::SetBuffer()
• RResourceFile::AllocReadL()
• RResourceFile::AllocReadLC()

void SetBuffer(const TDesC8* aBuffer);

Description

Sets the buffer containing the resource data.

The current position within the buffer is set to the start of the buffer so that subsequent calls to the interpreting functions, for example ReadInt8(), start at the beginning of this buffer.

Parameters

const TDesC8* aBuffer A pointer to an 8 bit non-modifiable descriptor containing or representing resource data.

const TAny* Ptr();

Description

Returns the current position within the resource buffer.

The function makes no assumption about the type of data in the buffer at the current position.

Return value

TAny* A pointer to the current position within the resource buffer.

HBufC* ReadHBufCL();

Description

Interprets the data at the current buffer position as leading byte count data and constructs a build independent heap descriptor containing a copy of this data.

The data is interpreted as:

• a byte value defining the number of text characters or the length of binary data

followed by:

• the text characters or binary data. This resource data is interpreted as either 8 bit or 16 bit, depending on the build.

If the value of the leading byte is zero, the function assumes that no data follows the leading byte and returns a NULL pointer.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this build independent variant when the resource contains text. If the resource contains binary data, use the explicit 8 bit variant ReadHBufC8L().

Return value

HBufC* A pointer to the heap descriptor containing a copy of the data following the leading byte count at the current position within the resource buffer. The pointer can be NULL.

HBufC8* ReadHBufC8L();

Description

Interprets the data at the current buffer position as leading byte count data and constructs an 8 bit heap descriptor containing a copy of this data.

The data is interpreted as:

• a byte value defining the number of 8 bit text characters or the length of binary data

followed by:

• the 8 bit text characters or binary data.

If the value of the leading byte is zero, the function assumes that no data follows the leading byte and returns a NULL pointer.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this explicit 8 bit variant when the resource contains binary data. If the resource contains text, then use the build independent variant ReadHBufCL().

In general, this type of resource data corresponds to one of the following:

• a LTEXT type in a resource STRUCT declaration.

• a variable length array within a STRUCT declaration which includes the LEN BYTE keywords.

HBufC8*

Description

A pointer to the 8 bit heap descriptor containing a copy of the data following the leading byte count at the current position within the resource buffer.

The pointer can be NULL.

HBufC16* ReadHBufC16L();

Description

Interprets the data at the current buffer position as leading byte count data and constructs a 16 bit heap descriptor containing a copy of this data.

The data is interpreted as:

• a byte value defining the number of 16 bit text characters

followed by:

• the 16 bit text characters.

If the value of the leading byte is zero, the function assumes that no data follows the leading byte and returns a NULL pointer.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Do not use this explicit 16 bit variant when the resource contains binary data; use the explicit 8 bit variant instead. If the resource contains text, use the build independent variant ReadHBufCL().

Return value

HBufC16* A pointer to the 16 bit heap descriptor containing a copy of the data following the leading byte count at the current position within the resource buffer. The pointer can be NULL.

TPtrC ReadTPtrC();

Description

Interprets the data at the current buffer position as leading byte count data and constructs a non modifiable pointer descriptor to represent this data.

The data is interpreted as:

• a byte value defining the number of text characters or the length of binary data

followed by:

• the text characters or binary data. This resource data is interpreted as either 8 bit or 16 bit, depending on the build.

If the value of the leading byte is zero, calling Length() on the returned TPtrC returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this build independent variant when the resource contains text. If the resource contains binary data, use the explicit 8 bit variant ReadTPtrC8().

Return value

TPtrC A non modifiable pointer descriptor representing the data following the leading byte count at the current position within the resource buffer.

TPtrC8 ReadTPtrC8();

Description

Interprets the data at the current buffer position as leading byte count data and constructs an 8 bit non modifiable pointer descriptor to represent this data.

The data is interpreted as:

• a byte value defining the number of text characters or the length of binary data

followed by:

• the 8 bit text characters or binary data.

If the value of the leading byte is zero, calling Length() on the returned TPtrC8 returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this explicit 8 bit variant when the resource contains binary data. If the resource contains text, then use the build independent variant ReadTPtrC().

In general, this type of resource data corresponds to one of the following:

• a LTEXT type in a resource STRUCT declaration.

• a variable length array within a STRUCT declaration which includes the LEN BYTE keywords.

Return value

TPtrC8 An 8 bit non modifiable pointer descriptor representing the data following the leading byte count at the current position within the resource buffer.

TPtrC16 ReadTPtrC16();

Description

Interprets the data at the current buffer position as leading byte count data and constructs a 16 bit non modifiable pointer descriptor to represent this data.

The data is interpreted as:

• a byte value defining the number of 16 bit text characters

followed by:

• the 16 bit text characters.

If the value of the leading byte is zero, calling Length() on the returned TPtrC16 returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Do not use this explicit 16 bit variant when the resource contains binary data; use the explicit 8 bit variant instead. If the resource contains text, use the build independent variant ReadTPtrC().

Return value

TPtrC16 A 16 bit non modifiable pointer descriptor representing the data following the leading byte count at the current position within the resource buffer.

TPtrC ReadTPtrC(TInt aIndex,const TDesC8* aBuffer);

Description

Interprets the data within the specified resource buffer as an array of leading byte count data and constructs a non modifiable pointer descriptor to represent an element within this array.

The function sets the buffer containing the resource data and sets the current position to the start of this buffer. Any buffer set by a previous call to SetBuffer() etc, is lost.

The buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of text characters or the length of binary data

followed by:

• the text characters or binary data. This resource data is interpreted as either 8 bit or 16 bit, depending on the build.

If the value of the leading byte is zero, calling Length() on the returned TPtrC returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this build independent variant when the elements contain text. If the elements contain binary data, use the explicit 8 bit variant ReadTPtrC8(TInt,const TDesC8*).

Parameters

TInt aIndex The position of the element within the array. This value is relative to zero. const TDesC8* aBuffer The buffer containing the resource data.

Return value

TPtrC A non modifiable pointer descriptor representing the data following the leading byte count of the element at the specified position within the array.

See also:

• Using TResourceReader

TPtrC8 ReadTPtrC8(TInt aIndex,const TDesC8* aBuffer);

Description

Interprets the data within the specified resource buffer as an array of leading byte count data and constructs an 8 bit non modifiable pointer descriptor to represent an element within this array.

The function sets the buffer containing the resource data and sets the current position to the start of this buffer. Any buffer set by a previous call to SetBuffer() etc, is lost.

The buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of 8 bit text characters or the length of binary data

followed by:

• the 8 bit text characters or binary data.

If the value of the leading byte is zero, calling Length() on the returned TPtrC8 returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this explicit 8 bit variant when the resource contains binary data, If the resource contains text, then use the build independent variant ReadTPtrC(TInt,const TDesC8*).

Parameters

TInt aIndex The position of the element within the array. This value is relative to zero. const TDesC8* aBuffer The buffer containing the resource data.

Return value

TPtrC8 An 8 bit non modifiable pointer descriptor representing the data following the leading byte count of the element at the specified position within the array.

TPtrC16 ReadTPtrC16(TInt aIndex,const TDesC8* aBuffer);

Description

Interprets the data within the specified resource buffer as an array of leading byte count data and constructs a 16 bit non modifiable pointer descriptor to represent an element within this array.

The function sets the buffer containing the resource data and sets the current position to the start of this buffer. Any buffer set by a previous call to SetBuffer() etc., is lost.

The buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of 8 bit text characters or the length of binary data

followed by:

• the 16 bit text characters.

If the value of the leading byte is zero, calling Length() on the returned TPtrC16 returns zero.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Do not use this explicit 16 bit variant when the resource contains binary data; use the explicit 8 bit variant instead. If the resource contains text, use the build independent variant ReadTPtrC(TInt,const TDesC8*).

Parameters

TInt aIndex The position of the element within the array. This value is relative to zero. const TDesC8* aBuffer The buffer containing the resource data.

Return value

TPtrC16 A 16 bit non modifiable pointer descriptor representing the data following the leading byte count of the element at position within the array

CDesCArrayFlat* ReadDesCArrayL();

Description

Interprets the data at the current buffer position as an array of leading byte count data and constructs a build independent flat array of descriptors.

Each descriptor in the descriptor array corresponds to an element of the resource array.

At the current buffer position, the buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of text characters or the length of binary data

followed by:

• the text characters or binary data. This resource data is interpreted as either 8 bit or 16 bit, depending on the build.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this build independent variant when the elements contain text. If the elements contain binary data, use the explicit 8 bit variant ReadDesC8ArrayL().

Return value

CDesCArrayFlat* A pointer to a build independent flat descriptor array.

See also:

• CDesCArrayFlat

CDesC8ArrayFlat* ReadDesC8ArrayL();

Description

Interprets the data at the current buffer position as an array of leading byte count data and constructs a flat array of 8 bit descriptors.

Each descriptor in the descriptor array corresponds to an element of the resource array.

At the current buffer position, the buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of 8 bit text characters or the length of binary data

followed by:

• the text characters or binary data.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Use this explicit 8 bit variant when the resource contains binary data. If the elements of the resource array contain text, use the build independent variant of ReadDesCArrayL().

Return value

CDesC8ArrayFlat* A pointer to an 8 bit variant flat descriptor array.

See also:

• CDesC8ArrayFlat

CDesC16ArrayFlat* ReadDesC16ArrayL();

Description

Interprets the data at the current buffer position as an array of leading byte count data and constructs a flat array of 16 bit descriptors.

Each descriptor in the descriptor array corresponds to an element of the resource array.

At the current buffer position, the buffer is expected to contain an array of data elements preceded by a TInt16 value defining the number of elements within that array.

Each element of the array is interpreted as:

• a byte value defining the number of 8 bit text characters or the length of binary data

followed by:

• the 16 bit text characters.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Do not use this explicit 16 bit variant when the resource contains binary data; use the explicit 8 bit variant instead. If the resource contains text, use the build independent variant ReadDesCArrayL().

Return value

CDesC16ArrayFlat* A pointer to a 16 bit variant flat descriptor array.

See also:

• CDesC16ArrayFlat

TInt ReadInt8();

Description

Interprets the data at the current buffer position as a TInt8 type and returns the value as a TInt.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TInt8 corresponds to a BYTE type in a resource STRUCT declaration.

Note that in EPOC, a TInt is at least as big as a TInt8.

Return value

TInt The TInt8 value taken from the resource buffer.

TInt ReadInt16();

Description

Interprets the data at the current buffer position as a TInt16 type and returns the value as a TInt.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TInt16 corresponds to a WORD type in a resource STRUCT declaration.

Note that in EPOC, a TInt is at least as big as a TInt16.

Return value

TInt The TInt16 value taken from the resource buffer.

TInt ReadInt32();

Description

Interprets the data at the current buffer position as a TInt32 type and returns the value as a TInt.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TInt32 corresponds to a LONG type in a resource STRUCT declaration.

Note that in EPOC, TInt and TInt32 are the same size.

Return value

TInt The TInt32 value taken from the resource buffer.

TUint ReadUint8();

Description

Interprets the data at the current buffer position as a TUint8 type and returns the value as a TUint.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TUint8 corresponds to a BYTE type in a resource STRUCT declaration.

Note that in EPOC, a TUint is at least as big as a TUint8.

Return value

TUint The TUint8 value taken from the resource buffer.

TUint ReadUint16();

Description

Interprets the data at the current buffer position as a TUint16 type and returns the value as a TUint.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TUint16 corresponds to a WORD type in a resource STRUCT declaration.

Note that in EPOC, a TUint is at least as big as a TUint16.

Return value

TUint The TUint16 value taken from the resource buffer.

TUint ReadUint32();

Description

Interprets the data at the current buffer position as a TUint32 type and returns the value as a TUint.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TUint32 corresponds to a LONG type in a resource STRUCT declaration.

Note that in EPOC a TUint is the same size as a TUint32.

Return value

TUint The TUint32 value taken from the resource buffer.

TReal64 ReadReal64();

Description

Interprets the data at the current buffer position as a TReal64 type and returns the value as a TReal64.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

In general, a TReal64 corresponds to a DOUBLE type in a resource STRUCT declaration.

Return value

TReal64 The TReal64 value taken from the resource buffer.

void Read(TAny* aPtr,TInt aLength);

Description

Copies a specified length of data from the resource buffer, starting at the current position within the buffer, into the location pointed to by a specified pointer. No assumption is made about the type of data at being read.

The current position within the resource buffer is updated. If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Parameters

TAny* aPtr A pointer to the target location for data copied from the resource buffer. TInt aLength The length of data to be copied from the resource buffer.

void Advance(TInt aLength);

Description

Moves the current buffer position forwards by the specified amount.

If the resulting position lies beyond the end of the resource buffer, then the function raises a BAFL 4 panic.

Parameters

TInt aLength The length by which the current position is to be advanced.

void Rewind(TInt aLength);

Description

Moves the current buffer position backwards by the specified amount.

If the resulting position lies before the start of the resource buffer, then the function raises a BAFL 5 panic.

Parameters

TInt aLength The length by which the current position is to be moved backward.