/*

* Copyright (c) 2005 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:   XDM document node

*

*/

#ifndef __XDMDOCUMENTNODE__

#define __XDMDOCUMENTNODE__

#include <e32base.h>

#include "XdmNodeInterface.h"

enum TXdmElementType

    {

    EXdmElementNode = 0,

    EXdmElementAttribute,

    EXdmElementUnspecified

    };

class CXdmEngine;

struct SXdmAttribute8;

struct SXdmAttribute16;

class MXdmNodeFactory;

class CXdmNodeAttribute;

class CXdmOperationFactory;

//CLASS DECLARATION

class CXdmDocumentNode : public CBase, public MXdmNodeInterface

    {

    public:  // Constructors and destructor

        /**

        * Create a new child element

        *

		* @return CXdmDocumentNode* 

        */

        IMPORT_C CXdmDocumentNode* CreateChileNodeL();

        /**

        * Create a new child element

        *

        * @param TDesC8& Name of the new element

		* @return CXdmDocumentNode* 

        */

        IMPORT_C CXdmDocumentNode* CreateChileNodeL( const TDesC& aChildName );

        /**

        * Create a new attribute

        *

        * @param TDesC8& Name of the new attribute

		* @return CXdmNodeAttribute* 

        */

        IMPORT_C CXdmNodeAttribute* CreateAttributeL();

        /**

        * Create a new attribute

        *

        * @param TDesC8& Name of the new attribute

		* @return CXdmNodeAttribute* 

        */

        IMPORT_C CXdmNodeAttribute* CreateAttributeL( const TDesC& aAttributeName );

        /**

        * Set the contents of a leaf node. Fails if this element

        * is not a leaf element.

        *

        * <leaf>leafnodecontent</leaf>

        *

        *

        * @param TDesC8& Content of the leaf element

		* @return void 

        */

        IMPORT_C void SetLeafNodeContentL( const TDesC& aLeafContent );

        /**

        * Set the contents of a leaf node. Fails if this element

        * is not a leaf element.

        *

        * <leaf>leafnodecontent</leaf>

        *

        *

        * @param TDesC8& Content of the leaf element

		* @return void 

        */

        IMPORT_C void SetLeafNodeContentL( const TDesC8& aLeafContent );

        /**

        * Define this node to be a leaf node. Default value is EFalse,

        * so this method only needs to be called when the client wants to

        * define a node a leaf node. The operation can, of course, be

        * reverted if needed.

        *

        * @param TBool Define/undefine this node to be a leaf node

		* @return void 

        */

        IMPORT_C void SetLeafNode( TBool aIsLeafNode );

        /**

        * Define this node to be empty. Default value is EFalse,

        * so this method only needs to be called when the client wants

        * to indicate that a node does not/will not have children.

        * The operation can be reverted if needed.

        *

        * NOTE: An attempt to create children on an empty node will

        *       result in a panic being raised. Respectively, if a

        *       client application wants to revert the state of a 

        *       node from non-empty to empty, all children that may

        *       have been created will be removed.

        *

        * @param TBool Define/undefine this node to be empty

		* @return void 

        */

        IMPORT_C void SetEmptyNode( TBool aIsEmptyNode );

        /**

        * Report whether or not this is a leaf element

		* @return TBool Is this a leaf element

        */

        IMPORT_C TBool IsLeafNode() const;

        /**

        * Report whether or not this element is empty

		* @return TBool Is this an empty element

        */

        IMPORT_C TBool IsEmptyNode() const;

        /**

        * Return the contents of a leaf element

		* @return TPtrC8 Contents of the leaf element

        */

        IMPORT_C TPtrC8 LeafNodeContent() const;

        /**

        * Return the contents of a leaf element escape-coded, if needed

		* @return TPtrC8 Contents of the leaf element

        */

        IMPORT_C HBufC8* EscapeLeafNodeContentLC() const;

        /**

        * Returns the contents of a single element without any brackets

        * and pushes the buffer onto the CleanupStack.

        *

        * For instance:

        *

        * 'element attribute1 = "value" attribute2 = "another value"'

        *

		* @return HBufC8* 

        */

        IMPORT_C HBufC8* ElementDataLC() const;

        /**

        * Return the parent node of this element

        *

		* @return CXdmDocumentNode* 

        */

        IMPORT_C CXdmDocumentNode* Parent() const;

        /**

        * Name of this element

		* @return TPtrC8 Name of this element

        */

        IMPORT_C TPtrC NodeName() const;

        /**

        * Name of this element

		* @return TPtrC8 Name of this element

        */

        IMPORT_C HBufC8* EightBitNodeNameLC() const;

        /**

        * (Re-)Set the name of this element

		* @param TDesC& Name of this element

        * @return void

        */

        IMPORT_C void SetNameL( const TDesC& aNodeName );

        /**

        * (Re-)Set the name of this element

		* @param TDesC& Name of this element

        * @return void

        */

        IMPORT_C void SetNameL( const TDesC8& aNodeName );

        /**

        * Returns the number of child & lealf elements

        *

        * @return TInt Number of descendants

        */

        IMPORT_C TInt NodeCount() const;

        /**

        * Returns the number of attributes of this element

        *

		* @return TInt The number of attributes 

        */

        IMPORT_C TInt AttributeCount() const;

        /**

        * Returns a child node specified by its position among the

        * descendants of an element

        *

		* @return CXdmDocument* 

        */

        IMPORT_C CXdmDocumentNode* ChileNode( TInt aPosition ) const;

        /**

        * Reference an attribute of this element specified by the position

        * of the attribute

        *

		* @return CXdmDocument* 

        */

        IMPORT_C CXdmNodeAttribute* Attribute( TInt aPosition ) const;

        /**

        * Reference an attribute of this element specified by the position

        * of the attribute

        *

		* @return CXdmDocument* 

        */

        IMPORT_C CXdmNodeAttribute* Attribute( const TDesC& aAttributeName ) const;

        /**

        * Search for nodes which match the specified name

        *

        * @param TDesC& The element name to search for

        * @param RPointerArray<CXdmDocumentNode> Results, if any

		* @return TInt Error

        */

        IMPORT_C TInt Find( const TDesC& aNodeName,

                            RPointerArray<CXdmDocumentNode>& aResultArray ) const;

        /**

        * Search for nodes which match the specified node

        *

        * @param CXdmDocumentNode& The node to compare to

		* @return TInt KErrNotFound if no matching nodes are found

        */

        IMPORT_C TInt Find( const CXdmDocumentNode& aTargetNode,

                            RPointerArray<CXdmDocumentNode>& aResultArray ) const;

        /**

        * Search for nodes which match the specified name & attributes

        *

        * @param TDesC& The element name to search for

        * @param RPointerArray<CXdmDocumentNode>& Results

        * @param RPointerArray<SXdmAttribute16>& Attributes to search for

		* @return TInt KErrNotFound if no matching nodes are found

        */

        IMPORT_C TInt Find( const TDesC& aNodeName,

                            RPointerArray<CXdmDocumentNode>& aResultArray,

                            const RPointerArray<SXdmAttribute16>& aAttributeArray ) const;

        /**

        * The type of this element: an element or an attribute

		* @return TXdmElementType* 

        */

        IMPORT_C TBool Match( const CXdmDocumentNode& aAnotherNode ) const;

        /**

        * The type of this element: an element or an attribute

		* @return TXdmElementType* 

        */

        IMPORT_C TBool Match( const TDesC& aNodeName,

                              const RPointerArray<SXdmAttribute8>& aAttributeArray ) const;

        /**

        * Comparison operator

        *

		* @return TBool Are the contents of this object identical to

		*               the ones in the parameter

        */

        IMPORT_C TBool operator==( const CXdmDocumentNode& aNode ) const;

        /**

        * The type of this element: an element or an attribute

		* @return TXdmElementType* 

        */                    

        IMPORT_C TBool HasAttribute( const TDesC& aAttributeName ) const;

        /**

        * The type of this element: an element or an attribute

		* @return TXdmElementType* 

        */

        IMPORT_C virtual TXdmElementType ElementType() const;

        /**

        * Remove a child node

        * @param CXdmDocumentNode The element to be removed

		* @return void 

        */

        IMPORT_C void RemoveChileNodeL( CXdmDocumentNode* aChileNode );

        /**

        * Append a child node

        * @param CXdmDocumentNode The element to be appended

		* @return void 

        */

        IMPORT_C void AppendChileNodeL( CXdmDocumentNode* aChileNode );

        /**

        * Insert a child node to the given position

        * @param TInt The position of the new element

        * @param CXdmDocumentNode The element to be inserted

		* @return void 

        */

        IMPORT_C void InsertChileNodeL( TInt aIndex, CXdmDocumentNode* aChileNode );

        /**

        * Replace a child node

        * @param CXdmDocumentNode The new node

        * @param CXdmDocumentNode The node to be replaced

		* @return void 

        */

        IMPORT_C void ReplaceChileNodeL( CXdmDocumentNode* aNewNode,

                                         CXdmDocumentNode* aTargetNode );

        /**

        * Destructor.

        */

        IMPORT_C ~CXdmDocumentNode();

    public:

        /**

        * Print the contents of this node to the log file

        *

		* @return void 

        */

        IMPORT_C void Print();

        /**

        * Return the next node in the list

		* @return CXdmDocumentNode* 

        */

        IMPORT_C CXdmDocumentNode* NextNode() const;

        /**

        * Set the next node in the list

        * @param The next node in the list

		* @return void 

        */

        IMPORT_C void SetNextNode( CXdmDocumentNode* aNextNode );

    public:

        /**

        * Check whether an element has the specified attribute

        *

        * @param CXdmNodeAttribute& The specified attribute

		* @return TBool Does the element have the specified attribute

        */

        TBool HasAttribute( const CXdmNodeAttribute& aNode ) const;

        /**

        * Check whether an element has the specified attribute

        *

        * @param SXdmAttribute8& The specified attribute

		* @return TBool Does the element have the specified attribute

        */

        TBool HasAttributeL( const SXdmAttribute8& aAttribute ) const;

        /**

        * Check whether an element has the specified attribute

        *

        * @param SXdmAttribute16& The specified attribute

		* @return TBool Does the element have the specified attribute

        */

        TBool HasAttribute( const SXdmAttribute16& aAttribute ) const;

    protected: // New functions

        /**

        * Escape-code the specified string

        *

        * @param TDesC8& The descriptor to escape-code

		* @return HBufC8* Escape-coded string

        */

        HBufC8* EscapeDescLC( const TDesC8& aDescriptor ) const;

    protected:

        /**

        * C++ constructor, for derived classes

        *

        * @param CXdmEngine* Reference to the engine

        * @param MXdmNodeFactory* Reference to the node factory

        * @param CXdmDocumentNode* The parent node of this element

        */

		IMPORT_C CXdmDocumentNode( CXdmEngine& aXdmEngine,

		                           MXdmNodeFactory& aNodeFactory,

		                           CXdmDocumentNode* aParentNode );

		/**

        * CC++ constructor, for derived classes

        *

        * @param CXdmEngine* Reference to the engine

        * @param MXdmNodeFactory* Reference to the node factory

        */

        IMPORT_C CXdmDocumentNode( CXdmEngine& aXdmEngine,

                                   MXdmNodeFactory& aNodeFactory );

        /**

        * C++ constructor, for derived classes

        *

        * @param CXdmEngine* Is this a leaf element

        * @param CXdmEngine* Reference to the engine

        * @param MXdmNodeFactory* Reference to the node factory

        * @param CXdmDocumentNode* The parent node of this element

        */

		IMPORT_C CXdmDocumentNode( const TBool aLeafNode,

		                           CXdmEngine& aXdmEngine,

		                           MXdmNodeFactory& aNodeFactory,

                                   CXdmDocumentNode* aParentNode );

        /**

        * Symbian OS constructor for derived classes.

        *

        * @param TDesC8& Name of this element

        * @return void

        */

		IMPORT_C void BaseConstructL( const TDesC& aNodeName );

		/**

        * Copy constructor

        *

        * @param CXdmDocumentNode& The element to copy

        * @param CXdmDocumentNode& The parent of this element

        * @return void

        */

		IMPORT_C virtual void CopyConstructL( const CXdmDocumentNode& aAnotherNode,

		                                      const CXdmDocumentNode& aParentNode );

    private:

        /**

        * Search for nodes which match the specified name

        *

        * @param TDesC& The element name to search for

        * @param RPointerArray<CXdmDocumentNode> Results, if any

		* @return TInt KErrNotFound if no matches were found,

		*         number of matching elements otherwise

        */

        TInt DoFind( const TDesC& aNodeName,

                     RPointerArray<CXdmDocumentNode>& aResultArray ) const;

        /**

        * Search for nodes which match the specified node

        *

        * @param CXdmDocumentNode& The node to compare to

		* @return TInt KErrNotFound if no matching nodes are found

        */             

        TInt DoFind( const CXdmDocumentNode& aTargetNode,

                     RPointerArray<CXdmDocumentNode>& aResultArray ) const;

        /**

        * Search for nodes which match the specified name & attributes

        *

        * @param TDesC& The element name to search for

        * @param RPointerArray<CXdmDocumentNode>& Results

        * @param RPointerArray<SXdmAttribute16>& Attributes to search for

		* @return TInt KErrNotFound if no matching nodes are found

        */              

        TInt DoFind( const TDesC& aNodeName,

                     RPointerArray<CXdmDocumentNode>& aResultArray,

                     const RPointerArray<SXdmAttribute16>& aAttributeArray );

        /**

        * Copy the child nodes of another element.

        *

        * @param CXdmDocumentNode& The element the children of which should be copied

        * @return void

        */

        void ConstructChildrenL( const CXdmDocumentNode& aAnotherNode );

        /**

        * Copy the attributes of another element.

        *

        * @param CXdmDocumentNode& The element the attributes of which should be copied

        * @return void

        */

        void ConstructAttributesL( const CXdmDocumentNode& aAnotherNode );

        /**

        * Remove namespace attributes from this element. Namespaces must 

        * not be used when comparing two elements, which is why these 

        * attributes need to be removed before the comparison.

        *

        * @return void

        */

        void RemoveNamespaceAttributes();

    protected:

        TInt                                        iPosition;

        TBool                                       iLeafNode;

        TBool                                       iEmptyNode;

        HBufC*                                      iNodeName;

        HBufC8*                                     iLeafContent;

        CXdmEngine&                                 iXdmEngine;

        MXdmNodeFactory&                            iNodeFactory;

        friend class                                CXdmDocument;

        CXdmDocumentNode*                           iNextNode;

        CXdmDocumentNode*                           iParentNode;

        RPointerArray<CXdmDocumentNode>             iChildren;

        RPointerArray<CXdmNodeAttribute>            iAttributes;  

    };

#endif      //__XDMDOCUMENTNODE__

// End of File