/*
* 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 <e32base.h>
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<TUid>& 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<TDiagResultsDatabaseTestRecordInfo>& 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<TUid>& 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<CDiagResultsDatabaseItem>& 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<TUid>& aSortedRecordUidArray ) const;
/*
* @see GetDatabaseMaximumSize()
*/
static void DoGetDatabaseMaximumSizeL( TInt& aMaxSize );
void DoGetAllRecordInfosL ( CArrayFixFlat<TDiagResultsDatabaseTestRecordInfo>& aInfoArray);
void DoGetLastResultsL ( RPointerArray<CDiagResultsDatabaseItem>& aResults ) const;
void WriteArrayIntoBufferL( const CArrayFixFlat<TUid>& 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<TUid>& 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<CDiagResultsDatabaseItem>& 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<TUid>& aTestUidArray ) const;
void DoLogTestResultL ( TRequestStatus& aStatus,
const CDiagResultsDatabaseItem& aResultItem );
void DoGetTestResultsL ( RPointerArray<CDiagResultsDatabaseItem>& 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