1 /*

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

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef XCFWENGINE_H

    21 #define XCFWENGINE_H

    22 

    23 //  INCLUDES

    24 #include <s32std.h>

    25 #include <gmxmlparser.h>

    26 #include <gmxmlcomposer.h>

    27 #include "gecodefaultobjectfactory.h"

    28 

    29 // FORWARD DECLARATIONS

    30 class CXCFWEntityConverter;

    31 class CMDXMLNode;

    32 class MXCFWTree;

    33 class MXCFWNode;

    34 class CXCFWLocalizer;

    35 

    36 // DATA TYPES

    37 typedef RPointerArray<CGECOObjectFactoryBase> RFactoryArray;

    38 

    39 // CONSTANTS

    40 // XCFW error range: -32350, -32379

    41 const TInt KErrDTDLoadFailed = -32350;

    42 

    43 // CLASS DECLARATION

    44 /**

    45 * Engine observer interface. Engine user must implement this interface

    46 *

    47 * @lib XCFW.lib

    48 * @since Series 60 3.1

    49 */

    50 class MXCFWEngineObserver

    51     {

    52     public: //event enumeration

    53     

    54     enum TXCFWEngineEvent //Engine events

    55         {

    56         EEvtNull = 0,           //for module testing purposes only

    57         EEvtParsingStarted,     //triggered when DOM to Tree parsing starts

    58         EEvtParsingComplete,    //triggered when whole DOM has been processed

    59         EEvtSavingStarted,      //triggered when Tree to DOM composing starts

    60         EEvtSavingComplete,     //triggered when composing is done

    61         EEvtParsingCanceled,    //triggered when parsing is canceled by client

    62         EEvtSavingCanceled,     //triggered when saving is canceled by client

    63         };

    64 

    65     public: //new functions

    66     /**

    67     * Called when Engine parsing / saving state changes

    68     * User can do desired actions on corresponding events.

    69     * @param aEvent Engine event

    70     */

    71     virtual void HandleEngineEventL( TXCFWEngineEvent aEvent ) = 0;

    72     

    73     /**

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

    75     * @param aErrorCode Error code from engine

    76     */

    77     virtual void HandleEngineErrorL( TInt aErrorCode ) = 0;        

    78     };

    79 

    80 

    81 

    82 /**

    83 *  XCFW Engine class

    84 *  Responsible for internalizing / externalizing XML files

    85 *  to and from a XCFW tree 

    86 *

    87 *  @lib XCFW.lib

    88 *  @since Series 60 3.1

    89 */

    90 class CXCFWEngine: public CActive,

    91                    public MGECOAttributeProvider,

    92                    public MMDXMLParserObserver,

    93                    public MMDXMLComposerObserver

    94     {

    95     public:

    96     

    97     enum TXCFWEngineState // Engine states

    98         {

    99         EStateIdle = 0,             //when engine is not active

   100         EStateInitializingLoad,     //when initializing Load operation

   101         EStateLoadingFile,          //when GMXML parser is loading

   102         EStateInitializingSave,     //when initializing save op

   103         EStateSavingFile,           //when GMXML Composer is saving

   104         EStateParsing,              //when parsing DOM to content tree

   105         EStateConstructingDOM       //when constructing DOM from XCFWTree

   106         };

   107 

   108 

   109     public:  // Constructors and destructor

   110         

   111         /**

   112         * Two-phased constructor.

   113         */

   114         IMPORT_C static CXCFWEngine* NewL( MXCFWEngineObserver* aObserver );

   115 

   116         /**

   117         * Destructor.

   118         */

   119         IMPORT_C virtual ~CXCFWEngine();

   120 

   121     public: // New functions

   122         

   123         /**

   124         * Cancels currently ongoing load/save operation

   125         * @since Series 60 3.1

   126         */

   127         IMPORT_C void CancelOperation();

   128 

   129         /**

   130         * Loads given XML content definition to given tree.

   131         * Operation is asynchronous. Engine will notify client through

   132         * MXCFWEngineObserver interface when parsing completes.

   133         * XCFW Engine will look for localization DTD based on the

   134         *  doctype declaration of loaded XML file. It assumes that

   135         *  the localization files are stored in language variant

   136         *  specific subdirectories under the directory where the

   137         *  loaded content file exists. 

   138         * @since Series 60 3.1

   139         * @param aTree Target tree to construct the content into

   140         * @param aFile File to load

   141         */

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

   143         

   144         /**

   145         * Loads given XML content definition to given tree with

   146         * localized strings from given DTD file

   147         * Operation is asynchronous.

   148         * @since Series 60 3.1

   149         * @param aTree Target tree to construct the content into

   150         * @param aFile File to load

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

   152         *   overrides the possible DOCTYPE definition in the XML file.

   153         */

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

   155             const TDesC& aDTDFile );

   156 

   157         /**

   158         * Saves given Tree to given XML content definition file.

   159         * Operation is asynchronous.

   160         * @since Series 60 3.1

   161         * @param aTree Target tree to construct XML from

   162         * @param aFile File to save the XML definition to

   163         */

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

   165 

   166         /**

   167         * Saves given Tree to given XML content definition file with

   168         * entity references from given DTD file.

   169         * Operation is asynchronous.

   170         * @since Series 60 3.1

   171         * @param aTree Target tree to construct XML from

   172         * @param aFile File to save the XML definition to

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

   174         *   parameter overrides the possible DOCTYPE definition that was

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

   176         */

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

   178             const TDesC& aDTDFile );

   179         

   180         /**

   181         * Adds new object factory to engine factory array.

   182         * Engine does NOT take ownership of the factory.

   183         * @since Series 60 3.1

   184         * @param aFactory Object factory to add. Engine will

   185         *  query factories for objects when constructing tree.

   186         */

   187         IMPORT_C void RegisterObjectFactoryL( 

   188             CGECOObjectFactoryBase* aFactory );

   189 

   190         /**

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

   192         * @since Series 60 3.1

   193         * @param aFactory Object factory to be removed

   194         */

   195         IMPORT_C TInt UnRegisterObjectFactory( 

   196             CGECOObjectFactoryBase* aFactory );

   197 

   198         /**

   199         * Returns engine's current state

   200         * Client may want to check state at error events

   201         * @since Series 60 3.1

   202         * @return Engine state

   203         */

   204         IMPORT_C TXCFWEngineState CurrentState();

   205 

   206 

   207     public: // Functions from base classes

   208 

   209         /**

   210         * From MGECOAttributeProvider. 

   211         * Returns attribute details for given index.

   212         */

   213         IMPORT_C void AttributeDetailsL( const TInt aIndex, 

   214             TPtrC& aAttributeName, 

   215             TPtrC& aAttributeValue, 

   216             TBool& aIsLocalized);

   217 

   218         /**

   219         * From MGECOAttributeProvider. 

   220         * Returns attribute details for given index.

   221         */

   222         IMPORT_C void AttributeDetailsL( const TInt aIndex, 

   223             TPtrC& aAttributeName, 

   224             TPtrC& aAttributeValue);

   225 

   226         /** 

   227         * From MGECOAttributeProvider. 

   228         * Returns number of attributes for a xml tag.

   229         */

   230         IMPORT_C TInt NumAttributes();

   231 

   232         /**

   233         * From MGECOAttributeProvider. Returns node / data object text

   234         * and possible localization status for the text.

   235         */

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

   237         

   238         /**

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

   240         */

   241         IMPORT_C TBool HasTextData();

   242         

   243         /**

   244         * From MMDXMLParserObserver. Called when XML to DOM 

   245         * parsing is done

   246         */

   247         void ParseFileCompleteL();

   248 

   249         /**

   250         * From MMDXMLComposerObserver. Called when DOM to XML 

   251         * composing is done.

   252         */

   253         void ComposeFileCompleteL();

   254 

   255     protected:  // Functions from base classes

   256 

   257         //From CActive

   258         void RunL();

   259         void DoCancel();

   260         TInt RunError( TInt aError );

   261         

   262     private:

   263 

   264         /**

   265         * C++ default constructor.

   266         * @param aObserver Engine observer

   267         */

   268         CXCFWEngine( MXCFWEngineObserver* aObserver );

   269 

   270         /**

   271         * By default Symbian 2nd phase constructor is private.

   272         */

   273         void ConstructL();

   274 

   275         

   276         /**

   277         * Traverses XML DOM and constructs XCFW tree

   278         * Each call to this function processes one DOM element

   279         * @since Series 60 3.1

   280         */

   281         void DOM2TreeNextCycleL();

   282         

   283         /**

   284         * Traverses content tree and constructs XML DOM

   285         * Each call to this function processes one XCFW Tree element

   286         * @since Series 60 3.1

   287         */

   288         void Tree2DOMNextCycleL();

   289         

   290         /**

   291         * Adds a XCFW Tree node to DOM

   292         * Called repeatedly during parsing from Tree2DOMNextCycle()

   293         * @since Series 60 3.1

   294         */

   295         void AddCurrentTreeNodeToDOML();

   296         

   297         /**

   298         * Adds a XML element to content tree

   299         * Called repeatedly during parsing from Dom2TreeNextCycle()

   300         * @since Series 60 3.1

   301         */

   302         void AddCurrentXMLNodeToTreeL();

   303 

   304         /**

   305         * Frees resources used during parse / compose operation

   306         * @since Series 60 3.1

   307         */

   308         void FreeResources();

   309 

   310         /**

   311         * Loads DTD for the requested save / load op

   312         * and sets engine active. 

   313         * @since Series 60 3.1

   314         */

   315         void PrepareEntityConverterAndSetActiveL();

   316         

   317         /**

   318         * Prepares DTD file path for localization file loading

   319         * This function checks the DTD path from XML doctype declaration

   320         */

   321         void PrepareDTDPathL();

   322         

   323 

   324     private:    // Data

   325         // Engine observer. Not owned

   326         MXCFWEngineObserver*        iObserver;

   327 

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

   329         RFactoryArray               iFactoryList;

   330 

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

   332         CGECODefaultObjectFactory*  iDefaultFactory;

   333         

   334         // file system handle for load / save ops

   335         RFs                         iFileSystem;

   336         

   337         // XML file name buffer

   338         HBufC*                      iFile;

   339         

   340         // DTD file name buffer

   341         HBufC*                      iDTD;

   342         

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

   344         HBufC*                      iNodeText;

   345         

   346         // XML Parser

   347         CMDXMLParser*               iParser;

   348         

   349         // XML Composer

   350         CMDXMLComposer*             iComposer;

   351         

   352         //XML document to operate with.

   353         CMDXMLDocument*             iXMLDoc;

   354 

   355         //Current XML node

   356         CMDXMLNode*                 iCurrentXMLNode;

   357         

   358         // Localization utility class

   359         CXCFWLocalizer*             iLocalizer;

   360 

   361         //Tree to operate with. Not owned.

   362         MXCFWTree*                  iTree;

   363 

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

   365         MXCFWNode*                  iCurrentTreeNode;

   366         

   367         // engine internal state

   368         TXCFWEngineState            iState;

   369         

   370         // engine internal state by last error

   371         TXCFWEngineState            iStateByLastError;

   372     

   373         // Entity converter

   374         CXCFWEntityConverter*       iConverter;

   375 

   376     };

   377 

   378 #endif      // XCFWENGINE_H   

   379             

   380 // End of File