1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   

    15 *  

    16 *  HSPS Application Theme Management Service APIs

    17 *  ************************************************

    18 *  This file introduces the definitions of the interfaces and constanst to be a base of the

    19 *  implementations of HSPS Application Theme Management services.

    20 *  HSPS Application Theme Management Service APIs are introduced by defining Symbian M-classes

    21 *  for each API-functionality groups. These functionality groups and their correcponding M-classes

    22 *  are the following: 

    23 *  - MhspsInstallationService  - defines services for Application Theme 

    24 *                              installations,

    25 *  - MhspsMaintenanceService   - defines services for listing, activation, 

    26 *                              removing and restoring themes set as default, 

    27 *  - MhspsClientRequestService - defines services for usage of Application Themes,

    28 * 

    29 *  - MhspsThemeManagementServiceObserver - a generic call-back service API to be utilized by client

    30 *    applications of HSPS Theme Management Services, and

    31 *  - MhspsClientRequestServiceObserver - a dedicated interface to define the call-back service to be

    32 *    utilized by clients of HSPS Client Request Service. Typical client of the request service is

    33 *    some rendering engine implementation like HSPS UI Engine.

    34 *

    35 *  Typical HSPS Application Theme Management Service use-cases

    36 *  =============================================================

    37 *  Usage of Application Theme is requested by Rendering Engines. Theme rendering happens when 

    38 *  Application's UI (user interface) is shown on the screen of the target device. Principal

    39 *  requestor of Installation and Maintenanace Service APIs is S60 Personalisation Application. 

    40 *  Personalisation UI will present theme installation and activation functionality to the end-user.

    41 *  Also, HSPS-application itself may want to offer some installation and maintenance 

    42 *  functionality on their menus, for e.g. allow a user select the theme to be used - theme 

    43 *  activation (or hot-swap). Some system services of target devices, like OTAPush or DM (Device

    44 *  Management), may also use installation and maintenance APIs. 

    45 *  This supports operators related use-cases where they want to maintain the customisation of mobile

    46 *  phone applications on-line.

    47 *

    48 *  HSPS UI Manager

    49 *  ***************** 

    50 *  UI Manager is a Symbian Client/Server system which is intended to serve HSPS native 

    51 *  applications - as well as S60-legacy applications - with Application Theme installation, 

    52 *  maintenance and usage related services. UI Manager implements HSPS Application Theme Management

    53 *  Service APIs. 

    54 *

    55 *  Client-side functionality and APIs

    56 *  ==================================

    57 *  In Client/Server system, only Client-side APIs are meaningful to the client

    58 *  applications. Offered client-side APIs are divided in two categories; 

    59 *  hspsClient API and hspsRequestClient API. Both clients run basicly in 

    60 *  asynchronous mode. however, they offers synchronic services also when 

    61 *  appropriate. Clients are are able to delegate server messages to their 

    62 *  client applications. hspsClient API offers application theme installation 

    63 *  and maintenance related services, meanwhile hspsRequestClient API offers 

    64 *  services related to the usage of Application Themes. 

    65 *                 

    66 *  Server-side functionality and APIs

    67 *  ==================================

    68 *

    69 *

    70 *  Security

    71 *  ========

    72 *  Security in using services is quarantied by controlling the rights to list 

    73 *  information of the theme set installed as well as to load individual themes.

    74 *  The access control is based on SECUREID of application process.

    75 *  Security is maintained behind the curtain by means of Symbian EKA2 Kernel 

    76 *  services for Platform Security.

    77 *

    78 *  Scalability

    79 *  ===========

    80 *  Architecture of UI Manager supports scalability in next way: Services 

    81 *  provided on server-side reflects the client-side APIs. Client-side objects 

    82 *  implements exactly the same APIs than services on server-side. This approach

    83 *  is selected to support scalability of the theme management system; 

    84 *  small and one-application systems, for e.g. MP3-player, all services could

    85 *  be implemented on client-side, meanwhile large systems can increase their 

    86 *  performance and features providing powerful and centralised server-side 

    87 *  theme handling operations like OTA Push, theme caching, theme editing etc. 

    88 *  HSPS UI Manager implementation is targeted for medium-wide systems running

    89 *  on Symbian OS 9.x, typically serving multiple applications and operators

    90 *  on-line operations customization on single smartphone.  

    91 *

    92 *  HSPS Utility Classes

    93 *  ======================

    94 *  HSPS Utility Classes are used as parameters in HSPS Application Theme 

    95 *  Management service calls. They are owned by serveice caller. Utility 

    96 *  classes are kind of data objects and therefore they are not defined with 

    97 *  specific interface (M-classes). Utility classes are the following:

    98 *  - ChspsODT, and 

    99 *  - ChspsResource. 

   100 *

   101 *  ChspsODT

   102 *  ------

   103 *  HSPS ChspsODT-class, nick-named ODT (Object Description Tree), class is a

   104 *  base unit of information exchanged in HSPS Application Theme Management 

   105 *  operations. 

   106 *  ODT consist of an header-part and its associated DOM-document member class

   107 *  on which it has a dependency. The header contains all information what is

   108 *  needed to distinquish application themes from each others. 

   109 *  HSPS Application Theme Management services handles mainly these 

   110 *  ODT-headers, however, the DOM-document is accessed for applying theme 

   111 *  updates by Installation Handler and to serve the theme usage requests from

   112 *  Rendering Engines. For more information, see ChspsODT documentation. 

   113 *  

   114 *  ChspsResource

   115 *  -----------

   116 *  HSPS ChspsResource-class defines all information what is needed to maintain

   117 *  resources of Application Theme. Every ChspsResource-objects defines just one 

   118 *  resource source, however, the same resource source coud be referenced

   119 *  multible times inside a theme - resources are usually shared. 

   120 *  HSPS Application Theme Management system supports theme resourcing by 

   121 *  offering resource conversations and storing services, and offering Rendering

   122 *  Engines the following services:

   123 *  1) the way to match a resource quoted in xml- or css-module to the 

   124 *  corresponding resource source, and 2) a secure way to access a resource 

   125 *  through the Symbian Platform Security's process separation wall.

   126 *

   127 *  ChspsResult

   128 *  ---------

   129 *  HSPS ChspsResult-class defines feature called Additional Return Code support

   130 *  for HSPS Application Theme Management Services on service request return.

   131 *  It is quaranteed that ChspsResult-object is always accessible after

   132 *  client request whether the result was successful or not.

   133 *  ChspsResult-class has attributes that informs the result as follows:

   134 *  - iSystemError - Symbian OS returned error code

   135 *  - iHSPSError - HSPS defined error code in HSPS error space

   136 *  - iIntValue1   - additional information relevant the result. 

   137 *  - iIntValue2   - additional information relevant the result.

   138 *

   139 *

   140 *

   141 */

   142 

   143 

   144 #ifndef __hspsTHEMEMANAGEMENT_H__

   145 #define __hspsTHEMEMANAGEMENT_H__

   146 

   147 #include <f32file.h> // RFile

   148 #include <badesca.h> // descriptors

   149 

   150 // --------------------

   151 const TUid KSecureId_Psln =  	{0x10005A32};	// from S60 3.1 Plsn

   152 const TUid KSecureId_RDAS =  	{0x10210EA1};	// 270601889 from S60 3.1 R&D AppShell for Xuikon

   153 const TUid KSecureId_hspsAS =  	{0x101F4CD2};	// 270486738 from S60 3.1 Xuikon AppShell in 3.1 product.

   154 const TUid KSecureId_hsps =    	{0x200159C6};	// HSPS configuration installer (ThemeInstallerCons.exe)

   155 const TUid KSecureId_LE =    	{0x102049AD};

   156 const TUid KSecureId_XTA =   	{0x1020747D}; 	// Xuikon Test Automation

   157 const TUid KSecureId_XKON =  	{0x102049AF}; 	// Xuikon Demo

   158 const TUid KSecureId_hspsAI =  	{0x102750F0}; 	// 271012080 support for Xuikon-based ActiveIdle 

   159 const TUid KSecureId_GS =    	{0x100058EC}; 	// S60 3.1 GS-application(General Settings).

   160 const TUid KSecureId_HUIMenu = 	{0x102828BD}; 

   161 const TUid KSecureId_EUnit = 	{0x20000FB1};

   162 const TUid KSecureId_Test =     {0x200159C5};   // HSPS ThemeManager Testapp (internal folder)

   163 

   164 

   165 // -----------------

   166 

   167 /**  Nokia VID: = VID_DEFAULT */

   168 const TInt Nokia_VID  = 0x101FB657;

   169 

   170 /** 

   171 *   KhspsThemeStatusRepositoryUid. 

   172 *   Central repository entry for HSPS. 

   173 */

   174 const TUid KhspsThemeStatusRepositoryUid = {0x200159C9};

   175 

   176 /** 

   177 *   KMaxHeaderDataLength8. Maximun number of data bytes reserved for ODT-header.

   178 *   This is same as the maximum file path length expressed in unicode chars

   179 */

   180 const TInt KMaxHeaderDataLength8=512;

   181 

   182 /** KHeaderListGranularity. List granularity used in header listing operations: */

   183 const TInt KHeaderListGranularity = 4;

   184 

   185 /** 

   186 *   KHeaderListUpdatePollingTimeSpan. The time between the subsequent 

   187 *   request to check changes in Definition Repository. 

   188 *   The value is expressed in microseconds. 

   189 */

   190 const TInt KHeaderListUpdatePollingTimeSpan = 1000000;

   191 

   192 /** 

   193 *   @deprecated KMaxElementDataLength. The maximum size of buffer reserved to

   194 *   internalize theme. 

   195 */

   196 const TInt KMaxElementDataLength = 1048576;

   197 

   198 /** 

   199 *   KPathListGranularity. Controls the granularity of the path list retrieved

   200 *   from Definition Repository. 

   201 */

   202 const TInt KPathListGranularity = 4;

   203 

   204 

   205 /** 

   206 *   KMahspsumberOfThemeLoadRepeats. Controls the maximum number of repeats when delivering 

   207 *   the application theme and its resource list data in memory chunk

   208 *   from the server side to the client size. Value 0 means infinite repeats.

   209 */

   210 const TInt KMahspsumberOfThemeLoadRepeats = 10; // value 0 means infinite repeats.

   211 

   212 /** 

   213 *   KThemeLoadRepeatWaitTime. Controls the time to wait between the 

   214 *   tryes to delivere application theme and its resource list data from the server 

   215 *   side to the client size.

   216 */

   217 const TInt KThemeLoadRepeatWaitTime = 5000000; // 5 seconds

   218 

   219 /** 

   220 *   KActiveThemeUpdatePollingTimeSpan. 

   221 *   Constant KActiveThemeUpdatePollingTimeSpan controls the time slice 

   222 *   between the checking the theme status change theme and/or resource updates. 

   223 *   The value is expressed in microseconds.

   224 */

   225 const TInt KActiveThemeUpdatePollingTimeSpan = 1000000; // 1 second

   226 

   227 const TInt KMaxPluginIdLenght = 8;

   228 

   229 /** 

   230 *   KThemeInvalidatedTimeSpan

   231 * Controls the time to wait for client application to notify it has rendered the theme

   232 * successfully. If the notification is not received in time (or clientsession crashes)

   233 * the default operator or licensee theme is restored.

   234 *

   235 * When client app. starts it requests theme with GetOdt-request

   236 * After the client receives the theme it starts rendering it. 

   237 * After succesfull rendering the client app subscribes for theme updates

   238 * with GetODTUpdate-request. ThemeServer starts a timer when receiving 

   239 * GetODT and if no GetODTUpdate- request if received before the timer expires

   240 * the default operator or licensee theme is restored.

   241 *

   242 */

   243 const TInt KThemeInvalidatedTimeSpan = 120000000;

   244 

   245 /** 

   246  * Client initiated service requests: an enumeration of function indexes

   247  *  

   248  * NOTE: hspsThemeRanges array in hspsThemeServer.h file needs to be in sync with the following enumerations,

   249  * failing to do so results in -5 (Not supported) errors.

   250  * 

   251  */

   252 enum ThspsServiceRequestMessage

   253   {

   254   

   255   /**************************************

   256    * Installation related requests: 

   257    *************************************/

   258   EhspsInstallationBase = 0,

   259   

   260   /** 

   261    *	EhspsInstallTheme. 

   262    * 	Initiates synchronous and asynhronous theme installation process. 

   263    */

   264   EhspsInstallTheme = EhspsInstallationBase,

   265     

   266   /** 

   267    * 	EhspsInstallNextPhase:

   268    *	Promotes subsequent asyncronous installation phases 

   269    * 	and offers client process a point to cancel installation.    

   270    */

   271   EhspsInstallNextPhase,

   272   

   273   /** 

   274    * 	EhspsCancelInstallTheme:

   275    * 	Cancels asynchronous installation process. 

   276    */

   277   EhspsCancelInstallTheme,

   278 

   279   /** 

   280    *    EhspsReinstallConf:

   281    *    Initiates synchronous configuration's reinstallation process 

   282    */

   283   EhspsReinstallConf,

   284   

   285   

   286   /**************************************

   287    * Maintenance related requests: 

   288    *************************************/  

   289   EhspsMaintenanceBase,

   290   

   291   /** 

   292    *	EhspsGetListHeaders. 

   293    *   	Initiates listings of theme headers by setting a query on server. 

   294    */      

   295   EhspsGetListHeaders = EhspsMaintenanceBase,

   296     

   297   /**	

   298    * 	EhspsGetNextHeader:

   299    * 	Subscribes updates for received header list. 

   300    */ 

   301   EhspsGetNextHeader,

   302   

   303   /**	

   304    * 	EhspsCancelGetListHeaders. 

   305    * 	Cancels a subscription of header list updates. 

   306    */

   307   EhspsCancelGetListHeaders,

   308     

   309   /**	

   310    * 	EhspsSetActiveTheme. 

   311    * 	Theme activation. 

   312    */

   313   EhspsSetActiveTheme,

   314   

   315   /** 

   316    *   	EhspsRestoreDefault. 

   317    *	Restores the default theme in next order: 

   318    *   	1. Restore the user default theme if one exists.

   319    *   	2. Restore the operatot default theme if one exist.

   320    *   	3. Finally, as the last resource, restore the licensee default theme. 

   321    *   	Licencee default theme is located on ROM (Z-drive), therefore it is

   322    *   	quaranteed that application is in working condition allways.

   323    */

   324   EhspsRestoreDefault,

   325   

   326   /** 

   327    *   	EhspsRemoveTheme. 

   328    * 	Removes a given theme with all its dependent files and 

   329    *   	settings. Does not remove the theme which is currently active. 

   330    *   	Cannot remove the licencee default theme located on ROM, however, it can

   331    *   	remove possible updates on the licencee default them if not active.

   332    */

   333   EhspsRemoveTheme,

   334   

   335   /** 

   336    *  	EhspsAddPlugin. 

   337    * 	Adds a plug-in configuration into active application configuration.

   338    */

   339   EhspsAddPlugin,

   340   

   341   /** 

   342    *  	EhspsRemovePlugin. 

   343    * 	Removes a plug-in configuration from active application configuration.

   344    */

   345   EhspsRemovePlugin,

   346 

   347   /** 

   348    *    EhspsSetActivePlugin. 

   349    *    Set active plugin.

   350    */

   351   EhspsSetActivePlugin,

   352 

   353   /** 

   354    *    EhspsReplacePlugin. 

   355    *    Replaces a plug-in in an active application configuration.

   356    */

   357   EhspsReplacePlugin,

   358     

   359   /** 

   360    *    EhspsSetSettings. 

   361    *    Sets settings of plugin in active configuration

   362    */

   363   EhspsSetPluginSettings,

   364   

   365    /** 

   366     *    EhspsGetPluginOdt. 

   367     *    Gets plugin odt by UID

   368     */

   369    EhspsGetPluginOdt,

   370 

   371   /** 

   372    *  	EhspsMovePlugins 

   373    * 	Updates plugin positions within a configuration

   374    */

   375   EhspsMovePlugins,

   376 

   377   /**   EhspsSetConfState 

   378    *    Updates configuration's state. 

   379    */

   380   EhspsSetConfState,

   381 

   382   /**   EhspsRestoreActiveAppConf 

   383    *    Restore active application configuration in following order

   384    *    1) Restore application configuration from backup folder

   385    *    2) Activate licensee default restorable configuration

   386    *    3) Reinstall licensee default restorable configuration  

   387    */

   388   EhspsRestoreActiveAppConf,

   389   /** 

   390    *  Updating plugin configuration

   391    */

   392     

   393   EhspsUpdatePluginConf,

   394   

   395 

   396   /**************************************

   397    * Client Request related requests: 

   398    *************************************/

   399   EhspsClientRequestBase,

   400   

   401   /** 

   402    *   	EhspsGetODT:

   403    *	Get currently active theme and resource list for specified application.    

   404    */    

   405   EhspsGetODT = EhspsClientRequestBase,  

   406     

   407   /** 

   408    * 	EhspsGetODTUpdate. 

   409    * 	Subscribes theme status change and theme update messages.  

   410    */

   411   EhspsGetODTUpdate,

   412     

   413   /**

   414    * 	EhspsCancelGetODTUpdate. 

   415    * 	Cancels a subscription of theme updates. 

   416    */

   417   EhspsCancelGetODTUpdate,

   418     

   419   /** 

   420    *   	EhspsAccessResourceFile. 

   421    *	Request access to resource file on hspsThemeServer private folder.

   422    */

   423   EhspsAccessResourceFile,

   424     

   425   /**

   426    *    EhspsCopyResources

   427    *    Copies resource files to the destination folder.

   428    *    Given destination folder is only prefix for actual destination folder.

   429    */

   430   EhspsCopyResources,

   431   

   432   /**************************************

   433    *	Out of range 

   434    *************************************/  

   435   EhspsNotSupported  

   436   };

   437   

   438 /** 

   439 *  ThspsServiceCompletedMessage. Response codes used by client-server 

   440 *  communication to indicate a result of the completion of requested service. 

   441 */    

   442 enum ThspsServiceCompletedMessage

   443     {

   444 /** Installation related responses: */

   445 

   446     /** 

   447      * EhspsInstallThemeSuccess. Theme installation was successful. 

   448      */

   449     EhspsInstallThemeSuccess,

   450 

   451     /** 

   452      *  EhspsInstallThemeFailed. Theme instalation was failed. 

   453      */

   454     EhspsInstallThemeFailed,

   455         

   456     /** 

   457     *   EhspsInstallPhaseSuccess. Installation service was performed an 

   458     *   installation phase successfully. 

   459     */

   460     EhspsInstallPhaseSuccess, 

   461 

   462     /** 

   463      * EhspsReinstallConfSuccess. Configuration reinstallation was successful. 

   464      */

   465     EhspsReinstallConfSuccess,

   466 

   467     /** 

   468      *  EhspsReinstallConfFailed. Configuration reinstalation was failed. 

   469      */

   470     EhspsReinstallConfFailed,

   471 

   472 /** Maintenance: */

   473     

   474     /** 

   475     *   EhspsGetListHeadersSuccess. Query of a header list was successful. 

   476     *   Client must start listen the delivery events.

   477     */

   478     EhspsGetListHeadersSuccess,    

   479     

   480     /** 

   481      *   EhspsGetListHeadersFailed. Headers cannot be listed. 

   482      */

   483     EhspsGetListHeadersFailed, 

   484     

   485     /** 

   486      *   EhspsGetListHeadersUpdate. A header is arrived. 

   487      */

   488     EhspsGetListHeadersUpdate, 

   489     

   490     /** 

   491      *  EhspsGetListHeadersUpdateData

   492      *  EhspsGetListHeadersUpdate for observing low-level API-calls. 

   493      */

   494     EhspsGetListHeadersUpdateData, 

   495     

   496     /** 

   497      *   EhspsGetListHeadersEmpty. Header list is empy - no matching headers on 

   498      *   current query. Client must clear the list screen. 

   499      */

   500     EhspsGetListHeadersEmpty,

   501       

   502     /** 

   503      *   EhspsGetListHeadersNoChange. No change in headers. Server side only. 

   504      */

   505     EhspsGetListHeadersNoChange,

   506    

   507     /** 

   508      *   EhspsGetListHeadersRestart. Header list is canged radiacally. Listing 

   509      *   must start from the begin. Client must clear the list screen. 

   510      */

   511     EhspsGetListHeadersRestart,

   512     

   513     /** 

   514      *   EhspsGetListHeadersRestartData. 

   515      *   EhspsGetListHeadersRestart for observing low-level API-calls.

   516      */

   517     EhspsGetListHeadersRestartData,

   518     

   519     /** 

   520      * EhspsSetActiveThemeSuccess. Theme activation was successful. 

   521      */ 

   522     EhspsSetActiveThemeSuccess, 

   523     

   524     /** 

   525      * EhspsSetActiveThemeFailed. Theme activation has failed. 

   526      */

   527     EhspsSetActiveThemeFailed, 

   528     

   529     /** 

   530      * EhspsRestoreDefaultSuccess. Restoring the default theme was successful. 

   531      */

   532     EhspsRestoreDefaultSuccess,

   533     

   534     /** 

   535      * EhspsRestoreDefaultFailed. Restoring the default theme was failed. 

   536      */

   537     EhspsRestoreDefaultFailed,

   538     

   539     /** 

   540      * EhspsRemoveThemeSuccess. Theme removal was successful. 

   541      */

   542     EhspsRemoveThemeSuccess, 

   543     

   544     /** 

   545      * EhspsRemoveThemeFailed. Theme removal was failed. 

   546      */

   547     EhspsRemoveThemeFailed,

   548     

   549     /** 

   550      * EhspsAddPluginSuccess. A plugin was added succesfully. 

   551      */

   552     EhspsAddPluginSuccess,

   553     

   554     /** 

   555      * EhspsAddPluginFailed. Failed to add a plugin. 

   556      */

   557     EhspsAddPluginFailed,

   558     

   559     /** 

   560      * EhspsRemovePluginSuccess. A plugin was removed succesfully. 

   561      */

   562     EhspsRemovePluginSuccess,

   563     

   564     /** 

   565      * EhspsRemovePluginFailed. Failed to remove a plugin. 

   566      */

   567     EhspsRemovePluginFailed,

   568 

   569     /** 

   570      * EhspsSetActivePluginSuccess. A plugin was activated succesfully. 

   571      */

   572     EhspsSetActivePluginSuccess,    

   573 

   574     /** 

   575      * EhspsSetActivePluginFailed. Failed to activate a plugin. 

   576      */

   577     EhspsSetActivePluginFailed,    

   578     

   579     /** 

   580      * EhspsSetSettingsSuccess. A plugin settings was updated succesfully. 

   581      */

   582     EhspsSetPluginSettingsSuccess,

   583         

   584     /** 

   585      * EEhspsSetSettingsFailed. Failed to set settings of plugin. 

   586      */

   587     EhspsSetPluginSettingsFailed,

   588     

   589     /** 

   590      * EhspsMovePluginsSuccess. A plugins list was updated succesfully. 

   591      */

   592     EhspsMovePluginsSuccess,

   593 

   594     /** 

   595      * EhspsMovePluginsFailed. Failed to update a plugins list.

   596      */

   597     EhspsMovePluginsFailed,

   598 

   599     /** 

   600      * EhspsReplacePluginSuccess. A plugin was replace succesfully. 

   601      */

   602     EhspsReplacePluginSuccess,

   603 

   604     /** 

   605      * EhspsReplacePluginFailed. Failed to update a plugins list.

   606      */

   607     EhspsReplacePluginFailed,

   608     

   609     /**

   610      *  EhspsGetPluginOdtSuccess. Getting plugin odt was successful.

   611      */

   612     EhspsGetPluginOdtSuccess,

   613     

   614     /** 

   615      * EhspsGetPluginOdtFailed. Failed to get plugin odt.

   616      */

   617     EhspsGetPluginOdtFailed,

   618     

   619 /* Client Requests: */

   620     

   621     /** 

   622     *   EhspsGetODTSuccess. 

   623     *   ODT and associated resource list (if any) were received successfully. 

   624     */

   625     EhspsGetODTSuccess, 

   626     

   627     /** 

   628      * EhspsGetODTFailed. ODT was not received. Request failed.

   629      */

   630     EhspsGetODTFailed,

   631     

   632     /** 

   633     *   EhspsGetODTLowMemoryStrategy. Memory chunk big enough could not be created

   634     *   by the server, switching to low memory strategy. 

   635     */

   636     EhspsGetODTLowMemoryStrategy,

   637     

   638     /** 

   639     *   EhspsGetODTUpdateSuccess. Subscription of the theme updates and status 

   640     *   changes was successful. Cient must start observe the server events. 

   641     */

   642     EhspsGetODTUpdateSuccess,

   643     

   644     /**

   645     * 	EhspsSettingsLoaded. Loading settings for a theme was successful.

   646     */

   647     EhspsSettingsLoaded,

   648     

   649     /**

   650     *	EhspsSettingsLoadFailed. Loading settings for a theme failed.

   651     */

   652     EhspsSettingsLoadFailed,

   653     

   654     /**

   655     *	EhspsSettingsUpdated. Updating settings for a theme was successful.

   656     */

   657     EhspsSettingsUpdated,

   658     

   659     /**

   660     *	EhspsSettingsUpdateFailed. Updating settings for a theme failed.

   661     */

   662     EhspsSettingsUpdateFailed,

   663     /** 

   664     *   EhspsGetODTUpdateFailed. 

   665     *   Subscription of the theme updates and status changes failed. 

   666     */

   667     EhspsGetODTUpdateFailed, 

   668     

   669     /** 

   670     *   EhspsGetODTUpdateStatus. Theme status is changed. 

   671     *   Client must reset rendering and request theme again. 

   672     */

   673     EhspsGetODTUpdateStatus, 

   674     

   675     /** EhspsGetODTUpdateHot. Theme is updated. Client should reload the theme. */

   676     EhspsGetODTUpdateHot,

   677   

   678     /** 

   679     *   EhspsGetODTUpdateEmpty. 

   680     *   No update available. Client may retain subscription. 

   681     */

   682     EhspsGetODTUpdateEmpty,

   683   

   684     /** EhspsGetODTUpdateNone. No update available. Used only on server-side. */

   685     EhspsGetODTUpdateNone,

   686 

   687     /** 

   688     *   EhspsAccessResourceFileSuccess. 

   689     *   Request to get access to a theme resource file was successful. 

   690     */

   691     EhspsAccessResourceFileSuccess,

   692     

   693     /** 

   694     *   EhspsAccessResourceFileFailed. Request to get access to a theme resource

   695     *   file was successful. Possible in due to security fault.

   696     */

   697     EhspsAccessResourceFileFailed,

   698     

   699 /** Generic: */

   700     /** 

   701     *   @deprecated EhspsThemeServiceCanceled. 

   702     *   Server has cancelled the service request possible in due to client 

   703     *   cancellation request. Usually this is not handled by client because of

   704     *   the cancelled request on client-side. This protocol should not cause any

   705     *   problem.

   706     */  

   707     EhspsServiceRequestCanceled,    

   708     

   709     /** 

   710     *   EhspsServiceRequestSheduled. Server has sheduled the asynchronous service 

   711     *   request. Client must start observe the server events. 

   712     */

   713     EhspsServiceRequestSheduled,

   714     

   715     /** 

   716     *   EhspsServiceNotSupported. 

   717     *   Server does not support servinng this request in current implementation.

   718     */

   719     EhspsServiceNotSupported,

   720     

   721     /** 

   722     *   EhspsServiceRequestError. Server rejects the service request maybe because

   723     *   the semaphore for this service in rised, or The request was violating 

   724     *   the security. Addidional return Code tells the exact reason.

   725     */  

   726     EhspsServiceRequestError,

   727     

   728     /** 

   729     *   EhspsResourceCopyFailed.

   730     */  

   731     EhspsResourceCopyFailed,

   732 

   733     /** 

   734     *   EhspsResourceCopySuccess.

   735     */  

   736     EhspsResourceCopySuccess,

   737 

   738     /** 

   739     *  Configuration state changed successfully

   740     */  

   741     EhspsSetConfStateSuccess,

   742 

   743     /** 

   744     *  Configuration state change failed

   745     */  

   746     EhspsSetConfStateFailed,

   747 

   748     /** 

   749     *  Active application configuration restored successfully

   750     */  

   751     EhspsRestoreActiveAppConfSuccess,

   752 

   753     /** 

   754     *  Active application configuration restoring failed

   755     */  

   756     EhspsRestoreActiveAppConfFailed,

   757     /** 

   758     *  Updating plugin configuration failed

   759     */

   760     EhspsUpdatePluginFailed,

   761     /** 

   762      *  Updating plugin configuration succeed

   763      */ 

   764     EhspsUpdatePluginSuccess,

   765     

   766     /**

   767     * Resolution changed, theme should be changed (emulator environment) 

   768     */

   769     EhspsResolutionChangedUpdate    

   770 

   771     };  

   772 

   773  

   774 /** 

   775 *   ThspsThemeStatus. 

   776 *   Theme status flag-definitions. Theme status flags are bit-masked. 

   777 */

   778 enum ThspsThemeStatus

   779   {

   780   /** EhspsThemeStatusNone. Theme has no specific staus. This is a common case. */

   781   EhspsThemeStatusNone            = 0x0000, //0b0000000000000000,

   782   

   783   /** 

   784   *   EhspsThemeStatusActive. 

   785   *   This theme is currently activated in scope of its application. 

   786   */

   787   EhspsThemeStatusActive          = 0x0001, //0b0000000000000001,

   788   

   789   /** 

   790   *   EhspsThemeStatusLicenceeDefault. 

   791   *   This theme is licencee default. It is located on ROM (Z-drive) 

   792   */

   793   EhspsThemeStatusLicenceeDefault = 0x0002, //0b0000000000000010,

   794   

   795   /** EhspsThemeStatusOperatorDefault. This theme is set as operator default. */

   796   EhspsThemeStatusOperatorDefault = 0x0004, //0b0000000000000100,

   797   

   798   /** EhspsThemeStatusUserDefault. This theme has set as user default. */

   799   EhspsThemeStatusUserDefault     = 0x0008,  //0b0000000000001000

   800   

   801   /** EhspsThemeStatusMakeActive. Activates the theme after installation. */

   802   EhspsThemeStatusMakeActive     = 0x0010,  //0b0000000000010000

   803 

   804   /** EhspsThemeStatusClean. Removes the RAM-installed themes on default restoration. */

   805   EhspsThemeStatusClean    = 0x0020,  //0b0000000000100000

   806   

   807   /** 

   808   *   EhspsThemeStatusLicenceeRestorable. This theme is restored when licensee default 

   809   *   theme is restored. When using this flag, the ThemeStatusLicenceeDefault

   810   *   -flag is also automatically activated. It is located on ROM (Z-drive) 

   811   */

   812   EhspsThemeStatusLicenceeRestorable = 0x0040, //0b00000000001000000,

   813   

   814   EhspsThemeStatusLocked = 0x0080, //0b00000000010000000,

   815   /** EhspsThemeStatusHitchcock. Indicates that the theme is meant for a Hitchcock application. */

   816   EhspsThemeStatusHitchcock = 0x0100, //0b00000000100000000

   817   /** EhspsThemeStatusIncludeControlBlock. Includes control block to ODT when called with hspsGetODT. */

   818   EhspsThemeStatusIncludeControlBlock = 0x0200 //0b00000001000000000

   819   };  

   820 

   821 

   822 /**

   823  *   ThspsInstallationPhase.

   824  *   The phases of the installation state-machine in Installation Service. 

   825  *   In case of failed or canceled installation, the Roll-back process will take 

   826  *   place from the phase where the instaaltion was before the failure.

   827  */

   828 enum ThspsInstallationPhase

   829   {

   830   /** EhspsPhaseIdle. */

   831   EhspsPhaseIdle,  

   832   

   833   /** EhspsPhaseInitialise. Header ok and query validity check */

   834   EhspsPhaseInitialise,

   835   

   836   /** EhspsPhaseCleanup. */

   837   EhspsPhaseCleanup,

   838       

   839   /** EhspsPhaseInstallODT. */

   840   EhspsPhaseInstallSkeleton,

   841   

   842   /** EhspsPhaseImportPlugins. */

   843   EhspsPhaseImportPlugins,

   844     

   845   /** EhspsPhaseRollBack. */

   846   EhspsPhaseRollBack

   847   };

   848 

   849 

   850 /**

   851  * ThspsFamily.

   852  * Identifies resolution for which the widget for designed for.

   853  * Should be in sync with the hspsmanifest.h file. 

   854  */

   855 enum ThspsFamily

   856     {

   857     EhspsFamilyUnknown = 0x00,

   858     EhspsFamilyQvga = 0x01,

   859     EhspsFamilyQvga2 = 0x02,

   860     EhspsFamilyVga = 0x04,

   861     EhspsFamilyVga3 = 0x08,

   862     EhspsFamilyQhd = 0x10,

   863     EhspsFamilyQhd_tch = 0x20,

   864     EhspsFamilyVga_tch = 0x40

   865     };

   866 

   867 /**

   868  * ThspsConfigurationType.

   869  * Indentifies the configuration type, which is diffrent for application and plugin themes.  

   870  */

   871 enum ThspsConfigurationType

   872     {

   873     EhspsAppConfiguration = 1,

   874     EhspsViewConfiguration,

   875     EhspsWidgetConfiguration,

   876     EhspsTemplateConfiguration    

   877     };

   878 

   879 /**

   880  * ThspsConfigurationState.

   881  * Indentifies the configuration state  

   882  */

   883 enum ThspsConfigurationState

   884     {

   885     EhspsConfStateNotConfirmed = 1,

   886     EhspsConfStateWaitForConfirmation,

   887     EhspsConfStateConfirmed,

   888     EhspsConfStateError  

   889     };

   890 

   891 /**

   892  * ThspsConfStateChangeFilter

   893  * Indentifies the configuration state change options

   894  */

   895 enum ThspsConfStateChangeFilter

   896     {

   897     EhspsConfStateChangeNoFilter = 1,

   898     EhspsConfStateChangePlugins

   899     };

   900 

   901 /**

   902  * ThspsConfiguration.

   903  * A definition for passing several uids from client to server session.

   904  */

   905 struct ThspsConfiguration

   906     {

   907     // Application uid or Interface uid

   908     TInt rootUid;

   909     

   910     // Theme uid

   911     TInt themeUid;

   912     

   913     // Type of the configuration

   914     ThspsConfigurationType type;

   915     };

   916 

   917 

   918 /**

   919  * Input parameters for the AddPlugin service

   920  */

   921 struct ThpsParamAddPlugin

   922 	{

   923 	TInt appUid;					// uid of the application configuration

   924 	TInt configurationId;			// id of the configuration being modified 

   925 	TInt pluginUid;					// uid of the plugin configuration to be added

   926 	TInt positionIndex;				// position of the added plugin in the configuration's plugins list 

   927 	};

   928 

   929 /**

   930  * Input parameters for the RemovePlugin service

   931  */

   932 struct ThpsParamRemovePlugin

   933     {

   934     TInt appUid;                    // uid of the application configuration

   935     TInt pluginId;                    // id of the plugin configuration instance

   936     };

   937 

   938 /**

   939  * Input parameters for the ActivatePlugin service

   940  */

   941 struct ThpsParamSetActivePlugin

   942     {

   943     TInt appUid;                    // uid of the application configuration

   944     TInt pluginId;                  // id of the plugin configuration instance

   945     };

   946 

   947 /**

   948  * Input parameter for the GetSettings service 

   949  */

   950 struct ThspsParamGetPluginOdt

   951 	{

   952 	TInt appUid;					// uid of the application configuration

   953 	TInt pluginUid;					// uid of the plugin

   954 	};

   955 

   956 /**

   957  * Input parameters for the MovePlugins service

   958  */

   959 const TInt KMaxPluginIdsLength = 2048;

   960 struct ThpsParamMovePlugins

   961 	{

   962 	TInt appUid;					// uid of the application configuration

   963 	TInt configurationId;			// id of the configuration being modified 

   964 	TBuf8<KMaxPluginIdsLength> pluginIdsBuf; // descriptor for passing externalized plugin ids

   965 	};

   966 

   967 /**

   968  * Input parameter for the SetConfState service 

   969  */

   970 struct ThspsParamSetConfState

   971     {

   972     TInt appUid;                       // uid of the application

   973     TInt confId;                       // id of the configuration

   974     ThspsConfigurationState state;     // new configuration state

   975     ThspsConfStateChangeFilter filter; // filter parameter

   976     };

   977 

   978 /**

   979  * Input parameter for the ReinstallConf service 

   980  */

   981 struct ThspsParamReinstallConf

   982     {

   983     TInt appUid;                    // uid of the application

   984     TInt confUId;                   // uid of the reinstalled configuration

   985     };

   986 

   987 /**

   988  * Input parameter for the RestoreActiveAppConf service 

   989  */

   990 struct ThspsParamRestoreActiveAppConf

   991     {

   992     TInt appUid;                    // uid of the application

   993     TInt confUid;                   // uid of the restored configuration

   994     };

   995 

   996 /**

   997  * Input parameter for the ReplacePlugin service 

   998  */

   999 struct ThspsParamReplacePlugin

  1000     {

  1001     TInt appUid;                    // uid of the application

  1002     TInt pluginId;                  // id of the existing plugin to be replaced

  1003     TInt confUid;                   // uid of the new plugin configuration

  1004     };

  1005 /**

  1006  * Input parameter for the ReplacePlugin service 

  1007  */

  1008 struct ThspsParamSetPluginSettings

  1009     {

  1010     TInt pluginId;                  // id of the existing plugin to be replaced

  1011     TBool storingStatus;            // storing status telling if modified plugin settings are needed to stored its reference.

  1012     };

  1013 

  1014 

  1015 class ChspsODT;

  1016 class ChspsResource;

  1017 class ChspsDomDocument;

  1018 class ChspsRequestNotificationParams;

  1019 /**

  1020 *  Part of HSPS Plugin Configuration Management Service APIs.

  1021 *  MhspsThemeManagementServiceObserver. Interface definition for the HSPS 

  1022 *  Installation and Maintenance Service related events observation.

  1023 *  The call-back function HandlehspsClientMessage() must be inplemented by client 

  1024 *  application if it want to handle messages coming from the 

  1025 *  hspsInstallationHandler and hspsMaintenanceHandler. 

  1026 *  For more information of different Installation and Maintenance Service 

  1027 *  related messages, see the documentaion of ThspsServiceCompletedMessage.

  1028 *

  1029 *  @since S60 5.0

  1030 *  @ingroup group_hspsclients

  1031 */

  1032 class MhspsThemeManagementServiceObserver

  1033     {

  1034     public:

  1035                 

  1036         /**

  1037         * HandlehspsClientMessage

  1038         * 

  1039         * @since S60 5.0

  1040         * @param aMessage contains a service completion message returned from 

  1041         *        the hspsInstallationHandler and hspsMaintenanceHandler to their 

  1042         *        observer.

  1043         */

  1044         virtual void HandlehspsClientMessage(ThspsServiceCompletedMessage aMessage) = 0;

  1045     };

  1046 

  1047 /**

  1048 *  Part of HSPS Plugin Configuration Management Service APIs.

  1049 *  MhspsClientRequestServiceObserver. Interface definition for the HSPS Client 

  1050 *  Request Service events observation. 

  1051 *  The call-back function HandlehspsRequestClientMessage() must be inplemented by

  1052 *  the client applications if it want to handle messages coming from the 

  1053 *  hspsClientRequestHandler. 

  1054 *  For more information of different Client Request Service related messages, 

  1055 *  see the documentaion of ThspsServiceCompletedMessage.

  1056 *

  1057 *  @since S60 5.0

  1058 *  @ingroup group_hspsclients

  1059 */

  1060 class MhspsClientRequestServiceObserver

  1061     {

  1062     public:

  1063         /**

  1064         * HandlehspsRequestClientMessage

  1065         * 

  1066         * @since S60 5.0

  1067         * @param aMessage contains a service completion message returned from 

  1068         *        the hspsClientRequestHandler to its observer.

  1069         * @param aParams contains data for changes what are observed

  1070         */

  1071         virtual void HandlehspsRequestClientMessageL(ThspsServiceCompletedMessage aMessage, ChspsRequestNotificationParams& aParams ) = 0;

  1072     };

  1073 

  1074 /**

  1075 *  Part of HSPS Plugin Configuration Management Service APIs.

  1076 *  MhspsInstallationService. API-definition for HSPS Plugin Installation Service.

  1077 *  HSPS Plugin Installation Service is intended to serve Homescreen as well as S60 

  1078 *  legacy applications - expecially the Personalisation Application - with the 

  1079 *  Homescreen Application Configuartion installation functionality. Implementation of this 

  1080 *  interface will offer high- and low-level API-functionality. 

  1081 *  High-level and low-level calls are diffrentiated by their parametrization. 

  1082 *  High-level parametrization is directed to the be used by applications which 

  1083 *  need human readable data and offer a user interface. Low-level 

  1084 *  parametrization is directed to the machine-originated requestors like 

  1085 *  OTA Push or DM (Device Management) sub-systems where data is not needed to

  1086 *  understand semanticly.

  1087 *

  1088 *  Processing a installation task works in asynchronous mode, howvere, synchronous mode is applied 

  1089 *  everytime the installation is initiated. After checking installation rights and files valididies,

  1090 *  hsps Theme Server will allow actual installation. Client application must call actual  

  1091 *  installation by commencing next phase execution explicitly. First call of installation returns 

  1092 *  the ODT-header of the teme to be installed. This is to enable previewing information about 

  1093 *  a theme to be installed. In this point, user can accept or decline the installation. 

  1094 *  Installation preview feature is useful expecially in OTA-service cases when user acception on 

  1095 *  theme installation might be selected a a part of user policy settings.

  1096 *  A theme can include resources that can be imported to the target system as such like some audio

  1097 *  files etc., however, most of the images must be fitted on to the target device's color depth and

  1098 *  pixel density. In these cases, the needed conversions will be executed asynchronously on 

  1099 *  server-side. Asynchronous installation is executed in phases - resource by resource. 

  1100 *  Installation phases are promoted automaticly, however, client application can control and 

  1101 *  monitor installation phases, and also cancel installation at any time. If installation is 

  1102 *  canceled, hspsThemeServer initiates roll-back functionality removing inconsistent installation.  

  1103 *

  1104 *  Client application must call hspsInstallNextPhase() after testing that the synchronous call 

  1105 *  hspsInstallTheme() has returned EhspsInstallPhaseSuccess return code signalling that actual 

  1106 *  installation is allowed. The rest of the installation phases will be executed automatically,

  1107 *  however, installation can be interrupted by calling hspsCancelInstallTheme() at any time. 

  1108 *  If installation is canceled, hspsThemeServer initiates roll-back functionality removing

  1109 *  inconsistent installation.

  1110 *  Installation service uses specific manifest-file format to get informed about the xml, css, 

  1111 *  dtd, and resource files to be installed. Resource files might be locale-specific or generic

  1112 *  as well.

  1113 *  hspsThemeServer takes care of saving everything on their appropriate places in the target device's

  1114 *  user disk. Theme storage is located in hspsThemeServer's private-folder.

  1115 *  Locales are instructed in manifest file also. Manifest file's file-extension must be .dat, 

  1116 *  but actually, the file-name can be whatever, however, when low-level parametrization is used, 

  1117 *  the name must be "manifest.dat" and it must be the last file extracted from the installation 

  1118 *  package.

  1119 *  For more information of manifest-file format, see "Xuikon Manifest File User Guide.doc".

  1120 *

  1121 *  Installation functions can return one of the following 

  1122 *  ThspsServiceCompletedMessage-codes:

  1123 *  - EhspsInstallThemeSuccess,

  1124 *  - EhspsInstallPhaseSuccess, or

  1125 *  - EhspsInstallThemeFailed.

  1126 *

  1127 *  Client application must implement MhspsThemeManagementServiceObserver-interface

  1128 *  and listen these messages

  1129 *  mentionaed. Let it be emphasised that both synchronous and asynchronous calls 

  1130 *  can return the codes above.

  1131 *  Installation functions may also return one of the following codes:

  1132 *  - EhspsServiceRequestSheduled, or

  1133 *  - EhspsServiceRequestError.

  1134 *