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: Results database client interfaces. |
|
15 * Provides results database session and subsession. |
|
16 * libraries : DiagResultsDatabase.lib DiagResultsDatabase.dll |
|
17 * |
|
18 */ |
|
19 |
|
20 |
|
21 #ifndef DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H |
|
22 #define DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H |
|
23 |
|
24 #include <e32base.h> |
|
25 |
|
26 class CDiagResultsDatabaseItem; |
|
27 class TDiagResultsDatabaseTestRecordInfo; |
|
28 class CDiagResultsDbRecordEngineParam; |
|
29 |
|
30 /** |
|
31 * Diagnostics Results Database. Stores test results and more information. |
|
32 * Provides methods to retrieve and fetch new data. |
|
33 * Requires ReadDeviceData and WriteDeviceData capabilities even if the |
|
34 * session does not write anything. |
|
35 * |
|
36 * Results database is a permanent file store based solution. |
|
37 * Database files are stored under WINSCW\C\private\10282cd9 in emulator |
|
38 * environment. |
|
39 * |
|
40 * It is recommended to have only one open RDiagResultsDatabase per thread. |
|
41 * There should be only one writer and multiple readers at the same time |
|
42 * accessing the same database file. It is possible that there are multiple |
|
43 * DB files for example when there are two diagnostics applications in the |
|
44 * system. |
|
45 * |
|
46 * @since S60 v5.0 |
|
47 **/ |
|
48 class RDiagResultsDatabase : public RSessionBase |
|
49 { |
|
50 public: |
|
51 |
|
52 /** |
|
53 * Constructor |
|
54 **/ |
|
55 IMPORT_C RDiagResultsDatabase(); |
|
56 |
|
57 /** |
|
58 * Destructor |
|
59 **/ |
|
60 IMPORT_C ~RDiagResultsDatabase(); |
|
61 |
|
62 /** |
|
63 * Connect to the results database to a DB file. This must be called before |
|
64 * trying to use this class, otherwise KERN-EXEC 0 will crash your app. |
|
65 * Only one RDiagResultsDatabase connection is recommended per application, |
|
66 * because server sessions consume significant amount of system resources. |
|
67 * Share the session inside your thread! Subsessions are much more lighter. |
|
68 * |
|
69 * Calling connect creates the DB file inside server's private directory. |
|
70 * If for some reason database is corrupted, the DB file should be deleted |
|
71 * manually. |
|
72 * |
|
73 * @param aAppUid Unique identifier of the application. Each application has |
|
74 * its own store. Applications can access to another |
|
75 * applications's database if they know their UID. |
|
76 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
77 * error codes. If calling process does not have access rights, |
|
78 * KErrPermissionDenied is returned. ReadDeviceData+WriteDeviceData are |
|
79 * required. KErrDiskFull is returned if there is not enough space |
|
80 * on c-drive. |
|
81 **/ |
|
82 IMPORT_C TInt Connect( TUid aAppUid ); |
|
83 |
|
84 /** |
|
85 * Close the session with the server. Handle is not valid anymore. |
|
86 * |
|
87 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
88 * error codes. |
|
89 **/ |
|
90 IMPORT_C TInt Close(); |
|
91 |
|
92 /** |
|
93 * Returns the version number of the server. |
|
94 * |
|
95 * @return The version number. |
|
96 **/ |
|
97 IMPORT_C TVersion Version() const; |
|
98 |
|
99 /** |
|
100 * Get the current number of test records in the database. |
|
101 * |
|
102 * @param aCount the number of records. |
|
103 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
104 * error codes. |
|
105 **/ |
|
106 IMPORT_C TInt GetRecordCount ( TUint& aCount ) const; |
|
107 |
|
108 /** |
|
109 * Returns the maximum number of records for each application. The number |
|
110 * is defined in the central repository and it is static for all applications. |
|
111 * It is guarenteed that the DB file contains only the maxsize records and |
|
112 * not more. Old test records are deleted when new test records are |
|
113 * completed. |
|
114 * |
|
115 * @param aMaxSize The maximum number of test records. |
|
116 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
117 * error codes. |
|
118 **/ |
|
119 IMPORT_C static TInt GetDatabaseMaximumSize( TInt& aMaxSize ); |
|
120 |
|
121 /** |
|
122 * Returns an array of record Ids. The oldest records are at the beginning |
|
123 * of the array. Test record are sorted based on creation time. |
|
124 * |
|
125 * @param aSortedRecordUidArray An array of UIds. The array is sorted |
|
126 * based on time. |
|
127 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
128 * error codes. |
|
129 **/ |
|
130 IMPORT_C TInt GetRecordUids ( CArrayFixFlat<TUid>& aSortedRecordUidArray ) const; |
|
131 |
|
132 /** |
|
133 * Returns id to last test record. The last record cannot be |
|
134 * still open for writing! Test record are sorted based on creation time. |
|
135 * |
|
136 * @param aRecordUid Unique identifier of the record. |
|
137 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
138 * error codes. Returns KErrNotFound if there are no records. |
|
139 **/ |
|
140 IMPORT_C TInt GetLastRecord ( TUid& aRecordUid ) const; |
|
141 |
|
142 /** |
|
143 * Returns id to last suspended or incompleted test record. |
|
144 * The last record cannot be still open for writing! Returns KErrNotFound |
|
145 * if there are no suspended or incomplete test records. |
|
146 * |
|
147 * @param aRecordUid Unique identifier of the record. |
|
148 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
149 * error codes. Returns KErrNotFound if there are no suspended test records. |
|
150 **/ |
|
151 IMPORT_C TInt GetLastNotCompletedRecord ( TUid& aRecordUid ) const; |
|
152 |
|
153 /** |
|
154 * Returns an overview from all records. |
|
155 * |
|
156 * @param aInfoArray returns an array of record infos. |
|
157 * @see TDiagResultsDatabaseTestRecordInfo. |
|
158 **/ |
|
159 IMPORT_C TInt GetAllRecordInfos ( |
|
160 CArrayFixFlat<TDiagResultsDatabaseTestRecordInfo>& aInfoArray ); |
|
161 |
|
162 /** |
|
163 * Initiate retrieving of last results. After request is completed, |
|
164 * data can be fetched using GetLastResults method. |
|
165 * |
|
166 * @param aUidArray An array of uid used to identify plug-ins. |
|
167 * @param aStatus Completion status. |
|
168 **/ |
|
169 IMPORT_C void InitiateGetLastResults ( const CArrayFixFlat<TUid>& aUidArray, |
|
170 TRequestStatus& aStatus ); |
|
171 |
|
172 /** |
|
173 * Cancel InitiateGetLastResults. |
|
174 **/ |
|
175 IMPORT_C void CancelInitiateGetLastResults () const; |
|
176 |
|
177 /** |
|
178 * Get list of last results. Last result means that the plug-in has passed / failed |
|
179 * test result. |
|
180 * |
|
181 * GetLastResults deletes data after this function |
|
182 * is called, so InitiateGetLastResults must be called if data is needed |
|
183 * again. Client is responsible for deleting the returned array. Contains |
|
184 * null values if the searched uid was not found. There should be the same |
|
185 * number of cells in UidArray and in the results array. |
|
186 * |
|
187 * @param aResults Returned results array. Client is responsible for |
|
188 * deleting the array. |
|
189 * |
|
190 * @return KErrNotReady if this is called before InitiateGetLastResults. |
|
191 */ |
|
192 IMPORT_C TInt GetLastResults ( RPointerArray<CDiagResultsDatabaseItem>& aResults ) const; |
|
193 |
|
194 /** |
|
195 * Get last (the newest) test result of a test plug-in. The algorithm searches for a |
|
196 * test result that is either passed or failed. This is also asynchronous operation, |
|
197 * because all records have to be browsed in worst case scenario (that is, when |
|
198 * the plug-in uid is not found). Call GetLastResult when test result is needed. |
|
199 * |
|
200 * |
|
201 * @param aTestPluginUid UID of a plug-in. |
|
202 * @param aStatus Asynchronous request status. |
|
203 * |
|
204 */ |
|
205 IMPORT_C void InitiateGetLastResult ( TUid aTestPluginUid, |
|
206 TRequestStatus& aStatus ); |
|
207 |
|
208 |
|
209 /** |
|
210 * Get last result of a test plug-in. |
|
211 * |
|
212 * @param aItem Test result or NULL if not found. |
|
213 * @retrun KErrNotReady if this is called before InitiateGetLastResult. |
|
214 **/ |
|
215 IMPORT_C TInt GetLastResult ( CDiagResultsDatabaseItem*& aItem ); |
|
216 |
|
217 private: |
|
218 |
|
219 /** |
|
220 * Leaving version of the service functions. Look above for explanations. |
|
221 **/ |
|
222 void DoConnectL (TUid aAppUid); |
|
223 |
|
224 void DoGetRecordUidsL( CArrayFixFlat<TUid>& aSortedRecordUidArray ) const; |
|
225 |
|
226 /* |
|
227 * @see GetDatabaseMaximumSize() |
|
228 */ |
|
229 static void DoGetDatabaseMaximumSizeL( TInt& aMaxSize ); |
|
230 |
|
231 void DoGetAllRecordInfosL ( CArrayFixFlat<TDiagResultsDatabaseTestRecordInfo>& aInfoArray); |
|
232 |
|
233 void DoGetLastResultsL ( RPointerArray<CDiagResultsDatabaseItem>& aResults ) const; |
|
234 |
|
235 void WriteArrayIntoBufferL( const CArrayFixFlat<TUid>& aUidArray ); |
|
236 |
|
237 void DoGetLastResultL ( CDiagResultsDatabaseItem*& aItem ); |
|
238 |
|
239 private: |
|
240 |
|
241 // Flat dynamic buffer. |
|
242 CBufFlat* iBuffer; |
|
243 |
|
244 // is the connection already open. |
|
245 TBool iOpen; |
|
246 |
|
247 //Buffer pointer |
|
248 TPtr8 iPtr; |
|
249 }; |
|
250 |
|
251 /** |
|
252 * Sub-session to Diagnostics Results Database. This API is used to |
|
253 * handle a Test record. A test record is a collection of test results. |
|
254 * |
|
255 * Test record is always written into the file, when updates are necessary. |
|
256 * |
|
257 * |
|
258 * @since S60 v5.0 |
|
259 **/ |
|
260 class RDiagResultsDatabaseRecord : public RSubSessionBase |
|
261 { |
|
262 public: |
|
263 |
|
264 /** |
|
265 * Test record status. |
|
266 **/ |
|
267 enum TRecordStatus |
|
268 { |
|
269 EOpen, // Currently open for writing. |
|
270 ESuspended, // ::Suspend() is called. |
|
271 ECrashed, // It was open previously, and it was not |
|
272 // closed properly. |
|
273 EPartiallyCompleted, // Record is completed (not resumable), but not |
|
274 // all tests were completed. |
|
275 ECompleted // Record is completed (not resumable), and all |
|
276 // tests were completed. |
|
277 }; |
|
278 |
|
279 /** |
|
280 * Constructor |
|
281 **/ |
|
282 IMPORT_C RDiagResultsDatabaseRecord(); |
|
283 |
|
284 /** |
|
285 * Destructor |
|
286 **/ |
|
287 IMPORT_C ~RDiagResultsDatabaseRecord(); |
|
288 |
|
289 /** |
|
290 * Connects to a test record. There must be at least one created record. |
|
291 * If the specified record is not found, KErrNotFound is returned. |
|
292 * Opened test record can be modified if the test record has not been |
|
293 * completed (= TestCompleted called). |
|
294 * |
|
295 * @param aSession open database session. |
|
296 * @param aRecordId specifies the record where we want to connect. |
|
297 * @param aReadOnly Indicates is the test record opened in read-only mode. |
|
298 * If read-only = EFalse, the test record can overwrite |
|
299 * test records that are not completed already. If |
|
300 * the test record is completed it can be opened only |
|
301 * in read-mode. |
|
302 * |
|
303 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
304 * error codes. Returns KErrAlreadyExists if subsession is connected. |
|
305 **/ |
|
306 IMPORT_C TInt Connect( RDiagResultsDatabase& aSession, |
|
307 TUid aRecordId, |
|
308 TBool aReadOnly ); |
|
309 |
|
310 /** |
|
311 * Creates a new record and returns the uid of that record. |
|
312 * Writes empty test record into the file. Create new record opens the record |
|
313 * always in Write mode. |
|
314 * |
|
315 * @param aSession open database session. |
|
316 * @param aRecordId a new unique identifier is returned that is used to |
|
317 * identify particular test record. Client can use the record ID to access |
|
318 * the same record again. |
|
319 * @param aEngineParam Engine parameters. |
|
320 * |
|
321 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
322 * error codes. Returns KErrAlreadyExists if subsession is connected. |
|
323 * KErrDiskFull is returned if there is not enough space on c-drive. |
|
324 **/ |
|
325 IMPORT_C TInt CreateNewRecord( RDiagResultsDatabase& aSession, |
|
326 TUid& aRecordId, |
|
327 CDiagResultsDbRecordEngineParam& aEngineParam ); |
|
328 |
|
329 /** |
|
330 * Retrieve parameters of the diagnostics engine. These are needed in |
|
331 * Suspend/Resume functionality. |
|
332 * |
|
333 * @param aEngineParam Engine parameters. Ownership is transferred. |
|
334 * Client is responsible for deleting the object. |
|
335 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
336 * error codes. |
|
337 **/ |
|
338 IMPORT_C TInt GetEngineParam( CDiagResultsDbRecordEngineParam*& aEngineParam ) const; |
|
339 |
|
340 |
|
341 /** |
|
342 * Get record status. |
|
343 * |
|
344 * @param aRecordStatus The status of the record. |
|
345 * @see TRecordStatus in the beginning of the class declaration. |
|
346 * |
|
347 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
348 * error codes. |
|
349 **/ |
|
350 IMPORT_C TInt GetStatus( TRecordStatus& aRecordStatus ) const; |
|
351 |
|
352 /** |
|
353 * Close subsession. Does not write test record into the file. |
|
354 * |
|
355 * @return Symbian error code or KErrNone. |
|
356 **/ |
|
357 IMPORT_C void Close(); |
|
358 |
|
359 /** |
|
360 * Suspend test record. Same as complete, but the test record can be modified |
|
361 * on next connect.Writes test suspend time into test record info. |
|
362 * |
|
363 * @return Symbian error code or KErrNone. |
|
364 **/ |
|
365 IMPORT_C TInt Suspend(); |
|
366 |
|
367 /** |
|
368 * Indicates has this test record been suspended. |
|
369 * @param aSuspended Returns has this test record been suspended(ETrue), |
|
370 * otherwise EFalse. |
|
371 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
372 * error codes. |
|
373 **/ |
|
374 IMPORT_C TInt IsSuspended( TBool& aSuspended ) const; |
|
375 |
|
376 /** |
|
377 * Returns the record UID of this subsession. |
|
378 * |
|
379 * @param aRecordUid Record ID of the subsession. |
|
380 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
381 * error codes. |
|
382 **/ |
|
383 IMPORT_C TInt GetTestRecordId( TUid& aRecordUid ) const; |
|
384 |
|
385 /** |
|
386 * Write test completion time/date to the record and prevent further |
|
387 * writing. Handle is still valid. However, it cannot be used for adding |
|
388 * any more test results. During completion database file is cleaned up from |
|
389 * old test records (limited by GetDatabaseMaximumSize method). |
|
390 * |
|
391 * Test completion is synchronous operation because only record handle must be |
|
392 * updated (fixed size stream). |
|
393 * |
|
394 * @param aFullyComplete If ETrue (default), test record is completed with |
|
395 * status fully completed. Otherwise the test record is |
|
396 * considered partially completed. |
|
397 * |
|
398 * @return Symbian error code or KErrNone. KErrDiskFull is returned if there |
|
399 | is not enough space on c-drive. |
|
400 **/ |
|
401 IMPORT_C TInt TestCompleted( TBool aFullyComplete = ETrue ); |
|
402 |
|
403 /** |
|
404 * Indicates has this record been written into the DB file or not. |
|
405 * |
|
406 * @param aCompleted Has the test record been completed. |
|
407 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
408 * error codes. |
|
409 **/ |
|
410 IMPORT_C TInt IsTestCompleted( TBool& aCompleted ) const; |
|
411 |
|
412 /** |
|
413 * Returns information about the record. If the record is not finalized, |
|
414 * iFinishTimes contains unknown values. |
|
415 * |
|
416 * @param aInfo returns an overview of the test record. |
|
417 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
418 * error codes. |
|
419 **/ |
|
420 IMPORT_C TInt GetRecordInfo ( TDiagResultsDatabaseTestRecordInfo& aInfo ) const; |
|
421 |
|
422 /** |
|
423 * Get list of test UIDs inside the test record. |
|
424 * |
|
425 * @param aTestUidArray An array of test uids. |
|
426 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
427 * error codes. |
|
428 **/ |
|
429 IMPORT_C TInt GetTestUids ( CArrayFixFlat<TUid>& aTestUidArray ) const; |
|
430 |
|
431 /** |
|
432 * Logs results of a test into the database including more information |
|
433 * that there might be. See class CDiagResultsDatabaseItem. Result Item |
|
434 * is written into the file immediately after TRequestStatus completes. |
|
435 * |
|
436 * @param aResultItem This structure is stored into the database. |
|
437 * Client is responsible for creating the object. Also client is responsible |
|
438 * for setting item's values. |
|
439 * |
|
440 * @param aStatus Asynchronous status. Completes when process is finished. |
|
441 * |
|
442 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
443 * error codes. Returns KErrAlreadyExists if record is already completed. |
|
444 * KErrDiskFull is returned if there is not enough space on c-drive. |
|
445 * If KErrDiskFull is received, the test result is not logged. |
|
446 * |
|
447 **/ |
|
448 IMPORT_C TInt LogTestResult ( TRequestStatus& aStatus, |
|
449 const CDiagResultsDatabaseItem& aResultItem ); |
|
450 |
|
451 /** |
|
452 * Cancel LogTestResult. Server continues to write result item into the DB. |
|
453 * Cancelling only completes client's request. |
|
454 **/ |
|
455 IMPORT_C void CancelLogTestResult() const; |
|
456 |
|
457 /** |
|
458 * Get single test result from this test record identified by an uid. |
|
459 * |
|
460 * @param aPluginUid Unique identifier of the plug-in whose results are needed. |
|
461 * @param aResultItem Contains test results. |
|
462 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
463 * error codes.KErrNotFound is returned if the plug-in is not found |
|
464 * from the record. |
|
465 **/ |
|
466 IMPORT_C TInt GetTestResult ( TUid aPluginUid, |
|
467 CDiagResultsDatabaseItem*& aResultItem ) const; |
|
468 |
|
469 /** |
|
470 * Get all test results inside the test record. Client is responsible for |
|
471 * reseting/destroying the array. |
|
472 * |
|
473 * @param aResultsArray Returns test results for this record. |
|
474 * |
|
475 * @return KErrNone, if successful, otherwise one of the other system-wide |
|
476 * error codes. |
|
477 */ |
|
478 IMPORT_C TInt GetTestResults ( RPointerArray<CDiagResultsDatabaseItem>& aResultsArray ) const; |
|
479 |
|
480 private: |
|
481 |
|
482 /** |
|
483 * Leaving version of the functions and helper functions. |
|
484 **/ |
|
485 void DoConnectL ( RDiagResultsDatabase& aSession, |
|
486 TUid aRecordId, |
|
487 TBool aReadOnly ); |
|
488 |
|
489 void DoCreateNewRecordL ( RDiagResultsDatabase& aSession, TUid& aRecordId, |
|
490 CDiagResultsDbRecordEngineParam& aEngineParam ); |
|
491 |
|
492 void DoGetTestUidsL ( CArrayFixFlat<TUid>& aTestUidArray ) const; |
|
493 |
|
494 void DoLogTestResultL ( TRequestStatus& aStatus, |
|
495 const CDiagResultsDatabaseItem& aResultItem ); |
|
496 |
|
497 void DoGetTestResultsL ( RPointerArray<CDiagResultsDatabaseItem>& aResultsArray ) const; |
|
498 |
|
499 void DoGetTestResultL ( TUid aPluginUid, CDiagResultsDatabaseItem*& aResultItem ) const; |
|
500 |
|
501 void WriteDatabaseItemIntoBufferL( const CDiagResultsDatabaseItem& aResultItem ); |
|
502 |
|
503 void WriteEngineParamIntoBufferL( CDiagResultsDbRecordEngineParam& aEngineParam ); |
|
504 |
|
505 void DoGetEngineParamL( CDiagResultsDbRecordEngineParam*& aEngineParam ) const; |
|
506 |
|
507 private: |
|
508 |
|
509 // Dynamic flat buffer. |
|
510 CBufFlat* iBuffer; |
|
511 |
|
512 // Is the connection already open. |
|
513 TBool iOpen; |
|
514 |
|
515 //Buffer pointer |
|
516 TPtr8 iPtr; |
|
517 }; |
|
518 |
|
519 #endif // DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H |
|
520 |
|