Attempt to represent the S^2->S^3 header reorganisation as a series of "hg rename" operations
2 * Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * 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
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Node class declaration
24 #ifndef XMLENGINE_NODE_H_INCLUDED
25 #define XMLENGINE_NODE_H_INCLUDED
29 // forward declaration
32 // Forward declarations
33 template<class T> class RXmlEngNodeList;
35 class RXmlEngDocument;
38 class TXmlEngTextNode;
39 class TXmlEngNamespace;
41 class TXmlEngCDATASection;
42 class TXmlEngDocumentFragment;
43 class TXmlEngEntityReference;
44 class TXmlEngProcessingInstruction;
45 class MXmlEngUserData;
46 class TXmlEngBinaryContainer;
47 class TXmlEngChunkContainer;
48 class TXmlEngDataContainer;
49 class TXmlEngFileContainer;
53 * Instance of TXmlEngNode class represents an XML node in the DOM tree.
55 * Class implements methods that are similar for all XML node types
56 * i.e. element, attribute.
58 * Sample code for node tree modifications:
60 * RXmlEngDOMImplementation domImpl;
61 * domImpl.OpenL(); ///< opening DOM implementation object
62 * RXmlEngDocument iDoc; ///< iDoc with created nodes tree
63 * TXmlEngNode tmp = iDoc.DocumentElement();
64 * ///< copying first child of iDoc to tmp2 node and appending it
65 * TXmlEngNode tmp2 = tmp.FirstChild().CopyL();
66 * tmp.AppendChildL(tmp2);
67 * ///< copying next node to the first child of iDoc to the last child place
68 * tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild());
69 * ///< replasing before last child with second child
70 * tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling());
71 * ///< moving first child of iDoc to second child childrens
72 * tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling());
73 * iDoc.Close(); ///< closing all opened objects
77 * @lib XmlEngineDOM.lib
84 * The different element types carried by an XML tree.
86 * @note This is synchronized with DOM Level 3 values
87 * See http://www.w3.org/TR/DOM-Level-3-Core/
90 enum TXmlEngDOMNodeType {
96 EEntity = 6, //> Not supported currently
97 EProcessingInstruction = 7,
100 EDocumentType = 10, //> Not supported currently
101 EDocumentFragment = 11,
102 ENotation = 12, //> Not supported currently
103 ENamespaceDeclaration = 18, //> Not in DOM spec
104 EBinaryContainer = 30, //> Not in DOM spec
105 EChunkContainer = 31, //> Not in DOM spec
106 EFileContainer = 32 //> Not in DOM spec
111 * Default constructor
115 inline TXmlEngNode();
121 * @param aInternal node pointer
123 inline TXmlEngNode(void* aInternal);
126 * Check if node is NULL
129 * @return TRUE if node is NULL in other case FALSE
131 inline TBool IsNull() const;
134 * Check if node is NULL
137 * @return TRUE if node is not NULL in other case FALSE
139 inline TBool NotNull()const;
142 * Cast node to attribute node.
145 * @return Attribute node
148 * - Never cast nodes to a wrong node type!
149 * - Casting removes const'ness of the node
151 inline TXmlEngAttr& AsAttr() const;
154 * Cast node to text node.
160 * - Never cast nodes to a wrong node type!
161 * - Casting removes const'ness of the node
163 inline TXmlEngTextNode& AsText() const;
166 * Cast node to binary data container
169 * @return Binary container
172 * - Never cast nodes to a wrong node type!
173 * - Casting removes const'ness of the node
175 inline TXmlEngBinaryContainer& AsBinaryContainer() const;
178 * Cast node to memory chunk container
181 * @return Chunk container
184 * - Never cast nodes to a wrong node type!
185 * - Casting removes const'ness of the node
187 inline TXmlEngChunkContainer& AsChunkContainer() const;
190 * Cast node to file container
193 * @return File container
196 * - Never cast nodes to a wrong node type!
197 * - Casting removes const'ness of the node
199 inline TXmlEngFileContainer& AsFileContainer() const;
202 * Cast node to memory chunk container
205 * @return Chunk container
208 * - Never cast nodes to a wrong node type!
209 * - Casting removes const'ness of the node
211 inline TXmlEngDataContainer& AsDataContainer() const;
214 * Cast node to element node.
217 * @return Element node
220 * - Never cast nodes to a wrong node type!
221 * - Casting removes const'ness of the node
223 inline TXmlEngElement& AsElement() const;
226 * Cast node to comment node.
229 * @return Comment node
232 * - Never cast nodes to a wrong node type!
233 * - Casting removes const'ness of the node
235 inline TXmlEngComment& AsComment() const;
238 * Cast node to namespace node.
241 * @return Namespace node
244 * - Never cast nodes to a wrong node type!
245 * - Casting removes const'ness of the node
247 inline TXmlEngNamespace& AsNamespace() const;
250 * Cast node to CDATA section node.
253 * @return CDATA section node
256 * - Never cast nodes to a wrong node type!
257 * - Casting removes const'ness of the node
259 inline TXmlEngCDATASection& AsCDATASection() const;
262 * Cast node to entity reference node.
265 * @return Entity reference node
268 * - Never cast nodes to a wrong node type!
269 * - Casting removes const'ness of the node
271 inline TXmlEngEntityReference& AsEntityReference() const;
274 * Cast node to processing instruction node.
277 * @return Processing instruction node
280 * - Never cast nodes to a wrong node type!
281 * - Casting removes const'ness of the node
283 inline TXmlEngProcessingInstruction& AsProcessingInstruction() const;
286 * Get innerXML string. This method returns all content of the node.
287 * Output text does not include node markup.
290 * @param aBuffer RBuf8 in which output should be save
291 * @return Size of output buffer
292 * @note Returned RBuf8 should be freed
294 IMPORT_C TInt InnerXmlL(RBuf8& aBuffer);
297 * Get outerXML string. This method returns all content of the node.
298 * Output text includes node markup.
301 * @param aBuffer RBuf8 in which output should be save
302 * @return Size of output buffer
303 * @note Returned RBuf8 should be freed
305 IMPORT_C TInt OuterXmlL(RBuf8& aBuffer);
308 * Moves the node to become the first in the list of its siblings
309 * Node is expected to have a parent.
313 IMPORT_C void SetAsFirstSibling();
316 * Moves the node to become the last in the list of its siblings
317 * Node is expected to have a parent.
321 IMPORT_C void SetAsLastSibling();
324 * Moves the node in the list of sibling nodes before another node
325 * Node is expected to have a parent.
326 * Do nothing if aSiblingNode is not one of node's siblings
329 * @param aSiblingNode Node that should be after current node
331 IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode);
334 * Moves the node in the list of sibling nodes after another node
335 * Node is expected to have a parent.
336 * Do nothing if aSiblingNode is not one of the node's siblings
339 * @param aSiblingNode Node that should be after current node
341 IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode);
344 * Moves the node to another part of the tree or another document
345 * The node is unliked from current postion (if any) and appended
346 * to the its new parent.
349 * @param aParent Parent node
350 * @return Node handle
353 * In many cases this method call should be followed by ReconcileNamespacesL() on the moved node
355 inline TXmlEngNode MoveTo(TXmlEngNode aParent);
358 * Detaches a node from document tree
361 * @return This node, which is already not a part of any document
362 * @note Remember to use ReconcileNamespacesL() later, if extracted node (subtree)
363 * contains references to namespace declarations outside of the subtree.
364 * @see ReconcileNamespacesL()
365 * @note The document, from which the is being unlinked, becomes an owner of the node
366 * until it is linked elsewhere.
368 IMPORT_C TXmlEngNode Unlink();
371 * Ensures that namespaces referred to in the node and its descendants are
372 * in the scope the node.
374 * This method checks that all the namespaces declared within the given
375 * tree are properly declared. This is needed for example after Copy or Unlink
376 * and then Append operations. The subtree may still hold pointers to
377 * namespace declarations outside the subtree or they may be invalid/masked. As much
378 * as possible the function try to reuse the existing namespaces found in
379 * the new environment. If not possible, the new namespaces are redeclared
380 * on the top of the subtree.
382 * This method should be used after unlinking nodes and inserting to another
383 * document tree or to a another part of the original tree, if some nodes of the subtree
384 * are remove from the scope of a namespace declaration they refer to.
386 * When node is unlinked, it may still refer to namespace declarations from the previous location.
387 * It is important to reconcile subtree's namespaces if previous parent tree is to be destroyed.
388 * On the other hand, if the parent tree is not changed before pasting its unlinked part into another
389 * tree, then reconciliation is needed only after paste operation.
393 IMPORT_C void ReconcileNamespacesL();
396 * Unlinks the node and destroys it; all child nodes are destroyed as well and all memory is freed
398 * @note Document nodes cannot be "removed" with this method, uses RXmlEngDocument-specific methods.
402 IMPORT_C void Remove();
405 * Current node is replaced with another node (subtree).
407 * The replacement node is linked into document tree instead of this node.
408 * The replaced node is destroyed.
411 * @param aNode Node that repleace current node
413 * @see SubstituteFor(TXmlEngNode)
415 * In both cases the argument node is unlinked from its previous location
416 * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree).
418 * @note Replacement of a node with NULL TXmlEngNode is legal and equivalent to removing the node.
419 * @note Not applicable to document nodes
421 IMPORT_C void ReplaceWith(TXmlEngNode aNode);
424 * Another node is put instead of the current node.
426 * Does the same as ReplaceWith(TXmlEngNode) but does not free node and just returns it.
429 * @param aNode Node that repleace current node
430 * @return Current node after unlinking it from document tree
431 * @see ReplaceWith(TXmlEngNode)
433 * In both cases the argument node is unlinked from its previous location
434 * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree)
436 * It is possible to use NULL TXmlEngNode object as an argument. In such case
437 * no new node will be put instead of unlinked one.
439 * @note Not applicable to document nodes
441 IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode);
444 * Retrieves a "handle" for namespace declaration that applies to the node's namespace
445 * Note: DOM specs do not consider namespace declarations as a kind of nodes
446 * This API adds TXmlEngNamespace type of nodes, which is derived from TXmlEngNode.
449 * @return Object that represents namespace declaration and prefix binding that
450 * act on the node; returns NULL object (check using TXmlEngNamespace.IsNull()
451 * or TXmlEngNamespace.NotNull()) if no namespace associated
453 IMPORT_C TXmlEngNamespace NamespaceDeclaration() const;
456 * Attaches a user data object to this node. The ownership of the object is transferred.
457 * When the (underlying) node is deleted the Destroy method of the MXmlEngUserData class will be
458 * called. If there already is a user data object associated with this node, it will be
459 * deleted before attaching the new object.
462 * @param aData Pointer to the data object.
463 * @return true if successful, false if for example underlying node type doesn't support
464 * attaching user data.
465 * @note Only TXmlEngElement and Attribute nodes currently support this feature.
466 * User data is not copied, when node is copied.
468 IMPORT_C TBool AddUserData(MXmlEngUserData* aData);
471 * Returns the user data object attached to this node. Ownership is not transferred.
474 * @return Pointer to data object or NULL if it doesn't exist.
476 IMPORT_C MXmlEngUserData* UserData() const;
479 * Removes the user data onject attached to this node. Ownership is transferred
480 * (the object is not deleted).
483 * @return Pointer to data object or NULL if it doesn't exist.
485 IMPORT_C MXmlEngUserData* RemoveUserData();
488 * Clones the node completely: all attributes and namespace declarations (for TXmlEngElement nodes),
489 * values and children nodes are copied as well.
491 * Document nodes cannot be copied with this method: RXmlEngDocument::CloneDocumentL() must be used.
494 * @return Complete copy of a node or leaves.
495 * @note The node should not be NULL!
497 IMPORT_C TXmlEngNode CopyL() const;
500 * Creates a deep copy of the node and appends the subtree as a new child
501 * to the provided parent node.
504 * @return Created copy of the node after linking it into the target document tree.
505 * @note Document nodes cannot be copied with this method; use RXmlEngDocument::CloneDocumentL()
507 IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const;
510 * Append a child node.
512 * This is universal operation for any types of nodes.
513 * Note, that some types of nodes cannot have children and
514 * some types of nodes are not allowed to be children of some other types.
517 * @param aNewChild Child node that should be added
518 * @return Appended node, which could changed as a result of adding it to
519 * list of child nodes (e.g. text nodes can coalesce together)
521 IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild);
524 * Initializes a node list with all children of the node
527 * @param aList node list that should be initialized
529 IMPORT_C void GetChildNodes(RXmlEngNodeList<TXmlEngNode>& aList) const;
532 * Get parent node of current node.
535 * @return Parent node of the node or NULL if no parent
537 IMPORT_C TXmlEngNode ParentNode() const;
540 * Get first child of current node
543 * @return The first child node or NULL if no children
545 IMPORT_C TXmlEngNode FirstChild() const;
548 * Get last child of current node
551 * @return The last child node or NULL if no children
553 IMPORT_C TXmlEngNode LastChild() const;
556 * Get previous node of current node
559 * @return Previous node in a child list or NULL if no sibling before
561 IMPORT_C TXmlEngNode PreviousSibling() const;
564 * Get fallowing node of current node
567 * @return Following node in a child list or NULL if no sibling after
569 IMPORT_C TXmlEngNode NextSibling() const;
572 * Get document handle
575 * @return A document node of the DOM tree this node belongs to
577 * @note An instance of RXmlEngDocument class returns itself
579 IMPORT_C RXmlEngDocument OwnerDocument() const;
582 * Fetches value of this node, depending on its type.
584 * @note It is better to always cast nodes to specific type and then use specific
585 * method for getting "node value"
590 IMPORT_C TPtrC8 Value() const;
593 * Get copy of node's text content
594 * What is returned depends on the node type.
595 * Method caller is responsible for freeing returned string.
598 * @return the content of the node
600 IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const;
603 * Sets value of this node.
606 * @param aValue New value
608 IMPORT_C void SetValueL(const TDesC8& aValue);
611 * Check if node content is "simple text".
614 * @return Whether the value of the node is presented by only one TXmlEngTextNode node
616 * If the value is <i>"simple text"</i> then it is possible to access it as TDOMString
617 * without making copy, which combines values of all text nodes and entity reference nodes.
619 * @see TXmlEngNode::Value(), TXmlEngAttr::Value(), TXmlEngElement::Text()
621 * This method is applicable to TXmlEngElement and TXmlEngAttr nodes. On other nodes FALSE is returned.
624 * Values (contents) of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, ProcessingInstuction data are
627 * When the returned result is FALSE, getting value of the node would not returned
628 * whole contents because of either entity references present in the contents or
629 * the contents is mixed (for TXmlEngElement node). In this case WholeTextContentsCopyL()
632 * @see TXmlEngNode::WholeTextContentsCopyL()
634 IMPORT_C TBool IsSimpleTextContents() const;
637 * Use NodeType() to find out the type of the node prior to casting object
638 * of TXmlEngNode class to one of its derived subclasses (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.)
641 * @return Type of the node
643 * @see TXmlEngDOMNodeType
645 IMPORT_C TXmlEngDOMNodeType NodeType() const;
651 * @return Name of the node
653 * This method generally follows DOM spec :
654 * -------------------------------------------------------------------------------
655 * The values of nodeName, nodeValue, and attributes vary according to the node
658 * interface nodeName nodeValue attributes
659 * -------------------------------------------------------------------------------
660 * Attr = Attr.name = Attr.value = null
661 * CDATASection = "#cdata-section" = CharacterData.data = null
662 * Comment = "#comment" = CharacterData.data = null
663 * Document = "#document" = null = null
664 * DocumentFragment = "#document-fragment" = null = null
665 * DocumentType = DocumentType.name = null = null
666 * Element = Element.tagName = null = NamedNodeMap
667 * Entity = entity name = null = null
668 * EntityReference = name of entity referenced = null = null
669 * Notation = notation name = null = null
670 * ProcessingInstruction = target = data = null
671 * Text = "#text" = CharacterData.data = null
672 * -------------------------------------------------------------------------------
674 IMPORT_C TPtrC8 Name() const;
678 * Check if node has child nodes.
681 * @return True if the node is TXmlEngElement and has at least one child node
683 IMPORT_C TBool HasChildNodes() const;
686 * Check if node has attributes.
689 * @return True if the node is TXmlEngElement and has at least one attribute
691 * @note Namespace-to-prefix bindings are not attributes.
693 IMPORT_C TBool HasAttributes() const;
696 * Evaluates active base URI for the node by processing xml:base attributes of parents
699 * @return A copy of effective base URI for the node
700 * @note It's up to the caller to free the string
702 IMPORT_C void BaseUriL(RBuf8& aBaseUri) const;
707 * The nodes are the same if they are referring to the same in-memory
711 * @param aOther Node to compare
712 * @return TRUE if the same
714 inline TBool IsSameNode(TXmlEngNode aOther) const;
720 * @return Namespace URI of a node
721 * - NULL is returned for elements and attributes that do not
722 * belong to any namespace.
723 * - bound namespace URI is returned for namespace declaration nodes (instances of TXmlEngNamespace).
724 * - NULL is returned to all other types of node.
726 * @note use IsNull() and NotNull() for testing returned result on the subject
729 IMPORT_C TPtrC8 NamespaceUri() const;
732 * Get namespace prefix.
735 * @return Prefix of a node
736 * Returns NULL for elements and attributes that do not have prefix
737 * (node belongs to the default namespace or does not belong to any namespace)
738 * NULL is also returned for all types of node other than TXmlEngElement or TXmlEngAttr
740 IMPORT_C TPtrC8 Prefix() const;
743 * Check if nemespace is default for this node
746 * @param aNamespaceUri Namespace URI
747 * @return True if given namespace URI is a default one for the node (applicable to elements only)
749 * @note "" or NULL can be used to denote undefined namespace
751 IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const;
754 * Searches the prefix that is bound to the given aNamespaceUri and
755 * applicable in the scope of this TXmlEngNode.
758 * @param aNamespaceUri Namespace Uri that should be found
759 * @return A sought prefix or NULL if not found or aNamespaceUri is the default namespace
761 * @see TXmlEngElement::LookupNamespaceByUriL(const TDesC8&)
763 IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const;
766 * Searches the namespace URI that is bound to the given prefix.
769 * @param aPrefix Namespace prefix that should be found
770 * @return A sought URI or NULL if the prefix is not bound
772 * @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
774 IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const;
778 * Unlinks the internal libxml2's node from double-linked list.
779 * Relinks neighbour nodes.The node stays virtually linked to its old neighbours! Use with care!!
781 * No checks are made; nor parent's, nor node's properties updated
788 * Inserts the node in a double-linked list of nodes before specified node.
790 * No checks are made; nor parent's, nor node's properties updated (except prev/next)
793 * @param aNode Target node
795 void LinkBefore(TXmlEngNode aNode);
803 #include "xmlengnode.inl"
805 #endif /* XMLENGINE_NODE_H_INCLUDED */