/// 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

/// which accompanies this distribution, and is available

/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

///

/// Initial Contributors:

/// Nokia Corporation - initial contribution.

///

/// Contributors:

///

/// Description:

/// All rights reserved.

/// This component and the accompanying materials are made available

/// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

/// which accompanies this distribution, and is available

/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

/// Initial Contributors:

/// Nokia Corporation - initial contribution.

/// Contributors:

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

	@released

*/

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