/*

* 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:  Diagnostics Test Plug-in  Base class

*

*/

#ifndef DIAGTESTPLUGINBASE_H

#define DIAGTESTPLUGINBASE_H

// INCLUDES

#include <DiagTestPlugin.h>     // MDiagTestPlugin

#include <ConeResLoader.h>      // RConeResourceLoader

#include <DiagResultsDatabaseItem.h>    // CDiagResultsDatabaseItem::TResult

#include <DiagEngineWatchdogTypes.h>    // TDiagEngineWatchdogTypes

// FORWARD DECLARATIONS

class CDiagResultsDbItemBuilder;

class TDiagTestPluginBasePrivateData;

class CDiagPluginConstructionParam;

class CAknDialog;

/**

*  Diagnostics Framework Test Plugin  Base Class

*

*  This class provides further simplification of test execution.

*  It handles execution parameter and reporting results to engine

*

*  @since S60 v5.0

*/

class CDiagTestPluginBase : public CActive,

                            public MDiagTestPlugin

    {

public: // C++ Destructor

    /**

    * Destructor.

    */

    IMPORT_C virtual ~CDiagTestPluginBase();

protected: // new API for derived class

    /**

    * C++ constructor

    * 

    *   Note that BaseConstructL() must be called to complete object construction.

    * @param aConstructionParam Construction parameters.

    */

    IMPORT_C CDiagTestPluginBase( CDiagPluginConstructionParam* aConstructionParam );

    /**

    * 2nd phase Base class constructor

    * This initializes CDiagTestPluginBase class. Derived class must call this

    * method in its ConstructL() method.

    *  

    * @param aResourceFileName Drive and name of resource file in format

    *                          <path>:<rsc_file_name>

    */

    IMPORT_C void BaseConstructL( const TDesC& aResourceFileName );

    /**

    * Verify that all dependencies are satisfied. Also returns a list of

    * failed dependencies.

    *

    * @param aEngine. Reference to engine, which provides references to

    *   database session and plug-in pool.

    * @param aFailedUids. If ETrue is returned, the parameter is NULL.

    *           if EFalse is returned, the parameter points to an array that

    *           can be used to query UIDs of failed dependencies. Client is

    *           responsible of closing the array.

    * @return ETrue if all dependencies are executed successfully.

    *         EFalse if one or more dependencies are failed.

    */

    IMPORT_C virtual TBool AreDependenciesSatisfiedL( MDiagEngineCommon& aEngine,

                                            RArray<TUid>*& aFailedUids ) const;

    /**

    * Check result of dependencies. This will check each dependency and

    * determine the best overall result of all the dependencies.

    *

    * @param aEngine. Reference to engine, which provides references to

    *   database session and plug-in pool.

    * @param aFailedUids. If ESuccess is returned, the parameter is NULL.

    *           Otherwise the parameter points to an array that

    *           can be used to query UIDs of failed dependencies. Client is

    *           responsible of closing the array.

    * @return Result of the dependency check. If multiple depencies or suites

    *   are included, it will return the most appropreate result.

    */

    IMPORT_C virtual CDiagResultsDatabaseItem::TResult VerifyDependenciesL( 

        MDiagEngineCommon& aEngine,

        RArray<TUid>*& aFailedUids ) const;

    /**

    * Returns execution parameter. 

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @return Execution parameter.

    */

    IMPORT_C TDiagTestExecParam& ExecutionParam();

    /**

    * Check if current test session has dependency check skip flag set.

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    * 

    * @return ETrue if dependency check is disabled for this execution sesison.

    *   EFalse if dependency check is enabled.

    */

    IMPORT_C TBool IsDependencyCheckSkipped() const;

    /**

    * Check if current test is being executed to satisfy dependency or

    *   if it is being executed explicitly.

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @return ETrue - If it is to satisfy dependency.

    *   EFalse - If it is being executed explicitly.

    */

    IMPORT_C TBool IsDependencyExecution() const;

    /**

    * Get custom parameter passed to from the engine

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    * 

    * @return Custom parameter. Ownership is not transferred.

    */

    IMPORT_C TAny* CustomParam() const;

    /**

    * Get currently result db item builder.

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @return Reference to current CDiagResultsDbItemBuilder.

    */

    IMPORT_C CDiagResultsDbItemBuilder& ResultsDbItemBuilder();

    /**

    * Report test progress test observer.

    *   This function will call engine's TestProgressL method with watchdog

    *   type value that is based on plug-in RunMode.

    *

    *   If EAutomatic plug-in, it will use EDiagEngineWatchdogTypeNonInteractive.

    *   If EInteractiveView or EInteractiveDialog, EDiagEngineWatchdogTypeInteractive. 

    *

    *   When watchdog is timed out, it will stop test with test result

    *   CDiagResultsDatabaseItem::EWatchdogCancel.

    *

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @param aCurrentStep - Current execution step

    */

    IMPORT_C void ReportTestProgressL( TUint aCurrentStep );

    /**

    * Reset watchdog value and watchdog failure result type.

    *   When watchdog is timed out, it will use the given result type as

    *   value to report back to engine.  

    *

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @param aWatchdogType - Type of watchdog requested.

    * @param aResultType - Result to report when wachdog is failed.

    */

    IMPORT_C void ResetWatchdog( TDiagEngineWatchdogTypes aWatchdogType,

                                 CDiagResultsDatabaseItem::TResult aResultType );

    /**

    * Reset watchdog value and watchdog failure result type.

    *   For most plug-ins, the other ResetWatchdog should be better. 

    *   This should be used only if specific time must be given for the step.

    *

    *   When watchdog is timed out, it will use the given result type as

    *   value to report back to engine.  

    *

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @param aTimeToCompletion - Time needed to complete current operation.

    *   Unit is in microseconds.

    * @param aResultType - Result to report when wachdog is failed.

    */

    IMPORT_C void ResetWatchdog( 

        TInt aTimeToCompletion,

        CDiagResultsDatabaseItem::TResult aResultType );

    /**

    * Reset watchdog value and watchdog failure result type to default values.

    *   This will also reset watchdog on engine.

    *

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    */

    IMPORT_C void ResetWatchdogToDefault();

    /**

    * Report test result to test observer. 

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    *   This function will also call StopAndCleanupL(), which will call 

    *   DoStopAndCleanupL(). After CompleteTestL() is called, ExecutionParam() and

    *   other test state specific API will fail.

    *

    * @param aResult - Test result.

    */

    IMPORT_C void CompleteTestL( CDiagResultsDatabaseItem::TResult aResult );

    /**

    * Stop current execution and free any data associated with the test.

    *   This method will call DoStopAndCleanupL() function to allow

    *   derived class to clean up.

    *   

    *   It will also call DismissWaitingDialog() and CActive::Cancel().

    *

    *   If derived class overrides ExecutionStopL() function, this function

    *   must be called by derived version of ExecutionStopL() to allow

    *   proper clean up of CDiagTestPluginBase.

    *

    *   @see CDiagTestPluginBase::ExecutionStopL

    */

    IMPORT_C void StopAndCleanupL();

    /**

    * Run a dialog that waits for response. It is highly recommended that

    * all plug-ins use this function to display dialogs since it can detect

    * deletion of dialogs.

    *

    * The difference from normal dialog RunLD is that this function returns 

    * ETrue if dialog exited due to user response and 

    * EFalse if it was by other means, such as object deletion or

    * by DismissWaitingDialog() method. 

    * 

    *   !!!! NOTE THAT PLUG-IN MUST RETURN IMMEDIATELY WITHOUT ACCESSING  !!!!

    *   !!!! LOCAL VARIABLE OR LOCAL FUNCITONS WHEN THIS FUNCTION RETURNS !!!!

    *   !!!! EFalse VALUE BECAUSE "THIS" POINTER MAY BE FREED ALREADY.    !!!!

    * 

    * The normal dialog response is returned via aDialogResponse reference.

    * This function can only display one dialog at a time. Calling it again 

    * while it has not been returned will cause panic.

    *

    * @param aDialog - Pointer to dialog to run. If the dialog does not have

    *   EEikDialogFlagWait flag set, it will panic with EDiagPluginBaseBadArgument

    * @param aDialogResponse - Response from the dialog.  

    *   For detailed values @see avkon.hrh "CBA constants". E.g. EAknSoftkeyYes

    *   The only exception is that if cancel is pressed, it will be 0.

    * @return ETrue if dialog is exiting due to user response.

    *   Efalse if dialog is dismissed withou user input. 

    *   If EFalse is returned, plug-in MUST NOT act on the response.

    *   Also, since plug-in may have been deleted,

    */

    IMPORT_C TBool RunWaitingDialogL( CAknDialog* aDialog, TInt& aDialogResponse );

    /**

    * Dismiss the waiting dialog. This will cause the RunDialogLD() function to return with

    * aIsUserResponse = Efalse. If nothing is being displayed, this function

    * does nothing.

    */

    IMPORT_C void DismissWaitingDialog();

    /**

    * CCoeEnv

    *   @return Reference to CCoeEnv.

    */

    IMPORT_C CCoeEnv& CoeEnv();

    /**

    * Check if current test is being executed as a single plugin or 

    * as a part of a suite

    *   Note that this function should be called only during test execution. 

    *   If called in other states, it will Panic with EDiagPluginBasePanicInvalidState

    *

    * @return ETrue - If run as a single plugin

    *   EFalse - If run as a part of a suite

    */

    IMPORT_C TBool SinglePluginExecution() const;

protected:  // to be implemented by derived classes

    /**

    * Execute test. This is called by CDiagTestPluginBase::RunTestL()

    *   Note that CDiagTestPluginBase takes ownership of all parameters

    *   given in RunTestL() function. If specific parameter is needed

    *   use the following set of functions:

    *

    *   Parameters are available via the following APIs.

    *       Observer:               ExecutionParam().Observer();

    *       Engine:                 ExecutionParam().Engine();

    *       Dependency Execution:   IsDependencyExecution();

    *       Skip Depdency:          IsDependencyCheckSkipped();

    *       Custom Parameter:       CustomParam();

    *

    *   Also, a new instance of CDiagResultsDbItemBuilder is created and

    *   accessible via:

    *

    *       Result Db Item Builder: ResultsDbItemBuilder();

    */

    virtual void DoRunTestL() = 0;

    /**

    * Stop current execution and free any data associated with the test.

    *   This is called by StopAndCleanupL

    */

    virtual void DoStopAndCleanupL() = 0;

    /**

    * This is called by CDiagTestPluginBase::ExecutionStopL() to allow 

    *   the derived class to provide additional behavior in ExecutionStopL().

    *   Default implementation does nothing. For more information about

    *   how this is called, @see CDiagTestPluginBase::ExecutionStopL()

    *

    * @param aReason - Reason why ExecutionStopL() is being called.

    * @param aTestResult - Test result to write to in database.

    *   This is IN/OUT parameter. By default, it contains default result based on

    *   aReason. Plug-in can provide different test result, assign new result

    *   to this variable.

    *

    */

    IMPORT_C virtual void DoExecutionStopL( MDiagTestPlugin::TStopReason aReason,

                                            CDiagResultsDatabaseItem::TResult& aTestResult );

protected:  // From CActive

    /**

    * RunError. Handle leaves from test. If test is currently running, 

    * CDiagTestPluginBase will handle the error by calling 

    * CompleteTestL( CDiagResultsDatabaseItem::EFailed ). If test was

    * not running, it will return the error back to active scheduler.

    * 

    * If this behavior is not desired, derived class should override this

    * method.

    * 

    * For parameters and return value, 

    * @see CActive::RunError

    */

    IMPORT_C virtual TInt RunError( TInt aError );

protected: // from MDiagTestPlugin

    /**

    * Handle execution stop.

    *   @see MDiagTestPlugin::ExecutionStopL()

    * 

    *   This method does the following:

    *       a) Call DoExecutionStopL()   

    *       b) Call StopAndCleanupL()  -> Calls DoStopAndCleanupL()

    *       c) Return either EWatchdogCancel or ECancelled depending on

    *           the stop reason. 

    *   

    *   Note: If derived class wants override this function, be sure to 

    *   call StopAndCleanupL() to allow proper clean up of 

    *   CDiagTestPluginBase class. StopAndCleanupL() will call

    *   DoStopAndCleanupL(). 

    *

    *   @see DoExecutionStopL()

    *   @see StopAndCleanupL() 

    */

    IMPORT_C virtual CDiagResultsDatabaseItem* ExecutionStopL( TStopReason aReason );

protected:    // from MDiagTestPlugin

    /**

    * Get the name of the service that the plug-in provides.

    *

    * @return The name of the service.

    */

    IMPORT_C virtual const TDesC& ServiceLogicalName() const;

    /**

    * Get logical dependencies. One plug-in can have multiple dependencies to 

    * other plug-ins.

    *

    * @param aArray An array of logical names.

    * @see ServiceLogicalNameL

    */

    IMPORT_C virtual void GetLogicalDependenciesL( CPtrCArray& aArray ) const;

    /**

    * Return the type of the plug-in. 

    *

    * @return The type.

    * @see TPluginType.

    */

    IMPORT_C virtual TPluginType Type() const;

    /**

    * Create an icon that represents the plug-in.

    *

    * @return An icon. 

    */

    IMPORT_C virtual CGulIcon* CreateIconL() const;

    /**

    * @see MDiagPlugin::IsSupported

    */

    IMPORT_C virtual TBool IsSupported() const;

    /**

    * Get the order number that this plug-in should appear in its parent list.

    *

    * @return TUint order number.

    */

    IMPORT_C virtual TUint Order() const;

    /**

    * Get UID of the parent.

    *

    * @return The parent UID.

    */

    IMPORT_C virtual TUid ParentUid() const;

    /**

    * @see MDiagPlugin::SetDTorIdKey()

    */

    IMPORT_C virtual void SetDtorIdKey( TUid aDtorIdKey );

    /**

    * Get title of the plugin. Default implementation in CDiagTestPluginBase 

    *   will leave with KErrNotSupported. If plug-in has a title, plug-ins 

    *   must override this method.

    * @see MDiagPlugin::GetTitleL() 

    */

    IMPORT_C virtual HBufC* GetTitleL() const;

    /**

    * Get description of the plugin. Default implementation in 

    *   CDiagTestPluginBase will leave with KErrNotSupported. If plug-in 

    *   has a description, plug-in must override this method.

    * @see MDiagPlugin::GetDescriptionL()

    */

    IMPORT_C virtual HBufC* GetDescriptionL() const;

    /**

    * Reserved for future use/plugin's custom functionality. 

    *

    * @param aUid   Unique identifier of the operation.

    * @param aParam Custom parameter. 

    * @return TAny pointer. Custom data.

    */

    IMPORT_C virtual TAny* CustomOperationL( TUid aUid, TAny* aParam );

    /**

    * Reserved for future use/plugin's custom functionality. 

    *

    * @param aUid   Unique identifier of the property

    * @param aParam Custom parameter.

    * @return TAny pointer. Custom data. 

    */

    IMPORT_C virtual TAny* GetCustomL( TUid aUid, TAny* aParam );

    /**

    * Initialization Step. This method is called before any plugin are executed.

    * This can be used to clean up any left over data from previous execution 

    * sessions. All plug-ins in execution plan will have a chance to clean 

    * up before any plug-ins are run.  This is a synchrouns method.

    *

    * @param aEngine - Reference to engine.

    * @param aSkipDependencyCheck - If ETrue, plug-in will be executed

    *   even if dependencies are not executed.

    * @param aCustomParams Custom parameters for plug-ins. 

    *   It can used to pass arbitrary data from application to the plug-ins.

    *   Owership is not transferred and plug-in must not delete

    *   this parameter.

    */

    IMPORT_C virtual void TestSessionBeginL( MDiagEngineCommon& aEngine,

                                             TBool aSkipDependencyCheck,

                                             TAny* aCustomParams );

    /**

    * Cleanup Step. This method is called after all plug-ins in the 

    * execution plan is completed to clean up any left over data from 

    * current sesison. This can be used to clean up any data that

    * provides dependent service created for its dependencies.

    * This is a synchrouns method.

    *

    * @param aEngine - Reference to engine.

    * @param aSkipDependencyCheck - If ETrue, plug-in as executed

    *   even if dependencies are not executed.

    * @param aCustomParams Custom parameters for plug-ins. 

    *   It can used to pass arbitrary data from application to the plug-ins.

    *   Owership is not transferred and plug-in must not delete

    *   this parameter.

    */

    IMPORT_C virtual void TestSessionEndL( MDiagEngineCommon& aEngine,

                                           TBool aSkipDependencyCheck,

                                           TAny* aCustomParams );

    /**

    * Execute diagnostics test.

    * @see MDiagTestPlugin::RunTestL

    */

    IMPORT_C virtual void RunTestL( TDiagTestExecParam* aExecParam,

                                    TBool aSkipDependencyCheck,

                                    TBool aDependencyExecution,

                                    TAny* aCustomParams );

    /**

    * Suspend test.  

    * @see MDiagTestPlugin::SuspendL

    */

    IMPORT_C virtual void SuspendL();

    /**

    * Resume test. 

    * @see MDiagTestPlugin::ResumeL

    */

    IMPORT_C virtual void ResumeL();

    /**

    * Create test result detail.

    * @see CDiagTestPluginBase::CreateDetailL

    */

    IMPORT_C virtual MDiagResultDetail* CreateDetailL( 

        const CDiagResultsDatabaseItem& aResult ) const;