/*
* Copyright (c) 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: This is the declaration of the execution results class used
* by the Device Diagnostics Application to present a common interface
* for results information to the application.
*
*/
#ifndef DEVDIAGEXECUTIONRESULTS_H
#define DEVDIAGEXECUTIONRESULTS_H
// System Include Files
#include <e32base.h> // CBase
#include <e32cmn.h> // RPointerArray, TUid
// Forward Declarations
class MDiagEngineCommon;
class MDiagPlugin;
class MPDResultsObserver;
class CDiagResultsDatabaseItem;
class CDiagPluginPool;
class RDiagResultsDatabase;
/**
* Device Diagnostics Execution Results Class.
* This class presents a common interface to the application for results from
* both live test runs as well as from the results database.
*
* @lib diagresultsdatabase.lib
* @lib diagframework.lib
*/
class CDevDiagExecResults : public CBase
{
public: // Nested Classes
/**
* Device Diagnostics Execution Results Information Class.
* This class provides a common interface to individual results
* information from either live execution or the results database.
*/
class CResult : public CBase
{
public: // New Functions
/**
* Two-phased constructor.
*
* @param aPlugin The plugin that this result corresponds to.
* @return A pointer to the newly-created instance of CResult.
*/
static CResult* NewL( const MDiagPlugin& aPlugin );
/**
* Two-phased constructor.
*
* @param aPlugin The plugin that this result corresponds to.
* @return A pointer to the newly-created instance of CResult.
*/
static CResult* NewLC( const MDiagPlugin& aPlugin );
/**
* Destructor.
*/
virtual ~CResult();
/**
* Returns the pointer to the test result. This may be NULL if the
* item is a suite or has not been run yet. The client must not
* delete this pointer.
*
* @return A pointer to the test result for this item, or NULL.
*/
const CDiagResultsDatabaseItem* Result() const;
/**
* Returns a reference to the plugin that corresponds to this item.
*
* @return A reference to the plugin that corresponds to this item.
*/
const MDiagPlugin& Plugin() const;
/**
* Returns the execution status (error value) for this plugin. This
* will only contain meaningful data for live test executions.
*
* @return The execution status (error value) for this plugin
*/
TInt ExecStatus() const;
/**
* Returns the current execution step for this plugin. This will only
* contain meaningful data for live test executions.
*
* @return The current execution step for this plugin.
*/
TUint CurrentStep() const;
/**
* Returns the total number of execution steps for this plugin.
*
* @return The total number of execution steps for this plugin.
*/
TUint TotalSteps() const;
/**
* Sets the result information for this plugin. Ownership of the
* result is transferred. If the result was previously set, it will
* be deleted and replaced with the new data.
*
* @param aResult The test result.
* @param aError The execution status error value.
*/
void SetResult( CDiagResultsDatabaseItem* aResult, TInt aError );
/**
* Sets the test progress information.
*
* @param aCurrentStep The current execution step for this plugin.
* @param aCurrentStep The total number of execution steps for this
* plugin.
*/
void SetProgress( TUint aCurrentStep, TUint aTotalSteps );
private: // New Functions
/**
* Default constructor.
*
* @param aPlugin The plugin that this result corresponds to.
*/
CResult( const MDiagPlugin& aPlugin );
/**
* Two-phased constructor.
*/
void ConstructL();
private: // Data
/**
* The test results information.
* Own.
*/
CDiagResultsDatabaseItem* iResult;
/**
* A reference to the plugin that this result corresponds to.
*/
const MDiagPlugin& iPlugin;
/**
* The test execution status (error value).
*/
TInt iExecStatus;
/**
* The current step in the execution of this plugin.
*/
TUint iCurrentStep;
/**
* The total number of steps in the execution of this plugin.
*/
TUint iTotalSteps;
};
public: // New Functions
/**
* Two-phased constructor. This creates an execution results object by
* loading test results from the Results Database (logged results).
*
* @param aRecordId The unique record identifier from the results database
* for this set of results.
* @param aPluginPool A reference to the plugin pool, which is used for
* getting plugin information.
* @param aDbSession A reference to an open session with the results
* database server.
* @return A pointer to the newly-created instance of CDevDiagExecResults.
*/
static CDevDiagExecResults* NewL( TUid aRecordId,
CDiagPluginPool& aPluginPool,
RDiagResultsDatabase& aDbSession );
/**
* Two-phased constructor. This creates an execution results object by
* getting test results from live execution. The results objects are
* created from the diagnostics engine's execution plan, and updated as
* tests complete.
*
* @param aRecordId The unique record identifier from the results database
* for this set of results.
* @param aPluginPool A reference to the plugin pool, which is used for
* getting plugin information.
* @param aDbSession A reference to an open session with the results
* database server.
* @param aExecutedUid The uid of the plugin that was executed to produce
* these test results.
* @param aDiagEngine A pointer to the diagnostics engine, which is only
* used to get the execution plan during live test
* runs.
* @return A pointer to the newly-created instance of CDevDiagExecResults.
*/
static CDevDiagExecResults* NewL( TUid aRecordId,
CDiagPluginPool& aPluginPool,
RDiagResultsDatabase& aDbSession,
TUid aExecutedUid,
MDiagEngineCommon* aDiagEngine );
/**
* Destructor.
*/
virtual ~CDevDiagExecResults();
/**
* This function is used to set the result for the current execution plan
* index. It is only valid for live test executions. Ownership of the
* result is transferred. If called multiple times for the same plugin,
* each suqsequent call deletes and overwrites the previous result data.
*
* @param aResult The test result.
* @param aStatus The execution status error value.
*/
void AddEntryL( CDiagResultsDatabaseItem* aResult, TInt aStatus );
/**
* Sets the test progress information for the current execution plan
* index.
*
* @param aCurrentStep The current execution step for this plugin.
* @param aCurrentStep The total number of execution steps for this
* plugin.
*/
void SetProgressL( TUint aCurrentStep, TUint aTotalSteps );
/**
* Retrieves the CResult reference at the specified index.
*
* @param aIndex The index of the result to retrieve.
* @return A reference to the CResult object at the index.
*/
CResult& operator[] ( TInt aIndex );
const CResult& operator[] ( TInt aIndex ) const;
/**
* Retrieves the CResult reference at the current index. For live
* execution runs, this is determined from the test execution plan. For
* logged results, this is always the last item.
*
* @return A reference to the CResult object.
*/
CResult& CurrentItemL();
const CResult& CurrentItemL() const;
/**
* Returns the number of result items.
*
* @return The number of result items.
*/
TInt Count() const;
/**
* Returns the index of the current result item. For live execution runs,
* this is determined from the test execution plan. For logged results,
* this is always the last item.
*
* @return The index of the current execution item.
*/
TUint CurrentIndexL() const;
/**
* Checks if the diagnostics engine has finished the last test.
*
* @return ETrue if the last test has finished and the diagnostics engine
* is cleaning up.
*/
TBool LastTestFinishedL() const;
/**
* Returns whether or not the item specified by the argument is (or was)
* executed as a dependency test.
*
* @param aIndex The index of the item to check for dependency execution.
* @return ETrue if the item is (or was) a dependency, EFalse otherwise.
*/
TBool IsDependencyL( TInt aIndex ) const;
/**
* Returns whether or not the results are from a completed test record.
*
* @return ETrue if the results are from a completed test record, EFalse
* otherwise.
*/
TBool IsRecordCompleted() const;
/**
* Finalizes live execution results so that they may not be updated.
*
* @param aTestingComplete Indicates if all tests in the record were
* executed.
*/
void Finalize( TBool aTestingComplete );
/**
* Returns the total number of steps for all items in the execution
* results.
*
* @return The total number of steps for all items in the execution
* results.
*/
TInt TotalExecutionSteps() const;
/**
* Returns the current execution step based on all items in the execution
* results.
*
* @return The current execution step based on all items in the execution
* results.
*/
TInt CurrentExecutionStep() const;
/**
* Returns a reference to the plugin that the engine was asked to execute.
* The engine must be executing plugins for this to be valid.
*
* @return A reference to the plugin that the engine was asked to execute.
*/
const MDiagPlugin& ExecutedPluginL() const;
/**
* Returns whether or not the execution is for a single plugin.
*
* @return ETrue if the execution is for a single plugin.
*/
TBool SinglePluginExecutionL() const;
/**
* Returns the number of failed tests in this set of results.
*
* @return The number of failed tests in this set of results.
*/
TInt FailedResultsCount() const;
/**
* Returns the number of passed tests in this set of results.
*
* @return The number of passed tests in this set of results.
*/
TInt PassedResultsCount() const;
/**
* Returns whether or not the execution plan's resume index has been
* reached. This value indicates if the diagnostics engine is still
* updating the application with cached test results.
*
* @return ETrue if the execution plan's resume index has been reached.
*/
TBool ResumeIndexReachedL() const;
/**
* Returns the UID of the record associated with this set of results.
*
* @return The UID of the record associated with this set of results.
*/
const TUid& RecordId() const;
// ADO & Platformization Changes
const CDiagResultsDatabaseItem* GetSinglepluginExecutionResult() const;
private: // Data Types
/** Enum to indicate what type of results data this object contains. */
enum TResultsType
{
ETypeExecution,
ETypeLog
};
private: // New Functions
/**
* Default constructor.
*
* @param aRecordId The unique record identifier from the results database
* for this set of results.
* @param aPluginPool A reference to the plugin pool, which is used for
* getting plugin information.
* @param aExecutedUid The uid of the plugin that was executed to produce
* these test results. This is ignored for logged
* test results.
* @param aDiagEngine A pointer to the diagnostics engine, which is only
* used to get the execution plan during live test
* runs. This must be NULL for logged test results.
*/
CDevDiagExecResults( TUid aRecordId,
CDiagPluginPool& aPluginPool,
RDiagResultsDatabase& aDbSession,
TUid aExecutedUid = KNullUid,
MDiagEngineCommon* aDiagEngine = NULL );
/**
* Two-phased constructor.
*/
void ConstructL();
private: // Data
/**
* The type of results data contained by this object.
*/
TResultsType iType;
/**
* The array of results data.
*/
RPointerArray< CResult > iResults;
/**
* The results database UID that corresponds to this test record.
*/
TUid iRecordId;
/**
* The plugin pool, used to get information about test plugins.
*/
CDiagPluginPool& iPluginPool;
/**
* A reference to an open database session. This object does not close
* the database session; it may only use it and create subsessions.
*/
RDiagResultsDatabase& iDbSession;
/**
* A pointer to the diagnostics engine, used only to get the execution
* plan for live test exections.
* Not own.
*/
MDiagEngineCommon* iDiagEngine;
/**
* The total number of test steps in the entire execution.
*/
TInt iTotalSteps;
/**
* The total number of test steps in the entire execution.
*/
TInt iCompletedSteps;
/**
* The test step that the currently-executing plugin is on. This is not
* combined with "iCompletedSteps" because plugins may be suspended and
* restarted before they finally complete.
*/
TInt iCurrentPluginStep;
/**
* The UID of the plugin executed to produce these results. This is
* obtained from the test record during construction.
*/
TUid iExecutedPlugin;
/**
* The status of the record that corresponds to these test results. A
* record is fully completed only when all tests in it have been executed,
* or the user decides not to resume it after suspending it. This data is
* obtained from the Finalize() function for live executions and from the
* database for logged results.
*/
TBool iCompleted;
/**
* The number of failed tests in these test results. This data is
* obtained from the AddEntryL() function for live executions and from the
* database for logged results.
*/
TInt iFailedCount;
/**
* The number of passed tests in these test results. This data is
* obtained from the AddEntryL() function for live executions and from the
* database for logged results.
*/
TInt iPassedCount;
/**
* The index value of the last test plugin in the results array. This is
* used to check if the last test has finished.
*/
TInt iLastTestIndex;
};
#endif // PDEXECUTIONRESULTS_H