1.1 --- a/epoc32/include/xmlengelement.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,995 +0,0 @@
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 */