/*
* 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