TXmlEngElement Class Reference

RXmlEngNodeList< TXmlEngAttr > &

Retrieves list of attribute nodes of the element.

Parameters:

- a node list object to initialize

Passed by reference list of nodes is initialized and after call to Attributes(..) is ready for use with HasNext() and Next() methods:

       ...
       TXmlEngElement root = doc.DocumentElement();
       RXmlEngNodeList<TXmlEngAttr>    attlist;
       root.GetAttributes(attlist);
       while (attlist.HasNext())
           processAttribute(attlist.Next());
       ...
       attlist.Close();

Since:: S60 v3.1

IMPORT_C void TXmlEngElement::GetChildElements

RXmlEngNodeList< TXmlEngElement > &

Retrieves list of child elements of the element.

Since:: S60 v3.1

Parameters:

- a node list object to initialize

Passed by reference list of nodes is initialized and after the call it is ready for use with HasNext() and Next() methods:

Note:: Returned list is a "filtered view" of the underlying list of all element's children (with text nodes, comments processing instructions, etc.)

IMPORT_C void TXmlEngElement::GetElementsByTagNameL	(	RXmlEngNodeList< TXmlEngElement > &	aList,
		const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`
	)	const

Initializes list of child elements with matching name and namespace URI.

Since:: S60 v3.1

Parameters:

	aList	Node list to be initialized
	aLocalName	Element name
	aNamespaceUri	Namespace URI, default is NULL

Note:: This method does not lists all descedants of the element, only child elements

TBool TXmlEngElement::HasAttributeL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`
	)	const `[inline]`

Check if element has attribute with given parameters.

Since:: S60 v3.1

Parameters:

	aLocalName	Name of attribute
	aNamespaceUri	Namespace uri, default is NULL.

Returns:: TRUE if the element holds an attribute with such namespace URI and name.

Same result gives AttributeNodeL(uri,name).NotNull()

IMPORT_C TBool TXmlEngElement::HasNsDeclarationForPrefixL

Checks whether a prefix has been bound in this element (not in one of its ascendants).

Use this method for preventig prefix-name collision in a element node

Since:: S60 v3.1

Parameters:

aPrefix

Namespace prefix

Returns:: TRUE if there is already namespace declaration that uses aPrefix on this element

IMPORT_C TXmlEngNamespace TXmlEngElement::LookupNamespaceByPrefixL

Finds namespace declaration that has specific prefix in the scope for given node.

Prefix "" or NULL are considered the same, meaning "<b>NO PREFIX</b>". If namespace declaration for "no prefix" is searched, then default namespace is returned.

Since:: S60 v3.1

Parameters:

aPrefix

Namespace prefix

Returns:: Namespace handler, which may be NULL if prefix is not bound.

NULL result for "no prefix" means that default namespace is undefined.

IMPORT_C TXmlEngNamespace TXmlEngElement::LookupNamespaceByUriL

Finds namespace declaration that has specific namespace URI in the scope for the given node.

Since:: S60 v3.1

Parameters:

aUri

Namespace URI, for which namespace declaration is searched

Returns:: Handler to the namespace declaration that binds given namespace URI to some prefix or sets it a default namespace.

NULL value of aUri is equivalent to "" and means "<b>UNDEFINED NAMESPACE</b>". For such URI a NULL namespace handle is always returned even if there is namespace undeclaration, which has "" URI (and NULL prefix).

Hint:

Use returned instance of TXmlEngNamespace as aNsDef argument to element's methods that create new element's child elements and attributes. The same handler may be used on more deep descentants of the reference element (and doing this way will generally increase performance of DOM tree construction).
However, if namespace bindings are not controlled for element's children and prefix, which is bound to the search namespace, is rebound to some other namespace URI, then reusing namespace may lead to unwanted result.

Consider an example:

     TXmlEngElement root = doc.DocumentElement();
     TXmlEngNamespace targetNs = root.AddNamespaceDeclarationL("http://example.com/","ex");
     TXmlEngElement el_1 = root.AddNewElementL("outer", targetNs);
     TXmlEngElement el_2 = el_1.AddNewElementL("inner"); // element without prefix
 
     // NOTE: prefix "ex" is not bound to "http://example.com/" anymore!
     el_2.AddNamespaceDeclarationL("http://whatever.com/","ex");
     TXmlEngElement el_3 = el_2.AddNewElementL("problem", targetNs);
     ...

The sought result was (showing expanded names of elements):

     --> "root"
         --> {"http://example.com/","outer"}
         --> "inner"
             -->{"http://example.com/","problem"}
                 ...
             <--
         <-- "inner"
         <-- {"http://example.com/","outer"}
         ...
     <-- </root>

and it may look that it has been achieved. Indeed, if namespace of element "problem" was queried, it would have URI "http://example.com/" and prefix "ex". However, if namespace URI was looked up by "problem"'s prefix, it would be "http://whatever.com/". We have created illegal DOM tree.

The actual DOM tree in serialized form will be:

     <root>
         <ex:outer xmlns:ex="http://example.com/">
             <inner xmlns:ex="http://whatever.com/">
                 <ex:problem>
                 ...
                 </ex:problem>
             </inner>
         </ex:outer>
         ...
     </root>

So, reuse of namespace handlers should be performed with special care.

Note:

At the moment it is possible to retrieve namespace declaration nodes whose prefixes were rebound. Be careful when use returned TXmlEngNamespace object for creation of new elements. In later releases, this method will perform safe lookup. And so far, it is better to make check that prefix of returned namespace declaration has not rebound:

     TXmlEngNamespace ns = element.LookupNamespaceByUri("a_uri");
     if (element.LookupNamespaceByPrefix(ns.Prefix()).IsSameNode(ns)){
         ... // now it is safe to create new elements by using "ns"
         element.AddNewElementL("product",ns);
         ...
     }

IMPORT_C void TXmlEngElement::RemoveAttributeL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`
	)

Removes attribute with given name and namespace URI(if such exists).

Memory allocated for the attribute is freed.

Since:: S60 v3.1

Parameters:

	aLocalName	Name of the attribute
	aNamespaceUri	Attribute namespace URI, default is NULL

IMPORT_C void TXmlEngElement::RemoveAttributes

IMPORT_C void TXmlEngElement::RemoveChildren

Resets element's attributes.

Since:: S60 v3.1

IMPORT_C void TXmlEngElement::RemoveChildElementsL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri
	)

Removes attribute with given name and namespace URI(if such exists).

Memory allocated for the attribute is freed.

Since:: S60 v3.1

Parameters:

	aLocalName	Element name
	aNamespaceUri	Element namespace

IMPORT_C void TXmlEngElement::RemoveNamespaceDeclarations

Resets element's content: all child nodes are removed.

Since:: S60 v3.1

IMPORT_C void TXmlEngElement::SetAttributeNodeL

Resets all namespace declarations made in the element.

Note:: There can be references to these namespace declaration from elsewhere! Use ReconcileNamespacesL() to fix that.

Since:: S60 v3.1

IMPORT_C void TXmlEngElement::SetAttributeL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aValue,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`,
		const TDesC8 &	aPrefix = `KNullDesC8`
	)

Sets value of attribute; attribute is created if there is no such attribute yet.

Since:: S60 v3.1

Parameters:

	aLocalName	Attribute name
	aValue	Attribute value
	aNamespaceUri	Namespace URI - default is NULL
	aPrefix	Namespace prefix - default is NULL

Note:: If prefix is not NULL (or ""), then namespace URI may not be empty see http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)

Links attribute into tree.

Since:: S60 v3.1

Parameters:

aNewAttr

new attribute

The replaced attribute node is not returned and just deleted

IMPORT_C TXmlEngNamespace TXmlEngElement::SetDefaultNamespaceL

Adds default namespace declaration.

Since:: S60 v3.1

Parameters:

aNsUri

Namespace URI; both NULL and "" (empty string) are allowed to represent UNDEFINED NAMSPACE

Returns:: Handle to the created namespace declaration (NULL for UNDEFINED NAMESPACE)

Same result as with AddNamespaceDeclarationL(aNsUri, NULL), but additionally element's namespace modified (if it has no prefix and there were no default namespace declaration in the scope) to the new default one.

IMPORT_C void TXmlEngElement::SetEscapedTextL

Sets text content of the element from escaped string.

Since:: S60 v3.1

Parameters:

aEscapedString

New value

See also:: TXmlEngAttr::SetEscapedValueL(TDesC8&)

IMPORT_C void TXmlEngElement::SetNoDefaultNamespaceL

IMPORT_C void TXmlEngElement::SetTextL

Undeclares any default namespace for current element and its descendants.

If there is already some default namespace, xmlns="" namespace declaration is added. Otherwise, nothing happens, since element with no prefix in such scope is automaticaly considered as out of any namespace.

The side effect of this method is that namespace of the current element may change from previous default namespace to NULL TXmlEngNamespace, which is considered an absence of namespace.

If the element has prefix (i.e. not having default namespace), then the only effect for the element is undeclaration of existing default namespace.

If element is in the scope of another xmlns="" undeclaration, no actions are taken.

Note:: Use AddNamespaceDeclarationL(NULL,NULL) to force creation of xmlns="" declaration within scope of another such declaration (otherwise unneccessary/duplicate declarations are not created)
This method should be called on elements before adding children, because default namespace undeclaration is not spread into its subtree and descedants' default namespaces are not reset to NULL. This should be taken into account if later some processing on the subtree occurs. However, after serialization and deserialization, undeclared default namespace will affect whole element's subtree correctly.

Since:: S60 v3.1

Sets text contents for the element.

Any child nodes are removed. Same as TXmlEngNode::SetValueL(TDesC8&)

Since:: S60 v3.1

Parameters:

aString

text to be set as element's content.

See also:: TXmlEngNode::SetValueL(TDesC8&)

IMPORT_C void TXmlEngElement::SetTextNoEncL

Sets new element value exactly as presented in the string.

Predefined entities are not converted into characters they represent. Any child nodes are removed.

Since:: S60 v3.2

Parameters:

aNotEncText

New element value

See also:: TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);

IMPORT_C TPtrC8 TXmlEngElement::Text

IMPORT_C TXmlEngNamespace TXmlEngElement::TheXMLNamespaceL

Get element content.

This method may be used in most cases, when element has only simple text content (without entity references embedded). If element's contents is mixed (other types of nodes present), only contents of first child node is returned if it is a TXmlEngTextNode node. For getting mixed contents of the element of contents with entity references, WholeTextValueCopyL() should be used.

Since:: S60 v3.1

Returns:: Basic contents of the element

See also:: TXmlEngNode::WholeTextContentsCopyL()