API_REF/Public_API: comparison epoc32/include/xml/dom/xmlengelement.h

equal deleted inserted replaced

-:e1b950c65cb4
+:837f303aceeb
 /*
-* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
+* Copyright (c) 2008 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
+* under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
-* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *
 * Initial Contributors:
 * Nokia Corporation - initial contribution.
 *
 * Contributors:
 *
-* Description:       Element node functions
+* Description:
 *
 */
+/** @file
+@publishedAll
+@released
+*/
+#ifndef XMLENGELEMENT_H
+#define XMLENGELEMENT_H
-#ifndef XMLENGINE_ELEMENT_H_INCLUDED
-#define XMLENGINE_ELEMENT_H_INCLUDED
+#include <xml/dom/xmlengattr.h>
+#include <xml/dom/xmlengnamespace.h>
-#include "XmlEngAttr.h"
-#include "XmlEngNamespace.h"
 template<class T> class RXmlEngNodeList;
 /**
-* Instance of TXmlEngElement class represents an XML element in the DOM tree.
+This class represents an XML element in the DOM tree.
-*
-* <b>Namespace handling:</b>
+Namespace handling:
-*
-* Namespace of XML element is an URI that in pair with <i>local part</i> of
+The namespace of a XML element is an URI that in pair with the local part of
-* element's name consistute <b>expanded-name</b> of element. It is said that "the element
+the element's name consistute the @c expanded-name of the element. It is said
-* is of <i>NNN</i> namespace".
+that "the element is of NNN namespace".
-*
-* XML elements are shown as belonging to a specific namespace by using <i>prefixes</i>
+XML elements are shown as belonging to a specific namespace by using prefixes
-* that previously were bound to some namespace URIs. The scope of a prefix is the
+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.
+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>
+Namespace declaration is created by using a special @c xmlns:{prefix-name}
-* attribute (which is not really considered as attribute in DOM):
+attribute (which is not really considered as an attribute in DOM):
-* @code
+@code
-*    <a xmlns:pr="http://some.uri.com/"> ... </a>
+<a xmlns:pr="http://some.uri.com/"> ... </a>
-* OR
+OR
-*    <pr:a xmlns:pr="http://some.uri.com/"> ... </a>
+<pr:a xmlns:pr="http://some.uri.com/"> ... </a>
-*    <a xmlns="http://some.uri.com/"> ... </a>
+<a xmlns="http://some.uri.com/"> ... </a>
-* @endcode
+@endcode
-*
-* The latter two examples are equivalent and show the use of <i>default namespace</i>.
+The latter two examples are equivalent and show the use of @c default namespace.
-*
-* Implementation notes:
+Implementation notes:
-*	- Element having no namespace is either presented with a NULL TXmlEngNamespace node
+- Elements having no namespace are either presented with a NULL
-*    or a TXmlEngNamespace node that has NULL prefix and namespace URI set to "".
+TXmlEngNamespace node or a TXmlEngNamespace node that has NULL (KNullDesC8)
-*    The former is used by default on all nodes, whereas the latter is for cases
+prefix and namespace URI set to "" (an empty descriptor).  The former is
-*    when some node contains undeclaration of the default namespace:
+	used by default on all nodes, whereas the latter is for cases when some node
-* @code
+	contains undeclaration of the default namespace:
-*	   <a xmlns=""> .. </a>
+@code
-* @endcode
+	   <a xmlns=""> .. </a>
-*
+@endcode
-* - The prefix of the default attribute is NULL, not "" (zero-length string)
-*	 "" corresponds to
+- The prefix of the default attribute is NULL (KNullDesC8), not an "" (empty
-*   @code
+	descriptor).  An empty descriptor which corresponds to
-*       <a xmlns:="http://some.uri.com/"> ... </a>
+@code
-*   @endcode
+<a xmlns:="http://some.uri.com/"> ... </a>
-*   (it does not contradict XML spec, but you are strongly advised against using this)
+@endcode
-*
+(it does not contradict XML spec, but you are strongly advised against using
-* - Prefix <b>"xml"</b> is reserved by XML Namespace spec for special purposes; it is implicitly bound
+this)
-*   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 "xml" is reserved by XML Namespace spec for special purposes; it is
-*   prefix to other namespaces
+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
-* - Namespace URI may be "" only for default namespace. In other words,
+elements and attributes or to rebind this prefix to other namespaces
-*   "" namespace URI may not be bound to non-NULL prefix.
-*
+- Namespace URI may be "" (an empty descriptor) only for default namespace. In
-*   Declaration of "" namespace with NULL prefix results in:
+other words, "" namespace URI may not be bound to non-NULL prefix.
-*   @code
-*       <a xmlns=""> ... </a>
+Declaration of "" (an empty descriptor) namespace with NULL (KNullDesC8)
-*   @endcode
+prefix results in:
-*   which <i>undeclares</i> any existing (in some parent element) default namespace
+@code
-*   for the scope of element 'a': element, its attributes and all child nodes of DOM tree.
+<a xmlns=""> ... </a>
-*   Note, that such "undeclaration" will be added only if neccessary.
+@endcode
-*
+which undeclares any existing (in some parent element) default namespace
-* - Unneccessary namespace declaration are ignored. Attemps to add namespace binding
+for the scope of element 'a': element, its attributes and all child nodes
-*   using same namespace URI and prefix if such binding already exists in the scope
+of DOM tree. Note, that such "undeclaration" will be added only if neccessary.
-*   will have no effect.
-*
+- Unneccessary namespace declaration are ignored. Attemps to add namespace binding
-* - <b>IMPORTANT!</b> Attributes DO NOT HAVE default namespaces. If an attribute has no
+using same namespace URI and prefix if such binding already exists in the scope
-*   prefix, its namespace is <b>undeclared</b> even if there is some default namespaces for
+will have no effect.
-*   the scope of the element, which contains the attribute.
-*
+- IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no
-* So, it is wrong to write something like this:
+prefix, its namespace is undeclared even if there is some default namespaces for
-* @code
+the scope of the element, which contains the attribute.
-*     <a xmlns="ns_uri"  attr="value"> ... </a>
-* @endcode
+So, it is wrong to write something like this:
-* and assume that the <b>attr</b> belongs to namespace pointed to with <i>ns_uri</i>.
+@code
-*
+<a xmlns="ns_uri"  attr="value"> ... </a>
-* <b>HINTS:</b>
+@endcode
-* - Use namespace declaration nodes as much as possible (but watch out prefix collisions).
+and assume that the attr belongs to namespace pointed to with @c ns_uri.
-* - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
-*   any other namespace declarations in a element -- the will be found faster in
+HINTS:
-*   namespace lookups.
+- Use namespace declaration nodes as much as possible (but watch out for prefix collisions).
-*
+- Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
-* @lib XmlEngineDOM.lib
+any other namespace declarations in a element -- they will be found faster in
-* @since S60 v3.1
+namespace lookups.
-*/
+For more informarion on NULL and NULL nodes:
+@see TXmlEngNode
+@see KNullDesC8
+*/
 class TXmlEngElement : public TXmlEngNode
 {
 public:
-/**
+/** Default constructor */
-* Default constructor for automatic variables (not initialized)
-	 *
-* @since S60 v3.1
-	 */
 inline TXmlEngElement();
 /**
-* Constructor
+Constructor
-*
+	@param aInternal element pointer
-* @since S60 v3.1
+	*/
-	 * @param aInternal element pointer
-	 */
 inline TXmlEngElement(void* aInternal);
-/**
+/*
-*    @name XmlEngine's non-DOM extensions
+	Extensions to the DOM Level 3 Core methods
-*/
+	*/
-/** @{ */
+/**
-/**
+Retrieves a list of the attribute nodes of an element
-*   Retrieves list of attribute nodes of the element
-*
+	Upon return, aList is initialized and is ready for use with HasNext() and
-*   @param aList - a node list object to initialize
+	Next() methods:
-*
-*   Passed by reference list of nodes is initialized and after call to
+@code
-*   Attributes(..) is ready for use with HasNext() and Next() methods:
+...
-*
+TXmlEngElement root = doc.DocumentElement();
-*   @code
+RXmlEngNodeList<TXmlEngAttr>    attlist;
-*       ...
+root.GetAttributes(attlist);
-*       TXmlEngElement root = doc.DocumentElement();
+while (attlist.HasNext())
-*       RXmlEngNodeList<TXmlEngAttr>    attlist;
+processAttribute(attlist.Next());
-*       root.GetAttributes(attlist);
+...
-*       while (attlist.HasNext())
+	      attlist.Close();
-*           processAttribute(attlist.Next());
+@endcode
-*       ...
-	 *       attlist.Close();
+		If there are no attributes the list will be empty.
-*   @endcode
-	 *
+@param aList An attribute list to initialize
-* @since S60 v3.1
+*/
-	 */
 IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;
 /**
-* Retrieves list of child elements of the element
+Retrieves a list of child elements of an element.
-*
-* @since S60 v3.1
+	Upon return, aList is initialized and is ready for use with HasNext() and
-	 * @param aList - a node list object to initialize
+	Next() methods.
-*
-* Passed by reference list of nodes is initialized and after the call
+	Note: This returns a list of the child element nodes only.
-* it is ready for use with HasNext() and Next() methods:
-*
+	There is no affect if the element attributes are empty.
-* @note Returned list is a "filtered view" of the underlying
-*       list of all element's children (with text nodes, comments
+	@param aList A child list to initialize
-*       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),
+	Creates a new attribute node outside of any namespace (i.e. it has no
-* sets attribute's value and links it as the last attribute of the current element
+	prefix), sets the 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
+	Note:
-* @param  aValue  Value to set for new attribute or NULL (sets value to "")
+			- No checks are made that an attribute with the same name exists.
-* @return         A handler to the newly created attribute node;
+Use this method only on newly created elements!
-*
+Otherwise, use TXmlEngElement::SetAttributeL()
-* For adding attribute as the first one, use TXmlEngNode::SetAsFirstSibling() on the attribute:
+- Attributes do not inherit default namespace of its element
-* @code
+(http://w3.org/TR/REC-xml-names/#defaulting)
-*     TXmlEngElement el = ... ; // get some element
+- The attribute's value is the second argument in all AddNewAttributeL() methods
-*     el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
-* @endcode
+When adding the first attribute, use TXmlEngNode::SetAsFirstSibling() on the attribute:
-*
+@code
-* @see   SetAsLastSibling(), MoveBeforeSibling(TXmlEngNode) and MoveAfterSibling(TXmlEngNode)
+TXmlEngElement el = ... ; // get some element
-*
+el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
-* @note   - No checks are made that attribute with such name exists
+@endcode
-*           Use this method only on newly created elements!
-*           Otherwise, use TXmlEngElement::SetAttributeL(..)
+	 Copies are taken of descripters passed in.
-*         - Attributes do not inherit default namespace of its element
-*           (http://w3.org/TR/REC-xml-names/#defaulting)
+	@see SetAsLastSibling()
-*         - attribute's value is the second argument in all AddNewAttributeL(..) methods
+	@see MoveBeforeSibling(TXmlEngNode)
-*         - Use of NULL as value is more preferrable then ""
+	@see MoveAfterSibling(TXmlEngNode)
-	 */
+	 *
+	@param  aName   A local name of the attribute
+	@param  aValue  Value to set for new attribute or KNullDesC8
+	@return The created attribute
+	@leave KXmlEngErrNullNode The node is NULL
+	@leave KXmlEngErrWrongUseOfAPI aName is empty
+	@leave - One of the system-wide error codes
+	*/
 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);
 /**
-* Creates new attribute node and add it to the element
+Creates a new attribute node and adds it to the element.
-*
-* Provided handle to namespace declaration is used to set up
+	The provided namespace declaration is used to set the attribute's namespace.
-* attribute's namespace.
-*
+	Note:  If aNsDef is not defined in some of the attribute's ascendants
-* @since S60 v3.1
+	(including this element), then the ReconcileNamespacesL() method must be
-	 * @param  aName   A local name of attribute
+	called on this element later.
-* @param  aValue  Value to set for new attribute or NULL (sets value to "")
-* @param  aNsDef  Namespace to add to the attribute
+	 Copies are taken of descripters passed in.
-* @return         A handler to the newly created attribute node;
-*
+	@param  aName   The local name of attribute
-* @note If aNsDef is not defined in some of attributes ascendants
+	@param  aValue  Value to set for new attribute or KNullDesC8
-*      (including this element), then
+	@param  aNsDef  Namespace to add to the attribute
-*      ReconcileNamespacesL() method must be called on
+	@return The created attribute
-*      this element later.
+	@leave KXmlEngErrNullNode The node is NULL
-	 */
+	@leave KXmlEngErrWrongUseOfAPI aName is empty
+	@leave - One of the system-wide error codes
+	*/
 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
+	Creates a new attribute for the element. A namespace declaration for the
-* created too.
+	attribute namespace is also created.
-*
-* @since S60 v3.1
+	Note:  Namespace declarations are reused if possible (no redundant ones are
-	 * @param  aName   A local name of attribute
+	created)
-* @param  aValue  Value to set for new attribute or NULL (sets value to "")
-* @param  aNsUri  Namespace uri
+	 Copies are taken of descripters passed in.
-* @param  aPrefix  Namespace prefix
-* @return         A handler to the newly created attribute node;
+	@param  aName   The local name of attribute
-*
+@param  aValue  Value to set for the new attribute or an empty string
-* @note
+@param  aNsUri  Namespace URI
-*    - Namespace declarations are reused if possible (no redundant ones are created)
+@param  aPrefix  Namespace prefix
-*/
+@return The created attribute
+	@leave KXmlEngErrNullNode The node is NULL
+	@leave KXmlEngErrWrongUseOfAPI aName is empty
+	@leave - One of the system-wide error codes
+*/
 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),
+	Creates a new attribute node using the namespace of its parent element
-* sets attribute's value and links it as the last attribute of the element
+	(this element), sets the attribute's value and links it as the last
-*
+	attribute of the element
-* @since S60 v3.1
-	 * @param aName Local name of attribute
+For more hints how to use it @see AddNewAttributeL(const TDesC8&,const TDesC8&)
-* @param aValue Value to set for new attribute or NULL (sets value to "")
-* @return A handler to the newly created attribute node;
+	Note:
-*
+- No checks are made that an attribute with the same name exists
-* For more hints how to use it refer to AddNewAttributeL(const TDesC8&,const TDesC8&)
+- if the namespace of the parent element is default (i.e. bound prefix is KNullDesC8),
-*
+then a temporary prefix will be used and bound to the same namespace URI as the element
-* @note
+(It is due to the fact that default namespaces do not spread on unprefixed attributes,
-*     - No checks are made that attribute with such name exists
+see http://w3.org/TR/REC-xml-names/#defaulting)
-*     - 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
+	 Copies are taken of descripters passed in.
-*       (It is due to the fact that default namespaces do not spread on unprefixed attributes,
+	 @see KNullDesC8
-*       see http://w3.org/TR/REC-xml-names/#defaulting)
-*/
+	@param aName Local name of attribute
+@param aValue Value to set for the new attribute or empty.
+@return The created attribute
+	@leave KXmlEngErrNullNode The node is NULL
+	@leave KXmlEngErrWrongUseOfAPI aName is empty
+	@leave - One of the system-wide error codes
+*/
 inline   TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);
 /**
-* Creates new attributes using namespace, which is bound to the specified prefix
+Creates a new attribute using the namespace which is bound to the specified prefix
-*
-* @since S60 v3.1
+Use this mothod only for construction of new parts of DOM tree where
-	 * @param  aLocalName   A local name of attribute
+you know for sure that the prefix is bound in the given scope.
-* @param  aValue  Value to set for new attribute or NULL (sets value to "")
+@code
-* @param  aPrefix  Namespace prefix for new attribute
+TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
-* @return A handler to the newly created attribute node;
+el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
-*
+@endcode
-* 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.
+Otherwise, you should check that the prefix is bound like this example shows:
-* @code
+@code
-*     TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
+TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
-*     el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
+if (boundNS.NotNull()){
-* @endcode
+thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
-*
+}
-* Otherwise, you should check that prefix is bound like this example shows:
+@endcode
-* @code
-*     TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
+	Note: Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can,
-*     if (boundNS.NotNull()){
+	because it is the most efficient way to create namespaced DOM elements (no
-*         thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
+	additional lookups for namespace declarations are required).
-*     }
-* @endcode
+@code
-*
+// If namespace with given URI is not in the scope, then it will be declared
-* @note
+// and bound to "data" prefix.
-*     Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because
+TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
-*     it is most efficient way to create namespaced DOM elements (no additional
+elem.AddNewAttributeL("location", "...", nsDef);
-*     lookups for namespace declarations are required).
+elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
-*
+// the result is
-* @code
+...
-*     // If namespace with given URI is not in the scope, then it will be declared
+<elem xmlns:data="http://../Data" data:location="...">
-*     // and bound to "data" prefix.
+<data:child attr="...value..."/>
-*     TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
+</elem>
-*     elem.AddNewAttributeL("location", "...", nsDef);
+...
-*     elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
+//
-*     // the result is
+@endcode
-*         ...
-*      <elem xmlns:data="http://../Data" data:location="...">
+	 Copies are taken of descripters passed in.
-*         <data:child attr="...value..."/>
-*      </elem>
+	@param  aLocalName   The local name of the attribute
-*         ...
+@param  aValue  Value to set for the new attribute or empty string.
-*     //
+@param  aPrefix  Namespace prefix for the new attribute
-* @endcode
+@return The created attribute
-*/
+	@leave KXmlEngErrNullNode The node is NULL
+	@leave KXmlEngErrWrongUseOfAPI aLocalName is empty
+	@leave KErrNoMemory The namespace is not found and the URI is not
+	http://www.w3.org/XML/1998/namespace; or there is a memory allocation error
+	@leave - One of the system-wide error codes
+*/
 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
+Creates new attributes using the namespace in scope, which has the specified URI
-*
-* Almost the same as AddNewAttributeUsePrefixL(...) but does lookup by namespace URI
+Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI
-*
-* @since S60 v3.1
+@see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
-	 * @param  aLocalName   A local name of attribute
-* @param  aValue  Value to set for new attribute or NULL (sets value to "")
+	 Copies are taken of descripters passed in.
-* @param  aNsUri  Namespace uri for new attribute
+	 @see KNullDesC8
-* @return - NULL attribute if namespace declaration is not found OR newly added to the end of
-*           attribute list attribute of this element.
+	@param  aLocalName   The local name of the attribute
-*
+@param  aValue  Value to set for new attribute or empty string.
-* @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
+@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.
+	@leave KXmlEngErrNullNode The node is NULL
+	@leave KXmlEngErrWrongUseOfAPI aLocalName is empty
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName,
 const TDesC8& aValue,
 const TDesC8& aNsUri);
-/**
+	/**
-* Add attribute to element that will be used as Xml:Id.
+	Adds attribute to element that will be used as Xml:Id.  Does not check if
-*
+	an attribute with the same name exists.
-* No check if such attribute exists are made.
-*
+	Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register
-* @since S60 v3.2
+	existed id's in the document.  If the ids are not registered the ID will
-	 * @param aLocalName Name of attribute that should be add.
+	not be added to the element.
-	 * @param aValue Value of the attribute
-	 * @param aNs Namespace of the attribute
+	 Copies are taken of descripters passed in.
-	 * @return Attribute if created. Null attribute if Id exist
-*
+	@param aLocalName Name of the attribute
-* @note Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first
+	@param aValue Value of the attribute
-*       to register existed id's in the document.
+	@param aNs Namespace of the attribute
-*/
+	@return Attribute if created. Null attribute if Xml:Id exists
+	@leave KXmlEngErrWrongUseOfAPI Element is NULL or attribute doesn't exist
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,
 const TDesC8& aValue,
 TXmlEngNamespace aNs = TXmlEngNamespace());
-/**
+	/**
-* Adds child element with no namespace
+	Adds a child element with no namespace.  This results in adding an element
-*
+	with aName and no prefix.
-* @since S60 v3.1
-	 * @param aName name of the element
+	This method is the best for creation of non-namespace based documents
-* @return A handler to the newly created element node;
+	or document fragments, where no default namespace declared.
-*
-* Results in adding element with aName and no prefix.
+	It may be used also as a method for adding elements from the default
-*
+	namespace, BUT namespace will be assigned ONLY after serialization of the
-* This method is the best for creation of non-namespace based documents
+	current document and parsing it back into a DOM tree!! If you need the new
-* or document fragments, where no default namespace declared.
+	element to inherit the default namespace use:
-*
-* It may be used also as a method for adding element from default namespace,
+@code
-* 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
+TXmlEngNamespace defns = element.DefaultNamespace();
-* was inherited by new element immediately use:
+TXmlEngElement newEl = element.AddNewElementL("Name",defns);
-* @code
+...
-*    ...
+@endcode
-*    TXmlEngNamespace defns = element.DefaultNamespace();
-*    TXmlEngElement newEl = element.AddNewElementL("Name",defns);
+	It is not recommended that you use an undefined namespace with libxml.
-*    ...
+	If an undefined namespace for the element is truly required, then DO NOT
-* @endcode
+	USE this method if there is a default namespace in the scope!
-*
+	@see AddNamespaceDeclarationL
-* 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!
+	Copies are taken of descripters passed in.
-*/
+	@param aName The name of the element
+	@return The created element
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Name is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);
-/**
+	/**
-* Creates new child element with provided name and namespace declaration
+	Creates a new child element with the provided name and namespace
-*
+	declaration and adds it as the last child of its parent.
-* @since S60 v3.1
-	 * @param aLocalName Name of the element
+	 Copies are taken of descripters passed in.
-* @param aNsDecl Handle of the namespace declaration, that must be retrieved from
-*            one of the ascendant nodes of the new elements (and its prefix
+	@param aLocalName The name of the element
-*            should not be remapped to another namespace URI for the scope
+@param aNsDecl The namespace declaration that must be retrieved from
-*            of the new element)
+one of the ascendant nodes of the new elements (and its prefix
-* @return    Created element node (and added as the last child of its parent)
+should not be remapped to another namespace URI for the scope
-*/
+of the new element)
+@return Created element node
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Name is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);
-/**
+	/**
-* Creates new child element with provided name, prefix and namespace URI
+	Creates a new child element with provided the name, prefix and namespace
-*
+	URI and adds it as the last child of its parent.
-* 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
+	The new namespace declaration will be attached to the parent (this) element
-* (same prefix is bound to same URI), it will be reused. If the prefix is already
+	and used as the namespace for newly created child element. If such a
-* bound to some another namespace URI, it will be rebound by the new namespace
+	binding already exists (same prefix is bound to same URI), it will be
-* declaration node.
+	reused. If the prefix is already bound to some other namespace URI, it will
-*
+	be rebound by the new namespace declaration node.
-* @since S60 v3.1
-	 * @param aLocalName Name of the element
+	 Copies are taken of descripters passed in.
-* @param aNsUri     URI of element's namespace
-* @param aPrefix    Prefix of the element
+	@param aLocalName Name of the element
-* @return Created element node (and added as the last child of its parent)
+@param aNsUri     URI of the element's namespace
-*/
+@param aPrefix    Prefix of the element
+@return The created element node
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Name or URI or prefix is not specified
+	@leave - One of the system-wide error codes
+*/
 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
+	Creates a child element with the same namespace (and prefix if present) as
-*
+	the parent element and adds it as the last child of its parent.
-* @since S60 v3.1
-	 * @param aLocalName element's name
+	 Copies are taken of descripters passed in.
-* @return New element that was added to the end of children list of its parent (this element)
-*/
+	@param aLocalName The element's name
+@return The created element
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Name is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);
-/**
+	/**
-* Performs lookup for the namespace declaration for specified prefix and
+	Performs a lookup for the namespace declaration for the specified prefix
-* adds new child element with found namespace.
+	and adds a new child element with the found namespace as the last child of
-*
+	its parent.
-* The assumption is that prefix is bound, otherwise run-time error
-* (Symbian's Leave or exception) occurs
+	@pre The prefix is bound
-*
-* @note   Use this method only if there is a binding for the given prefix.
+	 Copies are taken of descripters passed in.
-*
-* @since S60 v3.1
+	@param aLocalName The element's name
-	 * @param aLocalName element's name
+@param aPrefix    The prefix to use for the search
-* @param aPrefix    prefix to use
+@return The created element
-* @return new TXmlEngElement that was added to the end of children list of its parent (this element)
+	@leave KXmlEngErrNullNode Element is NULL
-*/
+	@leave KXmlEngErrWrongUseOfAPI Name is not specified
+	@leave KErrNoMemory The namespace is not found and the prefix is not "xml"
+	(i.e http://www.w3.org/XML/1998/namespace); or there is a memory allocation
+	error.
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);
-/**
+	/**
-* Performs lookup for the namespace declaration for specified namespace URI and
+	Performs a lookup for the namespace declaration for the specified namespace
-* adds new child element with found namespace.
+	URI and adds a new child element with the found namespace.  The new element
-*
+	is added as the last child of this element.
-* The assumption is that namespace with given URI was declared,
-* otherwise run-time error (Symbian' Leave or exception) occurs
+	 Copies are taken of descripters passed in.
-*
-* @note Use this method only if namespace declaration for the provided URI exists.
+	@pre A namespace with the given URI has been declared
-*
-* @since S60 v3.1
+	@param aLocalName    The element's name
-	 * @param aLocalName    element's name
+@param aNsUri        The namespace of the element
-* @param aNsUri        namespace of element
+@return The created element
-* @return new TXmlEngElement that was added to the end of children list of its parent (this element)
+	@leave KXmlEngErrNullNode Element is NULL
-*/
+	@leave KXmlEngErrWrongUseOfAPI Name is not specified
+	@leave KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace
+	or there is a memory allocation error
+	@leave - One of the system-wide error codes
+*/
 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,
+	Creates a new child element.  If there is no a prefix binding for the new
-* a namespace decaration is created with generated prefix at specified element.
+	element's namespace, a namespace decaration is created with a generated
-*
+	prefix at the specified element.
-* @since S60 v3.1
-	 * @param aLocalName    Name of the element to create
+	The location of the namespace declaration may be controlled with
-* @param aNsUri        Namespace URI of the new element
+	aNsDeclTarget:
-* @param aNsDeclTarget An element where namespace declaraton should be placed
-*                     if there is a needed to create new namespace declaration;
+@code
-*                     NULL is used to specify the created element itself
+el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // declare on the new element
-*
+el.AddNewElementAutoPrefixL(tagName,uri,el);   // declare on the parent element
-* As aNsDeclTarget any ascendant of the new node may be provided:
+el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
-* @code
+...
-*     el.AddNewElementAutoPrefixL(tagName,uri,NULL); // declare on the new element
+@endcode
-*     el.AddNewElementAutoPrefixL(tagName,uri,el);   // declare on the parent element
-*     el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
+	Note:  The farther namespace declaration up in the document tree, the
-*    ...
+	longer the namespace declaration lookups take.
-* @endcode
-*
+	 Copies are taken of descripters passed in.
-* @note
-*  The farther namespace declaration up in the document tree,
+	@param aLocalName    Name of the element to create
-*  the longer time namespace declaration lookups take.
+	@param aNsUri        Namespace URI of the new element
-*/
+	@param aNsDeclTarget The element where the namespace declaraton should be placed.
+	@return The created element
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Name or URI is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName,
 const TDesC8& aNsUri,
 TXmlEngElement aNsDeclTarget);
-/**
+	/**
-* Get element content.
+	Gets element content.  This method may be used in most cases when the element
-* This method may be used in most cases, when element has only simple text content
+	has only simple text content (without entity references embedded).  If the
-* (without entity references embedded).
+	element's contents is mixed (other types of nodes present), only the contents
-* If element's contents is mixed (other types of nodes present), only contents of
+	of the first child node is returned (if it is a TXmlEngTextNode node).
-* 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.
+	For getting the contents of an element that has contents containing entity
-*
+	references, WholeTextValueCopyL() should be used.
-* @since S60 v3.1
-	 * @return Basic contents of the element
+	@see TXmlEngNode::WholeTextContentsCopyL()
-*
-* @see TXmlEngNode::WholeTextContentsCopyL()
+	@return The simple text contents of the element or NULL if there is no text.
 */
 IMPORT_C TPtrC8 Text() const;
 /**
-* Adds text as a child of the element.
+Adds text as a child of the element to the end of the list of children.
-*
-* @since S60 v3.1
+	Note:  There may be several TXmlEngTextNode and TXmlEngEntityReference
-	 * @param aString text to be added as element's content.
+	nodes added, depending on the aString value.  For example, if the curernt
-*
+	node has text and attributes, a text node and attribute nodes will
-* @note There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added actually,
+	be added.
-*   depending on the aString value
-*/
+	 Copies are taken of descripters passed in.
+	@param aString Text to be added as the element's content.
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C void  AddTextL(const TDesC8& aString);
 /**
-* Sets text contents for the element.
+Sets text contents for the element.  Any child nodes are removed.
-* Any child nodes are removed.
+This function is the same as TXmlEngNode::SetValueL(TDesC8&)
-* Same as TXmlEngNode::SetValueL(TDesC8&)
-*
+@see TXmlEngNode::SetValueL(TDesC8&)
-* @since S60 v3.1
-	 * @param aString text to be set as element's content.
+	@param aString Text to be set as element's content.
-*
+	@leave KXmlEngErrNullNode Element is NULL
-* @see TXmlEngNode::SetValueL(TDesC8&)
+	@leave - One of the system-wide error codes
 */
 IMPORT_C void  SetTextL(const TDesC8& aString);
 /**
-* Sets text content of the element from escaped string.
+Sets the text content of the element from an escaped string.
-*
+@see TXmlEngAttr::SetEscapedValueL(TDesC8&)
-* @since S60 v3.1
-	 * @param aEscapedString New value
+	@param aEscapedString New value
-*
+	@leave KXmlEngErrNullNode Element is NULL
-* @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
+	@leave - One of the system-wide error codes
 */
 IMPORT_C void  SetEscapedTextL(const TDesC8& aEscapedString);
-/**
+	/**
-* Sets new element value exactly as presented in the string.
+	Sets the new element value exactly as presented in the string.  Predefined
-	 * Predefined entities are not converted into characters they represent.
+	entities are not converted into the characters they represent.  Any child
-	 * Any child nodes are removed.
+	nodes are removed.
-*
-* @since S60 v3.2
+@see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
-	 * @param aNotEncText New element value
-*
+	@param aNotEncString New string value
-* @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
+	@leave KXmlEngErrNullNode Element is NULL
-*/
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C void SetTextNoEncL(const TDesC8& aNotEncString);
-/**
+	/**
-* Appends new text node with the value exactly as presented in the string.
+	Appends a new text node with the value exactly as presented in the string.
-	 * Predefined entities are not converted into characters they represent.
+	Predefined entities are not converted into the characters they represent.
-	 * Existing child nodes are not removed.
+	Existing child nodes are not removed.
-*
-* @since S60 v3.2
+@see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
-	 * @param aNotEncText Appended element value
-*
+	 Copies are taken of descripters passed in.
-* @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
-*/
+	@param aNotEncString Appended string value
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave - One of the system-wide error codes
+*/
 	IMPORT_C void AppendTextNoEncL(const TDesC8& aNotEncString);
-/**
+	/**
-* Adds namespace declaration to the current element, a binding of prefix to namespace URI.
+	Adds a 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
+	If the same namespace declaration exists (same prefix and URI), a redundant
-* will not be created.
+	namespace declaration will not be created.
-*
-* Both NULL or "" (empty string) may be used for "UNDEFINED URI" and "NO PREFIX" values of arguments.
+	Both KNullDesC8 or an empty descriptor may be used for "UNDEFINED URI"
-*
+	and "NO PREFIX" values of arguments.  Please refer to the class
-* @since S60 v3.1
+	documentation for more specific information.
-	 * @param aNsUri Namespace URI
+	@see TXmlEngElement
-* @param aPrefix Namespace prefix
+	@see KNullDesC8
-* @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
+	Note: Undeclaring of default namespace (xmlns="") is supported by
-*           used in node-creation methods that take namespace handle as an argument.
+	the SetNoDefaultNamespace() method.
-*
+	@see SetNoDefaulNamespace()
-* @note   Undeclaring of default namespace (xmlns="") is supported by
-*         SetNoDefaultNamespace() method
+	Note:   Adding a namespace declaration that rebinds the prefix mapping (or
-*
+	default namespace) used by nodes lower in the tree may damage the document
-* @see SetNoDefaulNamespace()
+	tree because references to namespace declarations are not updated.
-*
+	However, after serialization, the document will have the desired structure.
-* @note   By adding namespace declaration that rebinds prefix mapping (or default namespace)
+	Use this method with care!
-*         used by nodes lower in the tree, document tree may become
-*         wrongly constructed, because references to namespace declaration are
+	Copies are taken of descripters passed in.
-*         not updated. However, after serialization the document will have
-*         desired structure.
+	@param aNsUri Namespace URI, KNullDesC8 or an empty descriptor.
-*         Use this method with care!
+	@param aPrefix Namespace prefix, KNullDesC8 or an empty descriptor.
-*/
+	@return The namespace that was created or found or a NULL namespace if the
+	namespace is being undeclared.
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI URI or prefix is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngNamespace AddNamespaceDeclarationL(const TDesC8& aNsUri, const TDesC8& aPrefix);
 /**
-* Adds default namespace declaration.
+Adds a default namespace declaration.
-*
-* @since S60 v3.1
+1
-	 * @param aNsUri   Namespace URI;  both NULL and "" (empty string) are allowed to represent UNDEFINED NAMSPACE
+	This achieves the same result as with AddNamespaceDeclarationL(aNsUri,
-* @return    Handle to the created namespace declaration (NULL for UNDEFINED NAMESPACE)
+	KNullDesC8), but additionally the element's namespace is modified (if it has no
-*
+	prefix and there were no default namespace declaration in the scope) to the
-* Same result as with AddNamespaceDeclarationL(aNsUri, NULL), but additionally
+	new default one.
-* element's namespace modified (if it has no prefix and there were no default
-* namespace declaration in the scope) to the new default one.
+	 Copies are taken of descripters passed in.
-*/
+	 @see KNullDesC8
+	@param aNsUri   Namespace URI;  KNullDesC8 and empty descriptor are allowed to represent UNDEFINED NAMSPACE
+	@return The created namespace declaration (NULL for UNDEFINED NAMESPACE)
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI URI is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngNamespace SetDefaultNamespaceL(const TDesC8& aNsUri);
 /**
-* Undeclares any default namespace for current element and its descendants.
+Undeclares any default namespace for this element and its descendants.
-*
-* If there is already some default namespace,  <i>xmlns=""</i> namespace
+If there is already a default namespace, a @c xmlns="" namespace
-* declaration is added. Otherwise, nothing happens, since element with no
+declaration is added. Otherwise, nothing happens, since elements with no
-* prefix in such scope is automaticaly considered as out of any namespace.
+prefix in such scope are automaticaly considered outside of any namespace.
-*
-* The side effect of this method is that namespace of the current element
+	The side effect of this method is that the namespace of the current element
-* may change from previous <b>default</b> namespace to NULL TXmlEngNamespace, which is
+	may change from the previous default namespace to a NULL TXmlEngNamespace,
-* considered an absence of namespace.
+	which is considered an absence of namespace.
-*
-* If the element has prefix (i.e. not having default namespace),
+	If the element has a prefix (i.e. not having default namespace), then the
-* then the only effect for the element is undeclaration of existing default namespace.
+	only effect for the element is undeclaration of existing default namespace.
-*
-* If element is in the scope of another <i>xmlns=""</i> undeclaration, no
+If the element is in the scope of another @c xmlns="" undeclaration, no
-* actions are taken.
+action is taken.
-*
-* @note
+	Note: Use AddNamespaceDeclarationL(KNullDesC8,KNullDesC8) to force the creation of a @c
-*     Use AddNamespaceDeclarationL(NULL,NULL) to force creation of
+	xmlns="" declaration within the scope of another such declaration
-*     xmlns=""  declaration within scope of another such declaration
+	(otherwise unneccessary/duplicate declarations are not created).
-*     (otherwise unneccessary/duplicate declarations are not created)
-*
+	Note: This method should be called on elements before adding children,
-* @note
+	because default namespace undeclaration is not spread into its subtree and
-*     This method should be called on elements before adding children,
+	descendants' default namespaces are not reset to NULL. This should be taken
-*     because default namespace undeclaration is not spread into its subtree and
+	into account if later some processing on the subtree occurs.  However,
-*     descedants' default namespaces are not reset to NULL. This should be taken into
+	after serialization and deserialization, undeclared default namespace will
-*     account if later some processing on the subtree occurs.
+	affect whole element's subtree correctly.
-*     However, after serialization and deserialization, undeclared default namespace will
-*     affect whole element's subtree correctly.
+	 @see KNullDesC8
-*
-* @since S60 v3.1
+	@leave KXmlEngErrNullNode Element is NULL
-	 */
+	@leave - One of the system-wide error codes
-IMPORT_C void SetNoDefaultNamespaceL();
+	*/
+	IMPORT_C void SetNoDefaultNamespaceL();
-/**
-* Finds namespace declaration that has specific prefix in the scope for given node
+	/**
-*
+	Finds the namespace declaration that has a specific prefix in the list of parents for
-* Prefix "" or NULL are considered the same, meaning "<b>NO PREFIX</b>".
+	this element.
-* If namespace declaration for "no prefix" is searched, then default namespace is returned.
-*
+	If no prefix is specified (an empty descriptor or KNullDesC8) then it is
-* @since S60 v3.1
+	considered to be a "NO PREFIX" search.  Therefore, if the namespace
-	 * @param aPrefix Namespace prefix
+	declaration for "no prefix" is searched, then the default namespace is
-* @return Namespace handler, which may be NULL if prefix is not bound.
+	returned.
-*
-* NULL result for "no prefix" means that default namespace is undefined.
+	Copies are taken of descripters passed in.
-*/
+	@see KNullDesC8
+	@param aPrefix Namespace prefix.
+	@return The namespace, which may be NULL if prefix is not found; NULL result for "no prefix" means that default namespace is undefined.
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngNamespace LookupNamespaceByPrefixL(const TDesC8& aPrefix) const;
-/**
+	/**
-* Finds namespace declaration that has specific namespace URI
+	Finds a namespace declaration that has a specific namespace URI in the
-* in the scope for the given node.
+	scope for the given node.
-*
-* @since S60 v3.1
+	KNullDesC8 value of aUri is equivalent to an empty descriptor and means
-	 * @param aUri  Namespace URI, for which namespace declaration is searched
+	"UNDEFINED NAMESPACE".
-* @return Handler to the namespace declaration that binds given namespace URI to some prefix
+	For such URI's a NULL namespace handle is always returned even if there is
-*          or sets it a default namespace.
+	a namespace undeclaration, which has an empty descriptor URI (and KNullDesC8
-*
+	prefix).
-* 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
+	Hint: Use the returned instance of TXmlEngNamespace as the aNsDef argument
-* namespace undeclaration, which has "" URI (and NULL prefix).
+	to an element's methods that create new child elements and attributes. The
-*
+	same TXmlEngNamespace may be used on deeper descentants of the reference
-* <b>Hint:</b><p>
+	element (and doing this way will generally increase performance of DOM tree
-* Use returned instance of TXmlEngNamespace as aNsDef argument to element's methods
+	construction). However, if namespace bindings are not controlled for the
-* that create new element's child elements and attributes. The same handler
+	element's children and the prefix (which is bound to the search namespace)
-* may be used on more deep descentants of the reference element (and doing
+	is rebound to some other namespace URI, then reusing the namespace may lead
-* this way will generally increase performance of DOM tree construction).<br />
+	to unwanted result.
-* <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
+	Note: At the moment it is possible to retrieve namespace declaration nodes
-* rebound to some other namespace URI, then reusing namespace may lead to
+	whose prefixes were rebound. Be careful when using returned
-* unwanted result.
+	TXmlEngNamespace objects for creation of new elements.
-*
-* Consider an example:
+	Copies are taken of descripters passed in.
-* @code
-*     TXmlEngElement root = doc.DocumentElement();
+	@param aUri  Namespace URI, for which the namespace declaration is searched
-*     TXmlEngNamespace targetNs = root.AddNamespaceDeclarationL("http://example.com/","ex");
+	@return The namespace declaration that binds the given namespace URI to a
-*     TXmlEngElement el_1 = root.AddNewElementL("outer", targetNs);
+	prefix or sets it as a default namespace
-*     TXmlEngElement el_2 = el_1.AddNewElementL("inner"); // element without prefix
+	@leave - One of the system-wide error codes
-*
+*/
-*     // 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
+	Retrieves the implicitly declared XML infoset binding of the 'xml' prefix
-* of 'xml' prefix to XML's namespace URI:
+	to XML's namespace URI: "http://www.w3.org/XML/1998/namespace"
-* "http://www.w3.org/XML/1998/namespace"
-*
+The result should be used for creating attributes beloging to the XML namespace
-* @since S60 v3.1
+(xml:lang, xml:space, xml:id , etc.)
-	 * @return Handler to {xml,"http://www.w3.org/XML/1998/namespace"} prefix
-*            binding in the current document
+	DO NOT USE the methods LookupNamespaceByUriL(const TDesC8&) and
-*
+	LookupNamespaceByPrefixL(const TDesC8&) (with the arguments
-* The result should be used for creating attributes beloging to the XML namespace
+	"http://www.w3.org/XML/1998/namespace" and "xml" respectively) for
-* (xml:lang, xml:space, xml:id , etc.)
+	retrieving the namespace node, since in the case of a memory allocation
-*
+	fault, a NULL result is returned (and breaks your program silently)
-* DO NOT USE methods LookupNamespaceByUriL(const TDesC8&) and LookupNamespaceByPrefixL(const TDesC8&)
-* (with "http://www.w3.org/XML/1998/namespace" and "xml" arguments) for retrieving
+	Note:  Normally the 'xml' prefix is bound to the XML namespace URI in the
-* namespace node, since in a case of [possible] memory allocation fault
+	document node, BUT if this element is not a part of the document tree yet,
-* NULL result is returned (and breaks your program silently)
+	the requested namespace declaration WILL BE ADDED to the current node.
-*
+	This is the reason why the method may fail in OOM conditions.
-* @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,
+	@return The namespace matching the prefix binding
-*        the requested namespace declaration WILL BE ADDED to the current node.
+	{xml,"http://www.w3.org/XML/1998/namespace"} in the current document
-*        This is the reason why the method may fail in OOM conditions.
+	@leave KErrNoMemory The element is NULL or there was a memory allocation error
-*/
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngNamespace TheXMLNamespaceL() const;
-/**
+	/**
-* Get default namespace for element.
+	Get the default namespace for the element.
-*
-* @since S60 v3.1
+	A NULL TXmlEngNamespace means that an element with no prefix
-	 * @return Default namespace in the scope of the element
+	has no namespace associated with it because no default namespace was declared or
-*
+	the default namespace was undeclared with @c xmlns=""
-* 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>
+	This function is equivalent to LookupNamespaceByPrefixL(KNullDesC8).
-*
+	@see KNullDesC8
-* Equivalent to LookupNamespaceByPrefixL(const TDesC8&) with NULL (or "") prefix provided
-*/
+	@return The default namespace in the scope of the element
+	@leave - One of the system-wide error codes
+*/
 inline   TXmlEngNamespace DefaultNamespaceL() const;
-/**
+	/**
-* Performs search of namespace handler in the scope of the element. This method will
+	Performs a search for the namespace in the scope of the element. This
-* create new namespace declaration on the element if such namespace is not available.
+	method will create new namespace declaration on the element if such
-*
+	namespace is not found.
-* @since S60 v3.1
-	 * @param aNsUri   Searched namespace
+	Note: Be sure not to use the result of this method for non-descendants of
-* @param aPrefix  Prefix to use for <b>new</b> namespace declaration (if it is to be created)
+	the element or in situations when prefix overlapping might occur.
-* @return    TXmlEngNamespace handler that may be used to create new attributes and child elements of
+	@see TXmlEngAttr
-*            the element. The namespace may be one of those existed previously or was created
+	@see TXmlEngNamespace
-*
+Please read the documentation for this class:
-* @note
+	@see TXmlEngElement
-*    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
+	Copies are taken of descripters passed in.
-*    and elements creation using namespace handlers)
-*/
+	@param aNsUri   Namespace to search for
+	@param aPrefix  Prefix to use for the new namespace declaration (if it is to be created)
+	@return The namespace found or created
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI URI is not specified
+	@leave - One of the system-wide error codes
+	@see LookupNamespacebyUriL
+*/
 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri, const TDesC8& aPrefix);
-/**
+	/**
-* Performs search on the element and its ascendants for any namespace declaration
+	Performs a search on the element and its ascendants for any namespace
-* with given URI and create a new namespace declaration with some (unique) prefix
+	declaration with a given URI.  Creates a new namespace declaration with a
-* if the search was not successful.
+	(unique) prefix if the search was not successful.
-*
+	@see AddNamespaceDeclarationL
-* @since S60 v3.1
-	 * @param aNsUri   Searched namespace
+	 Copies are taken of descripters passed in.
-* @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
+	@param aNsUri Namespace to search for
-*/
+	@return The namespace found or created
+	@leave KXmlEngErrNullNode Element is NULL
+	@leave KXmlEngErrWrongUseOfAPI URI is not specified
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri);
 /**
-* Checks whether a prefix has been bound in this element (not in one of its ascendants)
+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
+Use this method for preventing prefix-name collision in a element node
-*
-* @since S60 v3.1
+	 Copies are taken of descripters passed in.
-	 * @param aPrefix Namespace prefix
-* @return TRUE if there is already namespace declaration that uses aPrefix on this element
+	@param aPrefix Namespace prefix
-*/
+@return ETrue if there is already a namespace declaration that uses aPrefix on this element
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TBool HasNsDeclarationForPrefixL(const TDesC8& aPrefix) const;
 /**
-* Copies the element with its attributes, but not child nodes
+Copies the element with its attributes, but not child nodes
-*
-* If context is preserved, then all namespace declarations that are in the element are
+	If the context is preserved (preserveNsContent), then all namespace
-* writen to element's start tag too.
+	declarations that are in the element are writen to the <element ...> tag.
-*
-* @since S60 v3.1
+	@param preserveNsContext Whether the namespace context should be preserved
-	 * @param preserveNsContext TRUE if context should be preserved
+@return The copied element
-* @return handle to copy of element
+	@leave KXmlEngErrNullNode The element is NULL
-*/
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngElement ElementCopyNoChildrenL(TBool preserveNsContext) const;
 /**
-* Specialized version of TXmlEngNode::CopyL()
+Specialized version of TXmlEngNode::CopyL()
-*
+	@return Deep copy of the element.
-* @since S60 v3.1
+	@leave KXmlEngErrNullNode The element is NULL
-	 * @return Deep copy of the element.
+	@leave - One of the system-wide error codes
 */
 inline   TXmlEngElement CopyL() const;
-/**
+/** Resets element's content: all child nodes are removed */
-* Resets element's content: all child nodes are removed
-*
-* @since S60 v3.1
-	 */
 IMPORT_C void RemoveChildren();
-/**
+/** Resets element's attributes */
-* Resets element's attributes
-*
-* @since S60 v3.1
-	 */
 IMPORT_C void RemoveAttributes();
 /**
-* Resets all namespace declarations made in the element
+Resets all namespace declarations made in the element
-*
-* @note There can be references to these namespace declaration from elsewhere!
+	Note: There can be references to these namespace declarations elsewhere!
-*      Use ReconcileNamespacesL() to fix that.
+	Use ReconcileNamespacesL() to fix that.
-*
+	*/
-* @since S60 v3.1
+	IMPORT_C void RemoveNamespaceDeclarations();
-	 */
-IMPORT_C void RemoveNamespaceDeclarations();
+/**
+Removes all element contents: child nodes, attributes and namespace declarations
-/**
-* Removes all element contents: child nodes, attributes and namespace declarations
+@see RemoveChildren()
-*
+	@see RemoveAttributes()
-* @see RemoveChildren(), RemoveAttributes(), RemoveNamespaceDeclarations();
+	@see RemoveNamespaceDeclarations();
-*
+	*/
-* @since S60 v3.1
-	 */
 inline   void ClearElement();
-/**
+	/**
-* Copies attributes from another element
+	Copies attributes from another element.  It may be a very convenient method
-*
+	for initializing element with a set of predefined attributes.
-* It may be a very convenient method for initializing element with a set of predefined attributes.
-*
+	Note: Namespaces of the this element may need to be reconciled if the
-* @since S60 v3.1
+	copied attributes belong to any namespace that is not declared on some
-	 * @param aSrc source element
+	ascendant of this node.  @see ReconcileNamespacesL()
-*
-* @note
+	@param aSrc Source element
-*  Namespaces of the this element may need to be reconciled if copied attributes
+	@leave KXmlEngErrNullNode The element is NULL
-*  belong to any namespace that is not declared on some ascendant of this node.
+	@leave - One of the system-wide error codes
-* @see ReconcileNamespacesL()
+*/
-*/
 IMPORT_C void CopyAttributesL(TXmlEngElement aSrc);
-/**
+	/**
-* Copies a list of elements.
+	Recursively copies the children (and all of it's associated information)
-*
+	from another element.  Elements are appended to the current element's
-* Elements are appended to the element's children list.
+	children list.
-*
-* @since S60 v3.1
+	Note: Namespaces of this element may need to be reconciled after copy
-	 * @param aSrc source element
+	operation
-*
+	@see ReconcileNamespacesL()
-* @note Namespaces of the this element may need to be reconciled after copy operation
-* @see  ReconcileNamespacesL()
+	@param aSrc Source element
-*/
+	@leave KXmlEngErrNullNode The element is NULL
+	@leave KXmlEngWrongUseOfAPI The source element is NULL
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C void CopyChildrenL(TXmlEngElement aSrc);
-/**
+	/**
-* Removes attribute with given name and namespace URI(if such exists).
+	Removes the child element with the given name and namespace URI (if it exists).
-* Memory allocated for the attribute is freed.
+	Memory allocated for the element is freed.
-*
-* @since S60 v3.1
+	@param aLocalName Child element name
-	 * @param aLocalName Element name
+@param aNamespaceUri Child element namespace
-* @param aNamespaceUri Element namespace
+	@leave KXmlEngErrNullNode The element is NULL
-*/
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C void RemoveChildElementsL(const TDesC8& aLocalName,const TDesC8& aNamespaceUri);
-/** @} */
+	/**
+	Renames the element with the given name, namespace URI, and namespace prefix.
-/**
-*    @name DOM Level 3 Core methods
+	@param aLocalName The new element name
-*
+	@param aNamespaceUri The new namespace URI
-*    @note
+	@param aPrefix The new namespace prefix
-*        Most methods of DOM spec operate with fully-qualified names (QNames)
+	@leave - One of the system-wide error codes
-*        of elements and attributes. It is different in this API - all methods
+	*/
-*        instead accept prefix and localName parts of QName.
+	IMPORT_C void RenameElementL(const TDesC8& aLocalName, const TDesC8& aNamespaceUri, const TDesC8& aPrefix);
-*/
-/** @{ */
+/*
+	DOM Level 3 Core methods
-/**
-* Returns value of attribute with given name and namespace URI
+	Most methods of DOM spec operate with fully-qualified names (QNames)
-*
+	of elements and attributes. It is different in this API - all methods
-* @since S60 v3.1
+	instead accept prefix and localName parts of QName.
-	 * @param aLocalName Local name of attribute node
+*/
-* @param aNamespaceUri Namespace URI of attribute
-* @return Attribute value
+/**
-*/
+Returns the value of the attribute with the given name and namespace URI.
+	@param aLocalName Local name of the attribute
+	@param aNamespaceUri Namespace URI of the attribute, or the default namespace if not specified.
+	@return The attribute value (for as long as the attribute exists) or
+	NULL if not found.
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TPtrC8 AttributeValueL(const TDesC8& aLocalName,
 const TDesC8& aNamespaceUri = KNullDesC8) const;
 /**
-* Initializes list of child elements with matching name and namespace URI.
+Initializes list of child elements with matching names and namespace URIs.
-*
-* @since S60 v3.1
+Note: This method does not list all descendants of the element, only child elements
-	 * @param aList Node list to be initialized
+	@see KNullDesC8
-* @param aLocalName Element name
-* @param aNamespaceUri Namespace URI, default is NULL
+	@param aList Node list to be created
-*
+@param aLocalName Element name
-* @note This method does not lists all descedants of the element, only child elements
+@param aNamespaceUri if specified it sets the Namespace URI, default is KNullDesC8 (no namespace set).
-*/
+	@leave - One of the system-wide error codes
+*/
 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
+	Sets the value of the given attribute.  The attribute is created if there
-*
+	is no such attribute yet.
-* @since S60 v3.1
-	 * @param aLocalName Attribute name
+	Note: If prefix is not KNullDesC8 (or an empty descriptor),
-* @param aValue Attribute value
+	then the namespace URI may not be empty see
-* @param aNamespaceUri Namespace URI - default is NULL
+	http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
-* @param aPrefix Namespace prefix - default is NULL
-*
+	Copies are taken of descripters passed in.
-* @note
+	@see KNullDesC8
-*  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)
+	@param aLocalName Attribute name
-*/
+@param aValue Attribute value
+@param aNamespaceUri Namespace URI - default is KNullDesC8
+@param aPrefix Namespace prefix - default is KNullDesC8
+	@leave KXmlEngErrNullNode The element is NULL
+	@leave KXmlEngErrWrongUseOfAPI Attribute name not specified
+	@leave - One of the system-wide error codes
+*/
 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).
+	Removes the attribute with the given name and namespace URI (if it exists).
-* Memory allocated for the attribute is freed.
+	Memory allocated for the attribute is freed.
-*
-* @since S60 v3.1
+	@see KNullDesC8
-	 * @param aLocalName Name of the attribute
-* @param aNamespaceUri Attribute namespace URI, default is NULL
+	@param aLocalName Name of the attribute
-*/
+	@param aNamespaceUri Attribute namespace URI, default is KNullDesC8
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C void  RemoveAttributeL(const TDesC8& aLocalName,
 const TDesC8& aNamespaceUri = KNullDesC8);
-/**
+	/**
-* Retrieves attribute node from specific namespace by its name.
+	Retrieves an attribute node with a specific namespace by its name.
-*
-* @since S60 v3.1
+	@see KNullDesC8
-	 * @param aLocalName Name of the attribute
-* @param aNamespaceUri Attribute namespace URI, default is NULL
+	@param aLocalName Name of the attribute
-* @return Attribute node with matching namespace URI and name
+	@param aNamespaceUri Attribute namespace URI, default is KNullDesC8
-*/
+	@return Attribute node with matching namespace URI and name, NULL if not found.
+	@leave - One of the system-wide error codes
+*/
 IMPORT_C TXmlEngAttr AttributeNodeL(const TDesC8& aLocalName,
 const TDesC8& aNamespaceUri = KNullDesC8) const;
 /**
-* Check if element has attribute with given parameters.
+Check if the element has an attribute with given parameters.
-*
-* @since S60 v3.1
+This function is the same as AttributeNodeL(uri,name).NotNull().
-	 * @param aLocalName Name of attribute
-* @param aNamespaceUri Namespace uri, default is NULL.
+	@see KNullDesC8
-* @return TRUE if the element holds an attribute with such namespace URI and name.
-*
+	@param aLocalName Name of attribute
-* Same result gives AttributeNodeL(uri,name).NotNull()
+@param aNamespaceUri Namespace uri, default is KNullDesC8.
-*/
+@return ETrue if the element holds an attribute with such namespace URI and name.
+	@leave - One of the system-wide error codes
+*/
 inline     TBool HasAttributeL(const TDesC8& aLocalName,
 const TDesC8& aNamespaceUri  = KNullDesC8) const;
-/**
+	/**
-* Links attribute into tree
+	Adds an attribute to this element.  If an attribute of the same name
-*
+	exists, it will be destroyed.
-* @since S60 v3.1
-	 * @param aNewAttr new attribute
+	@param aNewAttr The new attribute
-*
+	@leave KXmlEngErrNullNode The element or attribute is NULL
-* The replaced attribute node is not returned and just deleted
+	@leave - One of the system-wide error codes
 */
 IMPORT_C void  SetAttributeNodeL(TXmlEngAttr aNewAttr);
 };
+#include <xml/dom/xmlengelement.inl>
-#include "xmlengelement.inl"
+#endif /* XMLENGELEMENT_H */
-#endif /* XMLENGINE_ELEMENT_H_INCLUDED */

branch	Symbian3
changeset 4	837f303aceeb
parent 3	e1b950c65cb4