diff -r 0efa10d348c0 -r a5a39a295112 homescreenpluginsrv/inc/hspsthememanagement.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/homescreenpluginsrv/inc/hspsthememanagement.h Wed Sep 01 12:22:09 2010 +0100 @@ -0,0 +1,1674 @@ +/* +* 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: +* +* HSPS Application Theme Management Service APIs +* ************************************************ +* This file introduces the definitions of the interfaces and constanst to be a base of the +* implementations of HSPS Application Theme Management services. +* HSPS Application Theme Management Service APIs are introduced by defining Symbian M-classes +* for each API-functionality groups. These functionality groups and their correcponding M-classes +* are the following: +* - MhspsInstallationService - defines services for Application Theme +* installations, +* - MhspsMaintenanceService - defines services for listing, activation, +* removing and restoring themes set as default, +* - MhspsClientRequestService - defines services for usage of Application Themes, +* +* - MhspsThemeManagementServiceObserver - a generic call-back service API to be utilized by client +* applications of HSPS Theme Management Services, and +* - MhspsClientRequestServiceObserver - a dedicated interface to define the call-back service to be +* utilized by clients of HSPS Client Request Service. Typical client of the request service is +* some rendering engine implementation like HSPS UI Engine. +* +* Typical HSPS Application Theme Management Service use-cases +* ============================================================= +* Usage of Application Theme is requested by Rendering Engines. Theme rendering happens when +* Application's UI (user interface) is shown on the screen of the target device. Principal +* requestor of Installation and Maintenanace Service APIs is S60 Personalisation Application. +* Personalisation UI will present theme installation and activation functionality to the end-user. +* Also, HSPS-application itself may want to offer some installation and maintenance +* functionality on their menus, for e.g. allow a user select the theme to be used - theme +* activation (or hot-swap). Some system services of target devices, like OTAPush or DM (Device +* Management), may also use installation and maintenance APIs. +* This supports operators related use-cases where they want to maintain the customisation of mobile +* phone applications on-line. +* +* HSPS UI Manager +* ***************** +* UI Manager is a Symbian Client/Server system which is intended to serve HSPS native +* applications - as well as S60-legacy applications - with Application Theme installation, +* maintenance and usage related services. UI Manager implements HSPS Application Theme Management +* Service APIs. +* +* Client-side functionality and APIs +* ================================== +* In Client/Server system, only Client-side APIs are meaningful to the client +* applications. Offered client-side APIs are divided in two categories; +* hspsClient API and hspsRequestClient API. Both clients run basicly in +* asynchronous mode. however, they offers synchronic services also when +* appropriate. Clients are are able to delegate server messages to their +* client applications. hspsClient API offers application theme installation +* and maintenance related services, meanwhile hspsRequestClient API offers +* services related to the usage of Application Themes. +* +* Server-side functionality and APIs +* ================================== +* +* +* Security +* ======== +* Security in using services is quarantied by controlling the rights to list +* information of the theme set installed as well as to load individual themes. +* The access control is based on SECUREID of application process. +* Security is maintained behind the curtain by means of Symbian EKA2 Kernel +* services for Platform Security. +* +* Scalability +* =========== +* Architecture of UI Manager supports scalability in next way: Services +* provided on server-side reflects the client-side APIs. Client-side objects +* implements exactly the same APIs than services on server-side. This approach +* is selected to support scalability of the theme management system; +* small and one-application systems, for e.g. MP3-player, all services could +* be implemented on client-side, meanwhile large systems can increase their +* performance and features providing powerful and centralised server-side +* theme handling operations like OTA Push, theme caching, theme editing etc. +* HSPS UI Manager implementation is targeted for medium-wide systems running +* on Symbian OS 9.x, typically serving multiple applications and operators +* on-line operations customization on single smartphone. +* +* HSPS Utility Classes +* ====================== +* HSPS Utility Classes are used as parameters in HSPS Application Theme +* Management service calls. They are owned by serveice caller. Utility +* classes are kind of data objects and therefore they are not defined with +* specific interface (M-classes). Utility classes are the following: +* - ChspsODT, and +* - ChspsResource. +* +* ChspsODT +* ------ +* HSPS ChspsODT-class, nick-named ODT (Object Description Tree), class is a +* base unit of information exchanged in HSPS Application Theme Management +* operations. +* ODT consist of an header-part and its associated DOM-document member class +* on which it has a dependency. The header contains all information what is +* needed to distinquish application themes from each others. +* HSPS Application Theme Management services handles mainly these +* ODT-headers, however, the DOM-document is accessed for applying theme +* updates by Installation Handler and to serve the theme usage requests from +* Rendering Engines. For more information, see ChspsODT documentation. +* +* ChspsResource +* ----------- +* HSPS ChspsResource-class defines all information what is needed to maintain +* resources of Application Theme. Every ChspsResource-objects defines just one +* resource source, however, the same resource source coud be referenced +* multible times inside a theme - resources are usually shared. +* HSPS Application Theme Management system supports theme resourcing by +* offering resource conversations and storing services, and offering Rendering +* Engines the following services: +* 1) the way to match a resource quoted in xml- or css-module to the +* corresponding resource source, and 2) a secure way to access a resource +* through the Symbian Platform Security's process separation wall. +* +* ChspsResult +* --------- +* HSPS ChspsResult-class defines feature called Additional Return Code support +* for HSPS Application Theme Management Services on service request return. +* It is quaranteed that ChspsResult-object is always accessible after +* client request whether the result was successful or not. +* ChspsResult-class has attributes that informs the result as follows: +* - iSystemError - Symbian OS returned error code +* - iHSPSError - HSPS defined error code in HSPS error space +* - iIntValue1 - additional information relevant the result. +* - iIntValue2 - additional information relevant the result. +* +* +* +*/ + + +#ifndef __hspsTHEMEMANAGEMENT_H__ +#define __hspsTHEMEMANAGEMENT_H__ + +#include // RFile +#include // descriptors + +// -------------------- +const TUid KSecureId_Psln = {0x10005A32}; // from S60 3.1 Plsn +const TUid KSecureId_RDAS = {0x10210EA1}; // 270601889 from S60 3.1 R&D AppShell for Xuikon +const TUid KSecureId_hspsAS = {0x101F4CD2}; // 270486738 from S60 3.1 Xuikon AppShell in 3.1 product. +const TUid KSecureId_hsps = {0x200159C6}; // HSPS configuration installer (ThemeInstallerCons.exe) +const TUid KSecureId_LE = {0x102049AD}; +const TUid KSecureId_XTA = {0x1020747D}; // Xuikon Test Automation +const TUid KSecureId_XKON = {0x102049AF}; // Xuikon Demo +const TUid KSecureId_hspsAI = {0x102750F0}; // 271012080 support for Xuikon-based ActiveIdle +const TUid KSecureId_GS = {0x100058EC}; // S60 3.1 GS-application(General Settings). +const TUid KSecureId_HUIMenu = {0x102828BD}; +const TUid KSecureId_EUnit = {0x20000FB1}; +const TUid KSecureId_Test = {0x200159C5}; // HSPS ThemeManager Testapp (internal folder) + + +// ----------------- + +/** Nokia VID: = VID_DEFAULT */ +const TInt Nokia_VID = 0x101FB657; + +/** +* KhspsThemeStatusRepositoryUid. +* Central repository entry for HSPS. +*/ +const TUid KhspsThemeStatusRepositoryUid = {0x200159C9}; + +/** +* KMaxHeaderDataLength8. Maximun number of data bytes reserved for ODT-header. +* This is same as the maximum file path length expressed in unicode chars +*/ +const TInt KMaxHeaderDataLength8=512; + +/** KHeaderListGranularity. List granularity used in header listing operations: */ +const TInt KHeaderListGranularity = 8; + +/** +* KHeaderListUpdatePollingTimeSpan. The time between the subsequent +* request to check changes in Definition Repository. +* The value is expressed in microseconds. +*/ +const TInt KHeaderListUpdatePollingTimeSpan = 1000000; + +/** +* @deprecated KMaxElementDataLength. The maximum size of buffer reserved to +* internalize theme. +*/ +const TInt KMaxElementDataLength = 1048576; + +/** +* KPathListGranularity. Controls the granularity of the path list retrieved +* from Definition Repository. +*/ +const TInt KPathListGranularity = 4; + + +/** +* KMahspsumberOfThemeLoadRepeats. Controls the maximum number of repeats when delivering +* the application theme and its resource list data in memory chunk +* from the server side to the client size. Value 0 means infinite repeats. +*/ +const TInt KMahspsumberOfThemeLoadRepeats = 10; // value 0 means infinite repeats. + +/** +* KThemeLoadRepeatWaitTime. Controls the time to wait between the +* tryes to delivere application theme and its resource list data from the server +* side to the client size. +*/ +const TInt KThemeLoadRepeatWaitTime = 5000000; // 5 seconds + +/** +* KActiveThemeUpdatePollingTimeSpan. +* Constant KActiveThemeUpdatePollingTimeSpan controls the time slice +* between the checking the theme status change theme and/or resource updates. +* The value is expressed in microseconds. +*/ +const TInt KActiveThemeUpdatePollingTimeSpan = 1000000; // 1 second + +const TInt KMaxPluginIdLenght = 8; + +/** +* KThemeInvalidatedTimeSpan +* Controls the time to wait for client application to notify it has rendered the theme +* successfully. If the notification is not received in time (or clientsession crashes) +* the default operator or licensee theme is restored. +* +* When client app. starts it requests theme with GetOdt-request +* After the client receives the theme it starts rendering it. +* After succesfull rendering the client app subscribes for theme updates +* with GetODTUpdate-request. ThemeServer starts a timer when receiving +* GetODT and if no GetODTUpdate- request if received before the timer expires +* the default operator or licensee theme is restored. +* +*/ +const TInt KThemeInvalidatedTimeSpan = 120000000; + +/** + * Client initiated service requests: an enumeration of function indexes + * + * NOTE: hspsThemeRanges array in hspsThemeServer.h file needs to be in sync with the following enumerations, + * failing to do so results in -5 (Not supported) errors. + * + */ +enum ThspsServiceRequestMessage + { + + /************************************** + * Installation related requests: + *************************************/ + EhspsInstallationBase = 0, + + /** + * EhspsInstallTheme. + * Initiates synchronous and asynhronous theme installation process. + */ + EhspsInstallTheme = EhspsInstallationBase, + + /** + * EhspsInstallNextPhase: + * Promotes subsequent asyncronous installation phases + * and offers client process a point to cancel installation. + */ + EhspsInstallNextPhase, + + /** + * EhspsCancelInstallTheme: + * Cancels asynchronous installation process. + */ + EhspsCancelInstallTheme, + + /** + * EhspsReinstallConf: + * Initiates synchronous configuration's reinstallation process + */ + EhspsReinstallConf, + + + /************************************** + * Maintenance related requests: + *************************************/ + EhspsMaintenanceBase, + + /** + * EhspsGetListHeaders. + * Initiates listings of theme headers by setting a query on server. + */ + EhspsGetListHeaders = EhspsMaintenanceBase, + + /** + * EhspsGetNextHeader: + * Subscribes updates for received header list. + */ + EhspsGetNextHeader, + + /** + * EhspsCancelGetListHeaders. + * Cancels a subscription of header list updates. + */ + EhspsCancelGetListHeaders, + + /** + * EhspsSetActiveTheme. + * Theme activation. + */ + EhspsSetActiveTheme, + + /** + * EhspsRestoreDefault. + * Restores the default theme in next order: + * 1. Restore the user default theme if one exists. + * 2. Restore the operatot default theme if one exist. + * 3. Finally, as the last resource, restore the licensee default theme. + * Licencee default theme is located on ROM (Z-drive), therefore it is + * quaranteed that application is in working condition allways. + */ + EhspsRestoreDefault, + + /** + * EhspsRemoveTheme. + * Removes a given theme with all its dependent files and + * settings. Does not remove the theme which is currently active. + * Cannot remove the licencee default theme located on ROM, however, it can + * remove possible updates on the licencee default them if not active. + */ + EhspsRemoveTheme, + + /** + * EhspsAddPlugin. + * Adds a plug-in configuration into active application configuration. + */ + EhspsAddPlugin, + + /** + * EhspsRemovePlugin. + * Removes a plug-in configuration from active application configuration. + */ + EhspsRemovePlugin, + + /** + * EhspsSetActivePlugin. + * Set active plugin. + */ + EhspsSetActivePlugin, + + /** + * EhspsReplacePlugin. + * Replaces a plug-in in an active application configuration. + */ + EhspsReplacePlugin, + + /** + * EhspsSetSettings. + * Sets settings of plugin in active configuration + */ + EhspsSetPluginSettings, + + /** + * EhspsGetPluginOdt. + * Gets plugin odt by UID + */ + EhspsGetPluginOdt, + + /** + * EhspsMovePlugins + * Updates plugin positions within a configuration + */ + EhspsMovePlugins, + + /** EhspsSetConfState + * Updates configuration's state. + */ + EhspsSetConfState, + + /** EhspsRestoreActiveAppConf + * Restore active application configuration in following order + * 1) Restore application configuration from backup folder + * 2) Activate licensee default restorable configuration + * 3) Reinstall licensee default restorable configuration + */ + EhspsRestoreActiveAppConf, + /** + * Updating plugin configuration + */ + + EhspsUpdatePluginConf, + + /** + * Restores plugin configurations by either removing all plugins + * from the active view or by reinstalling all the ROM based plugins. + */ + EhspsRestoreConfigurations, + + + /************************************** + * Client Request related requests: + *************************************/ + EhspsClientRequestBase, + + /** + * EhspsGetODT: + * Get currently active theme and resource list for specified application. + */ + EhspsGetODT = EhspsClientRequestBase, + + /** + * EhspsGetODTUpdate. + * Subscribes theme status change and theme update messages. + */ + EhspsGetODTUpdate, + + /** + * EhspsCancelGetODTUpdate. + * Cancels a subscription of theme updates. + */ + EhspsCancelGetODTUpdate, + + /** + * EhspsAccessResourceFile. + * Request access to resource file on hspsThemeServer private folder. + */ + EhspsAccessResourceFile, + + /** + * EhspsCopyResources + * Copies resource files to the destination folder. + * Given destination folder is only prefix for actual destination folder. + */ + EhspsCopyResources, + + /************************************** + * Out of range + *************************************/ + EhspsNotSupported + }; + +/** +* ThspsServiceCompletedMessage. Response codes used by client-server +* communication to indicate a result of the completion of requested service. +*/ +enum ThspsServiceCompletedMessage + { +/** Installation related responses: */ + + /** + * EhspsInstallThemeSuccess. Theme installation was successful. + */ + EhspsInstallThemeSuccess, + + /** + * EhspsInstallThemeFailed. Theme instalation was failed. + */ + EhspsInstallThemeFailed, + + /** + * EhspsInstallPhaseSuccess. Installation service was performed an + * installation phase successfully. + */ + EhspsInstallPhaseSuccess, + + /** + * EhspsReinstallConfSuccess. Configuration reinstallation was successful. + */ + EhspsReinstallConfSuccess, + + /** + * EhspsReinstallConfFailed. Configuration reinstalation was failed. + */ + EhspsReinstallConfFailed, + +/** Maintenance: */ + + /** + * EhspsGetListHeadersSuccess. Query of a header list was successful. + * Client must start listen the delivery events. + */ + EhspsGetListHeadersSuccess, + + /** + * EhspsGetListHeadersFailed. Headers cannot be listed. + */ + EhspsGetListHeadersFailed, + + /** + * EhspsGetListHeadersUpdate. A header is arrived. + */ + EhspsGetListHeadersUpdate, + + /** + * EhspsGetListHeadersUpdateData + * EhspsGetListHeadersUpdate for observing low-level API-calls. + */ + EhspsGetListHeadersUpdateData, + + /** + * EhspsGetListHeadersEmpty. Header list is empy - no matching headers on + * current query. Client must clear the list screen. + */ + EhspsGetListHeadersEmpty, + + /** + * EhspsGetListHeadersNoChange. No change in headers. Server side only. + */ + EhspsGetListHeadersNoChange, + + /** + * EhspsGetListHeadersRestart. Header list is canged radiacally. Listing + * must start from the begin. Client must clear the list screen. + */ + EhspsGetListHeadersRestart, + + /** + * EhspsGetListHeadersRestartData. + * EhspsGetListHeadersRestart for observing low-level API-calls. + */ + EhspsGetListHeadersRestartData, + + /** + * EhspsSetActiveThemeSuccess. Theme activation was successful. + */ + EhspsSetActiveThemeSuccess, + + /** + * EhspsSetActiveThemeFailed. Theme activation has failed. + */ + EhspsSetActiveThemeFailed, + + /** + * EhspsRestoreDefaultSuccess. Restoring the default theme was successful. + */ + EhspsRestoreDefaultSuccess, + + /** + * EhspsRestoreDefaultFailed. Restoring the default theme was failed. + */ + EhspsRestoreDefaultFailed, + + /** + * EhspsRemoveThemeSuccess. Theme removal was successful. + */ + EhspsRemoveThemeSuccess, + + /** + * EhspsRemoveThemeFailed. Theme removal was failed. + */ + EhspsRemoveThemeFailed, + + /** + * EhspsAddPluginSuccess. A plugin was added succesfully. + */ + EhspsAddPluginSuccess, + + /** + * EhspsAddPluginFailed. Failed to add a plugin. + */ + EhspsAddPluginFailed, + + /** + * EhspsRemovePluginSuccess. A plugin was removed succesfully. + */ + EhspsRemovePluginSuccess, + + /** + * EhspsRemovePluginFailed. Failed to remove a plugin. + */ + EhspsRemovePluginFailed, + + /** + * EhspsSetActivePluginSuccess. A plugin was activated succesfully. + */ + EhspsSetActivePluginSuccess, + + /** + * EhspsSetActivePluginFailed. Failed to activate a plugin. + */ + EhspsSetActivePluginFailed, + + /** + * EhspsSetSettingsSuccess. A plugin settings was updated succesfully. + */ + EhspsSetPluginSettingsSuccess, + + /** + * EEhspsSetSettingsFailed. Failed to set settings of plugin. + */ + EhspsSetPluginSettingsFailed, + + /** + * EhspsMovePluginsSuccess. A plugins list was updated succesfully. + */ + EhspsMovePluginsSuccess, + + /** + * EhspsMovePluginsFailed. Failed to update a plugins list. + */ + EhspsMovePluginsFailed, + + /** + * EhspsReplacePluginSuccess. A plugin was replace succesfully. + */ + EhspsReplacePluginSuccess, + + /** + * EhspsReplacePluginFailed. Failed to update a plugins list. + */ + EhspsReplacePluginFailed, + + /** + * EhspsGetPluginOdtSuccess. Getting plugin odt was successful. + */ + EhspsGetPluginOdtSuccess, + + /** + * EhspsGetPluginOdtFailed. Failed to get plugin odt. + */ + EhspsGetPluginOdtFailed, + + /** + * EhspsRestoreConfigurationsSuccess. Restoration was successfull. + */ + EhspsRestoreConfigurationsSuccess, + + /** + * EhspsRestoreConfigurationsFailed. Restoration failed. + */ + EhspsRestoreConfigurationsFailed, + + +/* Client Requests: */ + + /** + * EhspsGetODTSuccess. + * ODT and associated resource list (if any) were received successfully. + */ + EhspsGetODTSuccess, + + /** + * EhspsGetODTFailed. ODT was not received. Request failed. + */ + EhspsGetODTFailed, + + /** + * EhspsGetODTLowMemoryStrategy. Memory chunk big enough could not be created + * by the server, switching to low memory strategy. + */ + EhspsGetODTLowMemoryStrategy, + + /** + * EhspsGetODTUpdateSuccess. Subscription of the theme updates and status + * changes was successful. Cient must start observe the server events. + */ + EhspsGetODTUpdateSuccess, + + /** + * EhspsSettingsLoaded. Loading settings for a theme was successful. + */ + EhspsSettingsLoaded, + + /** + * EhspsSettingsLoadFailed. Loading settings for a theme failed. + */ + EhspsSettingsLoadFailed, + + /** + * EhspsSettingsUpdated. Updating settings for a theme was successful. + */ + EhspsSettingsUpdated, + + /** + * EhspsSettingsUpdateFailed. Updating settings for a theme failed. + */ + EhspsSettingsUpdateFailed, + /** + * EhspsGetODTUpdateFailed. + * Subscription of the theme updates and status changes failed. + */ + EhspsGetODTUpdateFailed, + + /** + * EhspsGetODTUpdateStatus. Theme status is changed. + * Client must reset rendering and request theme again. + */ + EhspsGetODTUpdateStatus, + + /** EhspsGetODTUpdateHot. Theme is updated. Client should reload the theme. */ + EhspsGetODTUpdateHot, + + /** + * EhspsGetODTUpdateEmpty. + * No update available. Client may retain subscription. + */ + EhspsGetODTUpdateEmpty, + + /** EhspsGetODTUpdateNone. No update available. Used only on server-side. */ + EhspsGetODTUpdateNone, + + /** + * EhspsAccessResourceFileSuccess. + * Request to get access to a theme resource file was successful. + */ + EhspsAccessResourceFileSuccess, + + /** + * EhspsAccessResourceFileFailed. Request to get access to a theme resource + * file was successful. Possible in due to security fault. + */ + EhspsAccessResourceFileFailed, + +/** Generic: */ + /** + * @deprecated EhspsThemeServiceCanceled. + * Server has cancelled the service request possible in due to client + * cancellation request. Usually this is not handled by client because of + * the cancelled request on client-side. This protocol should not cause any + * problem. + */ + EhspsServiceRequestCanceled, + + /** + * EhspsServiceRequestSheduled. Server has sheduled the asynchronous service + * request. Client must start observe the server events. + */ + EhspsServiceRequestSheduled, + + /** + * EhspsServiceNotSupported. + * Server does not support servinng this request in current implementation. + */ + EhspsServiceNotSupported, + + /** + * EhspsServiceRequestError. Server rejects the service request maybe because + * the semaphore for this service in rised, or The request was violating + * the security. Addidional return Code tells the exact reason. + */ + EhspsServiceRequestError, + + /** + * EhspsResourceCopyFailed. + */ + EhspsResourceCopyFailed, + + /** + * EhspsResourceCopySuccess. + */ + EhspsResourceCopySuccess, + + /** + * Configuration state changed successfully + */ + EhspsSetConfStateSuccess, + + /** + * Configuration state change failed + */ + EhspsSetConfStateFailed, + + /** + * Active application configuration restored successfully + */ + EhspsRestoreActiveAppConfSuccess, + + /** + * Active application configuration restoring failed + */ + EhspsRestoreActiveAppConfFailed, + /** + * Updating plugin configuration failed + */ + EhspsUpdatePluginFailed, + /** + * Updating plugin configuration succeed + */ + EhspsUpdatePluginSuccess, + + /** + * Resolution changed, theme should be changed (emulator environment) + */ + EhspsResolutionChangedUpdate + + }; + + +/** +* ThspsThemeStatus. +* Theme status flag-definitions. Theme status flags are bit-masked. +*/ +enum ThspsThemeStatus + { + /** EhspsThemeStatusNone. Theme has no specific staus. This is a common case. */ + EhspsThemeStatusNone = 0x0000, //0b0000000000000000, + + /** + * EhspsThemeStatusActive. + * This theme is currently activated in scope of its application. + */ + EhspsThemeStatusActive = 0x0001, //0b0000000000000001, + + /** + * EhspsThemeStatusLicenceeDefault. + * This theme is licencee default. It is located on ROM (Z-drive) + */ + EhspsThemeStatusLicenceeDefault = 0x0002, //0b0000000000000010, + + /** EhspsThemeStatusOperatorDefault. This theme is set as operator default. */ + EhspsThemeStatusOperatorDefault = 0x0004, //0b0000000000000100, + + /** EhspsThemeStatusUserDefault. This theme has set as user default. */ + EhspsThemeStatusUserDefault = 0x0008, //0b0000000000001000 + + /** EhspsThemeStatusMakeActive. Activates the theme after installation. */ + EhspsThemeStatusMakeActive = 0x0010, //0b0000000000010000 + + /** EhspsThemeStatusClean. Removes the RAM-installed themes on default restoration. */ + EhspsThemeStatusClean = 0x0020, //0b0000000000100000 + + /** + * EhspsThemeStatusLicenceeRestorable. This theme is restored when licensee default + * theme is restored. When using this flag, the ThemeStatusLicenceeDefault + * -flag is also automatically activated. It is located on ROM (Z-drive) + */ + EhspsThemeStatusLicenceeRestorable = 0x0040, //0b00000000001000000, + + EhspsThemeStatusLocked = 0x0080, //0b00000000010000000, + /** EhspsThemeStatusHitchcock. Indicates that the theme is meant for a Hitchcock application. */ + EhspsThemeStatusHitchcock = 0x0100, //0b00000000100000000 + /** EhspsThemeStatusIncludeControlBlock. Includes control block to ODT when called with hspsGetODT. */ + EhspsThemeStatusIncludeControlBlock = 0x0200 //0b00000001000000000 + }; + + +/** + * ThspsInstallationPhase. + * The phases of the installation state-machine in Installation Service. + * In case of failed or canceled installation, the Roll-back process will take + * place from the phase where the instaaltion was before the failure. + */ +enum ThspsInstallationPhase + { + /** EhspsPhaseIdle. */ + EhspsPhaseIdle, + + /** EhspsPhaseInitialise. Header ok and query validity check */ + EhspsPhaseInitialise, + + /** EhspsPhaseCleanup. */ + EhspsPhaseCleanup, + + /** EhspsPhaseInstallODT. */ + EhspsPhaseInstallSkeleton, + + /** EhspsPhaseImportPlugins. */ + EhspsPhaseImportPlugins, + + /** EhspsPhaseRollBack. */ + EhspsPhaseRollBack + }; + + +/** + * ThspsFamily. + * Identifies resolution for which the widget for designed for. + * Should be in sync with the hspsmanifest.h file. + */ +enum ThspsFamily + { + EhspsFamilyUnknown = 0x00, + EhspsFamilyQvga = 0x01, + EhspsFamilyQvga2 = 0x02, + EhspsFamilyVga = 0x04, + EhspsFamilyVga3 = 0x08, + EhspsFamilyQhd = 0x10, + EhspsFamilyQhd_tch = 0x20, + EhspsFamilyVga_tch = 0x40 + }; + +/** + * ThspsConfigurationType. + * Indentifies the configuration type, which is diffrent for application and plugin themes. + */ +enum ThspsConfigurationType + { + EhspsAppConfiguration = 1, + EhspsViewConfiguration, + EhspsWidgetConfiguration, + EhspsTemplateConfiguration + }; + +/** + * ThspsConfigurationState. + * Indentifies the configuration state + */ +enum ThspsConfigurationState + { + EhspsConfStateNotConfirmed = 1, + EhspsConfStateWaitForConfirmation, + EhspsConfStateConfirmed, + EhspsConfStateError + }; + +/** + * ThspsConfStateChangeFilter + * Indentifies the configuration state change options + */ +enum ThspsConfStateChangeFilter + { + EhspsConfStateChangeNoFilter = 1, + EhspsConfStateChangePlugins + }; + +/** + * ThspsConfiguration. + * A definition for passing several uids from client to server session. + */ +struct ThspsConfiguration + { + // Application uid or Interface uid + TInt rootUid; + + // Theme uid + TInt themeUid; + + // Type of the configuration + ThspsConfigurationType type; + }; + + +/** + * Input parameters for the AddPlugin service + */ +struct ThpsParamAddPlugin + { + TInt appUid; // uid of the application configuration + TInt configurationId; // id of the configuration being modified + TInt pluginUid; // uid of the plugin configuration to be added + TInt positionIndex; // position of the added plugin in the configuration's plugins list + }; + +/** + * Input parameters for the RemovePlugin service + */ +struct ThpsParamRemovePlugin + { + TInt appUid; // uid of the application configuration + TInt pluginId; // id of the plugin configuration instance + }; + +/** + * Input parameters for the ActivatePlugin service + */ +struct ThpsParamSetActivePlugin + { + TInt appUid; // uid of the application configuration + TInt pluginId; // id of the plugin configuration instance + }; + +/** + * Input parameter for the GetSettings service + */ +struct ThspsParamGetPluginOdt + { + TInt appUid; // uid of the application configuration + TInt pluginUid; // uid of the plugin + }; + +/** + * Input parameters for the MovePlugins service + */ +const TInt KMaxPluginIdsLength = 2048; +struct ThpsParamMovePlugins + { + TInt appUid; // uid of the application configuration + TInt configurationId; // id of the configuration being modified + TBuf8 pluginIdsBuf; // descriptor for passing externalized plugin ids + }; + +/** + * Input parameter for the SetConfState service + */ +struct ThspsParamSetConfState + { + TInt appUid; // uid of the application + TInt confId; // id of the configuration + ThspsConfigurationState state; // new configuration state + ThspsConfStateChangeFilter filter; // filter parameter + }; + +/** + * Input parameter for the ReinstallConf service + */ +struct ThspsParamReinstallConf + { + TInt appUid; // uid of the application + TInt confUId; // uid of the reinstalled configuration + }; + +/** + * Input parameter for the RestoreActiveAppConf service + */ +struct ThspsParamRestoreActiveAppConf + { + TInt appUid; // uid of the application + }; + +/** + * Input parameter for the ReplacePlugin service + */ +struct ThspsParamReplacePlugin + { + TInt appUid; // uid of the application + TInt pluginId; // id of the existing plugin to be replaced + TInt confUid; // uid of the new plugin configuration + }; +/** + * Input parameter for the ReplacePlugin service + */ +struct ThspsParamSetPluginSettings + { + TInt pluginId; // id of the existing plugin to be replaced + TBool storingStatus; // storing status telling if modified plugin settings are needed to stored its reference. + }; + +enum ThspsRestore + { + EhspsRestoreAll = 0, // restores plug-ins from eMMC, UDA and ROM + EhspsRestoreRom, // restores plug-ins from ROM + EhspsRestoreViews // removes extra views and empties them + }; + +/** + * Input parameter for the RestoreActiveAppConf service + */ +struct ThspsParamRestoreConfigurations + { + TInt appUid; // uid of the application + ThspsRestore restore; // operation + }; + + +class ChspsODT; +class ChspsResource; +class ChspsDomDocument; +class ChspsRequestNotificationParams; +/** +* Part of HSPS Plugin Configuration Management Service APIs. +* MhspsThemeManagementServiceObserver. Interface definition for the HSPS +* Installation and Maintenance Service related events observation. +* The call-back function HandlehspsClientMessage() must be inplemented by client +* application if it want to handle messages coming from the +* hspsInstallationHandler and hspsMaintenanceHandler. +* For more information of different Installation and Maintenance Service +* related messages, see the documentaion of ThspsServiceCompletedMessage. +* +* @since S60 5.0 +* @ingroup group_hspsclients +*/ +class MhspsThemeManagementServiceObserver + { + public: + + /** + * HandlehspsClientMessage + * + * @since S60 5.0 + * @param aMessage contains a service completion message returned from + * the hspsInstallationHandler and hspsMaintenanceHandler to their + * observer. + */ + virtual void HandlehspsClientMessage(ThspsServiceCompletedMessage aMessage) = 0; + }; + +/** +* Part of HSPS Plugin Configuration Management Service APIs. +* MhspsClientRequestServiceObserver. Interface definition for the HSPS Client +* Request Service events observation. +* The call-back function HandlehspsRequestClientMessage() must be inplemented by +* the client applications if it want to handle messages coming from the +* hspsClientRequestHandler. +* For more information of different Client Request Service related messages, +* see the documentaion of ThspsServiceCompletedMessage. +* +* @since S60 5.0 +* @ingroup group_hspsclients +*/ +class MhspsClientRequestServiceObserver + { + public: + /** + * HandlehspsRequestClientMessage + * + * @since S60 5.0 + * @param aMessage contains a service completion message returned from + * the hspsClientRequestHandler to its observer. + * @param aParams contains data for changes what are observed + */ + virtual void HandlehspsRequestClientMessageL(ThspsServiceCompletedMessage aMessage, ChspsRequestNotificationParams& aParams ) = 0; + }; + +/** +* Part of HSPS Plugin Configuration Management Service APIs. +* MhspsInstallationService. API-definition for HSPS Plugin Installation Service. +* HSPS Plugin Installation Service is intended to serve Homescreen as well as S60 +* legacy applications - expecially the Personalisation Application - with the +* Homescreen Application Configuartion installation functionality. Implementation of this +* interface will offer high- and low-level API-functionality. +* High-level and low-level calls are diffrentiated by their parametrization. +* High-level parametrization is directed to the be used by applications which +* need human readable data and offer a user interface. Low-level +* parametrization is directed to the machine-originated requestors like +* OTA Push or DM (Device Management) sub-systems where data is not needed to +* understand semanticly. +* +* Processing a installation task works in asynchronous mode, howvere, synchronous mode is applied +* everytime the installation is initiated. After checking installation rights and files valididies, +* hsps Theme Server will allow actual installation. Client application must call actual +* installation by commencing next phase execution explicitly. First call of installation returns +* the ODT-header of the teme to be installed. This is to enable previewing information about +* a theme to be installed. In this point, user can accept or decline the installation. +* Installation preview feature is useful expecially in OTA-service cases when user acception on +* theme installation might be selected a a part of user policy settings. +* A theme can include resources that can be imported to the target system as such like some audio +* files etc., however, most of the images must be fitted on to the target device's color depth and +* pixel density. In these cases, the needed conversions will be executed asynchronously on +* server-side. Asynchronous installation is executed in phases - resource by resource. +* Installation phases are promoted automaticly, however, client application can control and +* monitor installation phases, and also cancel installation at any time. If installation is +* canceled, hspsThemeServer initiates roll-back functionality removing inconsistent installation. +* +* Client application must call hspsInstallNextPhase() 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 "Xuikon Manifest File User Guide.doc". +* +* Installation functions can return one of the following +* ThspsServiceCompletedMessage-codes: +* - EhspsInstallThemeSuccess, +* - EhspsInstallPhaseSuccess, or +* - EhspsInstallThemeFailed. +* +* Client application must implement MhspsThemeManagementServiceObserver-interface +* and listen these messages +* mentionaed. 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. +* +* @since S60 5.0 +* @ingroup group_hspsclients +*/ +class MhspsInstallationService + { + public: + /** + * hspsInstallTheme + * + * @since S60 5.0 + * @param aManifestFileName is the full path to the installation script file - a manifest + * file. + * @param aHeader is an empty ChspsODT-object in which a valid ODT-header of the newly + * installed theme will be returned if the request is successful. The use of + * ChspsODT-type parameter follows the high-level parametrization schema. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName, + ChspsODT& aHeader) = 0; + + /** + * hspsInstallTheme + * + * @since S60 5.0 + * @param aManifestFileName is full path of the installation script file - a manifest file + * @param aHeaderData will return ODT-header of the newly installed theme in serialized + * (i.e. marshalled) data mode. This follows the low-level parametrization schema. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName, + TDes8& aHeaderData) = 0; + + /** hspsInstallNextPhase + * + * @since S60 5.0 + * @param aHeader is an empty ChspsODT-object in which a valid ODT-header of the latest + * installation phase completed if the request was successful. + * The use of ChspsODT-type parameter follow the high-level parametrization schema. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsInstallNextPhaseL(ChspsODT& aHeader) = 0; + + /** hspsInstallNextPhase + * + * @since S60 5.0 + * @param aHeaderData will return ODT-header of the latest installation phase in + * serialized (i.e. marshalled) data mode. This follows the low-level + * parametrization schema. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsInstallNextPhaseL(TDes8& aHeaderData) = 0; + + /** hspsCancelInstallTheme + * + * @since S60 5.0 + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsCancelInstallTheme() = 0; + + }; + +/** +* Part of Xuikon Application Theme Management Service APIs. +* MhspsMaintenanceService. API-definition for Xuikon Theme Maintenance Service. +* Xuikon Theme Maintenance Service is intended to serve Xuikon applications as well as S60 legacy +* applications - especially Personalisation Application - with Theme Maintenance Services. +* Theme maintenance can take place after a set of themes are installed by Xuikon Theme Installation +* Service. Maintenance services includes theme listings, theme activation, theme removal, and +* default theme restoring functionality. +* Maintenance functions are presented in high-level and low-level parametrization mode. +* This is the same approach that was introduced with Xuikon Theme Installation Service - to support +* user-intefaces with human-readable high-level elements and on otherhand, machine-originated users +* with low-level data. Most of the maintenance functions are synchronous, only one is asynchronous; +* hspsGetNextHeader(). Others functions are stright forward to use but hspsGetListHeaders(). This will +* be explained next; synchronous call hspsGetListHeaders() initiates the theme header listing by +* passing search mask to Xuikon Theme 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. 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 in some reason. Possible reasons are for e.g. the missing +* rights to list headers queried. +* +* In the near future, there will be s.c. Additional Return Code Support feature available in Xuikon. This code +* 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, perhaps. +* +* Maintenanace functions may also return one of the following codes: +* - EhspsServiceRequestSheduled, or +* - EhspsServiceRequestError. +* +* For explanation of the meanings of these messages, see ThspsServiceCompletedMessage-documentation. +* +* @since S60 5.0 +* @ingroup group_hspsclients +*/ +class MhspsMaintenanceService + { + public: + + /** hspsGetListHeaders + * + * @since S60 5.0 + * @param 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. + * @param aCopyLogos indicates that logo resources should be copied to a private directory + * @param aHeaderList is an list object able to carry ChspsODT-objects. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsGetListHeaders( + const ChspsODT& aSearchMask, + const TBool aCopyLogos, + CArrayPtrFlat& aHeaderList) = 0; + + /** hspsGetListHeaders + * + * @since S60 5.0 + * @param aSearchMaskData is serialized ChspsODT-object. Before serializing, attributes + * in ChspsODT-object were filled to present a search parameters for theme set queried. + * Serialized data parametrisation follows the low-level schema. + * @param aHeaderDataList is an list object able to carry serialized ChspsODT-objects. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsGetListHeaders(const TDesC8& aSearchMaskData, + CArrayPtrSeg& aHeaderDataList) = 0; + + /** hspsGetNextHeader + * + * @since S60 5.0 + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsGetNextHeader() = 0; + + /** hspsCancelGetListHeaders + * + * @since S60 5.0 + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsCancelGetListHeaders() = 0; + + /** hspsSetActiveTheme + * + * @since S60 5.0 + * @param aSetMask represents parameters by which the new theme activation will be done. + * There must be sufficient set of parameters presented, at least a theme UID. + * @param aHeader is an empty ODT-object which will contain the header of activated + * theme on the return of the call. This parametrisation follows the high-level + * schema. There must be sufficient set of parameters presented, at least a theme UID. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsSetActiveTheme(const ChspsODT& aSetMask, + ChspsODT& aHeader) = 0; + + /** hspsSetActiveTheme + * + * @since S60 5.0 + * @param aSetMaskData is externalized version of ChspsODT-object presenting parameters by + * which the new theme activation will be done. There must be sufficient set of + * parameters presented, at least a theme UID. This parametrisation follows the + * low-level schema. + * @param aHeaderData is an empty description for externalized ODT-object data. + * When internalized, this object will contain the header of newly activated theme + * as a result of the call. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsSetActiveTheme(const TDesC8& aSetMaskData, + TDes8& aHeaderData) = 0; + + /** + * hspsRestoreDefault + * + * @since S60 5.0 + * @param aSetMask is an ODT-header paramerized engough to express the theme querid to made + * active. + * @param aHeader is an empty ODT-header object that will contain the header of the theme + * actually made active if the request was successful. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsRestoreDefault(const ChspsODT& aSetMask, + ChspsODT& aHeader) = 0; + + /** hspsRemoveTheme + * + * @since S60 5.0 + * @param aSetMask is an ODT-header parametrized enough to express the theme to be removed. + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsRemoveThemeL(const ChspsODT& aSetMask) = 0; + + /** + * Adds a new plugin configuration to the defined application configuration. + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration to be updated + * @param aConfId is an ID of the configuration being modified + * @param aPluginUid is an UID of the plugin configuration to be added + * @param aPosition is an UID of the added/new plugin configuration instance + * @param aAddedPluginId is an ID of the added plugin configuration + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsAddPlugin( + const TInt aAppUid, + const TInt aConfId, + const TInt aPluginUid, + const TInt aPosition, + TInt& aAddedPluginId ) = 0; + + /** hspsRemovePlugin + * Removes an existing plugin configuration instance from the defined application configuration. + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration to be updated + * @param aPluginId is an ID of the plugin configuration instance to be removed + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsRemovePlugin( + const TInt aAppUid, + const TInt aPluginId ) = 0; + + /** + * Activates plugin. + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration to be updated + * @param aPluginId is an ID of the plugin configuration instance to be activated + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsSetActivePlugin( + const TInt aAppUid, + const TInt aPluginId ) = 0; + + /** + * hspsSetSettings + * @since S60 5.0 + */ + virtual ThspsServiceCompletedMessage hspsSetPluginSettings( + const ChspsODT& aHeader, + const TInt aPluginId, + ChspsDomDocument& aDom, + const TBool aPluginStoringStatus) = 0; + + /** + * Updates plugin positions in an existing plugins list. + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration to be updated + * @param aConfId is an ID of the configuration being updated (parent of the plugins node) + * @param aPluginIdList is an array of plugin IDs for setting the plugin positions + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsMovePluginsL( + const TInt aAppUid, + const TInt aConfId, + const CArrayFixFlat& aPluginIdList ) = 0; + + /** + * Updates configuration's state + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration + * @param aConfId is an ID of the configuration which state is updated + * @param aState is a new state of the configuration + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsSetConfState( + const TInt aAppUid, + const TInt aConfId, + const ThspsConfigurationState aState, + const ThspsConfStateChangeFilter aFilter ) = 0; + + /** + * Restores active application configuration + * @since S60 5.0 + * @param aAppUid identifies the application which configuration is requested to be restored + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsRestoreActiveAppConf( + const TInt aAppUid ) = 0; + + /** + * Updates plugin configuration in all application configurations + * + * @since S60 5.0 + * @param aOdt is odt header information of the plugin configuration + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsPluginUpdateL( + const ChspsODT& aOdt ) = 0; + + /** + * Replaces existing plugin configuration instance in an active application configuration. + * + * @since S60 5.0 + * @param aAppUid identifies the application configuration + * @param aPluginId identifies the plugin to be replaced + * @param aConfUid is an uid of the new plugin configuration + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsReplacePlugin( + const TInt aAppUid, + const TInt aPluginId, + const TInt aConfUid ) = 0; + + }; + +/** +* Part of HSPS Plugin Configuration Management Service APIs. +* MhspsClientRequestService. HSPS Client Request Service API-definition. +* HSPS Client Request Service is intended to serve Rendering Engines with Application Themes +* and their associated resources. Implementation of this interface will provide access to +* HSPS Plugin Configuration database maintained by HSPS Definition Repository aka Plugin Registry. +* Definition Repository maintains plugin configurations 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. Resource-objects are delivered +* to the client side in a resource list which is associated to its theme. Resource list exist only +* if there is any resources belonging to a theme. +* 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. +* +* To initaite theme usage, Rendering Engine must call hspsGetODT(). There is no high-level or +* low-level parametrization used, however, API supports two parametrization mode; retrieving a +* theme with or without resources. The cases of retrieving a theme without resources are currently +* rare, but with partial theme update cases to be implemented with OTA Push and DM-cases, it will +* be quite applicable. +* +* 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 (not yet implemented) +* for the exact reason. Theme load can fail for e.g. for missing rights. +* - EhspsGetODTLowMemoryStrategy. Possible memory low to create memory chunk. Something must do to +* free memory and then try again. +* +* 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 +* theme rendering again. +* +* Rendering Engine can get information of the theme resources through the ChspsResource-objects +* delivered on Resource List. When ChspsODT-object's DOM-document has a reference to some URL, +* the access method to the URL-related resource can be found in ChspsResource-object. +* When access-method is clear, 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. +* +* @since S60 5.0 +* @ingroup group_hspsclients +*/ +class MhspsClientRequestService + { + public: + + /** hspsGetODT + * + * @since S60 5.0 + * @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. + */ + virtual ThspsServiceCompletedMessage hspsGetODT(TInt aAppUid, ChspsODT& aODT) = 0; + + /** hspsGetODTUpdate + * + * @since S60 5.0 + * @return ThspsServiceCompletedMessage expressing the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsGetODTUpdate() = 0; + + /** hspsCancelGetODTUpdate + * + * @since S60 5.0 + * @return ThspsServiceCompletedMessage telling the result of the call. + */ + virtual ThspsServiceCompletedMessage hspsCancelGetODTUpdate() = 0; + + /** hspsAccessResourceFile + * + * @since S60 5.0 + * @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 aConfiguration identifies the application or interface from which the theme is to be found + * @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. + */ + virtual ThspsServiceCompletedMessage hspsAccessResourceFile( + const TDesC& aResourceFileName, + const ThspsConfiguration& aConfiguration, + RFile& aFile) = 0; + }; + +/** +* MhspsSecurityService. +* Part of HSPS Application Theme Management Service APIs. +* +* These functions are the following: +* - control user access on service request, and +* - adjust user access in queries. +* +* Function are explained below: +* +* CheckAccessRightsL() +* -------------------- +* CheckAccessRights function is used to limit client accesses to hsps Theme Server to +* the predefined ones. There will be a hardcoded access list with extension mechanism. +* CheckQueryValidityL() function is used to limit theme request to the set allowed for this +* particular user. For example, S60 Personalisation Application is allowed to operate with +* all themes in theme storage, however, AppShell is limited to operate with it own themes only. +* CheckAccessRightsL() function is called by CPolicyServer when hspsThemeServer receives user +* request. Access rights are hard-coded here for S60 3.1, however, in later versions, +* support for dynamic configuration of access rights must atken care. This would be appropriate +* to solve together TARM-policy implementation. +* +* CheckQueryValidityL() +* ------------------- +* CheckQueryValidityL() function is called by hsps Theme Server's service handlers +* (ChspsInstallionHandler, ChspsMaintenanceHandler, and ChspsClientRequestHandler) for adjusting +* user request to match the access rights level that user actually will have. +* This function is to be called immediately when actual ODT is known. +* In the istallation cases, ODT is known after manifest-file parsing. +* In the maintenanace cases, ODT is known immediately on query. +* In the theme usage cases, ODT is known when it application theme has retrieved from +* UI Definition Repository. +* For instance, if user is requesting the theme listing (message hspsGetListHeaders) with +* application UID set to 0 in query meaning that the query concerns all themes in storage. +* However, if user is not S60 Personalisation Application, the query must not be allowed. +* +* @lib hspsThemeServer.exe +* @since S60 5.0 +* @ingroup group_hspsserver +*/ +class MhspsSecurityService + { + public: + /** CheckL + * + * @since S60 5.0 + * @param aOdt is the ODT of the theme whose policy is checked + */ + virtual void CheckIfLicenseeDefaultExistsL( const ChspsODT& aOdt ) = 0; + + /** + * CheckAccessRightsL + * + * @since S60 5.0 + * @param aMessage is the RMessage2 containing the client request data. + * Client's access rights to the hsps Theme Server is to be checked. + * @return ETrue if request has passed the access rights check, otherwise return EFalse. + */ + virtual TBool CheckAccessRightsL( const RMessage2& aMessage ) = 0; + + }; + +#endif// __hspsTHEMEMANAGEMENT_H__