1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Node class declaration
30 template<class T> class RXmlEngNodeList;
31 class RXmlEngDocument;
34 class TXmlEngTextNode;
35 class TXmlEngNamespace;
37 class TXmlEngCDATASection;
38 class TXmlEngDocumentFragment;
39 class TXmlEngEntityReference;
40 class TXmlEngProcessingInstruction;
41 class MXmlEngUserData;
42 class TXmlEngBinaryContainer;
43 class TXmlEngChunkContainer;
44 class TXmlEngDataContainer;
45 class TXmlEngFileContainer;
48 This class represents an XML node in the DOM tree.
50 As the base class for other node types (element, attribute, etc.) this class
51 implements common methods that are similar for all XML node types.
53 Sample code for tree manipulations:
55 RXmlEngDOMImplementation domImpl;
56 domImpl.OpenL(); // opening DOM implementation object
57 RXmlEngDocument iDoc; // iDoc with created nodes tree
58 TXmlEngNode tmp = iDoc.DocumentElement();
59 // copying first child of iDoc to tmp2 node and appending it
60 TXmlEngNode tmp2 = tmp.FirstChild().CopyL();
61 tmp.AppendChildL(tmp2);
62 // copying the second child of iDoc to the last child
63 tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild());
64 // replacing the second to last child with the second child
65 tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling());
66 // moving first child of iDoc to second child's children
67 tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling());
68 iDoc.Close(); // closing all opened objects
72 A node is NULL when the internal data pointer is NULL. This is the default
73 state of a newly created node. Many DOM APIs that return TXmlEngNode objects
74 use this NULL state to indicate a failure of some kind. The methods IsNull()
75 and NotNull() can be used to determine whether a node is NULL.
81 The different node types in a XML tree.
83 enum TXmlEngDOMNodeType {
91 EProcessingInstruction = 7,
96 EDocumentFragment = 11,
99 /** Extension to the DOM spec */
100 ENamespaceDeclaration = 18,
101 /** Extension to the DOM spec */
102 EBinaryContainer = 30,
103 /** Extension to the DOM spec */
104 EChunkContainer = 31,
105 /** Extension to the DOM spec */
110 /** Default constructor */
111 inline TXmlEngNode();
115 @param aInternal node pointer
117 inline TXmlEngNode(void* aInternal);
120 Check if the node is NULL
121 @return ETrue if node is NULL, otherwise EFalse
123 inline TBool IsNull() const;
126 Check if node is not NULL
127 @return ETrue if node is not NULL, otherwise EFalse
129 inline TBool NotNull() const;
132 Cast to an attribute node.
134 - Never cast nodes to the wrong node type!
135 - Casting removes the const'ness of the node
136 @return This node as an attribute node
138 inline TXmlEngAttr& AsAttr() const;
143 - Never cast nodes to the wrong node type!
144 - Casting removes the const'ness of the node
145 @return This node as a text node
147 inline TXmlEngTextNode& AsText() const;
150 Cast to a binary data container
152 - Never cast nodes to the wrong node type!
153 - Casting removes the const'ness of the node
154 @return This node as a binary container
156 inline TXmlEngBinaryContainer& AsBinaryContainer() const;
159 Cast to a memory chunk container
161 - Never cast nodes to the wrong node type!
162 - Casting removes the const'ness of the node
163 @return This node as a chunk container
165 inline TXmlEngChunkContainer& AsChunkContainer() const;
168 Cast to a file container
170 - Never cast nodes to the wrong node type!
171 - Casting removes the const'ness of the node
172 @return This node as a file container
174 inline TXmlEngFileContainer& AsFileContainer() const;
177 Cast to a memory chunk container
179 - Never cast nodes to the wrong node type!
180 - Casting removes the const'ness of the node
181 @return This node as a chunk container
183 inline TXmlEngDataContainer& AsDataContainer() const;
186 Cast to an element node.
188 - Never cast nodes to the wrong node type!
189 - Casting removes the const'ness of the node
190 @return This node as an element node
192 inline TXmlEngElement& AsElement() const;
195 Cast to a comment node.
197 - Never cast nodes to the wrong node type!
198 - Casting removes the const'ness of the node
199 @return This node as a comment node
201 inline TXmlEngComment& AsComment() const;
204 Cast to a namespace node.
206 - Never cast nodes to the wrong node type!
207 - Casting removes the const'ness of the node
208 @return This node as a namespace node
210 inline TXmlEngNamespace& AsNamespace() const;
213 Cast to a CDATA section node.
215 - Never cast nodes to the wrong node type!
216 - Casting removes the const'ness of the node
217 @return This node as a CDATA section node
219 inline TXmlEngCDATASection& AsCDATASection() const;
222 Cast to an entity reference node.
224 - Never cast nodes to the wrong node type!
225 - Casting removes the const'ness of the node
226 @return This node as an entity reference node
228 inline TXmlEngEntityReference& AsEntityReference() const;
231 Cast to a Document Fragment.
233 - Never cast nodes to the wrong node type!
234 - Casting removes the const'ness of the node
235 @return This node as a Document Fragment
237 inline TXmlEngDocumentFragment& AsDocumentFragment() const;
240 Cast to a processing instruction node.
242 - Never cast nodes to the wrong node type!
243 - Casting removes the const'ness of the node
244 @return This node as a Processing instruction node
246 inline TXmlEngProcessingInstruction& AsProcessingInstruction() const;
249 Get the inner XML string. This method returns all content of the node,
250 exluding node markup. Child nodes will be included. Any existing contents
251 in aBuffer will be destroyed. This method allocates memory for the buffer.
253 @param aBuffer A buffer owned by the caller that contains the result
254 @return Length of the output buffer
255 @leave KXmlEngErrWrongUseOfAPI Node is NULL
256 @leave - One of the system-wide error codes
258 IMPORT_C TInt InnerXmlL(RBuf8& aBuffer);
261 Get the outer XML string. This method returns all content of the node,
262 including node markup. Child nodes will be included. Any existing
263 contents in aBuffer will be destroyed. This method allocates memory for
266 @param aBuffer A buffer owned by the caller that contains the result
267 @return Length of the output buffer
268 @leave KXmlEngErrWrongUseOfAPI Node is NULL
269 @leave KXmlEngErrNegativeOutputSize Output has a negative length
270 @leave - One of the system-wide error codes
272 IMPORT_C TInt OuterXmlL(RBuf8& aBuffer);
275 Moves the node to become the first in the list of its siblings
276 @pre The node has a parent
278 IMPORT_C void SetAsFirstSibling();
281 Moves the node to become the last in the list of its siblings
282 @pre The node has a parent.
284 IMPORT_C void SetAsLastSibling();
287 Moves the node to come before the specified node in the list of sibling
288 nodes. This method does nothing if aSiblingNode is not one of the node's
290 @pre The node has a parent.
291 @param aSiblingNode The node is moved to fall before this sibling
293 IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode);
296 Moves the node to come after the specified node in the list of sibling
297 nodes. This method does nothing if aSiblingNode is not one of the node's
299 @pre The node has a parent
300 @param aSiblingNode The node is moved to fall after this sibling
302 IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode);
305 Moves the node to another part of the tree or to another document. The
306 node is unlinked from its current postion (if any) and appended to its new
309 Note: In many cases this method call should be followed by a call to
310 ReconcileNamespacesL().
312 @param aParent This node will be moved to be a child of this node
314 @leave KXmlEngErrNullNode The node is NULL
315 @leave - One of the system-wide error codes
317 inline TXmlEngNode MoveToL(TXmlEngNode aParent);
320 Moves the node to another part of the tree or to another document. The
321 node is unlinked from its current postion (if any) and appended to its new
324 Note: In many cases this method call should be followed by a call to
325 ReconcileNamespacesL().
327 @see ReconcileNamespacesL()
328 @param aParent This node will be moved to be a child of this node
330 @leave KXmlEngErrNullNode The node is NULL
331 @leave - One of the system-wide error codes
333 @deprecated This method has been deprecated and will be removed in a future
336 inline TXmlEngNode MoveTo(TXmlEngNode aParent);
339 Detaches the node from the document tree. The document maintains ownership
340 of the node until it is linked elsewhere.
342 Note: Remember to use ReconcileNamespacesL() later, if the extracted node
343 (or subtree) contains references to namespace declarations outside of the
346 @see ReconcileNamespacesL()
349 IMPORT_C TXmlEngNode Unlink();
352 Ensures that namespaces referred to in the node and its descendants are
353 within the scope of the node.
355 This method checks that all the namespaces declared within the subtree
356 parented by this node are properly declared. This is needed for example
357 after a Copy or an Unlink followed by an Append operation. The subtree may
358 still hold pointers to namespace declarations outside the subtree or they
359 may be invalid/masked. The function tries to reuse the existing namespaces
360 found in the new environment as much as possible. If not possible, the new
361 namespaces are redeclared at the top of the subtree.
363 This method should be used after unlinking nodes and inserting them into
364 another document tree or into another part of the original tree, if some
365 nodes of the subtree are removed from the scope of the namespace
366 declaration they refer to.
368 When a node is unlinked, it may still refer to namespace declarations from
369 the previous location. It is important to reconcile the subtree's
370 namespaces if the previous parent tree is to be destroyed. On the other
371 hand, if the parent tree is not changed before pasting its unlinked part
372 into another tree, then reconciliation is needed only after the paste
374 @leave - One of the system-wide error codes
376 IMPORT_C void ReconcileNamespacesL();
379 Unlinks this node and destroys it; all child nodes are also destroyed and
382 Note: Document nodes cannot be removed with this method. Use
383 RXmlEngDocument::Close() instead.
385 IMPORT_C void Remove();
388 This node is replaced with another node (or subtree). The replacement node
389 is linked into the document tree instead of this node. The replaced node
390 is destroyed. Replacement of a node with a NULL TXmlEngNode is legal and
391 equivalent to removing the node.
393 aNode is unlinked from its previous location, which can be none (i.e. not
394 linked), within the same document tree, or within another document tree.
396 Note: Not applicable to document nodes.
398 @see SubstituteForL(TXmlEngNode)
399 @param aNode Node that replaces this node
400 @leave KXmlEngErrNullNode Node is NULL
401 @leave KXmlEngErrWrongUseOfAPI Node is a document node
402 @leave - One of the system-wide error codes
404 IMPORT_C void ReplaceWithL(TXmlEngNode aNode);
407 This node is replaced with another node (or subtree). The replacement node
408 is linked into the document tree instead of this node. The replaced node
409 is destroyed. Replacement of a node with a NULL TXmlEngNode is legal and
410 equivalent to removing the node.
412 aNode is unlinked from its previous location, which can be none (i.e. not
413 linked), within the same document tree, or within another document tree.
415 Note: Not applicable to document nodes.
417 @see SubstituteForL(TXmlEngNode)
418 @param aNode Node that replaces this node
419 @deprecated This method has been deprecated and will be removed in a future
422 IMPORT_C void ReplaceWith(TXmlEngNode aNode);
425 Unlinks this node and puts another in its place. This function is the same
426 as ReplaceWithL(), but this node is not freed.
428 aNode is unlinked from its previous location, which can be none (i.e. not
429 linked), within the same document tree, or within another document tree.
431 It is possible to use a NULL TXmlEngNode object as an argument. In this
432 case, this node will simply be removed from the tree, but not freed.
434 Note: Not applicable to document nodes.
437 @param aNode Node that replaces current node
438 @return The current node after unlinking it from document tree
439 @leave KXmlEngErrNullNode Node is NULL
440 @leave KXmlEngErrWrongUseOfAPI Node is a document node
441 @leave - One of the system-wide error codes
443 IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode);
446 Retrieves the namespace declaration that applies to the node's namespace
448 Note: The DOM spec does not consider namespace declarations as a kind of
449 node. This API adds TXmlEngNamespace, which is derived from TXmlEngNode.
451 @return The namespace declaration and prefix binding that act on the node;
452 returns a NULL object if no namespace associated
454 IMPORT_C TXmlEngNamespace NamespaceDeclaration() const;
457 Attaches a user data object to this node. The ownership of the object is
458 transferred. When the node is deleted, the Destroy method of the
459 MXmlEngUserData class will be called. If there is a user data object
460 already associated with this node, it will be deleted before attaching the
463 Only TXmlEngElement and TXmlEngAttr nodes currently support this feature.
465 User data is not copied when the node is copied.
467 @param aData Pointer to the data object.
468 @return ETrue if successful or EFalse if the node type does not support this operation
470 IMPORT_C TBool AddUserData(MXmlEngUserData* aData);
473 Gets 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 object attached to this node and transfers ownership
480 to the caller. The user data object is not deleted.
481 @return Pointer to the user data object or NULL if it doesn't exist.
483 IMPORT_C MXmlEngUserData* RemoveUserData();
486 Creates a deep copy of the node. All values and children nodes are copied.
487 Attributes and namespace declarations are also copied for TXmlEngElement
488 nodes. Document nodes cannot be copied with this method. Use
489 RXmlEngDocument::CloneDocumentL() instead.
491 User data stored with AddUserData() is not copied.
493 @return A complete copy of the node or NULL if the node is a document node
494 @leave KXmlEngErrNullNode Node is NULL
495 @leave - One of the system-wide error codes
497 IMPORT_C TXmlEngNode CopyL() const;
500 Creates a deep copy of the node and appends the subtree as a new child to
501 the provided parent node. Document nodes cannot be copied with this
502 method. Use RXmlEngDocument::CloneDocumentL() instead.
504 User data stored with AddUserData() is not copied.
506 @return Created copy of the node after linking it into the target document tree.
507 @leave KXmlEngErrNullNode Node is NULL
508 @leave KXmlEngErrWrongUseOfAPI Node is document node
509 @leave - One of the system-wide error codes
511 IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const;
514 Append a child node. This is a universal operation for any type of node.
515 Note that some types of nodes cannot have children and some types of nodes
516 are not allowed to be children of some other types. These relationships
517 are not enforced by this function.
519 @param aNewChild The node that should be added as a child
520 @return The appended node, which could be changed as a result of adding it to
521 list of child nodes (e.g. text nodes can coalesce together)
522 @leave KXmlEngErrNullNode Node or aNewChild is NULL
523 @leave KErrNoMemory Memory allocation failure
524 @leave - One of the system-wide error codes
526 IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild);
529 Gets the list of children.
530 @param aList The list of children returned
532 IMPORT_C void GetChildNodes(RXmlEngNodeList<TXmlEngNode>& aList) const;
536 @return The parent node or NULL if no parent exists
538 IMPORT_C TXmlEngNode ParentNode() const;
542 @return The first child node or NULL if no children
544 IMPORT_C TXmlEngNode FirstChild() const;
548 @return The last child node or NULL if no children
550 IMPORT_C TXmlEngNode LastChild() const;
553 Gets the previous sibling
554 @return The previous sibling or NULL if there is no sibling before
556 IMPORT_C TXmlEngNode PreviousSibling() const;
559 Gets the next sibling
560 @return The next sibling or NULL if there is no sibling after
562 IMPORT_C TXmlEngNode NextSibling() const;
565 Gets the owning document
567 Note: An instance of the RXmlEngDocument class returns itself
569 @pre Node must not be NULL.
570 @return The document node of the DOM tree that this node belongs to or a
571 NULL document if no owning document.
573 IMPORT_C RXmlEngDocument OwnerDocument() const;
576 Gets the value of this node.
578 Note: Since this is not a virtual function, it is better to always cast
579 nodes to a specific type and then use the specific method for getting the
582 @return The node value
584 IMPORT_C TPtrC8 Value() const;
587 Gets a copy of the node's text content. What is returned depends on the
588 node type. Any existing content in the specified buffer is destroyed.
589 This method allocates memory for the buffer.
591 @param aOutput A buffer owned by the caller which holds the returned string
592 @leave - One of the system-wide error codes
594 IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const;
597 Copies the specified string and sets the value of this node.
598 @param aValue The value to set
599 @leave KXmlEngErrNullNode The node is NULL
600 @leave - One of the system-wide error codes
602 IMPORT_C void SetValueL(const TDesC8& aValue);
605 Check if the node content is "simple text" for element and attribute nodes.
607 If the node content is "simple text" then it is represented by a single
608 TXmlEngTextNode (or derived type). The contents can be obtained through a
609 call to Value(). A node that has multiple child text nodes does not have
610 node content that is "simple text" and the contents must be obtained
611 through a call to WholeTextContentsCopyL().
613 The contents of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, and
614 Processing Instuction data are always "simple".
616 @see TXmlEngNode::Value()
617 @see TXmlEngAttr::Value()
618 @see TXmlEngElement::Text()
619 @see TXmlEngNode::WholeTextContentsCopyL()
621 @return ETrue if the node is an element or attribute node and content is
622 represented by one TXmlEngTextNode or EFalse otherwise
624 IMPORT_C TBool IsSimpleTextContents() const;
627 Gets the node type. Used to find out the type of the node prior to casting
628 the node to one of TXmlEngNode class to one of its derived subclasses
629 (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.).
631 @see TXmlEngDOMNodeType
632 @pre Node must not be NULL
633 @return The type of the node
635 IMPORT_C TXmlEngDOMNodeType NodeType() const;
640 This method generally follows the DOM spec:
641 -------------------------------------------------------------------------------
642 The values of nodeName, nodeValue, and attributes vary according to the node
645 interface nodeName nodeValue attributes
646 -------------------------------------------------------------------------------
647 Attr = Attr.name = Attr.value = null
648 CDATASection = "#cdata-section" = CharacterData.data = null
649 Comment = "#comment" = CharacterData.data = null
650 Document = "#document" = null = null
651 DocumentFragment = "#document-fragment" = null = null
652 DocumentType = DocumentType.name = null = null
653 Element = Element.tagName = null = NamedNodeMap
654 Entity = entity name = null = null
655 EntityReference = name of entity referenced = null = null
656 Notation = notation name = null = null
657 ProcessingInstruction = target = data = null
658 Text = "#text" = CharacterData.data = null
659 -------------------------------------------------------------------------------
661 @return The name of the node
663 IMPORT_C TPtrC8 Name() const;
667 Check if the node has child nodes.
668 @return ETrue if the node has child nodes, EFalse otherwise
670 IMPORT_C TBool HasChildNodes() const;
673 Check if the node has attributes. Namespace-to-prefix bindings are not
674 considered attributes.
675 @return ETrue if the node is an Element node and has at least one
676 attribute, EFalse otherwise
678 IMPORT_C TBool HasAttributes() const;
681 Evaluates the active base URI for the node by processing the xml:base
682 attributes of the parents of the node. If no xml:base attributes exist,
683 an empty string is returned. Any existing content in the specified buffer
684 is destroyed. This function allocates memory for the buffer.
686 @param aBaseUri A buffer owned by the caller that holds the result.
687 @leave - One of the system-wide error codes
689 IMPORT_C void BaseUriL(RBuf8& aBaseUri) const;
692 Checks if a node is the same as this node. Nodes are considered the same
693 if they refer to the same in-memory data structure.
695 @param aOther Node to compare
696 @return ETrue if the nodes are the same, EFalse otherwise
698 inline TBool IsSameNode(TXmlEngNode aOther) const;
701 Gets the namespace URI.
703 @return The namespace URI of a TXmlEngNamespace, TXmlEngAttr or
704 TXmlEngElement node if bound, NULL in all other cases.
706 IMPORT_C TPtrC8 NamespaceUri() const;
709 Gets the namespace prefix.
711 @return The prefix of an element or attribute node if bound, NULL in all
714 IMPORT_C TPtrC8 Prefix() const;
717 Check if the given namespace is the same as the default namespace for this
720 Note: "" or NULL can be used to denote undefined namespace
722 @param aNamespaceUri Namespace URI
723 @return ETrue if the node is an element node and its default namespace URI is the same as the given namespace URI, EFalse otherwise
724 @leave - One of the system-wide error codes
726 IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const;
729 Searches for the prefix bound to the given aNamespaceUri and applicable
730 within the scope of this node.
732 @see TXmlEngElement::LookupNamespaceByUriL()
734 @param aNamespaceUri The Namespace URI to search for
736 @return The sought prefix or NULL if not found or if aNamespaceUri is the default namespace
737 @leave KXmlEngErrNullNode The node is NULL
738 @leave - One of the system-wide error codes
740 IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const;
743 Searches for the namespace URI that is bound to the given prefix.
745 @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
747 @param aPrefix The namespace prefix to search for
748 @return The sought URI or NULL if the prefix is not bound
749 @leave KXmlEngErrNullNode The node is NULL
750 @leave - One of the system-wide error codes
752 IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const;
756 Unlinks the node from the double-linked list and relinks any neighbour
757 nodes. Despite being removed from the list, the node retains links to its
758 old neighbours! Use with care!!
760 No checks are made. Neither the parent's, nor the node's properties are
766 Inserts this node before the specified node in the double-linked list.
768 No checks are made. Neither the parent's, nor the node's properties are
771 @param aNode After insertion, this node will come before aNode in the list
773 void LinkBefore(TXmlEngNode aNode);
781 #include <xml/dom/xmlengnode.inl>
783 #endif /* XMLENGNODE_H */