/*

* 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:  Manages Diagnostics Plug-in

*

*/

#ifndef DIAGPLUGINPOOLIMPL_H

#define DIAGPLUGINPOOLIMPL_H

// INCLUDES

#include <e32base.h>                    // CActive

#include <implementationinformation.h>  // RImplInfoPtrArray

// FORWARD DECLARATIONS

class MDiagPlugin;

class MDiagPluginPoolObserver;

class CDiagPluginConstructionParam;

class MDiagSuitePlugin;   

/**

*  Diagnostics Framework Plugin Pool Implementation Class

*

*  This class is used to load Diagnostics ECom plug-ins. It works with both

*  Suite Plug-in and Test Plug-in. Once loaded, it will manage the life

*  cycle of the plug-ins.

*

*  All loaded plug-ins will be destroyed when pool is deleted.

*

*  @since S60 v5.0

*/

NONSHARABLE_CLASS( CDiagPluginPoolImpl ) : public CActive

    {

public:

    /**

    * Two-phased constructors

    *

    * @param aObserver     Plug-in Pool observer.

    * @return New instance of CDiagPluginPool

    */

    static CDiagPluginPoolImpl* NewL( MDiagPluginPoolObserver& aObserver );

    static CDiagPluginPoolImpl* NewLC( MDiagPluginPoolObserver& aObserver );

    /**

    * Destructor

    *

    */

    virtual ~CDiagPluginPoolImpl();

public:     // new API

    /**

    * Loads all plug-ins. Progress is notified via MDiagPluginPoolObserver.

    * Leave codes:     KErrNone        - Success.

    *                  KErrNotFound    - No plugins

    *                  KErrAlreadyExists    - Plug-ins have already been loaded.

    */

    void LoadAsyncL();

    /**

    * Create an instance of a plug-in. It can be a test plug-in or suite plug-in.

    * If this is a suite, it will not have its children associated with it since

    * will require children to be loaded as well.

    *

    * Plug-ins created using this method is not part of plug-in pool. Therefore

    * client must manage the life cycle of the plug-in.

    * 

    * @param aUid - Implementation Uid of plug-in. 

    * @return Newly instantiated plug-in. Ownership is transferred to caller.

    */

    static MDiagPlugin* CreatePluginL( const TUid aUid );

    /**

    * Find Plug-in that matches given Uid.

    *

    * @param aUid      Uid of plug-in to search.

    * @param aPlugin   Reference to Plugin found. Engine owns this plug-in.

    *                  Client must not deallocate plug-in.

    * @return TInt     KErrNone        - Success.

    *                  KErrNotFound    - Not found.

    *                  KErrNotReady    - Plug-ins are not yet loaded.

    */

    TInt FindPlugin( TUid aUid, MDiagPlugin*& aPlugin ) const;

    /**

    * Find Plug-in that matches given service name.

    *

    * @param aServiceName  Service name of the plug-in. Name must match exactly.

    * @param aPlugin       Reference to Plugin found. Engine owns this plug-in.

    *                      Client must not deallocate plug-in.

    * @return TInt         KErrNone        - Success.

    *                      KErrNotFound    - Not found.

    *                      KErrNotReady    - Plug-ins are not yet loaded.

    */

    TInt FindPlugin( const TDesC& aServiceName, 

                             MDiagPlugin*& aPlugin ) const;      

private:    // internal types                                   

    typedef RPointerArray<CDiagPluginConstructionParam> RConstructionParamArray;        

private:    // private constructors

    /**

    * Construct a CDiagPluginPoolImpl object

    *

    * @param aObserver  The observer which listens to plug-in pool events

    */

    CDiagPluginPoolImpl( MDiagPluginPoolObserver& aObserver );

    /**

    * 2nd phase constructor

    *

    */    

    void ConstructL();  

private: // internal API

    /**

    * Obtain the list construction paramaters to construct a plug-in

    *    

    * @return Pointer to construction paramaters pointer array

    */    

    static RConstructionParamArray* GeneratePluginListL();

    /**

    * Generate parmaters to construct a plug-in given the ECOM implementation

    * info structure

    *

    * @param aInfo  Pointer to the implementation info structure

    * @return Pointer to newly generated construction params

    */

    static CDiagPluginConstructionParam* GenerateConstructionParamsLC(

            const CImplementationInformation* aInfo );

    /**

    * Create a plug-in from given construction data

    *

    * @param aInfo  Pointer to the implementation info structure

    * @return Pointer to the newly created plug-in

    */

    static MDiagPlugin* CreatePluginFromConstructionParamsL(

            const CDiagPluginConstructionParam* aParams );                       

    /**

    * Setup active object for next iteration of plug-in loading

    *    

    */

    void SetNextIteration();

    /**

    * Load the next plug-in in the list per built in iterator

    *    

    */

    void LoadNextPluginL();

    /**

    * Add plug-in to plug-in pool by inserting into the plug-in tree.

    * Plug-in ownership is transferred to the Plug-in Pool if it is

    * supported.  If the plug-in is not supported, it is deleted.

    *

    * @param aPlugin pointer to the new plug-in to be added

    * @return TUid UID of the plug-in to report back to the application.

    * Set to TUid::Null() if the plug-in was not added to the pool.

    */

    TUid AddPluginToPoolLD( MDiagPlugin* aPlugin );

    /**

    * Destroy implementation info regarding ECOM plug-ins

    *    

    */

    void DestroyConstructionParams();            

    /**

    * Call when a plug-in is loaded to add a newly loaded plug-in to a currently 

    * loaded suite (if available)

    * no ownership transfer

    *

    * @param aPluginSuite pointer to the new plug-in to be added

    */

    void AddNewPluginToSuiteL(MDiagPlugin* aPlugin);

    /**

    * Call when a suite is loaded to add any existing parentless plug-ins with

    * matching parent UID to suite

    * no ownership transfer

    *

    * @param aPluginSuite pointer to the new suite to be added

    */

    void AddPluginsToNewSuiteL(MDiagSuitePlugin* aPluginSuite);

    /**

    * Resets all member data and notifies observer that load is copmlete

    *

    * @param aErrorCode Plug-In load error

    * @return LoadCompletedL error, if any

    */

    TInt ResetAndNotify(TInt aErrorCode);

private: // From CActive

    /**

    * @see CActive::RunL

    */

    virtual void RunL();

    /**

    * @see CActive::DoCancel

    */

    virtual void DoCancel();

    /**

    * @see CActive::RunError

    */

    virtual TInt RunError( TInt aError );

private:    //  member data

    MDiagPluginPoolObserver& iObserver;

    // List of plug-ins that have been loaded

    RPointerArray<MDiagPlugin> iPlugins;        

    // Array of plug-in construction params        

    // owned

    RConstructionParamArray* iConstructionParamArray;

    // Indicates that all plug-ins have been loaded

    TBool iPluginsLoaded;

    // Indicates that plug-ins are currently loading

    TBool iPluginsLoading;

    // Index of current plug-in for plug-in load iteration

    TInt iCurrentPluginIndex;            

    // Holds error code for first error found in loading process

    TInt iErrorCode;

    // Total number of plug-ins found

    TInt iTotalPluginsFound;

    };

#endif // DIAGPLUGINPOOLIMPL_H

// End of File