homescreenpluginsrv/hspsmanager/inc/hspsclientrequesthandler.h
author Dremov Kirill (Nokia-D-MSW/Tampere) <kirill.dremov@nokia.com>
Tue, 27 Apr 2010 16:57:49 +0300
branchRCL_3
changeset 16 b276298d5729
parent 0 79c6a41cd166
permissions -rw-r--r--
Revision: 201015 Kit: 201017

/*
* Copyright (c) 2008 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:  ChspsClientRequestHandler is a server-side implementation for
*                retrieving configurations from the HSPS's Definition Repository.
*                Configurations are binary presentations of a manifest, XML and
*                resource files - actually, instances of the hspsODT class.
*                Due to perfomance aspects, instead of the binary files, a file 
*                handle is returned over the IPC channel, and on client side, 
*                the handle is then used for internalizing the requested 
*                configuration.
*                  
*
*/


#ifndef __hspsCLIENTREQUESTHANDLER_H__
#define __hspsCLIENTREQUESTHANDLER_H__

#include <e32base.h>

#include "hspscenreplistener.h"
#include "hspsreqnotifparam.h"

class MhspsClientRequestService;
class ChspsSecurityEnforcer;
class CRepository;
class ChspsODT;
class ChspsFileAccess;
class ChspsResource;
class ChspsThemeServer;
class ChspsResult;
class ChspsRequestNotifcationParams;

#ifdef HSPS_LOG_ACTIVE
class ChspsLogBus;
#endif

/**
* 
*  Class ChspsClientRequestHandler. ChspsClientRequestHandler performs all Xuikon Client Request Service 
*  related functionality of Xuikon Theme Mangement Service APIs.
*  Xuikon Client Request Service API is intended to serve Rendering Engines with Application Themes 
*  and their associated resources. ChspsClientRequestHandler will provide access to 
*  Xuikon's Application Theme database maintained by Xuikon Definition Repository.
*  Definition Repository maintains Application Themes in ChspsODT-objects. 
*  Themes can have resources like bitmaps etc. Resources can be accessed through this API also. 
*  Every individual resource has corresponding ChspsResource-object. hspsResource-object is delivered 
*  to the client side in a resource list which is associated to the theme. 
*  Resource list is included in ODT as well as DOM-document which contains UI-definition. 
*  There can be only one theme activated for a specific application at one time. 
*  The information of activation of themes is stored in Symbian Central Repository -object. 
*  The Central Repository is requested on every theme request that Rendering Engine commences. 
*
*  Class inheritance:
*  ==================
*  ChspsClientRequestHandler derives CTimer for active timer functionality. It implements 
*  MhspsClientRequestService-interface for Xuikon Client Request Service API functionality,
*  and MhspsDefinitionRepositoryObserver for listening to the definition repository events.  
*
*  Functionality:
*  ==============
*  To initiate theme usage, Rendering Engine must call hspsGetODT().
*  
*  hspsGetODT() returns one of the following codes:
*  - EhspsGetODTSuccess. Theme was received successfully. Client can start its rendering.
*  - EhspsGetODTFailed. Theme was not received. Check Additional Return Code in hspsResult-object
*   for the exact reason. Theme load can fail for e.g. for missing rights.
*  - EhspsGetODTLowMemoryStrategy. Possible memory low to create chunk. Client should
*                                implement some low memory strategy. In version 3.1, 
*                                the low-memory stategy is use direct file handle in
*                                accessing ODT. System can be configured to use
*                                low-memory strategy only.
*
*  After receiving the theme, Rendering Engine may subscribe the theme related events. 
*  These events may concern the changes of the theme status (meaning that some other theme is 
*  activated), or that the theme is updated. In both cases, client should reload the theme and do 
*  the rendering again. To act as a subscriber of these events, client must implement the interface
*  MhspsClientRequestServiceObserver. Subscription is applied by calling hspsGetODTUpdate(). 
*  This function returns immediately one of the following codes:
*  - EhspsGetODTUpdateSuccess - The subscription of the theme updates and/or status changes was 
                              successful. The cient must start observe the server events.
*  - EhspsGetODTUpdateFailed  - The subscription of the theme updates and status changes was failed.
*
*  Once success-response was received, the observation of the Client Request Service events can 
*  return one of the following codes:
*
*  - EhspsGetODTUpdateStatus - Theme status was changed. Client must reset rendering and request theme
*                            again. 
*  - EhspsGetODTUpdateHot    - Theme was updated. Client should reload the theme and then do the 
*                            rendering again. 
*  
*  Rendering Engine can get information of the theme resources through the ChspsResource-objects 
*  delivered on the resource list in ODT. When ChspsODT-object's DOM-document has a reference to 
*  some resource-URL, the access method to the resource can be found in ChspsResource-object. 
*  When access-method is resolved, client should call hspsAccessResourceFile() function with resource
*  file path and empty RFile-handle. In successful cases, valid file handle to the associated 
*  resource file is returned.
*  This functionality is arranged by the means of Symbian 9.0 EKA2 Kernel's support for Platform 
*  Security Concept. The return code can be one of the following:
*  - EhspsAccessResourceFileSuccess - request to get access to a theme resource file was successful.
*  - EhspsAccessResourceFileFailed  - request to get access to a theme resource file was unsuccessful
*    possible in due to a security fault.
* 
*  Client Request Service functions may also return one of the following codes:
*  - EhspsServiceRequestSheduled, or
*  - EhspsServiceRequestError.
*
*  For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.
*
*  @ingroup group_hspsserversession
*  @lib hspsThemeServer.exe
*  @since S60 5.0
*/       
class ChspsClientRequestHandler : public CBase,
                                public MhspsClientRequestService,
                                public MhspsDefinitionRepositoryObserver,
                                public MhspsCenRepObserver
                                               
    {
    public: // Constructors and destructor
        /**
        * NewL
        *
        * @since S60 5.0
        */
        static ChspsClientRequestHandler* NewL( ChspsThemeServer& aThemeServer );
        /**
        * NewLC
        *
        * @since S60 5.0
        */
        static ChspsClientRequestHandler* NewLC( ChspsThemeServer& aThemeServer );
             
        /**
        * ~ChspsClientRequestHandler
        * Destructor.
        */
        ~ChspsClientRequestHandler();
      
    public: // New functions
        /**
        * ServiceGetOdtL
        *
        * @since S60 5.0
        * @param aMessage contains the data received from the client
        */
        void ServiceGetOdtL(const RMessage2& aMessage);             
        /**
        * ServiceGetOdtUpdateL
        *
        * @since S60 5.0
        * @param aMessage contains the data received from the client
        */
        void ServiceGetOdtUpdateL(const RMessage2& aMessage);
        /**
        * ServiceAccessResourceFileL
        *
        * @since S60 5.0
        * @param aMessage contains the data received from the client
        */
        void ServiceAccessResourceFileL(const RMessage2& aMessage);

        /**
         * Finnishes installation of application configurations
         * @since S60 5.0
         * @param aAppODT is an ODT instance of an application configuration
         */
        void HandlePluginReferencesL(
                ChspsODT& aAppODT );

#ifdef HSPS_LOG_ACTIVE  
        /**
        * SetLogBus
        *
        * @since S60 5.0
        * @param aLogBus Log bus to be set.
        */
        void SetLogBus( ChspsLogBus* aLogBus );
#endif        
        
    public: // From MhspsClientRequestService
            
        /** 
        * From MhspsClientRequestService hspsGetODT
        * @since S60 3.1
        * @param aAppUid is the UID of the application for which the theme is requested for.
        * @param aODT is an empty ChspsODT-object in where the theme is expected to be placed when 
        *        the call returns.
        * @return ThspsServiceCompletedMessage expressing the result of the call.
        */
        ThspsServiceCompletedMessage hspsGetODT(TInt aAppUid, ChspsODT& aODT);
        
        /** 
        * From MhspsClientRequestService hspsGetODT
        * @since S60 3.1
        * @param aAppUid is the UID of the application for which the theme is requested for.
        * @param aODT is an empty ChspsODT-object in where the theme is expected to be placed when 
        *             the call returns.
        * @param aResourceList is an empty list-object able to contain ChspsResource-objects. 
        *        On return of the call, every resource object on the list will describe a resource 
        *        belonging to the theme in hand. 
        * @return ThspsServiceCompletedMessage expressing the result of the call.
        *
        * DEPRECATED
        */  
        ThspsServiceCompletedMessage hspsGetODT(TInt aAppUid, ChspsODT& aODT, 
                          CArrayPtrSeg<ChspsResource>& aResourceList);
        
        /** 
        * From MhspsClientRequestService hspsGetODTUpdate
        * @since S60 3.1
        * @return ThspsServiceCompletedMessage expressing the result of the call.
        */
        ThspsServiceCompletedMessage hspsGetODTUpdate();
        
        /** 
        * From MhspsClientRequestService hspsCancelGetODTUpdate
        * @since S60 3.1
        * @return ThspsServiceCompletedMessage telling the result of the call.
        */
        ThspsServiceCompletedMessage hspsCancelGetODTUpdate();
        
        /** 
        * From MhspsClientRequestService hspsAccessResourceFile
        * @since S60 3.1
        * @param aResourceFileName is the path for resource file to requested. Resource file name is
        *        given in every ChspsResource-object listed on the resource list.
        * @param aFile is an empty RFile object which a valid file handle to the resourec file will
        *        be placed on return. 
        *        The file access is arranged by means of Symbian 9.0 EKA2 Platform Security file 
        *        handle sharing concept.
        * @return ThspsServiceCompletedMessage expressing the result of the call.
        */
        ThspsServiceCompletedMessage hspsAccessResourceFile(
            const TDesC& /*aResourceFileName*/,
            const ThspsConfiguration& /*aConfiguration*/,
            RFile& /*aFile*/ );
  
    public: // from MhspsDefinitioRepositoryObserver
         
         TBool HandleDefinitionRespositoryEvent( ThspsRepositoryInfo aRepositoryInfo );
  
    public: // from MhspsCenRepObserver
         
        void HandleCenRepChangeL( const TUint32 aId );
         
    protected:
        /**
        * ChspsClientRequestHandler
        * C++ default constructor.
        * @since S60 5.0
        */
        ChspsClientRequestHandler( ChspsThemeServer& aThemeServer );
        
        /**
        * ConstructL
        * By default Symbian 2nd phase constructor is private
        * @since S60 5.0
        */
        void ConstructL();
  
    private:
                
        /**
        * RestoreDefaultL
        *
        * @since S60 3.1
        */
        void RestoreDefaultL( ChspsODT& aOdt );
        
        /**
        * CallGetODTPathL
        *
        * @since S60 5.0
        */
        void CallGetODTPathL( ChspsODT& aSearchMask, TDes& aODTPath );
        
        /**
        * CompleteRequest
        *
        * @since S60 5.0
        */
        void CompleteRequestL(const ThspsServiceCompletedMessage aReturnMessage,
                   RMessagePtr2& aMessagePtr, const TDesC8& aHeaderData = KNullDesC8 );
                
        /**
        * RestoreValidThemeL
        * Restores operator/licensee default theme
        * @since S60 3.1
        * @param aCorruptedOdt  Odt which failed to render
        */
        void RestoreValidThemeL(ChspsODT& aCorruptedOdt);
        
      /**
        * HandleDefinitionRespositoryEventL
        *
        * @since S60 5.0
        */
        
        TBool HandleDefinitionRespositoryEventL( ThspsRepositoryInfo aRepositoryInfo );
        
        /**
         * Finds plug-in references from the provided application configuration and append 
         * XML document with plug-ins specific XML.
         * Applies to plug-in configurations of type "application configuration" only.
         * @param aAppODT is an ODT instance of an application configuration
         */
        void AppendPluginConfigurationsL( 
                ChspsODT& aAppODT );
        
        /**
         * Appends missing plugin with a dummy configuration where status="Error"
         * @since S60 5.0
         * @param aAppDom is a DOM of an application configuration 
         * @param aMissingPluginNode is a plug-in node which was not found from the Plugin Repository
         * @param aPluginUid is an UID of the missing plugin
         */
        void AddErrorConfigurationL(
                ChspsDomDocument& aAppDom,
                ChspsDomNode& aMissingPluginNode,
                const TInt aPluginUid );

        /**
         * Prepare given ChspsRequestNotificationParams for sending.
         * 
         * @since S60 5.0
         * @param aInfo         Info to build params from.    
         * @param aMessage      Completed message.
         */
        void PrepareAndCompleteRequestL( const ThspsRepositoryInfo& aInfo,
                                         const ThspsServiceCompletedMessage& aMessage );                                                                           
         
	    /**
         * Finds plug-in's initial settings from the provided root configuration and modify 
         * plugin specific settings with these initial settings.
		 *
		 * @since S60 5.0
         * @param aAppODT is an ODT instance of an application configuration
         * @return KErNone if succeed
		 */
        TInt AppendInitialSettingsL( ChspsODT& aAppODT );
		
        /**
         * Parse initial settings items.
         * 
         * @since S60 5.0
         * @param aInitialSettingsNode         Initial settings node to be parsed(source node).    
         * @param aSettingsNode                Actual settings node(target node) where to initial settings needs to be copied.
         * @return KErNone if succeed
		 */
        TInt ParseInitialSettingsItemsL( ChspsDomNode& aInitialSettingsNode,ChspsDomNode& aSettingsNode);
		
        /**
         * Handling initial settings property nodes.
         * 
         * @since S60 5.0
         * @param aPropertyNode        Initial settings property node(property source node).    
         * @param aNode                Target node.
		 * @return KErNone if succeed
         */
        TInt HandlePropertyNodeL( ChspsDomNode& aPropertyNode,ChspsDomNode& aNode );  
		
        /**
         * Handling attributes.
         * 
         * @since S60 5.0
         * @param aAttrName       Attribute name.    
         * @param aAttrValue      Attribute value.
		 * @param aNode           Target property node.
		 * @return KErNone if succeed.
         */     
        TInt HandlePropertyAttributesL(const TDesC8& aAttrName,
                                    const TDesC8& aAttrValue,
                                    ChspsDomNode& aNode );
       
        /**
         * Finds a root node for liw structure from dom document by identifier
		 *
		 * @since S60 5.0
         * @param aNodeIdentifier An Tag.
         * @param aNodeIdentifier An Identifier.
         * @param aNode A Dom Node where the node is searched from.
         * @return Result node.
         */
        ChspsDomNode& FindRootNodeByIdentifierL( const TDesC8& aNodeTag,
                                                        const TDesC8& aNodeIdentifier,
                                                        ChspsDomNode& aNode );
        
    protected: // Functions from base classes

       
    private:    // Data
        // the next member variables should be used in asynchronous message handling only
        RMessagePtr2 iMessagePtr;
        TFileName iODTPath;
       
        // tells to restore default in repeated theme load cases
        TBool iRestoreDefault;
        ChspsResult* iResult;
        TBuf8<KMaxResultDataLength8> iResultData;
        ChspsRequestNotificationParams* iReqNotifParams;
        TBuf8<KMaxReqNotifDataLength8> iReqNotifData;
        HBufC8* iRequestData;
        
        // Index of the requested function
        ThspsServiceRequestMessage iRequestMessage;
        
        ThspsServiceCompletedMessage iCompletedMessage;
        TTime iLastHeaderListUpdateTime;
        TTime iLastSuccessThemeLoadTime;
        // application or interface uid
        TUint iRootUid;        
        // theme uid from the most recent request
        TUint iActiveThemeUid;
        TUint iSecureId;
        ChspsODT* iOdt;
        RFs iFs;
        TInt iThemeLoadRepeatCount;
        // ownership of the next objects is held by ChspsThemeServer
        ChspsThemeServer& iThemeServer;        
        // Reference to central repository
        CRepository& iCentralRepository;  
        // Pointer to Central Repository Listener        
        ChspsCenRepListener* iCenRepListener;
        // Reference to definition repository
        ChspsDefinitionRepository& iDefinitionRepository;
        // Reference to security enforcer
        ChspsSecurityEnforcer& iSecurityEnforcer;
        // header list cache
        CArrayPtrSeg<ChspsODT>& iHeaderListCache;   
        // Reserved pointer for future extension
        TAny* iReserved;

#ifdef HSPS_LOG_ACTIVE        
        // Log bus to be used. Not owned.
        ChspsLogBus* iLogBus;
#endif        
    };

#endif //__hspsCLIENTREQUESTHANDLER_H__

// end of file