/*

* Copyright (c) 2006 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:   Contains CNcdNodeManager class

*

*/

#ifndef NCD_NODE_MANAGER_H

#define NCD_NODE_MANAGER_H

#include <e32base.h>

#include <e32cmn.h>

#include <f32file.h>

#include "catalogscommunicable.h"

#include "ncdnodefactory.h"

#include "ncdparserobserver.h"

#include "ncdnodeclassids.h"

#include "ncdprotocoltypes.h"

#include "ncd_pp_entityref.h"

#include "ncddatabaseitems.h"

class CNcdNode;

class CNcdNodeItem;

class CNcdNodeFolder;

class CNcdRootNode;

class CNcdBundleFolder;

class CNcdNodeTransparentFolder;

class CNcdSearchNodeFolder;

class CNcdNodeMetaData;

class CNcdNodeIdentifier;

class CNcdStorageManager;

class CNcdNodeDbManager;

class CNcdPurchaseHistoryDb;

class MCatalogsBaseMessage;

class MNcdPreminetProtocolEntityRef;

class MNcdPreminetProtocolDataEntity;

class MNcdPreminetProtocolDownload;

class MNcdStorageDataItem;

class CNcdSearchNodeFolder;

class MCatalogsContext;

class CNcdNodeCacheCleanerManager;

class CNcdPreviewManager;

class MNcdConfigurationManager;

class CNcdExpiredNode;

class MNcdPreminetProtocolExpiredCachedData;

class CNcdSearchNodeBundle;

class CNcdSearchNodeItem;

class CNcdFavoriteManager;

class CNcdNodeSeenInfo;

class CNcdSearchableNode;

class CNcdGeneralManager;

/**

 *  CNodeManager provides functions to handle creation and deletion

 *  of node related objects.

 */

class CNcdNodeManager : public CCatalogsCommunicable                  

    {

public:

    /**

     * Defines how ref data is handled.

     */

    enum TNcdRefHandleMode

        {

        EUpdate,    // Updates a previously existing node

        EInsert,    // Inserts node to a specific index, increases node count

        EReplace,   // Replaces the node at a specific index

        EAppend     // Appends the node

        };

    /**

     * Different types of temporary nodes.

     */        

    enum TNcdTemporaryNodeType

        {

        ENcdTemporaryNodeItem,

        ENcdTemporaryNodeFolder,

        ENcdTemporaryBundleFolder

        };

    /**

     * NewL

     *

     * @param aStorageManager Storage manager provides means for

     * the manager to save, load, and remove data in db.

     * @param aPurchaseHistory Purchase history contains information

     * about node purchase phases.

     * @param aConfigurationManager Gives access to server capabilities etc.

     * @return CNcdNodeManager* Pointer to the created object 

     * of this class.

     */

    static CNcdNodeManager* NewL(

        CNcdGeneralManager& aGeneralManager );

    /**

     * Destructor

     *

     * Deletes the object from caches and releases objects that are

     * owned by this class object.

     */

    virtual ~CNcdNodeManager();

public: // General getter and setter functions

    /**

     * @return CNcdPurchaseHistoryDb& The purchase history class object.

     */    

    CNcdPurchaseHistoryDb& PurchaseHistory() const;

    CNcdPreviewManager& PreviewManager() const;

    MNcdConfigurationManager& ConfigurationManager() const;

    /**

     * @return CNcdNodeCacheCleanerManager& Cleaner Manager may be used 

     * to get db cache cleaners that can be used to clean data

     * from db.

     */

    CNcdNodeCacheCleanerManager& NodeCacheCleanerManager() const;

    /**

     * @return CNcdNodeDbManager& Reference to the db manager

     * that can be used to save, load, and remove data in db.

     */

    CNcdNodeDbManager& NodeDbManager() const;

    /**

     * @return CNcdNodeSeenInfo& Reference to the seen info

     * which is used to keep track of seen nodes.

     */

    CNcdNodeSeenInfo& SeenInfo() const;

    /**

     * Sets the favorite manager.

     */

    void SetFavoriteManager( CNcdFavoriteManager& aManager );

public: // Functions to get node objects from caches or from db. 

        // And, functions to create node objects.

    /**

     * Checks if the node is found from the cache or from the database.

     * If the node is found from the database then the metadata is also 

     * searched for the node and if it is found then it is inserted 

     * for the node.

     *

     * @note This uses the actual node identifier which may differ from

     * the metadata identifier. Be sure that the identifier is correct

     * when using this function.

     *

     * @param aIdentifier Identifies the node that is searched for.

     * @return CNcdNode& Reference to the node that was found.

     * @excpetion KErrNotFound if the node was not found from the

     * cache or from the database.

     */

    CNcdNode& NodeL( const CNcdNodeIdentifier& aIdentifier );

    /**

     * Instead of taking the actual nodeidentifier, uses the parent identifier

     * and the metadata identifier to create the correct identifier and after that

     * calls the NodeL above.

     *

     * @see CNcdNodeManager::NodeL

     *

     * @param aParentIdentifier Identifier of parent node of the node that is searched.

     * @param aNodeMetaDataIdentifier Metadata identifier of the node that is

     * searched for.

     */

    CNcdNode& NodeL( const CNcdNodeIdentifier& aParentIdentifier,

                     const CNcdNodeIdentifier& aNodeMetaDataIdentifier );

    /**

     * Checks if the node is found from the cache or from the database.

     * If the node is found from the database then the metadata is also 

     * searched for the node and if it is found then it is inserted 

     * for the node.

     *

     * @note Ownership of the node is not transferred.

     *

     * @note This uses the actual node identifier which may differ from

     * the metadata identifier. Be sure that the identifier is correct

     * when using this function.

     *

     * @param aIdentifier

     * @return CNcdNode* Node if it is found. Else NULL.

     */

    CNcdNode* NodePtrL( const CNcdNodeIdentifier& aIdentifier );

    /**

     * Instead of taking the actual nodeidentifier, uses the parent identifier

     * and the metadata identifier to create the correct identifier and after that

     * calls the NodeL above.

     *

     * @see CNcdNodeManager::NodePtrL

     *

     * @param aParentIdentifier Identifier of parent node of the node that is searched.

     * @param aNodeMetaDataIdentifier Metadata identifier of the node that is

     * searched for.

     */

    CNcdNode* NodePtrL( const CNcdNodeIdentifier& aParentIdentifier,

                        const CNcdNodeIdentifier& aNodeMetaDataIdentifier );

    /**

     * Uses NodeL to get the folder from the cache or from the db. 

     * If the node is of the folder type, then the folder object is 

     * returned.

     *

     * @see CNcdNodeManager::NodeL

     */    

    CNcdNodeFolder& FolderL(

        const CNcdNodeIdentifier& aIdentifier );

    /**

     * Uses NodeL to get the folder from the cache or from the db. 

     *

     * @see CNcdNodeManager::NodeL

     */    

    CNcdRootNode& RootNodeL( const TUid& aClientUid );

    /**

     * Uses NodeL to get the folder from the cache or from the db. 

     *

     * @see CNcdNodeManager::NodeL

     */    

    CNcdSearchNodeFolder& SearchFolderL( const CNcdNodeIdentifier& aParentIdentifier,

                                         const CNcdNodeIdentifier& aNodeMetaDataIdentifier );

    /**

     * Uses NodeL to get the folder from the cache or from the db.

     *

     * @see CNcdNodeManager::NodeL

     */    

    CNcdSearchNodeFolder& SearchFolderL( const CNcdNodeIdentifier& aNodeIdentifier );

    /**

     * Uses NodeL to get the folder from the cache or from the db.

     *

     * @see CNcdNodeManager::NodeL

     */    

    CNcdSearchNodeItem& SearchNodeItemL( const CNcdNodeIdentifier& aNodeIdentifier );

    /**

     * Creates a node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @note Be carefull when using this function. Make sure that the node identifier

     * actually contains all the parts. Should you use CreateNodeL with parent and

     * metadata identifiers instead?

     *

     * @param aNodeType informs if the node should be item or folder

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aNodeIdentfier The identifier that identifies the parent of this node.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNode& CreateNodeL( CNcdNodeFactory::TNcdNodeType aNodeType,

                           CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                           const CNcdNodeIdentifier& aNodeIdentifier );

    /**

     * Creates a node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @param aNodeType informs if the node should be item or folder

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aParentNodeIdentfier The identifier that identifies the parent of this node.

     * @param aMetaDataIdentifier The identifier of metadata of this node.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNode& CreateNodeL( CNcdNodeFactory::TNcdNodeType aNodeType,

                           CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                           const CNcdNodeIdentifier& aParentNodeIdentifier,

                           const CNcdNodeIdentifier& aMetaDataIdentifier );

    /**

     * Creates an item node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @note Be carefull when using this function. Make sure that the node identifier

     * actually contains all the parts. Should you use CreateNodeItemL with parent and

     * metadata identifiers instead?

     *

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aNodeIdentfier The identifier that identifies the parent of this node.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNodeItem& CNcdNodeManager::CreateNodeItemL( CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                                                    const CNcdNodeIdentifier& aNodeIdentifier );

    /**

     * Creates an item node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aParentNodeIdentfier The identifier that identifies the parent of this node.

     * @param aMetaDataIdentifier The identifier of metadata of this node.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNodeItem& CNcdNodeManager::CreateNodeItemL( CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                                                    const CNcdNodeIdentifier& aParentNodeIdentifier,

                                                    const CNcdNodeIdentifier& aMetaDataIdentifier );

    /**

     * Creates a folder node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @note Be carefull when using this function. Make sure that the node identifier

     * actually contains all the parts. Should you use CreateNodeFolderL with parent and

     * metadata identifiers instead?

     *

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aNodeIdentfier The identifier that identifies the parent of this node.

     * @param aFolderType May be used to inform what kind of special folder is used. For example

     * if root folder should be created.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNodeFolder& CNcdNodeManager::CreateNodeFolderL( CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                                                        const CNcdNodeIdentifier& aNodeIdentifier,

                                                        CNcdNodeFactory::TNcdNodeType aFolderType

                                                            = CNcdNodeFactory::ENcdNodeFolder );    

    /**

     * Creates a folder node accroding to the given type information. 

     * Adds the created node into the cache. If node already exists

     * in the cache or in the database, then the old node is used.

     *

     * @param aNodePurpose gives the information if the normal or some specific kind

     * of node should be created.

     * @param aParentNodeIdentfier The identifier that identifies the parent of this node.

     * @param aMetaDataIdentifier The identifier of metadata of this node.

     * @param aFolderType May be used to inform what kind of special folder is used. For example

     * if root folder should be created.

     * @return CNcdNode& Reference to the node that was found.

     */

    CNcdNodeFolder& CNcdNodeManager::CreateNodeFolderL( CNcdNodeFactory::TNcdNodePurpose aNodePurpose,

                                                        const CNcdNodeIdentifier& aParentNodeIdentifier,

                                                        const CNcdNodeIdentifier& aMetaDataIdentifier,

                                                        CNcdNodeFactory::TNcdNodeType aFolderType

                                                            = CNcdNodeFactory::ENcdNodeFolder );    

    /**

     * Uses FolderL to search an existing folder. If the folder is not

     * found then new transparent folder will be created and retured.

     *

     * @see CNcdNodeManager::FolderL

     */        

    CNcdNodeTransparentFolder& CreateTransparentFolderL(

        const CNcdNodeIdentifier& aNodeIdentifier );

    /**

     * Getter for root.

     * Uses FolderL to get the root from the cache or from the db.

     */

    CNcdRootNode& CreateRootL( const TUid& aClientUid );

    /**

     * Getter for root.

     * Uses CreateRootL above to get the root from the cache or from the db.

     */

    CNcdRootNode& CreateRootL( const MCatalogsContext& aContext );

    /**

     * Getter for search root.

     * Uses FolderL to get the search root from the cache or from the db.

     */

    CNcdNodeFolder& CreateSearchRootL( const MCatalogsContext& aContext );

    /**

     * Getter for the bundle node.

     * The parent of the bunlde is always root.

     *

     * @note the use of the metadata identifier instead of the node identifier

     * @note Also, note that this function does not add the created folder to be the child

     * of the root. It has to be done separately.

     *

     * @param aMetaDataIdentifier The metadata identifier of the bundle node is used

     * when the bundle folder is created. So, note that you have to give meta data identifier

     * here instead of the node identifier.

     */    

    CNcdNodeFolder& CreateBundleFolderL( const CNcdNodeIdentifier& aMetaDataIdentifier );

    /**

     * This function can be used to create temporary nodes.

     * If corresponding temporary node already exists in RAM cache or 

     * in database, it will be returned. If not, then metadata is checked.

     * If the metadata for the node exists, a temporary node is created directly 

     * for the node, and the server uri for the node link is set from 

     * the metadata identifier. The type of the node is gotten from the metadata.

     * If the temporary node could not be created, then the supplier node that will

     * act as a wrapper is created.

     *

     * @note aMetaDataIdentifier has to contain server URI if the node should be able

     * to load its data from the web.

     * @note According to the way the node is created. The node identifier will be an

     * identifier of the temporary node or the identifier of the supplier node.

     * @note If the metadata is found, it is set to the node 

     *

     * @param aMetaDataIdentifier Identifies the metadata that the node should contain.

     * @return CNcdNode& Reference to the node that has been created.

     */

    CNcdNode& CreateTemporaryNodeOrSupplierL( const CNcdNodeIdentifier& aMetaDataIdentifier );

    /**

     * Creates temporary node if the given metadata exists already. The type

     * of the created node is concluded from the type of the metadata. The

     * created node has no parent. The metadata is set automatically for the

     * created node. NULL is returned if the node cannot be created.

     *

     * @param aMetaDataIdentifier Identifies the metadata that the node should contain.

     * @return The node or NULL, ownership is NOT transferred.

     */

    CNcdNode* CreateTemporaryNodeIfMetadataExistsL(

        const CNcdNodeIdentifier& aMetadataIdentifier );

    /**

     * Creates temporary node. The created node has no parent. The metadata is 

     * set automatically for the created node if it exists or can be created. 

     * NULL is returned if the node cannot be created.

     *

     * @param aTempNodeIdentifier Temp node identifier

     * @param aType Type of the temp node

     * @param aCreateMetaData If ETrue metadata is created if it doesn't exist

     * @return The node or NULL, ownership is NOT transferred.

     */

    CNcdNode& CreateTemporaryNodeL(

        CNcdNodeIdentifier& aTempNodeIdentifier,

        TNcdTemporaryNodeType aType,

        TBool aCreateMetaData );

    /**

     * Creates a search bundle folder.

     *

     * @note the use of the metadata identifier instead of the node identifier

     * @note Also, note that this function does not add the created node as a child

     * for the parent. It has to be done separately.

     *

     * @param aMetaDataIdentifier The metadata identifier of the node is used

     * when the folder is created. So, note that you have to give meta data identifier

     * here instead of the node identifier.

     * @param aParentIdentifier The full identifier of the parent, NOT a metadata identifier.

     */    

    CNcdSearchNodeBundle& CreateSearchBundleL( const CNcdNodeIdentifier& aMetaDataIdentifier,

        const CNcdNodeIdentifier& aParentIdentifier );

    /**

     * Creates a search folder.

     *

     * @note the use of the metadata identifier instead of the node identifier

     * @note Also, note that this function does not add the created node as a child

     * for the parent. It has to be done separately.

     *

     * @param aMetaDataIdentifier The metadata identifier of the node is used

     * when the folder is created. So, note that you have to give meta data identifier

     * here instead of the node identifier.

     * @param aParentIdentifier The full identifier of the parent, NOT a metadata identifier.

     */

    CNcdSearchNodeFolder& CreateSearchFolderL( const CNcdNodeIdentifier& aMetaDataIdentifier,

        const CNcdNodeIdentifier& aParentIdentifier );

    /**

     * Checks if the node metadata is found from the cache or from the database.

     *

     * @param aIdentifier Identifies the node metadata that is searched for.

     * @return CNcdNode& Reference to the node metadata that was found.

     * @exception KErrNotFound if the node metadata was not found from the

     * cache or from the database.

     */

    CNcdNodeMetaData& NodeMetaDataL( const CNcdNodeIdentifier& aIdentifier );

    /**

     * Creates an empty node metadata.

     *

     * @note That this function does not set the metadata to any node because

     * the metadata may not be initialized with proper values if it has only

     * been created after it was not found from db or from cache.

     * The caller of this function has to set the metadata to the node

     * itself when it is wanted.

     *

     * @param aMetaDataIdentifier Identifies the name of the metadata that is created.

     * @param aMetaType Gives the type of metadata that will be created.

     * @return CNcdNodeFolderMetaData& reference to the metadata that was created.

     * @exception KErrNotFound If the node was not found from the cache or from the

     *                         database.

     */

    CNcdNodeMetaData& CreateNodeMetaDataL(

        const CNcdNodeIdentifier& aMetaDataIdentifier,

        CNcdNodeFactory::TNcdNodeType aMetaType );

public: // Functions that are used to insert data information

        // gotten from the data parsers into the correct node

        // objects. These functions are provided for operations

        // to update the nodes. The updated information may also be

        // inserted from the purchase history.