1 /*

     2 * Copyright (c) 2002-2006 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:  Plugin and view id caching support

    15 *

    16 */

    17 

    18 

    19 #ifndef GSPLUGINANDVIEWIDCACHE_H

    20 #define GSPLUGINANDVIEWIDCACHE_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <vwsdef.h>

    25 #include <f32file.h>

    26 #include <e32hashtab.h>

    27 

    28 // CONSTANTS

    29 

    30 // FORWARD DECLARATIONS

    31 class CEikAppUi;

    32 class CGSShimmedView;

    33 class CGSPluginInterface;

    34 class CGSPlaceholderView;

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39 *  CGSPluginAndViewIdCache application class.

    40 *   - Creates/Loads a list of CGSShimmedViews from a cache file on GS start-up.

    41 *   - Inserts CGSShimmedViews into view-framework view list.

    42 *

    43 *

    44 *  Problem/rationale:

    45 *  Launching GS plugin view outside GS application when GS application is not

    46 *  already running may fail. This was caused by application inter working

    47 *  combined with GS application's asynchronized plugin loading. High level

    48 *  functionality for external view launching goes:

    49 *   1. Application framework starts desired application

    50 *   2. Application framework calls view-activation on the desired application view.

    51 *   3. Desired view handles the activation call-back by drawing itself on

    52 *      screen or whatever required.

    53 *

    54 *  Starting from phase 2, things can go wrong: when GS start-up call returns, GS

    55 *  has not yet loaded all the plugins and the views owned by plugins are not

    56 *  added yet to the view-framework view list. Calling non-existing view will

    57 *  naturally fail.

    58 *

    59 *

    60 *  Solution:

    61 *  When GS start-up is called, populate view-frameworks view list with all the

    62 *  views provided by GS application before function return. Kind of: This would

    63 *  ruin GS's asynchronous plugin loading and would cause devastating freeze-up

    64 *  times on GS start-up. Hence, on GS start-up we're not actually loading the

    65 *  plugins nor the real views. We use light-weight dummy views

    66 *  (aka CGSShimmedView) wich we add into view-framework view list immedieately

    67 *  on start-up. If it happens so, that the view framework-decides to call view

    68 *  activation on one of these dummy views, dummy view will load manually the

    69 *  real plugin view and switch it with the dummy view. Dummy views are created

    70 *  by CGSPluginAndViewIdCache on GS-application start-up.

    71 *

    72 *

    73 *  Different use scenarios:

    74 *

    75 *  1. First GS-application start on a new device, create cache & save as file.

    76 *

    77 *  2. Launch GS-application second time. Always populate CCoeAppUi with

    78 *     CGSShimmedView instances created from cache file (cache maps view uid

    79 *     to ecom plugin implementation uid).

    80 *     - When pluginloader loads plugin, it replaces dummy view (shim) with the real

    81 *       view from the plugin. The shim is then destroyed.

    82 *

    83 *  3. GS plugin view is activated externally when GS is not running:

    84 *     - Uses normal application framework to launch GS application.

    85 *     - Same functionality as in scenario 2 but if shimmed view is requested

    86 *       before actual view is created, load actual plugin manually and

    87 *       synchronously.

    88 *     - CGSPlaceholderView: View-FW will only switch between two different view

    89 *       uids. This is why we need to switch between 3 different views.

    90 *     -> Will result in 3x fold different view activation.

    91 *     -  Used view activations are:

    92 *        1. Shimmed view DoActivate for view uid <view_uid>.

    93 *        2. Shimmed view calls Placeholder::DoActivate with a dummy "uid DEADBED".

    94 *        3. Placeholder view calls actual plugin::DoActivate with actual view uid

    95 *           <view_uid>.

    96 *

    97 *

    98 *  NOTE: Requirements:

    99 *  - Cache: GS has to be launched once successfully for the cache to work.

   100 *    -> otherwise error if launching from external application.

   101 *  - Views which need to be used externally (external view launch) must be

   102 *    implemented as a GS-plugin. Those cannot be implemented as a local view.

   103 *

   104 *

   105 *  @since Series60_3.1

   106 *

   107 */

   108 class CGSPluginAndViewIdCache : public CBase

   109     {

   110     public: // Constructor and destructor

   111 

   112         /**

   113         *

   114         */

   115         static CGSPluginAndViewIdCache* NewL( CEikAppUi& aAppUi );

   116 

   117         /**

   118         * Destructor.

   119         */

   120         ~CGSPluginAndViewIdCache();

   121 

   122     private:

   123 

   124         /**

   125         * C++ constructor

   126         */

   127         CGSPluginAndViewIdCache( CEikAppUi& aAppUi );

   128 

   129         /**

   130         * Second phase constructor

   131         */

   132         void ConstructL();

   133 

   134     public: // API - placeholder view related

   135 

   136         /**

   137         *

   138         */

   139         void ActivatePlaceholderViewL();

   140 

   141         /**

   142         *

   143         */

   144         const TVwsViewId& PriorToPlaceholderActiveViewId() const;

   145 

   146         /**

   147         *

   148         */

   149         void SetPriorToPlaceholderActiveViewId( const TVwsViewId& aViewId );

   150 

   151     public: // API - caching

   152 

   153         /**

   154         *

   155         */

   156         void RegisterViewAndImplementationAssociationL( TUid aViewId, TUid aImplementationUid );

   157 

   158         /**

   159         *

   160         */

   161         void RegisterViewAndImplementationAssociationL( TUid aViewId, TUid aImplementationUid, TBool aCreateShim );

   162 

   163         /**

   164         *

   165         */

   166         void PrepareToRegisterPluginInstanceLC( TUid aViewId );

   167 

   168         /**

   169         *

   170         */

   171         void RegisterPluginInstanceL( TUid aViewId, CGSPluginInterface& aPluginInstance );

   172 

   173         /**

   174         *

   175         */

   176         TBool IsPluginLoaded( TUid aViewId ) const;

   177 

   178         /**

   179         *

   180         */

   181         CGSPluginInterface* PluginInstance( TUid aViewId ) const;

   182 

   183         /**

   184         *

   185         */

   186         TUid PluginImplementationUidForView( TUid aViewId ) const;

   187 

   188         /**

   189         *

   190         */

   191         void PrepareForUIDestruction();

   192 

   193         /**

   194         *

   195         */

   196         void HandleShimDestruction( TUid aViewId );

   197 

   198     private: // Internal methods

   199         void DestroyShims();

   200         void RestoreL();

   201         void StoreL();

   202         void GetCacheFileNameL( TDes& aFileName );

   203         void GetCachePathL( TDes& aPath );

   204         static void ReRegisterShimWithUi( TAny* aSelf );

   205 

   206     private: // Hash function support

   207         static TUint32 HashFunction( const TUid& aViewId );

   208         static TBool HashIdentityRelation( const TUid& aLeft, const TUid& aRight );

   209 

   210     private: // Internal object

   211 

   212         struct TCacheEntry

   213             {

   214             TUid iImplementationUid;

   215             CGSShimmedView* iShim;

   216             CGSPluginInterface* iLoadedPluginImplementation;

   217             };

   218 

   219     private: // Data

   220 

   221         // UI - not owned

   222         CEikAppUi& iAppUi;

   223 

   224         // File server session - ref

   225         RFs& iFsSession;

   226 

   227         // Cache table - owned

   228         RHashMap< TUid /* KEY = view id */, TCacheEntry /* VALUE */ > iLookupTable;

   229 

   230         // Placeholder view - owned

   231         CGSPlaceholderView* iPlaceholderView;

   232 

   233         // Transient variable used during plugin registration preparation.

   234         TUid iTransientCleanupViewUid;

   235     };

   236 

   237 

   238 #endif // GSBASEDOCUMENT_H

   239 // End of File