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