--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/xmldomandxpath/inc/xmlenginedom/xmlengelement.h Thu Dec 17 09:29:21 2009 +0200
@@ -0,0 +1,1057 @@
+/*
+* 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 "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:
+*
+*/
+
+/** @file
+@publishedAll
+@released
+*/
+#ifndef XMLENGELEMENT_H
+#define XMLENGELEMENT_H
+
+#include <xml/dom/xmlengattr.h>
+#include <xml/dom/xmlengnamespace.h>
+
+template<class T> class RXmlEngNodeList;
+
+
+/**
+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 */
+ inline TXmlEngElement();
+
+ /**
+ Constructor
+ @param aInternal element pointer
+ */
+ inline TXmlEngElement(void* aInternal);
+
+ /*
+ Extensions to the DOM Level 3 Core methods
+ */
+
+ /**
+ 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 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 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 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 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 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 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 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);
+
+ /**
+ 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 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 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 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);
+
+ /**
+ 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 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 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 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);
+
+ /**
+ 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 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.
+ 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 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 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 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 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 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 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.
+
+ @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 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 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 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 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 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 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 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()
+ @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 */
+ IMPORT_C void RemoveChildren();
+
+ /** Resets element's attributes */
+ IMPORT_C void RemoveAttributes();
+
+ /**
+ 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();
+
+ /**
+ 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 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.
+
+ @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 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 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 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 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 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 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;
+
+ /**
+ 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>
+
+#endif /* XMLENGELEMENT_H */
+