// Copyright (c) 1998-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:
// This contains the definitions of CDataDelete, CDataNoDelete, CIntAttribute, CNode, and CTypedNode.
// CDataNoDelete is a base class to CDataDelete and are essentially a wrapper around an HBufC16.
// The node owns the data that is added to it and therefore is responsible for deleting all its data,
// hence theses two classes allow a user to have non deletable data. Internally to the node it is also 
// sometimes necessary to change the data into either deletable or non-deletable data api's are provided
// for this.
// CIntAttribute is wrapper around a TInt, this is provided as the nodes attribute value is a CBase* however
// it might be desirable to store integer's in here. Attribute value is owned by the node therefore the node is
// responsible for deleting it.
// CNode is the basis for constructing a tree. It consists of an array of child nodes, node type, a parent node,
// an array of attributes, and a data member. Internally the data member is defined as CDataNoDelete however
// to the user all the exported api's take an HBufC16*. Data is owned by the node and is destroyed by the node,
// However in certain circumstances this is not desirable hence the api's to make the data non-deletable. The
// node type is defined as a TAny* however normal usage would use the templated node - CTypedNode. The node type
// is used to identify groups of nodes. The attribute array is fairy simple and consists of AttributeType and 
// AttributeValue. AttributeType can be defined by using the templated class and should be a 32bit value. AttributeValue
// can be any object derived from CBase and the node takes ownership therefore the node delete's it.
// Basic usage should be to use the templated class in order to make use of the templated types (TNodeType,TAttributeType).
// Create a node for example:
// CTypedNode<CNode*, const TDesC*> *tree = CTypedNode<CNode*, const TDesC*>::NewL(0,0);
// add a new child:
// CNODE *TestChildNode1 = tree->AppendNodeL(aTempNodeForNodeType);
// add some data:
// TestChildNode1->SetDataL(aHBufC16);
// add an attribute:
// TestChildNode1->->AddAttributeL(aTAttributeType,aCBasePointerAttributeValue);
// Explanation of individual api's is documented below.
//

 

#ifndef __CNODE_H__
#define __CNODE_H__

#include <e32base.h>
#include <f32file.h>


/**
	@file
	@publishedAll
	@deprecated
*/

//Granularity of arrays
const TInt KGranularity = 5;

//enum of panic reasons
enum TNodePanic
	{
	ENodeBadArgument,
	ENodeNoChildren,
	ENoData,
	EAttributeFailure
	};

//node panic function
inline void Panic(TNodePanic aPanic);

//Wrapper around an HBufC16 doesn't delete data
//##ModelId=3B666BCC0303
class CDataNoDelete : public CBase
/** Provides a wrapper around an HBufC16: the buffer is not deleted when the object is deleted.
*/
	{
public:
	//##ModelId=3B666BCC032D
	CDataNoDelete(HBufC16* aData);
	//##ModelId=3B666BCC032C
	virtual ~CDataNoDelete();
	//##ModelId=3B666BCC0324
	HBufC16* SetData(HBufC16* aData);
	//##ModelId=3B666BCC0322
	virtual void ResetDataPointer(HBufC16* aData);
	//##ModelId=3B666BCC0321
	HBufC16* Data();

protected:
	/** The wrapped buffer. */
	//##ModelId=3B666BCC0319
	HBufC16* iData;
	};

//Wrapper around an HBufC16 does delete data
//##ModelId=3B666BCC0399
class CDataDelete : public CDataNoDelete
/** Provides a wrapper around an HBufC16: the buffer is deleted when the 
object is deleted.
*/
	{
public:
	//##ModelId=3B666BCC03B7
	CDataDelete(HBufC16* aData);
	//##ModelId=3B666BCC03B0
	virtual ~CDataDelete();
	//##ModelId=3B666BCC03AE
	virtual void ResetDataPointer(HBufC16* aData);
	};

//Wrapper around an HBufC16 does delete data (FileName)
// After Removing referenced File 
//##ModelId=3B666BC7026F
class CFileDataDelete : public CDataNoDelete
/** Provides a wrapper around a filename: the referenced file is deleted when the object is deleted.
*/
	{
public:
	//##ModelId=3B666BC7028F
	CFileDataDelete(HBufC16* aData);
	//##ModelId=3B666BC7028E
	virtual ~CFileDataDelete();
	//##ModelId=3B666BC70285
	virtual void ResetDataPointer(HBufC16* aData);
private:
	//##ModelId=3B666BC70284
	void RemoveFile();
	};

//Wrapper around a TInt used for attribute values in order to allow the node to call a dtor
//##ModelId=3B666BC6023E
class CIntAttribute : public CBase
/** Provides an object wrapper around a TInt value. */
	{
public:
	//##ModelId=3B666BC6025B
	inline CIntAttribute(TInt aInteger);		
	//##ModelId=3B666BC6025A
	inline TInt Int() const;
private:
	//##ModelId=3B666BC60264
	CIntAttribute();
	//##ModelId=3B666BC60253
	TInt iInteger;
	};

//
// Node class
// Normal usage would be to use CTypedNode in order to use specific templated types
//

//##ModelId=3B666BCD02D2
class CNode : public CBase 
	{
public:
	//##ModelId=3B666BCE0139
	IMPORT_C ~CNode();

	//NewL parameters aType to indentify the type of node, CNode* to set the parent of this node
	//##ModelId=3B666BCE0125
	IMPORT_C static CNode* NewL(TAny* aType,CNode* aParent);

	//Deletes a child node which is passed in as a parameter
	//##ModelId=3B666BCE011C
	IMPORT_C void DeleteChildNode(CNode* aNode);

	//Deletes all the child nodes haging of this node
	//##ModelId=3B666BCE011B
	IMPORT_C void DeleteAllChildNodes();

	//Creates a new node and adds it to the childlist, reference to new node is returned. Can leave if it can't allocate memory for a new node
	//Type of node is the parameter
	//##ModelId=3B666BCE0108
	IMPORT_C CNode& AppendNodeL(TAny* aType = 0);

	//Appends a node which is passed in as a parameter to this node, so its added to the childlist
	//##ModelId=3B666BCE00FD
	IMPORT_C void AppendNodeToThisNodeL(CNode* aNode);

	//Sets the data in the node to the parameter that is passed in. It's deletable and the node will delete it in dtor
	//Push aDataNowNodeOwns onto the CleanupStack before calling then pop off on return
	//##ModelId=3B666BCE00F3
	IMPORT_C void SetDataL(HBufC16* aDataNowNodeOwns);

	//returns the data stored in the node, which is returned as an HBufC16*
	//##ModelId=3B666BCE00EB
	IMPORT_C HBufC16* Data() const;

	//WARNING this function can leave as it deletes the wrapper object and then creates
	//a new non deletable wrapper object and sets the data pointer inside the new object
	//IF THIS LEAVES YOU WILL LOSE YOUR DATA
	//##ModelId=3B666BCE00EA
	IMPORT_C void SetDataNoDeleteL();

	//WARNING this function can leave as it deletes the wrapper object and then creates
	//a new deletable wrapper object then sets the pointer in the new object
	//##ModelId=3B666BCE00E9
	IMPORT_C void ClearSetDataNoDeleteL();

	// Sets the data in the node to the FileName parameter that is passed in. 
	// It's deletable and the node will delete it, and the file it refers to in dtor
	// Push aDataLocationNowNodeOwns onto the CleanupStack before calling then pop off on return
	//##ModelId=3B666BCE00DF
	IMPORT_C void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);

	//Resets the data pointer to point to aData parameter will delete the data that is owned by the node
	//##ModelId=3B666BCE00D5
	IMPORT_C void ResetDataPointer(HBufC16* aData);

	//returns a reference to the absolute root of the tree
	//##ModelId=3B666BCE00CB
	IMPORT_C const CNode& Root() const;

	//returns a child node which is stored in the array of children. The child node is accessed by the index that is the parameter.
	//##ModelId=3B666BCE00C1
	IMPORT_C CNode* Child(TInt aByIndex) const;

	//Returns either the first child of this node if the parameter is NULL. Or it returns the next chld in the array after
	//the child passed in as a parameter
	//##ModelId=3B666BCE00AE
	IMPORT_C CNode* NextChild(const CNode* aNode = NULL) const;

	//returns the previous child to the child passed in as a parameter. The node parameter is a reference because its the child previous
	//to the node passed in which obviously must exist
	//##ModelId=3B666BCE00A4
	IMPORT_C CNode* PrevChild(const CNode& aNode) const;

	//Returns the parent of this node
	//##ModelId=3B666BCE00A3
	IMPORT_C CNode* Parent() const;

	//WARNING this function can leave as it calls AppendNodeToThisNode. The aParent parameter is the node to which you would like to make
	//the parent of 'this' node.
	//It removes itself from the childlist of it's current parent
	//##ModelId=3B666BCE0099
	IMPORT_C void ReparentL(CNode* aParent);

	//Returns the next sibling which means in effect that it asks for the next child of its parent.
	//Sibling means brother or sister.
	//##ModelId=3B666BCE0090
	IMPORT_C CNode* NextSibling() const;

	//Returns the previous sibling which means in effect that it asks for the previous child of its parent.
	//Sibling means brother or sister.
	//##ModelId=3B666BCE008F
	IMPORT_C CNode* PrevSibling() const;

	//returns the number of children that this node has
	//##ModelId=3B666BCE0085
	IMPORT_C TInt NumberImmediateChildren() const;

	//Deletes the attribute of which is of aAttributeType (the parameter)
	//WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
	//##ModelId=3B666BCE007C
	IMPORT_C void DeleteAttribute(TAny* aAttributeType);

	//Deletes all the attributes of this node
	//WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
	//##ModelId=3B666BCE007B
	IMPORT_C void DeleteAllAttributes();

	//remove an attribute without deleting it, this is done by simply setting the attributeValue pointer to NULL
	//WARNING you are now responsiblefor the destruction of this attribute value
	//##ModelId=3B666BCE0071
	IMPORT_C void RemoveAttributeNoDelete(TAny* aAttributeType);

	// Returns the number of attributes that this node has
	//##ModelId=3B666BCE0067
	IMPORT_C TInt AttributeCount() const;

	//Returns the type of attribute (AttributeType) at a given index...NOT the attributeValue
	//##ModelId=3B666BCE005D
	IMPORT_C TAny* AttributeTypeByIndex(TInt aIndex) const; 

	//Returns the value of an attribute (AttributeValue) at a given index...NOT the attributeType
	//##ModelId=3B666BCE003F
	IMPORT_C CBase* AttributeByIndex(TInt aIndex) const;
	//##ModelId=3B666BCE0049
	IMPORT_C CBase* AttributeByIndex(TInt aIndex,TAny*& aType) const;

	//Adds an attribute, parameters are the type of attribute and its value
	//WARNING node takes ownership of aAttributeValue
	//Push aAttributeValue onto the CleanupStack before calling then pop off on return
	//##ModelId=3B666BCE002B
	IMPORT_C void AddAttributeL(TAny* AttributeType, CBase* aAttributeValue);

	//Adds data to the node and also adds an attribute, parameters are the Data to be added, the type of attribute and its value
	//WARNING node takes ownership of aData and aAttributeValue
	//Push aAttributeValue and aData onto the CleanupStack before calling then pop off on return
	//##ModelId=3B666BCE000D
	IMPORT_C void AddDataAndAttributeL(HBufC16 *aData, TAny* AttributeType, CBase* aAttributeValue);

	//Returns an attribute value for the given AttributeType(the parameter)
	//##ModelId=3B666BCE0003
	IMPORT_C CBase* Attribute(TAny* AttributeType) const;

	//Returns TRUE if the attribute of the given type exists
	//##ModelId=3B666BCD03E1
	IMPORT_C TBool AttributeExists(TAny* aAttributeType) const;

	//Returns the node type
	//##ModelId=3B666BCD03D7
	IMPORT_C TAny* Type() const;

	//Sets the node type to be aType (the parameter)
	//##ModelId=3B666BCD03CD
	IMPORT_C void SetType(TAny* aType);


protected:
	//ctor
	//##ModelId=3B666BCD03B9
	CNode(TAny* aType, CNode* aParent);

	//internal finds a child which is passed in as a parameter
	//##ModelId=3B666BCD03AF
	TInt FindChild(const CNode* aNode) const;

	//##ModelId=3B666BCD03A7
	HBufC16* SetupDeletableOrNonDeleteableDataLC();
	//##ModelId=3B666BCD03A6
	void AdjustBasePointers();
private:
	// Reserved for future expansion
	//##ModelId=3B666BCD039B
	virtual void Reserved1();			
	//##ModelId=3B666BCD03A5
	virtual void Reserved1() const;

protected:
	//the Type of Node
	//##ModelId=3B666BCD0392
	TAny* iType;

	//This Nodes parent
	//##ModelId=3B666BCD037E
	CNode *iParent;

	// stores attribute type and value. iTypes must be Flat array
	//##ModelId=3B666BCD0372
	CArrayPtrFlat<CBase> iValues;
	//##ModelId=3B666BCD034C
	CArrayPtrFlat<TAny> iTypes;

	//##ModelId=3B666BCD0324
	TInt32* iTypesBasePtr;
	//##ModelId=3B666BCD0310
	CDataNoDelete* iDataValue;
//
	//An array of child nodes
	//##ModelId=3B666BCD02FC
	CArrayPtr<CNode> *iChildList;
private:
	//##ModelId=3B666BCD02DF
	TAny*	iReserved;						// Reserved for future expansion
	};


//CTypedNode is derived from CNode and is a thin template. TNodeType you should define as a 32 bit value
//TAttributeType should be defined as a 32 bit value
//FOR EXPLANATION OF API'S SEE ABOVE 
//##ModelId=3B666BCC01A4
template <class TNodeType, class TAttributeType>
class CTypedNode : public CNode 
/** Template class for a node in a node tree.

The node type is set to the template parameter TNodeType and the attribute type to 
TAttributeType. These parameters should be pointers to the type required to store 
the type value: e.g. for a string, a const TDesC*.

The class is thin template over CNode. */
	{
public:
	//##ModelId=3B666BCC024A
	inline static CTypedNode* NewL(TNodeType aType,CNode* aParent);
	//##ModelId=3B666BCC0248
	inline void DeleteChildNode(CNode* aNode);
	//##ModelId=3B666BCC0247
	inline void DeleteAllChildNodes();
	//##ModelId=3B666BCC0245
	inline CTypedNode<TNodeType,TAttributeType>& AppendNodeL(TNodeType aType);
	//##ModelId=3B666BCC023B
	inline void AppendNodeToThisNodeL(CNode* aNode);
	//##ModelId=3B666BCC0228
	inline void SetDataL(HBufC16* aDataNowNodeOwns);
	//##ModelId=3B666BCC0227
	inline void SetDataNoDeleteL();
	//##ModelId=3B666BCC0221
	inline void ClearSetDataNoDeleteL();
	//##ModelId=3B666BCC021F
	inline void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);
	//##ModelId=3B666BCC021D
	inline void ResetDataPointer(HBufC16* aData);
	//##ModelId=3B666BCC0215
	inline HBufC16* Data() const;
	//##ModelId=3B666BCC0214
	inline const CTypedNode& Root() const;
	//##ModelId=3B666BCC020B
	inline CTypedNode* Child(TInt aByIndex) const;
	//##ModelId=3B666BCC0209
	inline CTypedNode* NextChild(const CNode* aNode = NULL) const;
	//##ModelId=3B666BCC0201
	inline CTypedNode* PrevChild( const CNode& aNode) const;
	//##ModelId=3B666BCC0200
	inline CTypedNode* Parent() const;
	//##ModelId=3B666BCC01FE
	inline void ReparentL(CNode* aParent);
	//##ModelId=3B666BCC01F5
	inline CTypedNode* NextSibling() const;
	//##ModelId=3B666BCC01F4
	inline CTypedNode* PrevSibling() const;
	//##ModelId=3B666BCC01EE
	inline TInt NumberImmediateChildren() const;
	//##ModelId=3B666BCC01EC
	inline void DeleteAttribute(TAttributeType aAttributeType);
	//##ModelId=3B666BCC01EB
	inline void DeleteAllAttributes();
	//##ModelId=3B666BCC01E5
	inline void RemoveAttributeNoDelete(TAttributeType aAttributeType);
	//##ModelId=3B666BCC01E4
	inline TInt AttributeCount() const; // Returns the number of attributes
	//##ModelId=3B666BCC01E2
	inline TAttributeType AttributeTypeByIndex(TInt aIndex) const; 
	//##ModelId=3B666BCC01DC
	inline CBase* AttributeByIndex(TInt aIndex) const; 
	//##ModelId=3B666BCC01DE
	inline CBase* AttributeByIndex(TInt aIndex,TAttributeType& aType) const; 
	//##ModelId=3B666BCC01D9
	inline void AddAttributeL(TAttributeType aAttributeType, CBase* aAttributeValue);
	//##ModelId=3B666BCC01D0
	inline void AddDataAndAttributeL(HBufC16 *aData, TAttributeType aAttributeType, CBase* aAttributeValue);
	//##ModelId=3B666BCC01CE
	inline CBase* Attribute(TAttributeType aAttributeType) const;
	//##ModelId=3B666BCC01CC
	inline TBool AttributeExists(TAttributeType aAttributeType) const;
	//##ModelId=3B666BCC01C9
	inline TNodeType Type() const;
	//##ModelId=3B666BCC01C7
	inline void SetType(TNodeType aType);
protected:
	//##ModelId=3B666BCC01C4
	CTypedNode(TNodeType aType, CNode* aParent);
	};
#include <cnode.inl>
#endif