1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
17 #include "BaRscImpl.h"
20 /** Creates CResourceFile instance.
21 @param aFs Handle to a file server session.
22 @param aName File to open as a resource file.
23 @param aFileOffset The resource file section offset from the beginning of the file.
24 @param aFileSize The resource file section size.
25 @leave KErrCorrupt if the file is corrupted.
26 @leave KErrNoMemory if there is not enough memory for the object. */
27 EXPORT_C CResourceFile* CResourceFile::NewL(RFs& aFs, const TDesC& aName,
28 TUint aFileOffset, TInt aFileSize)
30 CResourceFile* self = CResourceFile::NewLC(aFs, aName, aFileOffset, aFileSize);
31 CleanupStack::Pop(self);
35 /** Creates CResourceFile instance.
36 @param aRscFileBuffer a buffer containing one entire resource file
37 @return a CResourceFile instance corresponding to the rsc file passed
38 through the file buffer
39 @leave KErrCorrupt if the file buffer is corrupted.
40 @leave KErrNoMemory if there is not enough memory for the object. */
41 EXPORT_C CResourceFile* CResourceFile::NewL(const TDesC8& aRscFileBuffer)
43 CResourceFile* self = new (ELeave) CResourceFile;
44 CleanupStack::PushL(self);
45 self->ConstructL(aRscFileBuffer);
46 CleanupStack::Pop(self);
50 /** Creates CResourceFile instance.
51 @param aFs Handle to a file server session.
52 @param aName File to open as a resource file.
53 @param aFileOffset The resource file section offset from the beginning of the file.
54 @param aFileSize The resource file section size.
55 @leave KErrCorrupt if the file is corrupted.
56 @leave KErrNoMemory if there is not enough memory for the object. */
57 EXPORT_C CResourceFile* CResourceFile::NewLC(RFs& aFs, const TDesC& aName,
58 TUint aFileOffset, TInt aFileSize)
60 CResourceFile* self = new (ELeave) CResourceFile;
61 CleanupStack::PushL(self);
62 self->ConstructL(aFs, aName, aFileOffset, aFileSize);
66 /** Frees the resources, allocated by the instance.*/
67 EXPORT_C CResourceFile::~CResourceFile()
69 RResourceFileImpl* impl = Impl();
71 //RResourceFileImpl doesn't have a user defined destructor.
72 //All resources deallocation must be done in the RResourceFileImpl::Close() method.
75 /** Returns this resource file's UIDs.
77 @return The UIDs of the loaded resource file. */
78 EXPORT_C TUidType CResourceFile::UidType() const
80 return Impl()->UidType();
83 /** Reads a resource specified by resource id into the specified descriptor.
85 The descriptor must be long enough to contain the entire resource
87 The search for the resource uses the following algorithm:
89 A resource id in the range 1 to 4095 is looked up in this resource file. The
90 function leaves if there is no matching resource.
92 If the resource id is greater than 4095, then the most significant 20 bits
93 of the resource id is treated as an offset and the least significant 12 bits
94 is treated as the real resource id. If the offset matches the offset value
95 defined for this file, then the resource is looked up in this resource file
96 using the real resource id (i.e. the least significant 12 bits). If the offset
97 does not match, then the function leaves.
99 Note, do not call this function until a call to ConfirmSignatureL() has completed
102 @param aDes On return, contains the resource that has been read.
103 The function leaves if the descriptor is not long enough to contain the entire resource.
104 @param aResourceId The numeric id of the resource to be read. The function
105 leaves if this resource id is not in this resource file.
106 @leave The function leaves if this resource id is not in this
107 resource file or the file is corrupted. */
108 EXPORT_C void CResourceFile::ReadL(TDes8 &aDes,TInt aResourceId) const
110 Impl()->ReadL(aDes, aResourceId);
113 /** Reads a resource into a heap descriptor and returns a pointer to that descriptor.
115 A heap descriptor of appropriate length is allocated for the resource. Ownership
116 of the heap descriptor passes to the caller who must destroy it when it is
119 The search for the resource uses the following algorithm:
121 A resource id in the range 1 to 4095 is looked up in this resource file. The
122 function leaves if there is no matching resource.
124 If the resource id is greater than 4095, then the most significant 20 bits
125 of the resource id is treated as an offset and the least significant 12 bits
126 is treated as the real resource id. If the offset matches the offset value
127 defined for this file, then the resource is looked up in this resource file
128 using the real resource id (i.e. the least significant 12 bits). If the offset
129 does not match, then the function leaves.
131 Note, do not call this function until a call to ConfirmSignatureL() has completed
134 @param aResourceId The numeric id of the resource to be read.
135 @return Pointer to a heap descriptor containing the resource.
136 @leave The function leaves if this resource id is not in this
137 resource file or the file is corrupted.
138 @see RResourceFile::Offset() */
139 EXPORT_C HBufC8* CResourceFile::AllocReadL(TInt aResourceId) const
141 HBufC8* resource = AllocReadLC(aResourceId);
142 CleanupStack::Pop(resource);
146 /** Reads a resource into a heap descriptor, returns a pointer to that descriptor
147 and pushes the pointer onto the cleanup stack.
149 A heap descriptor of appropriate length is allocated for the resource. Ownership
150 of the heap descriptor passes to the caller who must destroy it and pop its
151 pointer off the cleanup stack when it is no longer needed.
153 The search for the resource uses the following algorithm:
155 A resource id in the range 1 to 4095 is looked up in this resource file. The
156 function leaves if there is no matching resource.
158 If the resource id is greater than 4095, then the most significant 20 bits
159 of the resource id is treated as an offset and the least significant 12 bits
160 is treated as the real resource id. If the offset matches the offset value
161 defined for this file, then the resource is looked up in this resource file
162 using the real resource id (i.e. the least significant 12 bits). If the offset
163 does not match, then the function leaves.
165 Note, do not call this function until a call to ConfirmSignatureL() has completed
168 @param aResourceId The numeric id of the resource to be read.
169 @return Pointer to a heap descriptor containing the resource.
170 @leave The function leaves if this resource id is not in this
171 resource file or the file is corrupted.
172 @see RResourceFile::Offset() */
173 EXPORT_C HBufC8* CResourceFile::AllocReadLC(TInt aResourceId) const
175 return Impl()->AllocReadLC(aResourceId);
178 /** Initialises the offset value from the first resource.
180 The function assumes that the first resource in the file consists of
181 two 32-bit integers. The first integer contains the version number and
182 the second is a self-referencing link whose value is the offset for
183 the resources in the file, plus 1.This function must be called before
184 calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
186 @param aSignature This argument value is not used by the function.
187 @leave The function leaves if this resource id is not in this
188 resource file or the file is corrupted. */
189 EXPORT_C void CResourceFile::ConfirmSignatureL(TInt aSignature)
191 Impl()->ConfirmSignatureL(aSignature);
194 /** Initialises the offset value from the first resource.
196 The function tests to catch cases where the first resource is not an RSS_SIGNATURE.
197 It assumes that the first resource in the file consists of
198 two 32-bit integers. The first integer contains the version number and
199 the second is a self-referencing link whose value is the offset for
200 the resources in the file, plus 1.This function must be called before
201 calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
202 @leave The function leaves if this resource id is not in this
203 resource file or the file is corrupted. */
204 EXPORT_C void CResourceFile::ConfirmSignatureL()
206 Impl()->ConfirmSignatureL();
209 /** Returns this resource file's version number.
211 The function assumes that the first resource in the file consists of two 32-bit integers.
212 The first integer contains the version number.
213 @return The version number.
214 @leave KErrCorrupt - the file is corrupted.
215 @see RResourceFile::ConfirmSignatureL() */
216 EXPORT_C TInt CResourceFile::SignatureL() const
218 return Impl()->SignatureL();
221 /** Tests whether the resource file owns the specified resource id.
222 The resource file owns the resource id if the most significant 20 bits of
223 the resource id are zero or match the offset value as returned from a call
224 to the Offset() member function or if the resource id is not out of range.
225 @param aResourceId The resource id to test.
226 @return True, if the resource file owns the id, false otherwise.
227 @leave KErrCorrupt - the file is corrupted. Some other error codes are possible. */
228 EXPORT_C TBool CResourceFile::OwnsResourceIdL(TInt aResourceId) const
230 return Impl()->OwnsResourceIdL(aResourceId);
233 /** Returns the offset value defined for this resource file.
235 This function must not be called until a call to ConfirmSignatureL()
236 has completed successfully, otherwise the value returned by this
237 function may be meaningless.
238 @return The offset value defined for this resource file. */
239 EXPORT_C TInt CResourceFile::Offset() const
241 return Impl()->Offset();
247 Initializes in place the implementation object.
249 CResourceFile::CResourceFile()
251 //Creating the implementation instance with a placement new operator.
252 new (iImpl) RResourceFileImpl;
255 /** @internalComponent
256 @param aFs Handle to a file server session.
257 @param aName File to open as a resource file.
258 @param aFileOffset The resource file section offset from the beginning of the file.
259 @param aFileSize The resource file section size.
260 @leave KErrCorrupt if the file is corrupted.
261 @leave KErrNoMemory if there is not enough memory for the object. */
262 void CResourceFile::ConstructL(RFs& aFs, const TDesC& aName,
263 TUint aFileOffset, TInt aFileSize)
265 TBaAssert assertObj(TBaAssert::ELeave);
266 Impl()->OpenL(aFs, aName, assertObj, aFileOffset, aFileSize);
269 /** @internalComponent
270 @param aRscFileBuffer a buffer containing a full rsc file
271 @leave KErrCorrupt if the file buffer is corrupted.
272 @leave KErrNoMemory if there is not enough memory for the object. */
273 void CResourceFile::ConstructL(const TDesC8& aRscFileBuffer)
275 TBaAssert assertObj(TBaAssert::ELeave);
276 Impl()->OpenL(aRscFileBuffer,assertObj);
279 /** @internalComponent
280 @return Non-const pointer to the implementation. */
281 RResourceFileImpl* CResourceFile::Impl()
283 return reinterpret_cast <RResourceFileImpl*> (iImpl);
286 /** @internalComponent
287 @return Const pointer to the implementation. */
288 const RResourceFileImpl* CResourceFile::Impl() const
290 return reinterpret_cast <const RResourceFileImpl*> (iImpl);