Collapse all Symbian^3 Product Developer Library

ChspsClient Class Reference

class ChspsClient : public CActive

ChspsClient. ChspsClient performs all client-side theme installation and maintenance related functionality. Theme maintenance services includes theme listings, theme activation, theme removal, and default theme restoring functionality.

Class inheritance: ================== ChspsClient derives CActive for asynchronous request handling, and MhspsInstallationService and MhspsMaintenanceService from Homescreenpluginservices.

Theme installation functionality: ================================= Client application must call hspsInstallNextPhaseL() after testing that the synchronous call hspsInstallTheme() has returned EhspsInstallPhaseSuccess return code signalling that actual installation is allowed. The rest of the installation phases will be executed automatically, however, installation can be interrupted by calling hspsCancelInstallTheme() at any time. If installation is canceled, hspsThemeServer initiates roll-back functionality removing inconsistent installation. Installation service uses specific manifest-file format to get informed about the xml, css, dtd, and resource files to be installed. Resource files might be locale-specific or generic as well. hspsThemeServer takes care of saving everything on their appropriate places in the target device's user disk. Theme storage is located in hspsThemeServer's private-folder. Locales are instructed in manifest file also. Manifest file's file-extension must be .dat, but actually, the file-name can be whatever, however, when low-level parametrization is used, the name must be "manifest.dat" and it must be the last file extracted from the installation package. For more information of manifest-file format, see Homescreen wikipages.

Installation functions can return one of the following ThspsServiceCompletedMessage-codes:

EhspsInstallThemeSuccess,
EhspsInstallPhaseSuccess, or
EhspsInstallThemeFailed.

Client application must implement MhspsThemeManagementServiceObserver-interface and listen these messages mentioned. Let it be emphasised that both synchronous and asynchronous calls can return the codes above. Installation functions may also return one of the following codes:

EhspsServiceRequestSheduled, or
EhspsServiceRequestError.

For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.

Theme maintenance functionality: ================================ Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader(). Others functions are straightforward to use but hspsGetListHeaders(). This will be explained next; synchronous call hspsGetListHeaders() initiates the theme header listing by passing search mask to HSPS Server's Maintenance Service. This search mask is called a query. It also passes a list object in where maintenance service should append theme-header objects (type of ChspsODT-class without DOM-document) when one is retrieved asychronously. Search mask should be filled with proper parameters matching the need in hand. If no parameters are given, all headers of Application Themes available in Definition Repository will be delivered, otherwise, only sub-set of theme-headers will be delivered. After the query-call hspsGetListHeaders(), the delivering of the theme-headers is asynchronous. Asynchronous service must be initiated by calling hspsGetNextHeader() after checking that any theme matching on current query is found or that query is valid anyway. This action is called a subscription. To receive theme listing, the client application must implement MhspsThemeManagementServiceObserver-interface and start to listen call-back messages. The headers matching on query will be delivered immediately. Query remains until hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, it will be delivered. As mentioned, when hspsGetListHeaders() returns, the return value must be checked. Return value could be one of the following:

EhspsGetListHeadersSuccess - there is at least one Application Theme available matching on query. Call first hspsGetNextHeader() to get the headers. Same call will set the subscribtion of new ones possible coming available later.
EhspsGetListHeadersEmpty - there is no themes matching on the query available at the time, however, some might be exist later in due to installations. Client application should retain the subcription.
EhspsGetListHeadersFailed - service request failed for some reason. Possible reasons are for e.g. the missing rights to list headers queried.

Additional Return Code Support (ChspsResult) will express for e.g. the number of headers to be delivered or possible system error code in failed cases.

By MhspsServiceObserver::HandlehspsServiceMessage() call-back function implementation, client application must listen the following ThspsServiceCompletedMessage-messages:

EhspsGetListHeadersUpdate - header list on the client side has a new object appended at the end of the list,
EhspsGetListHeadersRestart - header list on server side has changed so much that the client must empty the list printed on screen. New list will be delivered immediately. The subscription stands.
EhspsGetListHeadersEmpty - header list on server side is now empty. The client must empty the list on screen if printed. The subscription stands.
EhspsGetListHeadersFailed - operation has failed. Client should cancel request and restart.

Maintenanace functions may also return one of the following codes:

EhspsServiceRequestSheduled, or
EhspsServiceRequestError.

For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation.

hspsClient.lib

Since: S60 5.0

Inherits from

ChspsClient
- CActive
  - CBase

Public Member Functions
	~ChspsClient()
IMPORT_C void	GethspsResult(ChspsResult &)
IMPORT_C ChspsClient *	NewL(MhspsThemeManagementServiceObserver &)
IMPORT_C ChspsClient *	NewLC(MhspsThemeManagementServiceObserver &)
IMPORT_C void	SetLogBus(void *)
IMPORT_C ThspsServiceCompletedMessage	hspsAddPlugin(const TInt, const TInt, const TInt, const TInt, TInt &)
IMPORT_C ThspsServiceCompletedMessage	hspsCancelGetListHeaders()
IMPORT_C ThspsServiceCompletedMessage	hspsCancelInstallTheme()
IMPORT_C TInt	hspsGetHeaders(const ChspsODT &, const TBool, CArrayPtrFlat< ChspsODT > &)
IMPORT_C ThspsServiceCompletedMessage	hspsGetListHeaders(const ChspsODT &, const TBool, CArrayPtrFlat< ChspsODT > &)
IMPORT_C ThspsServiceCompletedMessage	hspsGetListHeaders(const TDesC8 &, CArrayPtrSeg< HBufC8 > &)
IMPORT_C ThspsServiceCompletedMessage	hspsGetNextHeader()
IMPORT_C ThspsServiceCompletedMessage	hspsGetPluginOdtL(const TInt, const TInt, ChspsODT *)
IMPORT_C ThspsServiceCompletedMessage	hspsInstallNextPhaseL(ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsInstallNextPhaseL(TDes8 &)
IMPORT_C ThspsServiceCompletedMessage	hspsInstallTheme(const TDesC &, ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsInstallTheme(const TDesC &, TDes8 &)
IMPORT_C ThspsServiceCompletedMessage	hspsMovePluginsL(const TInt, const TInt, const CArrayFixFlat< TInt > &)
IMPORT_C ThspsServiceCompletedMessage	hspsPluginUpdateL(const ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsReinstallConf(TInt, TInt)
IMPORT_C ThspsServiceCompletedMessage	hspsRemovePlugin(const TInt, const TInt)
IMPORT_C ThspsServiceCompletedMessage	hspsRemoveThemeL(const ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsReplacePlugin(const TInt, const TInt, const TInt)
IMPORT_C ThspsServiceCompletedMessage	hspsRestoreActiveAppConf(const TInt, const TInt)
IMPORT_C ThspsServiceCompletedMessage	hspsRestoreConfigurations(const TInt, const ThspsRestore)
IMPORT_C ThspsServiceCompletedMessage	hspsRestoreDefault(const ChspsODT &, ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsSetActivePlugin(const TInt, const TInt)
IMPORT_C ThspsServiceCompletedMessage	hspsSetActiveTheme(const ChspsODT &, ChspsODT &)
IMPORT_C ThspsServiceCompletedMessage	hspsSetActiveTheme(const TDesC8 &, TDes8 &)
IMPORT_C ThspsServiceCompletedMessage	hspsSetConfState(const TInt, const TInt, const ThspsConfigurationState, const ThspsConfStateChangeFilter)
IMPORT_C ThspsServiceCompletedMessage	hspsSetPluginSettings(const ChspsODT &, const TInt, ChspsDomDocument &, const TBool)

Protected Member Functions
void	DoCancel()
TInt	RunError(TInt)
void	RunL()

Private Member Functions
	ChspsClient(MhspsThemeManagementServiceObserver &)
void	AppendHeaderListL(TDesC8 &)
void	ConstructL()
TInt	StreamOdtL(TDes &, const TInt, ChspsODT *)
void	UpdatehspsResult(TDesC8 &)

Inherited Functions
	CActive::CActive(TInt)
	CActive::Cancel()
	CActive::Deque()
	CActive::Extension_(TUint,TAny &,TAny )
	CActive::IsActive()const
	CActive::IsAdded()const
	CActive::Priority()const
	CActive::SetActive()
	CActive::SetPriority(TInt)
	CActive::~CActive()
	CBase::CBase()
	CBase::Delete(CBase *)
	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()

Inherited Enumerations
	CActive:TPriority

Private Attributes
ThspsServiceRequestMessage	iCancelRequestMessage
ChspsODT *	iHeader
TBuf8< KMaxHeaderDataLength8 >	iHeaderData
CArrayPtrSeg< HBufC8 > *	iHeaderDataList
CArrayPtrFlat< ChspsODT > *	iHeaderList
TBool	iODTMode
MhspsThemeManagementServiceObserver &	iObserver
ChspsODT *	iOdt
ChspsResult *	iResult
TBuf8< KMaxResultDataLength8 >	iResultData
HBufC8 *	iSearchMaskData
RhspsClientSession	iSession
HBufC8 *	iSetMaskData
TBool	iSubscription

Inherited Attributes
	CActive::iStatus

Constructor & Destructor Documentation

ChspsClient(MhspsThemeManagementServiceObserver &)

ChspsClient

(

MhspsThemeManagementServiceObserver &

aObserver

)

[private]

ChspsClient. Performs the first phase of two phase construction.

Parameters

MhspsThemeManagementServiceObserver & aObserver

The object to be used to handle updates from the server.

~ChspsClient()

~ChspsClient

(

)

[virtual]

~ChspsClient.

Destructor. Destroys the object and release all memory objects.

Member Functions Documentation

AppendHeaderListL(TDesC8 &)

void

AppendHeaderListL

(

TDesC8 &

aHeaderData

)

[private]

Creates a header object from header data (iHeaderData) and adds created header to the header list (iHeaderList)

Parameters

TDesC8 & aHeaderData

Header data

ConstructL()

void

ConstructL

(

)

[private]

ConstructL. Performs the second phase construction of a ChspsClient object.

DoCancel()

void

DoCancel

(

)

[protected, virtual]

From CActive, DoCancel. Cancels any outstanding operation.

GethspsResult(ChspsResult &)

IMPORT_C void

GethspsResult

(

ChspsResult &

aResult

)

GethspsResult

Since: S60 5.0

Parameters

ChspsResult & aResult

is a ChspsResult object containing additional information of query result.

NewL(MhspsThemeManagementServiceObserver &)

IMPORT_C ChspsClient *

NewL

(

MhspsThemeManagementServiceObserver &

aObserver

)

[static]

NewL.

Two-phased constructor. Creates a ChspsClient object using two phase construction, and return a pointer to the created object.

Since: S60 5.0

Parameters

MhspsThemeManagementServiceObserver & aObserver

The object to be used to handle updates from the server.

NewLC(MhspsThemeManagementServiceObserver &)

IMPORT_C ChspsClient *

NewLC

(

MhspsThemeManagementServiceObserver &

aObserver

)

[static]

NewLC.

Two-phased constructor. Creates a ChspsClinet object using two phase construction, and return a pointer to the created object.

Since: S60 5.0

Parameters

MhspsThemeManagementServiceObserver & aObserver

The object to be used to handle updates from the server.

RunError(TInt)

TInt

RunError

(

TInt

aError

)

[protected, virtual]

From CActive Called when asynchronous request has failed

Since: S60 3.1

Parameters

TInt aError

RunL()

void

RunL

(

)

[protected, virtual]

From CActive, RunL. Callback function. Invoked to handle responses from the server.

SetLogBus(void *)

IMPORT_C void

SetLogBus

(

void *

aLogBus

)

Internal log bus setter. Empty method in product builds.

Since: S60 5.0

Parameters

void * aLogBus

Log bus to be set.

StreamOdtL(TDes &, const TInt, ChspsODT *)

TInt	StreamOdtL	(	TDes &	aOdtPath,
			const TInt	aAppUid,
			ChspsODT *	aPluginOdt
		)	[private]

Gets file handle and streams odt from the file.

Since: S60 5.0

Parameters

TDes & aOdtPath	- odt file path
const TInt aAppUid	- application uid for accessing to the file
ChspsODT * aPluginOdt	- odt for streaming

UpdatehspsResult(TDesC8 &)

void

UpdatehspsResult

(

TDesC8 &

aResultData

)

[private]

Updates iResult

Parameters

TDesC8 & aResultData

Result data

hspsAddPlugin(const TInt, const TInt, const TInt, const TInt, TInt &)

IMPORT_C ThspsServiceCompletedMessage	hspsAddPlugin	(	const TInt	aAppUid,
			const TInt	aConfId,
			const TInt	aPluginUid,
			const TInt	aPosition,
			TInt &	aAddedPluginId
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aConfId
const TInt aPluginUid
const TInt aPosition
TInt & aAddedPluginId

hspsCancelGetListHeaders()

IMPORT_C ThspsServiceCompletedMessage

hspsCancelGetListHeaders

(

)

From MhspsMaintenanceService.

hspsCancelInstallTheme()

IMPORT_C ThspsServiceCompletedMessage

hspsCancelInstallTheme

(

)

From MhspsInstallationService.

hspsGetHeaders(const ChspsODT &, const TBool, CArrayPtrFlat< ChspsODT > &)

IMPORT_C TInt	hspsGetHeaders	(	const ChspsODT &	aSearchMask,
			const TBool	aCopyLogos,
			CArrayPtrFlat< ChspsODT > &	aHeaderList
		)

Returns ODT header list according to the defined search mask

Since: S60 5.0

Parameters

const ChspsODT & aSearchMask	is ChspsODT-object which attributes are filled to present search parameters for theme set queried by client. This parametrisation follows the high-level schema.
const TBool aCopyLogos	is set if client wants to view logos
CArrayPtrFlat< ChspsODT > & aHeaderList	is an list object able to carry ChspsODT-objects.

hspsGetListHeaders(const ChspsODT &, const TBool, CArrayPtrFlat< ChspsODT > &)

IMPORT_C ThspsServiceCompletedMessage	hspsGetListHeaders	(	const ChspsODT &	aSearchMask,
			const TBool	aCopyLogos,
			CArrayPtrFlat< ChspsODT > &	aHeaderList
		)

From MhspsMaintenanceService.

Parameters

const ChspsODT & aSearchMask
const TBool aCopyLogos
CArrayPtrFlat< ChspsODT > & aHeaderList

hspsGetListHeaders(const TDesC8 &, CArrayPtrSeg< HBufC8 > &)

IMPORT_C ThspsServiceCompletedMessage	hspsGetListHeaders	(	const TDesC8 &	aSearchMaskData,
			CArrayPtrSeg< HBufC8 > &	aHeaderDataList
		)

From MhspsMaintenanceService.

Parameters

const TDesC8 & aSearchMaskData
CArrayPtrSeg< HBufC8 > & aHeaderDataList

hspsGetNextHeader()

IMPORT_C ThspsServiceCompletedMessage

hspsGetNextHeader

(

)

From MhspsMaintenanceService.

hspsGetPluginOdtL(const TInt, const TInt, ChspsODT *)

IMPORT_C ThspsServiceCompletedMessage	hspsGetPluginOdtL	(	const TInt	aAppUid,
			const TInt	aPluginUid,
			ChspsODT *	aPluginOdt
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aPluginUid
ChspsODT * aPluginOdt

hspsInstallNextPhaseL(ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage

hspsInstallNextPhaseL

(

ChspsODT &

aHeader

)

From MhspsInstallationService.

Parameters

ChspsODT & aHeader

hspsInstallNextPhaseL(TDes8 &)

IMPORT_C ThspsServiceCompletedMessage

hspsInstallNextPhaseL

(

TDes8 &

aHeaderData

)

From MhspsInstallationService.

Parameters

TDes8 & aHeaderData

hspsInstallTheme(const TDesC &, ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage	hspsInstallTheme	(	const TDesC &	aManifestFileName,
			ChspsODT &	aHeader
		)

From MhspsInstallationService.

Parameters

const TDesC & aManifestFileName
ChspsODT & aHeader

hspsInstallTheme(const TDesC &, TDes8 &)

IMPORT_C ThspsServiceCompletedMessage	hspsInstallTheme	(	const TDesC &	aManifestFileName,
			TDes8 &	aHeaderData
		)

From MhspsInstallationService.

Parameters

const TDesC & aManifestFileName
TDes8 & aHeaderData

hspsMovePluginsL(const TInt, const TInt, const CArrayFixFlat< TInt > &)

IMPORT_C ThspsServiceCompletedMessage	hspsMovePluginsL	(	const TInt	aAppUid,
			const TInt	aConfId,
			const CArrayFixFlat< TInt > &	aPluginIdList
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aConfId
const CArrayFixFlat< TInt > & aPluginIdList

hspsPluginUpdateL(const ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage

hspsPluginUpdateL

(

const ChspsODT &

)

Updates plugin configuration in all application configuration

Since: S60 5.0

Parameters

const ChspsODT &

hspsReinstallConf(TInt, TInt)

IMPORT_C ThspsServiceCompletedMessage	hspsReinstallConf	(	TInt	aAppUid,
			TInt	aConfUid
		)

Reinstalls requested configuration

Since: S60 5.0

Parameters

TInt aAppUid	is interface.
TInt aConfUid	is ID of the reinstalled configuration.

hspsRemovePlugin(const TInt, const TInt)

IMPORT_C ThspsServiceCompletedMessage	hspsRemovePlugin	(	const TInt	aAppUid,
			const TInt	aPluginId
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aPluginId

hspsRemoveThemeL(const ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage

hspsRemoveThemeL

(

const ChspsODT &

aSetMask

)

From MhspsMaintenanceService.

Parameters

const ChspsODT & aSetMask

hspsReplacePlugin(const TInt, const TInt, const TInt)

IMPORT_C ThspsServiceCompletedMessage	hspsReplacePlugin	(	const TInt	aAppUid,
			const TInt	aPluginId,
			const TInt	aConfUid
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aPluginId
const TInt aConfUid

hspsRestoreActiveAppConf(const TInt, const TInt)

IMPORT_C ThspsServiceCompletedMessage	hspsRestoreActiveAppConf	(	const TInt	aAppUid,
			const TInt	aConfUid
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aConfUid

hspsRestoreConfigurations(const TInt, const ThspsRestore)

IMPORT_C ThspsServiceCompletedMessage	hspsRestoreConfigurations	(	const TInt	aAppUid,
			const ThspsRestore	aRestore
		)

Restores plugin configurations according to the input.

Since: S60 5.2

Parameters

const TInt aAppUid	Application uid
const ThspsRestore aRestore	Operation to be executed

hspsRestoreDefault(const ChspsODT &, ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage	hspsRestoreDefault	(	const ChspsODT &	aSetMask,
			ChspsODT &	aHeader
		)

From MhspsMaintenanceService.

Parameters

const ChspsODT & aSetMask
ChspsODT & aHeader

hspsSetActivePlugin(const TInt, const TInt)

IMPORT_C ThspsServiceCompletedMessage	hspsSetActivePlugin	(	const TInt	aAppUid,
			const TInt	aPluginId
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aPluginId

hspsSetActiveTheme(const ChspsODT &, ChspsODT &)

IMPORT_C ThspsServiceCompletedMessage	hspsSetActiveTheme	(	const ChspsODT &	aSetMask,
			ChspsODT &	aHeader
		)

From MhspsMaintenanceService.

Parameters

const ChspsODT & aSetMask
ChspsODT & aHeader

hspsSetActiveTheme(const TDesC8 &, TDes8 &)

IMPORT_C ThspsServiceCompletedMessage	hspsSetActiveTheme	(	const TDesC8 &	aSetMaskData,
			TDes8 &	aHeaderData
		)

From MhspsMaintenanceService.

Parameters

const TDesC8 & aSetMaskData
TDes8 & aHeaderData

hspsSetConfState(const TInt, const TInt, const ThspsConfigurationState, const ThspsConfStateChangeFilter)

IMPORT_C ThspsServiceCompletedMessage	hspsSetConfState	(	const TInt	aAppUid,
			const TInt	aConfId,
			const ThspsConfigurationState	aState,
			const ThspsConfStateChangeFilter	aFilter
		)

From MhspsMaintenanceService

Parameters

const TInt aAppUid
const TInt aConfId
const ThspsConfigurationState aState
const ThspsConfStateChangeFilter aFilter

hspsSetPluginSettings(const ChspsODT &, const TInt, ChspsDomDocument &, const TBool)

IMPORT_C ThspsServiceCompletedMessage	hspsSetPluginSettings	(	const ChspsODT &	aHeader,
			const TInt	aPluginId,
			ChspsDomDocument &	aDom,
			const TBool	aPluginStoringStatus
		)