#include <xml/dom/xmlengnode.h>
| class TXmlEngNode |
| Protected Attributes | |
|---|---|
| void * | iInternal |
| Public Member Enumerations | |
|---|---|
| enum | TXmlEngDOMNodeType { EElement, EAttribute, EText, ECDATASection, ..., EFileContainer } |
| Protected Member Functions | |
|---|---|
| void | DoUnlinkNode() |
| void | LinkBefore(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.
The different node types in a XML tree.
| TXmlEngNode | ( | void * | aInternal | ) | [inline] |
Constructor
| Parameter | Description |
|---|---|
| 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.
| Parameter | Description |
|---|---|
| aData | Pointer to the data object. |
Returns: ETrue if successful or EFalse if the node type does not support this operation
| 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.
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aNewChild | The node that should be added as a child |
Returns: 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)
| TXmlEngAttr & | AsAttr | ( | ) | const [inline] |
Never cast nodes to the wrong node type!
Casting removes the const'ness of the node
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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
Returns: 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.
One of the system-wide error codes
| Parameter | Description |
|---|---|
| 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.
One of the system-wide error codes
Returns: A complete copy of the node or NULL if the node is a document node
| 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.
One of the system-wide error codes
Returns: Created copy of the node after linking it into the target document tree.
| 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
Returns: The first child node or NULL if no children
| IMPORT_C void | GetChildNodes | ( | RXmlEngNodeList< TXmlEngNode > & | aList | ) | const |
Gets the list of children.
| Parameter | Description |
|---|---|
| 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.
Returns: 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.
Returns: ETrue if the node has child nodes, EFalse otherwise
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.
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aBuffer | A buffer owned by the caller that contains the result |
Returns: Length of the output buffer
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
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aNamespaceUri | Namespace URI |
Returns: ETrue if the node is an element node and its default namespace URI is the same as the given namespace URI, EFalse otherwise
| TBool | IsNull | ( | ) | const [inline] |
Check if the node is NULL
Returns: 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.
| Parameter | Description |
|---|---|
| aOther | Node to compare |
Returns: ETrue if the nodes are the same, EFalse otherwise
| 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".
See also: TXmlEngNode::Value() TXmlEngAttr::Value() TXmlEngElement::Text() TXmlEngNode::WholeTextContentsCopyL()
Returns: 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
Returns: 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.
| Parameter | Description |
|---|---|
| aNode | After insertion, this node will come before aNode in the list |
Searches for the namespace URI that is bound to the given prefix.
See also: TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aPrefix | The namespace prefix to search for |
Returns: The sought URI or NULL if the prefix is not bound
Searches for the prefix bound to the given aNamespaceUri and applicable within the scope of this node.
See also: TXmlEngElement::LookupNamespaceByUriL()
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aNamespaceUri | The Namespace URI to search for |
Returns: The sought prefix or NULL if not found or if aNamespaceUri is the default namespace
| IMPORT_C void | MoveAfterSibling | ( | TXmlEngNode | aSiblingNode | ) |
| Parameter | Description |
|---|---|
| aSiblingNode | The node is moved to fall after this sibling |
| IMPORT_C void | MoveBeforeSibling | ( | TXmlEngNode | aSiblingNode | ) |
| Parameter | Description |
|---|---|
| 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().
See also: ReconcileNamespacesL()
One of the system-wide error codes
This method has been deprecated and will be removed in a future release.
| Parameter | Description |
|---|---|
| aParent | This node will be moved to be a child of this node |
Returns: 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().
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aParent | This node will be moved to be a child of this node |
Returns: 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 -------------------------------------------------------------------------------
Returns: 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.
Returns: 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.
Returns: 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
Returns: 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.).
See also: TXmlEngDOMNodeType
Returns: The type of the node
| TBool | NotNull | ( | ) | const [inline] |
Check if node is not NULL
Returns: ETrue if node is not NULL, otherwise EFalse
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.
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aBuffer | A buffer owned by the caller that contains the result |
Returns: Length of the output buffer
| IMPORT_C RXmlEngDocument | OwnerDocument | ( | ) | const |
Gets the owning document
Note: An instance of the RXmlEngDocument class returns itself
Returns: 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
Returns: The parent node or NULL if no parent exists
| IMPORT_C TPtrC8 | Prefix | ( | ) | const |
Gets the namespace prefix.
Returns: The prefix of an element or attribute node if bound, NULL in all other cases.
| IMPORT_C TXmlEngNode | PreviousSibling | ( | ) | const |
Gets the previous sibling
Returns: 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.
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.
Returns: 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.
See also: SubstituteForL(TXmlEngNode)
DeprecatedThis method has been deprecated and will be removed in a future release.
| Parameter | Description |
|---|---|
| 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.
See also: SubstituteForL(TXmlEngNode)
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aNode | Node that replaces this node |
| IMPORT_C void | SetAsFirstSibling | ( | ) |
| IMPORT_C void | SetAsLastSibling | ( | ) |
| IMPORT_C void | SetValueL | ( | const TDesC8 & | aValue | ) |
One of the system-wide error codes
| Parameter | Description |
|---|---|
| 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.
See also: ReplaceWithL()
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aNode | Node that replaces current node |
Returns: The current node after unlinking it from document tree
| 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.
See also: ReconcileNamespacesL()
Returns: This node
| IMPORT_C MXmlEngUserData * | UserData | ( | ) | const |
Gets the user data object attached to this node. Ownership is not transferred.
Returns: 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".
Returns: 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.
One of the system-wide error codes
| Parameter | Description |
|---|---|
| aOutput | A buffer owned by the caller which holds the returned string |