--- a/epoc32/include/xml/dom/xmlengnode.h Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/xml/dom/xmlengnode.h Wed Mar 31 12:33:34 2010 +0100
@@ -1,37 +1,33 @@
-/*
-* 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
-*
-*/
+// Copyright (c) 2006-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:
+// Node class declaration
+//
-
-
-
-
-#ifndef XMLENGINE_NODE_H_INCLUDED
-#define XMLENGINE_NODE_H_INCLUDED
+/**
+ @file
+ @publishedAll
+ @released
+*/
+#ifndef XMLENGNODE_H
+#define XMLENGNODE_H
#include <e32base.h>
-// forward declaration
class TXmlEngNode;
-
-// Forward declarations
template<class T> class RXmlEngNodeList;
-
class RXmlEngDocument;
class TXmlEngElement;
class TXmlEngAttr;
@@ -47,751 +43,733 @@
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
- */
+This class represents an XML node in the DOM tree.
+
+As the base class for other node types (element, attribute, etc.) this class
+implements common methods that are similar for all XML node types.
+
+Sample code for tree manipulations:
+@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 the second child of iDoc to the last child
+ tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild());
+ // replacing the second to last child with the second child
+ tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling());
+ // moving first child of iDoc to second child's children
+ tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling());
+ iDoc.Close(); // closing all opened objects
+ domImpl.Close();
+@endcode
+
+A node is NULL when the internal data pointer is NULL. This is the default
+state of a newly created node. Many DOM APIs that return TXmlEngNode objects
+use this NULL state to indicate a failure of some kind. The methods IsNull()
+and NotNull() can be used to determine whether a node is NULL.
+*/
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/
- *
- */
+ The different node types in a XML tree.
+ */
enum TXmlEngDOMNodeType {
EElement = 1,
EAttribute = 2,
EText = 3,
ECDATASection = 4,
EEntityReference = 5,
- EEntity = 6, //> Not supported currently
+ /** Not supported */
+ EEntity = 6,
EProcessingInstruction = 7,
EComment = 8,
EDocument = 9,
- EDocumentType = 10, //> Not supported currently
+ /** Not supported */
+ EDocumentType = 10,
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
+ /** Not supported */
+ ENotation = 12,
+ /** Extension to the DOM spec */
+ ENamespaceDeclaration = 18,
+ /** Extension to the DOM spec */
+ EBinaryContainer = 30,
+ /** Extension to the DOM spec */
+ EChunkContainer = 31,
+ /** Extension to the DOM spec */
+ EFileContainer = 32
};
public:
- /**
- * Default constructor
- *
- * @since S60 v3.1
- */
+ /** Default constructor */
inline TXmlEngNode();
/**
- * Constructor
- *
- * @since S60 v3.1
- * @param aInternal node pointer
- */
+ Constructor
+ @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
- */
+ Check if the node is NULL
+ @return ETrue if node is NULL, otherwise EFalse
+ */
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;
+ Check if node is not NULL
+ @return ETrue if node is not NULL, otherwise EFalse
+ */
+ 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 to an attribute node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as an attribute 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 to a text node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a text 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 to a binary data container
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a binary container
+ */
+ 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 to a memory chunk container
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a chunk container
+ */
+ 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 to a file container
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a file container
+ */
+ 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 to a memory chunk container
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a chunk container
+ */
+ 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
- */
+ Cast to an element node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as an element 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
- */
+ Cast to a comment node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a comment 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
- */
+ Cast to a namespace node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a namespace 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
- */
+ Cast to a CDATA section node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a CDATA section 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
- */
+ Cast to an entity reference node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as an entity reference 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;
+ Cast to a Document Fragment.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a Document Fragment
+ */
+ inline TXmlEngDocumentFragment& AsDocumentFragment() 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
- */
+ Cast to a processing instruction node.
+ Note:
+ - Never cast nodes to the wrong node type!
+ - Casting removes the const'ness of the node
+ @return This node as a Processing instruction node
+ */
+ inline TXmlEngProcessingInstruction& AsProcessingInstruction() const;
+
+ /**
+ Get the inner XML string. This method returns all content of the node,
+ exluding node markup. Child nodes will be included. Any existing contents
+ in aBuffer will be destroyed. This method allocates memory for the buffer.
+
+ @param aBuffer A buffer owned by the caller that contains the result
+ @return Length of the output buffer
+ @leave KXmlEngErrWrongUseOfAPI Node is NULL
+ @leave - One of the system-wide error codes
+ */
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
- */
+ /**
+ Get the outer XML string. This method returns all content of the node,
+ including node markup. Child nodes will be included. Any existing
+ contents in aBuffer will be destroyed. This method allocates memory for
+ the buffer.
+
+ @param aBuffer A buffer owned by the caller that contains the result
+ @return Length of the output buffer
+ @leave KXmlEngErrWrongUseOfAPI Node is NULL
+ @leave KXmlEngErrNegativeOutputSize Output has a negative length
+ @leave - One of the system-wide error codes
+ */
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
- */
+ Moves the node to become the first in the list of its siblings
+ @pre The node has a parent
+ */
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
- */
+ Moves the node to become the last in the list of its siblings
+ @pre The node has a parent.
+ */
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
- */
+ /**
+ Moves the node to come before the specified node in the list of sibling
+ nodes. This method does nothing if aSiblingNode is not one of the node's
+ siblings.
+ @pre The node has a parent.
+ @param aSiblingNode The node is moved to fall before this sibling
+ */
IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode);
+ /**
+ Moves the node to come after the specified node in the list of sibling
+ nodes. This method does nothing if aSiblingNode is not one of the node's
+ siblings.
+ @pre The node has a parent
+ @param aSiblingNode The node is moved to fall after this sibling
+ */
+ IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode);
+
+ /**
+ Moves the node to another part of the tree or to another document. The
+ node is unlinked from its current postion (if any) and appended to its new
+ parent.
+
+ Note: In many cases this method call should be followed by a call to
+ ReconcileNamespacesL().
+
+ @param aParent This node will be moved to be a child of this node
+ @return This node
+ @leave KXmlEngErrNullNode The node is NULL
+ @leave - One of the system-wide error codes
+ */
+ inline TXmlEngNode MoveToL(TXmlEngNode aParent);
+
/**
- * 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 to another document. The
+ node is unlinked from its current postion (if any) and appended to its new
+ parent.
+
+ Note: In many cases this method call should be followed by a call to
+ ReconcileNamespacesL().
- /**
- * 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);
+ @see ReconcileNamespacesL()
+ @param aParent This node will be moved to be a child of this node
+ @return This node
+ @leave KXmlEngErrNullNode The node is NULL
+ @leave - One of the system-wide error codes
+
+ @deprecated This method has been deprecated and will be removed in a future
+ release.
+ */
+ 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.
- */
+ /**
+ Detaches the node from the document tree. The document maintains ownership
+ of the node until it is linked elsewhere.
+
+ Note: Remember to use ReconcileNamespacesL() later, if the extracted node
+ (or subtree) contains references to namespace declarations outside of the
+ subtree.
+
+ @see ReconcileNamespacesL()
+ @return This node
+ */
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();
+ Ensures that namespaces referred to in the node and its descendants are
+ within the scope of the node.
+
+ This method checks that all the namespaces declared within the subtree
+ parented by this node are properly declared. This is needed for example
+ after a Copy or an Unlink followed by an Append operation. The subtree may
+ still hold pointers to namespace declarations outside the subtree or they
+ may be invalid/masked. The function tries to reuse the existing namespaces
+ found in the new environment as much as possible. If not possible, the new
+ namespaces are redeclared at the top of the subtree.
+
+ This method should be used after unlinking nodes and inserting them into
+ another document tree or into another part of the original tree, if some
+ nodes of the subtree are removed from the scope of the namespace
+ declaration they refer to.
+
+ When a node is unlinked, it may still refer to namespace declarations from
+ the previous location. It is important to reconcile the subtree's
+ namespaces if the 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 the paste
+ operation.
+ @leave - One of the system-wide error codes
+ */
+ IMPORT_C void ReconcileNamespacesL();
+
+ /**
+ Unlinks this node and destroys it; all child nodes are also destroyed and
+ all memory is freed.
+
+ Note: Document nodes cannot be removed with this method. Use
+ RXmlEngDocument::Close() instead.
+ */
+ IMPORT_C void Remove();
- /**
- * 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();
+ /**
+ This node is replaced with another node (or subtree). The replacement node
+ is linked into the document tree instead of this node. The replaced node
+ is destroyed. Replacement of a node with a NULL TXmlEngNode is legal and
+ equivalent to removing the node.
+
+ aNode is unlinked from its previous location, which can be none (i.e. not
+ linked), within the same document tree, or within another document tree.
+
+ Note: Not applicable to document nodes.
- /**
- * 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
- */
+ @see SubstituteForL(TXmlEngNode)
+ @param aNode Node that replaces this node
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave KXmlEngErrWrongUseOfAPI Node is a document node
+ @leave - One of the system-wide error codes
+ */
+ IMPORT_C void ReplaceWithL(TXmlEngNode aNode);
+
+ /**
+ This node is replaced with another node (or subtree). The replacement node
+ is linked into the document tree instead of this node. The replaced node
+ is destroyed. Replacement of a node with a NULL TXmlEngNode is legal and
+ equivalent to removing the node.
+
+ aNode is unlinked from its previous location, which can be none (i.e. not
+ linked), within the same document tree, or within another document tree.
+
+ Note: Not applicable to document nodes.
+
+ @see SubstituteForL(TXmlEngNode)
+ @param aNode Node that replaces this node
+ @deprecated This method has been deprecated and will be removed in a future
+ release.
+ */
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
- */
+ /**
+ Unlinks this node and puts another in its place. This function is the same
+ as ReplaceWithL(), but this node is not freed.
+
+ aNode is unlinked from its previous location, which can be none (i.e. not
+ linked), within the same document tree, or within another document tree.
+
+ It is possible to use a NULL TXmlEngNode object as an argument. In this
+ case, this node will simply be removed from the tree, but not freed.
+
+ Note: Not applicable to document nodes.
+
+ @see ReplaceWithL()
+ @param aNode Node that replaces current node
+ @return The current node after unlinking it from document tree
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave KXmlEngErrWrongUseOfAPI Node is a document node
+ @leave - One of the system-wide error codes
+ */
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;
+ Retrieves the namespace declaration that applies to the node's namespace
+
+ Note: The DOM spec does not consider namespace declarations as a kind of
+ node. This API adds TXmlEngNamespace, which is derived from TXmlEngNode.
+
+ @return The namespace declaration and prefix binding that act on the node;
+ returns a NULL object 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.
- */
+ /**
+ Attaches a user data object to this node. The ownership of the object is
+ transferred. When the node is deleted, the Destroy method of the
+ MXmlEngUserData class will be called. If there is a user data object
+ already associated with this node, it will be deleted before attaching the
+ new object.
+
+ Only TXmlEngElement and TXmlEngAttr nodes currently support this feature.
+
+ User data is not copied when the node is copied.
+
+ @param aData Pointer to the data object.
+ @return ETrue if successful or EFalse if the node type does not support this operation
+ */
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.
- */
+ Gets the user data object attached to this node. Ownership is not transferred.
+ @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.
- */
+ /**
+ Removes the user data object attached to this node and transfers ownership
+ to the caller. The user data object is not deleted.
+ @return Pointer to the user 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!
- */
+ /**
+ Creates a deep copy of the node. All values and children nodes are copied.
+ Attributes and namespace declarations are also copied for TXmlEngElement
+ nodes. Document nodes cannot be copied with this method. Use
+ RXmlEngDocument::CloneDocumentL() instead.
+
+ User data stored with AddUserData() is not copied.
+
+ @return A complete copy of the node or NULL if the node is a document node
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TXmlEngNode CopyL() const;
- /**
- * Creates a deep copy of the node and appends the subtree as a new child
- * to the provided parent node.
- *
- * @since S60 v3.1
- * @return Created copy of the node after linking it into the target document tree.
- * @note Document nodes cannot be copied with this method; use RXmlEngDocument::CloneDocumentL()
- */
+ /**
+ Creates a deep copy of the node and appends the subtree as a new child to
+ the provided parent node. Document nodes cannot be copied with this
+ method. Use RXmlEngDocument::CloneDocumentL() instead.
+
+ User data stored with AddUserData() is not copied.
+
+ @return Created copy of the node after linking it into the target document tree.
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave KXmlEngErrWrongUseOfAPI Node is document node
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const;
- /**
- * Append a child node.
- *
- * This is universal operation for any types of nodes.
- * Note, that some types of nodes cannot have children and
- * some types of nodes are not allowed to be children of some other types.
- *
- * @since S60 v3.1
- * @param aNewChild Child node that should be added
- * @return Appended node, which could changed as a result of adding it to
- * list of child nodes (e.g. text nodes can coalesce together)
- */
+ /**
+ Append a child node. This is a universal operation for any type of node.
+ Note that some types of nodes cannot have children and some types of nodes
+ are not allowed to be children of some other types. These relationships
+ are not enforced by this function.
+
+ @param aNewChild The node that should be added as a child
+ @return The appended node, which could be changed as a result of adding it to
+ list of child nodes (e.g. text nodes can coalesce together)
+ @leave KXmlEngErrNullNode Node or aNewChild is NULL
+ @leave KErrNoMemory Memory allocation failure
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild);
/**
- * Initializes a node list with all children of the node
- *
- * @since S60 v3.1
- * @param aList node list that should be initialized
- */
+ Gets the list of children.
+ @param aList The list of children returned
+ */
IMPORT_C void GetChildNodes(RXmlEngNodeList<TXmlEngNode>& aList) const;
/**
- * Get parent node of current node.
- *
- * @since S60 v3.1
- * @return Parent node of the node or NULL if no parent
- */
+ Gets the parent node
+ @return The parent node or NULL if no parent exists
+ */
IMPORT_C TXmlEngNode ParentNode() const;
/**
- * Get first child of current node
- *
- * @since S60 v3.1
- * @return The first child node or NULL if no children
- */
+ Gets the first child
+ @return The first child node or NULL if no children
+ */
IMPORT_C TXmlEngNode FirstChild() const;
/**
- * Get last child of current node
- *
- * @since S60 v3.1
- * @return The last child node or NULL if no children
- */
+ Gets the last child
+ @return The last child node or NULL if no children
+ */
IMPORT_C TXmlEngNode LastChild() const;
/**
- * Get previous node of current node
- *
- * @since S60 v3.1
- * @return Previous node in a child list or NULL if no sibling before
- */
+ Gets the previous sibling
+ @return The previous sibling or NULL if there is no sibling before
+ */
IMPORT_C TXmlEngNode PreviousSibling() const;
/**
- * Get fallowing node of current node
- *
- * @since S60 v3.1
- * @return Following node in a child list or NULL if no sibling after
- */
+ Gets the next sibling
+ @return The next sibling or NULL if there is no sibling after
+ */
IMPORT_C TXmlEngNode NextSibling() const;
- /**
- * Get document handle
- *
- * @since S60 v3.1
- * @return A document node of the DOM tree this node belongs to
- *
- * @note An instance of RXmlEngDocument class returns itself
- */
+ /**
+ Gets the owning document
+
+ Note: An instance of the RXmlEngDocument class returns itself
+
+ @pre Node must not be NULL.
+ @return The document node of the DOM tree that this node belongs to or a
+ NULL document if no owning document.
+ */
IMPORT_C RXmlEngDocument OwnerDocument() const;
/**
- * Fetches value of this node, depending on its type.
- *
- * @note It is better to always cast nodes to specific type and then use specific
- * method for getting "node value"
- *
- * @since S60 v3.1
- * @return Node value
- */
+ Gets the value of this node.
+
+ Note: Since this is not a virtual function, it is better to always cast
+ nodes to a specific type and then use the specific method for getting the
+ "node value".
+
+ @return The node value
+ */
IMPORT_C TPtrC8 Value() const;
- /**
- * Get copy of node's text content
- * What is returned depends on the node type.
- * Method caller is responsible for freeing returned string.
- *
- * @since S60 v3.1
- * @return the content of the node
- */
+ /**
+ Gets a copy of the node's text content. What is returned depends on the
+ node type. Any existing content in the specified buffer is destroyed.
+ This method allocates memory for the buffer.
+
+ @param aOutput A buffer owned by the caller which holds the returned string
+ @leave - One of the system-wide error codes
+ */
IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const;
/**
- * Sets value of this node.
- *
- * @since S60 v3.1
- * @param aValue New value
- */
+ Copies the specified string and sets the value of this node.
+ @param aValue The value to set
+ @leave KXmlEngErrNullNode The node is NULL
+ @leave - One of the system-wide error codes
+ */
IMPORT_C void SetValueL(const TDesC8& aValue);
/**
- * Check if node content is "simple text".
- *
- * @since S60 v3.1
- * @return Whether the value of the node is presented by only one TXmlEngTextNode node
- *
- * If the value is <i>"simple text"</i> then it is possible to access it as TDOMString
- * without making copy, which combines values of all text nodes and entity reference nodes.
- *
- * @see TXmlEngNode::Value(), TXmlEngAttr::Value(), TXmlEngElement::Text()
- *
- * This method is applicable to TXmlEngElement and TXmlEngAttr nodes. On other nodes FALSE is returned.
- *
- * @note
- * Values (contents) of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, ProcessingInstuction data are
- * always "simple".
- *
- * When the returned result is FALSE, getting value of the node would not returned
- * whole contents because of either entity references present in the contents or
- * the contents is mixed (for TXmlEngElement node). In this case WholeTextContentsCopyL()
- * should be used.
- *
- * @see TXmlEngNode::WholeTextContentsCopyL()
- */
- IMPORT_C TBool IsSimpleTextContents() const;
+ Check if the node content is "simple text" for element and attribute nodes.
+
+ If the node content is "simple text" then it is represented by a single
+ TXmlEngTextNode (or derived type). The contents can be obtained through a
+ call to Value(). A node that has multiple child text nodes does not have
+ node content that is "simple text" and the contents must be obtained
+ through a call to WholeTextContentsCopyL().
- /**
- * Use NodeType() to find out the type of the node prior to casting object
- * of TXmlEngNode class to one of its derived subclasses (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.)
- *
- * @since S60 v3.1
- * @return Type of the node
- *
- * @see TXmlEngDOMNodeType
- */
+ The contents of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, and
+ Processing Instuction data are always "simple".
+
+ @see TXmlEngNode::Value()
+ @see TXmlEngAttr::Value()
+ @see TXmlEngElement::Text()
+ @see TXmlEngNode::WholeTextContentsCopyL()
+
+ @return ETrue if the node is an element or attribute node and content is
+ represented by one TXmlEngTextNode or EFalse otherwise
+ */
+ IMPORT_C TBool IsSimpleTextContents() const;
+
+ /**
+ Gets the node type. Used to find out the type of the node prior to casting
+ the node to one of TXmlEngNode class to one of its derived subclasses
+ (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.).
+
+ @see TXmlEngDOMNodeType
+ @pre Node must not be NULL
+ @return The type of the node
+ */
IMPORT_C TXmlEngDOMNodeType NodeType() const;
/**
- * Get node name
- *
- * @since S60 v3.1
- * @return Name of the node
- *
- * This method generally follows DOM spec :
- * -------------------------------------------------------------------------------
- * The values of nodeName, nodeValue, and attributes vary according to the node
- * type as follows:
- *
- * interface nodeName nodeValue attributes
- * -------------------------------------------------------------------------------
- * Attr = Attr.name = Attr.value = null
- * CDATASection = "#cdata-section" = CharacterData.data = null
- * Comment = "#comment" = CharacterData.data = null
- * Document = "#document" = null = null
- * DocumentFragment = "#document-fragment" = null = null
- * DocumentType = DocumentType.name = null = null
- * Element = Element.tagName = null = NamedNodeMap
- * Entity = entity name = null = null
- * EntityReference = name of entity referenced = null = null
- * Notation = notation name = null = null
- * ProcessingInstruction = target = data = null
- * Text = "#text" = CharacterData.data = null
- * -------------------------------------------------------------------------------
- */
+ Gets the node name.
+
+ This method generally follows the DOM spec:
+ -------------------------------------------------------------------------------
+ The values of nodeName, nodeValue, and attributes vary according to the node
+ type as follows:
+
+ interface nodeName nodeValue attributes
+ -------------------------------------------------------------------------------
+ Attr = Attr.name = Attr.value = null
+ CDATASection = "#cdata-section" = CharacterData.data = null
+ Comment = "#comment" = CharacterData.data = null
+ Document = "#document" = null = null
+ DocumentFragment = "#document-fragment" = null = null
+ DocumentType = DocumentType.name = null = null
+ Element = Element.tagName = null = NamedNodeMap
+ Entity = entity name = null = null
+ EntityReference = name of entity referenced = null = null
+ Notation = notation name = null = null
+ ProcessingInstruction = target = data = null
+ Text = "#text" = CharacterData.data = null
+ -------------------------------------------------------------------------------
+
+ @return The name of the node
+ */
IMPORT_C TPtrC8 Name() const;
/**
- * Check if node has child nodes.
- *
- * @since S60 v3.1
- * @return True if the node is TXmlEngElement and has at least one child node
- */
+ Check if the node has child nodes.
+ @return ETrue if the node has child nodes, EFalse otherwise
+ */
IMPORT_C TBool HasChildNodes() const;
- /**
- * Check if node has attributes.
- *
- * @since S60 v3.1
- * @return True if the node is TXmlEngElement and has at least one attribute
- *
- * @note Namespace-to-prefix bindings are not attributes.
- */
- IMPORT_C TBool HasAttributes() const;
+ /**
+ Check if the node has attributes. Namespace-to-prefix bindings are not
+ considered attributes.
+ @return ETrue if the node is an Element node and has at least one
+ attribute, EFalse otherwise
+ */
+ IMPORT_C TBool HasAttributes() const;
- /**
- * Evaluates active base URI for the node by processing xml:base attributes of parents
- *
- * @since S60 v3.1
- * @return A copy of effective base URI for the node
- * @note It's up to the caller to free the string
- */
+ /**
+ Evaluates the active base URI for the node by processing the xml:base
+ attributes of the parents of the node. If no xml:base attributes exist,
+ an empty string is returned. Any existing content in the specified buffer
+ is destroyed. This function allocates memory for the buffer.
+
+ @param aBaseUri A buffer owned by the caller that holds the result.
+ @leave - One of the system-wide error codes
+ */
IMPORT_C void BaseUriL(RBuf8& aBaseUri) const;
- /**
- * Compares nodes.
- *
- * The nodes are the same if they are referring to the same in-memory
- * data structure.
- *
- * @since S60 v3.1
- * @param aOther Node to compare
- * @return TRUE if the same
- */
+ /**
+ Checks if a node is the same as this node. Nodes are considered the same
+ if they refer to the same in-memory data structure.
+
+ @param aOther Node to compare
+ @return ETrue if the nodes are the same, EFalse otherwise
+ */
inline TBool IsSameNode(TXmlEngNode aOther) const;
/**
- * Get namespace uri.
- *
- * @since S60 v3.1
- * @return Namespace URI of a node
- * - NULL is returned for elements and attributes that do not
- * belong to any namespace.
- * - bound namespace URI is returned for namespace declaration nodes (instances of TXmlEngNamespace).
- * - NULL is returned to all other types of node.
- *
- * @note use IsNull() and NotNull() for testing returned result on the subject
- * of having some URI
- */
+ Gets the namespace URI.
+
+ @return The namespace URI of a TXmlEngNamespace, TXmlEngAttr or
+ TXmlEngElement node if bound, NULL in all other cases.
+ */
IMPORT_C TPtrC8 NamespaceUri() const;
/**
- * Get namespace prefix.
- *
- * @since S60 v3.1
- * @return Prefix of a node
- * Returns NULL for elements and attributes that do not have prefix
- * (node belongs to the default namespace or does not belong to any namespace)
- * NULL is also returned for all types of node other than TXmlEngElement or TXmlEngAttr
- */
- IMPORT_C TPtrC8 Prefix() const;
+ Gets the namespace prefix.
+
+ @return The prefix of an element or attribute node if bound, NULL in all
+ other cases.
+ */
+ IMPORT_C TPtrC8 Prefix() const;
- /**
- * Check if nemespace is default for this node
- *
- * @since S60 v3.1
- * @param aNamespaceUri Namespace URI
- * @return True if given namespace URI is a default one for the node (applicable to elements only)
- *
- * @note "" or NULL can be used to denote undefined namespace
- */
+ /**
+ Check if the given namespace is the same as the default namespace for this
+ node.
+
+ Note: "" or NULL can be used to denote undefined namespace
+
+ @param aNamespaceUri Namespace URI
+ @return ETrue if the node is an element node and its default namespace URI is the same as the given namespace URI, EFalse otherwise
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const;
- /**
- * Searches the prefix that is bound to the given aNamespaceUri and
- * applicable in the scope of this TXmlEngNode.
- *
- * @since S60 v3.1
- * @param aNamespaceUri Namespace Uri that should be found
- * @return A sought prefix or NULL if not found or aNamespaceUri is the default namespace
- *
- * @see TXmlEngElement::LookupNamespaceByUriL(const TDesC8&)
- */
+ /**
+ Searches for the prefix bound to the given aNamespaceUri and applicable
+ within the scope of this node.
+
+ @see TXmlEngElement::LookupNamespaceByUriL()
+
+ @param aNamespaceUri The Namespace URI to search for
+
+ @return The sought prefix or NULL if not found or if aNamespaceUri is the default namespace
+ @leave KXmlEngErrNullNode The node is NULL
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const;
/**
- * Searches the namespace URI that is bound to the given prefix.
- *
- * @since S60 v3.1
- * @param aPrefix Namespace prefix that should be found
- * @return A sought URI or NULL if the prefix is not bound
- *
- * @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
- */
+ Searches for the namespace URI that is bound to the given prefix.
+
+ @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
+
+ @param aPrefix The namespace prefix to search for
+ @return The sought URI or NULL if the prefix is not bound
+ @leave KXmlEngErrNullNode The node is NULL
+ @leave - One of the system-wide error codes
+ */
IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const;
protected:
- /**
- * Unlinks the internal libxml2's node from double-linked list.
- * Relinks neighbour nodes.The node stays virtually linked to its old neighbours! Use with care!!
- *
- * No checks are made; nor parent's, nor node's properties updated
- *
- * @since S60 v3.1
- */
- void DoUnlinkNode();
+ /**
+ Unlinks the node from the double-linked list and relinks any neighbour
+ nodes. Despite being removed from the list, the node retains links to its
+ old neighbours! Use with care!!
+
+ No checks are made. Neither the parent's, nor the node's properties are
+ updated.
+ */
+ void DoUnlinkNode();
/**
- * Inserts the node in a double-linked list of nodes before specified node.
- *
- * No checks are made; nor parent's, nor node's properties updated (except prev/next)
- *
- * @since S60 v3.1
- * @param aNode Target node
- */
+ Inserts this node before the specified node in the double-linked list.
+
+ No checks are made. Neither the parent's, nor the node's properties are
+ updated.
+
+ @param aNode After insertion, this node will come before aNode in the list
+ */
void LinkBefore(TXmlEngNode aNode);
protected:
@@ -800,6 +778,7 @@
};
-#include "xmlengnode.inl"
+#include <xml/dom/xmlengnode.inl>
-#endif /* XMLENGINE_NODE_H_INCLUDED */
+#endif /* XMLENGNODE_H */
+