XMLParserItf Interface CATIDOMElement

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

interface CATIDOMElement

Interface representing by far the vast majority of objects nodes (apart from text) that authors encounter when traversing a document.
Assume the following XML document:

<elementExample id="demo">
<subelement1/>
<subelement2><subsubelement/></subelement2>
</elementExample>

When represented using DOM, the top node is a CATIDOMElement node for "elementExample", which contains two child CATIDOMElement nodes, one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes.

Elements may have attributes associated with them; since the CATIDOMElement interface inherits from CATIDOMNode, the generic CATIDOMNode interface method CATIDOMNode.GetAttributes may be used to retrieve the set of all attributes for an element.
There are methods on the CATIDOMElement interface to retrieve either a CATIDOMAttr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, a CATIDOMAttr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

Method Index


o GetAttribute(CATUnicodeString&,CATUnicodeString&)
Retrieves an attribute value by name.
o GetAttributeNS(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&)
Retrieves an attribute value by local name and namespace URI.
o GetAttributeNode(CATUnicodeString&,CATIDOMAttr_var&)
Retrieves a CATIDOMAttr node by name.
o GetAttributeNodeNS(CATUnicodeString&,CATUnicodeString&,CATIDOMAttr_var&)
Retrieves a CATIDOMAttr node by local name and namespace URI.
o GetElementsByTagName(CATUnicodeString&,CATIDOMNodeList_var&)
Returns a CATIDOMNodeList of all descendant elements with a given tag name.
o GetElementsByTagNameNS(CATUnicodeString&,CATUnicodeString&,CATIDOMNodeList_var&)
Returns a CATIDOMNodeList of all the CATIDOMElements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the CATIDOMDocument tree, starting from this node.
o GetTagName(CATUnicodeString&)
Retrieves the name of the element.
o HasAttribute(CATUnicodeString&,CATBoolean&)
Returns TRUE when an attribute with a given name is specified on this element or has a default value, FALSE otherwise.
o HasAttributeNS(CATUnicodeString&,CATUnicodeString&,CATBoolean&)
Returns TRUE when an attribute with a given local name and namespace URI is specified on this element or has a default value, FALSE otherwise.
o RemoveAttribute(CATUnicodeString&)
Removes an attribute by name.
o RemoveAttributeNS(CATUnicodeString&,CATUnicodeString&)
Removes an attribute by local name and namespace URI.
o RemoveAttributeNode(CATIDOMAttr_var&)
Removes the specified attribute.
o SetAttribute(CATUnicodeString&,CATUnicodeString&)
Adds a new attribute.
o SetAttributeNS(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&)
Adds a new attribute.
o SetAttributeNode(CATIDOMAttr_var&)
Adds a new attribute.
o SetAttributeNodeNS(CATIDOMAttr_var&,CATIDOMAttr_var&)
Adds a new attribute.

Methods


o GetAttribute
public virtual HRESULT GetAttribute( const CATUnicodeString& iName,
CATUnicodeString& oValue) = 0
Retrieves an attribute value by name.
Parameters:
iName
The name of the attribute to retrieve.
oValue
The
CATIDOMAttr value as a string, or the empty string if that attribute does not have a specified or default value.
o GetAttributeNS
public virtual HRESULT GetAttributeNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iLocalName,
CATUnicodeString& oValue) = 0
Retrieves an attribute value by local name and namespace URI.
Parameters:
iNamespaceURI
The namespace URI of the attribute to retrieve. When it is an empty
CATUnicodeString, this method behaves like GetAttribute.
iLocalName
The local name of the attribute to retrieve.
oValue
The
CATIDOMAttr value as a string, or an empty string if that attribute does not have a specified or default value.
o GetAttributeNode
public virtual HRESULT GetAttributeNode( const CATUnicodeString& iAttributeName,
CATIDOMAttr_var& oAttributeNode) = 0
Retrieves a CATIDOMAttr node by name.
Parameters:
iAttributeName
The name of the attribute to retrieve.
oAttributeNode
The retrieved
CATIDOMAttr node with the specified attribute name or NULL_var if there is no such attribute.
See also:
CATIDOMAttr
o GetAttributeNodeNS
public virtual HRESULT GetAttributeNodeNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iLocalName,
CATIDOMAttr_var& oAttribute) = 0
Retrieves a CATIDOMAttr node by local name and namespace URI.
Parameters:
iNamespaceURI
The namespace URI of the attribute to retrieve. When it is or an empty
CATUnicodeString, this method behaves like GetAttributeNode.
iLocalName
The local name of the attribute to retrieve.
oAttribute
The
CATIDOMAttr node with the specified attribute local name and namespace URI or NULL_var if there is no such attribute.
o GetElementsByTagName
public virtual HRESULT GetElementsByTagName( const CATUnicodeString& iElementsName,
CATIDOMNodeList_var& oListOfElements) = 0
Returns a CATIDOMNodeList of all descendant elements with a given tag name. The elements are returned in the order in which they would be encountered in a preorder traversal of the CATIDOMElement tree.
Parameters:
iElementsName
The name of the tag to match on. The special value "*" matches all tags.
oListOfElements
A list of matching
CATIDOMElement nodes.
See also:
CATIDOMNodeList
o GetElementsByTagNameNS
public virtual HRESULT GetElementsByTagNameNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iLocalName,
CATIDOMNodeList_var& oElementList)= 0
Returns a CATIDOMNodeList of all the CATIDOMElements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the CATIDOMDocument tree, starting from this node.
Parameters:
iNamespaceURI
The namespace URI of the elements to match on. The special value "*" matches all namespaces. When it is an empty
CATUnicodeString, this method behaves like GetElementsByTagName .
iLocalName
The local name of the elements to match on. The special value "*" matches all local names.
oElementList
A new
CATIDOMNodeList object containing all the matched instances of CATIDOMElement.
o GetTagName
public virtual HRESULT GetTagName(CATUnicodeString& oTagName) = 0
Retrieves the name of the element. For example, in:
<elementExample id="demo"> ... </elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM.
Parameters:
oTagName
The retrieved name of the element.
o HasAttribute
public virtual HRESULT HasAttribute( const CATUnicodeString& iName,
CATBoolean& oResult) = 0
Returns TRUE when an attribute with a given name is specified on this element or has a default value, FALSE otherwise.
Parameters:
iName
The name of the attribute to look for.
oResult
TRUE if an attribute with the given name is specified on this element or has a default value, FALSE otherwise.
o HasAttributeNS
public virtual HRESULT HasAttributeNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iLocalName,
CATBoolean& oResult) = 0
Returns TRUE when an attribute with a given local name and namespace URI is specified on this element or has a default value, FALSE otherwise. HTML-only DOM implementations do not need to implement this method.
Parameters:
iNamespaceURI
The namespace URI of the attribute to look for.
iLocalName
The local name of the attribute to look for.
oResult
TRUE if an attribute with the given local name and namespace URI is specified or has a default value on this element, FALSE otherwise.
o RemoveAttribute
public virtual HRESULT RemoveAttribute( const CATUnicodeString& iAttributeName) = 0
Removes an attribute by name. If the removed attribute has a default value it is immediately replaced.
Parameters:
iAttributeName
The name of the attribute to remove.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
o RemoveAttributeNS
public virtual HRESULT RemoveAttributeNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iLocalName) = 0
Removes an attribute by local name and namespace URI. If the removed attribute has a default value it is immediately replaced.
Parameters:
iNamespaceURI
The namespace URI of the attribute to remove. When it is an empty
CATUnicodeString, this method behaves like RemoveAttribute.
iLocalName
The local name of the attribute to remove.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
o RemoveAttributeNode
public virtual HRESULT RemoveAttributeNode( const CATIDOMAttr_var& iAttributeNodeToRemove) = 0
Removes the specified attribute.
Parameters:
iAttributeNodeToRemove
The
CATIDOMAttr node to remove from the attribute list. If the removed CATIDOMAttr has a default value it is immediately replaced.
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 iAttributeNodeToRemove is not an attribute of the element.
See also:
CATIDOMAttr
o SetAttribute
public virtual HRESULT SetAttribute( const CATUnicodeString& iAttributeName,
const CATUnicodeString& iAttributeValue) = 0
Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string, it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an CATIDOMAttr node plus any CATIDOMText and CATIDOMEntityReference nodes, build the appropriate subtree, and use SetAttributeNode to assign it as the value of an attribute.
Parameters:
iAttributeName
The name of the attribute to create or alter.
iAttributeValue
Value to set in string form.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2205 INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
See also:
CATIDOMAttr, CATIDOMText
o SetAttributeNS
public virtual HRESULT SetAttributeNS( const CATUnicodeString& iNamespaceURI,
const CATUnicodeString& iQualifiedName,
const CATUnicodeString& iValue) = 0
Adds a new attribute. If an attribute with the same local name and namespace URI is already present in the element, its prefix is changed to be that of the qualifiedName parameter, and its value is changed to be that of the value parameter. This value is a simple string, it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create a CATIDOMAttr node plus any CATIDOMText and CATIDOMEntityReference nodes, build the appropriate subtree, and use SetAttributeNodeNS or SetAttributeNode to assign it as the value of an attribute.
Parameters:
iNamespaceURI
The namespace URI of the attribute to create or alter. When it is an empty
CATUnicodeString, this method behaves like SetAttribute.
iQualifiedName
The qualified name of the attribute to create or alter.
iValue
The value to set in string form.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2205 INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
o SetAttributeNode
public virtual HRESULT SetAttributeNode( const CATIDOMAttr_var& iAttributeNode) = 0
Adds a new attribute. If an attribute with that name is already present in the element, it is replaced by the new one.
Parameters:
iAttributeNode
The
CATIDOMAttr node to add to the attribute list.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2204 WRONG_DOCUMENT_ERR: Raised if iAttributeNode was created from a different document than the one that created the element.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2210 INUSE_ATTRIBUTE_ERR: Raised if iAttributeNode is already an attribute of another CATIDOMElement object. The DOM user must explicitly clone CATIDOMAttr nodes to re-use them in other elements.
See also:
CATIDOMAttr
o SetAttributeNodeNS
public virtual HRESULT SetAttributeNodeNS( const CATIDOMAttr_var& iNewAttribute,
CATIDOMAttr_var& oPreviousAttr) = 0
Adds a new attribute. If an attribute with that local name and namespace URI is already present in the element, it is replaced by the new one.
Parameters:
iNewAttribute
The
CATIDOMAttr node to add to the attribute list. When the node has no namespaceURI, this method behaves like SetAttributeNode.
oPreviousAttr
If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the previously existing
CATIDOMAttr node is returned, otherwise NULL_var is returned.
Errors Returned:
Error Class Error Id Description
CATDOMException XMLParserERR_2204 WRONG_DOCUMENT_ERR: Raised if iNewAttribute was created from a different document than the one that created the element.
CATDOMException XMLParserERR_2207 NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
CATDOMException XMLParserERR_2210 INUSE_ATTRIBUTE_ERR: Raised if iNewAttribute is already an attribute of another CATIDOMElement object. The DOM user must explicitly clone CATIDOMAttr nodes to re-use them in other elements.
This object is included in the file: CATIDOMElement.h
If needed, your Imakefile.mk should include the module: CatXmlItfExt

Copyright © 1999-2014, Dassault Systèmes. All rights reserved.