RResourceFile Class Reference

#include <barsc.h>

class RResourceFile
Public Member Functions
RResourceFile()
IMPORT_C HBufC8 *AllocReadL(TInt)
IMPORT_C HBufC8 *AllocReadLC(TInt)
IMPORT_C voidClose()
IMPORT_C voidConfirmSignatureL(TInt)
IMPORT_C voidConfirmSignatureL()
TInt Offset()
IMPORT_C voidOpenL(RFs &, const TDesC &)
IMPORT_C voidOpenL(RFs &, const TDesC &, TUint, TInt)
IMPORT_C TBoolOwnsResourceId(TInt)
IMPORT_C TBoolOwnsResourceIdL(TInt)
IMPORT_C voidReadL(TDes8 &, TInt)
IMPORT_C TIntSignatureL()
IMPORT_C TUidTypeUidType()

Detailed Description

Accesses a resource file and reads the resource data into a buffer.

Interpretation of the data is achieved using the TResourceReader class.

RResourceFile instance behaviour when some problem occurs - it panics. Or asserts, if the used method is not "L" method.

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 heap buffers used by the source class instance will be shared with the destination class instance.

Expected behaviour when the RResourceFile instance is about to be destroyed: The class doesn't have destructor so compiler generated one will be used. Always call Close() to free allocated by the instance resources.

See also: TResourceReader

Constructor & Destructor Documentation

RResourceFile ( )

IMPORT_CRResourceFile()

Constructs a default resource file object.

Member Function Documentation

AllocReadL ( TInt )

IMPORT_C HBufC8 *AllocReadL(TIntaResourceId)const

Reads a resource into a heap descriptor and returns a pointer to that descriptor.

A heap descriptor of appropriate length is allocated for the resource. Ownership of the heap descriptor passes to the caller who must destroy it when it is no longer needed.

The search for the resource uses the following algorithm:

A resource id in the range 1 to 4095 is looked up in this resource file. The function leaves if there is no matching resource.

If the resource id is greater than 4095, then the most significant 20 bits of the resource id is treated as an offset and the least significant 12 bits is treated as the real resource id. If the offset matches the offset value defined for this file, then the resource is looked up in this resource file using the real resource id (i.e. the least significant 12 bits). If the offset does not match, then the function leaves.

Note, do not call this function until a call to ConfirmSignatureL() has completed successfully.

See also: RResourceFile::Offset() TBafPanic for panic codes.

Parameters
aResourceIdThe numeric id of the resource to be read.
Return Value
Pointer to an 8 bit heap descriptor containing the resource.
Leave Codes
KErrNotFound- there is no resource with aResourceId in the file.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

AllocReadLC ( TInt )

IMPORT_C HBufC8 *AllocReadLC(TIntaResourceId)const

Reads a resource into a heap descriptor, returns a pointer to that descriptor and pushes the pointer onto the cleanup stack.

A heap descriptor of appropriate length is allocated for the resource. Ownership of the heap descriptor passes to the caller who must destroy it and pop its pointer off the cleanup stack when it is no longer needed.

The search for the resource uses the following algorithm:

A resource id in the range 1 to 4095 is looked up in this resource file. The function leaves if there is no matching resource.

If the resource id is greater than 4095, then the most significant 20 bits of the resource id is treated as an offset and the least significant 12 bits is treated as the real resource id. If the offset matches the offset value defined for this file, then the resource is looked up in this resource file using the real resource id (i.e. the least significant 12 bits). If the offset does not match, then the function leaves.

Note, do not call this function until a call to ConfirmSignatureL() has completed successfully.

See also: RResourceFile::Offset() TBafPanic for panic codes.

Parameters
aResourceIdThe numeric id of the resource to be read.
Return Value
Pointer to a heap descriptor containing the resource.
Leave Codes
KErrNotFound- there is no resource with aResourceId in the file.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

Close ( )

IMPORT_C voidClose()

Closes the resource file reader. This function is called after finishing reading all resources.

ConfirmSignatureL ( TInt )

IMPORT_C voidConfirmSignatureL(TIntaSignature)

Initialises the offset value from the first resource.

The function assumes that the first resource in the file consists of two 32-bit integers. The first integer contains the version number and the second is a self-referencing link whose value is the offset for the resources in the file, plus 1.This function must be called before calling Offset(), AllocReadL(), AllocReadLC() or ReadL().

See also: TBafPanic for panic codes.

Parameters
aSignatureThis argument value is not used by the function.
Leave Codes
KErrCorrupt- wrong size of the first resource in the file. Probably the file is corrupted.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

ConfirmSignatureL ( )

IMPORT_C voidConfirmSignatureL()

Initialises the offset value from the first resource.

The function tests to catch cases where the first resource is not an RSS_SIGNATURE. It assumes that the first resource in the file consists of two 32-bit integers. The first integer contains the version number and the second is a self-referencing link whose value is the offset for the resources in the file, plus 1.This function must be called before calling Offset(), AllocReadL(), AllocReadLC() or ReadL().

See also: TBafPanic for panic codes.

Leave Codes
KErrCorrupt- wrong size of the first resource in the file. Probably the file is corrupted.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

Offset ( )

TInt Offset()const [inline]

Returns the offset value defined for this resource file.

This function must not be called until a call to ConfirmSignatureL() has completed successfully, otherwise the value returned by this function may be meaningless.

See also: RResourceFile::ConfirmSignatureL()

Return Value
The offset value defined for this resource file.

OpenL ( RFs &, const TDesC & )

IMPORT_C voidOpenL(RFs &aFs,
const TDesC &aName
)

Opens the resource file reader.

The resource file reader must be opened before reading resources or checking the signature of the resource file. This function initially closes the resource-file object if it is currently open. If a leave occurs during the function, the object is reverted to its closed state.

See also: TBafPanic for panic codes.

Parameters
aFsHandle to a file server session.
aNameFile to open as a resource file
Leave Codes
Thefunction leaves if the named file cannot be opened or the header record at the beginning of the file cannot be read.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

OpenL ( RFs &, const TDesC &, TUint, TInt )

IMPORT_C voidOpenL(RFs &aFs,
const TDesC &aName,
TUintaFileOffset,
TIntaFileSize
)

Opens the resource file reader.

The resource file reader must be opened before reading resources or checking the signature of the resource file. This function initially closes the resource-file object if it is currently open. If a leave occurs during the function, the object is reverted to its closed state.

See also: TBafPanic for panic codes.

Parameters
aFsHandle to a file server session
aNameFile to open as a resource file
aFileOffsetResource file section offset from the beginning of the file.
aFileSizeResource file section size.
Leave Codes
Functionleaves if the named file cannot be opened or the header record at the beginning of the file cannot be read.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

OwnsResourceId ( TInt )

IMPORT_C TBoolOwnsResourceId(TIntaResourceId)const

Tests whether the resource file owns the specified resource id.

The resource file owns the resource id if the most significant 20 bits of the resource id are zero or match the offset value as returned from a call to the DeprecatedInterface is deprecated because it is unsafe as it may leave. Offset() member function.

See also: RResourceFile::OwnsResourceIdL

Parameters
aResourceIdThe resource id to test or if the resource id is not out of range.
Return Value
True, if the resource file owns the id, false otherwise.

OwnsResourceIdL ( TInt )

IMPORT_C TBoolOwnsResourceIdL(TIntaResourceId)const

Tests whether the resource file owns the specified resource id.

The resource file owns the resource id if the most significant 20 bits of the resource id are zero or match the offset value as returned from a call to the Offset() member function or if the resource id is not out of range.

See also: TBafPanic for panic codes.

Parameters
aResourceIdThe resource id to test.
Return Value
True, if the resource file owns the id, false otherwise.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

ReadL ( TDes8 &, TInt )

IMPORT_C voidReadL(TDes8 &aDes,
TIntaResourceId
)const

Reads a resource specified by resource id into the specified descriptor.

The descriptor must be long enough to contain the entire resource

The search for the resource uses the following algorithm:

A resource id in the range 1 to 4095 is looked up in this resource file. The function leaves if there is no matching resource.

If the resource id is greater than 4095, then the most significant 20 bits of the resource id is treated as an offset and the least significant 12 bits is treated as the real resource id. If the offset matches the offset value defined for this file, then the resource is looked up in this resource file using the real resource id (i.e. the least significant 12 bits). If the offset does not match, then the function leaves.

Note, do not call this function until a call to ConfirmSignatureL() has completed successfully.

See also: TBafPanic for panic codes.

Parameters
aDesOn return, contains the resource that has been read. The function leaves if the descriptor is not long enough to contain the entire resource.
aResourceIdThe numeric id of the resource to be read.
Leave Codes
Thefunction leaves if this resource id is not in this resource file.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

SignatureL ( )

IMPORT_C TIntSignatureL()const

Returns this resource file's version number.

The function assumes that the first resource in the file consists of two 32-bit integers. The first integer contains the version number.

See also: RResourceFile::ConfirmSignatureL() TBafPanic for panic codes.

Return Value
The version number.
Leave Codes
KErrCorruptWrong size of the first resource in the file. Probably the file is corrupted.
Panic Codes
Ifthe file is corrupted - the method will panic in debug mode.

UidType ( )

IMPORT_C TUidTypeUidType()const

Retrieve the UID tuple of the opened resource file.

Pre-condition
OpenL() has been called successfully.

See also: TBafPanic for panic codes.

Return Value
The UIDs of the loaded resource file.
Panic Codes
Ifthe file is not opened or class data members initialization fails - the method will panic always.