/*

* 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:  Abstract class that represents a diagnostics plug-in

*

*/

#ifndef DIAGPLUGIN_H

#define DIAGPLUGIN_H

// INCLUDES

#include <badesca.h>            // CPtrCArray . Needed since this is typedef.

//Forward declarations

class CGulIcon;

class MDiagEngineCommon;

// Constants for plugin interfaces 

const TUid KDiagPluginInterfaceUid = { 0x2000AFEB };

// UID of top most root suite uid.  All plug-ins are descendant of this suite.

const TUid KDiagRootSuiteUid = { 0x00000000 };

/**

* Abstract class that repsesents a diagnostics plug-in.

*

* @since S60 v5.0

**/

class MDiagPlugin

    {

public: //data structures

    /**

    * Indicates is the plug-in a suite or a test plug-in

    **/

    enum TPluginType

        {

        ETypeTestPlugin,

        ETypeSuitePlugin

        };

    /**

    * Layout type of name being requested.

    */

    enum TNameLayoutType

        {

        ENameLayoutListSingle,              // list_single_graphic_heading_pane_t1_cp2

        ENameLayoutPopupNoteWaitWindow,     // popup_note_wait_window

        ENameLayoutListLargeGraphic,        // list_single_large_graphic_pane_t1

        ENameLayoutHeadingPane,             // heading_pane_t1

        ENameLayoutPopupInfoPane,           // popup_info_list_pane_t1

        ENameLayoutTitlePane,               // title_pane_t2/opt12

        ENameLayoutListSingleGraphic,       // list_single_graphic_pane_t1

        ENameLayoutListDoubleGraphic        // list_double_graphic_pane_t1

        };

public: // public methods

    /**

    * Virtual destructor. This ensures that when the interface is deleted,

    * compiler will look up virtual table to find correct destructor.

    */

    virtual ~MDiagPlugin() {}

    /**

    * Method for getting the name of the plugin. Name returned should be based

    * on the layout requested, and it should fit within the layout.

    *

    * @param aLayoutType - Layout where text will be displayed in. @see TNameLayoutType

    * @return Localized name of the plug-in. Ownership is transferred to caller.

    */

    virtual HBufC* GetPluginNameL( TNameLayoutType aLayoutType ) const = 0;

    /**

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

    * Service name is defined in the ECOM resource file, thus, it is not localized.

    *

    * @return The name of the service.

    **/

    virtual const TDesC& ServiceLogicalName() const = 0;

    /**

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

    *

    * @param aArray An array of logical names.

    * @see ServiceLogicalName.

    **/

    virtual void GetLogicalDependenciesL( CPtrCArray& aArray ) const = 0;

    /**

    * Return the type of the plug-in. 

    *

    * @return The type.

    * @see TPluginType.

    **/

    virtual TPluginType Type() const = 0;

    /**

    * Create an icon that represents the plug-in.

    *

    * @return An icon. 

    **/

    virtual CGulIcon* CreateIconL() const = 0;

    /** Method for checking, if plugin should be visible.

    * (for example shown in listbox).

    * Overwrite this function to show or hide your plugin dynamically.

    *

    * @return ETrue if plugin should be visible, EFalse otherwise.

    */

    virtual TBool IsVisible() const = 0;

    /** Method for checking, if plugin is supported.

    * Overwrite this function to enable or disable your plugin dynamically.

    * If EFalse, plug-in will not be loaded by plugin pool.

    *

    * @return ETrue if plugin is supported, EFalse otherwise.

    */

    virtual TBool IsSupported() const = 0;

    /**

    * Get localised description of the test. Description should be used to explain 

    * the test for the user. It can contain comments that this service needs for 

    * example access point and it creates costs or that the duration might be long.

    *

    * @return Allocated buffer containing localized description of the plugin.

    **/

    virtual HBufC* GetDescriptionL() const = 0;

    /**

    * Get UID of this plug-in.

    *

    * @return the UID.

    **/

    virtual TUid Uid() const = 0;

    /**

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

    *

    * @return TUint order number.

    **/

    virtual TUint Order() const = 0;

    /**

    * Get UID of the parent.

    *

    * @return The parent UID.

    **/

    virtual TUid ParentUid() const = 0;

    /**

    * Set ECom Destructor ID Key.

    *

    * @param aDtorIdKey Uid returned by REComSession::CreateImplementationL()

    **/

    virtual void SetDtorIdKey( TUid aDtorIdKey ) = 0;

    /**

    * 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. Ownership is not transferred since

    *   client does not always know the type of pointer.

    **/

    virtual void TestSessionBeginL( MDiagEngineCommon& aEngine,

                                    TBool aSkipDependencyCheck,

                                    TAny* aCustomParams ) = 0;

    /**

    * 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. Ownership is not transferred since

    *   client does not always know the type of pointer.

    **/

    virtual void TestSessionEndL( MDiagEngineCommon& aEngine,

                                  TBool aSkipDependencyCheck,

                                  TAny* aCustomParams ) = 0;

    /**

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

    *

    * @param aUid Unique identifier of the operation.

    * @param aParam Custom parameter. 

    * @return TAny pointer. Custom data.

    *   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. Ownership is not transferred since

    *   client does not always know the type of pointer.

    **/

    virtual TAny* CustomOperationL( TUid aUid, TAny* aParam ) = 0;

    /**

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

    *

    * @param aParam Custom parameter.

    * @return TAny pointer. Custom data. 

    *   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. Ownership is not transferred since

    *   client does not always know the type of pointer.

    **/

    virtual TAny* GetCustomL( TUid aUid, TAny* aParam ) = 0;

    };

#endif // DIAGPLUGIN_H

// End of File