test: epoc32/include/mw/cnode.h@e1b950c65cb4

     1 /// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 /// All rights reserved.

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

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

     5 /// which accompanies this distribution, and is available

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

     7 ///

     8 /// Initial Contributors:

     9 /// Nokia Corporation - initial contribution.

    10 ///

    11 /// Contributors:

    12 ///

    13 /// Description:

    14 /// All rights reserved.

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

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

    17 /// which accompanies this distribution, and is available

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

    19 /// Initial Contributors:

    20 /// Nokia Corporation - initial contribution.

    21 /// Contributors:

    22 /// This contains the definitions of CDataDelete, CDataNoDelete, CIntAttribute, CNode, and CTypedNode.

    23 /// CDataNoDelete is a base class to CDataDelete and are essentially a wrapper around an HBufC16.

    24 /// The node owns the data that is added to it and therefore is responsible for deleting all its data,

    25 /// hence theses two classes allow a user to have non deletable data. Internally to the node it is also

    26 /// sometimes necessary to change the data into either deletable or non-deletable data api's are provided

    27 /// for this.

    28 /// CIntAttribute is wrapper around a TInt, this is provided as the nodes attribute value is a CBase* however

    29 /// it might be desirable to store integer's in here. Attribute value is owned by the node therefore the node is

    30 /// responsible for deleting it.

    31 /// CNode is the basis for constructing a tree. It consists of an array of child nodes, node type, a parent node,

    32 /// an array of attributes, and a data member. Internally the data member is defined as CDataNoDelete however

    33 /// to the user all the exported api's take an HBufC16*. Data is owned by the node and is destroyed by the node,

    34 /// However in certain circumstances this is not desirable hence the api's to make the data non-deletable. The

    35 /// node type is defined as a TAny* however normal usage would use the templated node - CTypedNode. The node type

    36 /// is used to identify groups of nodes. The attribute array is fairy simple and consists of AttributeType and

    37 /// AttributeValue. AttributeType can be defined by using the templated class and should be a 32bit value. AttributeValue

    38 /// can be any object derived from CBase and the node takes ownership therefore the node delete's it.

    39 /// Basic usage should be to use the templated class in order to make use of the templated types (TNodeType,TAttributeType).

    40 /// Create a node for example:

    41 /// CTypedNode<CNode*, const TDesC*> *tree = CTypedNode<CNode*, const TDesC*>::NewL(0,0);

    42 /// add a new child:

    43 /// CNODE *TestChildNode1 = tree->AppendNodeL(aTempNodeForNodeType);

    44 /// add some data:

    45 /// TestChildNode1->SetDataL(aHBufC16);

    46 /// add an attribute:

    47 /// TestChildNode1->->AddAttributeL(aTAttributeType,aCBasePointerAttributeValue);

    48 /// Explanation of individual api's is documented below.

    49 ///

    54 #ifndef __CNODE_H__

    55 #define __CNODE_H__

    57 #include <e32base.h>

    58 #include <f32file.h>

    61 /**

    62 	@file

    63 	@publishedAll

    64 	@released

    65 */

    67 //Granularity of arrays

    68 const TInt KGranularity = 5;

    70 //enum of panic reasons

    71 enum TNodePanic

    72 	{

    73 	ENodeBadArgument,

    74 	ENodeNoChildren,

    75 	ENoData,

    76 	EAttributeFailure

    77 	};

    79 //node panic function

    80 inline void Panic(TNodePanic aPanic);

    82 //Wrapper around an HBufC16 doesn't delete data

    83 //##ModelId=3B666BCC0303

    84 class CDataNoDelete : public CBase

    85 /** Provides a wrapper around an HBufC16: the buffer is not deleted when the object is deleted.

    86 */

    87 	{

    88 public:

    89 	//##ModelId=3B666BCC032D

    90 	CDataNoDelete(HBufC16* aData);

    91 	//##ModelId=3B666BCC032C

    92 	virtual ~CDataNoDelete();

    93 	//##ModelId=3B666BCC0324

    94 	HBufC16* SetData(HBufC16* aData);

    95 	//##ModelId=3B666BCC0322

    96 	virtual void ResetDataPointer(HBufC16* aData);

    97 	//##ModelId=3B666BCC0321

    98 	HBufC16* Data();

   100 protected:

   101 	/** The wrapped buffer. */

   102 	//##ModelId=3B666BCC0319

   103 	HBufC16* iData;

   104 	};

   106 //Wrapper around an HBufC16 does delete data

   107 //##ModelId=3B666BCC0399

   108 class CDataDelete : public CDataNoDelete

   109 /** Provides a wrapper around an HBufC16: the buffer is deleted when the

   110 object is deleted.

   111 */

   112 	{

   113 public:

   114 	//##ModelId=3B666BCC03B7

   115 	CDataDelete(HBufC16* aData);

   116 	//##ModelId=3B666BCC03B0

   117 	virtual ~CDataDelete();

   118 	//##ModelId=3B666BCC03AE

   119 	virtual void ResetDataPointer(HBufC16* aData);

   120 	};

   122 //Wrapper around an HBufC16 does delete data (FileName)

   123 // After Removing referenced File

   124 //##ModelId=3B666BC7026F

   125 class CFileDataDelete : public CDataNoDelete

   126 /** Provides a wrapper around a filename: the referenced file is deleted when the object is deleted.

   127 */

   128 	{

   129 public:

   130 	//##ModelId=3B666BC7028F

   131 	CFileDataDelete(HBufC16* aData);

   132 	//##ModelId=3B666BC7028E

   133 	virtual ~CFileDataDelete();

   134 	//##ModelId=3B666BC70285

   135 	virtual void ResetDataPointer(HBufC16* aData);

   136 private:

   137 	//##ModelId=3B666BC70284

   138 	void RemoveFile();

   139 	};

   141 //Wrapper around a TInt used for attribute values in order to allow the node to call a dtor

   142 //##ModelId=3B666BC6023E

   143 class CIntAttribute : public CBase

   144 /** Provides an object wrapper around a TInt value. */

   145 	{

   146 public:

   147 	//##ModelId=3B666BC6025B

   148 	inline CIntAttribute(TInt aInteger);

   149 	//##ModelId=3B666BC6025A

   150 	inline TInt Int() const;

   151 private:

   152 	//##ModelId=3B666BC60264

   153 	CIntAttribute();

   154 	//##ModelId=3B666BC60253

   155 	TInt iInteger;

   156 	};

   158 //

   159 // Node class

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

   161 //

   163 //##ModelId=3B666BCD02D2

   164 class CNode : public CBase

   165 	{

   166 public:

   167 	//##ModelId=3B666BCE0139

   168 	IMPORT_C ~CNode();

   170 	//NewL parameters aType to indentify the type of node, CNode* to set the parent of this node

   171 	//##ModelId=3B666BCE0125

   172 	IMPORT_C static CNode* NewL(TAny* aType,CNode* aParent);

   174 	//Deletes a child node which is passed in as a parameter

   175 	//##ModelId=3B666BCE011C

   176 	IMPORT_C void DeleteChildNode(CNode* aNode);

   178 	//Deletes all the child nodes haging of this node

   179 	//##ModelId=3B666BCE011B

   180 	IMPORT_C void DeleteAllChildNodes();

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

   183 	//Type of node is the parameter

   184 	//##ModelId=3B666BCE0108

   185 	IMPORT_C CNode& AppendNodeL(TAny* aType = 0);

   187 	//Appends a node which is passed in as a parameter to this node, so its added to the childlist

   188 	//##ModelId=3B666BCE00FD

   189 	IMPORT_C void AppendNodeToThisNodeL(CNode* aNode);

   191 	//Sets the data in the node to the parameter that is passed in. It's deletable and the node will delete it in dtor

   192 	//Push aDataNowNodeOwns onto the CleanupStack before calling then pop off on return

   193 	//##ModelId=3B666BCE00F3

   194 	IMPORT_C void SetDataL(HBufC16* aDataNowNodeOwns);

   196 	//returns the data stored in the node, which is returned as an HBufC16*

   197 	//##ModelId=3B666BCE00EB

   198 	IMPORT_C HBufC16* Data() const;

   200 	//WARNING this function can leave as it deletes the wrapper object and then creates

   201 	//a new non deletable wrapper object and sets the data pointer inside the new object

   202 	//IF THIS LEAVES YOU WILL LOSE YOUR DATA

   203 	//##ModelId=3B666BCE00EA

   204 	IMPORT_C void SetDataNoDeleteL();

   206 	//WARNING this function can leave as it deletes the wrapper object and then creates

   207 	//a new deletable wrapper object then sets the pointer in the new object

   208 	//##ModelId=3B666BCE00E9

   209 	IMPORT_C void ClearSetDataNoDeleteL();

   211 	// Sets the data in the node to the FileName parameter that is passed in.

   212 	// It's deletable and the node will delete it, and the file it refers to in dtor

   213 	// Push aDataLocationNowNodeOwns onto the CleanupStack before calling then pop off on return

   214 	//##ModelId=3B666BCE00DF

   215 	IMPORT_C void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);

   217 	//Resets the data pointer to point to aData parameter will delete the data that is owned by the node

   218 	//##ModelId=3B666BCE00D5

   219 	IMPORT_C void ResetDataPointer(HBufC16* aData);

   221 	//returns a reference to the absolute root of the tree

   222 	//##ModelId=3B666BCE00CB

   223 	IMPORT_C const CNode& Root() const;

   225 	//returns a child node which is stored in the array of children. The child node is accessed by the index that is the parameter.

   226 	//##ModelId=3B666BCE00C1

   227 	IMPORT_C CNode* Child(TInt aByIndex) const;

   229 	//Returns either the first child of this node if the parameter is NULL. Or it returns the next chld in the array after

   230 	//the child passed in as a parameter

   231 	//##ModelId=3B666BCE00AE

   232 	IMPORT_C CNode* NextChild(const CNode* aNode = NULL) const;

   234 	//returns the previous child to the child passed in as a parameter. The node parameter is a reference because its the child previous

   235 	//to the node passed in which obviously must exist

   236 	//##ModelId=3B666BCE00A4

   237 	IMPORT_C CNode* PrevChild(const CNode& aNode) const;

   239 	//Returns the parent of this node

   240 	//##ModelId=3B666BCE00A3

   241 	IMPORT_C CNode* Parent() const;

   243 	//WARNING this function can leave as it calls AppendNodeToThisNode. The aParent parameter is the node to which you would like to make

   244 	//the parent of 'this' node.

   245 	//It removes itself from the childlist of it's current parent

   246 	//##ModelId=3B666BCE0099

   247 	IMPORT_C void ReparentL(CNode* aParent);

   249 	//Returns the next sibling which means in effect that it asks for the next child of its parent.

   250 	//Sibling means brother or sister.

   251 	//##ModelId=3B666BCE0090

   252 	IMPORT_C CNode* NextSibling() const;

   254 	//Returns the previous sibling which means in effect that it asks for the previous child of its parent.

   255 	//Sibling means brother or sister.

   256 	//##ModelId=3B666BCE008F

   257 	IMPORT_C CNode* PrevSibling() const;

   259 	//returns the number of children that this node has

   260 	//##ModelId=3B666BCE0085

   261 	IMPORT_C TInt NumberImmediateChildren() const;

   263 	//Deletes the attribute of which is of aAttributeType (the parameter)

   264 	//WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper

   265 	//##ModelId=3B666BCE007C

   266 	IMPORT_C void DeleteAttribute(TAny* aAttributeType);

   268 	//Deletes all the attributes of this node

   269 	//WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper

   270 	//##ModelId=3B666BCE007B

   271 	IMPORT_C void DeleteAllAttributes();

   273 	//remove an attribute without deleting it, this is done by simply setting the attributeValue pointer to NULL

   274 	//WARNING you are now responsiblefor the destruction of this attribute value

   275 	//##ModelId=3B666BCE0071

   276 	IMPORT_C void RemoveAttributeNoDelete(TAny* aAttributeType);

   278 	// Returns the number of attributes that this node has

   279 	//##ModelId=3B666BCE0067

   280 	IMPORT_C TInt AttributeCount() const;

   282 	//Returns the type of attribute (AttributeType) at a given index...NOT the attributeValue

   283 	//##ModelId=3B666BCE005D

   284 	IMPORT_C TAny* AttributeTypeByIndex(TInt aIndex) const;

   286 	//Returns the value of an attribute (AttributeValue) at a given index...NOT the attributeType

   287 	//##ModelId=3B666BCE003F

   288 	IMPORT_C CBase* AttributeByIndex(TInt aIndex) const;

   289 	//##ModelId=3B666BCE0049

   290 	IMPORT_C CBase* AttributeByIndex(TInt aIndex,TAny*& aType) const;

   292 	//Adds an attribute, parameters are the type of attribute and its value

   293 	//WARNING node takes ownership of aAttributeValue

   294 	////Push aAttributeValue onto the CleanupStack before calling then pop off on return

   295 	//##ModelId=3B666BCE002B

   296 	IMPORT_C void AddAttributeL(TAny* AttributeType, CBase* aAttributeValue);

   298 	//Adds data to the node and also adds an attribute, parameters are the Data to be added, the type of attribute and its value

   299 	//WARNING node takes ownership of aData and aAttributeValue

   300 	////Push aAttributeValue and aData onto the CleanupStack before calling then pop off on return

   301 	//##ModelId=3B666BCE000D

   302 	IMPORT_C void AddDataAndAttributeL(HBufC16 *aData, TAny* AttributeType, CBase* aAttributeValue);

   304 	//Returns an attribute value for the given AttributeType(the parameter)

   305 	//##ModelId=3B666BCE0003

   306 	IMPORT_C CBase* Attribute(TAny* AttributeType) const;

   308 	//Returns TRUE if the attribute of the given type exists

   309 	//##ModelId=3B666BCD03E1

   310 	IMPORT_C TBool AttributeExists(TAny* aAttributeType) const;

   312 	//Returns the node type

   313 	//##ModelId=3B666BCD03D7

   314 	IMPORT_C TAny* Type() const;

   316 	//Sets the node type to be aType (the parameter)

   317 	//##ModelId=3B666BCD03CD

   318 	IMPORT_C void SetType(TAny* aType);

   321 protected:

   322 	//ctor

   323 	//##ModelId=3B666BCD03B9

   324 	CNode(TAny* aType, CNode* aParent);

   326 	//internal finds a child which is passed in as a parameter

   327 	//##ModelId=3B666BCD03AF

   328 	TInt FindChild(const CNode* aNode) const;

   330 	//##ModelId=3B666BCD03A7

   331 	HBufC16* SetupDeletableOrNonDeleteableDataLC();

   332 	//##ModelId=3B666BCD03A6

   333 	void AdjustBasePointers();

   334 private:

   335 	// Reserved for future expansion

   336 	//##ModelId=3B666BCD039B

   337 	virtual void Reserved1();

   338 	//##ModelId=3B666BCD03A5

   339 	virtual void Reserved1() const;

   341 protected:

   342 	//the Type of Node

   343 	//##ModelId=3B666BCD0392

   344 	TAny* iType;

   346 	//This Nodes parent

   347 	//##ModelId=3B666BCD037E

   348 	CNode *iParent;

   350 	// stores attribute type and value. iTypes must be Flat array

   351 	//##ModelId=3B666BCD0372

   352 	CArrayPtrFlat<CBase> iValues;

   353 	//##ModelId=3B666BCD034C

   354 	CArrayPtrFlat<TAny> iTypes;

   356 	//##ModelId=3B666BCD0324

   357 	TInt32* iTypesBasePtr;

   358 	//##ModelId=3B666BCD0310

   359 	CDataNoDelete* iDataValue;

   360 //

   361 	//An array of child nodes

   362 	//##ModelId=3B666BCD02FC

   363 	CArrayPtr<CNode> *iChildList;

   364 private:

   365 	//##ModelId=3B666BCD02DF

   366 	TAny*	iReserved;						// Reserved for future expansion

   367 	};

   370 //CTypedNode is derived from CNode and is a thin template. TNodeType you should define as a 32 bit value

   371 //TAttributeType should be defined as a 32 bit value

   372 //FOR EXPLANATION OF API'S SEE ABOVE

   373 //##ModelId=3B666BCC01A4

   374 template <class TNodeType, class TAttributeType>

   375 class CTypedNode : public CNode

   376 /** Template class for a node in a node tree.

   378 The node type is set to the template parameter TNodeType and the attribute type to

   379 TAttributeType. These parameters should be pointers to the type required to store

   380 the type value: e.g. for a string, a const TDesC*.

   382 The class is thin template over CNode. */

   383 	{

   384 public:

   385 	//##ModelId=3B666BCC024A

   386 	inline static CTypedNode* NewL(TNodeType aType,CNode* aParent);

   387 	//##ModelId=3B666BCC0248

   388 	inline void DeleteChildNode(CNode* aNode);

   389 	//##ModelId=3B666BCC0247

   390 	inline void DeleteAllChildNodes();

   391 	//##ModelId=3B666BCC0245

   392 	inline CTypedNode<TNodeType,TAttributeType>& AppendNodeL(TNodeType aType);

   393 	//##ModelId=3B666BCC023B

   394 	inline void AppendNodeToThisNodeL(CNode* aNode);

   395 	//##ModelId=3B666BCC0228

   396 	inline void SetDataL(HBufC16* aDataNowNodeOwns);

   397 	//##ModelId=3B666BCC0227

   398 	inline void SetDataNoDeleteL();

   399 	//##ModelId=3B666BCC0221

   400 	inline void ClearSetDataNoDeleteL();

   401 	//##ModelId=3B666BCC021F

   402 	inline void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);

   403 	//##ModelId=3B666BCC021D

   404 	inline void ResetDataPointer(HBufC16* aData);

   405 	//##ModelId=3B666BCC0215

   406 	inline HBufC16* Data() const;

   407 	//##ModelId=3B666BCC0214

   408 	inline const CTypedNode& Root() const;

   409 	//##ModelId=3B666BCC020B

   410 	inline CTypedNode* Child(TInt aByIndex) const;

   411 	//##ModelId=3B666BCC0209

   412 	inline CTypedNode* NextChild(const CNode* aNode = NULL) const;

   413 	//##ModelId=3B666BCC0201

   414 	inline CTypedNode* PrevChild( const CNode& aNode) const;

   415 	//##ModelId=3B666BCC0200

   416 	inline CTypedNode* Parent() const;

   417 	//##ModelId=3B666BCC01FE

   418 	inline void ReparentL(CNode* aParent);

   419 	//##ModelId=3B666BCC01F5

   420 	inline CTypedNode* NextSibling() const;

   421 	//##ModelId=3B666BCC01F4

   422 	inline CTypedNode* PrevSibling() const;

   423 	//##ModelId=3B666BCC01EE

   424 	inline TInt NumberImmediateChildren() const;

   425 	//##ModelId=3B666BCC01EC

   426 	inline void DeleteAttribute(TAttributeType aAttributeType);

   427 	//##ModelId=3B666BCC01EB

   428 	inline void DeleteAllAttributes();

   429 	//##ModelId=3B666BCC01E5

   430 	inline void RemoveAttributeNoDelete(TAttributeType aAttributeType);

   431 	//##ModelId=3B666BCC01E4

   432 	inline TInt AttributeCount() const; // Returns the number of attributes

   433 	//##ModelId=3B666BCC01E2

   434 	inline TAttributeType AttributeTypeByIndex(TInt aIndex) const;

   435 	//##ModelId=3B666BCC01DC

   436 	inline CBase* AttributeByIndex(TInt aIndex) const;

   437 	//##ModelId=3B666BCC01DE

   438 	inline CBase* AttributeByIndex(TInt aIndex,TAttributeType& aType) const;

   439 	//##ModelId=3B666BCC01D9

   440 	inline void AddAttributeL(TAttributeType aAttributeType, CBase* aAttributeValue);

   441 	//##ModelId=3B666BCC01D0

   442 	inline void AddDataAndAttributeL(HBufC16 *aData, TAttributeType aAttributeType, CBase* aAttributeValue);

   443 	//##ModelId=3B666BCC01CE

   444 	inline CBase* Attribute(TAttributeType aAttributeType) const;

   445 	//##ModelId=3B666BCC01CC

   446 	inline TBool AttributeExists(TAttributeType aAttributeType) const;

   447 	//##ModelId=3B666BCC01C9

   448 	inline TNodeType Type() const;

   449 	//##ModelId=3B666BCC01C7

   450 	inline void SetType(TNodeType aType);

   451 protected:

   452 	//##ModelId=3B666BCC01C4

   453 	CTypedNode(TNodeType aType, CNode* aParent);

   454 	};

   455 #include <cnode.inl>

   456 #endif

author	William Roberts <williamr@symbian.org>
	Wed, 31 Mar 2010 12:27:01 +0100
branch	Symbian2
changeset 3	e1b950c65cb4
parent 2	epoc32/include/cnode.h@2fe1408b6811
child 4	837f303aceeb
permissions	-rw-r--r--