/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   

*  

*  HSPS Application Theme Management Service APIs

*  ************************************************

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

*  implementations of HSPS Application Theme Management services.

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

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

*  are the following: 

*  - MhspsInstallationService  - defines services for Application Theme 

*                              installations,

*  - MhspsMaintenanceService   - defines services for listing, activation, 

*                              removing and restoring themes set as default, 

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

* 

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

*    applications of HSPS Theme Management Services, and

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

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

*    some rendering engine implementation like HSPS UI Engine.

*

*  Typical HSPS Application Theme Management Service use-cases

*  =============================================================

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

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

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

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

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

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

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

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

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

*  phone applications on-line.

*

*  HSPS UI Manager

*  ***************** 

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

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

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

*  Service APIs. 

*

*  Client-side functionality and APIs

*  ==================================

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

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

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

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

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

*  client applications. hspsClient API offers application theme installation 

*  and maintenance related services, meanwhile hspsRequestClient API offers 

*  services related to the usage of Application Themes. 

*                 

*  Server-side functionality and APIs

*  ==================================

*

*

*  Security

*  ========

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

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

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

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

*  services for Platform Security.

*

*  Scalability

*  ===========

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

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

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

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

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

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

*  performance and features providing powerful and centralised server-side 

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

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

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

*  on-line operations customization on single smartphone.  

*

*  HSPS Utility Classes

*  ======================

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

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

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

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

*  - ChspsODT, and 

*  - ChspsResource. 

*

*  ChspsODT

*  ------

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

*  base unit of information exchanged in HSPS Application Theme Management 

*  operations. 

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

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

*  needed to distinquish application themes from each others. 

*  HSPS Application Theme Management services handles mainly these 

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

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

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

*  

*  ChspsResource

*  -----------

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

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

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

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

*  HSPS Application Theme Management system supports theme resourcing by 

*  offering resource conversations and storing services, and offering Rendering

*  Engines the following services:

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

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

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

*

*  ChspsResult

*  ---------

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

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

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

*  client request whether the result was successful or not.

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

*  - iSystemError - Symbian OS returned error code

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

*  - iIntValue1   - additional information relevant the result. 

*  - iIntValue2   - additional information relevant the result.

*

*

*

*/

#ifndef __hspsTHEMEMANAGEMENT_H__

#define __hspsTHEMEMANAGEMENT_H__

#include <f32file.h> // RFile

#include <badesca.h> // descriptors

// --------------------

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

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

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

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

const TUid KSecureId_LE =    	{0x102049AD};

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

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

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

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

const TUid KSecureId_HUIMenu = 	{0x102828BD}; 

const TUid KSecureId_EUnit = 	{0x20000FB1};

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

// -----------------

/**  Nokia VID: = VID_DEFAULT */

const TInt Nokia_VID  = 0x101FB657;

/** 

*   KhspsThemeStatusRepositoryUid. 

*   Central repository entry for HSPS. 

*/

const TUid KhspsThemeStatusRepositoryUid = {0x200159C9};

/** 

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

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

*/

const TInt KMaxHeaderDataLength8=512;

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

/** 

*   KHeaderListUpdatePollingTimeSpan. The time between the subsequent 

*   request to check changes in Definition Repository. 

*   The value is expressed in microseconds. 

*/

const TInt KHeaderListUpdatePollingTimeSpan = 1000000;

/** 

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

*   internalize theme. 

*/

const TInt KMaxElementDataLength = 1048576;

/** 

*   KPathListGranularity. Controls the granularity of the path list retrieved

*   from Definition Repository. 

*/

const TInt KPathListGranularity = 4;

/** 

*   KMahspsumberOfThemeLoadRepeats. Controls the maximum number of repeats when delivering 

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

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

*/

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

/** 

*   KThemeLoadRepeatWaitTime. Controls the time to wait between the 

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

*   side to the client size.

*/

const TInt KThemeLoadRepeatWaitTime = 5000000; // 5 seconds

/** 

*   KActiveThemeUpdatePollingTimeSpan. 

*   Constant KActiveThemeUpdatePollingTimeSpan controls the time slice 

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

*   The value is expressed in microseconds.

*/

const TInt KActiveThemeUpdatePollingTimeSpan = 1000000; // 1 second

const TInt KMaxPluginIdLenght = 8;

/** 

*   KThemeInvalidatedTimeSpan

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

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

* the default operator or licensee theme is restored.

*

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

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

* After succesfull rendering the client app subscribes for theme updates

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

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

* the default operator or licensee theme is restored.

*

*/

const TInt KThemeInvalidatedTimeSpan = 120000000;

/** 

 * Client initiated service requests: an enumeration of function indexes

 *  

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

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

 * 

 */

enum ThspsServiceRequestMessage

  {

  /**************************************

   * Installation related requests: 

   *************************************/

  EhspsInstallationBase = 0,

  /** 

   *	EhspsInstallTheme. 

   * 	Initiates synchronous and asynhronous theme installation process. 

   */

  EhspsInstallTheme = EhspsInstallationBase,

  /** 

   * 	EhspsInstallNextPhase:

   *	Promotes subsequent asyncronous installation phases 

   * 	and offers client process a point to cancel installation.    

   */

  EhspsInstallNextPhase,

  /** 

   * 	EhspsCancelInstallTheme:

   * 	Cancels asynchronous installation process. 

   */

  EhspsCancelInstallTheme,

  /** 

   *    EhspsReinstallConf:

   *    Initiates synchronous configuration's reinstallation process 

   */

  EhspsReinstallConf,

  /**************************************

   * Maintenance related requests: 

   *************************************/  

  EhspsMaintenanceBase,

  /** 

   *	EhspsGetListHeaders. 

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

   */      

  EhspsGetListHeaders = EhspsMaintenanceBase,

  /**	

   * 	EhspsGetNextHeader:

   * 	Subscribes updates for received header list. 

   */ 

  EhspsGetNextHeader,

  /**	

   * 	EhspsCancelGetListHeaders. 

   * 	Cancels a subscription of header list updates. 

   */

  EhspsCancelGetListHeaders,

  /**	

   * 	EhspsSetActiveTheme. 

   * 	Theme activation. 

   */

  EhspsSetActiveTheme,

  /** 

   *   	EhspsRestoreDefault. 

   *	Restores the default theme in next order: 

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

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

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

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

   *   	quaranteed that application is in working condition allways.

   */

  EhspsRestoreDefault,

  /** 

   *   	EhspsRemoveTheme. 

   * 	Removes a given theme with all its dependent files and 

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

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

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

   */

  EhspsRemoveTheme,

  /** 

   *  	EhspsAddPlugin. 

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

   */

  EhspsAddPlugin,

  /** 

   *  	EhspsRemovePlugin. 

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

   */

  EhspsRemovePlugin,

  /** 

   *    EhspsSetActivePlugin. 

   *    Set active plugin.

   */

  EhspsSetActivePlugin,

  /** 

   *    EhspsReplacePlugin. 

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

   */

  EhspsReplacePlugin,

  /** 

   *    EhspsSetSettings. 

   *    Sets settings of plugin in active configuration

   */

  EhspsSetPluginSettings,

   /** 

    *    EhspsGetPluginOdt. 

    *    Gets plugin odt by UID

    */

   EhspsGetPluginOdt,

  /** 

   *  	EhspsMovePlugins 

   * 	Updates plugin positions within a configuration

   */

  EhspsMovePlugins,

  /**   EhspsSetConfState 

   *    Updates configuration's state. 

   */

  EhspsSetConfState,

  /**   EhspsRestoreActiveAppConf 

   *    Restore active application configuration in following order

   *    1) Restore application configuration from backup folder

   *    2) Activate licensee default restorable configuration

   *    3) Reinstall licensee default restorable configuration  

   */

  EhspsRestoreActiveAppConf,

  /** 

   *  Updating plugin configuration

   */

  EhspsUpdatePluginConf,

  /**

   * Restores plugin configurations by either removing all plugins

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

   */

  EhspsRestoreConfigurations,

  /**************************************

   * Client Request related requests: 

   *************************************/

  EhspsClientRequestBase,

  /** 

   *   	EhspsGetODT:

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

   */    

  EhspsGetODT = EhspsClientRequestBase,  

  /** 

   * 	EhspsGetODTUpdate. 

   * 	Subscribes theme status change and theme update messages.  

   */

  EhspsGetODTUpdate,

  /**

   * 	EhspsCancelGetODTUpdate. 

   * 	Cancels a subscription of theme updates. 

   */

  EhspsCancelGetODTUpdate,

  /** 

   *   	EhspsAccessResourceFile. 

   *	Request access to resource file on hspsThemeServer private folder.

   */

  EhspsAccessResourceFile,

  /**

   *    EhspsCopyResources

   *    Copies resource files to the destination folder.

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

   */

  EhspsCopyResources,

  /**************************************

   *	Out of range 

   *************************************/  

  EhspsNotSupported  

  };

/** 

*  ThspsServiceCompletedMessage. Response codes used by client-server 

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

*/    

enum ThspsServiceCompletedMessage

    {

/** Installation related responses: */

    /** 

     * EhspsInstallThemeSuccess. Theme installation was successful. 

     */

    EhspsInstallThemeSuccess,

    /** 

     *  EhspsInstallThemeFailed. Theme instalation was failed. 

     */

    EhspsInstallThemeFailed,

    /** 

    *   EhspsInstallPhaseSuccess. Installation service was performed an 

    *   installation phase successfully. 

    */

    EhspsInstallPhaseSuccess, 

    /** 

     * EhspsReinstallConfSuccess. Configuration reinstallation was successful. 

     */

    EhspsReinstallConfSuccess,

    /** 

     *  EhspsReinstallConfFailed. Configuration reinstalation was failed. 

     */

    EhspsReinstallConfFailed,

/** Maintenance: */

    /** 

    *   EhspsGetListHeadersSuccess. Query of a header list was successful. 

    *   Client must start listen the delivery events.

    */

    EhspsGetListHeadersSuccess,    

    /** 

     *   EhspsGetListHeadersFailed. Headers cannot be listed. 

     */

    EhspsGetListHeadersFailed, 

    /** 

     *   EhspsGetListHeadersUpdate. A header is arrived. 

     */

    EhspsGetListHeadersUpdate, 

    /** 

     *  EhspsGetListHeadersUpdateData

     *  EhspsGetListHeadersUpdate for observing low-level API-calls. 

     */

    EhspsGetListHeadersUpdateData, 

    /** 

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

     *   current query. Client must clear the list screen. 

     */

    EhspsGetListHeadersEmpty,

    /** 

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

     */

    EhspsGetListHeadersNoChange,

    /** 

     *   EhspsGetListHeadersRestart. Header list is canged radiacally. Listing 

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

     */

    EhspsGetListHeadersRestart,

    /** 

     *   EhspsGetListHeadersRestartData. 

     *   EhspsGetListHeadersRestart for observing low-level API-calls.

     */

    EhspsGetListHeadersRestartData,

    /** 

     * EhspsSetActiveThemeSuccess. Theme activation was successful. 

     */ 

    EhspsSetActiveThemeSuccess,