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:  Handles most of the model related logic..

    15 *

    16 */

    17 

    18 

    19 #ifndef DEVDIAGDENGINE_H

    20 #define DEVDIAGDENGINE_H

    21 

    22 // System Include Files

    23 #include <e32base.h>                // CActive

    24 #include <etel3rdparty.h>           // CTelephony

    25 #include <DiagResultsDatabase.h>    // RDiagResultsDatabase,

    26                                     // RDiagResultsDatabaseRecord

    27 #include <DiagEngineObserver.h>     // MDiagEngineObserver

    28 #include <DiagPluginPoolObserver.h> // MDiagPluginPoolObserver

    29 #include <DiagCommonDialog.h>       // TDiagCommonDialog

    30 

    31 // Forward Declarations

    32 class MDevDiagEngineObserver;

    33 class MDiagPlugin;

    34 class MDiagSuitePlugin;

    35 class CDevDiagExecResults;

    36 class CDiagResultsDatabaseItem;

    37 class CDiagEngine;

    38 class RFs;

    39 class CDiagPluginPool;

    40 class CAknViewAppUi;

    41 class CAknDialog;

    42 class CIdle;

    43 

    44 /**

    45  *  Device Diagnostics Application Engine

    46  *  This class defines the engine used by the Device Diagnostics application.  The

    47  *  engine class handles the interfacing between UI components and diagnostics

    48  *  components.

    49  *

    50  *  @lib euser.lib

    51  *  @lib diagframework.lib

    52  *  @lib etel3rdparty.lib

    53  *  @lib diagresultsdatabase.lib

    54  *  @lib avkon.lib

    55  *  @lib eikcore.lib

    56  *  @lib eiksrv.lib

    57  *  @lib efsrv.lib

    58  *  @lib drmserviceapi.lib

    59  */

    60 class CDevDiagEngine : public CActive,

    61                        public MDiagEngineObserver,

    62                        public MDiagPluginPoolObserver

    63     {

    64 

    65 public: // Data Types

    66 

    67     /**  This enum indicates how the engine should stop tests. */

    68     enum TDevDiagAppEngineStopMode

    69         {

    70         EStopModeSkip,

    71         EStopModeCancel,

    72         EStopModeSuspend,

    73         EStopModeWatchdog

    74         };

    75 

    76     enum TDevDiagAppEngineResumeMode

    77         {

    78         EResumeModeResume,

    79         EResumeModeWatchdog

    80         };

    81 

    82 

    83 public: // New Functions

    84 

    85     /**

    86      * Two-phased constructor.

    87      */

    88     static CDevDiagEngine* NewL();

    89 

    90     /**

    91      * Two-phased constructor.

    92      * Leaves the new engine instance on the cleanup stack.

    93      */

    94     static CDevDiagEngine* NewLC();

    95 

    96     /**

    97     * Destructor.

    98     */

    99     virtual ~CDevDiagEngine();

   100 

   101     /**

   102      * Sets the engine observer, for receiving engine events.

   103      *

   104      * @param aObserver A pointer to a class implementing the observer

   105      *                  interface.  Ownership is not transferred.

   106      */

   107     void SetObserver( MDevDiagEngineObserver* aObserver );

   108 

   109     /**

   110      * Run a test or suite of tests.

   111      *

   112      * @param aUid The UID of the test or suite to execute.

   113      * @param aAppUi The application UI which is executing tests.

   114      */

   115     void ExecuteTestL( TUid aUid, CAknViewAppUi& aAppUi );

   116 

   117     /**

   118      * Gets the results from test execution.  Results may be from a log or

   119      * from live test execution.  The caller should check if results are

   120      * available before calling this function.

   121      *

   122      * @return A reference to the execution results.

   123      */

   124     const CDevDiagExecResults& ExecutionResults() const;

   125 

   126     /**

   127      * Instructs the engine to populate the execution results information with

   128      * the last set of logged data.  This may be followed by a call to

   129      * ExecutionResults to retrieve the data.

   130      */

   131     void LoadLastLoggedResultsL();

   132 

   133     /**

   134     * Get results of the suite. Observer will be notified when

   135     * results are ready (EDevDiagEngineCommandGetLastResult).

   136     * 

   137     * @param aParentUid UID of the plug-in whose results are needed.

   138     */

   139     void GetLastResultsL( TUid aParentUid );

   140 

   141     /**

   142      * Suspends, skips, or halts test execution.

   143      *

   144      * @param aReason The reason for stopping execution.

   145      */

   146     void ExecutionStopL( TDevDiagAppEngineStopMode aReason );

   147 

   148     /**

   149      * Resumes the diagnostics engine.  In the case of resuming suspended test

   150      * execution, this must have been preceded by a call to ExecutionStopL

   151      * with EStopModeSuspend specified.

   152      *

   153      * @param aReason The reason for resuming execution.

   154      */

   155     void ExecutionResumeL( TDevDiagAppEngineResumeMode aReason );

   156 

   157     /**

   158      * Gets the plugin pool, which is owned by the engine.

   159      *

   160      * @return A reference to the plugin pool.

   161      */

   162     const CDiagPluginPool& PluginPool() const;

   163 

   164     /**

   165      * Checks if the engine is currently running plugins.  This includes

   166      * when the engine is suspended for any reason.

   167      *

   168      * @return ETrue if plugins are running, EFalse otherwise.

   169      */

   170     TBool IsRunningPlugins() const;

   171 

   172     /**

   173      * Checks if the engine is currently stopping execution.

   174      *

   175      * @return ETrue if execution is being cancelled, EFalse otherwise.

   176      */

   177     TBool IsStoppingExecution() const;

   178 

   179     /**

   180      * Checks if the engine is initialzed (it has finished loading plugins).

   181      * This must be true before the runtime requirements can be checked or

   182      * the reference to the plugin pool can be returned.

   183      *

   184      * @return ETrue if plugins are loaded, EFalse otherwise.

   185      */

   186     TBool ArePluginsLoaded() const;

   187 

   188     /**

   189      * Checks if the engine has execution results available.  This must be

   190      * true before a reference to the results can be retrieved.

   191      *

   192      * @return ETrue if results are available, EFalse otherwise.

   193      */

   194     TBool HasExecutionResults() const;

   195     

   196     /**

   197      * Searches Results Database for a crashed test plug-in.

   198      * 

   199      * @param aPluginUid Plug-in Uid that crashed.

   200      * @return ETrue if crashed plug-in was found, EFalse otherwise.

   201      **/

   202     TBool CrashedPluginL( TUid& aPluginUid );

   203 

   204     /**

   205      * Marks the crashed test record as complete in the database.  This

   206      * means that the test record is not found again when calling CrashedTestRecordL.

   207      *

   208      * @return KErrNone if the record was successfully completed, otherwise, a

   209      *         system error code.

   210      */

   211     //TInt CompleteCrashedTestRecord();

   212     ///@@@KSR: changes for Codescanner error val = High

   213     TInt CompleteCrashedTestRecordL();

   214     ///@@@KSR: changes for Codescanner error val = High

   215     // ADO & Platformization Changes

   216     TBool GetPluginDependencyL();

   217     // GetState

   218     TInt GetState();

   219 

   220 private: // Data Types

   221 

   222     /**  This enum indicates the engine's internal state.

   223      *   Any changes to this enum must be reflected with changes to the

   224      *   SetState function.

   225      */

   226     enum TDevDiagAppEngineState

   227         {

   228         EStateInitial = 0,

   229         EStateLoadingPlugins,

   230         EStateReady,

   231         EStateStartingExecution,

   232         EStateRunningTests,

   233         EStateStoppingExecution,

   234         EStateExecutionSuspended,

   235         EStateMax

   236         };

   237 

   238 

   239 private: // New Functions

   240 

   241     /**

   242      * The default constructor.

   243      */

   244     CDevDiagEngine();

   245 

   246     /**

   247      * Two-phased constructor.

   248      */

   249     void ConstructL();

   250 

   251     /**

   252      * Handles state transitions in the application engine by validating the

   253      * requested transition.

   254      *

   255      * @param aNextState The new state to transition to.

   256      */

   257     void SetState( TDevDiagAppEngineState aNextState );

   258 

   259     /**

   260      * The callback function to continue handling cancelling execution.

   261      *

   262      * @param aPtr A pointer to "this" object.

   263      * @return Always KErrNone.

   264      */

   265     static TInt HandleExecutionCancelledL( TAny* aPtr );

   266 

   267 

   268 private: // From base class CActive

   269 

   270     /**

   271      * From CActive.

   272      * This function is called when an active request completes.  For the

   273      * application engine, this only happens when checking runtime

   274      * requirements.

   275      */

   276     virtual void RunL();

   277 

   278     /**

   279      * From CActive.

   280      * This function is called to cancel any outstanding asynchronous

   281      * requests.

   282      */

   283     virtual void DoCancel();

   284     

   285     /**

   286      * From CActive.

   287      * This function is called when RunL leaves

   288      * 

   289      */

   290     virtual TInt RunError( TInt aError );

   291 

   292 

   293 private: // From base class MDiagEngineObserver

   294 

   295     /**

   296      * From MDiagEngineObserver.

   297      * This callback is used when test execution starts.

   298      *

   299      */

   300     virtual void TestExecutionBeginL();

   301     

   302     /**

   303     * Notify client of execution completion of one plug-in.

   304     *   This can be either test plug-in or suite plug-in.

   305     *

   306     * @param aError  - KErrNone - Success.

   307     *   KErrNoMemory - Out of memory.

   308     *   KErrCancel   - Cancelled due to ExecutionStopL()

   309     *

   310     * @param aResult - Result of the test. Ownership is transferred here. 

   311     *  Client must deallocate aResult to avoid memory leak. aResult is Null 

   312     *  if the plug-in being executed is a suite pre/post method.

   313     */

   314     virtual void TestExecutionPluginExecutedL( TInt aError,

   315                                                CDiagResultsDatabaseItem* aResult );

   316 

   317     /**

   318      * From MDiagEngineObserver.

   319      * This callback is used to inform the application of the execution

   320      * progress for the currently executing test.

   321      *

   322      * @param aCurrentItemStep The current step for this test.

   323      * @param aCurrentItemTotalSteps The total number of steps for this test.

   324      */

   325     virtual void TestExecutionProgressL( TUint aCurrentItemStep,

   326                                          TUint aCurrentItemTotalSteps);

   327 

   328 

   329     /**

   330     * From MDiagEngineObserver.

   331     * Notify client of engine stopping.

   332     *

   333     * This indicates that engine execution has stopped. There will not be any

   334     * further messages from engine. This could be called because all

   335     * tests are completed, or an unrecoverable error occured during execution.

   336     *

   337     * Note that if cancel is called during plan creation or if plan creation

   338     * fails, TestExecutionStoppedL() may be called withing first calling

   339     * TestExecutionBeginL(). 

   340     *

   341     * @param aError - Reason for engine stopping. 

   342     *   a) KErrNone - All tests are successfully completed.

   343     *   b) KErrCancel - ExecutionStopL is called with ECancelAll. 

   344     *       Test session cannot be resumed later.

   345     *   c) KErrArgument - Parameters passed to engine are invalid.

   346     *   d) Others - Other critical that could not be recovered occured during

   347     *       test execution.  Test may be resumed later in this case.

   348     */

   349     virtual void TestExecutionCompletedL( TInt aError );

   350 

   351     /**

   352      * From MDiagEngineObserver.

   353      * Notifes that execution has been suspended.

   354      *

   355      * @param aSuspendReason Why execution is suspended.

   356      */

   357     virtual void TestExecutionSuspendedL( TSuspendReason aSuspendReason );

   358 

   359     /**

   360      * From MDiagEngineObserver.

   361      * Notifes that execution has been resumed.

   362      *

   363      * @param aResumeReason Why execution is resumed.

   364      */

   365     virtual void TestExecutionResumedL( TResumeReason aResumeReason );

   366 

   367     /**

   368      * From MDiagEngineObserver.

   369      * Create a common dialog.

   370      * @param aDialogType Type of dialog to create.

   371      * @param aData Initialization parameter. Ownership is transferred.

   372      * @return A pointer to newly created dialog. Ownership is passed to

   373      *         caller.

   374     */

   375     virtual CAknDialog* CreateCommonDialogLC( TDiagCommonDialog aDialogType,

   376                                               TAny* aInitData );

   377                                               

   378     /**

   379     * From MDiagEngineObserver.

   380     *

   381     * Execute a command from plug-in. Parameters are identical to 

   382     * MDiagEngineCommon::ExecuteAppCommandL(). 

   383     * @see MDiagEngineCommon::ExecuteAppCommandL()

   384     * @see TDiagAppCommand

   385     */

   386     virtual void ExecuteAppCommandL( TDiagAppCommand aCommand, 

   387                                      TAny* aParam1,

   388                                      TAny* aParam2 );                                              

   389 

   390 

   391 private: // From base class MDiagPluginPoolObserver

   392 

   393        /**

   394      * From MDiagPluginPoolObserver.

   395      * This callback is used to inform the application about loading progress

   396      * of plugins.

   397      *

   398      * @param aCurrentPlugin The current plugin index in the loading progress.

   399      * @param aPluginCount The total number of plugins to load.

   400      @ @param aLoadedPluginUid The UID of the plugin that was just loaded.

   401      */

   402     virtual void LoadProgressL ( TUint aCurrentPlugin,

   403                                  TUint aPluginCount,

   404                                  const TUid& aLoadedPluginUid );

   405 

   406 

   407     /**

   408     * Notify client of plug-in loading completion

   409     *

   410     * @param aError     KErrNone - Success

   411     *                   KErrCorrupt  - One ore more plugin could not

   412     *                   be loaded. 

   413     *                   KErrNoMemory - Not enough memory.

   414     */

   415     virtual void LoadCompletedL( TInt aError );

   416 

   417 

   418 private: // Data

   419 

   420     /**

   421      * The application engine's current state.

   422      */

   423     TDevDiagAppEngineState iState;

   424 

   425     /**

   426      * The test execution results.

   427      * Own.

   428      */

   429     CDevDiagExecResults* iResults;

   430 

   431     /**

   432      * The current observer of the application engine.

   433      * Not own.

   434      */

   435     MDevDiagEngineObserver* iObserver;

   436 

   437     /**

   438      * The diagnostics engine.

   439      * Own.

   440      */

   441     CDiagEngine* iDiagEngine;

   442 

   443     /**

   444      * The session with the results database server.

   445      */

   446     RDiagResultsDatabase iResultsDatabase;

   447 

   448     

   449     /**

   450      * The plugin pool, which loads and owns plugins.

   451      * Own.

   452      */

   453     CDiagPluginPool* iPluginPool;

   454 

   455 

   456     /**

   457      * Holds the number of times suspend has been called.  In nested suspend /

   458      * resume scenarios, this is used to ensure we don't resume until we have

   459      * matched the number of suspends.

   460      */

   461     TInt iSuspendCounter;

   462     

   463      /**

   464      * A utility active object that is used to continue handling cancelling

   465      * execution, because we cannot use synchronous cancelling due to the

   466      * possibility of test plugins displaying the common "Cancel Execution"

   467      * dialog.

   468      * Own.

   469      */

   470     CIdle* iIdle;

   471     

   472     /**

   473     * Get Last results UIDs. Own.

   474     **/

   475     CArrayFixFlat<TUid>* iUids;

   476     

   477     /**

   478     * Buffered last results. Own.

   479     **/

   480     RPointerArray<CDiagResultsDatabaseItem> iLastResults;

   481 

   482     };

   483 

   484 #endif // DEVDIAGDENGINE_H