/*

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

*

*  Installation Handler.

* 

*  

*  ChspsInstallatioHandler is a server-side implementation of HSPS Configuration 

*  Management Services.

*  The Installation Service is intended to serve the HSPS SAPI client only.

*   

*  Services:

*  1) reads installation instructions from a manifest-file 

*  2) parses and updates xml configuration into a binary representation (ODT's DOM)

*  3) stores various resources, localized and common, into Plug-in Repository  

*     (a.k.a. Definition Repository)

*    

*  When installation is successful, Installation Handler utilizes HSPS Definition 

*  Repository to store the results. All resources are stored on Definition Repository 

*  and their related information is stored on the list of ChspsResource-objects 

*  - a resource list. This list of ChspsResource-objects is called Resource List. 

*  For more information, see hspsResource documentation.

* 

*  On theme updates, Installation Handler deploys ChspsSecurityEnforcer to control 

*  update rights. For more information, see ChspsSecurityEnforcer documentation  

*  and ChspsInstallatioHandler documentation

*

*

*/

#ifndef __hspsINSTALLATIONHANDLER_H__

#define __hspsINSTALLATIONHANDLER_H__

#include <contenthandler.h>

#include <parser.h>

#include "hspsthememanagement.h"

#include "hspsresource.h"

#include "hspsresult.h"

#ifdef HSPS_LOG_ACTIVE

class ChspsLogBus;

#endif

class CRepository;

class ChspsThemeServer;

class ChspsDefinitionRepository;

class ChspsDefinitionEngineInterface;

class ChspsODT;

class ChspsDomNode;

class ChspsDomStringPool;

class ChspsSecurityEnforcer;

class ChspsResource;

class ChspsDomList; 

using namespace Xml;

#if defined(WINSCW) || defined(__WINS__)

const ThspsFamily KDefaultFamily = EhspsFamilyQhd_tch;

#endif

enum TInstallationMode

    {

    EAsynchronousObject,

    EServiceHandler

    };

/**

*  Class ChspsInstallationHandler.

*  ChspsInstallationHandler performs all theme installation related functionality for hspsThemeServer.

*

*  Class inheritance:

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

*  ChspsInstallationHandler implements MhspsInstallationService from HSPS Theme Management Service

*  and MContentHandler for XML-parsing of manifest file. For more information, see the architecture 

*  description in the beginning of this file. 

*

*  Functionality:

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

*  ChspsInstallationHandler offer high- and low-level API-functionality. High-level and low-level 

*  calls are diffrentiated by their parametrization. High-level parametrization is directed to the

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

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

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

*  Processing the installation task can be synchronous or asynchronous. Synchronous mode is 

*  applied everytime an installation is initiated. Application Theme may include resources. 

*  Importing these resources to the target device may need conversions. Such resources like some

*  audio files etc., can be imported directly, however, most of the image-resources must be fitted

*  for the target device because target screen device's color depth and/or pixel density varies.

*  In this case, the needed conversions will be executed asynchronously. Asynchronous installation

*  is executed in phases - resource by resource. Client application must initiate asynchronous mode

*  by calling hspsInstallNextPhaseL() after testing that the synchronous call hspsInstallTheme() 

*  has returned EhspsInstallPhaseSuccess return code. This means that there are resources to convert 

*  asynchronoulsly. The rest of the asynchronous installation phases will be executed automatically, 

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

*  If installation is canceled, installation handler 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.

*  HSPS Definition Repository takes care of saving everything on their appropriate places in the

*  target device. Repository, i.e. theme storage, is loacted on hspsThemeServer's private-folder. 

*  The storage is organized by the information contained in ODT-header.

*  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 "HSPS Manifest File User Guide.doc".

*

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

*  - EhspsInstallThemeSuccess,

*  - EhspsInstallPhaseSuccess, or

*  - EhspsInstallThemeFailed.

*

*  Client application must implement MhspsThemeManagementServiceObserver-interface and listen the 

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

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

*  - EhspsServiceRequestSheduled, or

*  - EhspsServiceRequestError.

*

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

*  

*  @ingroup group_hspsserversession

*  @lib hspsThemeServer.exe

*  @since S60 5.0

*/

class ChspsInstallationHandler : public CBase, 

                                 public MhspsInstallationService, 

                                 public MContentHandler

    {

    public:

    public:

        /**

        * Two-phased constructor.

        */

        static ChspsInstallationHandler* NewL( ChspsThemeServer& aThemeServer );

        static ChspsInstallationHandler* NewLC( ChspsThemeServer& aThemeServer );

        /**

        * Destructor.

        */      

        ~ChspsInstallationHandler();

    public:  // New functions

        /**

        * ServiceInstallThemeL

        * Starts the actual installation in ChspsInstallationHandler.

        * @since S60 5.0

        * @param aMessage Message from client

        */      

        void ServiceInstallThemeL(

                const RMessage2& aMessage);

        /**

        * ServiceInstallNextPhaseL

        * Starts subsequent installation phases.

        * @since S60 5.0

        * @param aMessage Message from client

        */            

        void ServiceInstallNextPhaseL(

                const RMessage2& aMessage);

        /** 

        * hspsInstallNextPhase

        * @since S60 5.0

        * This is server-side only function.

        * @param aHeaderData will return ODT-header of the latest installation phase in serialized 

        *        (i.e. marshalled)

        *        data mode. This follows the low-level parametrization schema.  

        * @param aRequestStatus will return the status of the asynchronous request returned by 

        *        installer.

        * @return TInthspsServiceCompletedMessage expressing the result of the call.

        */

        void hspsInstallNextPhaseL( 

                TDes8& aHeaderData, 

                TRequestStatus& aRequestStatus );

        /** 

        * CheckAutoInstallationValidityL

        * Checks if auto installation of a theme is permitted

        * @since S60 5.0

        * This is server-side only function.

        * @return TBool ETrue if auto installation can proceed.

        */

        TBool CheckAutoInstallationValidityL();

#ifdef HSPS_LOG_ACTIVE        

        /** 

        * Set log bus.

        */

        void SetLogBus( ChspsLogBus* aLogBus );

#endif        

        /**

         * Disables "configuration was installed" notifications

         * @since S60 5.0

         */

        void DisableNotifications();

    public: // Functions from base classes

        /**

        * From MhspsInstallationService hspsInstallTheme

        * 

        * @since S60 5.0

        * @param aManifestFileName is the full path to the installation script file - a manifest 

        *        file.

        * @param aHeader is an empty ChspsODT-object in which a valid ODT-header of the newly 

        *        installed theme will be returned if the request is successful. The use of 

        *        ChspsODT-type parameter follows the high-level parametrization schema.

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        inline ThspsServiceCompletedMessage hspsInstallTheme( 

                const TDesC& /*aManifestFileName*/, 

                ChspsODT& /*aHeader*/ );

        /**

        * From MhspsInstallationService hspsInstallTheme

        * 

        * @since S60 5.0

        * @param aManifestFileName is full path of the installation script file - a manifest file

        * @param aHeaderData will return ODT-header of the newly installed theme in serialized 

        *        (i.e. marshalled)

        *        data mode. This follows the low-level parametrization schema.  

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        ThspsServiceCompletedMessage hspsInstallTheme( 

                const TDesC& aManifestFileName, 

                TDes8& aHeaderData );

        /**

         * Parses the manifest file and requests installation of next phases.

         * @since S60 5.2

         * @param aManifest is full path of the installation script file - a manifest file

         */

        void DoInstallThemeL(

                const TDesC& aManifest );

        /**

        * From MhspsInstallationService hspsInstallNextPhaseL

        * 

        * @since S60 5.0

        * @param aHeader is an empty ChspsODT-object in which a valid ODT-header of the latest 

        *        installation phase completed if the request was successful. The use of ChspsODT-type

        *        parameter follow the high-level parametrization schema.

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        inline ThspsServiceCompletedMessage hspsInstallNextPhaseL( 

                ChspsODT& /*aHeader*/ );

        /**

        * From MhspsInstallationService hspsInstallNextPhaseL

        * 

        * @since S60 5.0

        * @param aHeaderData will return ODT-header of the latest installation phase in 

        *        serialized (i.e. marshalled) data mode. This follows the low-level 

        *        parametrization schema.  

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        ThspsServiceCompletedMessage hspsInstallNextPhaseL( 

                TDes8& aHeaderData );

        /**

        * From MhspsInstallationService hspsCancelInstallTheme

        * 

        * @since S60 5.0

        * @return ThspsServiceCompletedMessage expressing the result of the call.

        */

        ThspsServiceCompletedMessage hspsCancelInstallTheme();

        //From MContentHandler

        /**

        * OnStartDocumentL

        * @since S60 5.0

        * This method is a callback to indicate the start of the document.

        * @param  aDocParam Specifies the various parameters of the document.

        * @arg  aDocParam.iCharacterSetName The character encoding of the document.

        * @param  aErrorCode is the error code. 

        * If this is not KErrNone then special action may be required.

        */

        inline void OnStartDocumentL(

                const RDocumentParameters& aDocParam, 

                TInt aErrorCode);

        /**

        * OnEndDocumentL

        * @since S60 5.0

        * This method is a callback to indicate the end of the document.

        * @param  aErrorCode is the error code. 

        * If this is not KErrNone then special action may be required.

        */

        inline void OnEndDocumentL(

                TInt aErrorCode);

        /**

        * OnStartElementL

        * @since S60 5.0

        * This method is a callback to indicate an element has been parsed.

        * @param  aElement is a handle to the element's details.

        * @param  aAttributes contains the attributes for the element.

        * @param  aErrorCode is the error code.

        *    If this is not KErrNone then special action may be required.

        */

        void OnStartElementL(

                const RTagInfo& aElement, 

                const RAttributeArray& aAttributes, 

                TInt aErrorCode);

        /**

        * OnEndElementL

        * @since S60 5.0

        * This method is a callback to indicate the end of the element has been reached.

        * @param  aElement is a handle to the element's details.

        * @param  aErrorCode is the error code.

        * If this is not KErrNone then special action may be required.

        */

        void OnEndElementL(

                const RTagInfo& aElement, 

                TInt aErrorCode);

        /**

        * OnContentL

        * @since S60 5.0

        * This method is a callback that sends the content of the element.

        * Not all the content may be returned in one go. The data may be sent in chunks.

        * When an OnEndElementL is received this means there is no more content to be sent.

        * @param  aBytes is the raw content data for the element. 

        *     The client is responsible for converting the data to the 

        *     required character set if necessary.

        *     In some instances the content may be binary and must not be converted.

        * @param  aErrorCode is the error code.

        *     If this is not KErrNone then special action may be required.

        */

        void OnContentL(

                const TDesC8& aBytes, 

                TInt aErrorCode);

        /**

        * OnStartPrefixMappingL

        * @since S60 5.0

        * This method is a notification of the beginning of the scope of a prefix-URI Namespace mapping.

        * This method is always called before the corresponding OnStartElementL method.

        * @param  aPrefix is the Namespace prefix being declared.

        * @param  aUri is the Namespace URI the prefix is mapped to.

        * @param  aErrorCode is the error code.

        *         If this is not KErrNone then special action may be required.

        */

        inline void OnStartPrefixMappingL(

                const RString& aPrefix, 

                const RString& aUri, 

                TInt aErrorCode);

        /**

        * OnEndPrefixMappingL

        * @since S60 5.0

        * This method is a notification of the end of the scope of a prefix-URI mapping.

        * This method is called after the corresponding DoEndElementL method.

        * @param aPrefix is the Namespace prefix that was mapped.

        * @param aErrorCode is the error code.

        *        If this is not KErrNone then special action may be required.

        */

        inline void OnEndPrefixMappingL(

                const RString& aPrefix, 

                TInt aErrorCode);

        /**

        * OnIgnorableWhiteSpaceL

        * @since S60 5.0

        * This method is a notification of ignorable whitespace in element content.

        * @param  aBytes are the ignored bytes from the document being parsed.

        * @param  aErrorCode is the error code.

        * If this is not KErrNone then special action may be required.

        */

        inline void OnIgnorableWhiteSpaceL(

                const TDesC8& aBytes, 

                TInt aErrorCode);

        /**

        * OnSkippedEntityL

        * @since S60 5.0

        * This method is a notification of a skipped entity. If the parser encounters an 

        * external entity it does not need to expand it - it can return the entity as aName 

        * for the client to deal with.

        * @param  aName is the name of the skipped entity.

        * @param  aErrorCode is the error code.

        * If this is not KErrNone then special action may be required.

        */

        inline void OnSkippedEntityL(

                const RString& aName, 

                TInt aErrorCode);

        /**

        * OnProcessingInstructionL

        * @since S60 5.0

        * This method is a receive notification of a processing instruction.

        * @param  aTarget is the processing instruction target.

        * @param  aData is the processing instruction data. If empty none was supplied.

        * @param  aErrorCode is the error code.

        * If this is not KErrNone then special action may be required.

        */

        inline void OnProcessingInstructionL(

                const TDesC8& aTarget, 

                const TDesC8& aData,

                TInt aErrorCode);

        /**

        * OnError

        * @since S60 5.0

        * This method indicates an error has occurred.

        * @param  aError is the error code

        */

        inline void OnError(

                TInt aErrorCode);

        /**

        * GetExtendedInterface

        * @since S60 5.0

        * This method obtains the interface matching the specified uid.

        * @return 0 if no interface matching the uid is found.

        *         Otherwise, the this pointer cast to that interface.

        * @param  aUid the uid identifying the required interface.

        */

        inline TAny* GetExtendedInterface(

                const TInt32 aUid);

    protected:  // New functions

        /**

        * Rolls back the installation if it fails or is cancelled.

        * @since S60 5.0

        * @param aOdt The ODT of the theme

        */

        void RollBackL( ChspsODT& aOdt );

    private:    

        /**

        * C++ default constructor.

        * @since S60 5.0

        */

        ChspsInstallationHandler( 

                ChspsThemeServer& aThemeServer );

        /**

        * By default Symbian 2nd phase constructor is private.

        * @since S60 5.0

        */ 

        void ConstructL();

        /**

        * CheckHeaderL

        * Checks the header information and stores it to iOdt

        * @since S60 5.0

        */

        void CheckHeaderL();

        /**

        * InstallOdtL

        * Installs the theme skeleton

        * @since S60 5.0

        */

        void InstallSkeletonL( 

                ThspsServiceCompletedMessage& aReturnMsg );        

        /**

         * Adds parsed resource into a temporary resource list, from which the resources

         * are applied to an ODT instance at later phase

         * @since S60 5.0

         * @param aArray is either iResourceArray or iLocalizedResourceArray instance 

         * @param aFilename is full path and filename to the resource in an installation folder

         * @param aLanguage is language of the resource (use ELangNone if it's a common resource)

         * @param aResourceType is MIME type or NULL      

         * @param aMimetype (Optional)   

         * @param aTag (Optional)

         */

        void AddResourceL(

                CArrayPtrSeg<ChspsResource>& aArray, 

                const TPtrC aFilename,

                const TLanguage aLanguage,

                const ThspsResourceType aResourceType,

                const TPtrC8 aMimetype,

                const TPtrC8 aTag );

        /**

        * CleanupL

        * Executes cleaning of the target folder prior to the installation process

        * @since S60 5.0

        */

        void CleanupL( 

                const ChspsODT& aUpdateMask );

        /**

         * ImportPluginsL         

         * Imports plug-in DOMs referenced by application configuration, other 

         * configuration types are ignored.

         * @since S60 5.0

         */

        void ImportPluginsL( );

        /**

        * ParseDocumentL

        * Calls the definition engine to create the dom 

        * @since S60 5.0

        */

        void ParseDocumentL( 

                ChspsODT& aOdt );

        /**

        * CompleteRequestL

        * Completes the request message

        * @since S60 5.0

        */

        void CompleteRequestL(const ThspsServiceCompletedMessage aReturnMessage, 

                const TDesC8& aHeaderData = KNullDesC8 );