diff -r 8ee96d21d9bf -r 7e0eff37aedb gsprofilesrv_plat/settings_framework_api/inc/GSPluginLoader.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gsprofilesrv_plat/settings_framework_api/inc/GSPluginLoader.h Wed Sep 01 12:20:44 2010 +0100 @@ -0,0 +1,368 @@ +/* +* 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 +#include + +// 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* 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* 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* 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* 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* 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