/*

* 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:  

*

*  ChspsClient is a client-side implementation of MhspsInstallationService and MhspsMaintenanceService

*  interface definitions of Homescreen Plugin Configuration Managament Services APIs. Installation and 

*  Maintenance Services are intended to serve Homescreen as well as S60 legacy applications - especially

*  the Personalisation Application - with the plugin installation and maintenance 

*  functionality. Typical use-case is that client application initiates ChspsClient-object, connects

*  to hspsThemeServer with its application UID, and commences installation and maintenance service 

*  requests.

*

*  Security in using services is quarantied by controlling the rights to see Application Themes 

*  and operate with hsps Theme Server. This control is based on SECUREID of application process.

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

*  Security.

*

*  ChspsClient offers high- and low-level API-functionality. High-level and low-level calls are 

*  diffrentiated by their parametrization. High-level parametrization is directed to the be used by

*  applications which need human readable data and offer a user interface. Low-level parametrization

*  is directed to the machine-originated requestors like OTA Push or DM (Device Management) 

*  sub-systems where data is not needed to understand semanticly. 

*  ChspsClient delegates server messages to its client application by 

*  MhspsThemeManagementServiceObserver::HandlehspsClientMessage() call-back to be implemented by the 

*  client application.

*

*  Theme Installation Services

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*

*  Theme Maintenanace Services:

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

*  Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().

*  Others functions are straightforward to use. They are explained in the class declaration section

*  below. The asynchronous service is applied only in theme listing service calls.

*  Client application initiates the theme listing by calling synchronous function 

*  hspsGetListHeaders(). This call initiates the query. Client application should call 

*  hspsGetNextHeader() after checking that any themes matching on current query is found or that query

*  is valid at least. This action is called a subscription. To receive actual theme listing, the 

*  client application must start to listen call-back messages from the server about list delivery. 

*  The headers matching on query will be delivered immediately. Query remains until 

*  hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, 

*  it will be delivered if the query concers it. 

*

*

*

*/

#ifndef __ChspsCLIENT_H__

#define __ChspsCLIENT_H__

#include <e32base.h>

#include "hspsthememanagement.h"

#include "hspsclientsession.h"

#include "hspsresult.h"

#ifdef HSPS_LOG_ACTIVE

class ChspsLogBus;

#endif

/** hspsClient Panic Category. */

_LIT( KhspsClient, "hspsClient" );

/** hspsClient panic codes: */

enum ThspsClientPanics

    {

    EhspsClientBadState

    };

class RhspsClientSession;

class MhspsInstallationService;

class MhspsMaintenanceService;

class MhspsThemeManagementServiceObserver;

class ChspsODT;

class ChspsResult;

/**

 *  ChspsClient. 

 *  ChspsClient performs all client-side theme installation and maintenance related functionality.

 *  Theme maintenance services includes theme listings, theme activation, theme removal, and default

 *  theme restoring functionality.

 *

 *  Class inheritance:

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

 *  ChspsClient derives CActive for asynchronous request handling, and MhspsInstallationService and 

 *  MhspsMaintenanceService from Homescreenpluginservices. 

 *

 *  Theme installation functionality:

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

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

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

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

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

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

 *  inconsistent installation.

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

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

 *  as well.

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

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

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

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

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

 *  package.

 *  For more information of manifest-file format, see Homescreen wikipages.

 *

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

 *  - EhspsInstallThemeSuccess,

 *  - EhspsInstallPhaseSuccess, or

 *  - EhspsInstallThemeFailed.

 *

 *  Client application must implement MhspsThemeManagementServiceObserver-interface and listen these 

 *  messages mentioned. Let it be emphasised that both synchronous and asynchronous calls can return

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

 *  - EhspsServiceRequestSheduled, or

 *  - EhspsServiceRequestError.

 *

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

 *

 *  Theme maintenance functionality:

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

 *  Most of the maintenance functions are synchronous, only one is asynchronous; hspsGetNextHeader().

 *  Others functions are straightforward to use but hspsGetListHeaders(). This will be explained next; 

 *  synchronous call hspsGetListHeaders() initiates the theme header listing by passing search mask 

 *  to HSPS Server's Maintenance Service. This search mask is called a query. It also passes

 *  a list object in where maintenance service should append theme-header objects (type of 

 *  ChspsODT-class without DOM-document) when one is retrieved asychronously. Search mask should be 

 *  filled with proper parameters matching the need in hand. If no parameters are given, all headers

 *  of Application Themes available in Definition Repository will be delivered, otherwise, 

 *  only sub-set of theme-headers will be delivered. After the query-call hspsGetListHeaders(), the 

 *  delivering of the theme-headers is asynchronous. Asynchronous service must be initiated by 

 *  calling hspsGetNextHeader() after checking that any theme matching on current query is found or

 *  that query is valid anyway. This action is called a subscription. To receive theme

 *  listing, the client application must implement MhspsThemeManagementServiceObserver-interface and

 *  start to listen call-back messages. 

 *  The headers matching on query will be delivered immediately. Query remains until 

 *  hspsCancelGetListHeaders() is called by client. If a new Application Theme exist in repository, it

 *  will be delivered. As mentioned, when hspsGetListHeaders() returns, the return value must be checked.

 *  Return value could be one of the following:

 *  - EhspsGetListHeadersSuccess - there is at least one Application Theme available matching on query. 

 *                               Call first hspsGetNextHeader() to get the headers. Same call will set 

 *                               the subscribtion of new ones possible coming available later.

 *  - EhspsGetListHeadersEmpty   - there is no themes matching on the query available at the time, 

 *                               however, some might be exist later in due to installations. 

 *                               Client application should retain the subcription.

 *  - EhspsGetListHeadersFailed  - service request failed for some reason. Possible reasons are for e.g.

 *                               the missing rights to list headers queried.  

 *   

 *  Additional Return Code Support (ChspsResult) will express for e.g. the number of headers to be

 *  delivered or possible system error code in failed cases.

 *  

 *  By MhspsServiceObserver::HandlehspsServiceMessage() call-back function implementation, client 

 *  application must listen the following ThspsServiceCompletedMessage-messages:

 *

 *  - EhspsGetListHeadersUpdate  - header list on the client side has a new object appended at the end

 *                               of the list,

 *  - EhspsGetListHeadersRestart - header list on server side has changed so much that the client must 

 *                               empty the list printed on screen. New list will be delivered 

 *                               immediately. The subscription stands.

 *  - EhspsGetListHeadersEmpty   - header list on server side is now empty. The client must empty 

 *                               the list on screen if printed. The subscription stands. 

 *  - EhspsGetListHeadersFailed  - operation has failed. Client should cancel request and restart.

 *

 *  Maintenanace functions may also return one of the following codes:

 *  - EhspsServiceRequestSheduled, or

 *  - EhspsServiceRequestError.

 *

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

 *

 *

 * @lib hspsClient.lib

 * @since S60 5.0

 * @ingroup group_hspsclients

 */

class ChspsClient : public CActive, public MhspsInstallationService, public MhspsMaintenanceService

    {

    public: // Constructors and destructors

        /**

        * NewL.

        * 

        * Two-phased constructor.

        * Creates a ChspsClient object using two phase construction,

        * and return a pointer to the created object.

        * 

        * @since S60 5.0 

        * @param aObserver The object to be used to handle updates from the server.

        */

        IMPORT_C static ChspsClient* NewL(MhspsThemeManagementServiceObserver& aObserver );

        /**

        * NewLC.

        * 

        * Two-phased constructor.

        * Creates a ChspsClinet object using two phase construction,

        * and return a pointer to the created object.

        * 

        * @since S60 5.0

        * @param aObserver The object to be used to handle updates from the server.

        */

        IMPORT_C static ChspsClient* NewLC( MhspsThemeManagementServiceObserver& aObserver );

        /**

        * ~ChspsClient.

        * 

        * Destructor.

        * Destroys the object and release all memory objects.

        */

        virtual ~ChspsClient();

    public: // New functions

        /**

        * From MhspsInstallationService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName,

                                   ChspsODT& aHeader);

        /**

        * From MhspsInstallationService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsInstallTheme(const TDesC& aManifestFileName, 

                                   TDes8& aHeaderData);

        /**

        * From MhspsInstallationService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(ChspsODT& aHeader);

        /**

        * From MhspsInstallationService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsInstallNextPhaseL(TDes8& aHeaderData);

        /**

        * From MhspsInstallationService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsCancelInstallTheme();

        /**

        * From MhspsMaintenanceService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const ChspsODT& aSearchMask,

                                   CArrayPtrFlat<ChspsODT>& aHeaderList);

        /** 

        * From MhspsMaintenanceService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsGetListHeaders(const TDesC8& aSearchMaskData,

                                   CArrayPtrSeg<HBufC8>& aHeaderDataList);

        /**

        * From MhspsMaintenanceService.

        */  

        IMPORT_C ThspsServiceCompletedMessage hspsGetNextHeader();       

        /**

        * From MhspsMaintenanceService.

        */  

        IMPORT_C ThspsServiceCompletedMessage hspsCancelGetListHeaders();       

        /**

        * From MhspsMaintenanceService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const ChspsODT& aSetMask,

                                   ChspsODT& aHeader);

        /**

        * From MhspsMaintenanceService.

        */        

        IMPORT_C ThspsServiceCompletedMessage hspsSetActiveTheme(const TDesC8& aSetMaskData,

                                 TDes8& aHeaderData);

        /**

        * From MhspsMaintenanceService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsRestoreDefault(const ChspsODT& aSetMask,

                                   ChspsODT& aHeader);

        /**

        * From MhspsMaintenanceService.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsRemoveThemeL(const ChspsODT& aSetMask);

        /**

        * GethspsResult

        * 

        * @since S60 5.0

        * @param aResult is a ChspsResult object containing additional information of query result.

        */

        IMPORT_C void GethspsResult(ChspsResult& aResult);

        /**

        * Returns ODT header list according to the defined search mask

        * 

        * @since S60 5.0 

        * @param aSearchMask is ChspsODT-object which attributes are filled to present search 

        *        parameters for theme set queried by client. This parametrisation follows 

        *        the high-level schema. 

        * @param aHeaderList is an list object able to carry ChspsODT-objects. 

        * @return Error code

        */

        IMPORT_C TInt hspsGetHeaders(const ChspsODT& aSearchMask,

                                   CArrayPtrFlat<ChspsODT>& aHeaderList);

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsAddPlugin(

        		const TInt aAppUid,

        		const TInt aConfId,

        		const TInt aPluginUid,

        		const TInt aPosition,

        		TInt& aAddedPluginId 

        		);

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsRemovePlugin(

        		const TInt aAppUid,        		

        		const TInt aPluginId

        		);

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsSetActivePlugin(

                const TInt aAppUid,

                const TInt aPluginId

                );        

        /**

         * From MhspsMaintenanceService        

         */

        IMPORT_C ThspsServiceCompletedMessage hspsSetPluginSettings(

               const ChspsODT& aHeader,

               const TInt aPluginId,

               ChspsDomDocument& aDom,

               const TBool aPluginStoringStatus

               );

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsGetPluginOdtL(

        		const TInt aAppUid,        		

        		const TInt aPluginUid,

        		ChspsODT* aPluginOdt );

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsMovePluginsL(

        		const TInt aAppUid,        

        		const TInt aConfId,

        		const CArrayFixFlat<TInt>& aPluginIdList 

        		);

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsSetConfState(

                const TInt aAppUid,        

                const TInt aConfId,

                const ThspsConfigurationState aState,

                const ThspsConfStateChangeFilter aFilter

                );

        /**

        * From MhspsMaintenanceService        

        */

        IMPORT_C ThspsServiceCompletedMessage hspsRestoreActiveAppConf(

                const TInt aAppUid,

                const TInt aConfUid );

        /** 

         * Updates plugin configuration in all application configuration

         *  

         * @since S60 5.0

         * @param apluginUid identifies the plugin configuration                

         * @return ThspsServiceCompletedMessage expressing the result of the call.

         */

        IMPORT_C  ThspsServiceCompletedMessage hspsPluginUpdateL(

                          const ChspsODT& /* aOdt */ );

        /**

        * Reinstalls requested configuration

        * 

        * @since S60 5.0

        * @param aAppUid is interface.

        * @param aConfUid is ID of the reinstalled configuration.  

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsReinstallConf(

            TInt aAppUid, 

            TInt aConfUid );

        /** 

        * Internal log bus setter. Empty method in product builds.

        * 

        * @since S60 5.0

        * @param aLogBus    Log bus to be set.

        */

        IMPORT_C void SetLogBus( void* aLogBus );        

        /**

        * From MhspsMaintenanceService        

        */                               

        IMPORT_C ThspsServiceCompletedMessage hspsReplacePlugin(

                const TInt aAppUid,

                const TInt aPluginId,             

                const TInt aConfUid );

        /**

        * Restores plugin configurations by either removing all plugins

        * from the active view or by removing all extra views.

        * In latter case, the first locked view is emptied. If there are 

        * no locked views then the first view will remain while others

        * are removed.

        * @since S60 5.2

        * @param aAppUid Application uid

        * @param aReinstall  False if only the active view should be fixed,

        *                    True if also all extra views should removed                         

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        IMPORT_C ThspsServiceCompletedMessage hspsRestoreConfigurations(

            const TInt aAppUid,

            const TBool aReinstall );

    protected: // Functions from base classes

        /**

        * From CActive, RunL.

        * Callback function.

        * Invoked to handle responses from the server.

        */

        void RunL();

        /**

        * From CActive, DoCancel.

        * Cancels any outstanding operation.

        */

        void DoCancel();

        /**

        * From CActive Called when asynchronous request has failed

        * @since S60 3.1

        */

        TInt RunError( TInt aError );

    private: 

        /**

        * Updates iResult 

        * @param aResultData Result data

        */

        void UpdatehspsResult( TDesC8& aResultData );

        /**

        * Creates a header object from header data (iHeaderData) 

        * and adds created header to the header list (iHeaderList)

        * @param aHeaderData Header data

        */

        void AppendHeaderListL( TDesC8& aHeaderData );

        /**

        * Gets file handle and streams odt from the file.

        * @since S60 5.0

        * 

        * @param aOdtPath - odt file path

        * @param aAppUid - application uid for accessing to the file

        * @param aPluginOdt - odt for streaming

        * @return error code  

        */

        TInt StreamOdtL( TDes& aOdtPath, 

        		const TInt aAppUid, ChspsODT* aPluginOdt );

    private: // Constructors and destructors

        /**

        * ChspsClient.

        * Performs the first phase of two phase construction.

        * @param aObserver The object to be used to handle updates from the server.

        */

        ChspsClient( MhspsThemeManagementServiceObserver& aObserver);

        /**

        * ConstructL.

        * Performs the second phase construction of a ChspsClient object.

        */

        void ConstructL();

    private: // Members

        /**

        * iSession, the theme server session.

        */