| class TXmlEngNode |
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.
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();
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.
| Protected Member Functions | |
|---|---|
| void | DoUnlinkNode() |
| void | LinkBefore(TXmlEngNode) |
| Public Member Enumerations | |
|---|---|
| enum | TXmlEngDOMNodeType { EElement = 1, EAttribute = 2, EText = 3, ECDATASection = 4, EEntityReference = 5, EEntity = 6, EProcessingInstruction = 7, EComment = 8, EDocument = 9, EDocumentType = 10, EDocumentFragment = 11, ENotation = 12, ENamespaceDeclaration = 18, EBinaryContainer = 30, EChunkContainer = 31, EFileContainer = 32 } |
| Protected Attributes | |
|---|---|
| void * | iInternal |
| TXmlEngNode | ( | void * | aInternal | ) | [inline] |
Constructor
| void * aInternal | node pointer |
| IMPORT_C TBool | AddUserData | ( | MXmlEngUserData * | aData | ) |
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.
ETrue if successful or EFalse if the node type does not support this operation
| MXmlEngUserData * aData | Pointer to the data object. |
| IMPORT_C TXmlEngNode | AppendChildL | ( | TXmlEngNode | aNewChild | ) |
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.
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
| TXmlEngNode aNewChild | The node that should be added as a child |
| TXmlEngAttr & | AsAttr | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as an attribute node
| TXmlEngBinaryContainer & | AsBinaryContainer | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a binary container
| TXmlEngCDATASection & | AsCDATASection | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a CDATA section node
| TXmlEngChunkContainer & | AsChunkContainer | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a chunk container
| TXmlEngComment & | AsComment | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a comment node
| TXmlEngDataContainer & | AsDataContainer | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a chunk container
| TXmlEngDocumentFragment & | AsDocumentFragment | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a Document Fragment
| TXmlEngElement & | AsElement | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as an element node
| TXmlEngEntityReference & | AsEntityReference | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as an entity reference node
| TXmlEngFileContainer & | AsFileContainer | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a file container
| TXmlEngNamespace & | AsNamespace | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a namespace node
| TXmlEngProcessingInstruction & | AsProcessingInstruction | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a Processing instruction node
| TXmlEngTextNode & | AsText | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node This node as a text node
| IMPORT_C void | BaseUriL | ( | RBuf8 & | aBaseUri | ) | const |
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.
leave
One of the system-wide error codes
| RBuf8 & aBaseUri | A buffer owned by the caller that holds the result. |
| IMPORT_C TXmlEngNode | CopyL | ( | ) | const |
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.
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 | CopyToL | ( | TXmlEngNode | aParent | ) | const |
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.
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
| TXmlEngNode aParent |
| void | DoUnlinkNode | ( | ) | [protected] |
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.
| IMPORT_C TXmlEngNode | FirstChild | ( | ) | const |
Gets the first child The first child node or NULL if no children
| IMPORT_C void | GetChildNodes | ( | RXmlEngNodeList< TXmlEngNode > & | aList | ) | const |
Gets the list of children.
| RXmlEngNodeList< TXmlEngNode > & aList | The list of children returned |
| IMPORT_C TBool | HasAttributes | ( | ) | const |
Check if the node has attributes. Namespace-to-prefix bindings are not considered attributes. ETrue if the node is an Element node and has at least one attribute, EFalse otherwise
| IMPORT_C TBool | HasChildNodes | ( | ) | const |
Check if the node has child nodes. ETrue if the node has child nodes, EFalse otherwise
| IMPORT_C TInt | InnerXmlL | ( | RBuf8 & | aBuffer | ) |
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.
Length of the output buffer
leave
KXmlEngErrWrongUseOfAPI Node is NULL
leave
One of the system-wide error codes
| RBuf8 & aBuffer | A buffer owned by the caller that contains the result |
| IMPORT_C TBool | IsDefaultNamespaceL | ( | const TDesC8 & | aNamespaceUri | ) | const |
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
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
| const TDesC8 & aNamespaceUri | Namespace URI |
| TBool | IsNull | ( | ) | const [inline] |
Check if the node is NULL ETrue if node is NULL, otherwise EFalse
| TBool | IsSameNode | ( | TXmlEngNode | aOther | ) | const [inline] |
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.
ETrue if the nodes are the same, EFalse otherwise
| TXmlEngNode aOther | Node to compare |
| 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().
The contents of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, and Processing Instuction data are always "simple".
TXmlEngNode::WholeTextContentsCopyL()
ETrue if the node is an element or attribute node and content is represented by one TXmlEngTextNode or EFalse otherwise
| IMPORT_C TXmlEngNode | LastChild | ( | ) | const |
Gets the last child The last child node or NULL if no children
| void | LinkBefore | ( | TXmlEngNode | aNode | ) | [protected] |
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.
| TXmlEngNode aNode | After insertion, this node will come before aNode in the list |
| IMPORT_C TPtrC8 | LookupNamespaceUriL | ( | const TDesC8 & | aPrefix | ) | const |
Searches for the namespace URI that is bound to the given prefix.
TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
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
| const TDesC8 & aPrefix | The namespace prefix to search for |
| IMPORT_C TPtrC8 | LookupPrefixL | ( | const TDesC8 & | aNamespaceUri | ) | const |
Searches for the prefix bound to the given aNamespaceUri and applicable within the scope of this node.
TXmlEngElement::LookupNamespaceByUriL()
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
| const TDesC8 & aNamespaceUri | The Namespace URI to search for |
| IMPORT_C void | MoveAfterSibling | ( | 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. The node has a parent
| TXmlEngNode aSiblingNode | The node is moved to fall after this sibling |
| IMPORT_C void | MoveBeforeSibling | ( | TXmlEngNode | aSiblingNode | ) |
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. The node has a parent.
| TXmlEngNode aSiblingNode | The node is moved to fall before this sibling |
| TXmlEngNode | MoveTo | ( | TXmlEngNode | aParent | ) | [inline] |
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().
This node
leave
KXmlEngErrNullNode The node is NULL
leave
One of the system-wide error codes
This method has been deprecated and will be removed in a future release.
| TXmlEngNode aParent | This node will be moved to be a child of this node |
| TXmlEngNode | MoveToL | ( | TXmlEngNode | aParent | ) | [inline] |
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().
This node
leave
KXmlEngErrNullNode The node is NULL
leave
One of the system-wide error codes
| TXmlEngNode aParent | This node will be moved to be a child of this node |
| IMPORT_C TPtrC8 | Name | ( | ) | const |
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 -------------------------------------------------------------------------------
The name of the node
| 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.
The namespace declaration and prefix binding that act on the node; returns a NULL object if no namespace associated
| IMPORT_C TPtrC8 | NamespaceUri | ( | ) | const |
Gets the namespace URI.
The namespace URI of a TXmlEngNamespace, TXmlEngAttr or TXmlEngElement node if bound, NULL in all other cases.
| IMPORT_C TXmlEngNode | NextSibling | ( | ) | const |
Gets the next sibling The next sibling or NULL if there is no sibling after
| IMPORT_C TXmlEngDOMNodeType | NodeType | ( | ) | 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.).
Node must not be NULL
The type of the node
| TBool | NotNull | ( | ) | const [inline] |
Check if node is not NULL ETrue if node is not NULL, otherwise EFalse
| IMPORT_C TInt | OuterXmlL | ( | RBuf8 & | aBuffer | ) |
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.
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
| RBuf8 & aBuffer | A buffer owned by the caller that contains the result |
| IMPORT_C RXmlEngDocument | OwnerDocument | ( | ) | const |
Gets the owning document
Note: An instance of the RXmlEngDocument class returns itself
Node must not be NULL.
The document node of the DOM tree that this node belongs to or a NULL document if no owning document.
| IMPORT_C TXmlEngNode | ParentNode | ( | ) | const |
Gets the parent node The parent node or NULL if no parent exists
| IMPORT_C TPtrC8 | Prefix | ( | ) | const |
Gets the namespace prefix.
The prefix of an element or attribute node if bound, NULL in all other cases.
| IMPORT_C TXmlEngNode | PreviousSibling | ( | ) | const |
Gets the previous sibling The previous sibling or NULL if there is no sibling before
| 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 | Remove | ( | ) |
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 MXmlEngUserData * | RemoveUserData | ( | ) |
Removes the user data object attached to this node and transfers ownership to the caller. The user data object is not deleted. Pointer to the user data object or NULL if it doesn't exist.
| IMPORT_C void | ReplaceWith | ( | 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.
This method has been deprecated and will be removed in a future release.
| TXmlEngNode aNode | Node that replaces this node |
| 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.
leave
KXmlEngErrNullNode Node is NULL
leave
KXmlEngErrWrongUseOfAPI Node is a document node
leave
One of the system-wide error codes
| TXmlEngNode aNode | Node that replaces this node |
| IMPORT_C void | SetAsFirstSibling | ( | ) |
Moves the node to become the first in the list of its siblings The node has a parent
| IMPORT_C void | SetAsLastSibling | ( | ) |
Moves the node to become the last in the list of its siblings The node has a parent.
| IMPORT_C void | SetValueL | ( | const TDesC8 & | aValue | ) |
Copies the specified string and sets the value of this node. leave
KXmlEngErrNullNode The node is NULL
leave
One of the system-wide error codes
| const TDesC8 & aValue | The value to set |
| IMPORT_C TXmlEngNode | SubstituteForL | ( | TXmlEngNode | aNode | ) |
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.
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
| TXmlEngNode aNode | Node that replaces current node |
| IMPORT_C TXmlEngNode | Unlink | ( | ) |
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.
This node
| IMPORT_C MXmlEngUserData * | UserData | ( | ) | const |
Gets the user data object attached to this node. Ownership is not transferred. Pointer to data object or NULL if it doesn't exist.
| IMPORT_C TPtrC8 | Value | ( | ) | const |
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".
The node value
| IMPORT_C void | WholeTextContentsCopyL | ( | RBuf8 & | aOutput | ) | const |
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.
leave
One of the system-wide error codes
| RBuf8 & aOutput | A buffer owned by the caller which holds the returned string |
The different node types in a XML tree.
| EElement = 1 | |
| EAttribute = 2 | |
| EText = 3 | |
| ECDATASection = 4 | |
| EEntityReference = 5 | |
| EEntity = 6 |
Not supported |
| EProcessingInstruction = 7 | |
| EComment = 8 | |
| EDocument = 9 | |
| EDocumentType = 10 |
Not supported |
| EDocumentFragment = 11 | |
| ENotation = 12 |
Not supported |
| ENamespaceDeclaration = 18 |
Extension to the DOM spec |
| EBinaryContainer = 30 |
Extension to the DOM spec |
| EChunkContainer = 31 |
Extension to the DOM spec |
| EFileContainer = 32 |
Extension to the DOM spec |