1 /*

     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Class definition for CGSPluginLoader

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef  GSPLUGINLOADER_H

    21 #define  GSPLUGINLOADER_H

    22 

    23 // INCLUDES

    24 #include    <e32base.h>

    25 #include    <ecom/implementationinformation.h>

    26 

    27 // CONSTANTS

    28 

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

    30 const TInt KGSComparisonEqual     = 0;

    31 

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

    33 const TInt KGSComparisonBefore    = -1;

    34 

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

    36 const TInt KGSComparisonAfter     = 1;

    37 

    38 // CLASS DEFINITIONS

    39 class CGSPluginInterface;

    40 class MGSPluginLoadObserver;

    41 class CAknViewAppUi;

    42 class REComSession;

    43 class CAknColumnListBox;

    44 class CAknInfoPopupNoteController;

    45 class CGSBaseDocument;

    46 class MGSWatchDog;

    47 

    48 /**

    49 * CGSPluginLoader. Mechanism used to load plugins asynchronously. Uses

    50 * MGSPluginLoadObserver as a callback.

    51 *

    52 * @lib GSFramework.lib

    53 * @since Series60_30.1

    54 */

    55 class CGSPluginLoader : public CActive

    56     {

    57     public:  // Constructor and destructor

    58 

    59         /**

    60         * Two-phased constructor.

    61         *

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

    63         */

    64         IMPORT_C static CGSPluginLoader* NewL( CAknViewAppUi* aAppUi );

    65 

    66         /**

    67         * Destructor

    68         */

    69         IMPORT_C ~CGSPluginLoader();

    70 

    71     private: // Internal construction

    72 

    73         /**

    74         * Default C++ contructor

    75         */

    76         CGSPluginLoader();

    77 

    78         /**

    79         * Symbian OS default constructor

    80         * @return void

    81         */

    82         void ConstructL( CAknViewAppUi* aAppUi );

    83 

    84     public: // API

    85 

    86         /**

    87         * Starts loading GS plug-ins asynchronously. Will call

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

    89         * loaded and when all plugins are loaded.

    90         *

    91         * CGSPluginLoader transfers the ownership of each loaded plugin view to

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

    93         * CAknViewAppUi and delete the plugins if necessary.

    94         *

    95         * @param aInterfaceUid Uid ofthe interfaces to be loaded.

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

    97         *        will be loaded.

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

    99         *        CGSPluginLoader does not take the ownership of this array.

   100         */

   101         IMPORT_C void LoadAsyncL(

   102             TUid aInterfaceUid,

   103             TUid aParentUid,

   104             CArrayPtrFlat<CGSPluginInterface>* aPluginArray );

   105 

   106         /**

   107         * Load a specific plugin instance synchronously.

   108         *

   109         * @param aInterfaceUid Uid ofthe interfaces to be loaded.

   110         * @param aImplementationUid Uid of the implementation to load

   111         */

   112         CGSPluginInterface& LoadSyncL( TUid aInterfaceUid, TUid aImplementationUid );

   113 

   114         /**

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

   116         * time is possible.

   117         */

   118         IMPORT_C void SetObserver(MGSPluginLoadObserver* aObserver);

   119 

   120         /**

   121         * Aborts asynchronous loading of the GS plug-ins.

   122         */

   123         IMPORT_C void AbortAsyncLoad();

   124 

   125         /**

   126         * Sorts the plugin array.

   127         *

   128         * Sorting criterias:

   129         *

   130         * 1. Order number if provider category is Internal.

   131         * 2. Provider category. Precedence as follows:

   132         *       1. KGSPluginProviderInternal

   133         *       2. EGSPluginProviderOEM

   134         *       3. EGSPluginProviderOperator

   135         *       4. EGSPluginProvider3rdParty

   136         * 3. Alphabetical

   137         *

   138         * @param aPlugins The array which will be sorted.

   139         */

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

   141 

   142 

   143         /**

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

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

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

   147         * child plugins loaded faster.

   148         *

   149         * @param aPriority Desired priority.

   150         */

   151         IMPORT_C void RequestPriority( CActive::TPriority aPriority );

   152 

   153     private: // Internal methods

   154 

   155         /**

   156         * Starts loading next plugin.

   157         */

   158         void LoadNextPluginL();

   159 

   160         /**

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

   162         */

   163         CGSPluginInterface& CreatePluginInstanceL(

   164                 const CImplementationInformation& aImpInfo );

   165 

   166         /**

   167         * Notifies MGSPluginLoadObserver.

   168         */

   169         void NotifyProgress();

   170 

   171         /**

   172         * Notifies MGSPluginLoadObserver.

   173         */

   174         void NotifyFinished();

   175 

   176         /**

   177         * Wait for the next round of CActive execution.

   178         */

   179         void CompleteOwnRequest();

   180 

   181         // Insertion function used by sorting:

   182 

   183         /**

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

   185         * criterias. Assumes aPlugins is ordered.

   186         *

   187         * @param aPlugin The plugin to be inserted.

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

   189         *        corresponding location.

   190         */

   191         void InsertPluginInOrderL(

   192             CGSPluginInterface* aPlugin,

   193             CArrayPtrFlat<CGSPluginInterface>* aPlugins );

   194 

   195         // Comparison functions:

   196 

   197         /**

   198         * Compares plugins according to comparison criterias.

   199         *

   200         * Note: GS internal comparison constants such as KGSComparisonEqual are

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

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

   203         * cannot be broken in GS.

   204         *

   205         * @return Negative value: If aFirst before aSecond.

   206         *                      0: If equal.

   207         *         Positive value: If aSecond before aFirst.

   208         */

   209         static TInt Compare( const CGSPluginInterface& aFirst,

   210                              const CGSPluginInterface& aSecond );

   211 

   212         /**

   213         * Precedence is as follows:

   214         * 1. KGSPluginProviderInternal

   215         * 2. EGSPluginProviderOEM

   216         * 3. EGSPluginProviderOperator

   217         * 4. EGSPluginProvider3rdParty

   218         *

   219         * @return   KGSComparisonEqual  = equal categories

   220         *           KGSComparisonBefore = aFirst is before aSecond

   221         *           KGSComparisonAfter  = aFirst is after aSecond

   222         */

   223         static TInt CompareCategory(

   224                 const CGSPluginInterface& aFirst,

   225                 const CGSPluginInterface& aSecond );

   226         /**

   227         *

   228         * @return   KGSComparisonEqual  = equal captions

   229         *           KGSComparisonBefore = aFirst is before aSecond

   230         *           KGSComparisonAfter  = aFirst is after aSecond

   231         */

   232         static TInt CompareCaption(

   233                 const CGSPluginInterface& aFirst,

   234                 const CGSPluginInterface& aSecond );

   235         /**

   236         *

   237         * @return   KGSComparisonEqual  = equal indexes

   238         *           KGSComparisonBefore = aFirst is before aSecond

   239         *           KGSComparisonAfter  = aFirst is after aSecond

   240         */

   241         static TInt CompareIndex(

   242                 const CGSPluginInterface& aFirst,

   243                 const CGSPluginInterface& aSecond );

   244 

   245     private: // Utility methods

   246 

   247         /**

   248         * Parses descriptor to UID.

   249         */

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

   251 

   252         /**

   253         * Parsers plugin's order number

   254         */

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

   256 

   257         /**

   258         * Print debug information.

   259         */

   260         static void PrintInfoDebugL( const CImplementationInformation& aInfo,

   261                                     TInt aIterator,

   262                                     TInt aPluginCount );

   263         /**

   264          * Print ordering debug data.

   265          */

   266         void CGSPluginLoader::PrintOrderTracesL(

   267                 CArrayPtrFlat<CGSPluginInterface>* aPlugins );

   268 

   269         /**

   270          * Display loading error popup message.

   271          */

   272         void DisplayErrorPopupL( TInt aError,

   273                                  const CImplementationInformation* aInfo );

   274 

   275     private: // From CActive

   276 

   277         /**

   278         * See base class.

   279         */

   280         void RunL();

   281 

   282         /**

   283         * See base class.

   284         */

   285         TInt RunError( TInt aError );

   286 

   287         /**

   288         * See base class.

   289         */

   290         void DoCancel();

   291 

   292     private: // Data

   293 

   294 

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

   296         // iPluginArray if they fulfill the criterias.

   297         RImplInfoPtrArray iImplInfoArray;

   298 

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

   300         TInt iImplInfoArrayIterator;

   301 

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

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

   304         CArrayPtrFlat<CGSPluginInterface>* iPluginArray;

   305 

   306         // UID for plugin parent.

   307         TUid iParentUid;

   308 

   309         // Pointer to app UI. Not owned.

   310         CAknViewAppUi* iAppUi;

   311 

   312         // Pointer to observer. Not owned.

   313         MGSPluginLoadObserver* iObserver;

   314 

   315         // Number of RunL calls.

   316         TInt iRunLDebugCount;

   317 

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

   319         CAknInfoPopupNoteController* iErrorPopup;

   320 

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

   322         MGSWatchDog* iWatchDog;

   323 

   324         // Reference to document. Not owned.

   325         CGSBaseDocument* iDocument;

   326 

   327         // Desired oactive object priority for loading child plugins.

   328         CActive::TPriority iRequestedPriority;

   329     };

   330 

   331 

   332 /**

   333 * Interface for GSPluginLoader observer. MGSPluginLoadObserver gets

   334 * notifications when plugins are loaded.

   335 *

   336 * @lib GSFramework.lib

   337 * @since Series60_30.1

   338 */

   339 class MGSPluginLoadObserver

   340     {

   341     public: // Enums

   342         enum KGSPluginLoaderStatus

   343             {

   344             // One plugin loaded successfully, continue to next.

   345             EGSSuccess,

   346             // Loading one plugin failed, contiue to next.

   347             EGSFail,

   348             // Client called AbortAsyncLoad(), finished loading.

   349             EGSAborted,

   350             // All plugins loaded successfully, finished loading.

   351             EGSFinished,

   352             // Severe error with loader, finished loading.

   353             EGSError

   354             };

   355 

   356     public: // New

   357 

   358         /**

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

   360         * loading is finished..

   361         */

   362         IMPORT_C virtual void HandlePluginLoaded(

   363             KGSPluginLoaderStatus aStatus ) = 0;

   364     };

   365 

   366 

   367 #endif // GSPLUGINLOADER_H

   368 // End of File