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

    15 *

    16 */

    17 

    18 

    19 #ifndef DIAGENGINECOMMON_H

    20 #define DIAGENGINECOMMON_H

    21 

    22 // SYSTEM INCLUDES

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

    24 #include <DiagCommonDialog.h>           // TDiagCommonDialog

    25 #include <DiagAppCommand.h>             // TDiagAppCommand

    26 #include <DiagEngineWatchdogTypes.h>    // TDiagEngineWatchdogTypes

    27 

    28 // FORWARD DECLARATION

    29 class MDiagPluginExecPlan;

    30 class MDiagPlugin;

    31 class CAknViewAppUi;

    32 class RDiagResultsDatabaseRecord;

    33 class CDiagPluginPool;

    34 class CAknDialog;

    35 

    36 /**

    37 *  Diagnostics Framework Engine Common Interface

    38 *

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

    40 *  any other clients of CDiagEngine.

    41 *

    42 *  @since S60 v5.0

    43 */

    44 class MDiagEngineCommon

    45     {

    46 public: // Data Structures

    47     

    48     /** 

    49     * Possible cancellation mode.

    50     */

    51     enum TCancelMode

    52         {

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

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

    55         };

    56 

    57     /**

    58     *  Text List based config options

    59     */

    60     enum TConfigListType

    61         { 

    62         /**

    63         * EConfigListCallIngore - List of phone numbers to ignore. 

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

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

    66         *   the engine execution when new call is made.

    67         */

    68         EConfigListCallIngore = 0

    69         };

    70 

    71 public: // public methods

    72 

    73     /**

    74     * Returns current execution plan.

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

    76     *

    77     * @return Reference to current execution plan.

    78     */

    79     virtual const MDiagPluginExecPlan& ExecutionPlanL() const = 0;

    80 

    81     /**

    82     * Stop current execution of tests.

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

    84     *

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

    86     *                      ECancelAll  - Cancels current test and skips the rest of

    87     *                                  execution.

    88     */

    89     virtual void ExecutionStopL( TCancelMode aCancelMode ) = 0;

    90 

    91     /**

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

    93     * timer value for currently executing plug-in.

    94     */

    95     virtual void ResetWatchdog() = 0;

    96 

    97     /**

    98     * Resets test execution watchdog timer.  

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

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

   101     *   ResetWachdogL() or TestProgressL() is called.

   102     *

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

   104     *   @see TDiagEngineWatchdogTypes

   105     */

   106     virtual void ResetWatchdog( TDiagEngineWatchdogTypes aWatchdogType ) = 0;

   107 

   108     /**

   109     * Resets test execution watchdog timer.  

   110     *   Engine will allow specified amount of time. 

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

   112     *   ResetWachdogL() or TestProgressL() is called.

   113     * 

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

   115     */

   116     virtual void ResetWatchdog( TTimeIntervalMicroSeconds32 aExpectedTimeToComplete ) = 0;

   117 

   118     /**

   119     * Get App Ui reference that launched Diagnostics Engine.

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

   121     * 

   122     * @return Reference to CAknViewAppUi

   123     */

   124     virtual CAknViewAppUi& ViewAppUi() = 0;

   125 

   126     /**

   127     * Get App Ui reference that launched Diagnostics Engine.

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

   129     * 

   130     * @return Reference to CAknViewAppUi

   131     */

   132     virtual const CAknViewAppUi& ViewAppUi() const = 0;

   133 

   134     /**

   135     * Get Database Subsession for record open for writing.

   136     * 

   137     * @return Reference to RDiagResultsDatabaseRecord

   138     */

   139     virtual RDiagResultsDatabaseRecord& DbRecord() = 0;

   140 

   141     /**

   142     * Get Database Subsession for record open for writing.

   143     * 

   144     * @return Reference to RDiagResultsDatabaseRecord

   145     */

   146     virtual const RDiagResultsDatabaseRecord& DbRecord() const = 0;

   147 

   148     /**

   149     * Get reference to Plugin Pool

   150     * 

   151     * @return Reference to CDiagPluginPool

   152     */

   153     virtual CDiagPluginPool& PluginPool() = 0;

   154 

   155     /**

   156     * Get reference to Plugin Pool

   157     * 

   158     * @return Reference to CDiagPluginPool

   159     */

   160     virtual const CDiagPluginPool& PluginPool() const = 0;

   161 

   162     /**

   163     * Add a text to configuraiton list option. 

   164     * 

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

   166     *   @see TConfigListType

   167     * @param aText - text to add to the list

   168     */

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

   170 

   171     /**

   172     * Remove a text from configuration list.

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

   174     * leave with KErrNotFound.

   175     * 

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

   177     *   @see TConfigListType

   178     * @param aText - text for the option

   179     */

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

   181 

   182     /**

   183     * Create a common dialog.

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

   185     * For available dialog types, @see DiagCommonDialog.h

   186     * 

   187     * @param aDialogType - Type of dialog to create.

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

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

   190     */

   191     virtual CAknDialog* CreateCommonDialogLC( TDiagCommonDialog aDialogType,

   192                                               TAny* aInitData ) = 0;

   193 

   194     /**

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

   196     *   a ) TestProgressL() is called.

   197     *   b ) ResetWatchdogL() is called.

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

   199     */

   200     virtual void StopWatchdogTemporarily() = 0;

   201 

   202     /**

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

   204     *   @return TBool - ETrue if dependency is disabled.

   205     *                   EFalse if depencenty is enabled.

   206     */

   207     virtual TBool IsDependencyDisabled() const = 0;

   208 

   209     /**

   210     * Get custom parameter passed during engine creation.

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

   212     */

   213     virtual TAny* CustomParam() const = 0;

   214 

   215     /**

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

   217     * request certain behavior from application. For more information about

   218     * types of commands possible, @see TDiagAppCommand.

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

   220     * leave with error code KErrNotSupported.

   221     *

   222     * Memory Ownership of Parameters.

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

   224     *   because if a particular operation is not supported, application 

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

   226     *   

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

   228     *   ExecuteAppCommandL() leaves KErrNotSupported and deallocate

   229     *   parameters.

   230     *

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

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

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

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

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

   236     *   

   237     */

   238     virtual void ExecuteAppCommandL( TDiagAppCommand aCommand, 

   239                                      TAny* aParam1,

   240                                      TAny* aParam2 ) = 0;

   241     };

   242 

   243 

   244 #endif // DIAGENGINECOMMON_H

   245 

   246 // End of File

   247