Class CResourceFile

class CResourceFile : public CBase;

Description

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

Interpretation of the data is achieved using the RResourceReader class. CResourceFile methods behaviour when some problem occurs - it leaves with an error code. Most of the time the error code will be KErrCorrupt.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CResourceFile - Accesses a resource file or resource file buffer and reads the resource data int...

Members

Defined in CResourceFile:

• AllocReadL(TInt)constReads a resource into a heap descriptor and returns a pointer to that descriptor...
• AllocReadLC(TInt)constReads a resource into a heap descriptor, returns a pointer to that descriptor an...
• ConfirmSignatureL()Initialises the offset value from the first resource.
• ConfirmSignatureL(TInt)Initialises the offset value from the first resource.
• NewL(RFs &,const TDesC &,TUint,TInt)Creates CResourceFile instance.
• NewL(const TDesC8 &)Creates CResourceFile instance.
• NewLC(RFs &,const TDesC &,TUint,TInt)Creates CResourceFile instance.
• Offset()constReturns the offset value defined for this resource file.
• OwnsResourceIdL(TInt)constTests whether the resource file owns the specified resource id. The resource fil...
• ReadL(TDes8 &,TInt)constReads a resource specified by resource id into the specified descriptor.
• SignatureL()constReturns this resource file's version number.
• UidType()constReturns this resource file's UIDs.
• ~CResourceFile()Frees the resources, allocated by the instance.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

See also:

• RResourceReaderInterprets resource data read from a resource file.

IMPORT_C static CResourceFile* NewL(RFs &aFs, const TDesC &aName, TUint aFileOffset, TInt aFileSize);

Description

Creates CResourceFile instance.

Parameters

RFs &aFs Handle to a file server session. const TDesC16 &aName File to open as a resource file. TUint aFileOffset The resource file section offset from the beginning of the file. TInt aFileSize The resource file section size.

Return value

CResourceFile *

Leave codes

KErrCorrupt if the file is corrupted. KErrNoMemory if there is not enough memory for the object.

IMPORT_C static CResourceFile* NewLC(RFs &aFs, const TDesC &aName, TUint aFileOffset, TInt aFileSize);

Description

Creates CResourceFile instance.

Parameters

RFs &aFs Handle to a file server session. const TDesC16 &aName File to open as a resource file. TUint aFileOffset The resource file section offset from the beginning of the file. TInt aFileSize The resource file section size.

Return value

CResourceFile *

Leave codes

KErrCorrupt if the file is corrupted. KErrNoMemory if there is not enough memory for the object.

IMPORT_C static CResourceFile* NewL(const TDesC8 &aRscFileBuffer);

Description

Creates CResourceFile instance.

Parameters

const TDesC8 &aRscFileBuffer a buffer containing one entire resource file

Return value

CResourceFile * a CResourceFile instance corresponding to the rsc file passed through the file buffer

Leave codes

KErrCorrupt if the file buffer is corrupted. KErrNoMemory if there is not enough memory for the object.

IMPORT_C virtual ~CResourceFile();

Description

Frees the resources, allocated by the instance.

IMPORT_C TUidType UidType() const;

Description

Returns this resource file's UIDs.

Return value

TUidType The UIDs of the loaded resource file.

IMPORT_C void ReadL(TDes8 &aDes, TInt aResourceId) const;

Description

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 CResourceFile::ConfirmSignatureL() has completed successfully.

Parameters

TDes8 &aDes On return, contains the resource that has been read. The function leaves if the descriptor is not long enough to contain the entire resource. TInt aResourceId The numeric id of the resource to be read. The function leaves if this resource id is not in this resource file.

Leave codes

The function leaves if this resource id is not in this resource file or the file is corrupted.

IMPORT_C HBufC8* AllocReadL(TInt aResourceId) const;

Description

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 CResourceFile::ConfirmSignatureL() has completed successfully.

Parameters

TInt aResourceId The numeric id of the resource to be read.

Return value

HBufC8 * Pointer to a heap descriptor containing the resource.

Leave codes

The function leaves if this resource id is not in this resource file or the file is corrupted.

See also:

• RResourceFile::Offset()constReturns the offset value defined for this resource file.

IMPORT_C HBufC8* AllocReadLC(TInt aResourceId) const;

Description

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 CResourceFile::ConfirmSignatureL() has completed successfully.

Parameters

TInt aResourceId The numeric id of the resource to be read.

Return value

HBufC8 * Pointer to a heap descriptor containing the resource.

Leave codes

The function leaves if this resource id is not in this resource file or the file is corrupted.

See also:

• RResourceFile::Offset()constReturns the offset value defined for this resource file.

IMPORT_C void ConfirmSignatureL(TInt aSignature);

Description

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 CResourceFile::Offset()const, CResourceFile::AllocReadL(TInt)const, CResourceFile::AllocReadLC(TInt)const or CResourceFile::ReadL(TDes8 &,TInt)const.

Parameters

TInt aSignature This argument value is not used by the function.

Leave codes

The function leaves if this resource id is not in this resource file or the file is corrupted.

IMPORT_C void ConfirmSignatureL();

Description

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 CResourceFile::Offset()const, CResourceFile::AllocReadL(TInt)const, CResourceFile::AllocReadLC(TInt)const or CResourceFile::ReadL(TDes8 &,TInt)const.

Leave codes

The function leaves if this resource id is not in this resource file or the file is corrupted.

IMPORT_C TInt SignatureL() const;

Description

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.

Return value

TInt The version number.

Leave codes

KErrCorrupt - the file is corrupted.

See also:

• RResourceFile::ConfirmSignatureL()Initialises the offset value from the first resource.

IMPORT_C TBool OwnsResourceIdL(TInt aResourceId) const;

Description

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 CResourceFile::Offset()const member function or if the resource id is not out of range.

Parameters

TInt aResourceId The resource id to test.

Return value

TBool True, if the resource file owns the id, false otherwise.

Leave codes

KErrCorrupt - the file is corrupted. Some other error codes are possible.

IMPORT_C TInt Offset() const;

Description

Returns the offset value defined for this resource file.

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

Return value

TInt The offset value defined for this resource file.