williamr@4: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@4: // All rights reserved. williamr@4: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@4: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: // williamr@4: // Initial Contributors: williamr@4: // Nokia Corporation - initial contribution. williamr@4: // williamr@4: // Contributors: williamr@4: // williamr@4: // Description: williamr@4: // This contains the definitions of CDataDelete, CDataNoDelete, CIntAttribute, CNode, and CTypedNode. williamr@4: // CDataNoDelete is a base class to CDataDelete and are essentially a wrapper around an HBufC16. williamr@4: // The node owns the data that is added to it and therefore is responsible for deleting all its data, williamr@4: // hence theses two classes allow a user to have non deletable data. Internally to the node it is also williamr@4: // sometimes necessary to change the data into either deletable or non-deletable data api's are provided williamr@4: // for this. williamr@4: // CIntAttribute is wrapper around a TInt, this is provided as the nodes attribute value is a CBase* however williamr@4: // it might be desirable to store integer's in here. Attribute value is owned by the node therefore the node is williamr@4: // responsible for deleting it. williamr@4: // CNode is the basis for constructing a tree. It consists of an array of child nodes, node type, a parent node, williamr@4: // an array of attributes, and a data member. Internally the data member is defined as CDataNoDelete however williamr@4: // to the user all the exported api's take an HBufC16*. Data is owned by the node and is destroyed by the node, williamr@4: // However in certain circumstances this is not desirable hence the api's to make the data non-deletable. The williamr@4: // node type is defined as a TAny* however normal usage would use the templated node - CTypedNode. The node type williamr@4: // is used to identify groups of nodes. The attribute array is fairy simple and consists of AttributeType and williamr@4: // AttributeValue. AttributeType can be defined by using the templated class and should be a 32bit value. AttributeValue williamr@4: // can be any object derived from CBase and the node takes ownership therefore the node delete's it. williamr@4: // Basic usage should be to use the templated class in order to make use of the templated types (TNodeType,TAttributeType). williamr@4: // Create a node for example: williamr@4: // CTypedNode *tree = CTypedNode::NewL(0,0); williamr@4: // add a new child: williamr@4: // CNODE *TestChildNode1 = tree->AppendNodeL(aTempNodeForNodeType); williamr@4: // add some data: williamr@4: // TestChildNode1->SetDataL(aHBufC16); williamr@4: // add an attribute: williamr@4: // TestChildNode1->->AddAttributeL(aTAttributeType,aCBasePointerAttributeValue); williamr@4: // Explanation of individual api's is documented below. williamr@4: // williamr@2: williamr@2: williamr@2: williamr@2: #ifndef __CNODE_H__ williamr@2: #define __CNODE_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: williamr@2: williamr@2: /** williamr@2: @file williamr@2: @publishedAll williamr@4: @deprecated williamr@2: */ williamr@2: williamr@2: //Granularity of arrays williamr@2: const TInt KGranularity = 5; williamr@2: williamr@2: //enum of panic reasons williamr@2: enum TNodePanic williamr@2: { williamr@2: ENodeBadArgument, williamr@2: ENodeNoChildren, williamr@2: ENoData, williamr@2: EAttributeFailure williamr@2: }; williamr@2: williamr@2: //node panic function williamr@2: inline void Panic(TNodePanic aPanic); williamr@2: williamr@2: //Wrapper around an HBufC16 doesn't delete data williamr@2: //##ModelId=3B666BCC0303 williamr@2: class CDataNoDelete : public CBase williamr@2: /** Provides a wrapper around an HBufC16: the buffer is not deleted when the object is deleted. williamr@2: */ williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BCC032D williamr@2: CDataNoDelete(HBufC16* aData); williamr@2: //##ModelId=3B666BCC032C williamr@2: virtual ~CDataNoDelete(); williamr@2: //##ModelId=3B666BCC0324 williamr@2: HBufC16* SetData(HBufC16* aData); williamr@2: //##ModelId=3B666BCC0322 williamr@2: virtual void ResetDataPointer(HBufC16* aData); williamr@2: //##ModelId=3B666BCC0321 williamr@2: HBufC16* Data(); williamr@2: williamr@2: protected: williamr@2: /** The wrapped buffer. */ williamr@2: //##ModelId=3B666BCC0319 williamr@2: HBufC16* iData; williamr@2: }; williamr@2: williamr@2: //Wrapper around an HBufC16 does delete data williamr@2: //##ModelId=3B666BCC0399 williamr@2: class CDataDelete : public CDataNoDelete williamr@2: /** Provides a wrapper around an HBufC16: the buffer is deleted when the williamr@2: object is deleted. williamr@2: */ williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BCC03B7 williamr@2: CDataDelete(HBufC16* aData); williamr@2: //##ModelId=3B666BCC03B0 williamr@2: virtual ~CDataDelete(); williamr@2: //##ModelId=3B666BCC03AE williamr@2: virtual void ResetDataPointer(HBufC16* aData); williamr@2: }; williamr@2: williamr@2: //Wrapper around an HBufC16 does delete data (FileName) williamr@2: // After Removing referenced File williamr@2: //##ModelId=3B666BC7026F williamr@2: class CFileDataDelete : public CDataNoDelete williamr@2: /** Provides a wrapper around a filename: the referenced file is deleted when the object is deleted. williamr@2: */ williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BC7028F williamr@2: CFileDataDelete(HBufC16* aData); williamr@2: //##ModelId=3B666BC7028E williamr@2: virtual ~CFileDataDelete(); williamr@2: //##ModelId=3B666BC70285 williamr@2: virtual void ResetDataPointer(HBufC16* aData); williamr@2: private: williamr@2: //##ModelId=3B666BC70284 williamr@2: void RemoveFile(); williamr@2: }; williamr@2: williamr@2: //Wrapper around a TInt used for attribute values in order to allow the node to call a dtor williamr@2: //##ModelId=3B666BC6023E williamr@2: class CIntAttribute : public CBase williamr@2: /** Provides an object wrapper around a TInt value. */ williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BC6025B williamr@2: inline CIntAttribute(TInt aInteger); williamr@2: //##ModelId=3B666BC6025A williamr@2: inline TInt Int() const; williamr@2: private: williamr@2: //##ModelId=3B666BC60264 williamr@2: CIntAttribute(); williamr@2: //##ModelId=3B666BC60253 williamr@2: TInt iInteger; williamr@2: }; williamr@2: williamr@2: // williamr@2: // Node class williamr@2: // Normal usage would be to use CTypedNode in order to use specific templated types williamr@2: // williamr@2: williamr@2: //##ModelId=3B666BCD02D2 williamr@2: class CNode : public CBase williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BCE0139 williamr@2: IMPORT_C ~CNode(); williamr@2: williamr@2: //NewL parameters aType to indentify the type of node, CNode* to set the parent of this node williamr@2: //##ModelId=3B666BCE0125 williamr@2: IMPORT_C static CNode* NewL(TAny* aType,CNode* aParent); williamr@2: williamr@2: //Deletes a child node which is passed in as a parameter williamr@2: //##ModelId=3B666BCE011C williamr@2: IMPORT_C void DeleteChildNode(CNode* aNode); williamr@2: williamr@2: //Deletes all the child nodes haging of this node williamr@2: //##ModelId=3B666BCE011B williamr@2: IMPORT_C void DeleteAllChildNodes(); williamr@2: williamr@2: //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 williamr@2: //Type of node is the parameter williamr@2: //##ModelId=3B666BCE0108 williamr@2: IMPORT_C CNode& AppendNodeL(TAny* aType = 0); williamr@2: williamr@2: //Appends a node which is passed in as a parameter to this node, so its added to the childlist williamr@2: //##ModelId=3B666BCE00FD williamr@2: IMPORT_C void AppendNodeToThisNodeL(CNode* aNode); williamr@2: williamr@2: //Sets the data in the node to the parameter that is passed in. It's deletable and the node will delete it in dtor williamr@2: //Push aDataNowNodeOwns onto the CleanupStack before calling then pop off on return williamr@2: //##ModelId=3B666BCE00F3 williamr@2: IMPORT_C void SetDataL(HBufC16* aDataNowNodeOwns); williamr@2: williamr@2: //returns the data stored in the node, which is returned as an HBufC16* williamr@2: //##ModelId=3B666BCE00EB williamr@2: IMPORT_C HBufC16* Data() const; williamr@2: williamr@2: //WARNING this function can leave as it deletes the wrapper object and then creates williamr@2: //a new non deletable wrapper object and sets the data pointer inside the new object williamr@2: //IF THIS LEAVES YOU WILL LOSE YOUR DATA williamr@2: //##ModelId=3B666BCE00EA williamr@2: IMPORT_C void SetDataNoDeleteL(); williamr@2: williamr@2: //WARNING this function can leave as it deletes the wrapper object and then creates williamr@2: //a new deletable wrapper object then sets the pointer in the new object williamr@2: //##ModelId=3B666BCE00E9 williamr@2: IMPORT_C void ClearSetDataNoDeleteL(); williamr@2: williamr@2: // Sets the data in the node to the FileName parameter that is passed in. williamr@2: // It's deletable and the node will delete it, and the file it refers to in dtor williamr@2: // Push aDataLocationNowNodeOwns onto the CleanupStack before calling then pop off on return williamr@2: //##ModelId=3B666BCE00DF williamr@2: IMPORT_C void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns); williamr@2: williamr@2: //Resets the data pointer to point to aData parameter will delete the data that is owned by the node williamr@2: //##ModelId=3B666BCE00D5 williamr@2: IMPORT_C void ResetDataPointer(HBufC16* aData); williamr@2: williamr@2: //returns a reference to the absolute root of the tree williamr@2: //##ModelId=3B666BCE00CB williamr@2: IMPORT_C const CNode& Root() const; williamr@2: williamr@2: //returns a child node which is stored in the array of children. The child node is accessed by the index that is the parameter. williamr@2: //##ModelId=3B666BCE00C1 williamr@2: IMPORT_C CNode* Child(TInt aByIndex) const; williamr@2: williamr@2: //Returns either the first child of this node if the parameter is NULL. Or it returns the next chld in the array after williamr@2: //the child passed in as a parameter williamr@2: //##ModelId=3B666BCE00AE williamr@2: IMPORT_C CNode* NextChild(const CNode* aNode = NULL) const; williamr@2: williamr@2: //returns the previous child to the child passed in as a parameter. The node parameter is a reference because its the child previous williamr@2: //to the node passed in which obviously must exist williamr@2: //##ModelId=3B666BCE00A4 williamr@2: IMPORT_C CNode* PrevChild(const CNode& aNode) const; williamr@2: williamr@2: //Returns the parent of this node williamr@2: //##ModelId=3B666BCE00A3 williamr@2: IMPORT_C CNode* Parent() const; williamr@2: williamr@2: //WARNING this function can leave as it calls AppendNodeToThisNode. The aParent parameter is the node to which you would like to make williamr@2: //the parent of 'this' node. williamr@2: //It removes itself from the childlist of it's current parent williamr@2: //##ModelId=3B666BCE0099 williamr@2: IMPORT_C void ReparentL(CNode* aParent); williamr@2: williamr@2: //Returns the next sibling which means in effect that it asks for the next child of its parent. williamr@2: //Sibling means brother or sister. williamr@2: //##ModelId=3B666BCE0090 williamr@2: IMPORT_C CNode* NextSibling() const; williamr@2: williamr@2: //Returns the previous sibling which means in effect that it asks for the previous child of its parent. williamr@2: //Sibling means brother or sister. williamr@2: //##ModelId=3B666BCE008F williamr@2: IMPORT_C CNode* PrevSibling() const; williamr@2: williamr@2: //returns the number of children that this node has williamr@2: //##ModelId=3B666BCE0085 williamr@2: IMPORT_C TInt NumberImmediateChildren() const; williamr@2: williamr@2: //Deletes the attribute of which is of aAttributeType (the parameter) williamr@2: //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper williamr@2: //##ModelId=3B666BCE007C williamr@2: IMPORT_C void DeleteAttribute(TAny* aAttributeType); williamr@2: williamr@2: //Deletes all the attributes of this node williamr@2: //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper williamr@2: //##ModelId=3B666BCE007B williamr@2: IMPORT_C void DeleteAllAttributes(); williamr@2: williamr@2: //remove an attribute without deleting it, this is done by simply setting the attributeValue pointer to NULL williamr@2: //WARNING you are now responsiblefor the destruction of this attribute value williamr@2: //##ModelId=3B666BCE0071 williamr@2: IMPORT_C void RemoveAttributeNoDelete(TAny* aAttributeType); williamr@2: williamr@2: // Returns the number of attributes that this node has williamr@2: //##ModelId=3B666BCE0067 williamr@2: IMPORT_C TInt AttributeCount() const; williamr@2: williamr@2: //Returns the type of attribute (AttributeType) at a given index...NOT the attributeValue williamr@2: //##ModelId=3B666BCE005D williamr@2: IMPORT_C TAny* AttributeTypeByIndex(TInt aIndex) const; williamr@2: williamr@2: //Returns the value of an attribute (AttributeValue) at a given index...NOT the attributeType williamr@2: //##ModelId=3B666BCE003F williamr@2: IMPORT_C CBase* AttributeByIndex(TInt aIndex) const; williamr@2: //##ModelId=3B666BCE0049 williamr@2: IMPORT_C CBase* AttributeByIndex(TInt aIndex,TAny*& aType) const; williamr@2: williamr@2: //Adds an attribute, parameters are the type of attribute and its value williamr@2: //WARNING node takes ownership of aAttributeValue williamr@4: //Push aAttributeValue onto the CleanupStack before calling then pop off on return williamr@2: //##ModelId=3B666BCE002B williamr@2: IMPORT_C void AddAttributeL(TAny* AttributeType, CBase* aAttributeValue); williamr@2: williamr@2: //Adds data to the node and also adds an attribute, parameters are the Data to be added, the type of attribute and its value williamr@2: //WARNING node takes ownership of aData and aAttributeValue williamr@4: //Push aAttributeValue and aData onto the CleanupStack before calling then pop off on return williamr@2: //##ModelId=3B666BCE000D williamr@2: IMPORT_C void AddDataAndAttributeL(HBufC16 *aData, TAny* AttributeType, CBase* aAttributeValue); williamr@2: williamr@2: //Returns an attribute value for the given AttributeType(the parameter) williamr@2: //##ModelId=3B666BCE0003 williamr@2: IMPORT_C CBase* Attribute(TAny* AttributeType) const; williamr@2: williamr@2: //Returns TRUE if the attribute of the given type exists williamr@2: //##ModelId=3B666BCD03E1 williamr@2: IMPORT_C TBool AttributeExists(TAny* aAttributeType) const; williamr@2: williamr@2: //Returns the node type williamr@2: //##ModelId=3B666BCD03D7 williamr@2: IMPORT_C TAny* Type() const; williamr@2: williamr@2: //Sets the node type to be aType (the parameter) williamr@2: //##ModelId=3B666BCD03CD williamr@2: IMPORT_C void SetType(TAny* aType); williamr@2: williamr@2: williamr@2: protected: williamr@2: //ctor williamr@2: //##ModelId=3B666BCD03B9 williamr@2: CNode(TAny* aType, CNode* aParent); williamr@2: williamr@2: //internal finds a child which is passed in as a parameter williamr@2: //##ModelId=3B666BCD03AF williamr@2: TInt FindChild(const CNode* aNode) const; williamr@2: williamr@2: //##ModelId=3B666BCD03A7 williamr@2: HBufC16* SetupDeletableOrNonDeleteableDataLC(); williamr@2: //##ModelId=3B666BCD03A6 williamr@2: void AdjustBasePointers(); williamr@2: private: williamr@2: // Reserved for future expansion williamr@2: //##ModelId=3B666BCD039B williamr@2: virtual void Reserved1(); williamr@2: //##ModelId=3B666BCD03A5 williamr@2: virtual void Reserved1() const; williamr@2: williamr@2: protected: williamr@2: //the Type of Node williamr@2: //##ModelId=3B666BCD0392 williamr@2: TAny* iType; williamr@2: williamr@2: //This Nodes parent williamr@2: //##ModelId=3B666BCD037E williamr@2: CNode *iParent; williamr@2: williamr@2: // stores attribute type and value. iTypes must be Flat array williamr@2: //##ModelId=3B666BCD0372 williamr@2: CArrayPtrFlat iValues; williamr@2: //##ModelId=3B666BCD034C williamr@2: CArrayPtrFlat iTypes; williamr@2: williamr@2: //##ModelId=3B666BCD0324 williamr@2: TInt32* iTypesBasePtr; williamr@2: //##ModelId=3B666BCD0310 williamr@2: CDataNoDelete* iDataValue; williamr@2: // williamr@2: //An array of child nodes williamr@2: //##ModelId=3B666BCD02FC williamr@2: CArrayPtr *iChildList; williamr@2: private: williamr@2: //##ModelId=3B666BCD02DF williamr@2: TAny* iReserved; // Reserved for future expansion williamr@2: }; williamr@2: williamr@2: williamr@2: //CTypedNode is derived from CNode and is a thin template. TNodeType you should define as a 32 bit value williamr@2: //TAttributeType should be defined as a 32 bit value williamr@2: //FOR EXPLANATION OF API'S SEE ABOVE williamr@2: //##ModelId=3B666BCC01A4 williamr@2: template williamr@2: class CTypedNode : public CNode williamr@2: /** Template class for a node in a node tree. williamr@2: williamr@2: The node type is set to the template parameter TNodeType and the attribute type to williamr@2: TAttributeType. These parameters should be pointers to the type required to store williamr@2: the type value: e.g. for a string, a const TDesC*. williamr@2: williamr@2: The class is thin template over CNode. */ williamr@2: { williamr@2: public: williamr@2: //##ModelId=3B666BCC024A williamr@2: inline static CTypedNode* NewL(TNodeType aType,CNode* aParent); williamr@2: //##ModelId=3B666BCC0248 williamr@2: inline void DeleteChildNode(CNode* aNode); williamr@2: //##ModelId=3B666BCC0247 williamr@2: inline void DeleteAllChildNodes(); williamr@2: //##ModelId=3B666BCC0245 williamr@2: inline CTypedNode& AppendNodeL(TNodeType aType); williamr@2: //##ModelId=3B666BCC023B williamr@2: inline void AppendNodeToThisNodeL(CNode* aNode); williamr@2: //##ModelId=3B666BCC0228 williamr@2: inline void SetDataL(HBufC16* aDataNowNodeOwns); williamr@2: //##ModelId=3B666BCC0227 williamr@2: inline void SetDataNoDeleteL(); williamr@2: //##ModelId=3B666BCC0221 williamr@2: inline void ClearSetDataNoDeleteL(); williamr@2: //##ModelId=3B666BCC021F williamr@2: inline void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns); williamr@2: //##ModelId=3B666BCC021D williamr@2: inline void ResetDataPointer(HBufC16* aData); williamr@2: //##ModelId=3B666BCC0215 williamr@2: inline HBufC16* Data() const; williamr@2: //##ModelId=3B666BCC0214 williamr@2: inline const CTypedNode& Root() const; williamr@2: //##ModelId=3B666BCC020B williamr@2: inline CTypedNode* Child(TInt aByIndex) const; williamr@2: //##ModelId=3B666BCC0209 williamr@2: inline CTypedNode* NextChild(const CNode* aNode = NULL) const; williamr@2: //##ModelId=3B666BCC0201 williamr@2: inline CTypedNode* PrevChild( const CNode& aNode) const; williamr@2: //##ModelId=3B666BCC0200 williamr@2: inline CTypedNode* Parent() const; williamr@2: //##ModelId=3B666BCC01FE williamr@2: inline void ReparentL(CNode* aParent); williamr@2: //##ModelId=3B666BCC01F5 williamr@2: inline CTypedNode* NextSibling() const; williamr@2: //##ModelId=3B666BCC01F4 williamr@2: inline CTypedNode* PrevSibling() const; williamr@2: //##ModelId=3B666BCC01EE williamr@2: inline TInt NumberImmediateChildren() const; williamr@2: //##ModelId=3B666BCC01EC williamr@2: inline void DeleteAttribute(TAttributeType aAttributeType); williamr@2: //##ModelId=3B666BCC01EB williamr@2: inline void DeleteAllAttributes(); williamr@2: //##ModelId=3B666BCC01E5 williamr@2: inline void RemoveAttributeNoDelete(TAttributeType aAttributeType); williamr@2: //##ModelId=3B666BCC01E4 williamr@2: inline TInt AttributeCount() const; // Returns the number of attributes williamr@2: //##ModelId=3B666BCC01E2 williamr@2: inline TAttributeType AttributeTypeByIndex(TInt aIndex) const; williamr@2: //##ModelId=3B666BCC01DC williamr@2: inline CBase* AttributeByIndex(TInt aIndex) const; williamr@2: //##ModelId=3B666BCC01DE williamr@2: inline CBase* AttributeByIndex(TInt aIndex,TAttributeType& aType) const; williamr@2: //##ModelId=3B666BCC01D9 williamr@2: inline void AddAttributeL(TAttributeType aAttributeType, CBase* aAttributeValue); williamr@2: //##ModelId=3B666BCC01D0 williamr@2: inline void AddDataAndAttributeL(HBufC16 *aData, TAttributeType aAttributeType, CBase* aAttributeValue); williamr@2: //##ModelId=3B666BCC01CE williamr@2: inline CBase* Attribute(TAttributeType aAttributeType) const; williamr@2: //##ModelId=3B666BCC01CC williamr@2: inline TBool AttributeExists(TAttributeType aAttributeType) const; williamr@2: //##ModelId=3B666BCC01C9 williamr@2: inline TNodeType Type() const; williamr@2: //##ModelId=3B666BCC01C7 williamr@2: inline void SetType(TNodeType aType); williamr@2: protected: williamr@2: //##ModelId=3B666BCC01C4 williamr@2: CTypedNode(TNodeType aType, CNode* aParent); williamr@2: }; williamr@2: #include williamr@2: #endif