Collapse all Symbian^3 Application Developer Library

ChspsClientRequestHandler Class Reference

class ChspsClientRequestHandler : public CBase

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.

hspsThemeServer.exe

Since: S60 5.0

Inherits from

ChspsClientRequestHandler
- CBase

Public Member Functions
	~ChspsClientRequestHandler ()
void	HandleCenRepChangeL (const TUint32 )
TBool	HandleDefinitionRespositoryEvent ( ThspsRepositoryInfo )
void	HandlePluginReferencesL ( ChspsODT &)
ChspsClientRequestHandler *	NewL ( ChspsThemeServer &)
ChspsClientRequestHandler *	NewLC ( ChspsThemeServer &)
void	ServiceAccessResourceFileL (const RMessage2 &)
void	ServiceGetOdtL (const RMessage2 &)
void	ServiceGetOdtUpdateL (const RMessage2 &)
ThspsServiceCompletedMessage	hspsAccessResourceFile (const TDesC &, const ThspsConfiguration &, RFile &)
ThspsServiceCompletedMessage	hspsCancelGetODTUpdate ()
ThspsServiceCompletedMessage	hspsGetODT ( TInt , ChspsODT &)
ThspsServiceCompletedMessage	hspsGetODT ( TInt , ChspsODT &, CArrayPtrSeg < ChspsResource > &)
ThspsServiceCompletedMessage	hspsGetODTUpdate ()

Protected Member Functions
	ChspsClientRequestHandler ( ChspsThemeServer &)
void	ConstructL ()

Private Member Functions
void	AddErrorConfigurationL ( ChspsDomDocument &, ChspsDomNode &, const TInt )
TInt	AppendInitialSettingsL ( ChspsODT &)
void	AppendPluginConfigurationsL ( ChspsODT &)
void	CallGetODTPathL ( ChspsODT &, TDes &)
void	CompleteRequestL (const ThspsServiceCompletedMessage , RMessagePtr2 &, const TDesC8 &)
ChspsDomNode &	FindRootNodeByIdentifierL (const TDesC8 &, const TDesC8 &, ChspsDomNode &)
TBool	HandleDefinitionRespositoryEventL ( ThspsRepositoryInfo )
TInt	HandlePropertyAttributesL (const TDesC8 &, const TDesC8 &, ChspsDomNode &)
TInt	HandlePropertyNodeL ( ChspsDomNode &, ChspsDomNode &)
TInt	ParseInitialSettingsItemsL ( ChspsDomNode &, ChspsDomNode &)
void	PrepareAndCompleteRequestL (const ThspsRepositoryInfo &, const ThspsServiceCompletedMessage &)
void	RestoreDefaultL ( ChspsODT &)
void	RestoreValidThemeL ( ChspsODT &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
TUint	iActiveThemeUid
ChspsCenRepListener *	iCenRepListener
CRepository &	iCentralRepository
ThspsServiceCompletedMessage	iCompletedMessage
ChspsDefinitionRepository &	iDefinitionRepository
RFs	iFs
CArrayPtrSeg < ChspsODT > &	iHeaderListCache
TTime	iLastHeaderListUpdateTime
TTime	iLastSuccessThemeLoadTime
RMessagePtr2	iMessagePtr
TFileName	iODTPath
ChspsODT *	iOdt
TBuf8 < KMaxReqNotifDataLength8 >	iReqNotifData
ChspsRequestNotificationParams *	iReqNotifParams
HBufC8 *	iRequestData
ThspsServiceRequestMessage	iRequestMessage
TAny *	iReserved
TBool	iRestoreDefault
ChspsResult *	iResult
TBuf8 < KMaxResultDataLength8 >	iResultData
TUint	iRootUid
TUint	iSecureId
ChspsSecurityEnforcer &	iSecurityEnforcer
TInt	iThemeLoadRepeatCount
ChspsThemeServer &	iThemeServer

Constructor & Destructor Documentation

ChspsClientRequestHandler(ChspsThemeServer &)

ChspsClientRequestHandler

(

ChspsThemeServer &

aThemeServer

)

[protected]

ChspsClientRequestHandler C++ default constructor.

Since: S60 5.0

Parameters

ChspsThemeServer & aThemeServer

~ChspsClientRequestHandler()

~ChspsClientRequestHandler

(

)

~ChspsClientRequestHandler Destructor.

Member Functions Documentation

AddErrorConfigurationL(ChspsDomDocument &, ChspsDomNode &, const TInt)

void	AddErrorConfigurationL	(	ChspsDomDocument &	aAppDom,
			ChspsDomNode &	aMissingPluginNode,
			const TInt	aPluginUid
		)	[private]

Appends missing plugin with a dummy configuration where status="Error"

Since: S60 5.0

Parameters

ChspsDomDocument & aAppDom	is a DOM of an application configuration
ChspsDomNode & aMissingPluginNode	is a plug-in node which was not found from the Plugin Repository
const TInt aPluginUid	is an UID of the missing plugin

AppendInitialSettingsL(ChspsODT &)

TInt

AppendInitialSettingsL

(

ChspsODT &

aAppODT

)

[private]

Finds plug-in's initial settings from the provided root configuration and modify plugin specific settings with these initial settings.

Since: S60 5.0

Parameters

ChspsODT & aAppODT

is an ODT instance of an application configuration

AppendPluginConfigurationsL(ChspsODT &)

void

AppendPluginConfigurationsL

(

ChspsODT &

aAppODT

)

[private]

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.

Parameters

ChspsODT & aAppODT

is an ODT instance of an application configuration

CallGetODTPathL(ChspsODT &, TDes &)

void	CallGetODTPathL	(	ChspsODT &	aSearchMask,
			TDes &	aODTPath
		)	[private]

CallGetODTPathL

Since: S60 5.0

Parameters

ChspsODT & aSearchMask
TDes & aODTPath

CompleteRequestL(const ThspsServiceCompletedMessage, RMessagePtr2 &, const TDesC8 &)

void	CompleteRequestL	(	const ThspsServiceCompletedMessage	aReturnMessage,
			RMessagePtr2 &	aMessagePtr,
			const TDesC8 &	aHeaderData = KNullDesC8
		)	[private]

CompleteRequest

Since: S60 5.0

Parameters

const ThspsServiceCompletedMessage aReturnMessage
RMessagePtr2 & aMessagePtr
const TDesC8 & aHeaderData = KNullDesC8

ConstructL()

void

ConstructL

(

)

[protected]

ConstructL By default Symbian 2nd phase constructor is private

Since: S60 5.0

FindRootNodeByIdentifierL(const TDesC8 &, const TDesC8 &, ChspsDomNode &)

ChspsDomNode &	FindRootNodeByIdentifierL	(	const TDesC8 &	aNodeTag,
			const TDesC8 &	aNodeIdentifier,
			ChspsDomNode &	aNode
		)	[private]

Finds a root node for liw structure from dom document by identifier

Since: S60 5.0

Parameters

const TDesC8 & aNodeTag
const TDesC8 & aNodeIdentifier	An Identifier.
ChspsDomNode & aNode	A Dom Node where the node is searched from.

HandleCenRepChangeL(const TUint32)

void

HandleCenRepChangeL

(

const TUint32

aId

)

Parameters

const TUint32 aId

HandleDefinitionRespositoryEvent(ThspsRepositoryInfo)

TBool

HandleDefinitionRespositoryEvent

(

ThspsRepositoryInfo

aRepositoryInfo

)

Parameters

ThspsRepositoryInfo aRepositoryInfo

HandleDefinitionRespositoryEventL(ThspsRepositoryInfo)

TBool

HandleDefinitionRespositoryEventL

(

ThspsRepositoryInfo

aRepositoryInfo

)

[private]

HandleDefinitionRespositoryEventL

Since: S60 5.0

Parameters

ThspsRepositoryInfo aRepositoryInfo

HandlePluginReferencesL(ChspsODT &)

void

HandlePluginReferencesL

(

ChspsODT &

aAppODT

)

Finnishes installation of application configurations

Since: S60 5.0

Parameters

ChspsODT & aAppODT

is an ODT instance of an application configuration

HandlePropertyAttributesL(const TDesC8 &, const TDesC8 &, ChspsDomNode &)

TInt	HandlePropertyAttributesL	(	const TDesC8 &	aAttrName,
			const TDesC8 &	aAttrValue,
			ChspsDomNode &	aNode
		)	[private]

Handling attributes.

Since: S60 5.0

Parameters

const TDesC8 & aAttrName	Attribute name.
const TDesC8 & aAttrValue	Attribute value.
ChspsDomNode & aNode	Target property node.

HandlePropertyNodeL(ChspsDomNode &, ChspsDomNode &)

TInt	HandlePropertyNodeL	(	ChspsDomNode &	aPropertyNode,
			ChspsDomNode &	aNode
		)	[private]

Handling initial settings property nodes.

Since: S60 5.0

Parameters

ChspsDomNode & aPropertyNode	Initial settings property node(property source node).
ChspsDomNode & aNode	Target node.

NewL(ChspsThemeServer &)

ChspsClientRequestHandler *

NewL

(

ChspsThemeServer &

aThemeServer

)

[static]

NewL

Since: S60 5.0

Parameters

ChspsThemeServer & aThemeServer

NewLC(ChspsThemeServer &)

ChspsClientRequestHandler *

NewLC

(

ChspsThemeServer &

aThemeServer

)

[static]

NewLC

Since: S60 5.0

Parameters

ChspsThemeServer & aThemeServer

ParseInitialSettingsItemsL(ChspsDomNode &, ChspsDomNode &)

TInt	ParseInitialSettingsItemsL	(	ChspsDomNode &	aInitialSettingsNode,
			ChspsDomNode &	aSettingsNode
		)	[private]

Parse initial settings items.

Since: S60 5.0

Parameters

ChspsDomNode & aInitialSettingsNode	Initial settings node to be parsed(source node).
ChspsDomNode & aSettingsNode	Actual settings node(target node) where to initial settings needs to be copied.

PrepareAndCompleteRequestL(const ThspsRepositoryInfo &, const ThspsServiceCompletedMessage &)

void	PrepareAndCompleteRequestL	(	const ThspsRepositoryInfo &	aInfo,
			const ThspsServiceCompletedMessage &	aMessage
		)	[private]

Prepare given ChspsRequestNotificationParams for sending.

Since: S60 5.0

Parameters

const ThspsRepositoryInfo & aInfo	Info to build params from.
const ThspsServiceCompletedMessage & aMessage	Completed message.

RestoreDefaultL(ChspsODT &)

void

RestoreDefaultL

(

ChspsODT &

aOdt

)

[private]

RestoreDefaultL

Since: S60 3.1

Parameters

ChspsODT & aOdt

RestoreValidThemeL(ChspsODT &)

void

RestoreValidThemeL

(

ChspsODT &

aCorruptedOdt

)

[private]

RestoreValidThemeL Restores operator/licensee default theme

Since: S60 3.1

Parameters

ChspsODT & aCorruptedOdt

Odt which failed to render

ServiceAccessResourceFileL(const RMessage2 &)

void

ServiceAccessResourceFileL

(

const RMessage2 &

aMessage

)

ServiceAccessResourceFileL

Since: S60 5.0

Parameters

const RMessage2 & aMessage

contains the data received from the client

ServiceGetOdtL(const RMessage2 &)

void

ServiceGetOdtL

(

const RMessage2 &

aMessage

)

ServiceGetOdtL

Since: S60 5.0

Parameters

const RMessage2 & aMessage

contains the data received from the client

ServiceGetOdtUpdateL(const RMessage2 &)

void

ServiceGetOdtUpdateL

(

const RMessage2 &

aMessage

)

ServiceGetOdtUpdateL

Since: S60 5.0

Parameters

const RMessage2 & aMessage

contains the data received from the client

hspsAccessResourceFile(const TDesC &, const ThspsConfiguration &, RFile &)

ThspsServiceCompletedMessage	hspsAccessResourceFile	(	const TDesC &	,
			const ThspsConfiguration &	,
			RFile &
		)

From MhspsClientRequestService hspsAccessResourceFile

Since: S60 3.1

Parameters

const TDesC &
const ThspsConfiguration &
RFile &

hspsCancelGetODTUpdate()

ThspsServiceCompletedMessage

hspsCancelGetODTUpdate

(

)

From MhspsClientRequestService hspsCancelGetODTUpdate

Since: S60 3.1

hspsGetODT(TInt, ChspsODT &)

ThspsServiceCompletedMessage	hspsGetODT	(	TInt	aAppUid,
			ChspsODT &	aODT
		)

From MhspsClientRequestService hspsGetODT

Since: S60 3.1

Parameters

TInt aAppUid	is the UID of the application for which the theme is requested for.
ChspsODT & aODT	is an empty ChspsODT-object in where the theme is expected to be placed when the call returns.

hspsGetODT(TInt, ChspsODT &, CArrayPtrSeg< ChspsResource > &)

ThspsServiceCompletedMessage	hspsGetODT	(	TInt	aAppUid,
			ChspsODT &	aODT,
			CArrayPtrSeg < ChspsResource > &	aResourceList
		)

From MhspsClientRequestService hspsGetODT

Since: S60 3.1

DEPRECATED

Parameters

TInt aAppUid	is the UID of the application for which the theme is requested for.
ChspsODT & aODT	is an empty ChspsODT-object in where the theme is expected to be placed when the call returns.
CArrayPtrSeg < ChspsResource > & 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.