|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #include <barsc.h> |
|
17 #include "BaRscImpl.h" |
|
18 #include "BaAssert.h" |
|
19 #include "BaCompileAssert.h" |
|
20 |
|
21 #define UNUSED_VAR(a) a = a |
|
22 |
|
23 /** Constructs a default resource file object. */ |
|
24 EXPORT_C RResourceFile::RResourceFile() |
|
25 { |
|
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; |
|
35 } |
|
36 |
|
37 /** Closes the resource file reader. |
|
38 This function is called after finishing reading all resources. */ |
|
39 EXPORT_C void RResourceFile::Close() |
|
40 { |
|
41 Impl()->Close(); |
|
42 } |
|
43 |
|
44 /** Opens the resource file reader. |
|
45 |
|
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. |
|
50 |
|
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) |
|
58 { |
|
59 DoOpenL(aFs, aName, 0, 0); |
|
60 } |
|
61 |
|
62 /** Opens the resource file reader. |
|
63 |
|
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. |
|
68 |
|
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) |
|
78 { |
|
79 DoOpenL(aFs, aName, aFileOffset, aFileSize); |
|
80 } |
|
81 |
|
82 /** |
|
83 Retrieve the UID tuple of the opened resource file. |
|
84 |
|
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 |
|
91 { |
|
92 return Impl()->UidType(); |
|
93 } |
|
94 |
|
95 /** Reads a resource specified by resource id into the specified descriptor. |
|
96 |
|
97 The descriptor must be long enough to contain the entire resource |
|
98 |
|
99 The search for the resource uses the following algorithm: |
|
100 |
|
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. |
|
103 |
|
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. |
|
110 |
|
111 Note, do not call this function until a call to ConfirmSignatureL() has completed |
|
112 successfully. |
|
113 |
|
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 |
|
118 resource file. |
|
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 |
|
122 { |
|
123 Impl()->ReadL(aDes, aResourceId); |
|
124 } |
|
125 |
|
126 /** Reads a resource into a heap descriptor, returns a pointer to that descriptor |
|
127 and pushes the pointer onto the cleanup stack. |
|
128 |
|
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. |
|
132 |
|
133 The search for the resource uses the following algorithm: |
|
134 |
|
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. |
|
137 |
|
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. |
|
144 |
|
145 Note, do not call this function until a call to ConfirmSignatureL() has completed |
|
146 successfully. |
|
147 |
|
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 |
|
155 { |
|
156 return Impl()->AllocReadLC(aResourceId); |
|
157 } |
|
158 |
|
159 /** Reads a resource into a heap descriptor and returns a pointer to that descriptor. |
|
160 |
|
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 |
|
163 no longer needed. |
|
164 |
|
165 The search for the resource uses the following algorithm: |
|
166 |
|
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. |
|
169 |
|
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. |
|
176 |
|
177 Note, do not call this function until a call to ConfirmSignatureL() has completed |
|
178 successfully. |
|
179 |
|
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 |
|
187 { |
|
188 HBufC8* resource = AllocReadLC(aResourceId); |
|
189 CleanupStack::Pop(resource); |
|
190 return resource; |
|
191 } |
|
192 |
|
193 /** Initialises the offset value from the first resource. |
|
194 |
|
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(). |
|
200 |
|
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) |
|
207 { |
|
208 Impl()->ConfirmSignatureL(aSignature); |
|
209 } |
|
210 |
|
211 /** Initialises the offset value from the first resource. |
|
212 |
|
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(). |
|
219 |
|
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() |
|
225 { |
|
226 Impl()->ConfirmSignatureL(); |
|
227 } |
|
228 |
|
229 /** Returns this resource file's version number. |
|
230 |
|
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. |
|
233 |
|
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 |
|
241 { |
|
242 return Impl()->SignatureL(); |
|
243 } |
|
244 |
|
245 /** Tests whether the resource file owns the specified resource id. |
|
246 |
|
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. |
|
254 */ |
|
255 EXPORT_C TBool RResourceFile::OwnsResourceId(TInt aResourceId) const |
|
256 { |
|
257 TBool retCode=EFalse; |
|
258 TRAPD(errCode, retCode = OwnsResourceIdL (aResourceId)); |
|
259 UNUSED_VAR(errCode); |
|
260 return retCode; |
|
261 } |
|
262 |
|
263 |
|
264 /** Tests whether the resource file owns the specified resource id. |
|
265 |
|
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. |
|
269 |
|
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 |
|
275 { |
|
276 return Impl()->OwnsResourceIdL(aResourceId); |
|
277 } |
|
278 |
|
279 /** Opens the resource file reader. |
|
280 |
|
281 @internalComponent |
|
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) |
|
291 { |
|
292 Close(); |
|
293 TBaAssert assertObj(TBaAssert::EPanic); |
|
294 Impl()->OpenL(aFs, aName, assertObj, aFileOffset, aFileSize); |
|
295 } |
|
296 |
|
297 /** Returns the offset value defined for this resource file. |
|
298 |
|
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. |
|
301 |
|
302 @internalComponent |
|
303 @return The offset value defined for this resource file. */ |
|
304 EXPORT_C TInt RResourceFile::Offset2() const |
|
305 { |
|
306 return Impl()->Offset(); |
|
307 } |
|
308 |
|
309 /** The method returns a pointer to the object implementing resource file reader |
|
310 functionality. |
|
311 |
|
312 @internalComponent |
|
313 @return Pointer to the implementation instance. */ |
|
314 RResourceFileImpl* RResourceFile::Impl() |
|
315 { |
|
316 return reinterpret_cast <RResourceFileImpl*> (iImpl); |
|
317 } |
|
318 |
|
319 /** The method returns a const pointer to the object implementing resource file reader |
|
320 functionality. |
|
321 |
|
322 @internalComponent |
|
323 @return Const pointer to the implementation instance. */ |
|
324 const RResourceFileImpl* RResourceFile::Impl() const |
|
325 { |
|
326 return reinterpret_cast <const RResourceFileImpl*> (iImpl); |
|
327 } |