diff -r 588ad05716be -r c15b68295419 remotemgmt_plat/diagnostics_plugin_api/inc/diagtestpluginbase.h --- a/remotemgmt_plat/diagnostics_plugin_api/inc/diagtestpluginbase.h Sat May 01 10:33:10 2010 +0530 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,589 +0,0 @@ -/* -* 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 // MDiagTestPlugin -#include // RConeResourceLoader -#include // CDiagResultsDatabaseItem::TResult -#include // 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 - * : - */ - 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*& 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*& 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; - -private: // private functions - /** - * Stop and clean up CDiagTestPluginBase - */ - void BaseStopAndCleanup(); - - /** - * Utility function to get all dependent test plug-ins. If suite is found, - * it will be expanded to test plug-ins. - - * @param aEngine. Reference to engine, which provides references to - * database session and plug-in pool. - * @param aPluginList - Output array. Upon completion, it will hold - * list of test plug-ins. If this plug-in does not depend on any tests, - * it will be empty. - * Ownership of individual items are not trasferred, so ResetAndDestroy() - * must not be called. - */ - void GetAllDependentTestsL( MDiagEngineCommon& aEngine, - RPointerArray< MDiagTestPlugin >& aPluginList ) const; - - /** - * Utility function to check results of tests in array and come up with - * best overall result of tests. - * @param aPluginList - List of test plug-ins. - * @param aFailedUidList - Output array. Upon completion, it will contain - * list of uids that failed. - * @return Overall result of dependent tets. - */ - CDiagResultsDatabaseItem::TResult SummarizeOverallTestResultsL( - MDiagEngineCommon& aEngine, - const RPointerArray< MDiagTestPlugin >& aPluginList, - RArray< TUid >& aFailedUidList ) const; - - -private: // Private Data Type - // Forward declaration. - class TPrivateData; - -private: // Private Data - /** - * Plug-in constructor parameter. - * Ownership: this - */ - CDiagPluginConstructionParam* iConstructionParam; - - /** - * CCoeEnv. This is needed for handling resources. - */ - CCoeEnv& iCoeEnv; - - /** - * Plug-in base's private data - */ - TPrivateData* iData; - }; - -#endif // DIAGTESTPLUGINBASE_H - -// End of File -