RResourceReader Class Reference

#include <barsread2.h>

class RResourceReader

Public Member Functions
	RResourceReader()
	~RResourceReader()
IMPORT_C void	AdvanceL(TInt)
IMPORT_C void	Close()
IMPORT_C void	OpenL(const CResourceFile *, TInt)
IMPORT_C void	OpenL(const TDesC8 &)
IMPORT_C void	OpenLC(const CResourceFile *, TInt)
IMPORT_C void	OpenLC(const TDesC8 &)
IMPORT_C CDesC16ArrayFlat *	ReadDesC16ArrayL()
IMPORT_C CDesC8ArrayFlat *	ReadDesC8ArrayL()
IMPORT_C CDesCArrayFlat *	ReadDesCArrayL()
IMPORT_C HBufC16 *	ReadHBufC16L()
IMPORT_C HBufC8 *	ReadHBufC8L()
IMPORT_C HBufC *	ReadHBufCL()
IMPORT_C TInt	ReadInt16L()
IMPORT_C TInt	ReadInt32L()
IMPORT_C TInt	ReadInt8L()
IMPORT_C void	ReadL(TAny *, TInt)
IMPORT_C TReal64	ReadReal64L()
IMPORT_C TPtrC16	ReadTPtrC16L()
IMPORT_C TPtrC8	ReadTPtrC8L()
IMPORT_C TPtrC	ReadTPtrCL()
IMPORT_C TUint	ReadUint16L()
IMPORT_C TUint	ReadUint32L()
IMPORT_C TUint	ReadUint8L()
IMPORT_C void	RewindL(TInt)

Detailed Description

Interprets resource data read from a resource file.

To use an instance of this class, pass the CResourceFile object containing the resource data with aResourceId ID to it, by calling OpenL() or OpenLC(). Close the reader calling Close() after finishing with the resource.

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 .

Expected behaviour when assignment operator or copy constructor is called: The class doesn't have assignment operator and copy constructor, so the compiler generated ones will be used. The buffer used by the source class instance will be shared with the destination class instance. However source and destination instances will have their own current position pointers, both pointed initially to the same buffer position.

Constructor & Destructor Documentation

RResourceReader ( )

IMPORT_C

RResourceReader

(

)

It creates the implementation in place - iImpl array, and sets the default leave/panic behaviour of the object - the object "L" methods will leave if something goes wrong.

~RResourceReader ( )

IMPORT_C

~RResourceReader

(

)

The method calls RResourceReader::Close() method to release allocated by the instance resources.

Member Function Documentation

AdvanceL ( TInt )

IMPORT_C void

AdvanceL

(

TInt

aLength

)

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 leaves with KErrEof code.

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

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

Leave Codes
KErrEof	The resulting position lies beyond the end of the resource buffer.

Close ( )

IMPORT_C void

(

)

Destroys the buffer containing the resource data.

Open() method should be called if you want to set the buffer and current position again.

If a one or more copies of the same RResourceReader object exist - they share the same resource data buffer. So destroying the RResourceReader object you will destroy the shared resource data buffer.

Post-condition: Buffer pointer is set to NULL.
Buffer current position pointer is set to NULL.

OpenL ( const CResourceFile *, TInt )

IMPORT_C void	OpenL	(	const CResourceFile *	aRscFile,
			TInt	aResourceId
		)

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
aRscFile	A pointer to the CResourceFile object, used as a resource data supplier.
aResourceId	The numeric id of the resource to be read.

Panic Codes
0	If aRscFile is NULL.

OpenL ( const TDesC8 & )

IMPORT_C void

OpenL

(

const TDesC8 &

aRscData

)

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
aRscData	A reference to an 8bit descriptor containing or representing resource data.

OpenLC ( const CResourceFile *, TInt )

IMPORT_C void	OpenLC	(	const CResourceFile *	aRscFile,
			TInt	aResourceId
		)

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.

A pointer to current RResourceReader instance is placed into the cleanup stack.

Parameters
aRscFile	A pointer to the CResourceFile object, used as a resource data supplier.
aResourceId	Numeric id of the resource to be read.

Panic Codes
0	If aRscFile is NULL.

OpenLC ( const TDesC8 & )

IMPORT_C void

OpenLC

(

const TDesC8 &

aRscData

)

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.

A pointer to current RResourceReader instance is placed into the cleanup stack.

Parameters
aRscData	A reference to an 8bit descriptor containing or representing resource data.

ReadDesC16ArrayL ( )

IMPORT_C CDesC16ArrayFlat *

ReadDesC16ArrayL

(

)

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 (the resource string/binary data length is limited to 255 characters max)

followed by:

the 16 bit text characters.

The current position within the resource buffer is updated.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: Pointer to a 16bit variant flat descriptor array.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadDesC8ArrayL ( )

IMPORT_C CDesC8ArrayFlat *

ReadDesC8ArrayL

(

)

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 (the resource string/binary data length is limited to 255 characters max)

followed by:

the text characters or binary data.

The current position within the resource buffer is updated.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: Pointer to an 8bit variant flat descriptor array.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadDesCArrayL ( )

IMPORT_C CDesCArrayFlat *

ReadDesCArrayL

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: Pointer to a build independent flat descriptor array.

Leave Codes
KErrEof	The resulting position lies beyond the end of the resource buffer.

ReadHBufC16L ( )

IMPORT_C HBufC16 *

ReadHBufC16L

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: 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.

Leave Codes
KErrCorrupt	The new buffer position is beyond the buffer end.

ReadHBufC8L ( )

IMPORT_C HBufC8 *

ReadHBufC8L

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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.

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: 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.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadHBufCL ( )

IMPORT_C HBufC *

ReadHBufCL

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: 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.

Leave Codes
KErrCorrupt	The resulting position lies beyond the end of the resource buffer.

ReadInt16L ( )

IMPORT_C TInt

ReadInt16L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TInt16 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadInt32L ( )

IMPORT_C TInt

ReadInt32L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TInt32 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadInt8L ( )

IMPORT_C TInt

ReadInt8L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TInt8 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadL ( TAny *, TInt )

IMPORT_C void	ReadL	(	TAny *	aPtr,
			TInt	aLength
		)

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.

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Parameters
aPtr	Pointer to the target location for data copied from the resource buffer.
aLength	The length of data to be copied from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadReal64L ( )

IMPORT_C TReal64

ReadReal64L

(

)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TReal64 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadTPtrC16L ( )

IMPORT_C TPtrC16

ReadTPtrC16L

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

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

Leave Codes
KErrCorrupt	The new buffer position is beyond the buffer end.

ReadTPtrC8L ( )

IMPORT_C TPtrC8

ReadTPtrC8L

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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.

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

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

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadTPtrCL ( )

IMPORT_C TPtrC

ReadTPtrCL

(

)

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 (the resource string/binary data length is limited to 255 characters max)

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.

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: Non modifiable pointer descriptor representing the data following the leading byte count of the element at the specified position within the array.

Leave Codes
KErrCorrupt	The resulting position lies beyond the end of the resource buffer.

ReadUint16L ( )

IMPORT_C TUint

ReadUint16L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TUint16 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadUint32L ( )

IMPORT_C TUint

ReadUint32L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TUint32 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

ReadUint8L ( )

IMPORT_C TUint

ReadUint8L

(

)

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.

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

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

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

Return Value: The TUint8 value taken from the resource buffer.

Leave Codes
KErrEof	The new buffer position is beyond the buffer end.

RewindL ( TInt )

IMPORT_C void

RewindL

(

TInt

aLength

)

Moves the current buffer position backwards by the specified amount.

Pre-condition: Open() is called to initialize RResourceReader data members.

Post-condition: Current buffer position is updated.

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

Leave Codes
KErrArgument	The resulting position lies before the start of the resource.