1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/xml/dom/xmlengelement.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,995 @@
1.4 +/*
1.5 +* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Element node functions
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +#ifndef XMLENGINE_ELEMENT_H_INCLUDED
1.28 +#define XMLENGINE_ELEMENT_H_INCLUDED
1.29 +
1.30 +#include "XmlEngAttr.h"
1.31 +#include "XmlEngNamespace.h"
1.32 +
1.33 +template<class T> class RXmlEngNodeList;
1.34 +
1.35 +
1.36 +/**
1.37 + * Instance of TXmlEngElement class represents an XML element in the DOM tree.
1.38 + *
1.39 + * <b>Namespace handling:</b>
1.40 + *
1.41 + * Namespace of XML element is an URI that in pair with <i>local part</i> of
1.42 + * element's name consistute <b>expanded-name</b> of element. It is said that "the element
1.43 + * is of <i>NNN</i> namespace".
1.44 + *
1.45 + * XML elements are shown as belonging to a specific namespace by using <i>prefixes</i>
1.46 + * that previously were bound to some namespace URIs. The scope of a prefix is the
1.47 + * element, where it was declared and all its child (sub-)elements.
1.48 + *
1.49 + * Namespace declaration is created by using special <b>xmlns:<i>{prefix-name}</i></b>
1.50 + * attribute (which is not really considered as attribute in DOM):
1.51 + * @code
1.52 + * <a xmlns:pr="http://some.uri.com/"> ... </a>
1.53 + * OR
1.54 + * <pr:a xmlns:pr="http://some.uri.com/"> ... </a>
1.55 + * <a xmlns="http://some.uri.com/"> ... </a>
1.56 + * @endcode
1.57 + *
1.58 + * The latter two examples are equivalent and show the use of <i>default namespace</i>.
1.59 + *
1.60 + * Implementation notes:
1.61 + * - Element having no namespace is either presented with a NULL TXmlEngNamespace node
1.62 + * or a TXmlEngNamespace node that has NULL prefix and namespace URI set to "".
1.63 + * The former is used by default on all nodes, whereas the latter is for cases
1.64 + * when some node contains undeclaration of the default namespace:
1.65 + * @code
1.66 + * <a xmlns=""> .. </a>
1.67 + * @endcode
1.68 + *
1.69 + * - The prefix of the default attribute is NULL, not "" (zero-length string)
1.70 + * "" corresponds to
1.71 + * @code
1.72 + * <a xmlns:="http://some.uri.com/"> ... </a>
1.73 + * @endcode
1.74 + * (it does not contradict XML spec, but you are strongly advised against using this)
1.75 + *
1.76 + * - Prefix <b>"xml"</b> is reserved by XML Namespace spec for special purposes; it is implicitly bound
1.77 + * to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> and no one is allowed
1.78 + * to use this prefix except as with spec-defined elements and attributes or to rebind this
1.79 + * prefix to other namespaces
1.80 + *
1.81 + * - Namespace URI may be "" only for default namespace. In other words,
1.82 + * "" namespace URI may not be bound to non-NULL prefix.
1.83 + *
1.84 + * Declaration of "" namespace with NULL prefix results in:
1.85 + * @code
1.86 + * <a xmlns=""> ... </a>
1.87 + * @endcode
1.88 + * which <i>undeclares</i> any existing (in some parent element) default namespace
1.89 + * for the scope of element 'a': element, its attributes and all child nodes of DOM tree.
1.90 + * Note, that such "undeclaration" will be added only if neccessary.
1.91 + *
1.92 + * - Unneccessary namespace declaration are ignored. Attemps to add namespace binding
1.93 + * using same namespace URI and prefix if such binding already exists in the scope
1.94 + * will have no effect.
1.95 + *
1.96 + * - <b>IMPORTANT!</b> Attributes DO NOT HAVE default namespaces. If an attribute has no
1.97 + * prefix, its namespace is <b>undeclared</b> even if there is some default namespaces for
1.98 + * the scope of the element, which contains the attribute.
1.99 + *
1.100 + * So, it is wrong to write something like this:
1.101 + * @code
1.102 + * <a xmlns="ns_uri" attr="value"> ... </a>
1.103 + * @endcode
1.104 + * and assume that the <b>attr</b> belongs to namespace pointed to with <i>ns_uri</i>.
1.105 + *
1.106 + * <b>HINTS:</b>
1.107 + * - Use namespace declaration nodes as much as possible (but watch out prefix collisions).
1.108 + * - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
1.109 + * any other namespace declarations in a element -- the will be found faster in
1.110 + * namespace lookups.
1.111 + *
1.112 + * @lib XmlEngineDOM.lib
1.113 + * @since S60 v3.1
1.114 + */
1.115 +
1.116 +class TXmlEngElement : public TXmlEngNode
1.117 +{
1.118 + public:
1.119 + /**
1.120 + * Default constructor for automatic variables (not initialized)
1.121 + *
1.122 + * @since S60 v3.1
1.123 + */
1.124 + inline TXmlEngElement();
1.125 +
1.126 + /**
1.127 + * Constructor
1.128 + *
1.129 + * @since S60 v3.1
1.130 + * @param aInternal element pointer
1.131 + */
1.132 + inline TXmlEngElement(void* aInternal);
1.133 +
1.134 + /**
1.135 + * @name XmlEngine's non-DOM extensions
1.136 + */
1.137 + /** @{ */
1.138 +
1.139 + /**
1.140 + * Retrieves list of attribute nodes of the element
1.141 + *
1.142 + * @param aList - a node list object to initialize
1.143 + *
1.144 + * Passed by reference list of nodes is initialized and after call to
1.145 + * Attributes(..) is ready for use with HasNext() and Next() methods:
1.146 + *
1.147 + * @code
1.148 + * ...
1.149 + * TXmlEngElement root = doc.DocumentElement();
1.150 + * RXmlEngNodeList<TXmlEngAttr> attlist;
1.151 + * root.GetAttributes(attlist);
1.152 + * while (attlist.HasNext())
1.153 + * processAttribute(attlist.Next());
1.154 + * ...
1.155 + * attlist.Close();
1.156 + * @endcode
1.157 + *
1.158 + * @since S60 v3.1
1.159 + */
1.160 + IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;
1.161 +
1.162 + /**
1.163 + * Retrieves list of child elements of the element
1.164 + *
1.165 + * @since S60 v3.1
1.166 + * @param aList - a node list object to initialize
1.167 + *
1.168 + * Passed by reference list of nodes is initialized and after the call
1.169 + * it is ready for use with HasNext() and Next() methods:
1.170 + *
1.171 + * @note Returned list is a "filtered view" of the underlying
1.172 + * list of all element's children (with text nodes, comments
1.173 + * processing instructions, etc.)
1.174 + */
1.175 + IMPORT_C void GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const;
1.176 +
1.177 + /**
1.178 + * Creates new attribute node out of any namespace (i.e. it has no prefix),
1.179 + * sets attribute's value and links it as the last attribute of the current element
1.180 + *
1.181 + * @since S60 v3.1
1.182 + * @param aName A local name of attribute
1.183 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.184 + * @return A handler to the newly created attribute node;
1.185 + *
1.186 + * For adding attribute as the first one, use TXmlEngNode::SetAsFirstSibling() on the attribute:
1.187 + * @code
1.188 + * TXmlEngElement el = ... ; // get some element
1.189 + * el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
1.190 + * @endcode
1.191 + *
1.192 + * @see SetAsLastSibling(), MoveBeforeSibling(TXmlEngNode) and MoveAfterSibling(TXmlEngNode)
1.193 + *
1.194 + * @note - No checks are made that attribute with such name exists
1.195 + * Use this method only on newly created elements!
1.196 + * Otherwise, use TXmlEngElement::SetAttributeL(..)
1.197 + * - Attributes do not inherit default namespace of its element
1.198 + * (http://w3.org/TR/REC-xml-names/#defaulting)
1.199 + * - attribute's value is the second argument in all AddNewAttributeL(..) methods
1.200 + * - Use of NULL as value is more preferrable then ""
1.201 + */
1.202 + IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);
1.203 +
1.204 + /**
1.205 + * Creates new attribute node and add it to the element
1.206 + *
1.207 + * Provided handle to namespace declaration is used to set up
1.208 + * attribute's namespace.
1.209 + *
1.210 + * @since S60 v3.1
1.211 + * @param aName A local name of attribute
1.212 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.213 + * @param aNsDef Namespace to add to the attribute
1.214 + * @return A handler to the newly created attribute node;
1.215 + *
1.216 + * @note If aNsDef is not defined in some of attributes ascendants
1.217 + * (including this element), then
1.218 + * ReconcileNamespacesL() method must be called on
1.219 + * this element later.
1.220 + */
1.221 + IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
1.222 + const TDesC8& aValue,
1.223 + const TXmlEngNamespace aNsDef);
1.224 +
1.225 + /**
1.226 + * Creates new attribute on the element. Namespace declaration for the attribute namespace is
1.227 + * created too.
1.228 + *
1.229 + * @since S60 v3.1
1.230 + * @param aName A local name of attribute
1.231 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.232 + * @param aNsUri Namespace uri
1.233 + * @param aPrefix Namespace prefix
1.234 + * @return A handler to the newly created attribute node;
1.235 + *
1.236 + * @note
1.237 + * - Namespace declarations are reused if possible (no redundant ones are created)
1.238 + */
1.239 + IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
1.240 + const TDesC8& aValue,
1.241 + const TDesC8& aNsUri,
1.242 + const TDesC8& aPrefix);
1.243 +
1.244 + /**
1.245 + * Creates new attribute node using namespace of its parent element (this element),
1.246 + * sets attribute's value and links it as the last attribute of the element
1.247 + *
1.248 + * @since S60 v3.1
1.249 + * @param aName Local name of attribute
1.250 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.251 + * @return A handler to the newly created attribute node;
1.252 + *
1.253 + * For more hints how to use it refer to AddNewAttributeL(const TDesC8&,const TDesC8&)
1.254 + *
1.255 + * @note
1.256 + * - No checks are made that attribute with such name exists
1.257 + * - if namespace of the parent element is default (i.e. bound prefix is NULL),
1.258 + * then temporary prefix will be used and bound to the same namespace URI as elements
1.259 + * (It is due to the fact that default namespaces do not spread on unprefixed attributes,
1.260 + * see http://w3.org/TR/REC-xml-names/#defaulting)
1.261 + */
1.262 + inline TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);
1.263 +
1.264 + /**
1.265 + * Creates new attributes using namespace, which is bound to the specified prefix
1.266 + *
1.267 + * @since S60 v3.1
1.268 + * @param aLocalName A local name of attribute
1.269 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.270 + * @param aPrefix Namespace prefix for new attribute
1.271 + * @return A handler to the newly created attribute node;
1.272 + *
1.273 + * Use this mothod only for construction of new parts of DOM tree, where
1.274 + * you know for sure that prefix is bound in the given scope.
1.275 + * @code
1.276 + * TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
1.277 + * el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
1.278 + * @endcode
1.279 + *
1.280 + * Otherwise, you should check that prefix is bound like this example shows:
1.281 + * @code
1.282 + * TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
1.283 + * if (boundNS.NotNull()){
1.284 + * thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
1.285 + * }
1.286 + * @endcode
1.287 + *
1.288 + * @note
1.289 + * Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because
1.290 + * it is most efficient way to create namespaced DOM elements (no additional
1.291 + * lookups for namespace declarations are required).
1.292 + *
1.293 + * @code
1.294 + * // If namespace with given URI is not in the scope, then it will be declared
1.295 + * // and bound to "data" prefix.
1.296 + * TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
1.297 + * elem.AddNewAttributeL("location", "...", nsDef);
1.298 + * elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
1.299 + * // the result is
1.300 + * ...
1.301 + * <elem xmlns:data="http://../Data" data:location="...">
1.302 + * <data:child attr="...value..."/>
1.303 + * </elem>
1.304 + * ...
1.305 + * //
1.306 + * @endcode
1.307 + */
1.308 + IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName,
1.309 + const TDesC8& aValue,
1.310 + const TDesC8& aPrefix);
1.311 +
1.312 + /**
1.313 + * Creates new attributes using namespace in the scope, which has specified URI
1.314 + *
1.315 + * Almost the same as AddNewAttributeUsePrefixL(...) but does lookup by namespace URI
1.316 + *
1.317 + * @since S60 v3.1
1.318 + * @param aLocalName A local name of attribute
1.319 + * @param aValue Value to set for new attribute or NULL (sets value to "")
1.320 + * @param aNsUri Namespace uri for new attribute
1.321 + * @return - NULL attribute if namespace declaration is not found OR newly added to the end of
1.322 + * attribute list attribute of this element.
1.323 + *
1.324 + * @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
1.325 + */
1.326 + IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName,
1.327 + const TDesC8& aValue,
1.328 + const TDesC8& aNsUri);
1.329 +
1.330 + /**
1.331 + * Add attribute to element that will be used as Xml:Id.
1.332 + *
1.333 + * No check if such attribute exists are made.
1.334 + *
1.335 + * @since S60 v3.2
1.336 + * @param aLocalName Name of attribute that should be add.
1.337 + * @param aValue Value of the attribute
1.338 + * @param aNs Namespace of the attribute
1.339 + * @return Attribute if created. Null attribute if Id exist
1.340 + *
1.341 + * @note Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first
1.342 + * to register existed id's in the document.
1.343 + */
1.344 + IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,
1.345 + const TDesC8& aValue,
1.346 + TXmlEngNamespace aNs = TXmlEngNamespace());
1.347 +
1.348 + /**
1.349 + * Adds child element with no namespace
1.350 + *
1.351 + * @since S60 v3.1
1.352 + * @param aName name of the element
1.353 + * @return A handler to the newly created element node;
1.354 + *
1.355 + * Results in adding element with aName and no prefix.
1.356 + *
1.357 + * This method is the best for creation of non-namespace based documents
1.358 + * or document fragments, where no default namespace declared.
1.359 + *
1.360 + * It may be used also as a method for adding element from default namespace,
1.361 + * BUT namespace will be assigned ONLY after serialization of the current
1.362 + * document and parsing it back into a DOM tree!! If you need that default namespace
1.363 + * was inherited by new element immediately use:
1.364 + * @code
1.365 + * ...
1.366 + * TXmlEngNamespace defns = element.DefaultNamespace();
1.367 + * TXmlEngElement newEl = element.AddNewElementL("Name",defns);
1.368 + * ...
1.369 + * @endcode
1.370 + *
1.371 + * If truly undefined namespace for the element is required, then <b>DO NOT USE</b>
1.372 + * this method if there is a default namespace in the scope!
1.373 + */
1.374 + IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);
1.375 +
1.376 + /**
1.377 + * Creates new child element with provided name and namespace declaration
1.378 + *
1.379 + * @since S60 v3.1
1.380 + * @param aLocalName Name of the element
1.381 + * @param aNsDecl Handle of the namespace declaration, that must be retrieved from
1.382 + * one of the ascendant nodes of the new elements (and its prefix
1.383 + * should not be remapped to another namespace URI for the scope
1.384 + * of the new element)
1.385 + * @return Created element node (and added as the last child of its parent)
1.386 + */
1.387 + IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);
1.388 +
1.389 + /**
1.390 + * Creates new child element with provided name, prefix and namespace URI
1.391 + *
1.392 + * New namespace declaration will be attached to the parent (this) element and used
1.393 + * as namespace for newly created child element. If such binding already exists
1.394 + * (same prefix is bound to same URI), it will be reused. If the prefix is already
1.395 + * bound to some another namespace URI, it will be rebound by the new namespace
1.396 + * declaration node.
1.397 + *
1.398 + * @since S60 v3.1
1.399 + * @param aLocalName Name of the element
1.400 + * @param aNsUri URI of element's namespace
1.401 + * @param aPrefix Prefix of the element
1.402 + * @return Created element node (and added as the last child of its parent)
1.403 + */
1.404 + IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName,
1.405 + const TDesC8& aNsUri,
1.406 + const TDesC8& aPrefix);
1.407 +
1.408 + /**
1.409 + * Adds child element with same namespace (and prefix if present) as parent element has
1.410 + *
1.411 + * @since S60 v3.1
1.412 + * @param aLocalName element's name
1.413 + * @return New element that was added to the end of children list of its parent (this element)
1.414 + */
1.415 + IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);
1.416 +
1.417 + /**
1.418 + * Performs lookup for the namespace declaration for specified prefix and
1.419 + * adds new child element with found namespace.
1.420 + *
1.421 + * The assumption is that prefix is bound, otherwise run-time error
1.422 + * (Symbian's Leave or exception) occurs
1.423 + *
1.424 + * @note Use this method only if there is a binding for the given prefix.
1.425 + *
1.426 + * @since S60 v3.1
1.427 + * @param aLocalName element's name
1.428 + * @param aPrefix prefix to use
1.429 + * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
1.430 + */
1.431 + IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);
1.432 +
1.433 + /**
1.434 + * Performs lookup for the namespace declaration for specified namespace URI and
1.435 + * adds new child element with found namespace.
1.436 + *
1.437 + * The assumption is that namespace with given URI was declared,
1.438 + * otherwise run-time error (Symbian' Leave or exception) occurs
1.439 + *
1.440 + * @note Use this method only if namespace declaration for the provided URI exists.
1.441 + *
1.442 + * @since S60 v3.1
1.443 + * @param aLocalName element's name
1.444 + * @param aNsUri namespace of element
1.445 + * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
1.446 + */
1.447 + IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri);
1.448 +
1.449 + /**
1.450 + * Creates new child element; if there is no a prefix binding for new element's namespace,
1.451 + * a namespace decaration is created with generated prefix at specified element.
1.452 + *
1.453 + * @since S60 v3.1
1.454 + * @param aLocalName Name of the element to create
1.455 + * @param aNsUri Namespace URI of the new element
1.456 + * @param aNsDeclTarget An element where namespace declaraton should be placed
1.457 + * if there is a needed to create new namespace declaration;
1.458 + * NULL is used to specify the created element itself
1.459 + *
1.460 + * As aNsDeclTarget any ascendant of the new node may be provided:
1.461 + * @code
1.462 + * el.AddNewElementAutoPrefixL(tagName,uri,NULL); // declare on the new element
1.463 + * el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element
1.464 + * el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
1.465 + * ...
1.466 + * @endcode
1.467 + *
1.468 + * @note
1.469 + * The farther namespace declaration up in the document tree,
1.470 + * the longer time namespace declaration lookups take.
1.471 + */
1.472 + IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName,
1.473 + const TDesC8& aNsUri,
1.474 + TXmlEngElement aNsDeclTarget);
1.475 +
1.476 + /**
1.477 + * Get element content.
1.478 + * This method may be used in most cases, when element has only simple text content
1.479 + * (without entity references embedded).
1.480 + * If element's contents is mixed (other types of nodes present), only contents of
1.481 + * first child node is returned if it is a TXmlEngTextNode node. For getting mixed contents of the
1.482 + * element of contents with entity references, WholeTextValueCopyL() should be used.
1.483 + *
1.484 + * @since S60 v3.1
1.485 + * @return Basic contents of the element
1.486 + *
1.487 + * @see TXmlEngNode::WholeTextContentsCopyL()
1.488 + */
1.489 + IMPORT_C TPtrC8 Text() const;
1.490 +
1.491 + /**
1.492 + * Adds text as a child of the element.
1.493 + *
1.494 + * @since S60 v3.1
1.495 + * @param aString text to be added as element's content.
1.496 + *
1.497 + * @note There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added actually,
1.498 + * depending on the aString value
1.499 + */
1.500 + IMPORT_C void AddTextL(const TDesC8& aString);
1.501 +
1.502 + /**
1.503 + * Sets text contents for the element.
1.504 + * Any child nodes are removed.
1.505 + * Same as TXmlEngNode::SetValueL(TDesC8&)
1.506 + *
1.507 + * @since S60 v3.1
1.508 + * @param aString text to be set as element's content.
1.509 + *
1.510 + * @see TXmlEngNode::SetValueL(TDesC8&)
1.511 + */
1.512 + IMPORT_C void SetTextL(const TDesC8& aString);
1.513 +
1.514 + /**
1.515 + * Sets text content of the element from escaped string.
1.516 + *
1.517 + * @since S60 v3.1
1.518 + * @param aEscapedString New value
1.519 + *
1.520 + * @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
1.521 + */
1.522 + IMPORT_C void SetEscapedTextL(const TDesC8& aEscapedString);
1.523 +
1.524 + /**
1.525 + * Sets new element value exactly as presented in the string.
1.526 + * Predefined entities are not converted into characters they represent.
1.527 + * Any child nodes are removed.
1.528 + *
1.529 + * @since S60 v3.2
1.530 + * @param aNotEncText New element value
1.531 + *
1.532 + * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.533 + */
1.534 + IMPORT_C void SetTextNoEncL(const TDesC8& aNotEncString);
1.535 +
1.536 + /**
1.537 + * Appends new text node with the value exactly as presented in the string.
1.538 + * Predefined entities are not converted into characters they represent.
1.539 + * Existing child nodes are not removed.
1.540 + *
1.541 + * @since S60 v3.2
1.542 + * @param aNotEncText Appended element value
1.543 + *
1.544 + * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.545 + */
1.546 + IMPORT_C void AppendTextNoEncL(const TDesC8& aNotEncString);
1.547 +
1.548 + /**
1.549 + * Adds namespace declaration to the current element, a binding of prefix to namespace URI.
1.550 + *
1.551 + * If same namespace declaration exists (same prefix and URI), redundant namespace declaration
1.552 + * will not be created.
1.553 + *
1.554 + * Both NULL or "" (empty string) may be used for "UNDEFINED URI" and "NO PREFIX" values of arguments.
1.555 + *
1.556 + * @since S60 v3.1
1.557 + * @param aNsUri Namespace URI
1.558 + * @param aPrefix Namespace prefix
1.559 + * @return A handle to the created (or found, if there is such) namespace declaration node.
1.560 + * If namespace undeclaration is being created, NULL handle is returned -- it can be
1.561 + * used in node-creation methods that take namespace handle as an argument.
1.562 + *
1.563 + * @note Undeclaring of default namespace (xmlns="") is supported by
1.564 + * SetNoDefaultNamespace() method
1.565 + *
1.566 + * @see SetNoDefaulNamespace()
1.567 + *
1.568 + * @note By adding namespace declaration that rebinds prefix mapping (or default namespace)
1.569 + * used by nodes lower in the tree, document tree may become
1.570 + * wrongly constructed, because references to namespace declaration are
1.571 + * not updated. However, after serialization the document will have
1.572 + * desired structure.
1.573 + * Use this method with care!
1.574 + */
1.575 + IMPORT_C TXmlEngNamespace AddNamespaceDeclarationL(const TDesC8& aNsUri, const TDesC8& aPrefix);
1.576 +
1.577 + /**
1.578 + * Adds default namespace declaration.
1.579 + *
1.580 + * @since S60 v3.1
1.581 + * @param aNsUri Namespace URI; both NULL and "" (empty string) are allowed to represent UNDEFINED NAMSPACE
1.582 + * @return Handle to the created namespace declaration (NULL for UNDEFINED NAMESPACE)
1.583 + *
1.584 + * Same result as with AddNamespaceDeclarationL(aNsUri, NULL), but additionally
1.585 + * element's namespace modified (if it has no prefix and there were no default
1.586 + * namespace declaration in the scope) to the new default one.
1.587 + */
1.588 + IMPORT_C TXmlEngNamespace SetDefaultNamespaceL(const TDesC8& aNsUri);
1.589 +
1.590 + /**
1.591 + * Undeclares any default namespace for current element and its descendants.
1.592 + *
1.593 + * If there is already some default namespace, <i>xmlns=""</i> namespace
1.594 + * declaration is added. Otherwise, nothing happens, since element with no
1.595 + * prefix in such scope is automaticaly considered as out of any namespace.
1.596 + *
1.597 + * The side effect of this method is that namespace of the current element
1.598 + * may change from previous <b>default</b> namespace to NULL TXmlEngNamespace, which is
1.599 + * considered an absence of namespace.
1.600 + *
1.601 + * If the element has prefix (i.e. not having default namespace),
1.602 + * then the only effect for the element is undeclaration of existing default namespace.
1.603 + *
1.604 + * If element is in the scope of another <i>xmlns=""</i> undeclaration, no
1.605 + * actions are taken.
1.606 + *
1.607 + * @note
1.608 + * Use AddNamespaceDeclarationL(NULL,NULL) to force creation of
1.609 + * xmlns="" declaration within scope of another such declaration
1.610 + * (otherwise unneccessary/duplicate declarations are not created)
1.611 + *
1.612 + * @note
1.613 + * This method should be called on elements before adding children,
1.614 + * because default namespace undeclaration is not spread into its subtree and
1.615 + * descedants' default namespaces are not reset to NULL. This should be taken into
1.616 + * account if later some processing on the subtree occurs.
1.617 + * However, after serialization and deserialization, undeclared default namespace will
1.618 + * affect whole element's subtree correctly.
1.619 + *
1.620 + * @since S60 v3.1
1.621 + */
1.622 + IMPORT_C void SetNoDefaultNamespaceL();
1.623 +
1.624 + /**
1.625 + * Finds namespace declaration that has specific prefix in the scope for given node
1.626 + *
1.627 + * Prefix "" or NULL are considered the same, meaning "<b>NO PREFIX</b>".
1.628 + * If namespace declaration for "no prefix" is searched, then default namespace is returned.
1.629 + *
1.630 + * @since S60 v3.1
1.631 + * @param aPrefix Namespace prefix
1.632 + * @return Namespace handler, which may be NULL if prefix is not bound.
1.633 + *
1.634 + * NULL result for "no prefix" means that default namespace is undefined.
1.635 + */
1.636 + IMPORT_C TXmlEngNamespace LookupNamespaceByPrefixL(const TDesC8& aPrefix) const;
1.637 +
1.638 + /**
1.639 + * Finds namespace declaration that has specific namespace URI
1.640 + * in the scope for the given node.
1.641 + *
1.642 + * @since S60 v3.1
1.643 + * @param aUri Namespace URI, for which namespace declaration is searched
1.644 + * @return Handler to the namespace declaration that binds given namespace URI to some prefix
1.645 + * or sets it a default namespace.
1.646 + *
1.647 + * NULL value of aUri is equivalent to "" and means "<b>UNDEFINED NAMESPACE</b>".
1.648 + * For such URI a NULL namespace handle is always returned even if there is
1.649 + * namespace undeclaration, which has "" URI (and NULL prefix).
1.650 + *
1.651 + * <b>Hint:</b><p>
1.652 + * Use returned instance of TXmlEngNamespace as aNsDef argument to element's methods
1.653 + * that create new element's child elements and attributes. The same handler
1.654 + * may be used on more deep descentants of the reference element (and doing
1.655 + * this way will generally increase performance of DOM tree construction).<br />
1.656 + * <span class="color:red;">However</span>, if namespace bindings are not controlled
1.657 + * for element's children and prefix, which is bound to the search namespace, is
1.658 + * rebound to some other namespace URI, then reusing namespace may lead to
1.659 + * unwanted result.
1.660 + *
1.661 + * Consider an example:
1.662 + * @code
1.663 + * TXmlEngElement root = doc.DocumentElement();
1.664 + * TXmlEngNamespace targetNs = root.AddNamespaceDeclarationL("http://example.com/","ex");
1.665 + * TXmlEngElement el_1 = root.AddNewElementL("outer", targetNs);
1.666 + * TXmlEngElement el_2 = el_1.AddNewElementL("inner"); // element without prefix
1.667 + *
1.668 + * // NOTE: prefix "ex" is not bound to "http://example.com/" anymore!
1.669 + * el_2.AddNamespaceDeclarationL("http://whatever.com/","ex");
1.670 + * TXmlEngElement el_3 = el_2.AddNewElementL("problem", targetNs);
1.671 + * ...
1.672 + * @endcode
1.673 + *
1.674 + * The sought result was (showing expanded names of elements):
1.675 + * @code
1.676 + * --> "root"
1.677 + * --> {"http://example.com/","outer"}
1.678 + * --> "inner"
1.679 + * -->{"http://example.com/","problem"}
1.680 + * ...
1.681 + * <--
1.682 + * <-- "inner"
1.683 + * <-- {"http://example.com/","outer"}
1.684 + * ...
1.685 + * <-- </root>
1.686 + * @endcode
1.687 + * and it may look that it has been achieved. Indeed, if namespace of element "problem"
1.688 + * was queried, it would have URI "http://example.com/" and prefix "ex".
1.689 + * However, if namespace URI was looked up by "problem"'s prefix, it would be
1.690 + * "http://whatever.com/". We have created illegal DOM tree.
1.691 + *
1.692 + * The actual DOM tree in serialized form will be:
1.693 + * @code
1.694 + * <root>
1.695 + * <ex:outer xmlns:ex="http://example.com/">
1.696 + * <inner xmlns:ex="http://whatever.com/">
1.697 + * <ex:problem>
1.698 + * ...
1.699 + * </ex:problem>
1.700 + * </inner>
1.701 + * </ex:outer>
1.702 + * ...
1.703 + * </root>
1.704 + * @endcode
1.705 + *
1.706 + * So, reuse of namespace handlers should be performed with special care.
1.707 + *
1.708 + * @note
1.709 + * At the moment it is possible to retrieve namespace declaration nodes
1.710 + * whose prefixes were rebound. Be careful when use returned TXmlEngNamespace object
1.711 + * for creation of new elements. In later releases, this method will perform
1.712 + * safe lookup. And so far, it is better to make check that prefix of returned
1.713 + * namespace declaration has not rebound:
1.714 + * @code
1.715 + * TXmlEngNamespace ns = element.LookupNamespaceByUri("a_uri");
1.716 + * if (element.LookupNamespaceByPrefix(ns.Prefix()).IsSameNode(ns)){
1.717 + * ... // now it is safe to create new elements by using "ns"
1.718 + * element.AddNewElementL("product",ns);
1.719 + * ...
1.720 + * }
1.721 + * @endcode
1.722 + */
1.723 + IMPORT_C TXmlEngNamespace LookupNamespaceByUriL(const TDesC8& aUri) const;
1.724 +
1.725 + /**
1.726 + * Retrieves implicitly declared on every XML infoset binding
1.727 + * of 'xml' prefix to XML's namespace URI:
1.728 + * "http://www.w3.org/XML/1998/namespace"
1.729 + *
1.730 + * @since S60 v3.1
1.731 + * @return Handler to {xml,"http://www.w3.org/XML/1998/namespace"} prefix
1.732 + * binding in the current document
1.733 + *
1.734 + * The result should be used for creating attributes beloging to the XML namespace
1.735 + * (xml:lang, xml:space, xml:id , etc.)
1.736 + *
1.737 + * DO NOT USE methods LookupNamespaceByUriL(const TDesC8&) and LookupNamespaceByPrefixL(const TDesC8&)
1.738 + * (with "http://www.w3.org/XML/1998/namespace" and "xml" arguments) for retrieving
1.739 + * namespace node, since in a case of [possible] memory allocation fault
1.740 + * NULL result is returned (and breaks your program silently)
1.741 + *
1.742 + * @note Normally 'xml' prefix is bound to XML namespace URI in the document
1.743 + * node, BUT if current node is not a part of the document tree yet,
1.744 + * the requested namespace declaration WILL BE ADDED to the current node.
1.745 + * This is the reason why the method may fail in OOM conditions.
1.746 + */
1.747 + IMPORT_C TXmlEngNamespace TheXMLNamespaceL() const;
1.748 +
1.749 + /**
1.750 + * Get default namespace for element.
1.751 + *
1.752 + * @since S60 v3.1
1.753 + * @return Default namespace in the scope of the element
1.754 + *
1.755 + * NULL TXmlEngNamespace means that element with no prefix have no namespace associated
1.756 + * because no default namespace was declared or default namespace was undeclared with <b>xmlns=""</b>
1.757 + *
1.758 + * Equivalent to LookupNamespaceByPrefixL(const TDesC8&) with NULL (or "") prefix provided
1.759 + */
1.760 + inline TXmlEngNamespace DefaultNamespaceL() const;
1.761 +
1.762 + /**
1.763 + * Performs search of namespace handler in the scope of the element. This method will
1.764 + * create new namespace declaration on the element if such namespace is not available.
1.765 + *
1.766 + * @since S60 v3.1
1.767 + * @param aNsUri Searched namespace
1.768 + * @param aPrefix Prefix to use for <b>new</b> namespace declaration (if it is to be created)
1.769 + * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
1.770 + * the element. The namespace may be one of those existed previously or was created
1.771 + *
1.772 + * @note
1.773 + * Be sure not to use the result of this method for non-descendants of the element or in situations
1.774 + * when prefix overlapping might occur (read also about general general considerations of attributes
1.775 + * and elements creation using namespace handlers)
1.776 + */
1.777 + IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri, const TDesC8& aPrefix);
1.778 +
1.779 + /**
1.780 + * Performs search on the element and its ascendants for any namespace declaration
1.781 + * with given URI and create a new namespace declaration with some (unique) prefix
1.782 + * if the search was not successful.
1.783 + *
1.784 + * @since S60 v3.1
1.785 + * @param aNsUri Searched namespace
1.786 + * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
1.787 + * the element. The namespace may be one of those existed previously or was created
1.788 + */
1.789 + IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri);
1.790 +
1.791 + /**
1.792 + * Checks whether a prefix has been bound in this element (not in one of its ascendants)
1.793 + *
1.794 + * Use this method for preventig prefix-name collision in a element node
1.795 + *
1.796 + * @since S60 v3.1
1.797 + * @param aPrefix Namespace prefix
1.798 + * @return TRUE if there is already namespace declaration that uses aPrefix on this element
1.799 + */
1.800 + IMPORT_C TBool HasNsDeclarationForPrefixL(const TDesC8& aPrefix) const;
1.801 +
1.802 + /**
1.803 + * Copies the element with its attributes, but not child nodes
1.804 + *
1.805 + * If context is preserved, then all namespace declarations that are in the element are
1.806 + * writen to element's start tag too.
1.807 + *
1.808 + * @since S60 v3.1
1.809 + * @param preserveNsContext TRUE if context should be preserved
1.810 + * @return handle to copy of element
1.811 + */
1.812 + IMPORT_C TXmlEngElement ElementCopyNoChildrenL(TBool preserveNsContext) const;
1.813 +
1.814 + /**
1.815 + * Specialized version of TXmlEngNode::CopyL()
1.816 + *
1.817 + * @since S60 v3.1
1.818 + * @return Deep copy of the element.
1.819 + */
1.820 + inline TXmlEngElement CopyL() const;
1.821 +
1.822 + /**
1.823 + * Resets element's content: all child nodes are removed
1.824 + *
1.825 + * @since S60 v3.1
1.826 + */
1.827 + IMPORT_C void RemoveChildren();
1.828 +
1.829 + /**
1.830 + * Resets element's attributes
1.831 + *
1.832 + * @since S60 v3.1
1.833 + */
1.834 + IMPORT_C void RemoveAttributes();
1.835 +
1.836 + /**
1.837 + * Resets all namespace declarations made in the element
1.838 + *
1.839 + * @note There can be references to these namespace declaration from elsewhere!
1.840 + * Use ReconcileNamespacesL() to fix that.
1.841 + *
1.842 + * @since S60 v3.1
1.843 + */
1.844 + IMPORT_C void RemoveNamespaceDeclarations();
1.845 +
1.846 + /**
1.847 + * Removes all element contents: child nodes, attributes and namespace declarations
1.848 + *
1.849 + * @see RemoveChildren(), RemoveAttributes(), RemoveNamespaceDeclarations();
1.850 + *
1.851 + * @since S60 v3.1
1.852 + */
1.853 + inline void ClearElement();
1.854 +
1.855 + /**
1.856 + * Copies attributes from another element
1.857 + *
1.858 + * It may be a very convenient method for initializing element with a set of predefined attributes.
1.859 + *
1.860 + * @since S60 v3.1
1.861 + * @param aSrc source element
1.862 + *
1.863 + * @note
1.864 + * Namespaces of the this element may need to be reconciled if copied attributes
1.865 + * belong to any namespace that is not declared on some ascendant of this node.
1.866 + * @see ReconcileNamespacesL()
1.867 + */
1.868 + IMPORT_C void CopyAttributesL(TXmlEngElement aSrc);
1.869 +
1.870 + /**
1.871 + * Copies a list of elements.
1.872 + *
1.873 + * Elements are appended to the element's children list.
1.874 + *
1.875 + * @since S60 v3.1
1.876 + * @param aSrc source element
1.877 + *
1.878 + * @note Namespaces of the this element may need to be reconciled after copy operation
1.879 + * @see ReconcileNamespacesL()
1.880 + */
1.881 + IMPORT_C void CopyChildrenL(TXmlEngElement aSrc);
1.882 +
1.883 + /**
1.884 + * Removes attribute with given name and namespace URI(if such exists).
1.885 + * Memory allocated for the attribute is freed.
1.886 + *
1.887 + * @since S60 v3.1
1.888 + * @param aLocalName Element name
1.889 + * @param aNamespaceUri Element namespace
1.890 + */
1.891 + IMPORT_C void RemoveChildElementsL(const TDesC8& aLocalName,const TDesC8& aNamespaceUri);
1.892 +
1.893 + /** @} */
1.894 +
1.895 + /**
1.896 + * @name DOM Level 3 Core methods
1.897 + *
1.898 + * @note
1.899 + * Most methods of DOM spec operate with fully-qualified names (QNames)
1.900 + * of elements and attributes. It is different in this API - all methods
1.901 + * instead accept prefix and localName parts of QName.
1.902 + */
1.903 + /** @{ */
1.904 +
1.905 + /**
1.906 + * Returns value of attribute with given name and namespace URI
1.907 + *
1.908 + * @since S60 v3.1
1.909 + * @param aLocalName Local name of attribute node
1.910 + * @param aNamespaceUri Namespace URI of attribute
1.911 + * @return Attribute value
1.912 + */
1.913 + IMPORT_C TPtrC8 AttributeValueL(const TDesC8& aLocalName,
1.914 + const TDesC8& aNamespaceUri = KNullDesC8) const;
1.915 +
1.916 + /**
1.917 + * Initializes list of child elements with matching name and namespace URI.
1.918 + *
1.919 + * @since S60 v3.1
1.920 + * @param aList Node list to be initialized
1.921 + * @param aLocalName Element name
1.922 + * @param aNamespaceUri Namespace URI, default is NULL
1.923 + *
1.924 + * @note This method does not lists all descedants of the element, only child elements
1.925 + */
1.926 + IMPORT_C void GetElementsByTagNameL(RXmlEngNodeList<TXmlEngElement>& aList,
1.927 + const TDesC8& aLocalName,
1.928 + const TDesC8& aNamespaceUri = KNullDesC8) const;
1.929 +
1.930 + /**
1.931 + * Sets value of attribute; attribute is created if there is no such attribute yet
1.932 + *
1.933 + * @since S60 v3.1
1.934 + * @param aLocalName Attribute name
1.935 + * @param aValue Attribute value
1.936 + * @param aNamespaceUri Namespace URI - default is NULL
1.937 + * @param aPrefix Namespace prefix - default is NULL
1.938 + *
1.939 + * @note
1.940 + * If prefix is not NULL (or ""), then namespace URI may not be empty
1.941 + * see http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
1.942 + */
1.943 + IMPORT_C void SetAttributeL(const TDesC8& aLocalName,
1.944 + const TDesC8& aValue,
1.945 + const TDesC8& aNamespaceUri = KNullDesC8,
1.946 + const TDesC8& aPrefix = KNullDesC8);
1.947 +
1.948 + /**
1.949 + * Removes attribute with given name and namespace URI(if such exists).
1.950 + * Memory allocated for the attribute is freed.
1.951 + *
1.952 + * @since S60 v3.1
1.953 + * @param aLocalName Name of the attribute
1.954 + * @param aNamespaceUri Attribute namespace URI, default is NULL
1.955 + */
1.956 + IMPORT_C void RemoveAttributeL(const TDesC8& aLocalName,
1.957 + const TDesC8& aNamespaceUri = KNullDesC8);
1.958 +
1.959 + /**
1.960 + * Retrieves attribute node from specific namespace by its name.
1.961 + *
1.962 + * @since S60 v3.1
1.963 + * @param aLocalName Name of the attribute
1.964 + * @param aNamespaceUri Attribute namespace URI, default is NULL
1.965 + * @return Attribute node with matching namespace URI and name
1.966 + */
1.967 + IMPORT_C TXmlEngAttr AttributeNodeL(const TDesC8& aLocalName,
1.968 + const TDesC8& aNamespaceUri = KNullDesC8) const;
1.969 +
1.970 + /**
1.971 + * Check if element has attribute with given parameters.
1.972 + *
1.973 + * @since S60 v3.1
1.974 + * @param aLocalName Name of attribute
1.975 + * @param aNamespaceUri Namespace uri, default is NULL.
1.976 + * @return TRUE if the element holds an attribute with such namespace URI and name.
1.977 + *
1.978 + * Same result gives AttributeNodeL(uri,name).NotNull()
1.979 + */
1.980 + inline TBool HasAttributeL(const TDesC8& aLocalName,
1.981 + const TDesC8& aNamespaceUri = KNullDesC8) const;
1.982 +
1.983 + /**
1.984 + * Links attribute into tree
1.985 + *
1.986 + * @since S60 v3.1
1.987 + * @param aNewAttr new attribute
1.988 + *
1.989 + * The replaced attribute node is not returned and just deleted
1.990 + */
1.991 + IMPORT_C void SetAttributeNodeL(TXmlEngAttr aNewAttr);
1.992 +};
1.993 +
1.994 +
1.995 +
1.996 +#include "xmlengelement.inl"
1.997 +
1.998 +#endif /* XMLENGINE_ELEMENT_H_INCLUDED */