1.1 --- a/epoc32/include/cnode.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,456 +0,0 @@
1.4 -/// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -/// All rights reserved.
1.6 -/// This component and the accompanying materials are made available
1.7 -/// 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
1.8 -/// which accompanies this distribution, and is available
1.9 -/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -///
1.11 -/// Initial Contributors:
1.12 -/// Nokia Corporation - initial contribution.
1.13 -///
1.14 -/// Contributors:
1.15 -///
1.16 -/// Description:
1.17 -/// All rights reserved.
1.18 -/// This component and the accompanying materials are made available
1.19 -/// 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
1.20 -/// which accompanies this distribution, and is available
1.21 -/// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.22 -/// Initial Contributors:
1.23 -/// Nokia Corporation - initial contribution.
1.24 -/// Contributors:
1.25 -/// This contains the definitions of CDataDelete, CDataNoDelete, CIntAttribute, CNode, and CTypedNode.
1.26 -/// CDataNoDelete is a base class to CDataDelete and are essentially a wrapper around an HBufC16.
1.27 -/// The node owns the data that is added to it and therefore is responsible for deleting all its data,
1.28 -/// hence theses two classes allow a user to have non deletable data. Internally to the node it is also
1.29 -/// sometimes necessary to change the data into either deletable or non-deletable data api's are provided
1.30 -/// for this.
1.31 -/// CIntAttribute is wrapper around a TInt, this is provided as the nodes attribute value is a CBase* however
1.32 -/// it might be desirable to store integer's in here. Attribute value is owned by the node therefore the node is
1.33 -/// responsible for deleting it.
1.34 -/// CNode is the basis for constructing a tree. It consists of an array of child nodes, node type, a parent node,
1.35 -/// an array of attributes, and a data member. Internally the data member is defined as CDataNoDelete however
1.36 -/// to the user all the exported api's take an HBufC16*. Data is owned by the node and is destroyed by the node,
1.37 -/// However in certain circumstances this is not desirable hence the api's to make the data non-deletable. The
1.38 -/// node type is defined as a TAny* however normal usage would use the templated node - CTypedNode. The node type
1.39 -/// is used to identify groups of nodes. The attribute array is fairy simple and consists of AttributeType and
1.40 -/// AttributeValue. AttributeType can be defined by using the templated class and should be a 32bit value. AttributeValue
1.41 -/// can be any object derived from CBase and the node takes ownership therefore the node delete's it.
1.42 -/// Basic usage should be to use the templated class in order to make use of the templated types (TNodeType,TAttributeType).
1.43 -/// Create a node for example:
1.44 -/// CTypedNode<CNode*, const TDesC*> *tree = CTypedNode<CNode*, const TDesC*>::NewL(0,0);
1.45 -/// add a new child:
1.46 -/// CNODE *TestChildNode1 = tree->AppendNodeL(aTempNodeForNodeType);
1.47 -/// add some data:
1.48 -/// TestChildNode1->SetDataL(aHBufC16);
1.49 -/// add an attribute:
1.50 -/// TestChildNode1->->AddAttributeL(aTAttributeType,aCBasePointerAttributeValue);
1.51 -/// Explanation of individual api's is documented below.
1.52 -///
1.53 -
1.54 -
1.55 -
1.56 -
1.57 -#ifndef __CNODE_H__
1.58 -#define __CNODE_H__
1.59 -
1.60 -#include <e32base.h>
1.61 -#include <f32file.h>
1.62 -
1.63 -
1.64 -/**
1.65 - @file
1.66 - @publishedAll
1.67 - @released
1.68 -*/
1.69 -
1.70 -//Granularity of arrays
1.71 -const TInt KGranularity = 5;
1.72 -
1.73 -//enum of panic reasons
1.74 -enum TNodePanic
1.75 - {
1.76 - ENodeBadArgument,
1.77 - ENodeNoChildren,
1.78 - ENoData,
1.79 - EAttributeFailure
1.80 - };
1.81 -
1.82 -//node panic function
1.83 -inline void Panic(TNodePanic aPanic);
1.84 -
1.85 -//Wrapper around an HBufC16 doesn't delete data
1.86 -//##ModelId=3B666BCC0303
1.87 -class CDataNoDelete : public CBase
1.88 -/** Provides a wrapper around an HBufC16: the buffer is not deleted when the object is deleted.
1.89 -*/
1.90 - {
1.91 -public:
1.92 - //##ModelId=3B666BCC032D
1.93 - CDataNoDelete(HBufC16* aData);
1.94 - //##ModelId=3B666BCC032C
1.95 - virtual ~CDataNoDelete();
1.96 - //##ModelId=3B666BCC0324
1.97 - HBufC16* SetData(HBufC16* aData);
1.98 - //##ModelId=3B666BCC0322
1.99 - virtual void ResetDataPointer(HBufC16* aData);
1.100 - //##ModelId=3B666BCC0321
1.101 - HBufC16* Data();
1.102 -
1.103 -protected:
1.104 - /** The wrapped buffer. */
1.105 - //##ModelId=3B666BCC0319
1.106 - HBufC16* iData;
1.107 - };
1.108 -
1.109 -//Wrapper around an HBufC16 does delete data
1.110 -//##ModelId=3B666BCC0399
1.111 -class CDataDelete : public CDataNoDelete
1.112 -/** Provides a wrapper around an HBufC16: the buffer is deleted when the
1.113 -object is deleted.
1.114 -*/
1.115 - {
1.116 -public:
1.117 - //##ModelId=3B666BCC03B7
1.118 - CDataDelete(HBufC16* aData);
1.119 - //##ModelId=3B666BCC03B0
1.120 - virtual ~CDataDelete();
1.121 - //##ModelId=3B666BCC03AE
1.122 - virtual void ResetDataPointer(HBufC16* aData);
1.123 - };
1.124 -
1.125 -//Wrapper around an HBufC16 does delete data (FileName)
1.126 -// After Removing referenced File
1.127 -//##ModelId=3B666BC7026F
1.128 -class CFileDataDelete : public CDataNoDelete
1.129 -/** Provides a wrapper around a filename: the referenced file is deleted when the object is deleted.
1.130 -*/
1.131 - {
1.132 -public:
1.133 - //##ModelId=3B666BC7028F
1.134 - CFileDataDelete(HBufC16* aData);
1.135 - //##ModelId=3B666BC7028E
1.136 - virtual ~CFileDataDelete();
1.137 - //##ModelId=3B666BC70285
1.138 - virtual void ResetDataPointer(HBufC16* aData);
1.139 -private:
1.140 - //##ModelId=3B666BC70284
1.141 - void RemoveFile();
1.142 - };
1.143 -
1.144 -//Wrapper around a TInt used for attribute values in order to allow the node to call a dtor
1.145 -//##ModelId=3B666BC6023E
1.146 -class CIntAttribute : public CBase
1.147 -/** Provides an object wrapper around a TInt value. */
1.148 - {
1.149 -public:
1.150 - //##ModelId=3B666BC6025B
1.151 - inline CIntAttribute(TInt aInteger);
1.152 - //##ModelId=3B666BC6025A
1.153 - inline TInt Int() const;
1.154 -private:
1.155 - //##ModelId=3B666BC60264
1.156 - CIntAttribute();
1.157 - //##ModelId=3B666BC60253
1.158 - TInt iInteger;
1.159 - };
1.160 -
1.161 -//
1.162 -// Node class
1.163 -// Normal usage would be to use CTypedNode in order to use specific templated types
1.164 -//
1.165 -
1.166 -//##ModelId=3B666BCD02D2
1.167 -class CNode : public CBase
1.168 - {
1.169 -public:
1.170 - //##ModelId=3B666BCE0139
1.171 - IMPORT_C ~CNode();
1.172 -
1.173 - //NewL parameters aType to indentify the type of node, CNode* to set the parent of this node
1.174 - //##ModelId=3B666BCE0125
1.175 - IMPORT_C static CNode* NewL(TAny* aType,CNode* aParent);
1.176 -
1.177 - //Deletes a child node which is passed in as a parameter
1.178 - //##ModelId=3B666BCE011C
1.179 - IMPORT_C void DeleteChildNode(CNode* aNode);
1.180 -
1.181 - //Deletes all the child nodes haging of this node
1.182 - //##ModelId=3B666BCE011B
1.183 - IMPORT_C void DeleteAllChildNodes();
1.184 -
1.185 - //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
1.186 - //Type of node is the parameter
1.187 - //##ModelId=3B666BCE0108
1.188 - IMPORT_C CNode& AppendNodeL(TAny* aType = 0);
1.189 -
1.190 - //Appends a node which is passed in as a parameter to this node, so its added to the childlist
1.191 - //##ModelId=3B666BCE00FD
1.192 - IMPORT_C void AppendNodeToThisNodeL(CNode* aNode);
1.193 -
1.194 - //Sets the data in the node to the parameter that is passed in. It's deletable and the node will delete it in dtor
1.195 - //Push aDataNowNodeOwns onto the CleanupStack before calling then pop off on return
1.196 - //##ModelId=3B666BCE00F3
1.197 - IMPORT_C void SetDataL(HBufC16* aDataNowNodeOwns);
1.198 -
1.199 - //returns the data stored in the node, which is returned as an HBufC16*
1.200 - //##ModelId=3B666BCE00EB
1.201 - IMPORT_C HBufC16* Data() const;
1.202 -
1.203 - //WARNING this function can leave as it deletes the wrapper object and then creates
1.204 - //a new non deletable wrapper object and sets the data pointer inside the new object
1.205 - //IF THIS LEAVES YOU WILL LOSE YOUR DATA
1.206 - //##ModelId=3B666BCE00EA
1.207 - IMPORT_C void SetDataNoDeleteL();
1.208 -
1.209 - //WARNING this function can leave as it deletes the wrapper object and then creates
1.210 - //a new deletable wrapper object then sets the pointer in the new object
1.211 - //##ModelId=3B666BCE00E9
1.212 - IMPORT_C void ClearSetDataNoDeleteL();
1.213 -
1.214 - // Sets the data in the node to the FileName parameter that is passed in.
1.215 - // It's deletable and the node will delete it, and the file it refers to in dtor
1.216 - // Push aDataLocationNowNodeOwns onto the CleanupStack before calling then pop off on return
1.217 - //##ModelId=3B666BCE00DF
1.218 - IMPORT_C void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);
1.219 -
1.220 - //Resets the data pointer to point to aData parameter will delete the data that is owned by the node
1.221 - //##ModelId=3B666BCE00D5
1.222 - IMPORT_C void ResetDataPointer(HBufC16* aData);
1.223 -
1.224 - //returns a reference to the absolute root of the tree
1.225 - //##ModelId=3B666BCE00CB
1.226 - IMPORT_C const CNode& Root() const;
1.227 -
1.228 - //returns a child node which is stored in the array of children. The child node is accessed by the index that is the parameter.
1.229 - //##ModelId=3B666BCE00C1
1.230 - IMPORT_C CNode* Child(TInt aByIndex) const;
1.231 -
1.232 - //Returns either the first child of this node if the parameter is NULL. Or it returns the next chld in the array after
1.233 - //the child passed in as a parameter
1.234 - //##ModelId=3B666BCE00AE
1.235 - IMPORT_C CNode* NextChild(const CNode* aNode = NULL) const;
1.236 -
1.237 - //returns the previous child to the child passed in as a parameter. The node parameter is a reference because its the child previous
1.238 - //to the node passed in which obviously must exist
1.239 - //##ModelId=3B666BCE00A4
1.240 - IMPORT_C CNode* PrevChild(const CNode& aNode) const;
1.241 -
1.242 - //Returns the parent of this node
1.243 - //##ModelId=3B666BCE00A3
1.244 - IMPORT_C CNode* Parent() const;
1.245 -
1.246 - //WARNING this function can leave as it calls AppendNodeToThisNode. The aParent parameter is the node to which you would like to make
1.247 - //the parent of 'this' node.
1.248 - //It removes itself from the childlist of it's current parent
1.249 - //##ModelId=3B666BCE0099
1.250 - IMPORT_C void ReparentL(CNode* aParent);
1.251 -
1.252 - //Returns the next sibling which means in effect that it asks for the next child of its parent.
1.253 - //Sibling means brother or sister.
1.254 - //##ModelId=3B666BCE0090
1.255 - IMPORT_C CNode* NextSibling() const;
1.256 -
1.257 - //Returns the previous sibling which means in effect that it asks for the previous child of its parent.
1.258 - //Sibling means brother or sister.
1.259 - //##ModelId=3B666BCE008F
1.260 - IMPORT_C CNode* PrevSibling() const;
1.261 -
1.262 - //returns the number of children that this node has
1.263 - //##ModelId=3B666BCE0085
1.264 - IMPORT_C TInt NumberImmediateChildren() const;
1.265 -
1.266 - //Deletes the attribute of which is of aAttributeType (the parameter)
1.267 - //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
1.268 - //##ModelId=3B666BCE007C
1.269 - IMPORT_C void DeleteAttribute(TAny* aAttributeType);
1.270 -
1.271 - //Deletes all the attributes of this node
1.272 - //WARNING Attribute values of nodes will be deleted as the node owns them if you don't want it deleted then use a wrapper
1.273 - //##ModelId=3B666BCE007B
1.274 - IMPORT_C void DeleteAllAttributes();
1.275 -
1.276 - //remove an attribute without deleting it, this is done by simply setting the attributeValue pointer to NULL
1.277 - //WARNING you are now responsiblefor the destruction of this attribute value
1.278 - //##ModelId=3B666BCE0071
1.279 - IMPORT_C void RemoveAttributeNoDelete(TAny* aAttributeType);
1.280 -
1.281 - // Returns the number of attributes that this node has
1.282 - //##ModelId=3B666BCE0067
1.283 - IMPORT_C TInt AttributeCount() const;
1.284 -
1.285 - //Returns the type of attribute (AttributeType) at a given index...NOT the attributeValue
1.286 - //##ModelId=3B666BCE005D
1.287 - IMPORT_C TAny* AttributeTypeByIndex(TInt aIndex) const;
1.288 -
1.289 - //Returns the value of an attribute (AttributeValue) at a given index...NOT the attributeType
1.290 - //##ModelId=3B666BCE003F
1.291 - IMPORT_C CBase* AttributeByIndex(TInt aIndex) const;
1.292 - //##ModelId=3B666BCE0049
1.293 - IMPORT_C CBase* AttributeByIndex(TInt aIndex,TAny*& aType) const;
1.294 -
1.295 - //Adds an attribute, parameters are the type of attribute and its value
1.296 - //WARNING node takes ownership of aAttributeValue
1.297 - ////Push aAttributeValue onto the CleanupStack before calling then pop off on return
1.298 - //##ModelId=3B666BCE002B
1.299 - IMPORT_C void AddAttributeL(TAny* AttributeType, CBase* aAttributeValue);
1.300 -
1.301 - //Adds data to the node and also adds an attribute, parameters are the Data to be added, the type of attribute and its value
1.302 - //WARNING node takes ownership of aData and aAttributeValue
1.303 - ////Push aAttributeValue and aData onto the CleanupStack before calling then pop off on return
1.304 - //##ModelId=3B666BCE000D
1.305 - IMPORT_C void AddDataAndAttributeL(HBufC16 *aData, TAny* AttributeType, CBase* aAttributeValue);
1.306 -
1.307 - //Returns an attribute value for the given AttributeType(the parameter)
1.308 - //##ModelId=3B666BCE0003
1.309 - IMPORT_C CBase* Attribute(TAny* AttributeType) const;
1.310 -
1.311 - //Returns TRUE if the attribute of the given type exists
1.312 - //##ModelId=3B666BCD03E1
1.313 - IMPORT_C TBool AttributeExists(TAny* aAttributeType) const;
1.314 -
1.315 - //Returns the node type
1.316 - //##ModelId=3B666BCD03D7
1.317 - IMPORT_C TAny* Type() const;
1.318 -
1.319 - //Sets the node type to be aType (the parameter)
1.320 - //##ModelId=3B666BCD03CD
1.321 - IMPORT_C void SetType(TAny* aType);
1.322 -
1.323 -
1.324 -protected:
1.325 - //ctor
1.326 - //##ModelId=3B666BCD03B9
1.327 - CNode(TAny* aType, CNode* aParent);
1.328 -
1.329 - //internal finds a child which is passed in as a parameter
1.330 - //##ModelId=3B666BCD03AF
1.331 - TInt FindChild(const CNode* aNode) const;
1.332 -
1.333 - //##ModelId=3B666BCD03A7
1.334 - HBufC16* SetupDeletableOrNonDeleteableDataLC();
1.335 - //##ModelId=3B666BCD03A6
1.336 - void AdjustBasePointers();
1.337 -private:
1.338 - // Reserved for future expansion
1.339 - //##ModelId=3B666BCD039B
1.340 - virtual void Reserved1();
1.341 - //##ModelId=3B666BCD03A5
1.342 - virtual void Reserved1() const;
1.343 -
1.344 -protected:
1.345 - //the Type of Node
1.346 - //##ModelId=3B666BCD0392
1.347 - TAny* iType;
1.348 -
1.349 - //This Nodes parent
1.350 - //##ModelId=3B666BCD037E
1.351 - CNode *iParent;
1.352 -
1.353 - // stores attribute type and value. iTypes must be Flat array
1.354 - //##ModelId=3B666BCD0372
1.355 - CArrayPtrFlat<CBase> iValues;
1.356 - //##ModelId=3B666BCD034C
1.357 - CArrayPtrFlat<TAny> iTypes;
1.358 -
1.359 - //##ModelId=3B666BCD0324
1.360 - TInt32* iTypesBasePtr;
1.361 - //##ModelId=3B666BCD0310
1.362 - CDataNoDelete* iDataValue;
1.363 -//
1.364 - //An array of child nodes
1.365 - //##ModelId=3B666BCD02FC
1.366 - CArrayPtr<CNode> *iChildList;
1.367 -private:
1.368 - //##ModelId=3B666BCD02DF
1.369 - TAny* iReserved; // Reserved for future expansion
1.370 - };
1.371 -
1.372 -
1.373 -//CTypedNode is derived from CNode and is a thin template. TNodeType you should define as a 32 bit value
1.374 -//TAttributeType should be defined as a 32 bit value
1.375 -//FOR EXPLANATION OF API'S SEE ABOVE
1.376 -//##ModelId=3B666BCC01A4
1.377 -template <class TNodeType, class TAttributeType>
1.378 -class CTypedNode : public CNode
1.379 -/** Template class for a node in a node tree.
1.380 -
1.381 -The node type is set to the template parameter TNodeType and the attribute type to
1.382 -TAttributeType. These parameters should be pointers to the type required to store
1.383 -the type value: e.g. for a string, a const TDesC*.
1.384 -
1.385 -The class is thin template over CNode. */
1.386 - {
1.387 -public:
1.388 - //##ModelId=3B666BCC024A
1.389 - inline static CTypedNode* NewL(TNodeType aType,CNode* aParent);
1.390 - //##ModelId=3B666BCC0248
1.391 - inline void DeleteChildNode(CNode* aNode);
1.392 - //##ModelId=3B666BCC0247
1.393 - inline void DeleteAllChildNodes();
1.394 - //##ModelId=3B666BCC0245
1.395 - inline CTypedNode<TNodeType,TAttributeType>& AppendNodeL(TNodeType aType);
1.396 - //##ModelId=3B666BCC023B
1.397 - inline void AppendNodeToThisNodeL(CNode* aNode);
1.398 - //##ModelId=3B666BCC0228
1.399 - inline void SetDataL(HBufC16* aDataNowNodeOwns);
1.400 - //##ModelId=3B666BCC0227
1.401 - inline void SetDataNoDeleteL();
1.402 - //##ModelId=3B666BCC0221
1.403 - inline void ClearSetDataNoDeleteL();
1.404 - //##ModelId=3B666BCC021F
1.405 - inline void SetFileDataL(HBufC16* aFileDataLocationNowNodeOwns);
1.406 - //##ModelId=3B666BCC021D
1.407 - inline void ResetDataPointer(HBufC16* aData);
1.408 - //##ModelId=3B666BCC0215
1.409 - inline HBufC16* Data() const;
1.410 - //##ModelId=3B666BCC0214
1.411 - inline const CTypedNode& Root() const;
1.412 - //##ModelId=3B666BCC020B
1.413 - inline CTypedNode* Child(TInt aByIndex) const;
1.414 - //##ModelId=3B666BCC0209
1.415 - inline CTypedNode* NextChild(const CNode* aNode = NULL) const;
1.416 - //##ModelId=3B666BCC0201
1.417 - inline CTypedNode* PrevChild( const CNode& aNode) const;
1.418 - //##ModelId=3B666BCC0200
1.419 - inline CTypedNode* Parent() const;
1.420 - //##ModelId=3B666BCC01FE
1.421 - inline void ReparentL(CNode* aParent);
1.422 - //##ModelId=3B666BCC01F5
1.423 - inline CTypedNode* NextSibling() const;
1.424 - //##ModelId=3B666BCC01F4
1.425 - inline CTypedNode* PrevSibling() const;
1.426 - //##ModelId=3B666BCC01EE
1.427 - inline TInt NumberImmediateChildren() const;
1.428 - //##ModelId=3B666BCC01EC
1.429 - inline void DeleteAttribute(TAttributeType aAttributeType);
1.430 - //##ModelId=3B666BCC01EB
1.431 - inline void DeleteAllAttributes();
1.432 - //##ModelId=3B666BCC01E5
1.433 - inline void RemoveAttributeNoDelete(TAttributeType aAttributeType);
1.434 - //##ModelId=3B666BCC01E4
1.435 - inline TInt AttributeCount() const; // Returns the number of attributes
1.436 - //##ModelId=3B666BCC01E2
1.437 - inline TAttributeType AttributeTypeByIndex(TInt aIndex) const;
1.438 - //##ModelId=3B666BCC01DC
1.439 - inline CBase* AttributeByIndex(TInt aIndex) const;
1.440 - //##ModelId=3B666BCC01DE
1.441 - inline CBase* AttributeByIndex(TInt aIndex,TAttributeType& aType) const;
1.442 - //##ModelId=3B666BCC01D9
1.443 - inline void AddAttributeL(TAttributeType aAttributeType, CBase* aAttributeValue);
1.444 - //##ModelId=3B666BCC01D0
1.445 - inline void AddDataAndAttributeL(HBufC16 *aData, TAttributeType aAttributeType, CBase* aAttributeValue);
1.446 - //##ModelId=3B666BCC01CE
1.447 - inline CBase* Attribute(TAttributeType aAttributeType) const;
1.448 - //##ModelId=3B666BCC01CC
1.449 - inline TBool AttributeExists(TAttributeType aAttributeType) const;
1.450 - //##ModelId=3B666BCC01C9
1.451 - inline TNodeType Type() const;
1.452 - //##ModelId=3B666BCC01C7
1.453 - inline void SetType(TNodeType aType);
1.454 -protected:
1.455 - //##ModelId=3B666BCC01C4
1.456 - CTypedNode(TNodeType aType, CNode* aParent);
1.457 - };
1.458 -#include <cnode.inl>
1.459 -#endif