--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/homescreenpluginsrv/hspsmanager/inc/hspsclientrequesthandler.h Thu Dec 17 08:54:17 2009 +0200
@@ -0,0 +1,454 @@
+/*
+* 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
+