sl@0: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #include <barsc.h>
sl@0: #include "BaRscImpl.h"
sl@0: #include "BaAssert.h"
sl@0: #include "BaCompileAssert.h"
sl@0: 
sl@0: #define UNUSED_VAR(a) a = a
sl@0: 
sl@0: /** Constructs a default resource file object. */
sl@0: EXPORT_C RResourceFile::RResourceFile()
sl@0: 	{
sl@0: 	COMPILE_TIME_ASSERT(sizeof(RResourceFile)==sizeof(RResourceFileImpl));
sl@0: 	//Creating the implementation instance with a placement new operator.
sl@0: 	//All RResourceFileImpl resources deallocation must be done in its Close() method.
sl@0: 	//There are some special requirements about RResourceFileImpl implementation:
sl@0: 	//  - it must be the same size as the RResourceFile implementation;
sl@0: 	//  - the offset of iOffset data member must be the same as the offset
sl@0: 	//    of iOffset data member of RResourceFile class before the changes - 
sl@0: 	//    make the class using RResourceFileImpl;
sl@0: 	new (iImpl) RResourceFileImpl;
sl@0: 	}
sl@0: 
sl@0: /** Closes the resource file reader.
sl@0: This function is called after finishing reading all resources. */
sl@0: EXPORT_C void RResourceFile::Close()
sl@0: 	{
sl@0: 	Impl()->Close();
sl@0: 	}
sl@0: 
sl@0: /** Opens the resource file reader.
sl@0: 
sl@0: The resource file reader must be opened before reading resources or
sl@0: checking the signature of the resource file. This function initially
sl@0: closes the resource-file object if it is currently open. If a leave
sl@0: occurs during the function, the object is reverted to its closed state.
sl@0: 
sl@0: @param aFs Handle to a file server session.
sl@0: @param aName File to open as a resource file
sl@0: @leave The function leaves if the named file cannot be opened or the header 
sl@0: record at the beginning of the file cannot be read. 
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C void RResourceFile::OpenL(RFs &aFs,const TDesC &aName)
sl@0: 	{
sl@0: 	DoOpenL(aFs, aName, 0, 0);
sl@0: 	}
sl@0: 
sl@0: /** Opens the resource file reader.
sl@0: 
sl@0: The resource file reader must be opened before reading resources or
sl@0: checking the signature of the resource file. This function initially
sl@0: closes the resource-file object if it is currently open. If a leave
sl@0: occurs during the function, the object is reverted to its closed state.
sl@0: 
sl@0: @param aFs Handle to a file server session
sl@0: @param aName File to open as a resource file
sl@0: @param aFileOffset Resource file section offset from the beginning of the file.
sl@0: @param aFileSize Resource file section size.
sl@0: @leave Function leaves if the named file cannot be opened or the header 
sl@0: record at the beginning of the file cannot be read. 
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C void RResourceFile::OpenL(RFs& aFs, const TDesC& aName, TUint aFileOffset, TInt aFileSize)
sl@0: 	{
sl@0: 	DoOpenL(aFs, aName, aFileOffset, aFileSize);
sl@0: 	}
sl@0: 
sl@0: /** 
sl@0: Retrieve the UID tuple of the opened resource file.
sl@0: 
sl@0: @pre OpenL() has been called successfully.
sl@0: @return The UIDs of the loaded resource file.
sl@0: @panic If the file is not opened or class data members initialization fails - 
sl@0: the method will panic always.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C TUidType RResourceFile::UidType() const
sl@0: 	{
sl@0: 	return Impl()->UidType();
sl@0: 	}
sl@0: 
sl@0: /** Reads a resource specified by resource id into the specified descriptor.
sl@0: 
sl@0: The descriptor must be long enough to contain the entire resource
sl@0: 
sl@0: The search for the resource uses the following algorithm:
sl@0: 
sl@0: A resource id in the range 1 to 4095 is looked up in this resource file. The 
sl@0: function leaves if there is no matching resource.
sl@0: 
sl@0: If the resource id is greater than 4095, then the most significant 20 bits 
sl@0: of the resource id is treated as an offset and the least significant 12 bits 
sl@0: is treated as the real resource id. If the offset matches the offset value 
sl@0: defined for this file, then the resource is looked up in this resource file 
sl@0: using the real resource id (i.e. the least significant 12 bits). If the offset 
sl@0: does not match, then the function leaves.
sl@0: 
sl@0: Note, do not call this function until a call to ConfirmSignatureL() has completed 
sl@0: successfully.
sl@0: 
sl@0: @param aDes On return, contains the resource that has been read.
sl@0: The function leaves if the descriptor is not long enough to contain the entire resource.
sl@0: @param aResourceId The numeric id of the resource to be read.
sl@0: @leave The function leaves if this resource id is not in this
sl@0: resource file.
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C void RResourceFile::ReadL(TDes8 &aDes,TInt aResourceId) const
sl@0: 	{
sl@0: 	Impl()->ReadL(aDes, aResourceId);
sl@0: 	}
sl@0: 
sl@0: /** Reads a resource into a heap descriptor, returns a pointer to that descriptor 
sl@0: and pushes the pointer onto the cleanup stack.
sl@0: 
sl@0: A heap descriptor of appropriate length is allocated for the resource. Ownership 
sl@0: of the heap descriptor passes to the caller who must destroy it and pop its 
sl@0: pointer off the cleanup stack when it is no longer needed.
sl@0: 
sl@0: The search for the resource uses the following algorithm:
sl@0: 
sl@0: A resource id in the range 1 to 4095 is looked up in this resource file. The 
sl@0: function leaves if there is no matching resource.
sl@0: 
sl@0: If the resource id is greater than 4095, then the most significant 20 bits 
sl@0: of the resource id is treated as an offset and the least significant 12 bits 
sl@0: is treated as the real resource id. If the offset matches the offset value 
sl@0: defined for this file, then the resource is looked up in this resource file 
sl@0: using the real resource id (i.e. the least significant 12 bits). If the offset 
sl@0: does not match, then the function leaves.
sl@0: 
sl@0: Note, do not call this function until a call to ConfirmSignatureL() has completed 
sl@0: successfully.
sl@0: 
sl@0: @param aResourceId The numeric id of the resource to be read.
sl@0: @return Pointer to a heap descriptor containing the resource.
sl@0: @leave KErrNotFound - there is no resource with aResourceId in the file.
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see RResourceFile::Offset()
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C HBufC8* RResourceFile::AllocReadLC(TInt aResourceId) const
sl@0: 	{
sl@0: 	return Impl()->AllocReadLC(aResourceId);
sl@0: 	}
sl@0: 
sl@0: /** Reads a resource into a heap descriptor and returns a pointer to that descriptor.
sl@0: 
sl@0: A heap descriptor of appropriate length is allocated for the resource. Ownership 
sl@0: of the heap descriptor passes to the caller who must destroy it when it is 
sl@0: no longer needed.
sl@0: 
sl@0: The search for the resource uses the following algorithm:
sl@0: 
sl@0: A resource id in the range 1 to 4095 is looked up in this resource file. The 
sl@0: function leaves if there is no matching resource.
sl@0: 
sl@0: If the resource id is greater than 4095, then the most significant 20 bits 
sl@0: of the resource id is treated as an offset and the least significant 12 bits 
sl@0: is treated as the real resource id. If the offset matches the offset value 
sl@0: defined for this file, then the resource is looked up in this resource file 
sl@0: using the real resource id (i.e. the least significant 12 bits). If the offset 
sl@0: does not match, then the function leaves.
sl@0: 
sl@0: Note, do not call this function until a call to ConfirmSignatureL() has completed 
sl@0: successfully.
sl@0: 
sl@0: @param aResourceId The numeric id of the resource to be read.
sl@0: @return Pointer to an 8 bit heap descriptor containing the resource.
sl@0: @leave KErrNotFound - there is no resource with aResourceId in the file.
sl@0: @panic If the file is corrupted - the method will panic in debug mode. 
sl@0: @see RResourceFile::Offset()
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C HBufC8* RResourceFile::AllocReadL(TInt aResourceId) const
sl@0: 	{
sl@0: 	HBufC8* resource = AllocReadLC(aResourceId);
sl@0: 	CleanupStack::Pop(resource);
sl@0: 	return resource;
sl@0: 	}
sl@0: 
sl@0: /** Initialises the offset value from the first resource.
sl@0: 
sl@0: The function assumes that the first resource in the file consists of
sl@0: two 32-bit integers. The first integer contains the version number and
sl@0: the second is a self-referencing link whose value is the offset for
sl@0: the resources in the file, plus 1.This function must be called before
sl@0: calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
sl@0: 
sl@0: @param aSignature This argument value is not used by the function.
sl@0: @leave KErrCorrupt - wrong size of the first resource in the file.
sl@0: Probably the file is corrupted.
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C void RResourceFile::ConfirmSignatureL(TInt aSignature)
sl@0:     {
sl@0: 	Impl()->ConfirmSignatureL(aSignature);
sl@0:     }
sl@0: 
sl@0: /** Initialises the offset value from the first resource.
sl@0: 
sl@0: The function tests to catch cases where the first resource is not an RSS_SIGNATURE.
sl@0: It assumes that the first resource in the file consists of
sl@0: two 32-bit integers. The first integer contains the version number and
sl@0: the second is a self-referencing link whose value is the offset for
sl@0: the resources in the file, plus 1.This function must be called before
sl@0: calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
sl@0: 
sl@0: @leave KErrCorrupt - wrong size of the first resource in the file.
sl@0: Probably the file is corrupted.
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C void RResourceFile::ConfirmSignatureL()
sl@0: 	{
sl@0: 	Impl()->ConfirmSignatureL();
sl@0: 	}
sl@0: 
sl@0: /** Returns this resource file's version number.
sl@0: 
sl@0: The function assumes that the first resource in the file consists of two 32-bit integers. 
sl@0: The first integer contains the version number.
sl@0: 
sl@0: @return The version number.
sl@0: @leave KErrCorrupt Wrong size of the first resource in the file.
sl@0: Probably the file is corrupted.
sl@0: @panic If the file is corrupted - the method will panic in debug mode. 
sl@0: @see RResourceFile::ConfirmSignatureL()
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C TInt RResourceFile::SignatureL() const
sl@0: 	{
sl@0: 	return Impl()->SignatureL();
sl@0: 	}
sl@0: 
sl@0: /** Tests whether the resource file owns the specified resource id.
sl@0: 
sl@0: The resource file owns the resource id if the most significant 20 bits of 
sl@0: the resource id are zero or match the offset value as returned from a call 
sl@0: to the Offset() member function.
sl@0: @deprecated Interface is deprecated because it is unsafe as it may leave.
sl@0: @see RResourceFile::OwnsResourceIdL
sl@0: @param aResourceId The resource id to test or if the resource id is not out of range.
sl@0: @return True, if the resource file owns the id, false otherwise.
sl@0: */
sl@0: EXPORT_C TBool RResourceFile::OwnsResourceId(TInt aResourceId) const
sl@0: 	{
sl@0: 	TBool retCode=EFalse;
sl@0: 	TRAPD(errCode, retCode = OwnsResourceIdL (aResourceId));
sl@0:     UNUSED_VAR(errCode);
sl@0: 	return retCode;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /** Tests whether the resource file owns the specified resource id.
sl@0: 
sl@0: The resource file owns the resource id if the most significant 20 bits of 
sl@0: the resource id are zero or match the offset value as returned from a call 
sl@0: to the Offset() member function or if the resource id is not out of range.
sl@0: 
sl@0: @param aResourceId The resource id to test.
sl@0: @return True, if the resource file owns the id, false otherwise.
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: EXPORT_C TBool RResourceFile::OwnsResourceIdL(TInt aResourceId) const
sl@0: 	{
sl@0: 	return Impl()->OwnsResourceIdL(aResourceId);
sl@0: 	}
sl@0: 
sl@0: /** Opens the resource file reader.
sl@0: 
sl@0: @internalComponent
sl@0: @param aFs Handle to a file server session.
sl@0: @param aName File to open as a resource file.
sl@0: @param aFileOffset Resource file section offset from the beginning of the file.
sl@0: @param aFileSize Resource file section size.
sl@0: @leave The function leaves if the named file cannot be opened or the header 
sl@0: record at the beginning of the file cannot be read. 
sl@0: @panic If the file is corrupted - the method will panic in debug mode.
sl@0: @see TBafPanic for panic codes. */
sl@0: void RResourceFile::DoOpenL(RFs& aFs, const TDesC& aName, TUint aFileOffset, TInt aFileSize)
sl@0: 	{
sl@0: 	Close();
sl@0: 	TBaAssert assertObj(TBaAssert::EPanic);
sl@0: 	Impl()->OpenL(aFs, aName, assertObj, aFileOffset, aFileSize);
sl@0: 	}
sl@0: 
sl@0: /** Returns the offset value defined for this resource file.
sl@0: 
sl@0: This function must not be called until a call to ConfirmSignatureL() has completed successfully, 
sl@0: otherwise the value returned by this function may be meaningless.
sl@0: 
sl@0: @internalComponent
sl@0: @return The offset value defined for this resource file. */
sl@0: EXPORT_C TInt RResourceFile::Offset2() const
sl@0: 	{
sl@0: 	return Impl()->Offset();
sl@0: 	}
sl@0: 
sl@0: /** The method returns a pointer to the object implementing resource file reader
sl@0: functionality.
sl@0: 
sl@0: @internalComponent
sl@0: @return Pointer to the implementation instance. */
sl@0: RResourceFileImpl* RResourceFile::Impl()
sl@0: 	{
sl@0: 	return reinterpret_cast <RResourceFileImpl*> (iImpl);
sl@0: 	}
sl@0: 
sl@0: /** The method returns a const pointer to the object implementing resource file reader
sl@0: functionality.
sl@0: 
sl@0: @internalComponent
sl@0: @return Const pointer to the implementation instance. */
sl@0: const RResourceFileImpl* RResourceFile::Impl() const
sl@0: 	{
sl@0: 	return reinterpret_cast <const RResourceFileImpl*> (iImpl);
sl@0: 	}