/*
* 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 CNcdNodeFolder class
*
*/


#ifndef NCD_NODE_FOLDER_H
#define NCD_NODE_FOLDER_H


#include <e32cmn.h>

#include "ncdnodeimpl.h"

class CNcdNodeIdentifier;
class CNcdChildEntity;
class CNcdNodeFolderLink;
class CNcdNodeSeenFolder;


/**
 *  ?one_line_short_description
 *
 *  ?more_complete_description
 *
 *  @lib ?library
 *  @since S60 ?S60_version *** for example, S60 v3.0
 */
class CNcdNodeFolder : public CNcdNode
    {
    
public:

    /**
     * NewL
     *
     * @return CNcdNodeFolder* Pointer to the created object 
     * of this class.
     */
    static CNcdNodeFolder* NewL( CNcdNodeManager& aNodeManager,
                                 const CNcdNodeIdentifier& aIdentifier );
    
    /**
     * NewLC
     *
     * @return CNcdNodeFolder* Pointer to the created object 
     * of this class.
     */
    static CNcdNodeFolder* NewLC( CNcdNodeManager& aNodeManager,
                                  const CNcdNodeIdentifier& aIdentifier );


    /**
     * Destructor
     */
    virtual ~CNcdNodeFolder();


    /** 
     * Getter for child count.
     * 
     * @note This is the count of children in the child array, not the expected
     * child count that comes from server!
     */
    virtual TInt ChildCount() const;

    /**
     * Returns the child node by the given index.
     *
     * @note Returns the available children, can be indexed against ChildCount
     */
    virtual const CNcdNodeIdentifier& ChildL( TInt aIndex ) const;
    
    /**
     * Returns the whole child array.
     */
    const RPointerArray<CNcdChildEntity>& ChildArray() const;
    
    /** 
     * Getter for server child count.
     * 
     * Uses CNcdNodeFolderLink::ExpectedChildrenCount
     *
     * @exception KErrNotFound if link not set.
     */
    virtual TInt ServerChildCountL() const;
    
    /** 
     * Getter for child identifier by server child index.
     *
     * Indexed against ServerChildCountL. Some children may be unavailable
     * because of paging, so this function should be used with care.
     *
     * @param aIndex The index of the child (i.e. index on server).
     * @return Child identifier for the given index.
     * @exception KErrNotFound if the child entity is not found.
     */
    virtual const CNcdNodeIdentifier& ChildByServerIndexL( TInt aIndex ) const;
    
    /** 
     * Getter for child entity by server child index.
     *
     * Indexed against ServerChildCountL. Some children may be unavailable
     * because of paging, so this function should be used with care.
     *
     * @param aIndex The index of the child (i.e. index on server).
     * @return Child entity for the given index.
     * @exception KErrNotFound if the child entity is not found.
     */
    virtual const CNcdChildEntity& ChildEntityByServerIndexL( TInt aIndex ) const;
    
    
    
    /**
     * Adds a child to this folder if not present already.
     *
     * @param aNodeIdentifier Identifier of the node.
     * @param aIndex Index of the child node (i.e. index of the actual node on server)
     * @param aTransparent Defines whether this child is transparent.
     * @param aNodeType Type of the child node (folder, item etc.).
     * @return ETrue if the child was added. Else EFalse (children
     * are inserted only once).
     */
    virtual TBool ReplaceChildL( 
        const CNcdNodeIdentifier& aNodeIdentifier,
        TInt aIndex,
        TBool aTransparent,
        CNcdNodeFactory::TNcdNodeType aNodeType );
    
    virtual TBool InsertChildL( 
        const CNcdNodeIdentifier& aNodeIdentifier,
        TInt aIndex,
        TBool aTransparent,
        CNcdNodeFactory::TNcdNodeType aNodeType );
        
    virtual TBool AppendChildL( 
        const CNcdNodeIdentifier& aNodeIdentifier,
        TBool aTransparent,
        CNcdNodeFactory::TNcdNodeType aNodeType );
        
    CNcdNodeFolderLink& FolderLinkL() const;

    CNcdNodeSeenFolder& NodeSeenFolder() const;

    void RemoveChild( const CNcdNodeIdentifier& aNodeIdentifier );
    
    /**
     * Removes children from the child list and database
     */
    void RemoveChildrenL();
    
    /**
     * Removes children only from the child list
     */
    void RemoveChildren();
    
    /**
     * Stores current children to previous child list and sets the
     * previous child count.
     */
    void StoreChildrenToPreviousListL();
    
    /**
     * Stores the given child list as previous child list and sets the
     * previous child count.
     *
     * @param aPreviousChildren The previous children.
     * @param aPreviousChildCount.
     */
    void StoreChildrenToPreviousListL(
        const RPointerArray<CNcdChildEntity>& aPreviousChildren,
        TInt aPreviousChildCount );
    
    /**
     * Checks that have this folder's children been loaded previously.
     * This is needed to differentiate first time loading of the folder from
     * consequent loads.
     *
     * @note Does not indicate that the children are in cache or
     * anything else other than what is described above.
     *
     * @return ETrue if children have been loaded previously, EFalse otherwise.
     */
    TBool ChildrenPreviouslyLoaded();
    
    /**
     * Setter for the children previously loaded flag.
     *
     * @param aChildrenPreviouslyLoaded Default value is ETrue.
     * @note This flag should be unset only in special occaisions
     * such as unsetting for root node on cache clear.
     */
    void SetChildrenPreviouslyLoaded( TBool aChildrenPreviouslyLoaded = ETrue );
    
    /**
     * Getter for previous child count.
     *
     * @note Not persistently stored to db.
     * @return The previous child count or KErrNotFound if not set.
     */
    TInt PreviousChildCount();
    
    /**
     * Getter for previous child array.
     *
     * @note The array is not persistently stored to db.
     * @return An array containing previous children.
     */
    const RPointerArray<CNcdChildEntity>& PreviousChildArray();
    
    
    /**
     * Sets folder's children as expired and removes them from the child array
     * and deletes their metadatas from disk cache
     */
    void ExpireAndRemoveChildrenL();
    

public: // CNcdNode

    /**
     * @see CNcdNode::ReceiveMessage
     */
    virtual void ReceiveMessage( MCatalogsBaseMessage* aMessage,
                                 TInt aFunctionNumber );


    /**
     * @see CNcdNode::ExternalizeL
     */
    virtual void ExternalizeL( RWriteStream& aStream );


    /**
     * @see CNcdNode::InternalizeL
     */
    virtual void InternalizeL( RReadStream& aStream );



protected:

    /**
     * @see CNcdNode::CNcdNode
     */
    CNcdNodeFolder( CNcdNodeManager& aNodeManager,
        NcdNodeClassIds::TNcdNodeClassId aNodeClassId = NcdNodeClassIds::ENcdFolderNodeClassId, 
        NcdNodeClassIds::TNcdNodeClassId aAcceptedLinkClassId = NcdNodeClassIds::ENcdFolderNodeLinkClassId,
        NcdNodeClassIds::TNcdNodeClassId aAcceptedMetaDataClassId = NcdNodeClassIds::ENcdFolderNodeMetaDataClassId );
    
    /**
     * @see CNcdNode::ConstructL
     */
    virtual void ConstructL( const CNcdNodeIdentifier& aIdentifier );


    /**
     * @see CNcdNode::CreateLinkL
     */
    virtual CNcdNodeLink* CreateLinkL();


    /** 
     * @see CNcdNode::ExternalizeDataForRequestL
     */
    virtual void ExternalizeDataForRequestL( RWriteStream& aStream ) const;    


    /**
     * @param aStream that will contain the child array data.
     */
    void ExternalizeChildArrayL( RWriteStream& aStream ) const;

    /**
     * This function is required because the proxy may require different
     * child identifiers into its array. The child classes of this class
     * may provide its own implementation to create child arrays for proxy.
     * This implementation uses ExternalizeChildArrayL.
     *
     * @param aStream that will contain the child array data.
     */
    virtual void ExternalizeChildArrayForRequestL( RWriteStream& aStream ) const;
    
    void NodeSeenFolderHandleRequestL( MCatalogsBaseMessage& aMessage ) const;  
    
    
private:
    
    // Prevent these two if they are not implemented
    CNcdNodeFolder( const CNcdNodeFolder& aObject );
    CNcdNodeFolder& operator =( const CNcdNodeFolder& aObject );


private: // data

    // This array contains the identifying info of child nodes.
    // The information can be used to get the actual node from
    // the node manager. The identityinfo is used here instead of
    // actual references to the nodes because the manager will
    // handle the destruction of the nodes. Now, there is not
    // danger for NULL pointer errors.
    RPointerArray<CNcdChildEntity> iChildren;
    
    // Determines whether the previous child list has been populated.
    // NOTE: This is not stored to db currently.
    //TBool iPreviousChildrenStored;
    
    // Previous child list is stored here when refreshing folder.
    // Nodes not found from this list are considered new.
    // NOTE: This array is not stored to db currently.
    RPointerArray<CNcdChildEntity> iPreviousChildren;
    
    // Previous child count (i.e. the server child count)
    // KErrNotFound if not set;
    // NOTE: This is not stored to db currently. 
    TInt iPreviousChildCount;
    
    // Defines whether children of this folder have been loaded previously.
    // This is needed to differentiate first time loading of the folder from
    // consequent loads. This flag is persistently stored to db.
    // NOTE: This flag does not indicate that the children are in cache or
    // anything else other than what is described above.
    TBool iChildrenPreviouslyLoaded;
    
    // Implements the seen interface of folders.
    CNcdNodeSeenFolder* iNodeSeenFolder;
    
    };


#endif // NCD_NODE_FOLDER_H