sl@0: // Copyright (c) 2003-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 <barsc2.h>
sl@0: #include "BaRscImpl.h"
sl@0: #include "BaAssert.h"
sl@0: 
sl@0: /** Creates CResourceFile instance.
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 The resource file section offset from the beginning of the file.
sl@0: @param aFileSize The resource file section size.
sl@0: @leave KErrCorrupt if the file is corrupted.
sl@0: @leave KErrNoMemory if there is not enough memory for the object. */
sl@0: EXPORT_C CResourceFile* CResourceFile::NewL(RFs& aFs, const TDesC& aName, 
sl@0: 											TUint aFileOffset, TInt aFileSize)
sl@0: 	{
sl@0: 	CResourceFile* self = CResourceFile::NewLC(aFs, aName, aFileOffset, aFileSize);
sl@0: 	CleanupStack::Pop(self);
sl@0: 	return self;
sl@0: 	}
sl@0: 
sl@0: /** Creates CResourceFile instance.
sl@0: @param aRscFileBuffer a buffer containing one entire resource file
sl@0: @return a CResourceFile instance corresponding to the rsc file passed
sl@0: through the file buffer
sl@0: @leave KErrCorrupt if the file buffer is corrupted.
sl@0: @leave KErrNoMemory if there is not enough memory for the object. */
sl@0: EXPORT_C CResourceFile* CResourceFile::NewL(const TDesC8& aRscFileBuffer)
sl@0: 	{
sl@0: 	CResourceFile* self = new (ELeave) CResourceFile;
sl@0: 	CleanupStack::PushL(self);
sl@0: 	self->ConstructL(aRscFileBuffer);
sl@0: 	CleanupStack::Pop(self);
sl@0: 	return self;
sl@0: 	}
sl@0: 
sl@0: /** Creates CResourceFile instance.
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 The resource file section offset from the beginning of the file.
sl@0: @param aFileSize The resource file section size.
sl@0: @leave KErrCorrupt if the file is corrupted.
sl@0: @leave KErrNoMemory if there is not enough memory for the object. */
sl@0: EXPORT_C CResourceFile* CResourceFile::NewLC(RFs& aFs, const TDesC& aName, 
sl@0: 											 TUint aFileOffset, TInt aFileSize)
sl@0: 	{
sl@0: 	CResourceFile* self = new (ELeave) CResourceFile;
sl@0: 	CleanupStack::PushL(self);
sl@0: 	self->ConstructL(aFs, aName, aFileOffset, aFileSize);
sl@0: 	return self;
sl@0: 	}
sl@0: 
sl@0: /** Frees the resources, allocated by the instance.*/
sl@0: EXPORT_C CResourceFile::~CResourceFile()
sl@0: 	{
sl@0: 	RResourceFileImpl* impl = Impl();
sl@0: 	impl->Close();
sl@0: 	//RResourceFileImpl doesn't have a user defined destructor.
sl@0: 	//All resources deallocation must be done in the RResourceFileImpl::Close() method.
sl@0: 	}
sl@0: 
sl@0: /** Returns this resource file's UIDs.
sl@0: 
sl@0: @return The UIDs of the loaded resource file. */
sl@0: EXPORT_C TUidType CResourceFile::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. The function 
sl@0: leaves if this resource id is not in this resource file.
sl@0: @leave The function leaves if this resource id is not in this
sl@0: resource file or the file is corrupted. */
sl@0: EXPORT_C void CResourceFile::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 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 a heap descriptor containing the resource.
sl@0: @leave  The function leaves if this resource id is not in this
sl@0: resource file or the file is corrupted.
sl@0: @see RResourceFile::Offset() */
sl@0: EXPORT_C HBufC8* CResourceFile::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: /** 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 The function leaves if this resource id is not in this
sl@0: resource file or the file is corrupted.
sl@0: @see RResourceFile::Offset() */
sl@0: EXPORT_C HBufC8* CResourceFile::AllocReadLC(TInt aResourceId) const
sl@0: 	{
sl@0: 	return Impl()->AllocReadLC(aResourceId);
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 The function leaves if this resource id is not in this
sl@0: resource file or the file is corrupted. */
sl@0: EXPORT_C void CResourceFile::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: @leave The function leaves if this resource id is not in this
sl@0: resource file or the file is corrupted. */
sl@0: EXPORT_C void CResourceFile::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: @return The version number.
sl@0: @leave KErrCorrupt - the file is corrupted.
sl@0: @see RResourceFile::ConfirmSignatureL() */
sl@0: EXPORT_C TInt CResourceFile::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: 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: @param aResourceId The resource id to test.
sl@0: @return True, if the resource file owns the id, false otherwise.
sl@0: @leave KErrCorrupt - the file is corrupted. Some other error codes are possible. */
sl@0: EXPORT_C TBool CResourceFile::OwnsResourceIdL(TInt aResourceId) const
sl@0: 	{
sl@0: 	return Impl()->OwnsResourceIdL(aResourceId);
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()
sl@0: has completed successfully, otherwise the value returned by this 
sl@0: function may be meaningless.
sl@0: @return The offset value defined for this resource file. */
sl@0: EXPORT_C TInt CResourceFile::Offset() const
sl@0: 	{
sl@0: 	return Impl()->Offset(); 
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @internalComponent
sl@0: Default constructor.
sl@0: Initializes in place the implementation object.
sl@0: */
sl@0: CResourceFile::CResourceFile()
sl@0: 	{
sl@0: 	//Creating the implementation instance with a placement new operator.
sl@0: 	new (iImpl) RResourceFileImpl;
sl@0: 	}
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 The resource file section offset from the beginning of the file.
sl@0: @param aFileSize The resource file section size.
sl@0: @leave KErrCorrupt if the file is corrupted.
sl@0: @leave KErrNoMemory if there is not enough memory for the object. */
sl@0: void CResourceFile::ConstructL(RFs& aFs, const TDesC& aName, 
sl@0: 								TUint aFileOffset, TInt aFileSize)
sl@0: 	{
sl@0: 	TBaAssert assertObj(TBaAssert::ELeave);
sl@0: 	Impl()->OpenL(aFs, aName, assertObj, aFileOffset, aFileSize);
sl@0: 	}
sl@0: 
sl@0: /** @internalComponent
sl@0: @param aRscFileBuffer a buffer containing a full rsc file
sl@0: @leave KErrCorrupt if the file buffer is corrupted.
sl@0: @leave KErrNoMemory if there is not enough memory for the object. */
sl@0: void CResourceFile::ConstructL(const TDesC8& aRscFileBuffer)
sl@0: 	{
sl@0: 	TBaAssert assertObj(TBaAssert::ELeave);
sl@0: 	Impl()->OpenL(aRscFileBuffer,assertObj);
sl@0: 	}
sl@0: 
sl@0: /** @internalComponent
sl@0: @return Non-const pointer to the implementation. */
sl@0: RResourceFileImpl* CResourceFile::Impl()
sl@0: 	{
sl@0: 	return reinterpret_cast <RResourceFileImpl*> (iImpl);
sl@0: 	}
sl@0: 
sl@0: /** @internalComponent
sl@0: @return Const pointer to the implementation. */
sl@0: const RResourceFileImpl* CResourceFile::Impl() const
sl@0: 	{
sl@0: 	return reinterpret_cast <const RResourceFileImpl*> (iImpl);
sl@0: 	}
sl@0: