/*

* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:       Node class declaration

*

*/

#ifndef XMLENGINE_NODE_H_INCLUDED

#define XMLENGINE_NODE_H_INCLUDED

#include <e32base.h>

// forward declaration

class TXmlEngNode;

// Forward declarations

template<class T> class RXmlEngNodeList;

class RXmlEngDocument;

class TXmlEngElement;

class TXmlEngAttr;

class TXmlEngTextNode;

class TXmlEngNamespace;

class TXmlEngComment;

class TXmlEngCDATASection;

class TXmlEngDocumentFragment;

class TXmlEngEntityReference;

class TXmlEngProcessingInstruction;

class MXmlEngUserData;

class TXmlEngBinaryContainer;

class TXmlEngChunkContainer;

class TXmlEngDataContainer;

class TXmlEngFileContainer;

//

/**

 * Instance of TXmlEngNode class represents an XML node in the DOM tree.

 *

 * Class implements methods that are similar for all XML node types

 * i.e. element, attribute.

 * 

 * Sample code for node tree modifications:

 * @code  

 *      RXmlEngDOMImplementation domImpl;

 *      domImpl.OpenL();        ///< opening DOM implementation object 

 *      RXmlEngDocument iDoc; ///< iDoc with created nodes tree

 *      TXmlEngNode tmp = iDoc.DocumentElement();

 *	///< copying first child of iDoc to tmp2 node and appending it

 * 	TXmlEngNode tmp2 = tmp.FirstChild().CopyL();

 *	tmp.AppendChildL(tmp2);

 *	///< copying next node to the first child of iDoc to the last child place

 *	tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild());

 *	///< replasing before last child with second child 

 *	tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling());

 *	///< moving first child of iDoc to second child childrens

 *	tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling());	

 *      iDoc.Close();               ///< closing all opened objects

 *      domImpl.Close();

 * @endcode 

 *

 * @lib XmlEngineDOM.lib

 * @since S60 v3.1

 */

class TXmlEngNode

{

public:

   /**

    * The different element types carried by an XML tree.

    *

    * @note This is synchronized with DOM Level 3 values

    *       See http://www.w3.org/TR/DOM-Level-3-Core/

    *

    */

    enum TXmlEngDOMNodeType {

        EElement                =        1,

        EAttribute              =        2,

        EText                   =        3,

        ECDATASection           =        4,

        EEntityReference        =        5,

        EEntity                 =        6,  //> Not supported currently

        EProcessingInstruction  =        7,

        EComment                =        8,

        EDocument               =        9,

        EDocumentType           =        10, //> Not supported currently

        EDocumentFragment       =        11,

        ENotation               =        12, //> Not supported currently

        ENamespaceDeclaration   =        18, //> Not in DOM spec

		EBinaryContainer 		= 		 30, //> Not in DOM spec

		EChunkContainer 		= 		 31, //> Not in DOM spec

		EFileContainer 			= 		 32  //> Not in DOM spec

    };

public:

    /**

     * Default constructor

     *

     * @since S60 v3.1

     */

    inline TXmlEngNode();

    /**

     * Constructor

     *

     * @since S60 v3.1

     * @param aInternal node pointer

     */

    inline TXmlEngNode(void* aInternal);

    /**

     * Check if node is NULL

     *

     * @since S60 v3.1

     * @return TRUE if node is NULL in other case FALSE

     */

    inline TBool IsNull() const;

    /**

     * Check if node is NULL

     *

     * @since S60 v3.1

     * @return TRUE if node is not NULL in other case FALSE

     */

    inline TBool NotNull()const;

    /**

     * Cast node to attribute node.

     *

     * @since S60 v3.1

     * @return Attribute node

     *

     * @note

     *      - Never cast nodes to a wrong node type!

     *      - Casting removes const'ness of the node

     */

    inline    TXmlEngAttr&                    AsAttr() const;

    /**

     * Cast node to text node.

     *

     * @since S60 v3.1

     * @return Text node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline    TXmlEngTextNode&                AsText() const;

    /**

     * Cast node to binary data container

     *

     * @since S60 v3.2

     * @return Binary container

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline    TXmlEngBinaryContainer&		 AsBinaryContainer() const;

    /**

     * Cast node to memory chunk container

     *

     * @since S60 v3.2

     * @return Chunk container

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline    TXmlEngChunkContainer&		 AsChunkContainer() const;

    /**

     * Cast node to file container

     *

     * @since S60 v3.2

     * @return File container

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline    TXmlEngFileContainer&		 AsFileContainer() const;

    /**

     * Cast node to memory chunk container

     *

     * @since S60 v3.1

     * @return Chunk container

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline    TXmlEngDataContainer&		 AsDataContainer() const;

    /**

     * Cast node to element node.

     *

     * @since S60 v3.1

     * @return Element node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngElement& AsElement() const;

    /**

     * Cast node to comment node.

     *

     * @since S60 v3.1

     * @return Comment node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngComment& AsComment() const;

    /**

     * Cast node to namespace node.

     *

     * @since S60 v3.1

     * @return Namespace node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngNamespace& AsNamespace() const;

    /**

     * Cast node to CDATA section node.

     *

     * @since S60 v3.1

     * @return CDATA section node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngCDATASection& AsCDATASection() const;

    /**

     * Cast node to entity reference node.

     *

     * @since S60 v3.1

     * @return Entity reference node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngEntityReference& AsEntityReference() const;

    /**

     * Cast node to processing instruction node.

     *

     * @since S60 v3.1

     * @return Processing instruction node

     *

     * @note

     *     - Never cast nodes to a wrong node type!

     *     - Casting removes const'ness of the node

     */

    inline TXmlEngProcessingInstruction& AsProcessingInstruction() const;

    /**

     * Get innerXML string. This method returns all content of the node.

     * Output text does not include node markup.

     *

     * @since S60 v3.1

     * @param aBuffer RBuf8 in which output should be save

     * @return Size of output buffer

     * @note Returned RBuf8 should be freed

     */

    IMPORT_C TInt InnerXmlL(RBuf8& aBuffer);

    /**

     * Get outerXML string. This method returns all content of the node.

     * Output text includes node markup.

     *

     * @since S60 v3.1

     * @param aBuffer RBuf8 in which output should be save

     * @return Size of output buffer

     * @note Returned RBuf8 should be freed

     */

    IMPORT_C TInt OuterXmlL(RBuf8& aBuffer);

    /**

     * Moves the node to become the first in the list of its siblings

     * Node is expected to have a parent.

     *

     * @since S60 v3.1

     */

    IMPORT_C void SetAsFirstSibling();

    /**

     * Moves the node to become the last in the list of its siblings

     * Node is expected to have a parent.

     *

     * @since S60 v3.1

     */

    IMPORT_C void SetAsLastSibling();

    /**

     * Moves the node in the list of sibling nodes before another node

     * Node is expected to have a parent.

     * Do nothing if aSiblingNode is not one of node's siblings

     *

     * @since S60 v3.1

	 * @param aSiblingNode Node that should be after current node 

     */

    IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode);

    /**

     * Moves the node in the list of sibling nodes after another node

     * Node is expected to have a parent.

     * Do nothing if aSiblingNode is not one of the node's siblings

     *

     * @since S60 v3.1

	 * @param aSiblingNode Node that should be after current node 

     */    

    IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode);

    /**

     * Moves the node to another part of the tree or another document

     * The node is unliked from current postion (if any) and appended

     * to the its new parent.

     *

     * @since S60 v3.1

     * @param aParent Parent node

     * @return Node handle

     *

     * @note 

     * In many cases this method call should be followed by ReconcileNamespacesL() on the moved node

     */

    inline  TXmlEngNode MoveTo(TXmlEngNode aParent);

    /**

     * Detaches a node from document tree

     *

     * @since S60 v3.1

     * @return This node, which is already not a part of any document

     * @note    Remember to use ReconcileNamespacesL() later, if extracted node (subtree)

     *          contains references to namespace declarations outside of the subtree.

     * @see     ReconcileNamespacesL()

     * @note    The document, from which the is being unlinked, becomes an owner of the node

     *          until it is linked elsewhere.

     */

    IMPORT_C TXmlEngNode Unlink();

    /**

     * Ensures that namespaces referred to in the node and its descendants are

     * in the scope the node.

     *

     * This method checks that all the namespaces declared within the given

     * tree are properly declared. This is needed for example after Copy or Unlink

     * and then Append operations. The subtree may still hold pointers to

     * namespace declarations outside the subtree or they may be invalid/masked. As much

     * as possible the function try to reuse the existing namespaces found in

     * the new environment. If not possible, the new namespaces are redeclared

     * on the top of the subtree.

     *

     * This method should be used after unlinking nodes and inserting to another

     * document tree or to a another part of the original tree, if some nodes of the subtree

     * are remove from the scope of a namespace declaration they refer to.

     *

     * When node is unlinked, it may still refer to namespace declarations from the previous location.

     * It is important to reconcile subtree's namespaces if previous parent tree is to be destroyed.

     * On the other hand, if the parent tree is not changed before pasting its unlinked part into another

     * tree, then reconciliation is needed only after paste operation.

     *

     * @since S60 v3.1

     */

    IMPORT_C void ReconcileNamespacesL();

    /**

     * Unlinks the node and destroys it; all child nodes are destroyed as well and all memory is freed

     *

     * @note  Document nodes cannot be "removed" with this method, uses RXmlEngDocument-specific methods.

     *

     * @since S60 v3.1

     */

    IMPORT_C void Remove();

    /**

     * Current node is replaced with another node (subtree).

     *

     * The replacement node is linked into document tree instead of this node.

     * The replaced node is destroyed.

     *

     * @since S60 v3.1

     * @param aNode Node that repleace current node

     *

     * @see SubstituteFor(TXmlEngNode)

     *

     * In both cases the argument node is unlinked from its previous location

     * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree).

     *

     * @note Replacement of a node with NULL TXmlEngNode is legal and equivalent to removing the node.

     * @note Not applicable to document nodes

     */

    IMPORT_C void ReplaceWith(TXmlEngNode aNode);

    /**

     * Another node is put instead of the current node.

     *

     * Does the same as ReplaceWith(TXmlEngNode) but does not free node and just returns it.

     *

     * @since S60 v3.1

     * @param aNode Node that repleace current node

     * @return Current node after unlinking it from document tree

     * @see ReplaceWith(TXmlEngNode)

     *

     * In both cases the argument node is unlinked from its previous location

     * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree)

     *

     * It is possible to use NULL TXmlEngNode object as an argument. In such case

     * no new node will be put instead of unlinked one.

     *

     * @note Not applicable to document nodes

     */

    IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode);

    /**

     * Retrieves a "handle" for namespace declaration that applies to the node's namespace

     * Note: DOM specs do not consider namespace declarations as a kind of nodes

     * This API adds TXmlEngNamespace type of nodes, which is derived from TXmlEngNode.

     *

     * @since S60 v3.1

     * @return    Object that represents namespace declaration and prefix binding that

     *             act on the node; returns NULL object (check using TXmlEngNamespace.IsNull()

     *             or TXmlEngNamespace.NotNull()) if no namespace associated

     */

    IMPORT_C TXmlEngNamespace NamespaceDeclaration() const;

    /**

     * Attaches a user data object to this node. The ownership of the object is transferred.

     * When the (underlying) node is deleted the Destroy method of the MXmlEngUserData class will be

     * called. If there already is a user data object associated with this node, it will be

     * deleted before attaching the new object.

     *

     * @since S60 v3.1

     * @param aData Pointer to the data object.

     * @return true if successful, false if for example underlying node type doesn't support

     * attaching user data.

     * @note Only TXmlEngElement and Attribute nodes currently support this feature.

     *             User data is not copied, when node is copied.

     */

    IMPORT_C TBool AddUserData(MXmlEngUserData* aData);

    /**

     * Returns the user data object attached to this node. Ownership is not transferred.

     *

     * @since S60 v3.1

     * @return Pointer to data object or NULL if it doesn't exist.

     */

    IMPORT_C MXmlEngUserData* UserData() const;

    /**

     * Removes the user data onject attached to this node. Ownership is transferred

     * (the object is not deleted).

     *

     * @since S60 v3.1

     * @return Pointer to data object or NULL if it doesn't exist.

     */

    IMPORT_C MXmlEngUserData* RemoveUserData();

    /**

     * Clones the node completely: all attributes and namespace declarations (for TXmlEngElement nodes),

     * values and children nodes are copied as well.

     *

     * Document nodes cannot be copied with this method: RXmlEngDocument::CloneDocumentL() must be used.

     *

     * @since S60 v3.1

     * @return Complete copy of a node or leaves.

     * @note    The node should not be NULL!