1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Diagnostics Test Plug-in  Base class

    15 *

    16 */

    17 

    18 

    19 #ifndef DIAGTESTPLUGINBASE_H

    20 #define DIAGTESTPLUGINBASE_H

    21 

    22 // INCLUDES

    23 #include <DiagTestPlugin.h>     // MDiagTestPlugin

    24 #include <ConeResLoader.h>      // RConeResourceLoader

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

    26 #include <DiagEngineWatchdogTypes.h>    // TDiagEngineWatchdogTypes

    27 

    28 // FORWARD DECLARATIONS

    29 class CDiagResultsDbItemBuilder;

    30 class TDiagTestPluginBasePrivateData;

    31 class CDiagPluginConstructionParam;

    32 class CAknDialog;

    33 

    34 /**

    35 *  Diagnostics Framework Test Plugin  Base Class

    36 *

    37 *  This class provides further simplification of test execution.

    38 *  It handles execution parameter and reporting results to engine

    39 *

    40 *  @since S60 v5.0

    41 */

    42 class CDiagTestPluginBase : public CActive,

    43                             public MDiagTestPlugin

    44     {

    45 public: // C++ Destructor

    46     /**

    47     * Destructor.

    48     */

    49     IMPORT_C virtual ~CDiagTestPluginBase();

    50 

    51 protected: // new API for derived class

    52     /**

    53     * C++ constructor

    54     * 

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

    56     * @param aConstructionParam Construction parameters.

    57     */

    58     IMPORT_C CDiagTestPluginBase( CDiagPluginConstructionParam* aConstructionParam );

    59     

    60     /**

    61     * 2nd phase Base class constructor

    62     * This initializes CDiagTestPluginBase class. Derived class must call this

    63     * method in its ConstructL() method.

    64     *  

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

    66     *                          <path>:<rsc_file_name>

    67     */

    68     IMPORT_C void BaseConstructL( const TDesC& aResourceFileName );

    69 

    70     /**

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

    72     * failed dependencies.

    73     *

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

    75     *   database session and plug-in pool.

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

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

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

    79     *           responsible of closing the array.

    80     * @return ETrue if all dependencies are executed successfully.

    81     *         EFalse if one or more dependencies are failed.

    82     */

    83     IMPORT_C virtual TBool AreDependenciesSatisfiedL( MDiagEngineCommon& aEngine,

    84                                             RArray<TUid>*& aFailedUids ) const;

    85 

    86     /**

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

    88     * determine the best overall result of all the dependencies.

    89     *

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

    91     *   database session and plug-in pool.

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

    93     *           Otherwise the parameter points to an array that

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

    95     *           responsible of closing the array.

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

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

    98     */

    99     IMPORT_C virtual CDiagResultsDatabaseItem::TResult VerifyDependenciesL( 

   100         MDiagEngineCommon& aEngine,

   101         RArray<TUid>*& aFailedUids ) const;

   102 

   103     /**

   104     * Returns execution parameter. 

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

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

   107     *

   108     * @return Execution parameter.

   109     */

   110     IMPORT_C TDiagTestExecParam& ExecutionParam();

   111 

   112     /**

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

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

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

   116     * 

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

   118     *   EFalse if dependency check is enabled.

   119     */

   120     IMPORT_C TBool IsDependencyCheckSkipped() const;

   121 

   122     /**

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

   124     *   if it is being executed explicitly.

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

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

   127     *

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

   129     *   EFalse - If it is being executed explicitly.

   130     */

   131     IMPORT_C TBool IsDependencyExecution() const;

   132 

   133     /**

   134     * Get custom parameter passed to from the engine

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

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

   137     * 

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

   139     */

   140     IMPORT_C TAny* CustomParam() const;

   141 

   142     /**

   143     * Get currently result db item builder.

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

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

   146     *

   147     * @return Reference to current CDiagResultsDbItemBuilder.

   148     */

   149     IMPORT_C CDiagResultsDbItemBuilder& ResultsDbItemBuilder();

   150 

   151     /**

   152     * Report test progress test observer.

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

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

   155     *

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

   157     *   If EInteractiveView or EInteractiveDialog, EDiagEngineWatchdogTypeInteractive. 

   158     *

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

   160     *   CDiagResultsDatabaseItem::EWatchdogCancel.

   161     *

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

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

   164     *

   165     * @param aCurrentStep - Current execution step

   166     */

   167     IMPORT_C void ReportTestProgressL( TUint aCurrentStep );

   168 

   169     /**

   170     * Reset watchdog value and watchdog failure result type.

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

   172     *   value to report back to engine.  

   173     *

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

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

   176     *

   177     * @param aWatchdogType - Type of watchdog requested.

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

   179     */

   180     IMPORT_C void ResetWatchdog( TDiagEngineWatchdogTypes aWatchdogType,

   181                                  CDiagResultsDatabaseItem::TResult aResultType );

   182 

   183     /**

   184     * Reset watchdog value and watchdog failure result type.

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

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

   187     *

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

   189     *   value to report back to engine.  

   190     *

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

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

   193     *

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

   195     *   Unit is in microseconds.

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

   197     */

   198     IMPORT_C void ResetWatchdog( 

   199         TInt aTimeToCompletion,

   200         CDiagResultsDatabaseItem::TResult aResultType );

   201 

   202     /**

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

   204     *   This will also reset watchdog on engine.

   205     *

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

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

   208     *

   209     */

   210     IMPORT_C void ResetWatchdogToDefault();

   211 

   212     /**

   213     * Report test result to test observer. 

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

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

   216     *

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

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

   219     *   other test state specific API will fail.

   220     *

   221     * @param aResult - Test result.

   222     */

   223     IMPORT_C void CompleteTestL( CDiagResultsDatabaseItem::TResult aResult );

   224 

   225     /**

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

   227     *   This method will call DoStopAndCleanupL() function to allow

   228     *   derived class to clean up.

   229     *   

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

   231     *

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

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

   234     *   proper clean up of CDiagTestPluginBase.

   235     *

   236     *   @see CDiagTestPluginBase::ExecutionStopL

   237     */

   238     IMPORT_C void StopAndCleanupL();

   239 

   240     /**

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

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

   243     * deletion of dialogs.

   244     *

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

   246     * ETrue if dialog exited due to user response and 

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

   248     * by DismissWaitingDialog() method. 

   249     * 

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

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

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

   253     * 

   254     * The normal dialog response is returned via aDialogResponse reference.

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

   256     * while it has not been returned will cause panic.

   257     *

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

   259     *   EEikDialogFlagWait flag set, it will panic with EDiagPluginBaseBadArgument

   260     * @param aDialogResponse - Response from the dialog.  

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

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

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

   264     *   Efalse if dialog is dismissed withou user input. 

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

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

   267     */

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

   269 

   270     /**

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

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

   273     * does nothing.

   274     */

   275     IMPORT_C void DismissWaitingDialog();

   276 

   277     /**

   278     * CCoeEnv

   279     *   @return Reference to CCoeEnv.

   280     */

   281     IMPORT_C CCoeEnv& CoeEnv();

   282 

   283     /**

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

   285     * as a part of a suite

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

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

   288     *

   289     * @return ETrue - If run as a single plugin

   290     *   EFalse - If run as a part of a suite

   291     */

   292     IMPORT_C TBool SinglePluginExecution() const;

   293     

   294 protected:  // to be implemented by derived classes

   295     /**

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

   297     *   Note that CDiagTestPluginBase takes ownership of all parameters

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

   299     *   use the following set of functions:

   300     *

   301     *   Parameters are available via the following APIs.

   302     *       Observer:               ExecutionParam().Observer();

   303     *       Engine:                 ExecutionParam().Engine();

   304     *       Dependency Execution:   IsDependencyExecution();

   305     *       Skip Depdency:          IsDependencyCheckSkipped();

   306     *       Custom Parameter:       CustomParam();

   307     *

   308     *   Also, a new instance of CDiagResultsDbItemBuilder is created and

   309     *   accessible via:

   310     *

   311     *       Result Db Item Builder: ResultsDbItemBuilder();

   312     */

   313     virtual void DoRunTestL() = 0;

   314 

   315     /**

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

   317     *   This is called by StopAndCleanupL

   318     */

   319     virtual void DoStopAndCleanupL() = 0;

   320 

   321     /**

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

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

   324     *   Default implementation does nothing. For more information about

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

   326     *

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

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

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

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

   331     *   to this variable.

   332     *

   333     */

   334     IMPORT_C virtual void DoExecutionStopL( MDiagTestPlugin::TStopReason aReason,

   335                                             CDiagResultsDatabaseItem::TResult& aTestResult );

   336 

   337 protected:  // From CActive

   338     /**

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

   340     * CDiagTestPluginBase will handle the error by calling 

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

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

   343     * 

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

   345     * method.

   346     * 

   347     * For parameters and return value, 

   348     * @see CActive::RunError

   349     */

   350     IMPORT_C virtual TInt RunError( TInt aError );

   351 

   352 protected: // from MDiagTestPlugin

   353     /**

   354     * Handle execution stop.

   355     *   @see MDiagTestPlugin::ExecutionStopL()

   356     * 

   357     *   This method does the following:

   358     *       a) Call DoExecutionStopL()   

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

   360     *       c) Return either EWatchdogCancel or ECancelled depending on

   361     *           the stop reason. 

   362     *   

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

   364     *   call StopAndCleanupL() to allow proper clean up of 

   365     *   CDiagTestPluginBase class. StopAndCleanupL() will call

   366     *   DoStopAndCleanupL(). 

   367     *

   368     *   @see DoExecutionStopL()

   369     *   @see StopAndCleanupL() 

   370     */

   371     IMPORT_C virtual CDiagResultsDatabaseItem* ExecutionStopL( TStopReason aReason );

   372 

   373 protected:    // from MDiagTestPlugin

   374     /**

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

   376     *

   377     * @return The name of the service.

   378     */

   379     IMPORT_C virtual const TDesC& ServiceLogicalName() const;

   380 

   381     /**

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

   383     * other plug-ins.

   384     *

   385     * @param aArray An array of logical names.

   386     * @see ServiceLogicalNameL

   387     */

   388     IMPORT_C virtual void GetLogicalDependenciesL( CPtrCArray& aArray ) const;

   389 

   390     /**

   391     * Return the type of the plug-in. 

   392     *

   393     * @return The type.

   394     * @see TPluginType.

   395     */

   396     IMPORT_C virtual TPluginType Type() const;

   397 

   398     /**

   399     * Create an icon that represents the plug-in.

   400     *

   401     * @return An icon. 

   402     */

   403     IMPORT_C virtual CGulIcon* CreateIconL() const;

   404 

   405     /**

   406     * @see MDiagPlugin::IsSupported

   407     */

   408     IMPORT_C virtual TBool IsSupported() const;

   409 

   410     /**

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

   412     *

   413     * @return TUint order number.

   414     */

   415     IMPORT_C virtual TUint Order() const;

   416 

   417     /**

   418     * Get UID of the parent.

   419     *

   420     * @return The parent UID.

   421     */

   422     IMPORT_C virtual TUid ParentUid() const;

   423 

   424     /**

   425     * @see MDiagPlugin::SetDTorIdKey()

   426     */

   427     IMPORT_C virtual void SetDtorIdKey( TUid aDtorIdKey );

   428 

   429     /**

   430     * Get title of the plugin. Default implementation in CDiagTestPluginBase 

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

   432     *   must override this method.

   433     * @see MDiagPlugin::GetTitleL() 

   434     */

   435     IMPORT_C virtual HBufC* GetTitleL() const;

   436 

   437     /**

   438     * Get description of the plugin. Default implementation in 

   439     *   CDiagTestPluginBase will leave with KErrNotSupported. If plug-in 

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

   441     * @see MDiagPlugin::GetDescriptionL()

   442     */

   443     IMPORT_C virtual HBufC* GetDescriptionL() const;

   444 

   445     /**

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

   447     *

   448     * @param aUid   Unique identifier of the operation.

   449     * @param aParam Custom parameter. 

   450     * @return TAny pointer. Custom data.

   451     */

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

   453 

   454     /**

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

   456     *

   457     * @param aUid   Unique identifier of the property

   458     * @param aParam Custom parameter.

   459     * @return TAny pointer. Custom data. 

   460     */

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

   462 

   463     /**

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

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

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

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

   468     *

   469     * @param aEngine - Reference to engine.

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

   471     *   even if dependencies are not executed.

   472     * @param aCustomParams Custom parameters for plug-ins. 

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

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

   475     *   this parameter.

   476     */

   477     IMPORT_C virtual void TestSessionBeginL( MDiagEngineCommon& aEngine,

   478                                              TBool aSkipDependencyCheck,

   479                                              TAny* aCustomParams );

   480 

   481     /**

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

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

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

   485     * provides dependent service created for its dependencies.

   486     * This is a synchrouns method.

   487     *

   488     * @param aEngine - Reference to engine.

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

   490     *   even if dependencies are not executed.

   491     * @param aCustomParams Custom parameters for plug-ins. 

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

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

   494     *   this parameter.

   495     */

   496     IMPORT_C virtual void TestSessionEndL( MDiagEngineCommon& aEngine,

   497                                            TBool aSkipDependencyCheck,

   498                                            TAny* aCustomParams );

   499 

   500 

   501     /**

   502     * Execute diagnostics test.

   503     * @see MDiagTestPlugin::RunTestL

   504     */

   505     IMPORT_C virtual void RunTestL( TDiagTestExecParam* aExecParam,

   506                                     TBool aSkipDependencyCheck,

   507                                     TBool aDependencyExecution,

   508                                     TAny* aCustomParams );

   509 

   510     /**

   511     * Suspend test.  

   512     * @see MDiagTestPlugin::SuspendL

   513     */

   514     IMPORT_C virtual void SuspendL();

   515 

   516     /**

   517     * Resume test. 

   518     * @see MDiagTestPlugin::ResumeL

   519     */

   520     IMPORT_C virtual void ResumeL();

   521 

   522     /**

   523     * Create test result detail.

   524     * @see CDiagTestPluginBase::CreateDetailL

   525     */

   526     IMPORT_C virtual MDiagResultDetail* CreateDetailL( 

   527         const CDiagResultsDatabaseItem& aResult ) const;

   528 

   529 private:    // private functions

   530     /**

   531     * Stop and clean up CDiagTestPluginBase

   532     */

   533     void BaseStopAndCleanup();

   534 

   535     /**

   536     * Utility function to get all dependent test plug-ins. If suite is found,

   537     * it will be expanded to test plug-ins.

   538 

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

   540     *   database session and plug-in pool.

   541     * @param aPluginList - Output array. Upon completion, it will hold

   542     *   list of test plug-ins. If this plug-in does not depend on any tests, 

   543     *   it will be empty.

   544     *   Ownership of individual items are not trasferred, so ResetAndDestroy()

   545     *   must not be called.

   546     */

   547     void GetAllDependentTestsL( MDiagEngineCommon& aEngine,

   548                                 RPointerArray< MDiagTestPlugin >& aPluginList ) const;

   549 

   550     /**

   551     * Utility function to check results of tests in array and come up with

   552     * best overall result of tests. 

   553     * @param aPluginList - List of test plug-ins.

   554     * @param aFailedUidList - Output array. Upon completion, it will contain

   555     *   list of uids that failed.

   556     * @return Overall result of dependent tets.

   557     */

   558     CDiagResultsDatabaseItem::TResult SummarizeOverallTestResultsL( 

   559         MDiagEngineCommon& aEngine,

   560         const RPointerArray< MDiagTestPlugin >& aPluginList,

   561         RArray< TUid >& aFailedUidList ) const;

   562 

   563 

   564 private:    // Private Data Type

   565     // Forward declaration.

   566     class TPrivateData;

   567 

   568 private:    // Private Data

   569     /**

   570     * Plug-in constructor parameter.

   571     * Ownership: this

   572     */

   573     CDiagPluginConstructionParam* iConstructionParam;

   574 

   575     /**

   576     * CCoeEnv. This is needed for handling resources. 

   577     */

   578     CCoeEnv& iCoeEnv;

   579 

   580     /**

   581     * Plug-in base's private data

   582     */

   583     TPrivateData* iData;

   584     };

   585 

   586 #endif // DIAGTESTPLUGINBASE_H

   587 

   588 // End of File

   589