diff -r 000000000000 -r 79c6a41cd166 menucontentsrv/enginc/menueng.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/menucontentsrv/enginc/menueng.h Thu Dec 17 08:54:17 2009 +0200 @@ -0,0 +1,502 @@ +/* +* Copyright (c) 2009 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: +* +*/ + +#ifndef __MENUENG_H__ +#define __MENUENG_H__ + +#include +#include +#include // for RNodeArray +#include "mcsmenunotifier.h" // for notification events + +// FORWARD DECLARATION + +class TMenuItem; +class CXCFWTree; +class MXCFWNode; +class CMenuEngObjectFactoryProxy; +class CMenuEngObject; +class CMenuEngIdManager; +class MMenuEngObserver; +class MMenuEngOperation; +class MMenuEngFilter; +class MMenuEngVisitor; + +/** +* Event notification data. +*/ +class TMenuEngNotify + { + +public: // construction + + /** + * Constructor. + * @param aFolder Folder. + * @param aEvents Events. + */ + TMenuEngNotify( TInt aFolder, TInt aEvents ) + : iFolder( aFolder ), iEvents( aEvents ) {} + +public: // data + + TInt iFolder; ///< Folder. + TInt iEvents; ///< Events. + + }; + +/** +* Menu Engine. +*/ +NONSHARABLE_CLASS( CMenuEng ): public CActive, public MXCFWEngineObserver + { + +public: // construction + + /** + * Destructor. + */ + IMPORT_C virtual ~CMenuEng(); + + /** + * Two-phased constructor. + * @param aName Name. + * @param aObserver Observer. + * @return The created object. + */ + IMPORT_C static CMenuEng* NewL( + const TDesC& aName, + MMenuEngObserver& aObserver ); + +protected: // construction + + /** + * Constructor. + * @param aObserver Observer. + */ + CMenuEng( MMenuEngObserver& aObserver ); + + /** + * Second phase constructor. + * @param aName Name. + */ + void ConstructL( const TDesC& aName ); + +public: // new methods + + enum TState /// State machine states. + { + ENull = 0, ///< Initial state. + ELoadRamFile, ///< Loading RAM file. + ELoadRomFile, ///< Loading ROM file. + ESaveFile, ///< Saving TEMP file and replacing RAM file. + EExecuteOp, ///< Operation scheduled for execution or being executed. + EReady, ///< Idle. + EDead ///< Unrecoverable error; final state. + }; + + /** + * Queue an operation for execution. + * Queued operations are scheduled for execution by the Engine. + * @param aOperation Operation. + */ + IMPORT_C void QueueOperationL( MMenuEngOperation& aOperation ); + + /** + * Dequeue an operation (remove from the operation queue). Safe to call + * if not queued. + * @param aOperation Operation. + */ + IMPORT_C void DequeueOperation( MMenuEngOperation& aOperation ); + + /** + * Traverse a subtree of the item tree. + * @param aFolder traversal starts at this folder. + * @param aVisitor Visitor visiting the nodes and controlling the traversal. + */ + IMPORT_C void TraverseFolderL( + TInt aFolder, + MMenuEngVisitor& aVisitor ) const; + + /** + * Create a new object. Owner is the caller. The object is not added to + * the engine yet, but it has an ID already. It can be used to AddL() item. + * @param aType Type. + * @return Created object. Owner is the caller. + */ + IMPORT_C CMenuEngObject* NewObjectL( const TDesC& aType ); + + /** + * Returns current engine state. + * @return Current state. + */ + inline TState State() const; + + /* + * Gets legacy format + * @return legacy format + */ + IMPORT_C TBool GetOnceLegacyFormat(); + +public: // data query (read access) + + // Read-access methods can be called any time. + // There is a short startup period during which the engine data is not + // ready yet; calls made in that period leave with KErrNotReady. + // When the engine becomes ready, an (0 ,EItemsAddedRemoved) event is + // sent to the observer. + + /** + * Get ID of root folder. + * @param aId ID of root folder. + */ + IMPORT_C void RootFolderL( TInt& aId ) const; + + /** + * Get parent folder of item. + * @param aId Item ID. + * @param aParentId ID of parent folder. + */ + IMPORT_C void ParentFolderL( TInt aId, TInt& aParentId ) const; + + /** + * Get item header. + * @param aId Item ID. + * @param aItem Item header is returned here. + */ + IMPORT_C void GetItemL( TInt aId, TMenuItem& aItem ) const; + + /** + * Get list of items. + * @param aItemArray Array receiving item list. Existing content not touched + * (new items are appended). + * @param aFolder Get items from this folder. + * @param aFilter Filter criteria or NULL for unfiltered results. + * @param aRecursive ETrue to recurse folders, EFalse for immediate + * children only. + */ + IMPORT_C void GetItemsL( + RArray& aItemArray, + TInt aFolder, + const MMenuEngFilter* aFilter, + TBool aRecursive ) const; + + /** + * Get object. + * @param aId Item ID. + * @return Object. + */ + IMPORT_C const CMenuEngObject& ObjectL( TInt aId ) const; + +public: // data manipulation (write access). + + // All write-access methods methods must be wrapped in MMenuEngOperation + // objects (scheduled execution), otherwise they leave with KErrLocked. + + /** + * Remove item. + * @param aId ID of item to be removed. + */ + IMPORT_C void RemoveL( TInt aId ); + + /** + * Move items to another folder. + * @param aItems ID-s of items to be to be moved. All items must be in + * the same folder. + * @param aFolder Target folder. + * @param aMoveBefore. In the target folder, items will be inserted before + * this item (if found). If the target folder contains no item with that ID, + * the moved items are appended to the end of existing items. Pass 0 to + * append to the end. + */ + IMPORT_C void MoveToFolderL( + RArray& aItems, + TInt aFolder, + TInt aMoveBefore ); + + /** + * Move item to a different position in its current folder. + * @param aId ID of item to be to be reordered. + * @param aMoveBefore. Move the item before this item (if found). + * If aMoveBefore is not found, the item is moved to the end. + */ + IMPORT_C void ReorderL( TInt aId, TInt aMoveBefore ); + + /** + * Add new object. + * @param aObject Object to be added. Note, the object must have been + * created with NewObjectL of THIS engine (or the call fails)! + * Ownership taken. + * @param aFolder Parent folder. + * @param aMoveBefore. Move the item before this item (if found). + * If aMoveBefore is not found, the item is added to the end. + */ + IMPORT_C void AddL( + CMenuEngObject& aObject, + TInt aFolder, + TInt aInsertBefore ); + + /** + * Get modifiable object. Note: when this method is called, the engine + * marks the object as changed (without checking if there was really + * a change or not). Therefore, it is advisable to use ObjectL() to + * investigate an object, and only call ModifiableObjectL if changes are + * really needed. This results in better performace, as it avoids + * unnecessary saving. + * @param aId Item ID. + * @param aEvent event for engine to append. + * @return Modifiable object. Already marked as changed. + */ + IMPORT_C CMenuEngObject& ModifiableObjectL( TInt aId, + TInt aEvent = RMenuNotifier::EItemAttributeChanged ); + + + /** + * Append new notification to the list of pending notifications. + * @param aFolder Folder. + * @param aEvents Events. + */ + IMPORT_C void AppendNotifyL( TInt aFolder, TInt aEvents ); + + + IMPORT_C TBool Exist( TInt aId ) const; + +private: // from CActive + + /** + * Outstanding request completed. + */ + void RunL(); + + /** + * Cancel outstanding request. + */ + void DoCancel(); + + /** + * Handle error. + * @param aError Error code. + * @return KErrNone. + */ + TInt RunError( TInt aError ); + +private: // from MXCFWEngineObserver + + /** + * Called when Engine parsing / saving state changes. + * @param aEvent Engine event + */ + void HandleEngineEventL( TXCFWEngineEvent aEvent ); + + /** + * Called when there's an error during parsing / saving. + * @param aErrorCode Error code + */ + void HandleEngineErrorL( TInt aErrorCode ); + +private: // types + + enum TFile /// File selector. + { + ERomFile, ///< Factory file in ROM. + ERamFile, ///< Working file in RAM. + ETempFile, ///< Temp file for saving (RAM). + }; + +private: // new methods + + /** + * Get object from node. + * @param aNode Node. + * @return Object. + */ + inline CMenuEngObject& Object( MXCFWNode& aNode ) const; + + /** + * Tree is up, perform structure check. + * @param aTree Tree. + * @return The root folder node. + */ + MXCFWNode& CheckTreeL( MXCFWTree& aTree ) const; + + /** + * Sanity ID check for all nodes in the tree. + * @param aTree Tree. + * @return ETrue if ID-s are OK. + */ + TBool DebugSanityCheck( MXCFWTree& aTree ) const; + + /** + * Wait for data xml file to load. + */ + void ActiveWaitForFileLoadL(); + + /** + * Sanity ID check for one nodes in the tree. + * @param aNode Node. + * @return ETrue if ID is OK. + */ + TBool DebugSanityCheck( MXCFWNode& aNode ) const; + + /** + * Find node by ID, leave with KErrNotFound if not found. + * @param aId ID. + * @return Node. + */ + MXCFWNode& NodeL( TInt aId ) const; + + /** + * Find folder node by ID, leave with KErrNotFound if not found or not + * folder. + * @param aId ID. + * @return Folder node. + */ + MXCFWNode& FolderNodeL( TInt aId ) const; + + /** + * Find child of aParent with given id, or NULL. Not recursive. + * @param aParent Folder. + * @param aId Child ID. + * @return Child or NULL. + */ + MXCFWNode* Child( MXCFWNode& aParent, TInt aId ); + + /** + * Cancel all operations in the queue. + */ + void CancelAllOperations(); + + /** + * Validate content filename. Leave with KErrArgument if not valid. + * @param aName Content filename (without extension). + */ + void ValidateNameL( const TDesC& aName ); + + /** + * Generate filename of content file. + * @param aFname Generated filename is returned here. + * @param aSelector Filename selector. + */ + void GetFileNameL( TFileName& aFname, TFile aSelector ); + + /** + * Traverse a node. + * @param aNode Node. + * @param aVisitor Visitor visiting the nodes and controlling the traversal. + */ + TBool TraverseNodeL( MXCFWNode& aNode, MMenuEngVisitor& aVisitor ) const; + + /** + * Tree is up; create and initialize ID manager and tree ID-s. + * @param aRootNode Root node. + */ + void InitIdManagerL( MXCFWNode& aRootNode ); + + /** + * Read id_seed from the tree. + * @param aIdSeed ID seed. + */ + void GetIdSeedL( TInt& aIdSeed ); + + /** + * Write the id_seed to the tree. + * @param aSeed ID seed. + */ + void SetIdSeedL( TInt aSeed ); + +private: // state machine parts + + /** + * Self-completion: go to RunL() asynchronously. + * @param aError Error code. + */ + void SelfComplete( TInt aError ); + + /** + * Initiate loading RAM file. + */ + void LoadRamFileL(); + + /** + * Initiate loading ROM file. + */ + void LoadRomFileL(); + + /** + * Initiate saving to TEMP file. + */ + void SaveTempFileL(); + + /** + * Replace RAM file with TEMP file. + */ + void ReplaceRamFileL(); + + /** + * Complete current operation, if any. + * @param aError Completion code. + */ + void CompleteCurrentOperation( TInt aError ); + + /** + * Start executing next operation, if any. + */ + void ExecuteOperationL(); + + /** + * Save changes, if any. + */ + void SaveChangesL(); + +private: // data + + RBuf iName; ///< Own. + RBuf iTempFileName; ///< Own. + RBuf iRamFileName; ///< Own. + TBool iChanged; ///< ETrue if there are unsaved changes. + MMenuEngObserver& iObserver; + TState iState; ///< State. + CXCFWTree* iTree; ///< DOM tree. Own. + CXCFWEngine* iEngine; ///< XML Engline. Own. + CMenuEngObjectFactoryProxy* iObjectFactory; ///< Object factory. Own. + TInt iRoot; ///< Cached root folder id. + RPointerArray iOperations; ///< Pending operations. + MMenuEngOperation* iCurrentOperation; ///< Operation being served. + RArray iNotifyQueue; ///< Events for notifiers. + RFs iFs; ///< File Server Session. Own. + CMenuEngIdManager* iIdManager; ///< ID manager. Owned. + CActiveSchedulerWait* iActiveWait; + /* + * Legacy format + */ + TBool iLegacyFormat; + /** + * True if the last saving was unsuccessful + */ + TBool iDiskWasFullAndRamFileWasNotCreated; + }; + +// ----------------------------------------------------------------------------- +// CMenuEng::State +// ----------------------------------------------------------------------------- +// +CMenuEng::TState CMenuEng::State() const + { + return iState; + } + +#endif // __MENUENG_H__