--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/homescreensrv_plat/xcfw_api/inc/xcfwengine.h Thu Dec 17 08:54:17 2009 +0200
@@ -0,0 +1,380 @@
+/*
+* 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