/*

* Copyright (c) 2005-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:   Class definition for CGSPluginLoader

*

*/

#ifndef  GSPLUGINLOADER_H

#define  GSPLUGINLOADER_H

// INCLUDES

#include    <e32base.h>

#include    <ecom/implementationinformation.h>

// CONSTANTS

// Value for a to b comparison result when logically a == b.

const TInt KGSComparisonEqual     = 0;

// Value for a to b comparison result when logically a < b.

const TInt KGSComparisonBefore    = -1;

// Value for a to b comparison result when logically a > b.

const TInt KGSComparisonAfter     = 1;

// CLASS DEFINITIONS

class CGSPluginInterface;

class MGSPluginLoadObserver;

class CAknViewAppUi;

class REComSession;

class CAknColumnListBox;

class CAknInfoPopupNoteController;

class CGSBaseDocument;

class MGSWatchDog;

/**

* CGSPluginLoader. Mechanism used to load plugins asynchronously. Uses

* MGSPluginLoadObserver as a callback.

*

* @lib GSFramework.lib

* @since Series60_30.1

*/

class CGSPluginLoader : public CActive

    {

    public:  // Constructor and destructor

        /**

        * Two-phased constructor.

        *

        * @param aAppUi Pointer to application UI. Does not take ownership.

        */

        IMPORT_C static CGSPluginLoader* NewL( CAknViewAppUi* aAppUi );

        /**

        * Destructor

        */

        IMPORT_C ~CGSPluginLoader();

    private: // Internal construction

        /**

        * Default C++ contructor

        */

        CGSPluginLoader();

        /**

        * Symbian OS default constructor

        * @return void

        */

        void ConstructL( CAknViewAppUi* aAppUi );

    public: // API

        /**

        * Starts loading GS plug-ins asynchronously. Will call

        * MGSPluginLoadObserver::HandlePluginLoaded() each time a plug-in is

        * loaded and when all plugins are loaded.

        *

        * CGSPluginLoader transfers the ownership of each loaded plugin view to

        * CAknViewAppUi. It is client's responsibility to remove the views from

        * CAknViewAppUi and delete the plugins if necessary.

        *

        * @param aInterfaceUid Uid ofthe interfaces to be loaded.

        * @param aParentUid Uid of the parent. Only children of this parent

        *        will be loaded.

        * @param aPluginArray An array for the loaded GS plug-ins.

        *        CGSPluginLoader does not take the ownership of this array.

        */

        IMPORT_C void LoadAsyncL(

            TUid aInterfaceUid,

            TUid aParentUid,

            CArrayPtrFlat<CGSPluginInterface>* aPluginArray );

        /**

        * Load a specific plugin instance synchronously.

        *

        * @param aInterfaceUid Uid ofthe interfaces to be loaded.

        * @param aImplementationUid Uid of the implementation to load

        */

        CGSPluginInterface& LoadSyncL( TUid aInterfaceUid, TUid aImplementationUid );

        /**

        * Sets observer for this loader. Only one observer per loader in one

        * time is possible.

        */

        IMPORT_C void SetObserver(MGSPluginLoadObserver* aObserver);

        /**

        * Aborts asynchronous loading of the GS plug-ins.

        */

        IMPORT_C void AbortAsyncLoad();

        /**

        * Sorts the plugin array.

        *

        * Sorting criterias:

        *

        * 1. Order number if provider category is Internal.

        * 2. Provider category. Precedence as follows:

        *       1. KGSPluginProviderInternal

        *       2. EGSPluginProviderOEM

        *       3. EGSPluginProviderOperator

        *       4. EGSPluginProvider3rdParty

        * 3. Alphabetical

        *

        * @param aPlugins The array which will be sorted.

        */

        IMPORT_C void SortPluginsL( CArrayPtrFlat<CGSPluginInterface>* aPlugins );

        /**

        * Attempts to change CActive priority on next RunL cycle. Use this if

        * needed to change plugin loader priority. Normally when parent plugin

        * view is opened, it is advisable to increase loader priority to get

        * child plugins loaded faster.

        *

        * @param aPriority Desired priority.

        */

        IMPORT_C void RequestPriority( CActive::TPriority aPriority );

    private: // Internal methods

        /**

        * Starts loading next plugin.

        */

        void LoadNextPluginL();

        /**

        * Creates a plugin instance from given UID. Ownership is transferred.

        */

        CGSPluginInterface& CreatePluginInstanceL(

                const CImplementationInformation& aImpInfo );

        /**

        * Notifies MGSPluginLoadObserver.

        */

        void NotifyProgress();

        /**

        * Notifies MGSPluginLoadObserver.

        */

        void NotifyFinished();

        /**

        * Wait for the next round of CActive execution.

        */

        void CompleteOwnRequest();

        // Insertion function used by sorting:

        /**

        * Inserts plugin in the correct position in the array using sorting

        * criterias. Assumes aPlugins is ordered.

        *

        * @param aPlugin The plugin to be inserted.

        * @param aPlugins Array in which the plugin is inserted into the

        *        corresponding location.

        */

        void InsertPluginInOrderL(

            CGSPluginInterface* aPlugin,

            CArrayPtrFlat<CGSPluginInterface>* aPlugins );

        // Comparison functions:

        /**

        * Compares plugins according to comparison criterias.

        *

        * Note: GS internal comparison constants such as KGSComparisonEqual are

        * different from the ones outputted by this function. This is because

        * this function is also usable by RArray sort -functionality but BC

        * cannot be broken in GS.

        *

        * @return Negative value: If aFirst before aSecond.

        *                      0: If equal.

        *         Positive value: If aSecond before aFirst.

        */

        static TInt Compare( const CGSPluginInterface& aFirst,

                             const CGSPluginInterface& aSecond );

        /**

        * Precedence is as follows:

        * 1. KGSPluginProviderInternal

        * 2. EGSPluginProviderOEM

        * 3. EGSPluginProviderOperator

        * 4. EGSPluginProvider3rdParty

        *

        * @return   KGSComparisonEqual  = equal categories

        *           KGSComparisonBefore = aFirst is before aSecond

        *           KGSComparisonAfter  = aFirst is after aSecond

        */

        static TInt CompareCategory(

                const CGSPluginInterface& aFirst,

                const CGSPluginInterface& aSecond );

        /**

        *

        * @return   KGSComparisonEqual  = equal captions

        *           KGSComparisonBefore = aFirst is before aSecond

        *           KGSComparisonAfter  = aFirst is after aSecond

        */

        static TInt CompareCaption(

                const CGSPluginInterface& aFirst,

                const CGSPluginInterface& aSecond );

        /**

        *

        * @return   KGSComparisonEqual  = equal indexes

        *           KGSComparisonBefore = aFirst is before aSecond

        *           KGSComparisonAfter  = aFirst is after aSecond

        */

        static TInt CompareIndex(

                const CGSPluginInterface& aFirst,

                const CGSPluginInterface& aSecond );

    private: // Utility methods

        /**

        * Parses descriptor to UID.

        */

        static TInt ParseToUid( const TDesC8& aSource, TUid& aTarget );

        /**

        * Parsers plugin's order number

        */

        static TInt ParseOrderNumber( const TDesC8& aSource, TInt& aOrderNumber );

        /**

        * Print debug information.

        */

        static void PrintInfoDebugL( const CImplementationInformation& aInfo,

                                    TInt aIterator,

                                    TInt aPluginCount );

        /**

         * Print ordering debug data.

         */

        void CGSPluginLoader::PrintOrderTracesL(

                CArrayPtrFlat<CGSPluginInterface>* aPlugins );

        /**

         * Display loading error popup message.

         */

        void DisplayErrorPopupL( TInt aError,

                                 const CImplementationInformation* aInfo );

    private: // From CActive

        /**

        * See base class.

        */

        void RunL();

        /**

        * See base class.

        */

        TInt RunError( TInt aError );

        /**

        * See base class.

        */

        void DoCancel();

    private: // Data

        // Pluginloader goes through this array and loads the plugins into

        // iPluginArray if they fulfill the criterias.

        RImplInfoPtrArray iImplInfoArray;

        // Used as an iterator to maintain location in iImplInfoArray.

        TInt iImplInfoArrayIterator;

        // Array of loaded plugins.Plugins are owned by iAppUi. Only the array

        // pointers are owned by this class and therefore only reset array.

        CArrayPtrFlat<CGSPluginInterface>* iPluginArray;

        // UID for plugin parent.

        TUid iParentUid;

        // Pointer to app UI. Not owned.

        CAknViewAppUi* iAppUi;

        // Pointer to observer. Not owned.

        MGSPluginLoadObserver* iObserver;

        // Number of RunL calls.

        TInt iRunLDebugCount;

        // For debugging: shows a note in case of a crashing plugin

        CAknInfoPopupNoteController* iErrorPopup;

        // Reference to GS application owned watchdog. Not onwed.

        MGSWatchDog* iWatchDog;

        // Reference to document. Not owned.

        CGSBaseDocument* iDocument;

        // Desired oactive object priority for loading child plugins.

        CActive::TPriority iRequestedPriority;

    };

/**

* Interface for GSPluginLoader observer. MGSPluginLoadObserver gets

* notifications when plugins are loaded.

*

* @lib GSFramework.lib

* @since Series60_30.1

*/

class MGSPluginLoadObserver

    {

    public: // Enums

        enum KGSPluginLoaderStatus

            {

            // One plugin loaded successfully, continue to next.

            EGSSuccess,

            // Loading one plugin failed, contiue to next.

            EGSFail,

            // Client called AbortAsyncLoad(), finished loading.

            EGSAborted,

            // All plugins loaded successfully, finished loading.

            EGSFinished,

            // Severe error with loader, finished loading.

            EGSError

            };

    public: // New

        /**

        * CGSPluginLoader calls this function when each plug-in is loaded or

        * loading is finished..

        */

        IMPORT_C virtual void HandlePluginLoaded(

            KGSPluginLoaderStatus aStatus ) = 0;

    };

#endif // GSPLUGINLOADER_H

// End of File