--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/gsprofilesrv_plat/settings_framework_api/inc/GSPluginLoader.h Thu Dec 17 08:52:52 2009 +0200
@@ -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 <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