diff -r 13d7c31c74e0 -r b183ec05bd8c remotemgmt_plat/diagnostics_results_api/inc/diagresultsdatabase.h --- a/remotemgmt_plat/diagnostics_results_api/inc/diagresultsdatabase.h Thu Aug 19 10:44:50 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,520 +0,0 @@ -/* -* Copyright (c) 2007-2007 Nokia Corporation and/or its subsidiary(-ies). -* All rights reserved. -* This component and the accompanying materials are made available -* under the terms of "Eclipse Public License v1.0" -* which accompanies this distribution, and is available -* at the URL "http://www.eclipse.org/legal/epl-v10.html". -* -* Initial Contributors: -* Nokia Corporation - initial contribution. -* -* Contributors: -* -* Description: Results database client interfaces. -* Provides results database session and subsession. -* libraries : DiagResultsDatabase.lib DiagResultsDatabase.dll -* -*/ - - -#ifndef DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H -#define DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H - -#include - -class CDiagResultsDatabaseItem; -class TDiagResultsDatabaseTestRecordInfo; -class CDiagResultsDbRecordEngineParam; - -/** -* Diagnostics Results Database. Stores test results and more information. -* Provides methods to retrieve and fetch new data. -* Requires ReadDeviceData and WriteDeviceData capabilities even if the -* session does not write anything. -* -* Results database is a permanent file store based solution. -* Database files are stored under WINSCW\C\private\10282cd9 in emulator -* environment. -* -* It is recommended to have only one open RDiagResultsDatabase per thread. -* There should be only one writer and multiple readers at the same time -* accessing the same database file. It is possible that there are multiple -* DB files for example when there are two diagnostics applications in the -* system. -* -* @since S60 v5.0 -**/ -class RDiagResultsDatabase : public RSessionBase - { -public: - - /** - * Constructor - **/ - IMPORT_C RDiagResultsDatabase(); - - /** - * Destructor - **/ - IMPORT_C ~RDiagResultsDatabase(); - - /** - * Connect to the results database to a DB file. This must be called before - * trying to use this class, otherwise KERN-EXEC 0 will crash your app. - * Only one RDiagResultsDatabase connection is recommended per application, - * because server sessions consume significant amount of system resources. - * Share the session inside your thread! Subsessions are much more lighter. - * - * Calling connect creates the DB file inside server's private directory. - * If for some reason database is corrupted, the DB file should be deleted - * manually. - * - * @param aAppUid Unique identifier of the application. Each application has - * its own store. Applications can access to another - * applications's database if they know their UID. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. If calling process does not have access rights, - * KErrPermissionDenied is returned. ReadDeviceData+WriteDeviceData are - * required. KErrDiskFull is returned if there is not enough space - * on c-drive. - **/ - IMPORT_C TInt Connect( TUid aAppUid ); - - /** - * Close the session with the server. Handle is not valid anymore. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt Close(); - - /** - * Returns the version number of the server. - * - * @return The version number. - **/ - IMPORT_C TVersion Version() const; - - /** - * Get the current number of test records in the database. - * - * @param aCount the number of records. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetRecordCount ( TUint& aCount ) const; - - /** - * Returns the maximum number of records for each application. The number - * is defined in the central repository and it is static for all applications. - * It is guarenteed that the DB file contains only the maxsize records and - * not more. Old test records are deleted when new test records are - * completed. - * - * @param aMaxSize The maximum number of test records. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C static TInt GetDatabaseMaximumSize( TInt& aMaxSize ); - - /** - * Returns an array of record Ids. The oldest records are at the beginning - * of the array. Test record are sorted based on creation time. - * - * @param aSortedRecordUidArray An array of UIds. The array is sorted - * based on time. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetRecordUids ( CArrayFixFlat& aSortedRecordUidArray ) const; - - /** - * Returns id to last test record. The last record cannot be - * still open for writing! Test record are sorted based on creation time. - * - * @param aRecordUid Unique identifier of the record. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. Returns KErrNotFound if there are no records. - **/ - IMPORT_C TInt GetLastRecord ( TUid& aRecordUid ) const; - - /** - * Returns id to last suspended or incompleted test record. - * The last record cannot be still open for writing! Returns KErrNotFound - * if there are no suspended or incomplete test records. - * - * @param aRecordUid Unique identifier of the record. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. Returns KErrNotFound if there are no suspended test records. - **/ - IMPORT_C TInt GetLastNotCompletedRecord ( TUid& aRecordUid ) const; - - /** - * Returns an overview from all records. - * - * @param aInfoArray returns an array of record infos. - * @see TDiagResultsDatabaseTestRecordInfo. - **/ - IMPORT_C TInt GetAllRecordInfos ( - CArrayFixFlat& aInfoArray ); - - /** - * Initiate retrieving of last results. After request is completed, - * data can be fetched using GetLastResults method. - * - * @param aUidArray An array of uid used to identify plug-ins. - * @param aStatus Completion status. - **/ - IMPORT_C void InitiateGetLastResults ( const CArrayFixFlat& aUidArray, - TRequestStatus& aStatus ); - - /** - * Cancel InitiateGetLastResults. - **/ - IMPORT_C void CancelInitiateGetLastResults () const; - - /** - * Get list of last results. Last result means that the plug-in has passed / failed - * test result. - * - * GetLastResults deletes data after this function - * is called, so InitiateGetLastResults must be called if data is needed - * again. Client is responsible for deleting the returned array. Contains - * null values if the searched uid was not found. There should be the same - * number of cells in UidArray and in the results array. - * - * @param aResults Returned results array. Client is responsible for - * deleting the array. - * - * @return KErrNotReady if this is called before InitiateGetLastResults. - */ - IMPORT_C TInt GetLastResults ( RPointerArray& aResults ) const; - - /** - * Get last (the newest) test result of a test plug-in. The algorithm searches for a - * test result that is either passed or failed. This is also asynchronous operation, - * because all records have to be browsed in worst case scenario (that is, when - * the plug-in uid is not found). Call GetLastResult when test result is needed. - * - * - * @param aTestPluginUid UID of a plug-in. - * @param aStatus Asynchronous request status. - * - */ - IMPORT_C void InitiateGetLastResult ( TUid aTestPluginUid, - TRequestStatus& aStatus ); - - - /** - * Get last result of a test plug-in. - * - * @param aItem Test result or NULL if not found. - * @retrun KErrNotReady if this is called before InitiateGetLastResult. - **/ - IMPORT_C TInt GetLastResult ( CDiagResultsDatabaseItem*& aItem ); - -private: - - /** - * Leaving version of the service functions. Look above for explanations. - **/ - void DoConnectL (TUid aAppUid); - - void DoGetRecordUidsL( CArrayFixFlat& aSortedRecordUidArray ) const; - - /* - * @see GetDatabaseMaximumSize() - */ - static void DoGetDatabaseMaximumSizeL( TInt& aMaxSize ); - - void DoGetAllRecordInfosL ( CArrayFixFlat& aInfoArray); - - void DoGetLastResultsL ( RPointerArray& aResults ) const; - - void WriteArrayIntoBufferL( const CArrayFixFlat& aUidArray ); - - void DoGetLastResultL ( CDiagResultsDatabaseItem*& aItem ); - -private: - - // Flat dynamic buffer. - CBufFlat* iBuffer; - - // is the connection already open. - TBool iOpen; - - //Buffer pointer - TPtr8 iPtr; - }; - -/** -* Sub-session to Diagnostics Results Database. This API is used to -* handle a Test record. A test record is a collection of test results. -* -* Test record is always written into the file, when updates are necessary. -* -* -* @since S60 v5.0 -**/ -class RDiagResultsDatabaseRecord : public RSubSessionBase - { -public: - - /** - * Test record status. - **/ - enum TRecordStatus - { - EOpen, // Currently open for writing. - ESuspended, // ::Suspend() is called. - ECrashed, // It was open previously, and it was not - // closed properly. - EPartiallyCompleted, // Record is completed (not resumable), but not - // all tests were completed. - ECompleted // Record is completed (not resumable), and all - // tests were completed. - }; - - /** - * Constructor - **/ - IMPORT_C RDiagResultsDatabaseRecord(); - - /** - * Destructor - **/ - IMPORT_C ~RDiagResultsDatabaseRecord(); - - /** - * Connects to a test record. There must be at least one created record. - * If the specified record is not found, KErrNotFound is returned. - * Opened test record can be modified if the test record has not been - * completed (= TestCompleted called). - * - * @param aSession open database session. - * @param aRecordId specifies the record where we want to connect. - * @param aReadOnly Indicates is the test record opened in read-only mode. - * If read-only = EFalse, the test record can overwrite - * test records that are not completed already. If - * the test record is completed it can be opened only - * in read-mode. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. Returns KErrAlreadyExists if subsession is connected. - **/ - IMPORT_C TInt Connect( RDiagResultsDatabase& aSession, - TUid aRecordId, - TBool aReadOnly ); - - /** - * Creates a new record and returns the uid of that record. - * Writes empty test record into the file. Create new record opens the record - * always in Write mode. - * - * @param aSession open database session. - * @param aRecordId a new unique identifier is returned that is used to - * identify particular test record. Client can use the record ID to access - * the same record again. - * @param aEngineParam Engine parameters. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. Returns KErrAlreadyExists if subsession is connected. - * KErrDiskFull is returned if there is not enough space on c-drive. - **/ - IMPORT_C TInt CreateNewRecord( RDiagResultsDatabase& aSession, - TUid& aRecordId, - CDiagResultsDbRecordEngineParam& aEngineParam ); - - /** - * Retrieve parameters of the diagnostics engine. These are needed in - * Suspend/Resume functionality. - * - * @param aEngineParam Engine parameters. Ownership is transferred. - * Client is responsible for deleting the object. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetEngineParam( CDiagResultsDbRecordEngineParam*& aEngineParam ) const; - - - /** - * Get record status. - * - * @param aRecordStatus The status of the record. - * @see TRecordStatus in the beginning of the class declaration. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetStatus( TRecordStatus& aRecordStatus ) const; - - /** - * Close subsession. Does not write test record into the file. - * - * @return Symbian error code or KErrNone. - **/ - IMPORT_C void Close(); - - /** - * Suspend test record. Same as complete, but the test record can be modified - * on next connect.Writes test suspend time into test record info. - * - * @return Symbian error code or KErrNone. - **/ - IMPORT_C TInt Suspend(); - - /** - * Indicates has this test record been suspended. - * @param aSuspended Returns has this test record been suspended(ETrue), - * otherwise EFalse. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt IsSuspended( TBool& aSuspended ) const; - - /** - * Returns the record UID of this subsession. - * - * @param aRecordUid Record ID of the subsession. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetTestRecordId( TUid& aRecordUid ) const; - - /** - * Write test completion time/date to the record and prevent further - * writing. Handle is still valid. However, it cannot be used for adding - * any more test results. During completion database file is cleaned up from - * old test records (limited by GetDatabaseMaximumSize method). - * - * Test completion is synchronous operation because only record handle must be - * updated (fixed size stream). - * - * @param aFullyComplete If ETrue (default), test record is completed with - * status fully completed. Otherwise the test record is - * considered partially completed. - * - * @return Symbian error code or KErrNone. KErrDiskFull is returned if there - | is not enough space on c-drive. - **/ - IMPORT_C TInt TestCompleted( TBool aFullyComplete = ETrue ); - - /** - * Indicates has this record been written into the DB file or not. - * - * @param aCompleted Has the test record been completed. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt IsTestCompleted( TBool& aCompleted ) const; - - /** - * Returns information about the record. If the record is not finalized, - * iFinishTimes contains unknown values. - * - * @param aInfo returns an overview of the test record. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetRecordInfo ( TDiagResultsDatabaseTestRecordInfo& aInfo ) const; - - /** - * Get list of test UIDs inside the test record. - * - * @param aTestUidArray An array of test uids. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - **/ - IMPORT_C TInt GetTestUids ( CArrayFixFlat& aTestUidArray ) const; - - /** - * Logs results of a test into the database including more information - * that there might be. See class CDiagResultsDatabaseItem. Result Item - * is written into the file immediately after TRequestStatus completes. - * - * @param aResultItem This structure is stored into the database. - * Client is responsible for creating the object. Also client is responsible - * for setting item's values. - * - * @param aStatus Asynchronous status. Completes when process is finished. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. Returns KErrAlreadyExists if record is already completed. - * KErrDiskFull is returned if there is not enough space on c-drive. - * If KErrDiskFull is received, the test result is not logged. - * - **/ - IMPORT_C TInt LogTestResult ( TRequestStatus& aStatus, - const CDiagResultsDatabaseItem& aResultItem ); - - /** - * Cancel LogTestResult. Server continues to write result item into the DB. - * Cancelling only completes client's request. - **/ - IMPORT_C void CancelLogTestResult() const; - - /** - * Get single test result from this test record identified by an uid. - * - * @param aPluginUid Unique identifier of the plug-in whose results are needed. - * @param aResultItem Contains test results. - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes.KErrNotFound is returned if the plug-in is not found - * from the record. - **/ - IMPORT_C TInt GetTestResult ( TUid aPluginUid, - CDiagResultsDatabaseItem*& aResultItem ) const; - - /** - * Get all test results inside the test record. Client is responsible for - * reseting/destroying the array. - * - * @param aResultsArray Returns test results for this record. - * - * @return KErrNone, if successful, otherwise one of the other system-wide - * error codes. - */ - IMPORT_C TInt GetTestResults ( RPointerArray& aResultsArray ) const; - -private: - - /** - * Leaving version of the functions and helper functions. - **/ - void DoConnectL ( RDiagResultsDatabase& aSession, - TUid aRecordId, - TBool aReadOnly ); - - void DoCreateNewRecordL ( RDiagResultsDatabase& aSession, TUid& aRecordId, - CDiagResultsDbRecordEngineParam& aEngineParam ); - - void DoGetTestUidsL ( CArrayFixFlat& aTestUidArray ) const; - - void DoLogTestResultL ( TRequestStatus& aStatus, - const CDiagResultsDatabaseItem& aResultItem ); - - void DoGetTestResultsL ( RPointerArray& aResultsArray ) const; - - void DoGetTestResultL ( TUid aPluginUid, CDiagResultsDatabaseItem*& aResultItem ) const; - - void WriteDatabaseItemIntoBufferL( const CDiagResultsDatabaseItem& aResultItem ); - - void WriteEngineParamIntoBufferL( CDiagResultsDbRecordEngineParam& aEngineParam ); - - void DoGetEngineParamL( CDiagResultsDbRecordEngineParam*& aEngineParam ) const; - -private: - - // Dynamic flat buffer. - CBufFlat* iBuffer; - - // Is the connection already open. - TBool iOpen; - - //Buffer pointer - TPtr8 iPtr; - }; - -#endif // DIAGNOSTICS_RESULTS_DATABASE_CLIENT_H -