/*

* Copyright (c) 2002-2005 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:  Class definitions for XCFW Engine

*

*/

#ifndef XCFWENGINE_H

#define XCFWENGINE_H

//  INCLUDES

#include <s32std.h>

#include <gmxmlparser.h>

#include <gmxmlcomposer.h>

#include "gecodefaultobjectfactory.h"

// FORWARD DECLARATIONS

class CXCFWEntityConverter;

class CMDXMLNode;

class MXCFWTree;

class MXCFWNode;

class CXCFWLocalizer;

// DATA TYPES

typedef RPointerArray<CGECOObjectFactoryBase> RFactoryArray;

// CONSTANTS

// XCFW error range: -32350, -32379

const TInt KErrDTDLoadFailed = -32350;

// CLASS DECLARATION

/**

* Engine observer interface. Engine user must implement this interface

*

* @lib XCFW.lib

* @since Series 60 3.1

*/

class MXCFWEngineObserver

    {

    public: //event enumeration

    enum TXCFWEngineEvent //Engine events

        {

        EEvtNull = 0,           //for module testing purposes only

        EEvtParsingStarted,     //triggered when DOM to Tree parsing starts

        EEvtParsingComplete,    //triggered when whole DOM has been processed

        EEvtSavingStarted,      //triggered when Tree to DOM composing starts

        EEvtSavingComplete,     //triggered when composing is done

        EEvtParsingCanceled,    //triggered when parsing is canceled by client

        EEvtSavingCanceled,     //triggered when saving is canceled by client

        };

    public: //new functions

    /**

    * Called when Engine parsing / saving state changes

    * User can do desired actions on corresponding events.

    * @param aEvent Engine event

    */

    virtual void HandleEngineEventL( TXCFWEngineEvent aEvent ) = 0;

    /**

    * Called when there's an error during parsing / saving

    * @param aErrorCode Error code from engine

    */

    virtual void HandleEngineErrorL( TInt aErrorCode ) = 0;        

    };

/**

*  XCFW Engine class

*  Responsible for internalizing / externalizing XML files

*  to and from a XCFW tree 

*

*  @lib XCFW.lib

*  @since Series 60 3.1

*/

class CXCFWEngine: public CActive,

                   public MGECOAttributeProvider,

                   public MMDXMLParserObserver,

                   public MMDXMLComposerObserver

    {

    public:

    enum TXCFWEngineState // Engine states

        {

        EStateIdle = 0,             //when engine is not active

        EStateInitializingLoad,     //when initializing Load operation

        EStateLoadingFile,          //when GMXML parser is loading

        EStateInitializingSave,     //when initializing save op

        EStateSavingFile,           //when GMXML Composer is saving

        EStateParsing,              //when parsing DOM to content tree

        EStateConstructingDOM       //when constructing DOM from XCFWTree

        };

    public:  // Constructors and destructor

        /**

        * Two-phased constructor.

        */

        IMPORT_C static CXCFWEngine* NewL( MXCFWEngineObserver* aObserver );

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CXCFWEngine();

    public: // New functions

        /**

        * Cancels currently ongoing load/save operation

        * @since Series 60 3.1

        */

        IMPORT_C void CancelOperation();

        /**

        * Loads given XML content definition to given tree.

        * Operation is asynchronous. Engine will notify client through

        * MXCFWEngineObserver interface when parsing completes.

        * XCFW Engine will look for localization DTD based on the

        *  doctype declaration of loaded XML file. It assumes that

        *  the localization files are stored in language variant

        *  specific subdirectories under the directory where the

        *  loaded content file exists. 

        * @since Series 60 3.1

        * @param aTree Target tree to construct the content into

        * @param aFile File to load

        */

        IMPORT_C void LoadL( MXCFWTree& aTree, const TDesC& aFile );

        /**

        * Loads given XML content definition to given tree with

        * localized strings from given DTD file

        * Operation is asynchronous.

        * @since Series 60 3.1

        * @param aTree Target tree to construct the content into

        * @param aFile File to load

        * @param aDTDFile DTD to use for localization. This parameter

        *   overrides the possible DOCTYPE definition in the XML file.

        */

        IMPORT_C void LoadL( MXCFWTree& aTree, const TDesC& aFile, 

            const TDesC& aDTDFile );

        /**

        * Saves given Tree to given XML content definition file.

        * Operation is asynchronous.

        * @since Series 60 3.1

        * @param aTree Target tree to construct XML from

        * @param aFile File to save the XML definition to

        */

        IMPORT_C void SaveL( MXCFWTree& aTree, const TDesC& aFile );

        /**

        * Saves given Tree to given XML content definition file with

        * entity references from given DTD file.

        * Operation is asynchronous.

        * @since Series 60 3.1

        * @param aTree Target tree to construct XML from

        * @param aFile File to save the XML definition to

        * @param aDTDFile DTD to use for entity localization. This

        *   parameter overrides the possible DOCTYPE definition that was

        *   internalized to content tree when it was loaded from XML.

        */

        IMPORT_C void SaveL( MXCFWTree& aTree, const TDesC& aFile,

            const TDesC& aDTDFile );

        /**

        * Adds new object factory to engine factory array.

        * Engine does NOT take ownership of the factory.

        * @since Series 60 3.1

        * @param aFactory Object factory to add. Engine will

        *  query factories for objects when constructing tree.

        */

        IMPORT_C void RegisterObjectFactoryL( 

            CGECOObjectFactoryBase* aFactory );

        /**

        * Removes a factory from Engine's object factory array.

        * @since Series 60 3.1

        * @param aFactory Object factory to be removed

        */

        IMPORT_C TInt UnRegisterObjectFactory( 

            CGECOObjectFactoryBase* aFactory );

        /**

        * Returns engine's current state

        * Client may want to check state at error events

        * @since Series 60 3.1

        * @return Engine state

        */

        IMPORT_C TXCFWEngineState CurrentState();

    public: // Functions from base classes

        /**

        * From MGECOAttributeProvider. 

        * Returns attribute details for given index.

        */

        IMPORT_C void AttributeDetailsL( const TInt aIndex, 

            TPtrC& aAttributeName, 

            TPtrC& aAttributeValue, 

            TBool& aIsLocalized);

        /**

        * From MGECOAttributeProvider. 

        * Returns attribute details for given index.

        */

        IMPORT_C void AttributeDetailsL( const TInt aIndex, 

            TPtrC& aAttributeName, 

            TPtrC& aAttributeValue);

        /** 

        * From MGECOAttributeProvider. 

        * Returns number of attributes for a xml tag.

        */

        IMPORT_C TInt NumAttributes();

        /**

        * From MGECOAttributeProvider. Returns node / data object text

        * and possible localization status for the text.

        */

        IMPORT_C void TextDetailsL( TPtrC& aText, TBool& aIsLocalized );

        /**

        * From MGECOAttributeProvider. Returns ETrue if xml node has text data

        */

        IMPORT_C TBool HasTextData();

        /**

        * From MMDXMLParserObserver. Called when XML to DOM 

        * parsing is done

        */

        void ParseFileCompleteL();

        /**

        * From MMDXMLComposerObserver. Called when DOM to XML 

        * composing is done.

        */

        void ComposeFileCompleteL();

    protected:  // Functions from base classes

        //From CActive

        void RunL();

        void DoCancel();

        TInt RunError( TInt aError );

    private:

        /**

        * C++ default constructor.

        * @param aObserver Engine observer

        */

        CXCFWEngine( MXCFWEngineObserver* aObserver );

        /**

        * By default Symbian 2nd phase constructor is private.

        */

        void ConstructL();

        /**

        * Traverses XML DOM and constructs XCFW tree

        * Each call to this function processes one DOM element

        * @since Series 60 3.1

        */

        void DOM2TreeNextCycleL();

        /**

        * Traverses content tree and constructs XML DOM

        * Each call to this function processes one XCFW Tree element

        * @since Series 60 3.1

        */

        void Tree2DOMNextCycleL();

        /**

        * Adds a XCFW Tree node to DOM

        * Called repeatedly during parsing from Tree2DOMNextCycle()

        * @since Series 60 3.1

        */

        void AddCurrentTreeNodeToDOML();

        /**

        * Adds a XML element to content tree

        * Called repeatedly during parsing from Dom2TreeNextCycle()

        * @since Series 60 3.1

        */

        void AddCurrentXMLNodeToTreeL();

        /**

        * Frees resources used during parse / compose operation

        * @since Series 60 3.1

        */

        void FreeResources();

        /**

        * Loads DTD for the requested save / load op

        * and sets engine active. 

        * @since Series 60 3.1

        */

        void PrepareEntityConverterAndSetActiveL();

        /**

        * Prepares DTD file path for localization file loading

        * This function checks the DTD path from XML doctype declaration

        */

        void PrepareDTDPathL();

    private:    // Data

        // Engine observer. Not owned

        MXCFWEngineObserver*        iObserver;

        // Object factory array. Factory pointers are not owned.

        RFactoryArray               iFactoryList;

        // Default factory (used if there's no object factory from client)

        CGECODefaultObjectFactory*  iDefaultFactory;

        // file system handle for load / save ops

        RFs                         iFileSystem;

        // XML file name buffer

        HBufC*                      iFile;

        // DTD file name buffer

        HBufC*                      iDTD;

        // Current node's text (all text with cdatasections included)

        HBufC*                      iNodeText;

        // XML Parser

        CMDXMLParser*               iParser;

        // XML Composer

        CMDXMLComposer*             iComposer;

        //XML document to operate with.

        CMDXMLDocument*             iXMLDoc;

        //Current XML node

        CMDXMLNode*                 iCurrentXMLNode;

        // Localization utility class

        CXCFWLocalizer*             iLocalizer;

        //Tree to operate with. Not owned.

        MXCFWTree*                  iTree;

        //Current parent node used during parsing. Not owned.

        MXCFWNode*                  iCurrentTreeNode;

        // engine internal state

        TXCFWEngineState            iState;

        // engine internal state by last error

        TXCFWEngineState            iStateByLastError;

        // Entity converter

        CXCFWEntityConverter*       iConverter;

    };

#endif      // XCFWENGINE_H   

// End of File