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