/*

* 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:  Common interface to use engine

*

*/

#ifndef DIAGENGINECOMMON_H

#define DIAGENGINECOMMON_H

// SYSTEM INCLUDES

#include <e32std.h>                     // TDesC, TTimeIntervalMicroSeconds32

#include <DiagCommonDialog.h>           // TDiagCommonDialog

#include <DiagAppCommand.h>             // TDiagAppCommand

#include <DiagEngineWatchdogTypes.h>    // TDiagEngineWatchdogTypes

// FORWARD DECLARATION

class MDiagPluginExecPlan;

class MDiagPlugin;

class CAknViewAppUi;

class RDiagResultsDatabaseRecord;

class CDiagPluginPool;

class CAknDialog;

/**

*  Diagnostics Framework Engine Common Interface

*

*  This interface is provided for Test plug-ins, Suite plug-ins and

*  any other clients of CDiagEngine.

*

*  @since S60 v5.0

*/

class MDiagEngineCommon

    {

public: // Data Structures

    /** 

    * Possible cancellation mode.

    */

    enum TCancelMode

        {

        ESkip,        // Cancel current test only. Continue rest.

        ECancelAll      // Cancel current test and skip rest of execution.

        };

    /**

    *  Text List based config options

    */

    enum TConfigListType

        { 

        /**

        * EConfigListCallIngore - List of phone numbers to ignore. 

        *   If a phone number is added to this list, engine will ignore the number

        *   a new MO/MT call is created by the phone, and will not suspend

        *   the engine execution when new call is made.

        */

        EConfigListCallIngore = 0

        };

public: // public methods

    /**

    * Returns current execution plan.

    * If test is not being executed, it will leave with KErrNotReady.

    *

    * @return Reference to current execution plan.

    */

    virtual const MDiagPluginExecPlan& ExecutionPlanL() const = 0;

    /**

    * Stop current execution of tests.

    * If test is not being executed, it will leave with KErrNotReady.

    *

    * @param aCancelMode   ESkip       - Skip current test only. Rest will continue.

    *                      ECancelAll  - Cancels current test and skips the rest of

    *                                  execution.

    */

    virtual void ExecutionStopL( TCancelMode aCancelMode ) = 0;

    /**

    * Resets test execution watchdog timer.  It will use the last given watchdog

    * timer value for currently executing plug-in.

    */

    virtual void ResetWatchdog() = 0;

    /**

    * Resets test execution watchdog timer.  

    *   Watchog timer value will be determined by the type of watchdog requested.

    *   Given value is valid until next plug-in is executed, or another

    *   ResetWachdogL() or TestProgressL() is called.

    *

    * @param aWatchdogType Type of watchdog timer vaule to use.

    *   @see TDiagEngineWatchdogTypes

    */

    virtual void ResetWatchdog( TDiagEngineWatchdogTypes aWatchdogType ) = 0;

    /**

    * Resets test execution watchdog timer.  

    *   Engine will allow specified amount of time. 

    *   Given value is valid until next plug-in is executed, or another

    *   ResetWachdogL() or TestProgressL() is called.

    * 

    * @param aTimeToWait - Amount of time to wait before watchdog is expired.

    */

    virtual void ResetWatchdog( TTimeIntervalMicroSeconds32 aExpectedTimeToComplete ) = 0;

    /**

    * Get App Ui reference that launched Diagnostics Engine.

    * AppUi reference can be used for tests that requires AppUi for view switching.

    * 

    * @return Reference to CAknViewAppUi

    */

    virtual CAknViewAppUi& ViewAppUi() = 0;

    /**

    * Get App Ui reference that launched Diagnostics Engine.

    * AppUi reference can be used for tests that requires AppUi for view switching.

    * 

    * @return Reference to CAknViewAppUi

    */

    virtual const CAknViewAppUi& ViewAppUi() const = 0;

    /**

    * Get Database Subsession for record open for writing.

    * 

    * @return Reference to RDiagResultsDatabaseRecord

    */

    virtual RDiagResultsDatabaseRecord& DbRecord() = 0;

    /**

    * Get Database Subsession for record open for writing.

    * 

    * @return Reference to RDiagResultsDatabaseRecord

    */

    virtual const RDiagResultsDatabaseRecord& DbRecord() const = 0;

    /**

    * Get reference to Plugin Pool

    * 

    * @return Reference to CDiagPluginPool

    */

    virtual CDiagPluginPool& PluginPool() = 0;

    /**

    * Get reference to Plugin Pool

    * 

    * @return Reference to CDiagPluginPool

    */

    virtual const CDiagPluginPool& PluginPool() const = 0;

    /**

    * Add a text to configuraiton list option. 

    * 

    * @param aListType - List type to add the configuration option to. 

    *   @see TConfigListType

    * @param aText - text to add to the list

    */

    virtual void AddToConfigListL( TConfigListType aListType, const TDesC& aText ) = 0;

    /**

    * Remove a text from configuration list.

    * If configuration item text does not exist in the list, this function will 

    * leave with KErrNotFound.

    * 

    * @param aListType - List type to remove the item from. 

    *   @see TConfigListType

    * @param aText - text for the option

    */

    virtual void RemoveFromConfigListL( TConfigListType aListType, const TDesC& aText ) = 0;

    /**

    * Create a common dialog.

    * Plug-ins can use this factory method to create a common dialog.

    * For available dialog types, @see DiagCommonDialog.h

    * 

    * @param aDialogType - Type of dialog to create.

    * @param aInitData - Initialization parameter. Ownership is passed to engine.

    * @return a pointer to newly created dialog. Ownership is passed to caller.

    */

    virtual CAknDialog* CreateCommonDialogLC( TDiagCommonDialog aDialogType,

                                              TAny* aInitData ) = 0;

    /**

    * Stop watchdog activity temporarily. Watchdog will stay inactive until:

    *   a ) TestProgressL() is called.

    *   b ) ResetWatchdogL() is called.

    *   c ) Plug-in is cancelled and the next plug-in starts to execute.

    */

    virtual void StopWatchdogTemporarily() = 0;

    /**

    * Check if current engine is being executed with dependency disabled.

    *   @return TBool - ETrue if dependency is disabled.

    *                   EFalse if depencenty is enabled.

    */

    virtual TBool IsDependencyDisabled() const = 0;

    /**

    * Get custom parameter passed during engine creation.

    *   @return TAny* Custom parameter.  Ownership is not transferred.

    */

    virtual TAny* CustomParam() const = 0;

    /**

    * Send a command to application to execute.. This can be used by the plug-in to

    * request certain behavior from application. For more information about

    * types of commands possible, @see TDiagAppCommand.

    * If the command is not supported by the application, this function will 

    * leave with error code KErrNotSupported.

    *

    * Memory Ownership of Parameters.

    *   Note that in general, parameters should be owned by the caller. This is 

    *   because if a particular operation is not supported, application 

    *   will not know how to deallocate the parameter, causing memory leak.

    *   

    *   In cases where ownership must be passed, caller must check if

    *   ExecuteAppCommandL() leaves KErrNotSupported and deallocate

    *   parameters.

    *

    * @param aCommand - Type of command to execute. @see TDiagAppCommand

    * @param aParam1 - Data for the command. Value of this parameter depends

    *   on the type of command. Ownership not transferred. @see TDiagAppCommand

    * @param aParam2 - Data for the command. Value of this parameter depends

    *   on the type of command. Ownership not transferred. @see TDiagAppCommand

    *   

    */

    virtual void ExecuteAppCommandL( TDiagAppCommand aCommand, 

                                     TAny* aParam1,

                                     TAny* aParam2 ) = 0;

    };

#endif // DIAGENGINECOMMON_H

// End of File