All Frameworks  Class Hierarchy  This Framework  Previous  Next  Indexes

XMLParser Interface CATIDOMNode

System.IUnknown
  |
  +---System.IDispatch
    |
    +---System.CATBaseUnknown
      |
      +---CATIDOMNode
 

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.


interface CATIDOMNode

Interface used as the primary datatype for the entire Document Object Model.
It represents a single node in the document tree. While all objects implementing the CATIDOMNode interface expose methods for dealing with children, not all objects implementing the CATIDOMNode interface may have children. For example, CATIDOMText nodes may not have children, and adding children to such nodes results in a CATDOMException being raised.

The methods GetNodeName, GetNodeValue and GetAttributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific NodeType (e.g., GetNodeValue for an CATIDOMElement or GetAttributes for a CATIDOMComment ), this returns empty CATUnicodeString or NULL_var values. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

The return values of GetNodeName, GetNodeValue, and GetAttributes methods vary according to the node type as follows:
Interface GetNodeName GetNodeValue GetAttributes
CATIDOMAttr name of attribute value of attribute NULL_var
CATIDOMCDATASection.r "#cdata-section" content of the CDATA Section NULL_var
CATIDOMComment. content of the CDATA Section NULL_var
"#comment" content of the comment NULL_var
CATIDOMDocument.I "#document" empty CATUnicodeString NULL_var
CATIDOMDocumentFragment.td valign='top' rowspan='1' colspan='1'>NULL_var
"#document-fragment" empty CATUnicodeString NULL_var
CATIDOMDocumentType document type name empty CATUnicodeString NULL_var
CATIDOMElement tag name empty CATUnicodeString CATIDOMNamedNodeMap
CATIDOMEntity entity name empty CATUnicodeString NULL_var
CATIDOMEntityReference name of entity referenced empty CATUnicodeString NULL_var
CATIDOMNotation notation name empty CATUnicodeString NULL_var
CATIDOMProcessingInstruction target entire content excluding the target NULL_var
CATIDOMText.' "#text" content of the text node NULL_var


Method Index


o AppendChild(CATIDOMNode_var&)
Adds the node iNewChild to the end of the list of children of this node.
o CloneNode(CATBoolean,CATIDOMNode_var&)
Returns a duplicate of this node.
o GetAttributes(CATIDOMNamedNodeMap_var&)
Retrieves a CATIDOMNamedNodeMap containing the attributes of this node.
o GetChildNodes(CATIDOMNodeList_var&)
Retrieves a CATIDOMNodeList that contains all children of this node.
o GetFirstChild(CATIDOMNode_var&)
Retrieves the first child of this node.
o GetLastChild(CATIDOMNode_var&)
Retrieves the last child of this node.
o GetLocalName(CATUnicodeString&)
Retrieves the local part of the qualified name of this node.
o GetNamespaceURI(CATUnicodeString&)
Retrieves the namespace URI of this node, or an empty CATUnicodeString if it is unspecified.
o GetNextSibling(CATIDOMNode_var&)
Retrieves node immediately following this node.
o GetNodeName(CATUnicodeString&)
Retrieves the name of this node, depending on its type.
o GetNodeType(NodeType&)
Retrieves the enum value representing the type of the underlying object.
o GetNodeValue(CATUnicodeString&)
Retrieves the value of this node, depending on its type.
o GetOwnerDocument(CATIDOMDocument_var&)
Retrieves the CATIDOMDocument object associated with this node.
o GetParentNode(CATIDOMNode_var&)
Retrieves the parent of this node.
o GetPrefix(CATUnicodeString&)
Retrieves the namespace prefix of this node, or an empty CATUnicodeString if it is unspecified.
o GetPreviousSibling(CATIDOMNode_var&)
Retrieves node immediately preceding this node.
o HasAttributes(CATBoolean&)
Returns whether this node (if it is an element) has any attributes.
o HasChildNodes(CATBoolean&)
Returns whether this node has any children.
o InsertBefore(CATIDOMNode_var&,CATIDOMNode_var&)
Inserts the node iNewChild before the existing child node iRefChild.
o IsSupported(CATUnicodeString&,CATUnicodeString&,CATBoolean&)
Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
o Normalize()
Puts all CATIDOMText nodes in the full depth of the sub-tree underneath this CATIDOMNode, including attribute nodes, into a "normal" form.
o RemoveChild(CATIDOMNode_var&)
Removes the child node indicated by iOldChild from the list of children.
o ReplaceChild(CATIDOMNode_var&,CATIDOMNode_var&)
Replaces the child node iOldChild with iNewChild in the list of children.
o SetNodeValue(CATUnicodeString&)
Sets the value of the node.
o SetPrefix(CATUnicodeString&)
Sets the namespace prefix of this node.

Enumerated Type Index


o NodeType
Possible node types.

Methods


o AppendChild
public virtual HRESULT AppendChild( const CATIDOMNode_var& iNewChild) = 0
Adds the node iNewChild to the end of the list of children of this node. If the iNewChild is already in the tree, it is first removed.
Parameters:
newChild
The node to add.If it is a
CATIDOMDocumentFragment object, the entire contents of the document fragment are moved into the child list of this node
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2203 HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the iNewChild node, or if the node to append is one of this node's ancestors.
CATDOMException XMLParserERR_2204 WRONG_DOCUMENT_ERR: Raised if iNewChild was created from a different document than the one that created this node.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
See also:
CATIDOMDocumentFragment
o CloneNode
public virtual HRESULT CloneNode(CATBoolean iDeep,
CATIDOMNode_var& oNewNode) = 0
Returns a duplicate of this node. This function serves as a generic copy constructor for nodes. The duplicate node has no parent ( GetParentNode returns NULL_var.).
Cloning a CATIDOMElement copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child CATIDOMText node. Cloning any other type of node simply returns a copy of this node.
Parameters:
iDeep
If TRUE, recursively clones the subtree under the specified node; if FALSE, clones only the node itself (and its attributes, if it is an CATIDOMElement).
oNewNode
The duplicate node.
See also:
CATIDOMElement, CATIDOMText
o GetAttributes
public virtual HRESULT GetAttributes(CATIDOMNamedNodeMap_var& oAttributes) = 0
Retrieves a CATIDOMNamedNodeMap containing the attributes of this node. This method sets oAttributes to NULL_var if this node is not an CATIDOMElement.
Parameters:
oAttributes
The retrieved CATIDOMNamedNodeMap containing the attributes of this node.
See also:
CATIDOMNamedNodeMap, CATIDOMElement
o GetChildNodes
public virtual HRESULT GetChildNodes(CATIDOMNodeList_var& oChildNodes) = 0
Retrieves a CATIDOMNodeList that contains all children of this node. If there are no children, this is a CATIDOMNodeList containing no nodes. The content of the returned CATIDOMNodeList is "live" in the sense that, for instance, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the CATIDOMNodeList accessors; it is not a static snapshot of the content of the node. This is true for every CATIDOMNodeList, including the ones returned by the CATIDOMElement.GetElementsByTagName method.
Parameters:
oParentNode
The retrieved list of children of the node.
See also:
CATIDOMNodeList
o GetFirstChild
public virtual HRESULT GetFirstChild(CATIDOMNode_var& oFirstChild) = 0
Retrieves the first child of this node. If there is no such node, oFirstChild is set to NULL_var.
Parameters:
oFirstChild
The retrieved first child of this node.
o GetLastChild
public virtual HRESULT GetLastChild(CATIDOMNode_var& oLastChild) = 0
Retrieves the last child of this node. If there is no such node, oLastChild is set to NULL_var.
Parameters:
oLastChild
The retrieved last child of this node.
o GetLocalName
public virtual HRESULT GetLocalName(CATUnicodeString& oLocalName) = 0
Retrieves the local part of the qualified name of this node.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as CATIDOMDocument.CreateElement method, this is always an empty CATUnicodeString.
Parameters:
oLocalName
the local part of the qualified name of this node
o GetNamespaceURI
public virtual HRESULT GetNamespaceURI(CATUnicodeString& oNamespaceURI) = 0
Retrieves the namespace URI of this node, or an empty CATUnicodeString if it is unspecified.
This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as CATIDOMDocument.CreateElement method, this is always an empty CATUnicodeString.Per the Namespaces in XML Specification an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.
Parameters:
oNamespaceURI
the namespace URI of this node, or an empty
CATUnicodeString if it is unspecified.
o GetNextSibling
public virtual HRESULT GetNextSibling(CATIDOMNode_var& oNextSibling) = 0
Retrieves node immediately following this node. If there is no such node, oNextSibling is set to NULL_var.
Parameters:
oNextSibling
The retrieved node immediately following this node.
o GetNodeName
public virtual HRESULT GetNodeName(CATUnicodeString& oNodeName) = 0
Retrieves the name of this node, depending on its type.
Parameters:
oNodeName
The retrieved name of the node.
o GetNodeType
public virtual HRESULT GetNodeType(NodeType& oNodeType) = 0
Retrieves the enum value representing the type of the underlying object.
Parameters:
oNodeType
The retrieved type of the node.
See also:
NodeType
o GetNodeValue
public virtual HRESULT GetNodeValue(CATUnicodeString& oNodeValue) = 0
Retrieves the value of this node, depending on its type.
Parameters:
oNodeValue
The retrieved value of the node.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2202 DOMSTRING_SIZE_ERR: Raised when it would return more characters than supported by the underlying implementation.
See also:
SetNodeValue
o GetOwnerDocument
public virtual HRESULT GetOwnerDocument(CATIDOMDocument_var& oOwnerDocument) = 0
Retrieves the CATIDOMDocument object associated with this node. This is also the CATIDOMDocument object used to create new nodes. When this node is a CATIDOMDocument or a CATIDOMDocumentType, which is not used with any CATIDOMDocument yet, oOwnerDocument is set to NULL_var.
Parameters:
oOwnerDocument
The retrieved CATIDOMDocument object associated with this node.
See also:
CATIDOMDocument, CATIDOMDocumentType
o GetParentNode
public virtual HRESULT GetParentNode(CATIDOMNode_var& oParentNode) = 0
Retrieves the parent of this node. All nodes, except CATIDOMDocument, CATIDOMDocumentFragment, and CATIDOMAttr may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, a NULL_var CATIDOMNode is returned.
Parameters:
oParentNode
The retrieved parent of the node.
o GetPrefix
public virtual HRESULT GetPrefix(CATUnicodeString& oPrefix) = 0
Retrieves the namespace prefix of this node, or an empty CATUnicodeString if it is unspecified. When this node is of any type other than ELEMENT_NODE and ATTRIBUTE_NODE this is always an empty CATUnicodeString and setting it has no effect.

For nodes created with a DOM Level 1 method, such as the CATIDOMDocument.CreateElement method, this is an empty CATUnicodeString.

Parameters:
oPrefix
the namespace prefix of this node, or an empty
CATUnicodeString if it is unspecified.
o GetPreviousSibling
public virtual HRESULT GetPreviousSibling(CATIDOMNode_var& oPreviousSibling) = 0
Retrieves node immediately preceding this node. If there is no such node, oPreviousSibling is set to NULL_var.
Parameters:
oPreviousSibling
The retrieved node immediately preceding this node.
o HasAttributes
public virtual HRESULT HasAttributes(CATBoolean& oResult) = 0
Returns whether this node (if it is an element) has any attributes.
Parameters:
oResult
TRUE if this node has any attributes, FALSE otherwise.
o HasChildNodes
public virtual HRESULT HasChildNodes(CATBoolean& oHasChildren) = 0
Returns whether this node has any children. Returns TRUE if this node has any children, FALSE otherwise.
Parameters:
oHasChildren
The retrieve boolean specifying whether this node has any children.
o InsertBefore
public virtual HRESULT InsertBefore( const CATIDOMNode_var& iNewChild,
const CATIDOMNode_var& iRefChild) = 0
Inserts the node iNewChild before the existing child node iRefChild. If iRefChild equals NULL_var, inserts iNewChild at the end of the list of children.
If iNewChild is a CATIDOMDocumentFragment object, all of its children are inserted, in the same order, before iRefChild. If the iNewChild is already in the tree, it is first removed.
Parameters:
iNewChild
The node to insert.
iRefChild
The reference node, i.e., the node before which the new node must be inserted.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2203 HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the iNewChild node, or if the node to insert is one of this node's ancestors.
CATDOMException XMLParserERR_2204 WRONG_DOCUMENT_ERR: Raised if iNewChild was created from a different document than the one that created this node.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2208 NOT_FOUND_ERR: Raised if iRefChild is not a child of this node.
See also:
CATIDOMDocumentFragment
o IsSupported
public virtual HRESULT IsSupported( const CATUnicodeString& iFeature,
const CATUnicodeString& iVersion,
CATBoolean& oResult) = 0
Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
Parameters:
iFeature
name of the feature to test. This is the same name which can be passed to the method
CATIDOMImplementation.HasFeature.
iVersion
The version number of the feature to test. In Level 2, version 1, this is the string "2.0". If the version is not specified, supporting any version of the feature will cause the method to return TRUE.
oResult
TRUE if the specified feature is supported on this node, FALSE otherwise.
o Normalize
public virtual HRESULT Normalize()= 0
Puts all CATIDOMText nodes in the full depth of the sub-tree underneath this CATIDOMNode, including attribute nodes, into a "normal" form. In the normal form, only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates CATIDOMText nodes, i.e., there are neither adjacent CATIDOMText nodes nor empty CATIDOMText nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on a particular document tree structure are to be used.
See also:
CATIDOMText
o RemoveChild
public virtual HRESULT RemoveChild( const CATIDOMNode_var& iOldChild) = 0
Removes the child node indicated by iOldChild from the list of children.
Parameters:
oldChild
The node being removed.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2208 NOT_FOUND_ERR: Raised if iRefChild is not a child of this node.
o ReplaceChild
public virtual HRESULT ReplaceChild( const CATIDOMNode_var& iNewChild,
const CATIDOMNode_var& iOldChild) = 0
Replaces the child node iOldChild with iNewChild in the list of children. If the iNewChild is already in the tree, it is first removed.
Parameters:
iNewChild
The new node to put in the child list.
iOldChild
The node being replaced in the list.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2203 HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the iNewChild node, or it the node to put in is one of this node's ancestors.
CATDOMException XMLParserERR_2204 WRONG_DOCUMENT_ERR: Raised if iNewChild was created from a different document than the one that created this node.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2208 NOT_FOUND_ERR: Raised if iRefChild is not a child of this node.
o SetNodeValue
public virtual HRESULT SetNodeValue( const CATUnicodeString& iNodeValue) = 0
Sets the value of the node. Any node which can have a nodeValue will also accept requests to set it to a string. The exact response to this varies from node to node -- Attribute, for example, stores its values in its children and has to replace them with a new Text holding the replacement value. For most types of Node, value is an empty CATUnicodeString and attempting to set it will raise a CATDOMException (NO_MODIFICATION_ALLOWED_ERR). This will also be thrown if the node is read-only.
Parameters:
iNodeValue
The value to set for the node.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
CATDOMException XMLParserERR_2202 DOMSTRING_SIZE_ERR: Raised when it would return more characters than supported by the underlying implementation.
See also:
GetNodeValue
o SetPrefix
public virtual HRESULT SetPrefix( const CATUnicodeString& iPrefix) = 0
Sets the namespace prefix of this node.
Note that setting this attribute, when permitted, changes the result of the CATIDOMNode.GetNodeName method, which returns the qualified name, as well as the CATIDOMElement.GetTagName and CATIDOMAttr.GetName methods, when applicable.
Note also that changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the result of GetNamespaceURI and GetLocalName methods does not change.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as CATIDOMDocument.CreateElement method, this is always an empty CATUnicodeString.
Parameters:
iPrefix
the namespace prefix of this node
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2205 INVALID_CHARACTER_ERR: Raised if the specified prefix contains an illegal character.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2214 NAMESPACE_ERR: Raised if the specified iPrefix is malformed, if the GetNamespaceURI of this node returns an empty CATUnicodeString, if the specified prefix is "xml" and the GetNamespaceURI of this node is different from " http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the GetNamespaceURI of this node is different from " http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualified name of this node is "xmlns"

Enumerated Types


o NodeType
enum NodeType {
  ELEMENT_NODE,
  ATTRIBUTE_NODE,
  TEXT_NODE,
  CDATA_SECTION_NODE,
  ENTITY_REFERENCE_NODE,
  ENTITY_NODE,
  PROCESSING_INSTRUCTION_NODE,
  COMMENT_NODE,
  DOCUMENT_NODE,
  DOCUMENT_TYPE_NODE,
  DOCUMENT_FRAGMENT_NODE,
  NOTATION_NODE
}
Possible node types.
Parameters:
ELEMENT_NODE
The node is a
CATIDOMElement.
ATTRIBUTE_NODE
The node is a
CATIDOMAttr.
TEXT_NODE
The node is a
CATIDOMText.
CDATA_SECTION_NODE
The node is a
CATIDOMCDATASection.
ENTITY_REFERENCE_NODE
The node is a
CATIDOMEntityReference.
ENTITY_NODE
The node is a
CATIDOMEntity.
PROCESSING_INSTRUCTION_NODE
The node is a
CATIDOMProcessingInstruction.
COMMENT_NODE
The node is a
CATIDOMComment.
DOCUMENT_NODE
The node is a
CATIDOMDocument.
DOCUMENT_TYPE_NODE
The node is a
CATIDOMDocumentType.
DOCUMENT_FRAGMENT_NODE
The node is a
CATIDOMDocumentFragment.
NOTATION_NODE
The node is a
CATIDOMNotation.

This object is included in the file: CATIDOMNode.h
If needed, your Imakefile.mk should include the module: CATXMLParserItf

Copyright © 2003, Dassault Systèmes. All rights reserved.