1 /* |
|
2 * Copyright (c) 2007-2007 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Permanent File Store for diagnostics test records. |
|
15 * libraries : |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 #ifndef DIAGRESULTSDBSTORE_H |
|
21 #define DIAGRESULTSDBSTORE_H |
|
22 |
|
23 //System includes |
|
24 #include <s32file.h> //CPermanentFileStore |
|
25 #include <f32file.h> //Rfs, RFile |
|
26 #include <e32base.h> |
|
27 |
|
28 class CDiagResultsDatabaseItem; |
|
29 class CDiagResultsDbTestRecord; |
|
30 class CDiagResultsDbTestRecordHandle; |
|
31 class TDiagResultsDatabaseTestRecordInfo; |
|
32 class CDiagResultsDbRecordEngineParam; |
|
33 |
|
34 /** |
|
35 * An interface that must be implemented in order to call |
|
36 * ExistingRecordsAsyncL that is an asynchronous method. |
|
37 * |
|
38 * @since S60 v5.0 |
|
39 **/ |
|
40 class MRecordLoadingObserver |
|
41 { |
|
42 public: |
|
43 /** |
|
44 * Returns an array of test records. Contains all test records from a |
|
45 * single database file. |
|
46 * |
|
47 * @param aError Indicates if there were any errors. |
|
48 * @param aArray An array of test records. Ownership is transferred. |
|
49 **/ |
|
50 virtual void ExistingRecordsL( TInt aError, |
|
51 RPointerArray<CDiagResultsDbTestRecord>* aArray ) = 0; |
|
52 |
|
53 }; |
|
54 |
|
55 /** |
|
56 * An interface that must be implemented in order to call CompleteRecordAsyncL. |
|
57 * |
|
58 * @since S60 v5.0 |
|
59 **/ |
|
60 class MRecordCompletionObserver |
|
61 { |
|
62 public: |
|
63 |
|
64 /** |
|
65 * This is called when test record is completed. |
|
66 * |
|
67 * @param aError Symbian error code or KErrNone. |
|
68 **/ |
|
69 virtual void CompletedRecordL( TInt aError ) = 0; |
|
70 }; |
|
71 |
|
72 /** |
|
73 * Permanent file store class that manipulates results database file. |
|
74 * Database files are saved under server's private directory. |
|
75 * For example epoc32\WINSCW\C\private\10282cd9\ in WINSCW. |
|
76 * Provides functions to load, save, compact and cleanup data. |
|
77 * |
|
78 * Files have format [UID].dat e.g. [21234563].dat |
|
79 * |
|
80 * Stream Ids of the test record handle are stored into the root stream. |
|
81 * Handles contain the stream ids to the test results. |
|
82 * |
|
83 * Implementation uses 3 kinds of streams: |
|
84 * 1) root stream |
|
85 * 2) Test record handle stream |
|
86 * 3) Test result stream |
|
87 * 4) Last results buffer (buffer for overflowing test results) |
|
88 * |
|
89 * In order to retrieve a test result, we must first know which record |
|
90 * is needed and then ask from the handle where test result is. |
|
91 * Of course we can browse all test records, because root stream |
|
92 * contains stream ids into test record handles. |
|
93 * |
|
94 * @since S60 v5.0 |
|
95 **/ |
|
96 class CDiagResultsDbStore : public CActive |
|
97 { |
|
98 public: |
|
99 |
|
100 /** |
|
101 * Destructor |
|
102 **/ |
|
103 ~CDiagResultsDbStore(); |
|
104 |
|
105 /** |
|
106 * NewL. |
|
107 * |
|
108 * @param aUid UID of the database file. This class manipulates only one |
|
109 * database file at a time. If multiple database files needs |
|
110 * to be open, use another instance. |
|
111 * @return New object. |
|
112 **/ |
|
113 static CDiagResultsDbStore* NewL( TUid aUid ); |
|
114 static CDiagResultsDbStore* NewLC( TUid aUid ); |
|
115 |
|
116 /** |
|
117 * Create and return a new record. Ownership is transferred. |
|
118 * |
|
119 * @return a new test record. |
|
120 **/ |
|
121 CDiagResultsDbTestRecordHandle* CreateNewRecordL( |
|
122 CDiagResultsDbRecordEngineParam* aEngineParam ); |
|
123 |
|
124 /** |
|
125 * Write test record into the database. |
|
126 * |
|
127 * @param aHandle The test record to be written into the database. |
|
128 * @return KErrNone or symbian error code. |
|
129 **/ |
|
130 TInt CompleteRecord( CDiagResultsDbTestRecordHandle& aHandle ); |
|
131 |
|
132 /** |
|
133 * Write one test item into the DB. |
|
134 * |
|
135 * @param aCommit Indicates should we commit the store. |
|
136 * @param aHandle Handle that is updated to contain the item. |
|
137 * @param aTestItem An item to be added. |
|
138 * |
|
139 * @return Symbian error code or KErrNone. |
|
140 **/ |
|
141 TInt CompleteTestResult( TBool aCommit, |
|
142 CDiagResultsDbTestRecordHandle& aHandle, |
|
143 CDiagResultsDatabaseItem& aTestItem ); |
|
144 |
|
145 /** |
|
146 * Search database for a test record handle. |
|
147 * Handle does not contain test results directly. It only contains |
|
148 * stream ids to the test results and general record info. |
|
149 * |
|
150 * @param aUid test record is searched based on the uid. |
|
151 * @return The found test record or NULL. |
|
152 **/ |
|
153 CDiagResultsDbTestRecordHandle* OpenExistingHandleL( TUid aUid ); |
|
154 |
|
155 |
|
156 /** |
|
157 * Search database for a test record. |
|
158 * |
|
159 * @param aUid test record is searched based on the uid. |
|
160 * @param aReadOnly indicates should we allow writing. |
|
161 * @return The found test record or NULL. |
|
162 */ |
|
163 CDiagResultsDbTestRecord* OpenExistingRecordL( TUid aUid, |
|
164 TBool aReadOnly ); |
|
165 |
|
166 /** |
|
167 * Opens a single database item. |
|
168 * @param aId Stream id that represents the item. |
|
169 * |
|
170 * @return The found item or NULL. |
|
171 **/ |
|
172 CDiagResultsDatabaseItem* OpenExistingTestResultL( TStreamId aId ); |
|
173 |
|
174 /** |
|
175 * Returns all record infos. Client is responsible for deleting the array. |
|
176 * |
|
177 * @return Record info array. |
|
178 **/ |
|
179 RArray<TDiagResultsDatabaseTestRecordInfo>* ExistingRecordInfosL(); |
|
180 |
|
181 /** |
|
182 * Retrieve all test records from the database asynchronously. |
|
183 * |
|
184 * @param aObserver Observer is notified after test records have |
|
185 * been loaded. |
|
186 **/ |
|
187 void ExistingRecordsAsyncL( MRecordLoadingObserver& aObserver ); |
|
188 |
|
189 |
|
190 |
|
191 /** |
|
192 * Open last results buffer. It contains the test results that would have |
|
193 * been otherwise deleted. These are needed when all last results are |
|
194 * retrieved. Use with CleanUpDatabaseUseLastResultsBufferL. |
|
195 * |
|
196 * @return Test record. |
|
197 **/ |
|
198 CDiagResultsDbTestRecord* OpenExistingLastResultsBufferL(); |
|
199 |
|
200 /** |
|
201 * Compacts database to have only necessary information. This should be |
|
202 * done as often as necessary after writing. Compacting should not be |
|
203 * done after reading! |
|
204 * However note that this operation could take a long time. |
|
205 **/ |
|
206 void CompactDatabase(); |
|
207 |
|
208 /** |
|
209 * Cleanup database. Used deletion algorithm is taken from the |
|
210 * Central Repository. |
|
211 * |
|
212 * @param aCommit ETrue commits the store. |
|
213 **/ |
|
214 void CleanUpDatabaseL( TBool aCommit ); |
|
215 |
|
216 /** |
|
217 * Read available test record handle uids. |
|
218 * |
|
219 * @param aUids Contains available test record handle uids. |
|
220 **/ |
|
221 void RecordUidsL( RArray<TUid>& aUids ); |
|
222 |
|
223 protected: //From CActive |
|
224 |
|
225 /** |
|
226 * Called from CActive::Cancel. |
|
227 **/ |
|
228 virtual void DoCancel(); |
|
229 |
|
230 /** |
|
231 * Asynchronous service function. |
|
232 **/ |
|
233 virtual void RunL(); |
|
234 |
|
235 /** |
|
236 * Called if error happens in RunL. |
|
237 **/ |
|
238 virtual TInt RunError(TInt aError); |
|
239 |
|
240 private: |
|
241 |
|
242 /** |
|
243 * Cleanup database to have only certain amount of test records |
|
244 * inside per each database file. |
|
245 * |
|
246 * @param aCommit ETrue commits the store. |
|
247 **/ |
|
248 void CleanUpDatabaseNoLastResultsL( TBool aCommit ); |
|
249 |
|
250 /** |
|
251 * Cleanup database and move some of the test results into the |
|
252 * last results buffer. This function guarantees that the DB |
|
253 * keeps last results. CleanUpDatabase does not do that. |
|
254 * |
|
255 * @param aCommit ETrue commits the store. |
|
256 **/ |
|
257 void CleanUpDatabaseUseLastResultsBufferL( TBool aCommit ); |
|
258 |
|
259 /** |
|
260 * Read all stream ids from the root stream. |
|
261 * |
|
262 * @param aIds StreamId array. |
|
263 **/ |
|
264 void ReadRootStreamL( RArray<TStreamId>& aIds ); |
|
265 |
|
266 /** |
|
267 * Create empty root stream. |
|
268 * |
|
269 * @param aStore Root stream is created into this store. |
|
270 **/ |
|
271 void CreateEmptyRootStreamL( CPermanentFileStore& aStore ); |
|
272 |
|
273 /** |
|
274 * Replace root stream with an array. |
|
275 * |
|
276 * @param aArray Array that replaces any existing root stream. |
|
277 **/ |
|
278 void ReplaceRootStreamL( RArray<TStreamId>& aArray ); |
|
279 |
|
280 /** |
|
281 * Write test record into the database file. |
|
282 * |
|
283 * @param aCompletedRecord is the record closed/completed or not. |
|
284 * @param aCommit Commit the store or not. |
|
285 * @param aTestRecord The test record to be written into the file. |
|
286 **/ |
|
287 void DoCompleteRecordL( CDiagResultsDbTestRecordHandle& aHandle ); |
|
288 |
|
289 /** |
|
290 * Complete test result i.e. write it into the store. |
|
291 * @param aHandle Handle to be written. |
|
292 * @param aTestItem Contains test results that are written into the store. |
|
293 **/ |
|
294 void DoCompleteTestResultL( TBool aCommit, |
|
295 CDiagResultsDbTestRecordHandle& aHandle, |
|
296 CDiagResultsDatabaseItem& aTestItem ); |
|
297 |
|
298 |
|
299 /** |
|
300 * Constructor. |
|
301 * |
|
302 * @param aDbUid Database file uid. |
|
303 **/ |
|
304 CDiagResultsDbStore( TUid aDbUid ); |
|
305 |
|
306 /** |
|
307 * ConstructL. |
|
308 **/ |
|
309 void ConstructL(); |
|
310 |
|
311 /** |
|
312 * Complete own request is needed in some cases because this class uses |
|
313 * CActive to partition tasks into smaller pieces. This function completes |
|
314 * TRequestStatus so that the RunL is called. |
|
315 **/ |
|
316 void CompleteOwnRequest(); |
|
317 |
|
318 //State of this class. These are used only in asynchronous methods. |
|
319 enum EState |
|
320 { |
|
321 ENotRunning, |
|
322 EGetRootStream, |
|
323 EGetRecord, |
|
324 ERecordsReady, |
|
325 }; |
|
326 |
|
327 enum EDeletionAlgorithm |
|
328 { |
|
329 EMaxRecordCountAlgorithm, |
|
330 ELastResultsAlgorithm, |
|
331 }; |
|
332 |
|
333 /** |
|
334 * Write handle into the store. Handle knows where test results are. |
|
335 * @param aHandle The handle that is written into the store. |
|
336 **/ |
|
337 void WriteHandleIntoDbL( CDiagResultsDbTestRecordHandle& aHandle ); |
|
338 |
|
339 |
|
340 /** |
|
341 * Append one ID into the root stream. |
|
342 * @param aId ID to be added. |
|
343 **/ |
|
344 void AppendRootStreamL( TStreamId& aId ); |
|
345 |
|
346 |
|
347 /** |
|
348 * Deletes the oldest handle from the store. |
|
349 * |
|
350 * @param aIds Root stream. |
|
351 **/ |
|
352 void DeleteOldestHandleL( RArray<TStreamId>& aIds ); |
|
353 |
|
354 /** |
|
355 * Delete handle and its test results. |
|
356 * |
|
357 * @param aIndex Index of the handle in the root stream. |
|
358 * @param aIds Root stream. |
|
359 * |
|
360 **/ |
|
361 void DeleteHandleL( TInt aIndex, RArray<TStreamId>& aIds ); |
|
362 |
|
363 /** |
|
364 * Create last results buffer. It can be used to store test results |
|
365 * that would be deleted otherwise. |
|
366 **/ |
|
367 void CreateLastResultsBufferStreamL(); |
|
368 |
|
369 /** |
|
370 * Open test record handle and its test results. |
|
371 * |
|
372 * @param aId Handle root stream ID. |
|
373 * @param aRecord Returned test record. |
|
374 * @param aHandle Returned test record handle. |
|
375 **/ |
|
376 void OpenExistingRecordAndHandleL( TStreamId aId, |
|
377 CDiagResultsDbTestRecord*& aRecord, |
|
378 CDiagResultsDbTestRecordHandle*& aHandle ); |
|
379 |
|
380 /** |
|
381 * Check last results buffer and add test results into it if needed. |
|
382 * |
|
383 * @param aIds Root stream. |
|
384 **/ |
|
385 ///@@@KSR: changes for Codescanner error val = High |
|
386 //void CheckOverflowingTestResults( RArray<TStreamId>& aIds ); |
|
387 void CheckOverflowingTestResultsL( RArray<TStreamId>& aIds ); |
|
388 |
|
389 /** |
|
390 * Return maximum file size defined in the Central Repository. |
|
391 * This can be used to prevent a DB file from using too much disk space. |
|
392 * |
|
393 * @return Maximum file size in bytes. |
|
394 **/ |
|
395 TInt GetMaximumFileSizeL(); |
|
396 |
|
397 /** |
|
398 * Return the deletion algorithm defined in the central repository. |
|
399 * |
|
400 * @return The type of the deletion algorithm. |
|
401 **/ |
|
402 TInt GetDeletionAlgorithmL(); |
|
403 |
|
404 /** |
|
405 * Get maximum file size from the central repository and check the file size. |
|
406 * |
|
407 * @param aRfs Opened file server session. |
|
408 * @param aFileName File name of the DB file. |
|
409 * @param aFileSize Size of the DB file in bytes. |
|
410 **/ |
|
411 void CheckMaximumFileSizeLimitL( RFs& aRfs, |
|
412 const TDesC& aFileName, |
|
413 TInt aFileSize ); |
|
414 |
|
415 private: // Data |
|
416 |
|
417 // Store that is owned by this class. Performs many file manipulation operations. |
|
418 CPermanentFileStore* iStore; |
|
419 |
|
420 // File DB uid. [UID].dat |
|
421 TUid iDbUid; |
|
422 |
|
423 // File server session |
|
424 RFs iRfs; |
|
425 |
|
426 // The database file. |
|
427 RFile iFile; |
|
428 |
|
429 // Loading observer to be notified async. |
|
430 MRecordLoadingObserver* iLoadingObserver; |
|
431 |
|
432 // Completion observer (notified async). |
|
433 MRecordCompletionObserver* iCompletionObserver; |
|
434 |
|
435 // Pointer to test record arrays. Used in async methods. |
|
436 RPointerArray<CDiagResultsDbTestRecord>* iRecordArray; |
|
437 |
|
438 // Contains available record ids. Used in async methods. |
|
439 RArray<TStreamId>* iRecordIds; |
|
440 |
|
441 // Used in async methods to remember what record was loaded. |
|
442 TInt iRecordNumber; |
|
443 |
|
444 // Contains the test record to be completed (Used only in async methods). |
|
445 CDiagResultsDbTestRecord* iTestRecord; |
|
446 |
|
447 // State of the asynchronous operation. |
|
448 EState iState; |
|
449 |
|
450 EDeletionAlgorithm iDeletionAlgorithm; |
|
451 }; |
|
452 |
|
453 #endif // DIAGRESULTSDBSTORE_H |
|