1 /*

     2 * Copyright (c) 2009 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:

    15 *

    16 */

    17 

    18 #ifndef __MENUENG_H__

    19 #define __MENUENG_H__

    20 

    21 #include <e32base.h>

    22 #include <xcfwengine.h>

    23 #include <xcfwtree.h> // for RNodeArray

    24 #include "mcsmenunotifier.h" // for notification events

    25 

    26 // FORWARD DECLARATION

    27 

    28 class TMenuItem;

    29 class CXCFWTree;

    30 class MXCFWNode;

    31 class CMenuEngObjectFactoryProxy;

    32 class CMenuEngObject;

    33 class CMenuEngIdManager;

    34 class MMenuEngObserver;

    35 class MMenuEngOperation;

    36 class MMenuEngFilter;

    37 class MMenuEngVisitor;

    38 

    39 /**

    40 * Event notification data.

    41 */

    42 class TMenuEngNotify

    43     {

    44 

    45 public:     // construction

    46 

    47     /**

    48     * Constructor.

    49     * @param aFolder Folder.

    50     * @param aEvents Events.

    51     */

    52     TMenuEngNotify( TInt aFolder, TInt aEvents )

    53         : iFolder( aFolder ), iEvents( aEvents ) {}

    54 

    55 public:     // data

    56 

    57     TInt iFolder; ///< Folder.

    58     TInt iEvents; ///< Events.

    59 

    60     };

    61 

    62 /**

    63 * Menu Engine.

    64 */

    65 NONSHARABLE_CLASS( CMenuEng ): public CActive, public MXCFWEngineObserver

    66     {

    67 

    68 public:     // construction

    69 

    70     /**

    71     * Destructor.

    72     */

    73     IMPORT_C virtual ~CMenuEng();

    74 

    75     /**

    76     * Two-phased constructor.

    77     * @param aName Name.

    78     * @param aObserver Observer.

    79     * @return The created object.

    80     */

    81     IMPORT_C static CMenuEng* NewL(

    82         const TDesC& aName,

    83         MMenuEngObserver& aObserver );

    84 

    85 protected:  // construction

    86 

    87     /**

    88     * Constructor.

    89     * @param aObserver Observer.

    90     */

    91     CMenuEng( MMenuEngObserver& aObserver );

    92 

    93     /**

    94     * Second phase constructor.

    95     * @param aName Name.

    96     */

    97     void ConstructL( const TDesC& aName );

    98 

    99 public:     // new methods

   100 

   101     enum TState /// State machine states.

   102         {

   103         ENull = 0, ///< Initial state.

   104         ELoadRamFile, ///< Loading RAM file.

   105         ELoadRomFile, ///< Loading ROM file.

   106         ESaveFile, ///< Saving TEMP file and replacing RAM file.

   107         EExecuteOp, ///< Operation scheduled for execution or being executed.

   108         EReady, ///< Idle.

   109         EDead ///< Unrecoverable error; final state.

   110         };

   111 

   112     /**

   113     * Queue an operation for execution.

   114     * Queued operations are scheduled for execution by the Engine.

   115     * @param aOperation Operation.

   116     */

   117     IMPORT_C void QueueOperationL( MMenuEngOperation& aOperation );

   118 

   119     /**

   120     * Dequeue an operation (remove from the operation queue). Safe to call

   121     * if not queued.

   122     * @param aOperation Operation.

   123     */

   124     IMPORT_C void DequeueOperation( MMenuEngOperation& aOperation );

   125 

   126     /**

   127     * Traverse a subtree of the item tree.

   128     * @param aFolder traversal starts at this folder.

   129     * @param aVisitor Visitor visiting the nodes and controlling the traversal.

   130     */

   131     IMPORT_C void TraverseFolderL(

   132         TInt aFolder,

   133         MMenuEngVisitor& aVisitor ) const;

   134 

   135     /**

   136     * Create a new object. Owner is the caller. The object is not added to

   137     * the engine yet, but it has an ID already. It can be used to AddL() item.

   138     * @param aType Type.

   139     * @return Created object. Owner is the caller.

   140     */

   141     IMPORT_C CMenuEngObject* NewObjectL( const TDesC& aType );

   142 

   143     /**

   144     * Returns current engine state.

   145     * @return Current state.

   146     */

   147 	inline TState State() const;

   148 	

   149 	/*

   150 	* Gets legacy format

   151 	* @return legacy format

   152 	*/

   153 	IMPORT_C TBool GetOnceLegacyFormat();

   154 

   155 public:     // data query (read access)

   156 

   157     // Read-access methods can be called any time.

   158     // There is a short startup period during which the engine data is not

   159     // ready yet; calls made in that period leave with KErrNotReady.

   160     // When the engine becomes ready, an (0 ,EItemsAddedRemoved) event is

   161     // sent to the observer.

   162 

   163     /**

   164     * Get ID of root folder.

   165     * @param aId ID of root folder.

   166     */

   167     IMPORT_C void RootFolderL( TInt& aId ) const;

   168 

   169     /**

   170     * Get parent folder of item.

   171     * @param aId Item ID.

   172     * @param aParentId ID of parent folder.

   173     */

   174     IMPORT_C void ParentFolderL( TInt aId, TInt& aParentId ) const;

   175 

   176     /**

   177     * Get item header.

   178     * @param aId Item ID.

   179     * @param aItem Item header is returned here.

   180     */

   181     IMPORT_C void GetItemL( TInt aId, TMenuItem& aItem ) const;

   182 

   183     /**

   184     * Get list of items.

   185     * @param aItemArray Array receiving item list. Existing content not touched

   186     * (new items are appended).

   187     * @param aFolder Get items from this folder.

   188     * @param aFilter Filter criteria or NULL for unfiltered results.

   189     * @param aRecursive ETrue to recurse folders, EFalse for immediate

   190     * children only.

   191     */

   192     IMPORT_C void GetItemsL(

   193         RArray<TMenuItem>& aItemArray,

   194         TInt aFolder,

   195         const MMenuEngFilter* aFilter,

   196         TBool aRecursive ) const;

   197 

   198     /**

   199     * Get object.

   200     * @param aId Item ID.

   201     * @return Object.

   202     */

   203     IMPORT_C const CMenuEngObject& ObjectL( TInt aId ) const;

   204 

   205 public:     // data manipulation (write access).

   206 

   207     // All write-access methods methods must be wrapped in MMenuEngOperation

   208     // objects (scheduled execution), otherwise they leave with KErrLocked.

   209 

   210     /**

   211     * Remove item.

   212     * @param aId ID of item to be removed.

   213     */

   214     IMPORT_C void RemoveL( TInt aId );

   215 

   216     /**

   217     * Move items to another folder.

   218     * @param aItems ID-s of items to be to be moved. All items must be in

   219     * the same folder.

   220     * @param aFolder Target folder.

   221     * @param aMoveBefore. In the target folder, items will be inserted before

   222     * this item (if found). If the target folder contains no item with that ID,

   223     * the moved items are appended to the end of existing items. Pass 0 to

   224     * append to the end.

   225     */

   226     IMPORT_C void MoveToFolderL(

   227         RArray<TInt>& aItems,

   228         TInt aFolder,

   229         TInt aMoveBefore );

   230 

   231     /**

   232     * Move item to a different position in its current folder.

   233     * @param aId ID of item to be to be reordered.

   234     * @param aMoveBefore. Move the item before this item (if found).

   235     * If aMoveBefore is not found, the item is moved to the end.

   236     */

   237     IMPORT_C void ReorderL( TInt aId, TInt aMoveBefore );

   238 

   239     /**

   240     * Add new object.

   241     * @param aObject Object to be added. Note, the object must have been

   242     * created with NewObjectL of THIS engine (or the call fails)!

   243     * Ownership taken.

   244     * @param aFolder Parent folder.

   245     * @param aMoveBefore. Move the item before this item (if found).

   246     * If aMoveBefore is not found, the item is added to the end.

   247     */

   248     IMPORT_C void AddL(

   249         CMenuEngObject& aObject,

   250         TInt aFolder,

   251         TInt aInsertBefore );

   252 

   253     /**

   254     * Get modifiable object. Note: when this method is called, the engine

   255     * marks the object as changed (without checking if there was really

   256     * a change or not). Therefore, it is advisable to use ObjectL() to

   257     * investigate an object, and only call ModifiableObjectL if changes are

   258     * really needed. This results in better performace, as it avoids

   259     * unnecessary saving.

   260     * @param aId Item ID.

   261     * @param aEvent event for engine to append.

   262     * @return Modifiable object. Already marked as changed.

   263     */

   264     IMPORT_C CMenuEngObject& ModifiableObjectL( TInt aId,

   265     		TInt aEvent = RMenuNotifier::EItemAttributeChanged );

   266 

   267     

   268     /**

   269     * Append new notification to the list of pending notifications.

   270     * @param aFolder Folder.

   271     * @param aEvents Events.

   272     */

   273     IMPORT_C void AppendNotifyL( TInt aFolder, TInt aEvents );

   274     

   275     

   276     IMPORT_C TBool Exist( TInt aId ) const;

   277 

   278 private:    // from CActive

   279 

   280     /**

   281     * Outstanding request completed.

   282     */

   283     void RunL();

   284 

   285     /**

   286     * Cancel outstanding request.

   287     */

   288     void DoCancel();

   289 

   290     /**

   291     * Handle error.

   292     * @param aError Error code.

   293     * @return KErrNone.

   294     */

   295     TInt RunError( TInt aError );

   296 

   297 private:    // from MXCFWEngineObserver

   298 

   299     /**

   300     * Called when Engine parsing / saving state changes.

   301     * @param aEvent Engine event

   302     */

   303     void HandleEngineEventL( TXCFWEngineEvent aEvent );

   304 

   305     /**

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

   307     * @param aErrorCode Error code

   308     */

   309     void HandleEngineErrorL( TInt aErrorCode );        

   310 

   311 private:    // types

   312 

   313     enum TFile /// File selector.

   314         {

   315         ERomFile, ///< Factory file in ROM.

   316         ERamFile, ///< Working file in RAM.

   317         ETempFile, ///< Temp file for saving (RAM).

   318         };

   319 

   320 private:    // new methods

   321 

   322     /**

   323     * Get object from node.

   324     * @param aNode Node.

   325     * @return Object.

   326     */

   327     inline CMenuEngObject& Object( MXCFWNode& aNode ) const;

   328 

   329     /**

   330     * Tree is up, perform structure check.

   331     * @param aTree Tree.

   332     * @return The root folder node.

   333     */

   334     MXCFWNode& CheckTreeL( MXCFWTree& aTree ) const;

   335 

   336     /**

   337     * Sanity ID check for all nodes in the tree.

   338     * @param aTree Tree.

   339     * @return ETrue if ID-s are OK.

   340     */

   341     TBool DebugSanityCheck( MXCFWTree& aTree ) const;

   342 

   343     /**

   344     * Wait for data xml file to load.

   345     */

   346     void ActiveWaitForFileLoadL();

   347 

   348     /**

   349     * Sanity ID check for one nodes in the tree.

   350     * @param aNode Node.

   351     * @return ETrue if ID is OK.

   352     */

   353     TBool DebugSanityCheck( MXCFWNode& aNode ) const;

   354 

   355     /**

   356     * Find node by ID, leave with KErrNotFound if not found.

   357     * @param aId ID.

   358     * @return Node.

   359     */

   360     MXCFWNode& NodeL( TInt aId ) const;

   361 

   362     /**

   363     * Find folder node by ID, leave with KErrNotFound if not found or not

   364     * folder.

   365     * @param aId ID.

   366     * @return Folder node.

   367     */

   368     MXCFWNode& FolderNodeL( TInt aId ) const;

   369 

   370     /**

   371     * Find child of aParent with given id, or NULL. Not recursive.

   372     * @param aParent Folder.

   373     * @param aId Child ID.

   374     * @return Child or NULL.

   375     */

   376     MXCFWNode* Child( MXCFWNode& aParent, TInt aId );

   377 

   378     /**

   379     * Cancel all operations in the queue.

   380     */

   381     void CancelAllOperations();

   382 

   383     /**

   384     * Validate content filename. Leave with KErrArgument if not valid.

   385     * @param aName Content filename (without extension).

   386     */

   387     void ValidateNameL( const TDesC& aName );

   388 

   389     /**

   390     * Generate filename of content file.

   391     * @param aFname Generated filename is returned here.

   392     * @param aSelector Filename selector.

   393     */

   394     void GetFileNameL( TFileName& aFname, TFile aSelector );

   395 

   396     /**

   397     * Traverse a node.

   398     * @param aNode Node.

   399     * @param aVisitor Visitor visiting the nodes and controlling the traversal.

   400     */

   401     TBool TraverseNodeL( MXCFWNode& aNode, MMenuEngVisitor& aVisitor ) const;

   402 

   403     /**

   404     * Tree is up; create and initialize ID manager and tree ID-s.

   405     * @param aRootNode Root node.

   406     */

   407     void InitIdManagerL( MXCFWNode& aRootNode );

   408 

   409     /**

   410     * Read id_seed from the tree.

   411     * @param aIdSeed ID seed.

   412     */

   413     void GetIdSeedL( TInt& aIdSeed );

   414 

   415     /**

   416     * Write the id_seed to the tree.

   417     * @param aSeed ID seed.

   418     */

   419     void SetIdSeedL( TInt aSeed );

   420 

   421 private:    // state machine parts

   422 

   423     /**

   424     * Self-completion: go to RunL() asynchronously.

   425     * @param aError Error code.

   426     */

   427     void SelfComplete( TInt aError );

   428 

   429     /**

   430     * Initiate loading RAM file.

   431     */

   432     void LoadRamFileL();

   433 

   434     /**

   435     * Initiate loading ROM file.

   436     */

   437     void LoadRomFileL();

   438 

   439     /**

   440     * Initiate saving to TEMP file.

   441     */

   442     void SaveTempFileL();

   443 

   444     /**

   445     * Replace RAM file with TEMP file.

   446     */

   447     void ReplaceRamFileL();

   448 

   449     /**

   450     * Complete current operation, if any.

   451     * @param aError Completion code.

   452     */

   453     void CompleteCurrentOperation( TInt aError );

   454 

   455     /**

   456     * Start executing next operation, if any.

   457     */

   458     void ExecuteOperationL();

   459 

   460     /**

   461     * Save changes, if any.

   462     */

   463     void SaveChangesL();

   464 

   465 private:    // data

   466 

   467     RBuf iName; ///< Own.

   468     RBuf iTempFileName; ///< Own.

   469     RBuf iRamFileName; ///< Own.

   470     TBool iChanged; ///< ETrue if there are unsaved changes.

   471     MMenuEngObserver& iObserver;

   472     TState iState; ///< State.

   473     CXCFWTree* iTree; ///< DOM tree. Own.

   474     CXCFWEngine* iEngine; ///< XML Engline. Own.

   475     CMenuEngObjectFactoryProxy* iObjectFactory; ///< Object factory. Own.

   476     TInt iRoot; ///< Cached root folder id.

   477     RPointerArray<MMenuEngOperation> iOperations; ///< Pending operations.

   478     MMenuEngOperation* iCurrentOperation; ///< Operation being served.

   479     RArray<TMenuEngNotify> iNotifyQueue; ///< Events for notifiers.

   480     RFs iFs; ///< File Server Session. Own.

   481     CMenuEngIdManager* iIdManager; ///< ID manager. Owned.

   482     CActiveSchedulerWait* iActiveWait;

   483     /*

   484     * Legacy format

   485     */

   486     TBool iLegacyFormat;

   487     /**

   488      * True if the last saving was unsuccessful

   489      */

   490     TBool iDiskWasFullAndRamFileWasNotCreated;

   491     };

   492 

   493 // -----------------------------------------------------------------------------

   494 // CMenuEng::State

   495 // -----------------------------------------------------------------------------

   496 // 

   497 CMenuEng::TState CMenuEng::State() const

   498     {

   499     return iState;

   500     }

   501 

   502 #endif // __MENUENG_H__