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


#ifndef GSPLUGINANDVIEWIDCACHE_H
#define GSPLUGINANDVIEWIDCACHE_H

// INCLUDES
#include <e32base.h>
#include <vwsdef.h>
#include <f32file.h>
#include <e32hashtab.h>

// CONSTANTS

// FORWARD DECLARATIONS
class CEikAppUi;
class CGSShimmedView;
class CGSPluginInterface;
class CGSPlaceholderView;

// CLASS DECLARATION

/**
*  CGSPluginAndViewIdCache application class.
*   - Creates/Loads a list of CGSShimmedViews from a cache file on GS start-up.
*   - Inserts CGSShimmedViews into view-framework view list.
*
*
*  Problem/rationale:
*  Launching GS plugin view outside GS application when GS application is not
*  already running may fail. This was caused by application inter working
*  combined with GS application's asynchronized plugin loading. High level
*  functionality for external view launching goes:
*   1. Application framework starts desired application
*   2. Application framework calls view-activation on the desired application view.
*   3. Desired view handles the activation call-back by drawing itself on
*      screen or whatever required.
*
*  Starting from phase 2, things can go wrong: when GS start-up call returns, GS
*  has not yet loaded all the plugins and the views owned by plugins are not
*  added yet to the view-framework view list. Calling non-existing view will
*  naturally fail.
*
*
*  Solution:
*  When GS start-up is called, populate view-frameworks view list with all the
*  views provided by GS application before function return. Kind of: This would
*  ruin GS's asynchronous plugin loading and would cause devastating freeze-up
*  times on GS start-up. Hence, on GS start-up we're not actually loading the
*  plugins nor the real views. We use light-weight dummy views
*  (aka CGSShimmedView) wich we add into view-framework view list immedieately
*  on start-up. If it happens so, that the view framework-decides to call view
*  activation on one of these dummy views, dummy view will load manually the
*  real plugin view and switch it with the dummy view. Dummy views are created
*  by CGSPluginAndViewIdCache on GS-application start-up.
*
*
*  Different use scenarios:
*
*  1. First GS-application start on a new device, create cache & save as file.
*
*  2. Launch GS-application second time. Always populate CCoeAppUi with
*     CGSShimmedView instances created from cache file (cache maps view uid
*     to ecom plugin implementation uid).
*     - When pluginloader loads plugin, it replaces dummy view (shim) with the real
*       view from the plugin. The shim is then destroyed.
*
*  3. GS plugin view is activated externally when GS is not running:
*     - Uses normal application framework to launch GS application.
*     - Same functionality as in scenario 2 but if shimmed view is requested
*       before actual view is created, load actual plugin manually and
*       synchronously.
*     - CGSPlaceholderView: View-FW will only switch between two different view
*       uids. This is why we need to switch between 3 different views.
*     -> Will result in 3x fold different view activation.
*     -  Used view activations are:
*        1. Shimmed view DoActivate for view uid <view_uid>.
*        2. Shimmed view calls Placeholder::DoActivate with a dummy "uid DEADBED".
*        3. Placeholder view calls actual plugin::DoActivate with actual view uid
*           <view_uid>.
*
*
*  NOTE: Requirements:
*  - Cache: GS has to be launched once successfully for the cache to work.
*    -> otherwise error if launching from external application.
*  - Views which need to be used externally (external view launch) must be
*    implemented as a GS-plugin. Those cannot be implemented as a local view.
*
*
*  @since Series60_3.1
*
*/
class CGSPluginAndViewIdCache : public CBase
    {
    public: // Constructor and destructor

        /**
        *
        */
        static CGSPluginAndViewIdCache* NewL( CEikAppUi& aAppUi );

        /**
        * Destructor.
        */
        ~CGSPluginAndViewIdCache();

    private:

        /**
        * C++ constructor
        */
        CGSPluginAndViewIdCache( CEikAppUi& aAppUi );

        /**
        * Second phase constructor
        */
        void ConstructL();

    public: // API - placeholder view related

        /**
        *
        */
        void ActivatePlaceholderViewL();

        /**
        *
        */
        const TVwsViewId& PriorToPlaceholderActiveViewId() const;

        /**
        *
        */
        void SetPriorToPlaceholderActiveViewId( const TVwsViewId& aViewId );

    public: // API - caching

        /**
        *
        */
        void RegisterViewAndImplementationAssociationL( TUid aViewId, TUid aImplementationUid );

        /**
        *
        */
        void RegisterViewAndImplementationAssociationL( TUid aViewId, TUid aImplementationUid, TBool aCreateShim );

        /**
        *
        */
        void PrepareToRegisterPluginInstanceLC( TUid aViewId );

        /**
        *
        */
        void RegisterPluginInstanceL( TUid aViewId, CGSPluginInterface& aPluginInstance );

        /**
        *
        */
        TBool IsPluginLoaded( TUid aViewId ) const;

        /**
        *
        */
        CGSPluginInterface* PluginInstance( TUid aViewId ) const;

        /**
        *
        */
        TUid PluginImplementationUidForView( TUid aViewId ) const;

        /**
        *
        */
        void PrepareForUIDestruction();

        /**
        *
        */
        void HandleShimDestruction( TUid aViewId );

    private: // Internal methods
        void DestroyShims();
        void RestoreL();
        void StoreL();
        void GetCacheFileNameL( TDes& aFileName );
        void GetCachePathL( TDes& aPath );
        static void ReRegisterShimWithUi( TAny* aSelf );

    private: // Hash function support
        static TUint32 HashFunction( const TUid& aViewId );
        static TBool HashIdentityRelation( const TUid& aLeft, const TUid& aRight );

    private: // Internal object

        struct TCacheEntry
            {
            TUid iImplementationUid;
            CGSShimmedView* iShim;
            CGSPluginInterface* iLoadedPluginImplementation;
            };

    private: // Data

        // UI - not owned
        CEikAppUi& iAppUi;

        // File server session - owned
        RFs iFsSession;

        // Cache table - owned
        RHashMap< TUid /* KEY = view id */, TCacheEntry /* VALUE */ > iLookupTable;

        // Placeholder view - owned
        CGSPlaceholderView* iPlaceholderView;

        // Transient variable used during plugin registration preparation.
        TUid iTransientCleanupViewUid;
    };


#endif // GSBASEDOCUMENT_H
// End of File