/*

* 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:  Observer interface to use with CDiagEngine

*

*/

#ifndef DIAGENGINEOBSERVER_H

#define DIAGENGINEOBSERVER_H

// SYSTEM INCLUDES

#include <e32def.h>                 // TUint

#include <DiagCommonDialog.h>       // TDiagCommonDialog

#include <DiagAppCommand.h>         // TDiagAppCommand

// FORWARD DECLARATION

class CDiagResultsDatabaseItem;

class CAknDialog;

/**

*  Diagnostics Framework Engine Observer

*

*  This interface is called by CDiagEngine to notify its client

*  of progress of requests made to engine.

*

* @since S60 v5.0

*/

class MDiagEngineObserver

    {

public: // Public Data types

    enum TSuspendReason

        {

        ESuspendByClient = 0,

        ESuspendByPhoneCall

        };

    enum TResumeReason

        {

        EResumedByClient = 0,

        EAutoResumedByCallHangup

        };

public: // Public interface

    /**

    * Notify client of test execution begin. Clients can get testplan using

    * CDiagEngine::ExecutionPlanL. 

    */

    virtual void TestExecutionBeginL() = 0;

    /**

    * Notify client of test execution progress.

    *

    * @param aCurrentItemStep       - Progress in current entry.

    * @param aCurrentItemTotalSteps - Total steps to execute in current entry.

    */

    virtual void TestExecutionProgressL( TUint aCurrentItemStep,

                                         TUint aCurrentItemTotalSteps ) = 0;

    /**

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

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

    *

    * @param aError  - KErrNone - Success.

    *   KErrNoMemory - Out of memory.

    *   KErrCancel   - Cancelled due to ExecutionStopL()

    *

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

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

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

    */

    virtual void TestExecutionPluginExecutedL( TInt aError,

                                               CDiagResultsDatabaseItem* aResult ) = 0;

    /**

    * Notify client of execution suspend.

    *

    * @param aSuspendReason - Why execution is suspended.

    */

    virtual void TestExecutionSuspendedL( TSuspendReason aSuspendReason ) = 0;

    /**

    * Notify client of execution resume.

    *

    * @param aResumeReason - Why execution is being resumed

    */

    virtual void TestExecutionResumedL( TResumeReason aResumeReason ) = 0;

    /**

    * Notify client of engine stopping.

    *

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

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

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

    *

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

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

    * TestExecutionBeginL(). 

    *

    * @param aError - Reason for engine stopping. 

    *   a) KErrNone - All tests are successfully completed.

    *   b) KErrCancel - ExecutionStopL is called with ECancelAll. 

    *       Test session cannot be resumed later.

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

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

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

    */

    virtual void TestExecutionCompletedL( TInt aError ) = 0;

    /**

    * Create a common Dialog.

    * Application should create an instance of requested dialog.

    * For available dialog types, @see DiagCommonDialog.h

    * 

    * @param aDialogType - Type of dialog to create.

    * @param aData - 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;

    /**

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

    * MDiagEngineCommon::ExecuteAppCommandL(). 

    * @see MDiagEngineCommon::ExecuteAppCommandL()

    * @see TDiagAppCommand

    */

    virtual void ExecuteAppCommandL( TDiagAppCommand aCommand, 

                                     TAny* aParam1,

                                     TAny* aParam2 ) = 0;

    };

#endif // DIAGENGINEOBSERVER_H

// End of File