1 // Copyright (c) 1997-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"
19 #include "BaCompileAssert.h"
21 #define UNUSED_VAR(a) a = a
23 /** Constructs a default resource file object. */
24 EXPORT_C RResourceFile::RResourceFile()
26 COMPILE_TIME_ASSERT(sizeof(RResourceFile)==sizeof(RResourceFileImpl));
27 //Creating the implementation instance with a placement new operator.
28 //All RResourceFileImpl resources deallocation must be done in its Close() method.
29 //There are some special requirements about RResourceFileImpl implementation:
30 // - it must be the same size as the RResourceFile implementation;
31 // - the offset of iOffset data member must be the same as the offset
32 // of iOffset data member of RResourceFile class before the changes -
33 // make the class using RResourceFileImpl;
34 new (iImpl) RResourceFileImpl;
37 /** Closes the resource file reader.
38 This function is called after finishing reading all resources. */
39 EXPORT_C void RResourceFile::Close()
44 /** Opens the resource file reader.
46 The resource file reader must be opened before reading resources or
47 checking the signature of the resource file. This function initially
48 closes the resource-file object if it is currently open. If a leave
49 occurs during the function, the object is reverted to its closed state.
51 @param aFs Handle to a file server session.
52 @param aName File to open as a resource file
53 @leave The function leaves if the named file cannot be opened or the header
54 record at the beginning of the file cannot be read.
55 @panic If the file is corrupted - the method will panic in debug mode.
56 @see TBafPanic for panic codes. */
57 EXPORT_C void RResourceFile::OpenL(RFs &aFs,const TDesC &aName)
59 DoOpenL(aFs, aName, 0, 0);
62 /** Opens the resource file reader.
64 The resource file reader must be opened before reading resources or
65 checking the signature of the resource file. This function initially
66 closes the resource-file object if it is currently open. If a leave
67 occurs during the function, the object is reverted to its closed state.
69 @param aFs Handle to a file server session
70 @param aName File to open as a resource file
71 @param aFileOffset Resource file section offset from the beginning of the file.
72 @param aFileSize Resource file section size.
73 @leave Function leaves if the named file cannot be opened or the header
74 record at the beginning of the file cannot be read.
75 @panic If the file is corrupted - the method will panic in debug mode.
76 @see TBafPanic for panic codes. */
77 EXPORT_C void RResourceFile::OpenL(RFs& aFs, const TDesC& aName, TUint aFileOffset, TInt aFileSize)
79 DoOpenL(aFs, aName, aFileOffset, aFileSize);
83 Retrieve the UID tuple of the opened resource file.
85 @pre OpenL() has been called successfully.
86 @return The UIDs of the loaded resource file.
87 @panic If the file is not opened or class data members initialization fails -
88 the method will panic always.
89 @see TBafPanic for panic codes. */
90 EXPORT_C TUidType RResourceFile::UidType() const
92 return Impl()->UidType();
95 /** Reads a resource specified by resource id into the specified descriptor.
97 The descriptor must be long enough to contain the entire resource
99 The search for the resource uses the following algorithm:
101 A resource id in the range 1 to 4095 is looked up in this resource file. The
102 function leaves if there is no matching resource.
104 If the resource id is greater than 4095, then the most significant 20 bits
105 of the resource id is treated as an offset and the least significant 12 bits
106 is treated as the real resource id. If the offset matches the offset value
107 defined for this file, then the resource is looked up in this resource file
108 using the real resource id (i.e. the least significant 12 bits). If the offset
109 does not match, then the function leaves.
111 Note, do not call this function until a call to ConfirmSignatureL() has completed
114 @param aDes On return, contains the resource that has been read.
115 The function leaves if the descriptor is not long enough to contain the entire resource.
116 @param aResourceId The numeric id of the resource to be read.
117 @leave The function leaves if this resource id is not in this
119 @panic If the file is corrupted - the method will panic in debug mode.
120 @see TBafPanic for panic codes. */
121 EXPORT_C void RResourceFile::ReadL(TDes8 &aDes,TInt aResourceId) const
123 Impl()->ReadL(aDes, aResourceId);
126 /** Reads a resource into a heap descriptor, returns a pointer to that descriptor
127 and pushes the pointer onto the cleanup stack.
129 A heap descriptor of appropriate length is allocated for the resource. Ownership
130 of the heap descriptor passes to the caller who must destroy it and pop its
131 pointer off the cleanup stack when it is no longer needed.
133 The search for the resource uses the following algorithm:
135 A resource id in the range 1 to 4095 is looked up in this resource file. The
136 function leaves if there is no matching resource.
138 If the resource id is greater than 4095, then the most significant 20 bits
139 of the resource id is treated as an offset and the least significant 12 bits
140 is treated as the real resource id. If the offset matches the offset value
141 defined for this file, then the resource is looked up in this resource file
142 using the real resource id (i.e. the least significant 12 bits). If the offset
143 does not match, then the function leaves.
145 Note, do not call this function until a call to ConfirmSignatureL() has completed
148 @param aResourceId The numeric id of the resource to be read.
149 @return Pointer to a heap descriptor containing the resource.
150 @leave KErrNotFound - there is no resource with aResourceId in the file.
151 @panic If the file is corrupted - the method will panic in debug mode.
152 @see RResourceFile::Offset()
153 @see TBafPanic for panic codes. */
154 EXPORT_C HBufC8* RResourceFile::AllocReadLC(TInt aResourceId) const
156 return Impl()->AllocReadLC(aResourceId);
159 /** Reads a resource into a heap descriptor and returns a pointer to that descriptor.
161 A heap descriptor of appropriate length is allocated for the resource. Ownership
162 of the heap descriptor passes to the caller who must destroy it when it is
165 The search for the resource uses the following algorithm:
167 A resource id in the range 1 to 4095 is looked up in this resource file. The
168 function leaves if there is no matching resource.
170 If the resource id is greater than 4095, then the most significant 20 bits
171 of the resource id is treated as an offset and the least significant 12 bits
172 is treated as the real resource id. If the offset matches the offset value
173 defined for this file, then the resource is looked up in this resource file
174 using the real resource id (i.e. the least significant 12 bits). If the offset
175 does not match, then the function leaves.
177 Note, do not call this function until a call to ConfirmSignatureL() has completed
180 @param aResourceId The numeric id of the resource to be read.
181 @return Pointer to an 8 bit heap descriptor containing the resource.
182 @leave KErrNotFound - there is no resource with aResourceId in the file.
183 @panic If the file is corrupted - the method will panic in debug mode.
184 @see RResourceFile::Offset()
185 @see TBafPanic for panic codes. */
186 EXPORT_C HBufC8* RResourceFile::AllocReadL(TInt aResourceId) const
188 HBufC8* resource = AllocReadLC(aResourceId);
189 CleanupStack::Pop(resource);
193 /** Initialises the offset value from the first resource.
195 The function assumes that the first resource in the file consists of
196 two 32-bit integers. The first integer contains the version number and
197 the second is a self-referencing link whose value is the offset for
198 the resources in the file, plus 1.This function must be called before
199 calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
201 @param aSignature This argument value is not used by the function.
202 @leave KErrCorrupt - wrong size of the first resource in the file.
203 Probably the file is corrupted.
204 @panic If the file is corrupted - the method will panic in debug mode.
205 @see TBafPanic for panic codes. */
206 EXPORT_C void RResourceFile::ConfirmSignatureL(TInt aSignature)
208 Impl()->ConfirmSignatureL(aSignature);
211 /** Initialises the offset value from the first resource.
213 The function tests to catch cases where the first resource is not an RSS_SIGNATURE.
214 It assumes that the first resource in the file consists of
215 two 32-bit integers. The first integer contains the version number and
216 the second is a self-referencing link whose value is the offset for
217 the resources in the file, plus 1.This function must be called before
218 calling Offset(), AllocReadL(), AllocReadLC() or ReadL().
220 @leave KErrCorrupt - wrong size of the first resource in the file.
221 Probably the file is corrupted.
222 @panic If the file is corrupted - the method will panic in debug mode.
223 @see TBafPanic for panic codes. */
224 EXPORT_C void RResourceFile::ConfirmSignatureL()
226 Impl()->ConfirmSignatureL();
229 /** Returns this resource file's version number.
231 The function assumes that the first resource in the file consists of two 32-bit integers.
232 The first integer contains the version number.
234 @return The version number.
235 @leave KErrCorrupt Wrong size of the first resource in the file.
236 Probably the file is corrupted.
237 @panic If the file is corrupted - the method will panic in debug mode.
238 @see RResourceFile::ConfirmSignatureL()
239 @see TBafPanic for panic codes. */
240 EXPORT_C TInt RResourceFile::SignatureL() const
242 return Impl()->SignatureL();
245 /** Tests whether the resource file owns the specified resource id.
247 The resource file owns the resource id if the most significant 20 bits of
248 the resource id are zero or match the offset value as returned from a call
249 to the Offset() member function.
250 @deprecated Interface is deprecated because it is unsafe as it may leave.
251 @see RResourceFile::OwnsResourceIdL
252 @param aResourceId The resource id to test or if the resource id is not out of range.
253 @return True, if the resource file owns the id, false otherwise.
255 EXPORT_C TBool RResourceFile::OwnsResourceId(TInt aResourceId) const
257 TBool retCode=EFalse;
258 TRAPD(errCode, retCode = OwnsResourceIdL (aResourceId));
264 /** Tests whether the resource file owns the specified resource id.
266 The resource file owns the resource id if the most significant 20 bits of
267 the resource id are zero or match the offset value as returned from a call
268 to the Offset() member function or if the resource id is not out of range.
270 @param aResourceId The resource id to test.
271 @return True, if the resource file owns the id, false otherwise.
272 @panic If the file is corrupted - the method will panic in debug mode.
273 @see TBafPanic for panic codes. */
274 EXPORT_C TBool RResourceFile::OwnsResourceIdL(TInt aResourceId) const
276 return Impl()->OwnsResourceIdL(aResourceId);
279 /** Opens the resource file reader.
282 @param aFs Handle to a file server session.
283 @param aName File to open as a resource file.
284 @param aFileOffset Resource file section offset from the beginning of the file.
285 @param aFileSize Resource file section size.
286 @leave The function leaves if the named file cannot be opened or the header
287 record at the beginning of the file cannot be read.
288 @panic If the file is corrupted - the method will panic in debug mode.
289 @see TBafPanic for panic codes. */
290 void RResourceFile::DoOpenL(RFs& aFs, const TDesC& aName, TUint aFileOffset, TInt aFileSize)
293 TBaAssert assertObj(TBaAssert::EPanic);
294 Impl()->OpenL(aFs, aName, assertObj, aFileOffset, aFileSize);
297 /** Returns the offset value defined for this resource file.
299 This function must not be called until a call to ConfirmSignatureL() has completed successfully,
300 otherwise the value returned by this function may be meaningless.
303 @return The offset value defined for this resource file. */
304 EXPORT_C TInt RResourceFile::Offset2() const
306 return Impl()->Offset();
309 /** The method returns a pointer to the object implementing resource file reader
313 @return Pointer to the implementation instance. */
314 RResourceFileImpl* RResourceFile::Impl()
316 return reinterpret_cast <RResourceFileImpl*> (iImpl);
319 /** The method returns a const pointer to the object implementing resource file reader
323 @return Const pointer to the implementation instance. */
324 const RResourceFileImpl* RResourceFile::Impl() const
326 return reinterpret_cast <const RResourceFileImpl*> (iImpl);