diff -r 000000000000 -r b16258d2340f applayerprotocols/wapbase/inc/cnode.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/applayerprotocols/wapbase/inc/cnode.h Tue Feb 02 01:09:52 2010 +0200 @@ -0,0 +1,447 @@ +// 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 *tree = CTypedNode::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 +#include + + +/** + @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 iValues; + //##ModelId=3B666BCD034C + CArrayPtrFlat iTypes; + + //##ModelId=3B666BCD0324 + TInt32* iTypesBasePtr; + //##ModelId=3B666BCD0310 + CDataNoDelete* iDataValue; +// + //An array of child nodes + //##ModelId=3B666BCD02FC + CArrayPtr *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 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& 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 +#endif