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 = 8;

   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    * Restores plugin configurations by either removing all plugins

   397    * from the active view or by reinstalling all the ROM based plugins.

   398    */

   399   EhspsRestoreConfigurations,

   400   

   401 

   402   /**************************************

   403    * Client Request related requests: 

   404    *************************************/

   405   EhspsClientRequestBase,

   406   

   407   /** 

   408    *   	EhspsGetODT:

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

   410    */    

   411   EhspsGetODT = EhspsClientRequestBase,  

   412     

   413   /** 

   414    * 	EhspsGetODTUpdate. 

   415    * 	Subscribes theme status change and theme update messages.  

   416    */

   417   EhspsGetODTUpdate,

   418     

   419   /**

   420    * 	EhspsCancelGetODTUpdate. 

   421    * 	Cancels a subscription of theme updates. 

   422    */

   423   EhspsCancelGetODTUpdate,

   424     

   425   /** 

   426    *   	EhspsAccessResourceFile. 

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

   428    */

   429   EhspsAccessResourceFile,

   430     

   431   /**

   432    *    EhspsCopyResources

   433    *    Copies resource files to the destination folder.

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

   435    */

   436   EhspsCopyResources,

   437   

   438   /**************************************

   439    *	Out of range 

   440    *************************************/  

   441   EhspsNotSupported  

   442   };

   443   

   444 /** 

   445 *  ThspsServiceCompletedMessage. Response codes used by client-server 

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

   447 */    

   448 enum ThspsServiceCompletedMessage

   449     {

   450 /** Installation related responses: */

   451 

   452     /** 

   453      * EhspsInstallThemeSuccess. Theme installation was successful. 

   454      */

   455     EhspsInstallThemeSuccess,

   456 

   457     /** 

   458      *  EhspsInstallThemeFailed. Theme instalation was failed. 

   459      */

   460     EhspsInstallThemeFailed,

   461         

   462     /** 

   463     *   EhspsInstallPhaseSuccess. Installation service was performed an 

   464     *   installation phase successfully. 

   465     */

   466     EhspsInstallPhaseSuccess, 

   467 

   468     /** 

   469      * EhspsReinstallConfSuccess. Configuration reinstallation was successful. 

   470      */

   471     EhspsReinstallConfSuccess,

   472 

   473     /** 

   474      *  EhspsReinstallConfFailed. Configuration reinstalation was failed. 

   475      */

   476     EhspsReinstallConfFailed,

   477 

   478 /** Maintenance: */

   479     

   480     /** 

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

   482     *   Client must start listen the delivery events.

   483     */

   484     EhspsGetListHeadersSuccess,    

   485     

   486     /** 

   487      *   EhspsGetListHeadersFailed. Headers cannot be listed. 

   488      */

   489     EhspsGetListHeadersFailed, 

   490     

   491     /** 

   492      *   EhspsGetListHeadersUpdate. A header is arrived. 

   493      */

   494     EhspsGetListHeadersUpdate, 

   495     

   496     /** 

   497      *  EhspsGetListHeadersUpdateData

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

   499      */

   500     EhspsGetListHeadersUpdateData, 

   501     

   502     /** 

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

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

   505      */

   506     EhspsGetListHeadersEmpty,

   507       

   508     /** 

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

   510      */

   511     EhspsGetListHeadersNoChange,

   512    

   513     /** 

   514      *   EhspsGetListHeadersRestart. Header list is canged radiacally. Listing 

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

   516      */

   517     EhspsGetListHeadersRestart,

   518     

   519     /** 

   520      *   EhspsGetListHeadersRestartData. 

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

   522      */

   523     EhspsGetListHeadersRestartData,

   524     

   525     /** 

   526      * EhspsSetActiveThemeSuccess. Theme activation was successful. 

   527      */ 

   528     EhspsSetActiveThemeSuccess, 

   529     

   530     /** 

   531      * EhspsSetActiveThemeFailed. Theme activation has failed. 

   532      */

   533     EhspsSetActiveThemeFailed, 

   534     

   535     /** 

   536      * EhspsRestoreDefaultSuccess. Restoring the default theme was successful. 

   537      */

   538     EhspsRestoreDefaultSuccess,

   539     

   540     /** 

   541      * EhspsRestoreDefaultFailed. Restoring the default theme was failed. 

   542      */

   543     EhspsRestoreDefaultFailed,

   544     

   545     /** 

   546      * EhspsRemoveThemeSuccess. Theme removal was successful. 

   547      */

   548     EhspsRemoveThemeSuccess, 

   549     

   550     /** 

   551      * EhspsRemoveThemeFailed. Theme removal was failed. 

   552      */

   553     EhspsRemoveThemeFailed,

   554     

   555     /** 

   556      * EhspsAddPluginSuccess. A plugin was added succesfully. 

   557      */

   558     EhspsAddPluginSuccess,

   559     

   560     /** 

   561      * EhspsAddPluginFailed. Failed to add a plugin. 

   562      */

   563     EhspsAddPluginFailed,

   564     

   565     /** 

   566      * EhspsRemovePluginSuccess. A plugin was removed succesfully. 

   567      */

   568     EhspsRemovePluginSuccess,

   569     

   570     /** 

   571      * EhspsRemovePluginFailed. Failed to remove a plugin. 

   572      */

   573     EhspsRemovePluginFailed,

   574 

   575     /** 

   576      * EhspsSetActivePluginSuccess. A plugin was activated succesfully. 

   577      */

   578     EhspsSetActivePluginSuccess,    

   579 

   580     /** 

   581      * EhspsSetActivePluginFailed. Failed to activate a plugin. 

   582      */

   583     EhspsSetActivePluginFailed,    

   584     

   585     /** 

   586      * EhspsSetSettingsSuccess. A plugin settings was updated succesfully. 

   587      */

   588     EhspsSetPluginSettingsSuccess,

   589         

   590     /** 

   591      * EEhspsSetSettingsFailed. Failed to set settings of plugin. 

   592      */

   593     EhspsSetPluginSettingsFailed,

   594     

   595     /** 

   596      * EhspsMovePluginsSuccess. A plugins list was updated succesfully. 

   597      */

   598     EhspsMovePluginsSuccess,

   599 

   600     /** 

   601      * EhspsMovePluginsFailed. Failed to update a plugins list.

   602      */

   603     EhspsMovePluginsFailed,

   604 

   605     /** 

   606      * EhspsReplacePluginSuccess. A plugin was replace succesfully. 

   607      */

   608     EhspsReplacePluginSuccess,

   609 

   610     /** 

   611      * EhspsReplacePluginFailed. Failed to update a plugins list.

   612      */

   613     EhspsReplacePluginFailed,

   614     

   615     /**

   616      *  EhspsGetPluginOdtSuccess. Getting plugin odt was successful.

   617      */

   618     EhspsGetPluginOdtSuccess,

   619     

   620     /** 

   621      * EhspsGetPluginOdtFailed. Failed to get plugin odt.

   622      */

   623     EhspsGetPluginOdtFailed,

   624     

   625     /**

   626      * EhspsRestoreConfigurationsSuccess. Restoration was successfull.

   627      */

   628     EhspsRestoreConfigurationsSuccess,

   629     

   630     /**

   631      * EhspsRestoreConfigurationsFailed. Restoration failed.

   632      */

   633     EhspsRestoreConfigurationsFailed,

   634     

   635     

   636 /* Client Requests: */

   637     

   638     /** 

   639     *   EhspsGetODTSuccess. 

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

   641     */

   642     EhspsGetODTSuccess, 

   643     

   644     /** 

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

   646      */

   647     EhspsGetODTFailed,

   648     

   649     /** 

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

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

   652     */

   653     EhspsGetODTLowMemoryStrategy,

   654     

   655     /** 

   656     *   EhspsGetODTUpdateSuccess. Subscription of the theme updates and status 

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

   658     */

   659     EhspsGetODTUpdateSuccess,

   660     

   661     /**

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

   663     */

   664     EhspsSettingsLoaded,

   665     

   666     /**

   667     *	EhspsSettingsLoadFailed. Loading settings for a theme failed.

   668     */

   669     EhspsSettingsLoadFailed,

   670     

   671     /**

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

   673     */

   674     EhspsSettingsUpdated,

   675     

   676     /**

   677     *	EhspsSettingsUpdateFailed. Updating settings for a theme failed.

   678     */

   679     EhspsSettingsUpdateFailed,

   680     /** 

   681     *   EhspsGetODTUpdateFailed. 

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

   683     */

   684     EhspsGetODTUpdateFailed, 

   685     

   686     /** 

   687     *   EhspsGetODTUpdateStatus. Theme status is changed. 

   688     *   Client must reset rendering and request theme again. 

   689     */

   690     EhspsGetODTUpdateStatus, 

   691     

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

   693     EhspsGetODTUpdateHot,

   694   

   695     /** 

   696     *   EhspsGetODTUpdateEmpty. 

   697     *   No update available. Client may retain subscription. 

   698     */

   699     EhspsGetODTUpdateEmpty,

   700   

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

   702     EhspsGetODTUpdateNone,

   703 

   704     /** 

   705     *   EhspsAccessResourceFileSuccess. 

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

   707     */

   708     EhspsAccessResourceFileSuccess,

   709     

   710     /** 

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

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

   713     */

   714     EhspsAccessResourceFileFailed,

   715     

   716 /** Generic: */

   717     /** 

   718     *   @deprecated EhspsThemeServiceCanceled. 

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

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

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

   722     *   problem.

   723     */  

   724     EhspsServiceRequestCanceled,    

   725     

   726     /** 

   727     *   EhspsServiceRequestSheduled. Server has sheduled the asynchronous service 

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

   729     */

   730     EhspsServiceRequestSheduled,

   731     

   732     /** 

   733     *   EhspsServiceNotSupported. 

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

   735     */

   736     EhspsServiceNotSupported,

   737     

   738     /** 

   739     *   EhspsServiceRequestError. Server rejects the service request maybe because

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

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

   742     */  

   743     EhspsServiceRequestError,

   744     

   745     /** 

   746     *   EhspsResourceCopyFailed.

   747     */  

   748     EhspsResourceCopyFailed,

   749 

   750     /** 

   751     *   EhspsResourceCopySuccess.

   752     */  

   753     EhspsResourceCopySuccess,

   754 

   755     /** 

   756     *  Configuration state changed successfully

   757     */  

   758     EhspsSetConfStateSuccess,

   759 

   760     /** 

   761     *  Configuration state change failed

   762     */  

   763     EhspsSetConfStateFailed,

   764 

   765     /** 

   766     *  Active application configuration restored successfully

   767     */  

   768     EhspsRestoreActiveAppConfSuccess,

   769 

   770     /** 

   771     *  Active application configuration restoring failed

   772     */  

   773     EhspsRestoreActiveAppConfFailed,

   774     /** 

   775     *  Updating plugin configuration failed

   776     */

   777     EhspsUpdatePluginFailed,

   778     /** 

   779      *  Updating plugin configuration succeed

   780      */ 

   781     EhspsUpdatePluginSuccess,

   782     

   783     /**

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

   785     */

   786     EhspsResolutionChangedUpdate    

   787 

   788     };  

   789 

   790  

   791 /** 

   792 *   ThspsThemeStatus. 

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

   794 */

   795 enum ThspsThemeStatus

   796   {

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

   798   EhspsThemeStatusNone            = 0x0000, //0b0000000000000000,

   799   

   800   /** 

   801   *   EhspsThemeStatusActive. 

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

   803   */

   804   EhspsThemeStatusActive          = 0x0001, //0b0000000000000001,

   805   

   806   /** 

   807   *   EhspsThemeStatusLicenceeDefault. 

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

   809   */

   810   EhspsThemeStatusLicenceeDefault = 0x0002, //0b0000000000000010,

   811   

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

   813   EhspsThemeStatusOperatorDefault = 0x0004, //0b0000000000000100,

   814   

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

   816   EhspsThemeStatusUserDefault     = 0x0008,  //0b0000000000001000

   817   

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

   819   EhspsThemeStatusMakeActive     = 0x0010,  //0b0000000000010000

   820 

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

   822   EhspsThemeStatusClean    = 0x0020,  //0b0000000000100000

   823   

   824   /** 

   825   *   EhspsThemeStatusLicenceeRestorable. This theme is restored when licensee default 

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

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

   828   */

   829   EhspsThemeStatusLicenceeRestorable = 0x0040, //0b00000000001000000,

   830   

   831   EhspsThemeStatusLocked = 0x0080, //0b00000000010000000,

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

   833   EhspsThemeStatusHitchcock = 0x0100, //0b00000000100000000

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

   835   EhspsThemeStatusIncludeControlBlock = 0x0200 //0b00000001000000000

   836   };  

   837 

   838 

   839 /**

   840  *   ThspsInstallationPhase.

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

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

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

   844  */

   845 enum ThspsInstallationPhase

   846   {

   847   /** EhspsPhaseIdle. */

   848   EhspsPhaseIdle,  

   849   

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

   851   EhspsPhaseInitialise,

   852   

   853   /** EhspsPhaseCleanup. */

   854   EhspsPhaseCleanup,

   855       

   856   /** EhspsPhaseInstallODT. */

   857   EhspsPhaseInstallSkeleton,

   858   

   859   /** EhspsPhaseImportPlugins. */

   860   EhspsPhaseImportPlugins,

   861     

   862   /** EhspsPhaseRollBack. */

   863   EhspsPhaseRollBack

   864   };

   865 

   866 

   867 /**

   868  * ThspsFamily.

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

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

   871  */

   872 enum ThspsFamily

   873     {

   874     EhspsFamilyUnknown = 0x00,

   875     EhspsFamilyQvga = 0x01,

   876     EhspsFamilyQvga2 = 0x02,

   877     EhspsFamilyVga = 0x04,

   878     EhspsFamilyVga3 = 0x08,

   879     EhspsFamilyQhd = 0x10,

   880     EhspsFamilyQhd_tch = 0x20,

   881     EhspsFamilyVga_tch = 0x40

   882     };

   883 

   884 /**

   885  * ThspsConfigurationType.

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

   887  */

   888 enum ThspsConfigurationType

   889     {

   890     EhspsAppConfiguration = 1,

   891     EhspsViewConfiguration,

   892     EhspsWidgetConfiguration,

   893     EhspsTemplateConfiguration    

   894     };

   895 

   896 /**

   897  * ThspsConfigurationState.

   898  * Indentifies the configuration state  

   899  */

   900 enum ThspsConfigurationState

   901     {

   902     EhspsConfStateNotConfirmed = 1,

   903     EhspsConfStateWaitForConfirmation,

   904     EhspsConfStateConfirmed,

   905     EhspsConfStateError  

   906     };

   907 

   908 /**

   909  * ThspsConfStateChangeFilter

   910  * Indentifies the configuration state change options

   911  */

   912 enum ThspsConfStateChangeFilter

   913     {

   914     EhspsConfStateChangeNoFilter = 1,

   915     EhspsConfStateChangePlugins

   916     };

   917 

   918 /**

   919  * ThspsConfiguration.

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

   921  */

   922 struct ThspsConfiguration

   923     {

   924     // Application uid or Interface uid

   925     TInt rootUid;

   926     

   927     // Theme uid

   928     TInt themeUid;

   929     

   930     // Type of the configuration

   931     ThspsConfigurationType type;

   932     };

   933 

   934 

   935 /**

   936  * Input parameters for the AddPlugin service

   937  */

   938 struct ThpsParamAddPlugin

   939 	{

   940 	TInt appUid;					// uid of the application configuration

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

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

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

   944 	};

   945 

   946 /**

   947  * Input parameters for the RemovePlugin service

   948  */

   949 struct ThpsParamRemovePlugin

   950     {

   951     TInt appUid;                    // uid of the application configuration

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

   953     };

   954 

   955 /**

   956  * Input parameters for the ActivatePlugin service

   957  */

   958 struct ThpsParamSetActivePlugin

   959     {

   960     TInt appUid;                    // uid of the application configuration

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

   962     };

   963 

   964 /**

   965  * Input parameter for the GetSettings service 

   966  */

   967 struct ThspsParamGetPluginOdt

   968 	{

   969 	TInt appUid;					// uid of the application configuration

   970 	TInt pluginUid;					// uid of the plugin

   971 	};

   972 

   973 /**

   974  * Input parameters for the MovePlugins service

   975  */

   976 const TInt KMaxPluginIdsLength = 2048;

   977 struct ThpsParamMovePlugins

   978 	{

   979 	TInt appUid;					// uid of the application configuration

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

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

   982 	};

   983 

   984 /**

   985  * Input parameter for the SetConfState service 

   986  */

   987 struct ThspsParamSetConfState

   988     {

   989     TInt appUid;                       // uid of the application

   990     TInt confId;                       // id of the configuration

   991     ThspsConfigurationState state;     // new configuration state

   992     ThspsConfStateChangeFilter filter; // filter parameter

   993     };

   994 

   995 /**

   996  * Input parameter for the ReinstallConf service 

   997  */

   998 struct ThspsParamReinstallConf

   999     {

  1000     TInt appUid;                    // uid of the application

  1001     TInt confUId;                   // uid of the reinstalled configuration

  1002     };

  1003 

  1004 /**

  1005  * Input parameter for the RestoreActiveAppConf service 

  1006  */

  1007 struct ThspsParamRestoreActiveAppConf

  1008     {

  1009     TInt appUid;                    // uid of the application    

  1010     };

  1011 

  1012 /**

  1013  * Input parameter for the ReplacePlugin service 

  1014  */

  1015 struct ThspsParamReplacePlugin

  1016     {

  1017     TInt appUid;                    // uid of the application

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

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

  1020     };

  1021 /**

  1022  * Input parameter for the ReplacePlugin service 

  1023  */

  1024 struct ThspsParamSetPluginSettings

  1025     {

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

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

  1028     };

  1029 

  1030 enum ThspsRestore

  1031     {

  1032     EhspsRestoreAll = 0,            // restores plug-ins from eMMC, UDA and ROM    

  1033     EhspsRestoreRom,                // restores plug-ins from ROM

  1034     EhspsRestoreViews               // removes extra views and empties them

  1035     };

  1036 

  1037 /**

  1038  * Input parameter for the RestoreActiveAppConf service 

  1039  */

  1040 struct ThspsParamRestoreConfigurations

  1041     {

  1042     TInt appUid;                    // uid of the application

  1043     ThspsRestore restore;           // operation               

  1044     };

  1045 

  1046 

  1047 class ChspsODT;

  1048 class ChspsResource;

  1049 class ChspsDomDocument;

  1050 class ChspsRequestNotificationParams;

  1051 /**

  1052 *  Part of HSPS Plugin Configuration Management Service APIs.

  1053 *  MhspsThemeManagementServiceObserver. Interface definition for the HSPS 

  1054 *  Installation and Maintenance Service related events observation.

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

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

  1057 *  hspsInstallationHandler and hspsMaintenanceHandler. 

  1058 *  For more information of different Installation and Maintenance Service 

  1059 *  related messages, see the documentaion of ThspsServiceCompletedMessage.

  1060 *

  1061 *  @since S60 5.0

  1062 *  @ingroup group_hspsclients

  1063 */

  1064 class MhspsThemeManagementServiceObserver

  1065     {

  1066     public:

  1067                 

  1068         /**

  1069         * HandlehspsClientMessage

  1070         * 

  1071         * @since S60 5.0

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

  1073         *        the hspsInstallationHandler and hspsMaintenanceHandler to their 

  1074         *        observer.

  1075         */

  1076         virtual void HandlehspsClientMessage(ThspsServiceCompletedMessage aMessage) = 0;

  1077     };

  1078 

  1079 /**

  1080 *  Part of HSPS Plugin Configuration Management Service APIs.

  1081 *  MhspsClientRequestServiceObserver. Interface definition for the HSPS Client 

  1082 *  Request Service events observation. 

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

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

  1085 *  hspsClientRequestHandler. 

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

  1087 *  see the documentaion of ThspsServiceCompletedMessage.

  1088 *

  1089 *  @since S60 5.0

  1090 *  @ingroup group_hspsclients

  1091 */

  1092 class MhspsClientRequestServiceObserver

  1093     {

  1094     public:

  1095         /**

  1096         * HandlehspsRequestClientMessage

  1097         * 

  1098         * @since S60 5.0

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

  1100         *        the hspsClientRequestHandler to its observer.

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

  1102         */

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

  1104     };

  1105 

  1106 /**

  1107 *  Part of HSPS Plugin Configuration Management Service APIs.

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

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

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

  1111 *  Homescreen Application Configuartion installation functionality. Implementation of this 

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

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

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

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

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

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

  1118 *  understand semanticly.

  1119 *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1135 *