--- a/epoc32/include/xml/dom/xmlengelement.h Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/xml/dom/xmlengelement.h Wed Mar 31 12:33:34 2010 +0100
@@ -1,995 +1,1057 @@
/*
-* 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 "XmlEngAttr.h"
-#include "XmlEngNamespace.h"
+#include <xml/dom/xmlengattr.h>
+#include <xml/dom/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
- */
+This class represents an XML element in the DOM tree.
+
+Namespace handling:
+
+The namespace of a XML element is an URI that in pair with the local part of
+the element's name consistute the @c expanded-name of the element. It is said
+that "the element is of NNN namespace".
+
+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
+element, where it was declared and all its child (sub-)elements.
+
+Namespace declaration is created by using a special @c xmlns:{prefix-name}
+attribute (which is not really considered as an 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 @c default namespace.
+
+Implementation notes:
+- Elements having no namespace are either presented with a NULL
+ TXmlEngNamespace node or a TXmlEngNamespace node that has NULL (KNullDesC8)
+ prefix and namespace URI set to "" (an empty descriptor). 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 (KNullDesC8), not an "" (empty
+ descriptor). An empty descriptor which 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 "xml" 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 "" (an empty descriptor) only for default namespace. In
+ other words, "" namespace URI may not be bound to non-NULL prefix.
+
+ Declaration of "" (an empty descriptor) namespace with NULL (KNullDesC8)
+ prefix results in:
+ @code
+ <a xmlns=""> ... </a>
+ @endcode
+ which undeclares 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.
+
+- IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no
+ prefix, its namespace is undeclared 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 attr belongs to namespace pointed to with @c ns_uri.
+
+HINTS:
+- Use namespace declaration nodes as much as possible (but watch out for prefix collisions).
+- Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
+ any other namespace declarations in a element -- they will be found faster in
+ namespace lookups.
+
+For more informarion on NULL and NULL nodes:
+@see TXmlEngNode
+@see KNullDesC8
+*/
class TXmlEngElement : public TXmlEngNode
{
public:
- /**
- * Default constructor for automatic variables (not initialized)
- *
- * @since S60 v3.1
- */
+ /** Default constructor */
inline TXmlEngElement();
/**
- * Constructor
- *
- * @since S60 v3.1
- * @param aInternal element pointer
- */
+ Constructor
+ @param aInternal element pointer
+ */
inline TXmlEngElement(void* aInternal);
- /**
- * @name XmlEngine's non-DOM extensions
- */
- /** @{ */
+ /*
+ Extensions to the DOM Level 3 Core methods
+ */
/**
- * 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
- */
+ Retrieves a list of the attribute nodes of an element
+
+ Upon return, aList is initialized and 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
+
+ If there are no attributes the list will be empty.
+
+ @param aList An attribute list to initialize
+ */
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.)
- */
+ Retrieves a list of child elements of an element.
+
+ Upon return, aList is initialized and is ready for use with HasNext() and
+ Next() methods.
+
+ Note: This returns a list of the child element nodes only.
+
+ There is no affect if the element attributes are empty.
+
+ @param aList A child list to initialize
+ */
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 ""
- */
+ /**
+ Creates a new attribute node outside of any namespace (i.e. it has no
+ prefix), sets the attribute's value and links it as the last attribute of
+ the current element.
+
+ Note:
+ - No checks are made that an attribute with the same 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)
+ - The attribute's value is the second argument in all AddNewAttributeL() methods
+
+ When adding the first attribute, use TXmlEngNode::SetAsFirstSibling() on the attribute:
+ @code
+ TXmlEngElement el = ... ; // get some element
+ el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
+ @endcode
+
+ Copies are taken of descripters passed in.
+
+ @see SetAsLastSibling()
+ @see MoveBeforeSibling(TXmlEngNode)
+ @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
- *
- * 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.
- */
+ Creates a new attribute node and adds it to the element.
+
+ The provided namespace declaration is used to set the attribute's namespace.
+
+ Note: If aNsDef is not defined in some of the attribute's ascendants
+ (including this element), then the ReconcileNamespacesL() method must be
+ called on this element later.
+
+ Copies are taken of descripters passed in.
+
+ @param aName The local name of attribute
+ @param aValue Value to set for new attribute or KNullDesC8
+ @param aNsDef Namespace to add to the attribute
+ @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 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)
- */
+ /**
+ Creates a new attribute for the element. A namespace declaration for the
+ attribute namespace is also created.
+
+ Note: Namespace declarations are reused if possible (no redundant ones are
+ created)
+
+ Copies are taken of descripters passed in.
+
+ @param aName The local name of attribute
+ @param aValue Value to set for the new attribute or an empty string
+ @param aNsUri Namespace URI
+ @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),
- * 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)
- */
+ /**
+ Creates a new attribute node using the namespace of its parent element
+ (this element), sets the attribute's value and links it as the last
+ attribute of the element
+
+ For more hints how to use it @see AddNewAttributeL(const TDesC8&,const TDesC8&)
+
+ Note:
+ - No checks are made that an attribute with the same name exists
+ - 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
+ (It is due to the fact that default namespaces do not spread on unprefixed attributes,
+ see http://w3.org/TR/REC-xml-names/#defaulting)
+
+ Copies are taken of descripters passed in.
+ @see KNullDesC8
+
+ @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
- *
- * @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
- */
+ Creates a new attribute using the namespace which is bound to the specified prefix
+
+ Use this mothod only for construction of new parts of DOM tree where
+ you know for sure that the 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 the 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 the 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
+
+ Copies are taken of descripters passed in.
+
+ @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
+ @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
- *
- * 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&)
- */
+ Creates new attributes using the namespace in scope, which has the specified URI
+
+ Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI
+
+ @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
+
+ Copies are taken of descripters passed in.
+ @see KNullDesC8
+
+ @param aLocalName The local name of the attribute
+ @param aValue Value to set for new attribute or empty string.
+ @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.
- *
- * 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.
- */
+ /**
+ Adds attribute to element that will be used as Xml:Id. Does not check if
+ an attribute with the same name exists.
+
+ Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register
+ existed id's in the document. If the ids are not registered the ID will
+ not be added to the element.
+
+ Copies are taken of descripters passed in.
+
+ @param aLocalName Name of the attribute
+ @param aValue Value of the attribute
+ @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
- *
- * @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!
- */
+ /**
+ Adds a child element with no namespace. This results in adding an 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 elements from the 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 the new
+ element to inherit the default namespace use:
+
+ @code
+ ...
+ TXmlEngNamespace defns = element.DefaultNamespace();
+ TXmlEngElement newEl = element.AddNewElementL("Name",defns);
+ ...
+ @endcode
+
+ 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
+ USE this method if there is a default namespace in the scope!
+ @see AddNamespaceDeclarationL
+
+ 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
- *
- * @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)
- */
+ /**
+ Creates a new child element with the provided name and namespace
+ declaration and adds it as the last child of its parent.
+
+ Copies are taken of descripters passed in.
+
+ @param aLocalName The name of the element
+ @param aNsDecl 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
+ @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
- *
- * 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)
- */
+ /**
+ Creates a new child element with provided the name, prefix and namespace
+ URI and adds it as the last child of its parent.
+
+ The new namespace declaration will be attached to the parent (this) element
+ and used as the namespace for newly created child element. If such a
+ binding already exists (same prefix is bound to same URI), it will be
+ reused. If the prefix is already bound to some other namespace URI, it will
+ be rebound by the new namespace declaration node.
+
+ Copies are taken of descripters passed in.
+
+ @param aLocalName Name of the element
+ @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
- *
- * @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)
- */
+ /**
+ 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.
+
+ Copies are taken of descripters passed in.
+
+ @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
- * 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)
- */
+ /**
+ Performs a lookup for the namespace declaration for the specified prefix
+ and adds a new child element with the found namespace as the last child of
+ its parent.
+
+ @pre The prefix is bound
+
+ Copies are taken of descripters passed in.
+
+ @param aLocalName The element's name
+ @param aPrefix The prefix to use for the search
+ @return The created 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
- * 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)
- */
+ /**
+ Performs a lookup for the namespace declaration for the specified namespace
+ URI and adds a new child element with the found namespace. The new element
+ is added as the last child of this element.
+
+ Copies are taken of descripters passed in.
+
+ @pre A namespace with the given URI has been declared
+
+ @param aLocalName The element's name
+ @param aNsUri The namespace of the element
+ @return The created 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,
- * 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.
- */
+ /**
+ Creates a new child element. If there is no a prefix binding for the new
+ element's namespace, a namespace decaration is created with a generated
+ prefix at the specified element.
+
+ The location of the namespace declaration may be controlled with
+ aNsDeclTarget:
+
+ @code
+ el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // 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 the namespace declaration lookups take.
+
+ Copies are taken of descripters passed in.
+
+ @param aLocalName Name of the element to create
+ @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.
- * 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()
- */
+ /**
+ Gets element content. This method may be used in most cases when the element
+ has only simple text content (without entity references embedded). If the
+ element's contents is mixed (other types of nodes present), only the contents
+ of the first child node is returned (if it is a TXmlEngTextNode node).
+
+ For getting the contents of an element that has contents containing entity
+ references, WholeTextValueCopyL() should be used.
+
+ @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.
- *
- * @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
- */
+ Adds text as a child of the element to the end of the list of children.
+
+ Note: There may be several TXmlEngTextNode and TXmlEngEntityReference
+ nodes added, depending on the aString value. For example, if the curernt
+ node has text and attributes, a text node and attribute nodes will
+ be added.
+
+ 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.
- * 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&)
- */
+ Sets text contents for the element. Any child nodes are removed.
+ This function is the same as TXmlEngNode::SetValueL(TDesC8&)
+
+ @see TXmlEngNode::SetValueL(TDesC8&)
+
+ @param aString Text to be set as element's content.
+ @leave KXmlEngErrNullNode Element is NULL
+ @leave - One of the system-wide error codes
+ */
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&)
- */
+ Sets the text content of the element from an escaped string.
+ @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
+
+ @param aEscapedString New value
+ @leave KXmlEngErrNullNode Element is NULL
+ @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.
- * 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);
- */
+ /**
+ Sets the new element value exactly as presented in the string. Predefined
+ entities are not converted into the characters they represent. Any child
+ nodes are removed.
+
+ @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
+
+ @param aNotEncString New string value
+ @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.
- * 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);
- */
+ /**
+ Appends a new text node with the value exactly as presented in the string.
+ Predefined entities are not converted into the characters they represent.
+ Existing child nodes are not removed.
+
+ @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
+
+ Copies are taken of descripters passed in.
+
+ @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.
- *
- * 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!
- */
+ /**
+ Adds a namespace declaration to the current element: a binding of prefix to namespace URI.
+
+ If the same namespace declaration exists (same prefix and URI), a redundant
+ namespace declaration will not be created.
+
+ Both KNullDesC8 or an empty descriptor may be used for "UNDEFINED URI"
+ and "NO PREFIX" values of arguments. Please refer to the class
+ documentation for more specific information.
+ @see TXmlEngElement
+ @see KNullDesC8
+
+ Note: Undeclaring of default namespace (xmlns="") is supported by
+ the SetNoDefaultNamespace() method.
+ @see SetNoDefaulNamespace()
+
+ Note: Adding a namespace declaration that rebinds the prefix mapping (or
+ default namespace) used by nodes lower in the tree may damage the document
+ tree because references to namespace declarations are not updated.
+ However, after serialization, the document will have the desired structure.
+ Use this method with care!
+
+ Copies are taken of descripters passed in.
+
+ @param aNsUri Namespace URI, KNullDesC8 or an empty descriptor.
+ @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.
- *
- * @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.
- */
+ Adds a default namespace declaration.
+
+1
+ This achieves the same result as with AddNamespaceDeclarationL(aNsUri,
+ 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
+ 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.
- *
- * 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();
+ Undeclares any default namespace for this element and its descendants.
+
+ If there is already a default namespace, a @c xmlns="" namespace
+ declaration is added. Otherwise, nothing happens, since elements with no
+ prefix in such scope are automaticaly considered outside of any namespace.
+
+ The side effect of this method is that the namespace of the current element
+ may change from the previous default namespace to a NULL TXmlEngNamespace,
+ which is considered an absence of namespace.
+
+ If the element has a prefix (i.e. not having default namespace), then the
+ only effect for the element is undeclaration of existing default namespace.
+
+ If the element is in the scope of another @c xmlns="" undeclaration, no
+ action is taken.
+
+ Note: Use AddNamespaceDeclarationL(KNullDesC8,KNullDesC8) to force the creation of a @c
+ xmlns="" declaration within the 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
+ descendants' 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.
- /**
- * 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.
- */
+ @see KNullDesC8
+
+ @leave KXmlEngErrNullNode Element is NULL
+ @leave - One of the system-wide error codes
+ */
+ IMPORT_C void SetNoDefaultNamespaceL();
+
+ /**
+ Finds the namespace declaration that has a specific prefix in the list of parents for
+ this element.
+
+ If no prefix is specified (an empty descriptor or KNullDesC8) then it is
+ considered to be a "NO PREFIX" search. Therefore, if the namespace
+ declaration for "no prefix" is searched, then the default namespace is
+ returned.
+
+ 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
- * 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
- */
+ /**
+ Finds a namespace declaration that has a specific namespace URI in the
+ scope for the given node.
+
+ KNullDesC8 value of aUri is equivalent to an empty descriptor and means
+ "UNDEFINED NAMESPACE".
+ For such URI's a NULL namespace handle is always returned even if there is
+ a namespace undeclaration, which has an empty descriptor URI (and KNullDesC8
+ prefix).
+
+ Hint: Use the returned instance of TXmlEngNamespace as the aNsDef argument
+ to an element's methods that create new child elements and attributes. The
+ same TXmlEngNamespace may be used on deeper descentants of the reference
+ element (and doing this way will generally increase performance of DOM tree
+ construction). However, if namespace bindings are not controlled for the
+ element's children and the prefix (which is bound to the search namespace)
+ is rebound to some other namespace URI, then reusing the namespace may lead
+ to unwanted result.
+
+ Note: At the moment it is possible to retrieve namespace declaration nodes
+ whose prefixes were rebound. Be careful when using returned
+ TXmlEngNamespace objects for creation of new elements.
+
+ Copies are taken of descripters passed in.
+
+ @param aUri Namespace URI, for which the namespace declaration is searched
+ @return The namespace declaration that binds the given namespace URI to a
+ prefix or sets it as a default namespace
+ @leave - One of the system-wide error codes
+ */
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.
- */
+ /**
+ Retrieves the implicitly declared XML infoset binding of the 'xml' prefix
+ to XML's namespace URI: "http://www.w3.org/XML/1998/namespace"
+
+ The result should be used for creating attributes beloging to the XML namespace
+ (xml:lang, xml:space, xml:id , etc.)
+
+ DO NOT USE the methods LookupNamespaceByUriL(const TDesC8&) and
+ LookupNamespaceByPrefixL(const TDesC8&) (with the arguments
+ "http://www.w3.org/XML/1998/namespace" and "xml" respectively) for
+ retrieving the namespace node, since in the case of a memory allocation
+ fault, a NULL result is returned (and breaks your program silently)
+
+ Note: Normally the 'xml' prefix is bound to the XML namespace URI in the
+ document node, BUT if this element 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.
+
+ @return The namespace matching the prefix binding
+ {xml,"http://www.w3.org/XML/1998/namespace"} in the current document
+ @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.
- *
- * @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
- */
+ /**
+ Get the default namespace for the element.
+
+ A NULL TXmlEngNamespace means that an element with no prefix
+ has no namespace associated with it because no default namespace was declared or
+ the default namespace was undeclared with @c xmlns=""
+
+ This function is equivalent to LookupNamespaceByPrefixL(KNullDesC8).
+ @see KNullDesC8
+
+ @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
- * 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)
- */
+ /**
+ Performs a search for the namespace in the scope of the element. This
+ method will create new namespace declaration on the element if such
+ namespace is not found.
+
+ 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.
+ @see TXmlEngAttr
+ @see TXmlEngNamespace
+ Please read the documentation for this class:
+ @see TXmlEngElement
+
+ Copies are taken of descripters passed in.
+
+ @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
- * 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
- */
+ /**
+ Performs a search on the element and its ascendants for any namespace
+ declaration with a given URI. Creates a new namespace declaration with a
+ (unique) prefix if the search was not successful.
+ @see AddNamespaceDeclarationL
+
+ Copies are taken of descripters passed in.
+
+ @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)
- *
- * 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
- */
+ Checks whether a prefix has been bound in this element (not in one of its ascendants)
+
+ Use this method for preventing prefix-name collision in a element node
+
+ Copies are taken of descripters passed in.
+
+ @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
- *
- * 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
- */
+ Copies the element with its attributes, but not child nodes
+
+ If the context is preserved (preserveNsContent), then all namespace
+ declarations that are in the element are writen to the <element ...> tag.
+
+ @param preserveNsContext Whether the namespace context should be preserved
+ @return The copied 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()
- *
- * @since S60 v3.1
- * @return Deep copy of the element.
- */
+ Specialized version of TXmlEngNode::CopyL()
+ @return Deep copy of the element.
+ @leave KXmlEngErrNullNode The element is NULL
+ @leave - One of the system-wide error codes
+ */
inline TXmlEngElement CopyL() const;
- /**
- * Resets element's content: all child nodes are removed
- *
- * @since S60 v3.1
- */
+ /** Resets element's content: all child nodes are removed */
IMPORT_C void RemoveChildren();
- /**
- * Resets element's attributes
- *
- * @since S60 v3.1
- */
+ /** Resets element's attributes */
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);
+ Resets all namespace declarations made in the element
+
+ Note: There can be references to these namespace declarations elsewhere!
+ Use ReconcileNamespacesL() to fix that.
+ */
+ IMPORT_C void RemoveNamespaceDeclarations();
/**
- * 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()
- */
+ Removes all element contents: child nodes, attributes and namespace declarations
+
+ @see RemoveChildren()
+ @see RemoveAttributes()
+ @see RemoveNamespaceDeclarations();
+ */
+ inline void ClearElement();
+
+ /**
+ Copies attributes from another element. 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
+ copied attributes belong to any namespace that is not declared on some
+ ascendant of this node. @see ReconcileNamespacesL()
+
+ @param aSrc Source element
+ @leave KXmlEngErrNullNode The element is NULL
+ @leave - One of the system-wide error codes
+ */
+ IMPORT_C void CopyAttributesL(TXmlEngElement aSrc);
+
+ /**
+ Recursively copies the children (and all of it's associated information)
+ from another element. Elements are appended to the current element's
+ children list.
+
+ Note: Namespaces of 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).
- * Memory allocated for the attribute is freed.
- *
- * @since S60 v3.1
- * @param aLocalName Element name
- * @param aNamespaceUri Element namespace
- */
+ /**
+ Removes the child element with the given name and namespace URI (if it exists).
+ Memory allocated for the element is freed.
+
+ @param aLocalName Child element name
+ @param aNamespaceUri Child 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
- *
- * @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.
+ @param aLocalName The new element name
+ @param aNamespaceUri The new namespace URI
+ @param aPrefix The new namespace prefix
+ @leave - One of the system-wide error codes
+ */
+ IMPORT_C void RenameElementL(const TDesC8& aLocalName, const TDesC8& aNamespaceUri, const TDesC8& aPrefix);
+
+ /*
+ DOM Level 3 Core methods
+
+ 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
- */
+ 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.
- *
- * @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
- */
+ Initializes list of child elements with matching names and namespace URIs.
+
+ Note: This method does not list all descendants of the element, only child elements
+ @see KNullDesC8
+
+ @param aList Node list to be created
+ @param aLocalName Element name
+ @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
- *
- * @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)
- */
+ /**
+ Sets the value of the given attribute. The attribute is created if there
+ is no such attribute yet.
+
+ Note: If prefix is not KNullDesC8 (or an empty descriptor),
+ then the namespace URI may not be empty see
+ http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
+
+ Copies are taken of descripters passed in.
+ @see KNullDesC8
+
+ @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).
- * 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
- */
+ /**
+ Removes the attribute with the given name and namespace URI (if it exists).
+ Memory allocated for the attribute is freed.
+
+ @see KNullDesC8
+
+ @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.
- *
- * @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
- */
+ /**
+ Retrieves an attribute node with a specific namespace by its name.
+
+ @see KNullDesC8
+
+ @param aLocalName Name of the attribute
+ @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.
- *
- * @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()
- */
+ Check if the element has an attribute with given parameters.
+
+ This function is the same as AttributeNodeL(uri,name).NotNull().
+
+ @see KNullDesC8
+
+ @param aLocalName Name of attribute
+ @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
- *
- * @since S60 v3.1
- * @param aNewAttr new attribute
- *
- * The replaced attribute node is not returned and just deleted
- */
+ /**
+ Adds an attribute to this element. If an attribute of the same name
+ exists, it will be destroyed.
+
+ @param aNewAttr The new attribute
+ @leave KXmlEngErrNullNode The element or attribute is NULL
+ @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 */