--- a/epoc32/include/xmlengelement.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/xmlengelement.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,995 @@
-xmlengelement.h
+/*
+* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* which accompanies this distribution, and is available
+* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Element node functions
+*
+*/
+
+
+
+
+
+
+
+#ifndef XMLENGINE_ELEMENT_H_INCLUDED
+#define XMLENGINE_ELEMENT_H_INCLUDED
+
+#include "XmlEngAttr.h"
+#include "XmlEngNamespace.h"
+
+template<class T> class RXmlEngNodeList;
+
+
+/**
+ * Instance of TXmlEngElement class represents an XML element in the DOM tree.
+ *
+ * <b>Namespace handling:</b>
+ *
+ * Namespace of XML element is an URI that in pair with <i>local part</i> of
+ * element's name consistute <b>expanded-name</b> of element. It is said that "the element
+ * is of <i>NNN</i> namespace".
+ *
+ * XML elements are shown as belonging to a specific namespace by using <i>prefixes</i>
+ * that previously were bound to some namespace URIs. The scope of a prefix is the
+ * element, where it was declared and all its child (sub-)elements.
+ *
+ * Namespace declaration is created by using special <b>xmlns:<i>{prefix-name}</i></b>
+ * attribute (which is not really considered as attribute in DOM):
+ * @code
+ * <a xmlns:pr="http://some.uri.com/"> ... </a>
+ * OR
+ * <pr:a xmlns:pr="http://some.uri.com/"> ... </a>
+ * <a xmlns="http://some.uri.com/"> ... </a>
+ * @endcode
+ *
+ * The latter two examples are equivalent and show the use of <i>default namespace</i>.
+ *
+ * Implementation notes:
+ * - Element having no namespace is either presented with a NULL TXmlEngNamespace node
+ * or a TXmlEngNamespace node that has NULL prefix and namespace URI set to "".
+ * The former is used by default on all nodes, whereas the latter is for cases
+ * when some node contains undeclaration of the default namespace:
+ * @code
+ * <a xmlns=""> .. </a>
+ * @endcode
+ *
+ * - The prefix of the default attribute is NULL, not "" (zero-length string)
+ * "" corresponds to
+ * @code
+ * <a xmlns:="http://some.uri.com/"> ... </a>
+ * @endcode
+ * (it does not contradict XML spec, but you are strongly advised against using this)
+ *
+ * - Prefix <b>"xml"</b> is reserved by XML Namespace spec for special purposes; it is implicitly bound
+ * to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> and no one is allowed
+ * to use this prefix except as with spec-defined elements and attributes or to rebind this
+ * prefix to other namespaces
+ *
+ * - Namespace URI may be "" only for default namespace. In other words,
+ * "" namespace URI may not be bound to non-NULL prefix.
+ *
+ * Declaration of "" namespace with NULL prefix results in:
+ * @code
+ * <a xmlns=""> ... </a>
+ * @endcode
+ * which <i>undeclares</i> any existing (in some parent element) default namespace
+ * for the scope of element 'a': element, its attributes and all child nodes of DOM tree.
+ * Note, that such "undeclaration" will be added only if neccessary.
+ *
+ * - Unneccessary namespace declaration are ignored. Attemps to add namespace binding
+ * using same namespace URI and prefix if such binding already exists in the scope
+ * will have no effect.
+ *
+ * - <b>IMPORTANT!</b> Attributes DO NOT HAVE default namespaces. If an attribute has no
+ * prefix, its namespace is <b>undeclared</b> even if there is some default namespaces for
+ * the scope of the element, which contains the attribute.
+ *
+ * So, it is wrong to write something like this:
+ * @code
+ * <a xmlns="ns_uri" attr="value"> ... </a>
+ * @endcode
+ * and assume that the <b>attr</b> belongs to namespace pointed to with <i>ns_uri</i>.
+ *
+ * <b>HINTS:</b>
+ * - Use namespace declaration nodes as much as possible (but watch out prefix collisions).
+ * - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
+ * any other namespace declarations in a element -- the will be found faster in
+ * namespace lookups.
+ *
+ * @lib XmlEngineDOM.lib
+ * @since S60 v3.1
+ */
+
+class TXmlEngElement : public TXmlEngNode
+{
+ public:
+ /**
+ * Default constructor for automatic variables (not initialized)
+ *
+ * @since S60 v3.1
+ */
+ inline TXmlEngElement();
+
+ /**
+ * Constructor
+ *
+ * @since S60 v3.1
+ * @param aInternal element pointer
+ */
+ inline TXmlEngElement(void* aInternal);
+
+ /**
+ * @name XmlEngine's non-DOM extensions
+ */
+ /** @{ */
+
+ /**
+ * Retrieves list of attribute nodes of the element
+ *
+ * @param aList - 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:
+ *
+ * @code
+ * ...
+ * TXmlEngElement root = doc.DocumentElement();
+ * RXmlEngNodeList<TXmlEngAttr> attlist;
+ * root.GetAttributes(attlist);
+ * while (attlist.HasNext())
+ * processAttribute(attlist.Next());
+ * ...
+ * attlist.Close();
+ * @endcode
+ *
+ * @since S60 v3.1
+ */
+ IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;
+
+ /**
+ * Retrieves list of child elements of the element
+ *
+ * @since S60 v3.1
+ * @param aList - 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 GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const;
+
+ /**
+ * Creates new attribute node out of any namespace (i.e. it has no prefix),
+ * sets attribute's value and links it as the last attribute of the current element
+ *
+ * @since S60 v3.1
+ * @param aName A local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @return A handler to the newly created attribute node;
+ *
+ * For adding attribute as the first one, use TXmlEngNode::SetAsFirstSibling() on the attribute:
+ * @code
+ * TXmlEngElement el = ... ; // get some element
+ * el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
+ * @endcode
+ *
+ * @see SetAsLastSibling(), MoveBeforeSibling(TXmlEngNode) and MoveAfterSibling(TXmlEngNode)
+ *
+ * @note - No checks are made that attribute with such name exists
+ * Use this method only on newly created elements!
+ * Otherwise, use TXmlEngElement::SetAttributeL(..)
+ * - Attributes do not inherit default namespace of its element
+ * (http://w3.org/TR/REC-xml-names/#defaulting)
+ * - attribute's value is the second argument in all AddNewAttributeL(..) methods
+ * - Use of NULL as value is more preferrable then ""
+ */
+ IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);
+
+ /**
+ * Creates new attribute node and add it to the element
+ *
+ * Provided handle to namespace declaration is used to set up
+ * attribute's namespace.
+ *
+ * @since S60 v3.1
+ * @param aName A local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @param aNsDef Namespace to add to the attribute
+ * @return A handler to the newly created attribute node;
+ *
+ * @note If aNsDef is not defined in some of attributes ascendants
+ * (including this element), then
+ * ReconcileNamespacesL() method must be called on
+ * this element later.
+ */
+ IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
+ const TDesC8& aValue,
+ const TXmlEngNamespace aNsDef);
+
+ /**
+ * Creates new attribute on the element. Namespace declaration for the attribute namespace is
+ * created too.
+ *
+ * @since S60 v3.1
+ * @param aName A local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @param aNsUri Namespace uri
+ * @param aPrefix Namespace prefix
+ * @return A handler to the newly created attribute node;
+ *
+ * @note
+ * - Namespace declarations are reused if possible (no redundant ones are created)
+ */
+ IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
+ const TDesC8& aValue,
+ const TDesC8& aNsUri,
+ const TDesC8& aPrefix);
+
+ /**
+ * Creates new attribute node using namespace of its parent element (this element),
+ * sets attribute's value and links it as the last attribute of the element
+ *
+ * @since S60 v3.1
+ * @param aName Local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @return A handler to the newly created attribute node;
+ *
+ * For more hints how to use it refer to AddNewAttributeL(const TDesC8&,const TDesC8&)
+ *
+ * @note
+ * - No checks are made that attribute with such name exists
+ * - if namespace of the parent element is default (i.e. bound prefix is NULL),
+ * then temporary prefix will be used and bound to the same namespace URI as elements
+ * (It is due to the fact that default namespaces do not spread on unprefixed attributes,
+ * see http://w3.org/TR/REC-xml-names/#defaulting)
+ */
+ inline TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);
+
+ /**
+ * Creates new attributes using namespace, which is bound to the specified prefix
+ *
+ * @since S60 v3.1
+ * @param aLocalName A local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @param aPrefix Namespace prefix for new attribute
+ * @return A handler to the newly created attribute node;
+ *
+ * Use this mothod only for construction of new parts of DOM tree, where
+ * you know for sure that prefix is bound in the given scope.
+ * @code
+ * TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
+ * el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
+ * @endcode
+ *
+ * Otherwise, you should check that prefix is bound like this example shows:
+ * @code
+ * TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
+ * if (boundNS.NotNull()){
+ * thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
+ * }
+ * @endcode
+ *
+ * @note
+ * Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because
+ * it is most efficient way to create namespaced DOM elements (no additional
+ * lookups for namespace declarations are required).
+ *
+ * @code
+ * // If namespace with given URI is not in the scope, then it will be declared
+ * // and bound to "data" prefix.
+ * TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
+ * elem.AddNewAttributeL("location", "...", nsDef);
+ * elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
+ * // the result is
+ * ...
+ * <elem xmlns:data="http://../Data" data:location="...">
+ * <data:child attr="...value..."/>
+ * </elem>
+ * ...
+ * //
+ * @endcode
+ */
+ IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName,
+ const TDesC8& aValue,
+ const TDesC8& aPrefix);
+
+ /**
+ * Creates new attributes using namespace in the scope, which has specified URI
+ *
+ * Almost the same as AddNewAttributeUsePrefixL(...) but does lookup by namespace URI
+ *
+ * @since S60 v3.1
+ * @param aLocalName A local name of attribute
+ * @param aValue Value to set for new attribute or NULL (sets value to "")
+ * @param aNsUri Namespace uri for new attribute
+ * @return - NULL attribute if namespace declaration is not found OR newly added to the end of
+ * attribute list attribute of this element.
+ *
+ * @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
+ */
+ IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName,
+ const TDesC8& aValue,
+ const TDesC8& aNsUri);
+
+ /**
+ * Add attribute to element that will be used as Xml:Id.
+ *
+ * No check if such attribute exists are made.
+ *
+ * @since S60 v3.2
+ * @param aLocalName Name of attribute that should be add.
+ * @param aValue Value of the attribute
+ * @param aNs Namespace of the attribute
+ * @return Attribute if created. Null attribute if Id exist
+ *
+ * @note Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first
+ * to register existed id's in the document.
+ */
+ IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,
+ const TDesC8& aValue,
+ TXmlEngNamespace aNs = TXmlEngNamespace());
+
+ /**
+ * Adds child element with no namespace
+ *
+ * @since S60 v3.1
+ * @param aName name of the element
+ * @return A handler to the newly created element node;
+ *
+ * Results in adding element with aName and no prefix.
+ *
+ * This method is the best for creation of non-namespace based documents
+ * or document fragments, where no default namespace declared.
+ *
+ * It may be used also as a method for adding element from default namespace,
+ * BUT namespace will be assigned ONLY after serialization of the current
+ * document and parsing it back into a DOM tree!! If you need that default namespace
+ * was inherited by new element immediately use:
+ * @code
+ * ...
+ * TXmlEngNamespace defns = element.DefaultNamespace();
+ * TXmlEngElement newEl = element.AddNewElementL("Name",defns);
+ * ...
+ * @endcode
+ *
+ * If truly undefined namespace for the element is required, then <b>DO NOT USE</b>
+ * this method if there is a default namespace in the scope!
+ */
+ IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);
+
+ /**
+ * Creates new child element with provided name and namespace declaration
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of the element
+ * @param aNsDecl Handle of the namespace declaration, that must be retrieved from
+ * one of the ascendant nodes of the new elements (and its prefix
+ * should not be remapped to another namespace URI for the scope
+ * of the new element)
+ * @return Created element node (and added as the last child of its parent)
+ */
+ IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);
+
+ /**
+ * Creates new child element with provided name, prefix and namespace URI
+ *
+ * New namespace declaration will be attached to the parent (this) element and used
+ * as namespace for newly created child element. If such binding already exists
+ * (same prefix is bound to same URI), it will be reused. If the prefix is already
+ * bound to some another namespace URI, it will be rebound by the new namespace
+ * declaration node.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of the element
+ * @param aNsUri URI of element's namespace
+ * @param aPrefix Prefix of the element
+ * @return Created element node (and added as the last child of its parent)
+ */
+ IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName,
+ const TDesC8& aNsUri,
+ const TDesC8& aPrefix);
+
+ /**
+ * Adds child element with same namespace (and prefix if present) as parent element has
+ *
+ * @since S60 v3.1
+ * @param aLocalName element's name
+ * @return New element that was added to the end of children list of its parent (this element)
+ */
+ IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);
+
+ /**
+ * Performs lookup for the namespace declaration for specified prefix and
+ * adds new child element with found namespace.
+ *
+ * The assumption is that prefix is bound, otherwise run-time error
+ * (Symbian's Leave or exception) occurs
+ *
+ * @note Use this method only if there is a binding for the given prefix.
+ *
+ * @since S60 v3.1
+ * @param aLocalName element's name
+ * @param aPrefix prefix to use
+ * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
+ */
+ IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);
+
+ /**
+ * Performs lookup for the namespace declaration for specified namespace URI and
+ * adds new child element with found namespace.
+ *
+ * The assumption is that namespace with given URI was declared,
+ * otherwise run-time error (Symbian' Leave or exception) occurs
+ *
+ * @note Use this method only if namespace declaration for the provided URI exists.
+ *
+ * @since S60 v3.1
+ * @param aLocalName element's name
+ * @param aNsUri namespace of element
+ * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
+ */
+ IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri);
+
+ /**
+ * Creates new child element; if there is no a prefix binding for new element's namespace,
+ * a namespace decaration is created with generated prefix at specified element.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of the element to create
+ * @param aNsUri Namespace URI of the new element
+ * @param aNsDeclTarget An element where namespace declaraton should be placed
+ * if there is a needed to create new namespace declaration;
+ * NULL is used to specify the created element itself
+ *
+ * As aNsDeclTarget any ascendant of the new node may be provided:
+ * @code
+ * el.AddNewElementAutoPrefixL(tagName,uri,NULL); // declare on the new element
+ * el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element
+ * el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
+ * ...
+ * @endcode
+ *
+ * @note
+ * The farther namespace declaration up in the document tree,
+ * the longer time namespace declaration lookups take.
+ */
+ IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName,
+ const TDesC8& aNsUri,
+ TXmlEngElement aNsDeclTarget);
+
+ /**
+ * 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
+ * @return Basic contents of the element
+ *
+ * @see TXmlEngNode::WholeTextContentsCopyL()
+ */
+ IMPORT_C TPtrC8 Text() const;
+
+ /**
+ * Adds text as a child of the element.
+ *
+ * @since S60 v3.1
+ * @param aString text to be added as element's content.
+ *
+ * @note There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added actually,
+ * depending on the aString value
+ */
+ IMPORT_C void AddTextL(const TDesC8& aString);
+
+ /**
+ * Sets text contents for the element.
+ * Any child nodes are removed.
+ * Same as TXmlEngNode::SetValueL(TDesC8&)
+ *
+ * @since S60 v3.1
+ * @param aString text to be set as element's content.
+ *
+ * @see TXmlEngNode::SetValueL(TDesC8&)
+ */
+ IMPORT_C void SetTextL(const TDesC8& aString);
+
+ /**
+ * Sets text content of the element from escaped string.
+ *
+ * @since S60 v3.1
+ * @param aEscapedString New value
+ *
+ * @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
+ */
+ IMPORT_C void SetEscapedTextL(const TDesC8& aEscapedString);
+
+ /**
+ * 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
+ * @param aNotEncText New element value
+ *
+ * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
+ */
+ IMPORT_C void SetTextNoEncL(const TDesC8& aNotEncString);
+
+ /**
+ * Appends new text node with the value exactly as presented in the string.
+ * Predefined entities are not converted into characters they represent.
+ * Existing child nodes are not removed.
+ *
+ * @since S60 v3.2
+ * @param aNotEncText Appended element value
+ *
+ * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
+ */
+ IMPORT_C void AppendTextNoEncL(const TDesC8& aNotEncString);
+
+ /**
+ * Adds namespace declaration to the current element, a binding of prefix to namespace URI.
+ *
+ * If same namespace declaration exists (same prefix and URI), redundant namespace declaration
+ * will not be created.
+ *
+ * Both NULL or "" (empty string) may be used for "UNDEFINED URI" and "NO PREFIX" values of arguments.
+ *
+ * @since S60 v3.1
+ * @param aNsUri Namespace URI
+ * @param aPrefix Namespace prefix
+ * @return A handle to the created (or found, if there is such) namespace declaration node.
+ * If namespace undeclaration is being created, NULL handle is returned -- it can be
+ * used in node-creation methods that take namespace handle as an argument.
+ *
+ * @note Undeclaring of default namespace (xmlns="") is supported by
+ * SetNoDefaultNamespace() method
+ *
+ * @see SetNoDefaulNamespace()
+ *
+ * @note By adding namespace declaration that rebinds prefix mapping (or default namespace)
+ * used by nodes lower in the tree, document tree may become
+ * wrongly constructed, because references to namespace declaration are
+ * not updated. However, after serialization the document will have
+ * desired structure.
+ * Use this method with care!
+ */
+ IMPORT_C TXmlEngNamespace AddNamespaceDeclarationL(const TDesC8& aNsUri, const TDesC8& aPrefix);
+
+ /**
+ * Adds default namespace declaration.
+ *
+ * @since S60 v3.1
+ * @param aNsUri Namespace URI; both NULL and "" (empty string) are allowed to represent UNDEFINED NAMSPACE
+ * @return 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 TXmlEngNamespace SetDefaultNamespaceL(const TDesC8& aNsUri);
+
+ /**
+ * Undeclares any default namespace for current element and its descendants.
+ *
+ * If there is already some default namespace, <i>xmlns=""</i> 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 <b>default</b> 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 <i>xmlns=""</i> 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)
+ *
+ * @note
+ * 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
+ */
+ IMPORT_C void SetNoDefaultNamespaceL();
+
+ /**
+ * 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
+ * @param aPrefix Namespace prefix
+ * @return 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 LookupNamespaceByPrefixL(const TDesC8& aPrefix) const;
+
+ /**
+ * Finds namespace declaration that has specific namespace URI
+ * in the scope for the given node.
+ *
+ * @since S60 v3.1
+ * @param aUri Namespace URI, for which namespace declaration is searched
+ * @return 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).
+ *
+ * <b>Hint:</b><p>
+ * 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).<br />
+ * <span class="color:red;">However</span>, 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:
+ * @code
+ * 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);
+ * ...
+ * @endcode
+ *
+ * The sought result was (showing expanded names of elements):
+ * @code
+ * --> "root"
+ * --> {"http://example.com/","outer"}
+ * --> "inner"
+ * -->{"http://example.com/","problem"}
+ * ...
+ * <--
+ * <-- "inner"
+ * <-- {"http://example.com/","outer"}
+ * ...
+ * <-- </root>
+ * @endcode
+ * 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:
+ * @code
+ * <root>
+ * <ex:outer xmlns:ex="http://example.com/">
+ * <inner xmlns:ex="http://whatever.com/">
+ * <ex:problem>
+ * ...
+ * </ex:problem>
+ * </inner>
+ * </ex:outer>
+ * ...
+ * </root>
+ * @endcode
+ *
+ * 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:
+ * @code
+ * 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);
+ * ...
+ * }
+ * @endcode
+ */
+ IMPORT_C TXmlEngNamespace LookupNamespaceByUriL(const TDesC8& aUri) const;
+
+ /**
+ * Retrieves implicitly declared on every XML infoset binding
+ * of 'xml' prefix to XML's namespace URI:
+ * "http://www.w3.org/XML/1998/namespace"
+ *
+ * @since S60 v3.1
+ * @return Handler to {xml,"http://www.w3.org/XML/1998/namespace"} prefix
+ * binding in the current document
+ *
+ * The result should be used for creating attributes beloging to the XML namespace
+ * (xml:lang, xml:space, xml:id , etc.)
+ *
+ * DO NOT USE methods LookupNamespaceByUriL(const TDesC8&) and LookupNamespaceByPrefixL(const TDesC8&)
+ * (with "http://www.w3.org/XML/1998/namespace" and "xml" arguments) for retrieving
+ * namespace node, since in a case of [possible] memory allocation fault
+ * NULL result is returned (and breaks your program silently)
+ *
+ * @note Normally 'xml' prefix is bound to XML namespace URI in the document
+ * node, BUT if current node is not a part of the document tree yet,
+ * the requested namespace declaration WILL BE ADDED to the current node.
+ * This is the reason why the method may fail in OOM conditions.
+ */
+ IMPORT_C TXmlEngNamespace TheXMLNamespaceL() const;
+
+ /**
+ * Get default namespace for element.
+ *
+ * @since S60 v3.1
+ * @return Default namespace in the scope of the element
+ *
+ * NULL TXmlEngNamespace means that element with no prefix have no namespace associated
+ * because no default namespace was declared or default namespace was undeclared with <b>xmlns=""</b>
+ *
+ * Equivalent to LookupNamespaceByPrefixL(const TDesC8&) with NULL (or "") prefix provided
+ */
+ inline TXmlEngNamespace DefaultNamespaceL() const;
+
+ /**
+ * Performs search of namespace handler in the scope of the element. This method will
+ * create new namespace declaration on the element if such namespace is not available.
+ *
+ * @since S60 v3.1
+ * @param aNsUri Searched namespace
+ * @param aPrefix Prefix to use for <b>new</b> namespace declaration (if it is to be created)
+ * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
+ * the element. The namespace may be one of those existed previously or was created
+ *
+ * @note
+ * Be sure not to use the result of this method for non-descendants of the element or in situations
+ * when prefix overlapping might occur (read also about general general considerations of attributes
+ * and elements creation using namespace handlers)
+ */
+ IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri, const TDesC8& aPrefix);
+
+ /**
+ * Performs search on the element and its ascendants for any namespace declaration
+ * with given URI and create a new namespace declaration with some (unique) prefix
+ * if the search was not successful.
+ *
+ * @since S60 v3.1
+ * @param aNsUri Searched namespace
+ * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
+ * the element. The namespace may be one of those existed previously or was created
+ */
+ IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri);
+
+ /**
+ * 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
+ * @param aPrefix Namespace prefix
+ * @return TRUE if there is already namespace declaration that uses aPrefix on this element
+ */
+ IMPORT_C TBool HasNsDeclarationForPrefixL(const TDesC8& aPrefix) const;
+
+ /**
+ * Copies the element with its attributes, but not child nodes
+ *
+ * If context is preserved, then all namespace declarations that are in the element are
+ * writen to element's start tag too.
+ *
+ * @since S60 v3.1
+ * @param preserveNsContext TRUE if context should be preserved
+ * @return handle to copy of element
+ */
+ IMPORT_C TXmlEngElement ElementCopyNoChildrenL(TBool preserveNsContext) const;
+
+ /**
+ * Specialized version of TXmlEngNode::CopyL()
+ *
+ * @since S60 v3.1
+ * @return Deep copy of the element.
+ */
+ inline TXmlEngElement CopyL() const;
+
+ /**
+ * Resets element's content: all child nodes are removed
+ *
+ * @since S60 v3.1
+ */
+ IMPORT_C void RemoveChildren();
+
+ /**
+ * Resets element's attributes
+ *
+ * @since S60 v3.1
+ */
+ IMPORT_C void RemoveAttributes();
+
+ /**
+ * 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 RemoveNamespaceDeclarations();
+
+ /**
+ * Removes all element contents: child nodes, attributes and namespace declarations
+ *
+ * @see RemoveChildren(), RemoveAttributes(), RemoveNamespaceDeclarations();
+ *
+ * @since S60 v3.1
+ */
+ inline void ClearElement();
+
+ /**
+ * Copies attributes from another element
+ *
+ * It may be a very convenient method for initializing element with a set of predefined attributes.
+ *
+ * @since S60 v3.1
+ * @param aSrc source element
+ *
+ * @note
+ * Namespaces of the this element may need to be reconciled if copied attributes
+ * belong to any namespace that is not declared on some ascendant of this node.
+ * @see ReconcileNamespacesL()
+ */
+ IMPORT_C void CopyAttributesL(TXmlEngElement aSrc);
+
+ /**
+ * Copies a list of elements.
+ *
+ * Elements are appended to the element's children list.
+ *
+ * @since S60 v3.1
+ * @param aSrc source element
+ *
+ * @note Namespaces of the this element may need to be reconciled after copy operation
+ * @see ReconcileNamespacesL()
+ */
+ IMPORT_C void CopyChildrenL(TXmlEngElement aSrc);
+
+ /**
+ * Removes attribute with given name and namespace URI(if such exists).
+ * Memory allocated for the attribute is freed.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Element name
+ * @param aNamespaceUri Element namespace
+ */
+ IMPORT_C void RemoveChildElementsL(const TDesC8& aLocalName,const TDesC8& aNamespaceUri);
+
+ /** @} */
+
+ /**
+ * @name DOM Level 3 Core methods
+ *
+ * @note
+ * Most methods of DOM spec operate with fully-qualified names (QNames)
+ * of elements and attributes. It is different in this API - all methods
+ * instead accept prefix and localName parts of QName.
+ */
+ /** @{ */
+
+ /**
+ * Returns value of attribute with given name and namespace URI
+ *
+ * @since S60 v3.1
+ * @param aLocalName Local name of attribute node
+ * @param aNamespaceUri Namespace URI of attribute
+ * @return Attribute value
+ */
+ IMPORT_C TPtrC8 AttributeValueL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8) const;
+
+ /**
+ * Initializes list of child elements with matching name and namespace URI.
+ *
+ * @since S60 v3.1
+ * @param aList Node list to be initialized
+ * @param aLocalName Element name
+ * @param aNamespaceUri Namespace URI, default is NULL
+ *
+ * @note This method does not lists all descedants of the element, only child elements
+ */
+ IMPORT_C void GetElementsByTagNameL(RXmlEngNodeList<TXmlEngElement>& aList,
+ const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8) const;
+
+ /**
+ * Sets value of attribute; attribute is created if there is no such attribute yet
+ *
+ * @since S60 v3.1
+ * @param aLocalName Attribute name
+ * @param aValue Attribute value
+ * @param aNamespaceUri Namespace URI - default is NULL
+ * @param 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)
+ */
+ IMPORT_C void SetAttributeL(const TDesC8& aLocalName,
+ const TDesC8& aValue,
+ const TDesC8& aNamespaceUri = KNullDesC8,
+ const TDesC8& aPrefix = KNullDesC8);
+
+ /**
+ * Removes attribute with given name and namespace URI(if such exists).
+ * Memory allocated for the attribute is freed.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of the attribute
+ * @param aNamespaceUri Attribute namespace URI, default is NULL
+ */
+ IMPORT_C void RemoveAttributeL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8);
+
+ /**
+ * Retrieves attribute node from specific namespace by its name.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of the attribute
+ * @param aNamespaceUri Attribute namespace URI, default is NULL
+ * @return Attribute node with matching namespace URI and name
+ */
+ IMPORT_C TXmlEngAttr AttributeNodeL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8) const;
+
+ /**
+ * Check if element has attribute with given parameters.
+ *
+ * @since S60 v3.1
+ * @param aLocalName Name of attribute
+ * @param aNamespaceUri Namespace uri, default is NULL.
+ * @return TRUE if the element holds an attribute with such namespace URI and name.
+ *
+ * Same result gives AttributeNodeL(uri,name).NotNull()
+ */
+ inline TBool HasAttributeL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8) const;
+
+ /**
+ * Links attribute into tree
+ *
+ * @since S60 v3.1
+ * @param aNewAttr new attribute
+ *
+ * The replaced attribute node is not returned and just deleted
+ */
+ IMPORT_C void SetAttributeNodeL(TXmlEngAttr aNewAttr);
+};
+
+
+
+#include "xmlengelement.inl"
+
+#endif /* XMLENGINE_ELEMENT_H_INCLUDED */