1.1 --- a/epoc32/include/xml/dom/xmlengelement.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/xml/dom/xmlengelement.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,995 +1,1057 @@
1.4 /*
1.5 -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
1.7 * All rights reserved.
1.8 * This component and the accompanying materials are made available
1.9 -* 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.10 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: Element node functions
1.21 +* Description:
1.22 *
1.23 */
1.24
1.25 +/** @file
1.26 +@publishedAll
1.27 +@released
1.28 +*/
1.29 +#ifndef XMLENGELEMENT_H
1.30 +#define XMLENGELEMENT_H
1.31
1.32 -
1.33 -
1.34 -
1.35 -
1.36 -
1.37 -#ifndef XMLENGINE_ELEMENT_H_INCLUDED
1.38 -#define XMLENGINE_ELEMENT_H_INCLUDED
1.39 -
1.40 -#include "XmlEngAttr.h"
1.41 -#include "XmlEngNamespace.h"
1.42 +#include <xml/dom/xmlengattr.h>
1.43 +#include <xml/dom/xmlengnamespace.h>
1.44
1.45 template<class T> class RXmlEngNodeList;
1.46
1.47
1.48 /**
1.49 - * Instance of TXmlEngElement class represents an XML element in the DOM tree.
1.50 - *
1.51 - * <b>Namespace handling:</b>
1.52 - *
1.53 - * Namespace of XML element is an URI that in pair with <i>local part</i> of
1.54 - * element's name consistute <b>expanded-name</b> of element. It is said that "the element
1.55 - * is of <i>NNN</i> namespace".
1.56 - *
1.57 - * XML elements are shown as belonging to a specific namespace by using <i>prefixes</i>
1.58 - * that previously were bound to some namespace URIs. The scope of a prefix is the
1.59 - * element, where it was declared and all its child (sub-)elements.
1.60 - *
1.61 - * Namespace declaration is created by using special <b>xmlns:<i>{prefix-name}</i></b>
1.62 - * attribute (which is not really considered as attribute in DOM):
1.63 - * @code
1.64 - * <a xmlns:pr="http://some.uri.com/"> ... </a>
1.65 - * OR
1.66 - * <pr:a xmlns:pr="http://some.uri.com/"> ... </a>
1.67 - * <a xmlns="http://some.uri.com/"> ... </a>
1.68 - * @endcode
1.69 - *
1.70 - * The latter two examples are equivalent and show the use of <i>default namespace</i>.
1.71 - *
1.72 - * Implementation notes:
1.73 - * - Element having no namespace is either presented with a NULL TXmlEngNamespace node
1.74 - * or a TXmlEngNamespace node that has NULL prefix and namespace URI set to "".
1.75 - * The former is used by default on all nodes, whereas the latter is for cases
1.76 - * when some node contains undeclaration of the default namespace:
1.77 - * @code
1.78 - * <a xmlns=""> .. </a>
1.79 - * @endcode
1.80 - *
1.81 - * - The prefix of the default attribute is NULL, not "" (zero-length string)
1.82 - * "" corresponds to
1.83 - * @code
1.84 - * <a xmlns:="http://some.uri.com/"> ... </a>
1.85 - * @endcode
1.86 - * (it does not contradict XML spec, but you are strongly advised against using this)
1.87 - *
1.88 - * - Prefix <b>"xml"</b> is reserved by XML Namespace spec for special purposes; it is implicitly bound
1.89 - * to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> and no one is allowed
1.90 - * to use this prefix except as with spec-defined elements and attributes or to rebind this
1.91 - * prefix to other namespaces
1.92 - *
1.93 - * - Namespace URI may be "" only for default namespace. In other words,
1.94 - * "" namespace URI may not be bound to non-NULL prefix.
1.95 - *
1.96 - * Declaration of "" namespace with NULL prefix results in:
1.97 - * @code
1.98 - * <a xmlns=""> ... </a>
1.99 - * @endcode
1.100 - * which <i>undeclares</i> any existing (in some parent element) default namespace
1.101 - * for the scope of element 'a': element, its attributes and all child nodes of DOM tree.
1.102 - * Note, that such "undeclaration" will be added only if neccessary.
1.103 - *
1.104 - * - Unneccessary namespace declaration are ignored. Attemps to add namespace binding
1.105 - * using same namespace URI and prefix if such binding already exists in the scope
1.106 - * will have no effect.
1.107 - *
1.108 - * - <b>IMPORTANT!</b> Attributes DO NOT HAVE default namespaces. If an attribute has no
1.109 - * prefix, its namespace is <b>undeclared</b> even if there is some default namespaces for
1.110 - * the scope of the element, which contains the attribute.
1.111 - *
1.112 - * So, it is wrong to write something like this:
1.113 - * @code
1.114 - * <a xmlns="ns_uri" attr="value"> ... </a>
1.115 - * @endcode
1.116 - * and assume that the <b>attr</b> belongs to namespace pointed to with <i>ns_uri</i>.
1.117 - *
1.118 - * <b>HINTS:</b>
1.119 - * - Use namespace declaration nodes as much as possible (but watch out prefix collisions).
1.120 - * - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
1.121 - * any other namespace declarations in a element -- the will be found faster in
1.122 - * namespace lookups.
1.123 - *
1.124 - * @lib XmlEngineDOM.lib
1.125 - * @since S60 v3.1
1.126 - */
1.127 +This class represents an XML element in the DOM tree.
1.128
1.129 +Namespace handling:
1.130 +
1.131 +The namespace of a XML element is an URI that in pair with the local part of
1.132 +the element's name consistute the @c expanded-name of the element. It is said
1.133 +that "the element is of NNN namespace".
1.134 +
1.135 +XML elements are shown as belonging to a specific namespace by using prefixes
1.136 +that previously were bound to some namespace URIs. The scope of a prefix is the
1.137 +element, where it was declared and all its child (sub-)elements.
1.138 +
1.139 +Namespace declaration is created by using a special @c xmlns:{prefix-name}
1.140 +attribute (which is not really considered as an attribute in DOM):
1.141 +@code
1.142 + <a xmlns:pr="http://some.uri.com/"> ... </a>
1.143 +OR
1.144 + <pr:a xmlns:pr="http://some.uri.com/"> ... </a>
1.145 + <a xmlns="http://some.uri.com/"> ... </a>
1.146 +@endcode
1.147 +
1.148 +The latter two examples are equivalent and show the use of @c default namespace.
1.149 +
1.150 +Implementation notes:
1.151 +- Elements having no namespace are either presented with a NULL
1.152 + TXmlEngNamespace node or a TXmlEngNamespace node that has NULL (KNullDesC8)
1.153 + prefix and namespace URI set to "" (an empty descriptor). The former is
1.154 + used by default on all nodes, whereas the latter is for cases when some node
1.155 + contains undeclaration of the default namespace:
1.156 + @code
1.157 + <a xmlns=""> .. </a>
1.158 + @endcode
1.159 +
1.160 +- The prefix of the default attribute is NULL (KNullDesC8), not an "" (empty
1.161 + descriptor). An empty descriptor which corresponds to
1.162 + @code
1.163 + <a xmlns:="http://some.uri.com/"> ... </a>
1.164 + @endcode
1.165 + (it does not contradict XML spec, but you are strongly advised against using
1.166 + this)
1.167 +
1.168 +- Prefix "xml" is reserved by XML Namespace spec for special purposes; it is
1.169 + implicitly bound to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i>
1.170 + and no one is allowed to use this prefix except as with spec-defined
1.171 + elements and attributes or to rebind this prefix to other namespaces
1.172 +
1.173 +- Namespace URI may be "" (an empty descriptor) only for default namespace. In
1.174 + other words, "" namespace URI may not be bound to non-NULL prefix.
1.175 +
1.176 + Declaration of "" (an empty descriptor) namespace with NULL (KNullDesC8)
1.177 + prefix results in:
1.178 + @code
1.179 + <a xmlns=""> ... </a>
1.180 + @endcode
1.181 + which undeclares any existing (in some parent element) default namespace
1.182 + for the scope of element 'a': element, its attributes and all child nodes
1.183 + of DOM tree. Note, that such "undeclaration" will be added only if neccessary.
1.184 +
1.185 +- Unneccessary namespace declaration are ignored. Attemps to add namespace binding
1.186 + using same namespace URI and prefix if such binding already exists in the scope
1.187 + will have no effect.
1.188 +
1.189 +- IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no
1.190 + prefix, its namespace is undeclared even if there is some default namespaces for
1.191 + the scope of the element, which contains the attribute.
1.192 +
1.193 +So, it is wrong to write something like this:
1.194 +@code
1.195 + <a xmlns="ns_uri" attr="value"> ... </a>
1.196 +@endcode
1.197 +and assume that the attr belongs to namespace pointed to with @c ns_uri.
1.198 +
1.199 +HINTS:
1.200 +- Use namespace declaration nodes as much as possible (but watch out for prefix collisions).
1.201 +- Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after
1.202 + any other namespace declarations in a element -- they will be found faster in
1.203 + namespace lookups.
1.204 +
1.205 +For more informarion on NULL and NULL nodes:
1.206 +@see TXmlEngNode
1.207 +@see KNullDesC8
1.208 +*/
1.209 class TXmlEngElement : public TXmlEngNode
1.210 {
1.211 public:
1.212 - /**
1.213 - * Default constructor for automatic variables (not initialized)
1.214 - *
1.215 - * @since S60 v3.1
1.216 - */
1.217 + /** Default constructor */
1.218 inline TXmlEngElement();
1.219
1.220 /**
1.221 - * Constructor
1.222 - *
1.223 - * @since S60 v3.1
1.224 - * @param aInternal element pointer
1.225 - */
1.226 + Constructor
1.227 + @param aInternal element pointer
1.228 + */
1.229 inline TXmlEngElement(void* aInternal);
1.230
1.231 - /**
1.232 - * @name XmlEngine's non-DOM extensions
1.233 - */
1.234 - /** @{ */
1.235 + /*
1.236 + Extensions to the DOM Level 3 Core methods
1.237 + */
1.238
1.239 /**
1.240 - * Retrieves list of attribute nodes of the element
1.241 - *
1.242 - * @param aList - a node list object to initialize
1.243 - *
1.244 - * Passed by reference list of nodes is initialized and after call to
1.245 - * Attributes(..) is ready for use with HasNext() and Next() methods:
1.246 - *
1.247 - * @code
1.248 - * ...
1.249 - * TXmlEngElement root = doc.DocumentElement();
1.250 - * RXmlEngNodeList<TXmlEngAttr> attlist;
1.251 - * root.GetAttributes(attlist);
1.252 - * while (attlist.HasNext())
1.253 - * processAttribute(attlist.Next());
1.254 - * ...
1.255 - * attlist.Close();
1.256 - * @endcode
1.257 - *
1.258 - * @since S60 v3.1
1.259 - */
1.260 + Retrieves a list of the attribute nodes of an element
1.261 +
1.262 + Upon return, aList is initialized and is ready for use with HasNext() and
1.263 + Next() methods:
1.264 +
1.265 + @code
1.266 + ...
1.267 + TXmlEngElement root = doc.DocumentElement();
1.268 + RXmlEngNodeList<TXmlEngAttr> attlist;
1.269 + root.GetAttributes(attlist);
1.270 + while (attlist.HasNext())
1.271 + processAttribute(attlist.Next());
1.272 + ...
1.273 + attlist.Close();
1.274 + @endcode
1.275 +
1.276 + If there are no attributes the list will be empty.
1.277 +
1.278 + @param aList An attribute list to initialize
1.279 + */
1.280 IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;
1.281
1.282 /**
1.283 - * Retrieves list of child elements of the element
1.284 - *
1.285 - * @since S60 v3.1
1.286 - * @param aList - a node list object to initialize
1.287 - *
1.288 - * Passed by reference list of nodes is initialized and after the call
1.289 - * it is ready for use with HasNext() and Next() methods:
1.290 - *
1.291 - * @note Returned list is a "filtered view" of the underlying
1.292 - * list of all element's children (with text nodes, comments
1.293 - * processing instructions, etc.)
1.294 - */
1.295 + Retrieves a list of child elements of an element.
1.296 +
1.297 + Upon return, aList is initialized and is ready for use with HasNext() and
1.298 + Next() methods.
1.299 +
1.300 + Note: This returns a list of the child element nodes only.
1.301 +
1.302 + There is no affect if the element attributes are empty.
1.303 +
1.304 + @param aList A child list to initialize
1.305 + */
1.306 IMPORT_C void GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const;
1.307
1.308 - /**
1.309 - * Creates new attribute node out of any namespace (i.e. it has no prefix),
1.310 - * sets attribute's value and links it as the last attribute of the current element
1.311 - *
1.312 - * @since S60 v3.1
1.313 - * @param aName A local name of attribute
1.314 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.315 - * @return A handler to the newly created attribute node;
1.316 - *
1.317 - * For adding attribute as the first one, use TXmlEngNode::SetAsFirstSibling() on the attribute:
1.318 - * @code
1.319 - * TXmlEngElement el = ... ; // get some element
1.320 - * el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
1.321 - * @endcode
1.322 - *
1.323 - * @see SetAsLastSibling(), MoveBeforeSibling(TXmlEngNode) and MoveAfterSibling(TXmlEngNode)
1.324 - *
1.325 - * @note - No checks are made that attribute with such name exists
1.326 - * Use this method only on newly created elements!
1.327 - * Otherwise, use TXmlEngElement::SetAttributeL(..)
1.328 - * - Attributes do not inherit default namespace of its element
1.329 - * (http://w3.org/TR/REC-xml-names/#defaulting)
1.330 - * - attribute's value is the second argument in all AddNewAttributeL(..) methods
1.331 - * - Use of NULL as value is more preferrable then ""
1.332 - */
1.333 + /**
1.334 + Creates a new attribute node outside of any namespace (i.e. it has no
1.335 + prefix), sets the attribute's value and links it as the last attribute of
1.336 + the current element.
1.337 +
1.338 + Note:
1.339 + - No checks are made that an attribute with the same name exists.
1.340 + Use this method only on newly created elements!
1.341 + Otherwise, use TXmlEngElement::SetAttributeL()
1.342 + - Attributes do not inherit default namespace of its element
1.343 + (http://w3.org/TR/REC-xml-names/#defaulting)
1.344 + - The attribute's value is the second argument in all AddNewAttributeL() methods
1.345 +
1.346 + When adding the first attribute, use TXmlEngNode::SetAsFirstSibling() on the attribute:
1.347 + @code
1.348 + TXmlEngElement el = ... ; // get some element
1.349 + el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
1.350 + @endcode
1.351 +
1.352 + Copies are taken of descripters passed in.
1.353 +
1.354 + @see SetAsLastSibling()
1.355 + @see MoveBeforeSibling(TXmlEngNode)
1.356 + @see MoveAfterSibling(TXmlEngNode)
1.357 + *
1.358 + @param aName A local name of the attribute
1.359 + @param aValue Value to set for new attribute or KNullDesC8
1.360 + @return The created attribute
1.361 + @leave KXmlEngErrNullNode The node is NULL
1.362 + @leave KXmlEngErrWrongUseOfAPI aName is empty
1.363 + @leave - One of the system-wide error codes
1.364 + */
1.365 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);
1.366
1.367 /**
1.368 - * Creates new attribute node and add it to the element
1.369 - *
1.370 - * Provided handle to namespace declaration is used to set up
1.371 - * attribute's namespace.
1.372 - *
1.373 - * @since S60 v3.1
1.374 - * @param aName A local name of attribute
1.375 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.376 - * @param aNsDef Namespace to add to the attribute
1.377 - * @return A handler to the newly created attribute node;
1.378 - *
1.379 - * @note If aNsDef is not defined in some of attributes ascendants
1.380 - * (including this element), then
1.381 - * ReconcileNamespacesL() method must be called on
1.382 - * this element later.
1.383 - */
1.384 + Creates a new attribute node and adds it to the element.
1.385 +
1.386 + The provided namespace declaration is used to set the attribute's namespace.
1.387 +
1.388 + Note: If aNsDef is not defined in some of the attribute's ascendants
1.389 + (including this element), then the ReconcileNamespacesL() method must be
1.390 + called on this element later.
1.391 +
1.392 + Copies are taken of descripters passed in.
1.393 +
1.394 + @param aName The local name of attribute
1.395 + @param aValue Value to set for new attribute or KNullDesC8
1.396 + @param aNsDef Namespace to add to the attribute
1.397 + @return The created attribute
1.398 + @leave KXmlEngErrNullNode The node is NULL
1.399 + @leave KXmlEngErrWrongUseOfAPI aName is empty
1.400 + @leave - One of the system-wide error codes
1.401 + */
1.402 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
1.403 const TDesC8& aValue,
1.404 const TXmlEngNamespace aNsDef);
1.405
1.406 - /**
1.407 - * Creates new attribute on the element. Namespace declaration for the attribute namespace is
1.408 - * created too.
1.409 - *
1.410 - * @since S60 v3.1
1.411 - * @param aName A local name of attribute
1.412 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.413 - * @param aNsUri Namespace uri
1.414 - * @param aPrefix Namespace prefix
1.415 - * @return A handler to the newly created attribute node;
1.416 - *
1.417 - * @note
1.418 - * - Namespace declarations are reused if possible (no redundant ones are created)
1.419 - */
1.420 + /**
1.421 + Creates a new attribute for the element. A namespace declaration for the
1.422 + attribute namespace is also created.
1.423 +
1.424 + Note: Namespace declarations are reused if possible (no redundant ones are
1.425 + created)
1.426 +
1.427 + Copies are taken of descripters passed in.
1.428 +
1.429 + @param aName The local name of attribute
1.430 + @param aValue Value to set for the new attribute or an empty string
1.431 + @param aNsUri Namespace URI
1.432 + @param aPrefix Namespace prefix
1.433 + @return The created attribute
1.434 + @leave KXmlEngErrNullNode The node is NULL
1.435 + @leave KXmlEngErrWrongUseOfAPI aName is empty
1.436 + @leave - One of the system-wide error codes
1.437 + */
1.438 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,
1.439 const TDesC8& aValue,
1.440 const TDesC8& aNsUri,
1.441 const TDesC8& aPrefix);
1.442
1.443 - /**
1.444 - * Creates new attribute node using namespace of its parent element (this element),
1.445 - * sets attribute's value and links it as the last attribute of the element
1.446 - *
1.447 - * @since S60 v3.1
1.448 - * @param aName Local name of attribute
1.449 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.450 - * @return A handler to the newly created attribute node;
1.451 - *
1.452 - * For more hints how to use it refer to AddNewAttributeL(const TDesC8&,const TDesC8&)
1.453 - *
1.454 - * @note
1.455 - * - No checks are made that attribute with such name exists
1.456 - * - if namespace of the parent element is default (i.e. bound prefix is NULL),
1.457 - * then temporary prefix will be used and bound to the same namespace URI as elements
1.458 - * (It is due to the fact that default namespaces do not spread on unprefixed attributes,
1.459 - * see http://w3.org/TR/REC-xml-names/#defaulting)
1.460 - */
1.461 + /**
1.462 + Creates a new attribute node using the namespace of its parent element
1.463 + (this element), sets the attribute's value and links it as the last
1.464 + attribute of the element
1.465 +
1.466 + For more hints how to use it @see AddNewAttributeL(const TDesC8&,const TDesC8&)
1.467 +
1.468 + Note:
1.469 + - No checks are made that an attribute with the same name exists
1.470 + - if the namespace of the parent element is default (i.e. bound prefix is KNullDesC8),
1.471 + then a temporary prefix will be used and bound to the same namespace URI as the element
1.472 + (It is due to the fact that default namespaces do not spread on unprefixed attributes,
1.473 + see http://w3.org/TR/REC-xml-names/#defaulting)
1.474 +
1.475 + Copies are taken of descripters passed in.
1.476 + @see KNullDesC8
1.477 +
1.478 + @param aName Local name of attribute
1.479 + @param aValue Value to set for the new attribute or empty.
1.480 + @return The created attribute
1.481 + @leave KXmlEngErrNullNode The node is NULL
1.482 + @leave KXmlEngErrWrongUseOfAPI aName is empty
1.483 + @leave - One of the system-wide error codes
1.484 + */
1.485 inline TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);
1.486
1.487 /**
1.488 - * Creates new attributes using namespace, which is bound to the specified prefix
1.489 - *
1.490 - * @since S60 v3.1
1.491 - * @param aLocalName A local name of attribute
1.492 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.493 - * @param aPrefix Namespace prefix for new attribute
1.494 - * @return A handler to the newly created attribute node;
1.495 - *
1.496 - * Use this mothod only for construction of new parts of DOM tree, where
1.497 - * you know for sure that prefix is bound in the given scope.
1.498 - * @code
1.499 - * TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
1.500 - * el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
1.501 - * @endcode
1.502 - *
1.503 - * Otherwise, you should check that prefix is bound like this example shows:
1.504 - * @code
1.505 - * TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
1.506 - * if (boundNS.NotNull()){
1.507 - * thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
1.508 - * }
1.509 - * @endcode
1.510 - *
1.511 - * @note
1.512 - * Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because
1.513 - * it is most efficient way to create namespaced DOM elements (no additional
1.514 - * lookups for namespace declarations are required).
1.515 - *
1.516 - * @code
1.517 - * // If namespace with given URI is not in the scope, then it will be declared
1.518 - * // and bound to "data" prefix.
1.519 - * TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
1.520 - * elem.AddNewAttributeL("location", "...", nsDef);
1.521 - * elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
1.522 - * // the result is
1.523 - * ...
1.524 - * <elem xmlns:data="http://../Data" data:location="...">
1.525 - * <data:child attr="...value..."/>
1.526 - * </elem>
1.527 - * ...
1.528 - * //
1.529 - * @endcode
1.530 - */
1.531 + Creates a new attribute using the namespace which is bound to the specified prefix
1.532 +
1.533 + Use this mothod only for construction of new parts of DOM tree where
1.534 + you know for sure that the prefix is bound in the given scope.
1.535 + @code
1.536 + TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
1.537 + el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
1.538 + @endcode
1.539 +
1.540 + Otherwise, you should check that the prefix is bound like this example shows:
1.541 + @code
1.542 + TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
1.543 + if (boundNS.NotNull()){
1.544 + thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
1.545 + }
1.546 + @endcode
1.547 +
1.548 + Note: Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can,
1.549 + because it is the most efficient way to create namespaced DOM elements (no
1.550 + additional lookups for namespace declarations are required).
1.551 +
1.552 + @code
1.553 + // If namespace with given URI is not in the scope, then it will be declared
1.554 + // and bound to "data" prefix.
1.555 + TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
1.556 + elem.AddNewAttributeL("location", "...", nsDef);
1.557 + elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
1.558 + // the result is
1.559 + ...
1.560 + <elem xmlns:data="http://../Data" data:location="...">
1.561 + <data:child attr="...value..."/>
1.562 + </elem>
1.563 + ...
1.564 + //
1.565 + @endcode
1.566 +
1.567 + Copies are taken of descripters passed in.
1.568 +
1.569 + @param aLocalName The local name of the attribute
1.570 + @param aValue Value to set for the new attribute or empty string.
1.571 + @param aPrefix Namespace prefix for the new attribute
1.572 + @return The created attribute
1.573 + @leave KXmlEngErrNullNode The node is NULL
1.574 + @leave KXmlEngErrWrongUseOfAPI aLocalName is empty
1.575 + @leave KErrNoMemory The namespace is not found and the URI is not
1.576 + http://www.w3.org/XML/1998/namespace; or there is a memory allocation error
1.577 + @leave - One of the system-wide error codes
1.578 + */
1.579 IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName,
1.580 const TDesC8& aValue,
1.581 const TDesC8& aPrefix);
1.582
1.583 /**
1.584 - * Creates new attributes using namespace in the scope, which has specified URI
1.585 - *
1.586 - * Almost the same as AddNewAttributeUsePrefixL(...) but does lookup by namespace URI
1.587 - *
1.588 - * @since S60 v3.1
1.589 - * @param aLocalName A local name of attribute
1.590 - * @param aValue Value to set for new attribute or NULL (sets value to "")
1.591 - * @param aNsUri Namespace uri for new attribute
1.592 - * @return - NULL attribute if namespace declaration is not found OR newly added to the end of
1.593 - * attribute list attribute of this element.
1.594 - *
1.595 - * @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
1.596 - */
1.597 + Creates new attributes using the namespace in scope, which has the specified URI
1.598 +
1.599 + Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI
1.600 +
1.601 + @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
1.602 +
1.603 + Copies are taken of descripters passed in.
1.604 + @see KNullDesC8
1.605 +
1.606 + @param aLocalName The local name of the attribute
1.607 + @param aValue Value to set for new attribute or empty string.
1.608 + @param aNsUri Namespace URI for new attribute
1.609 + @return NULL attribute if namespace declaration is not found OR newly added
1.610 + to the end of attribute list attribute of this element.
1.611 + @leave KXmlEngErrNullNode The node is NULL
1.612 + @leave KXmlEngErrWrongUseOfAPI aLocalName is empty
1.613 + @leave - One of the system-wide error codes
1.614 + */
1.615 IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName,
1.616 const TDesC8& aValue,
1.617 const TDesC8& aNsUri);
1.618
1.619 - /**
1.620 - * Add attribute to element that will be used as Xml:Id.
1.621 - *
1.622 - * No check if such attribute exists are made.
1.623 - *
1.624 - * @since S60 v3.2
1.625 - * @param aLocalName Name of attribute that should be add.
1.626 - * @param aValue Value of the attribute
1.627 - * @param aNs Namespace of the attribute
1.628 - * @return Attribute if created. Null attribute if Id exist
1.629 - *
1.630 - * @note Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first
1.631 - * to register existed id's in the document.
1.632 - */
1.633 + /**
1.634 + Adds attribute to element that will be used as Xml:Id. Does not check if
1.635 + an attribute with the same name exists.
1.636 +
1.637 + Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register
1.638 + existed id's in the document. If the ids are not registered the ID will
1.639 + not be added to the element.
1.640 +
1.641 + Copies are taken of descripters passed in.
1.642 +
1.643 + @param aLocalName Name of the attribute
1.644 + @param aValue Value of the attribute
1.645 + @param aNs Namespace of the attribute
1.646 + @return Attribute if created. Null attribute if Xml:Id exists
1.647 + @leave KXmlEngErrWrongUseOfAPI Element is NULL or attribute doesn't exist
1.648 + @leave - One of the system-wide error codes
1.649 + */
1.650 IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,
1.651 const TDesC8& aValue,
1.652 TXmlEngNamespace aNs = TXmlEngNamespace());
1.653
1.654 - /**
1.655 - * Adds child element with no namespace
1.656 - *
1.657 - * @since S60 v3.1
1.658 - * @param aName name of the element
1.659 - * @return A handler to the newly created element node;
1.660 - *
1.661 - * Results in adding element with aName and no prefix.
1.662 - *
1.663 - * This method is the best for creation of non-namespace based documents
1.664 - * or document fragments, where no default namespace declared.
1.665 - *
1.666 - * It may be used also as a method for adding element from default namespace,
1.667 - * BUT namespace will be assigned ONLY after serialization of the current
1.668 - * document and parsing it back into a DOM tree!! If you need that default namespace
1.669 - * was inherited by new element immediately use:
1.670 - * @code
1.671 - * ...
1.672 - * TXmlEngNamespace defns = element.DefaultNamespace();
1.673 - * TXmlEngElement newEl = element.AddNewElementL("Name",defns);
1.674 - * ...
1.675 - * @endcode
1.676 - *
1.677 - * If truly undefined namespace for the element is required, then <b>DO NOT USE</b>
1.678 - * this method if there is a default namespace in the scope!
1.679 - */
1.680 + /**
1.681 + Adds a child element with no namespace. This results in adding an element
1.682 + with aName and no prefix.
1.683 +
1.684 + This method is the best for creation of non-namespace based documents
1.685 + or document fragments, where no default namespace declared.
1.686 +
1.687 + It may be used also as a method for adding elements from the default
1.688 + namespace, BUT namespace will be assigned ONLY after serialization of the
1.689 + current document and parsing it back into a DOM tree!! If you need the new
1.690 + element to inherit the default namespace use:
1.691 +
1.692 + @code
1.693 + ...
1.694 + TXmlEngNamespace defns = element.DefaultNamespace();
1.695 + TXmlEngElement newEl = element.AddNewElementL("Name",defns);
1.696 + ...
1.697 + @endcode
1.698 +
1.699 + It is not recommended that you use an undefined namespace with libxml.
1.700 + If an undefined namespace for the element is truly required, then DO NOT
1.701 + USE this method if there is a default namespace in the scope!
1.702 + @see AddNamespaceDeclarationL
1.703 +
1.704 + Copies are taken of descripters passed in.
1.705 +
1.706 + @param aName The name of the element
1.707 + @return The created element
1.708 + @leave KXmlEngErrNullNode Element is NULL
1.709 + @leave KXmlEngErrWrongUseOfAPI Name is not specified
1.710 + @leave - One of the system-wide error codes
1.711 + */
1.712 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);
1.713
1.714 - /**
1.715 - * Creates new child element with provided name and namespace declaration
1.716 - *
1.717 - * @since S60 v3.1
1.718 - * @param aLocalName Name of the element
1.719 - * @param aNsDecl Handle of the namespace declaration, that must be retrieved from
1.720 - * one of the ascendant nodes of the new elements (and its prefix
1.721 - * should not be remapped to another namespace URI for the scope
1.722 - * of the new element)
1.723 - * @return Created element node (and added as the last child of its parent)
1.724 - */
1.725 + /**
1.726 + Creates a new child element with the provided name and namespace
1.727 + declaration and adds it as the last child of its parent.
1.728 +
1.729 + Copies are taken of descripters passed in.
1.730 +
1.731 + @param aLocalName The name of the element
1.732 + @param aNsDecl The namespace declaration that must be retrieved from
1.733 + one of the ascendant nodes of the new elements (and its prefix
1.734 + should not be remapped to another namespace URI for the scope
1.735 + of the new element)
1.736 + @return Created element node
1.737 + @leave KXmlEngErrNullNode Element is NULL
1.738 + @leave KXmlEngErrWrongUseOfAPI Name is not specified
1.739 + @leave - One of the system-wide error codes
1.740 + */
1.741 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);
1.742
1.743 - /**
1.744 - * Creates new child element with provided name, prefix and namespace URI
1.745 - *
1.746 - * New namespace declaration will be attached to the parent (this) element and used
1.747 - * as namespace for newly created child element. If such binding already exists
1.748 - * (same prefix is bound to same URI), it will be reused. If the prefix is already
1.749 - * bound to some another namespace URI, it will be rebound by the new namespace
1.750 - * declaration node.
1.751 - *
1.752 - * @since S60 v3.1
1.753 - * @param aLocalName Name of the element
1.754 - * @param aNsUri URI of element's namespace
1.755 - * @param aPrefix Prefix of the element
1.756 - * @return Created element node (and added as the last child of its parent)
1.757 - */
1.758 + /**
1.759 + Creates a new child element with provided the name, prefix and namespace
1.760 + URI and adds it as the last child of its parent.
1.761 +
1.762 + The new namespace declaration will be attached to the parent (this) element
1.763 + and used as the namespace for newly created child element. If such a
1.764 + binding already exists (same prefix is bound to same URI), it will be
1.765 + reused. If the prefix is already bound to some other namespace URI, it will
1.766 + be rebound by the new namespace declaration node.
1.767 +
1.768 + Copies are taken of descripters passed in.
1.769 +
1.770 + @param aLocalName Name of the element
1.771 + @param aNsUri URI of the element's namespace
1.772 + @param aPrefix Prefix of the element
1.773 + @return The created element node
1.774 + @leave KXmlEngErrNullNode Element is NULL
1.775 + @leave KXmlEngErrWrongUseOfAPI Name or URI or prefix is not specified
1.776 + @leave - One of the system-wide error codes
1.777 + */
1.778 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName,
1.779 const TDesC8& aNsUri,
1.780 const TDesC8& aPrefix);
1.781
1.782 - /**
1.783 - * Adds child element with same namespace (and prefix if present) as parent element has
1.784 - *
1.785 - * @since S60 v3.1
1.786 - * @param aLocalName element's name
1.787 - * @return New element that was added to the end of children list of its parent (this element)
1.788 - */
1.789 + /**
1.790 + Creates a child element with the same namespace (and prefix if present) as
1.791 + the parent element and adds it as the last child of its parent.
1.792 +
1.793 + Copies are taken of descripters passed in.
1.794 +
1.795 + @param aLocalName The element's name
1.796 + @return The created element
1.797 + @leave KXmlEngErrNullNode Element is NULL
1.798 + @leave KXmlEngErrWrongUseOfAPI Name is not specified
1.799 + @leave - One of the system-wide error codes
1.800 + */
1.801 IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);
1.802
1.803 - /**
1.804 - * Performs lookup for the namespace declaration for specified prefix and
1.805 - * adds new child element with found namespace.
1.806 - *
1.807 - * The assumption is that prefix is bound, otherwise run-time error
1.808 - * (Symbian's Leave or exception) occurs
1.809 - *
1.810 - * @note Use this method only if there is a binding for the given prefix.
1.811 - *
1.812 - * @since S60 v3.1
1.813 - * @param aLocalName element's name
1.814 - * @param aPrefix prefix to use
1.815 - * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
1.816 - */
1.817 + /**
1.818 + Performs a lookup for the namespace declaration for the specified prefix
1.819 + and adds a new child element with the found namespace as the last child of
1.820 + its parent.
1.821 +
1.822 + @pre The prefix is bound
1.823 +
1.824 + Copies are taken of descripters passed in.
1.825 +
1.826 + @param aLocalName The element's name
1.827 + @param aPrefix The prefix to use for the search
1.828 + @return The created element
1.829 + @leave KXmlEngErrNullNode Element is NULL
1.830 + @leave KXmlEngErrWrongUseOfAPI Name is not specified
1.831 + @leave KErrNoMemory The namespace is not found and the prefix is not "xml"
1.832 + (i.e http://www.w3.org/XML/1998/namespace); or there is a memory allocation
1.833 + error.
1.834 + @leave - One of the system-wide error codes
1.835 + */
1.836 IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);
1.837
1.838 - /**
1.839 - * Performs lookup for the namespace declaration for specified namespace URI and
1.840 - * adds new child element with found namespace.
1.841 - *
1.842 - * The assumption is that namespace with given URI was declared,
1.843 - * otherwise run-time error (Symbian' Leave or exception) occurs
1.844 - *
1.845 - * @note Use this method only if namespace declaration for the provided URI exists.
1.846 - *
1.847 - * @since S60 v3.1
1.848 - * @param aLocalName element's name
1.849 - * @param aNsUri namespace of element
1.850 - * @return new TXmlEngElement that was added to the end of children list of its parent (this element)
1.851 - */
1.852 + /**
1.853 + Performs a lookup for the namespace declaration for the specified namespace
1.854 + URI and adds a new child element with the found namespace. The new element
1.855 + is added as the last child of this element.
1.856 +
1.857 + Copies are taken of descripters passed in.
1.858 +
1.859 + @pre A namespace with the given URI has been declared
1.860 +
1.861 + @param aLocalName The element's name
1.862 + @param aNsUri The namespace of the element
1.863 + @return The created element
1.864 + @leave KXmlEngErrNullNode Element is NULL
1.865 + @leave KXmlEngErrWrongUseOfAPI Name is not specified
1.866 + @leave KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace
1.867 + or there is a memory allocation error
1.868 + @leave - One of the system-wide error codes
1.869 + */
1.870 IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri);
1.871
1.872 - /**
1.873 - * Creates new child element; if there is no a prefix binding for new element's namespace,
1.874 - * a namespace decaration is created with generated prefix at specified element.
1.875 - *
1.876 - * @since S60 v3.1
1.877 - * @param aLocalName Name of the element to create
1.878 - * @param aNsUri Namespace URI of the new element
1.879 - * @param aNsDeclTarget An element where namespace declaraton should be placed
1.880 - * if there is a needed to create new namespace declaration;
1.881 - * NULL is used to specify the created element itself
1.882 - *
1.883 - * As aNsDeclTarget any ascendant of the new node may be provided:
1.884 - * @code
1.885 - * el.AddNewElementAutoPrefixL(tagName,uri,NULL); // declare on the new element
1.886 - * el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element
1.887 - * el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
1.888 - * ...
1.889 - * @endcode
1.890 - *
1.891 - * @note
1.892 - * The farther namespace declaration up in the document tree,
1.893 - * the longer time namespace declaration lookups take.
1.894 - */
1.895 + /**
1.896 + Creates a new child element. If there is no a prefix binding for the new
1.897 + element's namespace, a namespace decaration is created with a generated
1.898 + prefix at the specified element.
1.899 +
1.900 + The location of the namespace declaration may be controlled with
1.901 + aNsDeclTarget:
1.902 +
1.903 + @code
1.904 + el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // declare on the new element
1.905 + el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element
1.906 + el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
1.907 + ...
1.908 + @endcode
1.909 +
1.910 + Note: The farther namespace declaration up in the document tree, the
1.911 + longer the namespace declaration lookups take.
1.912 +
1.913 + Copies are taken of descripters passed in.
1.914 +
1.915 + @param aLocalName Name of the element to create
1.916 + @param aNsUri Namespace URI of the new element
1.917 + @param aNsDeclTarget The element where the namespace declaraton should be placed.
1.918 + @return The created element
1.919 + @leave KXmlEngErrNullNode Element is NULL
1.920 + @leave KXmlEngErrWrongUseOfAPI Name or URI is not specified
1.921 + @leave - One of the system-wide error codes
1.922 + */
1.923 IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName,
1.924 const TDesC8& aNsUri,
1.925 TXmlEngElement aNsDeclTarget);
1.926
1.927 - /**
1.928 - * Get element content.
1.929 - * This method may be used in most cases, when element has only simple text content
1.930 - * (without entity references embedded).
1.931 - * If element's contents is mixed (other types of nodes present), only contents of
1.932 - * first child node is returned if it is a TXmlEngTextNode node. For getting mixed contents of the
1.933 - * element of contents with entity references, WholeTextValueCopyL() should be used.
1.934 - *
1.935 - * @since S60 v3.1
1.936 - * @return Basic contents of the element
1.937 - *
1.938 - * @see TXmlEngNode::WholeTextContentsCopyL()
1.939 - */
1.940 + /**
1.941 + Gets element content. This method may be used in most cases when the element
1.942 + has only simple text content (without entity references embedded). If the
1.943 + element's contents is mixed (other types of nodes present), only the contents
1.944 + of the first child node is returned (if it is a TXmlEngTextNode node).
1.945 +
1.946 + For getting the contents of an element that has contents containing entity
1.947 + references, WholeTextValueCopyL() should be used.
1.948 +
1.949 + @see TXmlEngNode::WholeTextContentsCopyL()
1.950 +
1.951 + @return The simple text contents of the element or NULL if there is no text.
1.952 + */
1.953 IMPORT_C TPtrC8 Text() const;
1.954
1.955 /**
1.956 - * Adds text as a child of the element.
1.957 - *
1.958 - * @since S60 v3.1
1.959 - * @param aString text to be added as element's content.
1.960 - *
1.961 - * @note There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added actually,
1.962 - * depending on the aString value
1.963 - */
1.964 + Adds text as a child of the element to the end of the list of children.
1.965 +
1.966 + Note: There may be several TXmlEngTextNode and TXmlEngEntityReference
1.967 + nodes added, depending on the aString value. For example, if the curernt
1.968 + node has text and attributes, a text node and attribute nodes will
1.969 + be added.
1.970 +
1.971 + Copies are taken of descripters passed in.
1.972 +
1.973 + @param aString Text to be added as the element's content.
1.974 + @leave KXmlEngErrNullNode Element is NULL
1.975 + @leave - One of the system-wide error codes
1.976 + */
1.977 IMPORT_C void AddTextL(const TDesC8& aString);
1.978
1.979 /**
1.980 - * Sets text contents for the element.
1.981 - * Any child nodes are removed.
1.982 - * Same as TXmlEngNode::SetValueL(TDesC8&)
1.983 - *
1.984 - * @since S60 v3.1
1.985 - * @param aString text to be set as element's content.
1.986 - *
1.987 - * @see TXmlEngNode::SetValueL(TDesC8&)
1.988 - */
1.989 + Sets text contents for the element. Any child nodes are removed.
1.990 + This function is the same as TXmlEngNode::SetValueL(TDesC8&)
1.991 +
1.992 + @see TXmlEngNode::SetValueL(TDesC8&)
1.993 +
1.994 + @param aString Text to be set as element's content.
1.995 + @leave KXmlEngErrNullNode Element is NULL
1.996 + @leave - One of the system-wide error codes
1.997 + */
1.998 IMPORT_C void SetTextL(const TDesC8& aString);
1.999
1.1000 /**
1.1001 - * Sets text content of the element from escaped string.
1.1002 - *
1.1003 - * @since S60 v3.1
1.1004 - * @param aEscapedString New value
1.1005 - *
1.1006 - * @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
1.1007 - */
1.1008 + Sets the text content of the element from an escaped string.
1.1009 + @see TXmlEngAttr::SetEscapedValueL(TDesC8&)
1.1010 +
1.1011 + @param aEscapedString New value
1.1012 + @leave KXmlEngErrNullNode Element is NULL
1.1013 + @leave - One of the system-wide error codes
1.1014 + */
1.1015 IMPORT_C void SetEscapedTextL(const TDesC8& aEscapedString);
1.1016
1.1017 - /**
1.1018 - * Sets new element value exactly as presented in the string.
1.1019 - * Predefined entities are not converted into characters they represent.
1.1020 - * Any child nodes are removed.
1.1021 - *
1.1022 - * @since S60 v3.2
1.1023 - * @param aNotEncText New element value
1.1024 - *
1.1025 - * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.1026 - */
1.1027 + /**
1.1028 + Sets the new element value exactly as presented in the string. Predefined
1.1029 + entities are not converted into the characters they represent. Any child
1.1030 + nodes are removed.
1.1031 +
1.1032 + @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.1033 +
1.1034 + @param aNotEncString New string value
1.1035 + @leave KXmlEngErrNullNode Element is NULL
1.1036 + @leave - One of the system-wide error codes
1.1037 + */
1.1038 IMPORT_C void SetTextNoEncL(const TDesC8& aNotEncString);
1.1039
1.1040 - /**
1.1041 - * Appends new text node with the value exactly as presented in the string.
1.1042 - * Predefined entities are not converted into characters they represent.
1.1043 - * Existing child nodes are not removed.
1.1044 - *
1.1045 - * @since S60 v3.2
1.1046 - * @param aNotEncText Appended element value
1.1047 - *
1.1048 - * @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.1049 - */
1.1050 + /**
1.1051 + Appends a new text node with the value exactly as presented in the string.
1.1052 + Predefined entities are not converted into the characters they represent.
1.1053 + Existing child nodes are not removed.
1.1054 +
1.1055 + @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
1.1056 +
1.1057 + Copies are taken of descripters passed in.
1.1058 +
1.1059 + @param aNotEncString Appended string value
1.1060 + @leave KXmlEngErrNullNode Element is NULL
1.1061 + @leave - One of the system-wide error codes
1.1062 + */
1.1063 IMPORT_C void AppendTextNoEncL(const TDesC8& aNotEncString);
1.1064
1.1065 - /**
1.1066 - * Adds namespace declaration to the current element, a binding of prefix to namespace URI.
1.1067 - *
1.1068 - * If same namespace declaration exists (same prefix and URI), redundant namespace declaration
1.1069 - * will not be created.
1.1070 - *
1.1071 - * Both NULL or "" (empty string) may be used for "UNDEFINED URI" and "NO PREFIX" values of arguments.
1.1072 - *
1.1073 - * @since S60 v3.1
1.1074 - * @param aNsUri Namespace URI
1.1075 - * @param aPrefix Namespace prefix
1.1076 - * @return A handle to the created (or found, if there is such) namespace declaration node.
1.1077 - * If namespace undeclaration is being created, NULL handle is returned -- it can be
1.1078 - * used in node-creation methods that take namespace handle as an argument.
1.1079 - *
1.1080 - * @note Undeclaring of default namespace (xmlns="") is supported by
1.1081 - * SetNoDefaultNamespace() method
1.1082 - *
1.1083 - * @see SetNoDefaulNamespace()
1.1084 - *
1.1085 - * @note By adding namespace declaration that rebinds prefix mapping (or default namespace)
1.1086 - * used by nodes lower in the tree, document tree may become
1.1087 - * wrongly constructed, because references to namespace declaration are
1.1088 - * not updated. However, after serialization the document will have
1.1089 - * desired structure.
1.1090 - * Use this method with care!
1.1091 - */
1.1092 + /**
1.1093 + Adds a namespace declaration to the current element: a binding of prefix to namespace URI.
1.1094 +
1.1095 + If the same namespace declaration exists (same prefix and URI), a redundant
1.1096 + namespace declaration will not be created.
1.1097 +
1.1098 + Both KNullDesC8 or an empty descriptor may be used for "UNDEFINED URI"
1.1099 + and "NO PREFIX" values of arguments. Please refer to the class
1.1100 + documentation for more specific information.
1.1101 + @see TXmlEngElement
1.1102 + @see KNullDesC8
1.1103 +
1.1104 + Note: Undeclaring of default namespace (xmlns="") is supported by
1.1105 + the SetNoDefaultNamespace() method.
1.1106 + @see SetNoDefaulNamespace()
1.1107 +
1.1108 + Note: Adding a namespace declaration that rebinds the prefix mapping (or
1.1109 + default namespace) used by nodes lower in the tree may damage the document
1.1110 + tree because references to namespace declarations are not updated.
1.1111 + However, after serialization, the document will have the desired structure.
1.1112 + Use this method with care!
1.1113 +
1.1114 + Copies are taken of descripters passed in.
1.1115 +
1.1116 + @param aNsUri Namespace URI, KNullDesC8 or an empty descriptor.
1.1117 + @param aPrefix Namespace prefix, KNullDesC8 or an empty descriptor.
1.1118 + @return The namespace that was created or found or a NULL namespace if the
1.1119 + namespace is being undeclared.
1.1120 + @leave KXmlEngErrNullNode Element is NULL
1.1121 + @leave KXmlEngErrWrongUseOfAPI URI or prefix is not specified
1.1122 + @leave - One of the system-wide error codes
1.1123 + */
1.1124 IMPORT_C TXmlEngNamespace AddNamespaceDeclarationL(const TDesC8& aNsUri, const TDesC8& aPrefix);
1.1125
1.1126 /**
1.1127 - * Adds default namespace declaration.
1.1128 - *
1.1129 - * @since S60 v3.1
1.1130 - * @param aNsUri Namespace URI; both NULL and "" (empty string) are allowed to represent UNDEFINED NAMSPACE
1.1131 - * @return Handle to the created namespace declaration (NULL for UNDEFINED NAMESPACE)
1.1132 - *
1.1133 - * Same result as with AddNamespaceDeclarationL(aNsUri, NULL), but additionally
1.1134 - * element's namespace modified (if it has no prefix and there were no default
1.1135 - * namespace declaration in the scope) to the new default one.
1.1136 - */
1.1137 + Adds a default namespace declaration.
1.1138 +
1.1139 +1
1.1140 + This achieves the same result as with AddNamespaceDeclarationL(aNsUri,
1.1141 + KNullDesC8), but additionally the element's namespace is modified (if it has no
1.1142 + prefix and there were no default namespace declaration in the scope) to the
1.1143 + new default one.
1.1144 +
1.1145 + Copies are taken of descripters passed in.
1.1146 + @see KNullDesC8
1.1147 +
1.1148 + @param aNsUri Namespace URI; KNullDesC8 and empty descriptor are allowed to represent UNDEFINED NAMSPACE
1.1149 + @return The created namespace declaration (NULL for UNDEFINED NAMESPACE)
1.1150 + @leave KXmlEngErrNullNode Element is NULL
1.1151 + @leave KXmlEngErrWrongUseOfAPI URI is not specified
1.1152 + @leave - One of the system-wide error codes
1.1153 + */
1.1154 IMPORT_C TXmlEngNamespace SetDefaultNamespaceL(const TDesC8& aNsUri);
1.1155
1.1156 /**
1.1157 - * Undeclares any default namespace for current element and its descendants.
1.1158 - *
1.1159 - * If there is already some default namespace, <i>xmlns=""</i> namespace
1.1160 - * declaration is added. Otherwise, nothing happens, since element with no
1.1161 - * prefix in such scope is automaticaly considered as out of any namespace.
1.1162 - *
1.1163 - * The side effect of this method is that namespace of the current element
1.1164 - * may change from previous <b>default</b> namespace to NULL TXmlEngNamespace, which is
1.1165 - * considered an absence of namespace.
1.1166 - *
1.1167 - * If the element has prefix (i.e. not having default namespace),
1.1168 - * then the only effect for the element is undeclaration of existing default namespace.
1.1169 - *
1.1170 - * If element is in the scope of another <i>xmlns=""</i> undeclaration, no
1.1171 - * actions are taken.
1.1172 - *
1.1173 - * @note
1.1174 - * Use AddNamespaceDeclarationL(NULL,NULL) to force creation of
1.1175 - * xmlns="" declaration within scope of another such declaration
1.1176 - * (otherwise unneccessary/duplicate declarations are not created)
1.1177 - *
1.1178 - * @note
1.1179 - * This method should be called on elements before adding children,
1.1180 - * because default namespace undeclaration is not spread into its subtree and
1.1181 - * descedants' default namespaces are not reset to NULL. This should be taken into
1.1182 - * account if later some processing on the subtree occurs.
1.1183 - * However, after serialization and deserialization, undeclared default namespace will
1.1184 - * affect whole element's subtree correctly.
1.1185 - *
1.1186 - * @since S60 v3.1
1.1187 - */
1.1188 - IMPORT_C void SetNoDefaultNamespaceL();
1.1189 + Undeclares any default namespace for this element and its descendants.
1.1190 +
1.1191 + If there is already a default namespace, a @c xmlns="" namespace
1.1192 + declaration is added. Otherwise, nothing happens, since elements with no
1.1193 + prefix in such scope are automaticaly considered outside of any namespace.
1.1194 +
1.1195 + The side effect of this method is that the namespace of the current element
1.1196 + may change from the previous default namespace to a NULL TXmlEngNamespace,
1.1197 + which is considered an absence of namespace.
1.1198 +
1.1199 + If the element has a prefix (i.e. not having default namespace), then the
1.1200 + only effect for the element is undeclaration of existing default namespace.
1.1201 +
1.1202 + If the element is in the scope of another @c xmlns="" undeclaration, no
1.1203 + action is taken.
1.1204 +
1.1205 + Note: Use AddNamespaceDeclarationL(KNullDesC8,KNullDesC8) to force the creation of a @c
1.1206 + xmlns="" declaration within the scope of another such declaration
1.1207 + (otherwise unneccessary/duplicate declarations are not created).
1.1208 +
1.1209 + Note: This method should be called on elements before adding children,
1.1210 + because default namespace undeclaration is not spread into its subtree and
1.1211 + descendants' default namespaces are not reset to NULL. This should be taken
1.1212 + into account if later some processing on the subtree occurs. However,
1.1213 + after serialization and deserialization, undeclared default namespace will
1.1214 + affect whole element's subtree correctly.
1.1215
1.1216 - /**
1.1217 - * Finds namespace declaration that has specific prefix in the scope for given node
1.1218 - *
1.1219 - * Prefix "" or NULL are considered the same, meaning "<b>NO PREFIX</b>".
1.1220 - * If namespace declaration for "no prefix" is searched, then default namespace is returned.
1.1221 - *
1.1222 - * @since S60 v3.1
1.1223 - * @param aPrefix Namespace prefix
1.1224 - * @return Namespace handler, which may be NULL if prefix is not bound.
1.1225 - *
1.1226 - * NULL result for "no prefix" means that default namespace is undefined.
1.1227 - */
1.1228 + @see KNullDesC8
1.1229 +
1.1230 + @leave KXmlEngErrNullNode Element is NULL
1.1231 + @leave - One of the system-wide error codes
1.1232 + */
1.1233 + IMPORT_C void SetNoDefaultNamespaceL();
1.1234 +
1.1235 + /**
1.1236 + Finds the namespace declaration that has a specific prefix in the list of parents for
1.1237 + this element.
1.1238 +
1.1239 + If no prefix is specified (an empty descriptor or KNullDesC8) then it is
1.1240 + considered to be a "NO PREFIX" search. Therefore, if the namespace
1.1241 + declaration for "no prefix" is searched, then the default namespace is
1.1242 + returned.
1.1243 +
1.1244 + Copies are taken of descripters passed in.
1.1245 + @see KNullDesC8
1.1246 +
1.1247 + @param aPrefix Namespace prefix.
1.1248 + @return The namespace, which may be NULL if prefix is not found; NULL result for "no prefix" means that default namespace is undefined.
1.1249 + @leave - One of the system-wide error codes
1.1250 + */
1.1251 IMPORT_C TXmlEngNamespace LookupNamespaceByPrefixL(const TDesC8& aPrefix) const;
1.1252
1.1253 - /**
1.1254 - * Finds namespace declaration that has specific namespace URI
1.1255 - * in the scope for the given node.
1.1256 - *
1.1257 - * @since S60 v3.1
1.1258 - * @param aUri Namespace URI, for which namespace declaration is searched
1.1259 - * @return Handler to the namespace declaration that binds given namespace URI to some prefix
1.1260 - * or sets it a default namespace.
1.1261 - *
1.1262 - * NULL value of aUri is equivalent to "" and means "<b>UNDEFINED NAMESPACE</b>".
1.1263 - * For such URI a NULL namespace handle is always returned even if there is
1.1264 - * namespace undeclaration, which has "" URI (and NULL prefix).
1.1265 - *
1.1266 - * <b>Hint:</b><p>
1.1267 - * Use returned instance of TXmlEngNamespace as aNsDef argument to element's methods
1.1268 - * that create new element's child elements and attributes. The same handler
1.1269 - * may be used on more deep descentants of the reference element (and doing
1.1270 - * this way will generally increase performance of DOM tree construction).<br />
1.1271 - * <span class="color:red;">However</span>, if namespace bindings are not controlled
1.1272 - * for element's children and prefix, which is bound to the search namespace, is
1.1273 - * rebound to some other namespace URI, then reusing namespace may lead to
1.1274 - * unwanted result.
1.1275 - *
1.1276 - * Consider an example:
1.1277 - * @code
1.1278 - * TXmlEngElement root = doc.DocumentElement();
1.1279 - * TXmlEngNamespace targetNs = root.AddNamespaceDeclarationL("http://example.com/","ex");
1.1280 - * TXmlEngElement el_1 = root.AddNewElementL("outer", targetNs);
1.1281 - * TXmlEngElement el_2 = el_1.AddNewElementL("inner"); // element without prefix
1.1282 - *
1.1283 - * // NOTE: prefix "ex" is not bound to "http://example.com/" anymore!
1.1284 - * el_2.AddNamespaceDeclarationL("http://whatever.com/","ex");
1.1285 - * TXmlEngElement el_3 = el_2.AddNewElementL("problem", targetNs);
1.1286 - * ...
1.1287 - * @endcode
1.1288 - *
1.1289 - * The sought result was (showing expanded names of elements):
1.1290 - * @code
1.1291 - * --> "root"
1.1292 - * --> {"http://example.com/","outer"}
1.1293 - * --> "inner"
1.1294 - * -->{"http://example.com/","problem"}
1.1295 - * ...
1.1296 - * <--
1.1297 - * <-- "inner"
1.1298 - * <-- {"http://example.com/","outer"}
1.1299 - * ...
1.1300 - * <-- </root>
1.1301 - * @endcode
1.1302 - * and it may look that it has been achieved. Indeed, if namespace of element "problem"
1.1303 - * was queried, it would have URI "http://example.com/" and prefix "ex".
1.1304 - * However, if namespace URI was looked up by "problem"'s prefix, it would be
1.1305 - * "http://whatever.com/". We have created illegal DOM tree.
1.1306 - *
1.1307 - * The actual DOM tree in serialized form will be:
1.1308 - * @code
1.1309 - * <root>
1.1310 - * <ex:outer xmlns:ex="http://example.com/">
1.1311 - * <inner xmlns:ex="http://whatever.com/">
1.1312 - * <ex:problem>
1.1313 - * ...
1.1314 - * </ex:problem>
1.1315 - * </inner>
1.1316 - * </ex:outer>
1.1317 - * ...
1.1318 - * </root>
1.1319 - * @endcode
1.1320 - *
1.1321 - * So, reuse of namespace handlers should be performed with special care.
1.1322 - *
1.1323 - * @note
1.1324 - * At the moment it is possible to retrieve namespace declaration nodes
1.1325 - * whose prefixes were rebound. Be careful when use returned TXmlEngNamespace object
1.1326 - * for creation of new elements. In later releases, this method will perform
1.1327 - * safe lookup. And so far, it is better to make check that prefix of returned
1.1328 - * namespace declaration has not rebound:
1.1329 - * @code
1.1330 - * TXmlEngNamespace ns = element.LookupNamespaceByUri("a_uri");
1.1331 - * if (element.LookupNamespaceByPrefix(ns.Prefix()).IsSameNode(ns)){
1.1332 - * ... // now it is safe to create new elements by using "ns"
1.1333 - * element.AddNewElementL("product",ns);
1.1334 - * ...
1.1335 - * }
1.1336 - * @endcode
1.1337 - */
1.1338 + /**
1.1339 + Finds a namespace declaration that has a specific namespace URI in the
1.1340 + scope for the given node.
1.1341 +
1.1342 + KNullDesC8 value of aUri is equivalent to an empty descriptor and means
1.1343 + "UNDEFINED NAMESPACE".
1.1344 + For such URI's a NULL namespace handle is always returned even if there is
1.1345 + a namespace undeclaration, which has an empty descriptor URI (and KNullDesC8
1.1346 + prefix).
1.1347 +
1.1348 + Hint: Use the returned instance of TXmlEngNamespace as the aNsDef argument
1.1349 + to an element's methods that create new child elements and attributes. The
1.1350 + same TXmlEngNamespace may be used on deeper descentants of the reference
1.1351 + element (and doing this way will generally increase performance of DOM tree
1.1352 + construction). However, if namespace bindings are not controlled for the
1.1353 + element's children and the prefix (which is bound to the search namespace)
1.1354 + is rebound to some other namespace URI, then reusing the namespace may lead
1.1355 + to unwanted result.
1.1356 +
1.1357 + Note: At the moment it is possible to retrieve namespace declaration nodes
1.1358 + whose prefixes were rebound. Be careful when using returned
1.1359 + TXmlEngNamespace objects for creation of new elements.
1.1360 +
1.1361 + Copies are taken of descripters passed in.
1.1362 +
1.1363 + @param aUri Namespace URI, for which the namespace declaration is searched
1.1364 + @return The namespace declaration that binds the given namespace URI to a
1.1365 + prefix or sets it as a default namespace
1.1366 + @leave - One of the system-wide error codes
1.1367 + */
1.1368 IMPORT_C TXmlEngNamespace LookupNamespaceByUriL(const TDesC8& aUri) const;
1.1369
1.1370 - /**
1.1371 - * Retrieves implicitly declared on every XML infoset binding
1.1372 - * of 'xml' prefix to XML's namespace URI:
1.1373 - * "http://www.w3.org/XML/1998/namespace"
1.1374 - *
1.1375 - * @since S60 v3.1
1.1376 - * @return Handler to {xml,"http://www.w3.org/XML/1998/namespace"} prefix
1.1377 - * binding in the current document
1.1378 - *
1.1379 - * The result should be used for creating attributes beloging to the XML namespace
1.1380 - * (xml:lang, xml:space, xml:id , etc.)
1.1381 - *
1.1382 - * DO NOT USE methods LookupNamespaceByUriL(const TDesC8&) and LookupNamespaceByPrefixL(const TDesC8&)
1.1383 - * (with "http://www.w3.org/XML/1998/namespace" and "xml" arguments) for retrieving
1.1384 - * namespace node, since in a case of [possible] memory allocation fault
1.1385 - * NULL result is returned (and breaks your program silently)
1.1386 - *
1.1387 - * @note Normally 'xml' prefix is bound to XML namespace URI in the document
1.1388 - * node, BUT if current node is not a part of the document tree yet,
1.1389 - * the requested namespace declaration WILL BE ADDED to the current node.
1.1390 - * This is the reason why the method may fail in OOM conditions.
1.1391 - */
1.1392 + /**
1.1393 + Retrieves the implicitly declared XML infoset binding of the 'xml' prefix
1.1394 + to XML's namespace URI: "http://www.w3.org/XML/1998/namespace"
1.1395 +
1.1396 + The result should be used for creating attributes beloging to the XML namespace
1.1397 + (xml:lang, xml:space, xml:id , etc.)
1.1398 +
1.1399 + DO NOT USE the methods LookupNamespaceByUriL(const TDesC8&) and
1.1400 + LookupNamespaceByPrefixL(const TDesC8&) (with the arguments
1.1401 + "http://www.w3.org/XML/1998/namespace" and "xml" respectively) for
1.1402 + retrieving the namespace node, since in the case of a memory allocation
1.1403 + fault, a NULL result is returned (and breaks your program silently)
1.1404 +
1.1405 + Note: Normally the 'xml' prefix is bound to the XML namespace URI in the
1.1406 + document node, BUT if this element is not a part of the document tree yet,
1.1407 + the requested namespace declaration WILL BE ADDED to the current node.
1.1408 + This is the reason why the method may fail in OOM conditions.
1.1409 +
1.1410 + @return The namespace matching the prefix binding
1.1411 + {xml,"http://www.w3.org/XML/1998/namespace"} in the current document
1.1412 + @leave KErrNoMemory The element is NULL or there was a memory allocation error
1.1413 + @leave - One of the system-wide error codes
1.1414 + */
1.1415 IMPORT_C TXmlEngNamespace TheXMLNamespaceL() const;
1.1416
1.1417 - /**
1.1418 - * Get default namespace for element.
1.1419 - *
1.1420 - * @since S60 v3.1
1.1421 - * @return Default namespace in the scope of the element
1.1422 - *
1.1423 - * NULL TXmlEngNamespace means that element with no prefix have no namespace associated
1.1424 - * because no default namespace was declared or default namespace was undeclared with <b>xmlns=""</b>
1.1425 - *
1.1426 - * Equivalent to LookupNamespaceByPrefixL(const TDesC8&) with NULL (or "") prefix provided
1.1427 - */
1.1428 + /**
1.1429 + Get the default namespace for the element.
1.1430 +
1.1431 + A NULL TXmlEngNamespace means that an element with no prefix
1.1432 + has no namespace associated with it because no default namespace was declared or
1.1433 + the default namespace was undeclared with @c xmlns=""
1.1434 +
1.1435 + This function is equivalent to LookupNamespaceByPrefixL(KNullDesC8).
1.1436 + @see KNullDesC8
1.1437 +
1.1438 + @return The default namespace in the scope of the element
1.1439 + @leave - One of the system-wide error codes
1.1440 + */
1.1441 inline TXmlEngNamespace DefaultNamespaceL() const;
1.1442
1.1443 - /**
1.1444 - * Performs search of namespace handler in the scope of the element. This method will
1.1445 - * create new namespace declaration on the element if such namespace is not available.
1.1446 - *
1.1447 - * @since S60 v3.1
1.1448 - * @param aNsUri Searched namespace
1.1449 - * @param aPrefix Prefix to use for <b>new</b> namespace declaration (if it is to be created)
1.1450 - * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
1.1451 - * the element. The namespace may be one of those existed previously or was created
1.1452 - *
1.1453 - * @note
1.1454 - * Be sure not to use the result of this method for non-descendants of the element or in situations
1.1455 - * when prefix overlapping might occur (read also about general general considerations of attributes
1.1456 - * and elements creation using namespace handlers)
1.1457 - */
1.1458 + /**
1.1459 + Performs a search for the namespace in the scope of the element. This
1.1460 + method will create new namespace declaration on the element if such
1.1461 + namespace is not found.
1.1462 +
1.1463 + Note: Be sure not to use the result of this method for non-descendants of
1.1464 + the element or in situations when prefix overlapping might occur.
1.1465 + @see TXmlEngAttr
1.1466 + @see TXmlEngNamespace
1.1467 + Please read the documentation for this class:
1.1468 + @see TXmlEngElement
1.1469 +
1.1470 + Copies are taken of descripters passed in.
1.1471 +
1.1472 + @param aNsUri Namespace to search for
1.1473 + @param aPrefix Prefix to use for the new namespace declaration (if it is to be created)
1.1474 + @return The namespace found or created
1.1475 + @leave KXmlEngErrNullNode Element is NULL
1.1476 + @leave KXmlEngErrWrongUseOfAPI URI is not specified
1.1477 + @leave - One of the system-wide error codes
1.1478 +
1.1479 + @see LookupNamespacebyUriL
1.1480 + */
1.1481 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri, const TDesC8& aPrefix);
1.1482
1.1483 - /**
1.1484 - * Performs search on the element and its ascendants for any namespace declaration
1.1485 - * with given URI and create a new namespace declaration with some (unique) prefix
1.1486 - * if the search was not successful.
1.1487 - *
1.1488 - * @since S60 v3.1
1.1489 - * @param aNsUri Searched namespace
1.1490 - * @return TXmlEngNamespace handler that may be used to create new attributes and child elements of
1.1491 - * the element. The namespace may be one of those existed previously or was created
1.1492 - */
1.1493 + /**
1.1494 + Performs a search on the element and its ascendants for any namespace
1.1495 + declaration with a given URI. Creates a new namespace declaration with a
1.1496 + (unique) prefix if the search was not successful.
1.1497 + @see AddNamespaceDeclarationL
1.1498 +
1.1499 + Copies are taken of descripters passed in.
1.1500 +
1.1501 + @param aNsUri Namespace to search for
1.1502 + @return The namespace found or created
1.1503 + @leave KXmlEngErrNullNode Element is NULL
1.1504 + @leave KXmlEngErrWrongUseOfAPI URI is not specified
1.1505 + @leave - One of the system-wide error codes
1.1506 + */
1.1507 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri);
1.1508
1.1509 /**
1.1510 - * Checks whether a prefix has been bound in this element (not in one of its ascendants)
1.1511 - *
1.1512 - * Use this method for preventig prefix-name collision in a element node
1.1513 - *
1.1514 - * @since S60 v3.1
1.1515 - * @param aPrefix Namespace prefix
1.1516 - * @return TRUE if there is already namespace declaration that uses aPrefix on this element
1.1517 - */
1.1518 + Checks whether a prefix has been bound in this element (not in one of its ascendants)
1.1519 +
1.1520 + Use this method for preventing prefix-name collision in a element node
1.1521 +
1.1522 + Copies are taken of descripters passed in.
1.1523 +
1.1524 + @param aPrefix Namespace prefix
1.1525 + @return ETrue if there is already a namespace declaration that uses aPrefix on this element
1.1526 + @leave - One of the system-wide error codes
1.1527 + */
1.1528 IMPORT_C TBool HasNsDeclarationForPrefixL(const TDesC8& aPrefix) const;
1.1529
1.1530 /**
1.1531 - * Copies the element with its attributes, but not child nodes
1.1532 - *
1.1533 - * If context is preserved, then all namespace declarations that are in the element are
1.1534 - * writen to element's start tag too.
1.1535 - *
1.1536 - * @since S60 v3.1
1.1537 - * @param preserveNsContext TRUE if context should be preserved
1.1538 - * @return handle to copy of element
1.1539 - */
1.1540 + Copies the element with its attributes, but not child nodes
1.1541 +
1.1542 + If the context is preserved (preserveNsContent), then all namespace
1.1543 + declarations that are in the element are writen to the <element ...> tag.
1.1544 +
1.1545 + @param preserveNsContext Whether the namespace context should be preserved
1.1546 + @return The copied element
1.1547 + @leave KXmlEngErrNullNode The element is NULL
1.1548 + @leave - One of the system-wide error codes
1.1549 + */
1.1550 IMPORT_C TXmlEngElement ElementCopyNoChildrenL(TBool preserveNsContext) const;
1.1551
1.1552 /**
1.1553 - * Specialized version of TXmlEngNode::CopyL()
1.1554 - *
1.1555 - * @since S60 v3.1
1.1556 - * @return Deep copy of the element.
1.1557 - */
1.1558 + Specialized version of TXmlEngNode::CopyL()
1.1559 + @return Deep copy of the element.
1.1560 + @leave KXmlEngErrNullNode The element is NULL
1.1561 + @leave - One of the system-wide error codes
1.1562 + */
1.1563 inline TXmlEngElement CopyL() const;
1.1564
1.1565 - /**
1.1566 - * Resets element's content: all child nodes are removed
1.1567 - *
1.1568 - * @since S60 v3.1
1.1569 - */
1.1570 + /** Resets element's content: all child nodes are removed */
1.1571 IMPORT_C void RemoveChildren();
1.1572
1.1573 - /**
1.1574 - * Resets element's attributes
1.1575 - *
1.1576 - * @since S60 v3.1
1.1577 - */
1.1578 + /** Resets element's attributes */
1.1579 IMPORT_C void RemoveAttributes();
1.1580
1.1581 /**
1.1582 - * Resets all namespace declarations made in the element
1.1583 - *
1.1584 - * @note There can be references to these namespace declaration from elsewhere!
1.1585 - * Use ReconcileNamespacesL() to fix that.
1.1586 - *
1.1587 - * @since S60 v3.1
1.1588 - */
1.1589 - IMPORT_C void RemoveNamespaceDeclarations();
1.1590 + Resets all namespace declarations made in the element
1.1591 +
1.1592 + Note: There can be references to these namespace declarations elsewhere!
1.1593 + Use ReconcileNamespacesL() to fix that.
1.1594 + */
1.1595 + IMPORT_C void RemoveNamespaceDeclarations();
1.1596
1.1597 /**
1.1598 - * Removes all element contents: child nodes, attributes and namespace declarations
1.1599 - *
1.1600 - * @see RemoveChildren(), RemoveAttributes(), RemoveNamespaceDeclarations();
1.1601 - *
1.1602 - * @since S60 v3.1
1.1603 - */
1.1604 + Removes all element contents: child nodes, attributes and namespace declarations
1.1605 +
1.1606 + @see RemoveChildren()
1.1607 + @see RemoveAttributes()
1.1608 + @see RemoveNamespaceDeclarations();
1.1609 + */
1.1610 inline void ClearElement();
1.1611
1.1612 - /**
1.1613 - * Copies attributes from another element
1.1614 - *
1.1615 - * It may be a very convenient method for initializing element with a set of predefined attributes.
1.1616 - *
1.1617 - * @since S60 v3.1
1.1618 - * @param aSrc source element
1.1619 - *
1.1620 - * @note
1.1621 - * Namespaces of the this element may need to be reconciled if copied attributes
1.1622 - * belong to any namespace that is not declared on some ascendant of this node.
1.1623 - * @see ReconcileNamespacesL()
1.1624 - */
1.1625 + /**
1.1626 + Copies attributes from another element. It may be a very convenient method
1.1627 + for initializing element with a set of predefined attributes.
1.1628 +
1.1629 + Note: Namespaces of the this element may need to be reconciled if the
1.1630 + copied attributes belong to any namespace that is not declared on some
1.1631 + ascendant of this node. @see ReconcileNamespacesL()
1.1632 +
1.1633 + @param aSrc Source element
1.1634 + @leave KXmlEngErrNullNode The element is NULL
1.1635 + @leave - One of the system-wide error codes
1.1636 + */
1.1637 IMPORT_C void CopyAttributesL(TXmlEngElement aSrc);
1.1638
1.1639 - /**
1.1640 - * Copies a list of elements.
1.1641 - *
1.1642 - * Elements are appended to the element's children list.
1.1643 - *
1.1644 - * @since S60 v3.1
1.1645 - * @param aSrc source element
1.1646 - *
1.1647 - * @note Namespaces of the this element may need to be reconciled after copy operation
1.1648 - * @see ReconcileNamespacesL()
1.1649 - */
1.1650 + /**
1.1651 + Recursively copies the children (and all of it's associated information)
1.1652 + from another element. Elements are appended to the current element's
1.1653 + children list.
1.1654 +
1.1655 + Note: Namespaces of this element may need to be reconciled after copy
1.1656 + operation
1.1657 + @see ReconcileNamespacesL()
1.1658 +
1.1659 + @param aSrc Source element
1.1660 + @leave KXmlEngErrNullNode The element is NULL
1.1661 + @leave KXmlEngWrongUseOfAPI The source element is NULL
1.1662 + @leave - One of the system-wide error codes
1.1663 + */
1.1664 IMPORT_C void CopyChildrenL(TXmlEngElement aSrc);
1.1665
1.1666 - /**
1.1667 - * Removes attribute with given name and namespace URI(if such exists).
1.1668 - * Memory allocated for the attribute is freed.
1.1669 - *
1.1670 - * @since S60 v3.1
1.1671 - * @param aLocalName Element name
1.1672 - * @param aNamespaceUri Element namespace
1.1673 - */
1.1674 + /**
1.1675 + Removes the child element with the given name and namespace URI (if it exists).
1.1676 + Memory allocated for the element is freed.
1.1677 +
1.1678 + @param aLocalName Child element name
1.1679 + @param aNamespaceUri Child element namespace
1.1680 + @leave KXmlEngErrNullNode The element is NULL
1.1681 + @leave - One of the system-wide error codes
1.1682 + */
1.1683 IMPORT_C void RemoveChildElementsL(const TDesC8& aLocalName,const TDesC8& aNamespaceUri);
1.1684
1.1685 - /** @} */
1.1686 + /**
1.1687 + Renames the element with the given name, namespace URI, and namespace prefix.
1.1688
1.1689 - /**
1.1690 - * @name DOM Level 3 Core methods
1.1691 - *
1.1692 - * @note
1.1693 - * Most methods of DOM spec operate with fully-qualified names (QNames)
1.1694 - * of elements and attributes. It is different in this API - all methods
1.1695 - * instead accept prefix and localName parts of QName.
1.1696 + @param aLocalName The new element name
1.1697 + @param aNamespaceUri The new namespace URI
1.1698 + @param aPrefix The new namespace prefix
1.1699 + @leave - One of the system-wide error codes
1.1700 + */
1.1701 + IMPORT_C void RenameElementL(const TDesC8& aLocalName, const TDesC8& aNamespaceUri, const TDesC8& aPrefix);
1.1702 +
1.1703 + /*
1.1704 + DOM Level 3 Core methods
1.1705 +
1.1706 + Most methods of DOM spec operate with fully-qualified names (QNames)
1.1707 + of elements and attributes. It is different in this API - all methods
1.1708 + instead accept prefix and localName parts of QName.
1.1709 */
1.1710 - /** @{ */
1.1711
1.1712 /**
1.1713 - * Returns value of attribute with given name and namespace URI
1.1714 - *
1.1715 - * @since S60 v3.1
1.1716 - * @param aLocalName Local name of attribute node
1.1717 - * @param aNamespaceUri Namespace URI of attribute
1.1718 - * @return Attribute value
1.1719 - */
1.1720 + Returns the value of the attribute with the given name and namespace URI.
1.1721 +
1.1722 + @param aLocalName Local name of the attribute
1.1723 + @param aNamespaceUri Namespace URI of the attribute, or the default namespace if not specified.
1.1724 + @return The attribute value (for as long as the attribute exists) or
1.1725 + NULL if not found.
1.1726 + @leave - One of the system-wide error codes
1.1727 + */
1.1728 IMPORT_C TPtrC8 AttributeValueL(const TDesC8& aLocalName,
1.1729 const TDesC8& aNamespaceUri = KNullDesC8) const;
1.1730
1.1731 /**
1.1732 - * Initializes list of child elements with matching name and namespace URI.
1.1733 - *
1.1734 - * @since S60 v3.1
1.1735 - * @param aList Node list to be initialized
1.1736 - * @param aLocalName Element name
1.1737 - * @param aNamespaceUri Namespace URI, default is NULL
1.1738 - *
1.1739 - * @note This method does not lists all descedants of the element, only child elements
1.1740 - */
1.1741 + Initializes list of child elements with matching names and namespace URIs.
1.1742 +
1.1743 + Note: This method does not list all descendants of the element, only child elements
1.1744 + @see KNullDesC8
1.1745 +
1.1746 + @param aList Node list to be created
1.1747 + @param aLocalName Element name
1.1748 + @param aNamespaceUri if specified it sets the Namespace URI, default is KNullDesC8 (no namespace set).
1.1749 + @leave - One of the system-wide error codes
1.1750 + */
1.1751 IMPORT_C void GetElementsByTagNameL(RXmlEngNodeList<TXmlEngElement>& aList,
1.1752 const TDesC8& aLocalName,
1.1753 const TDesC8& aNamespaceUri = KNullDesC8) const;
1.1754
1.1755 - /**
1.1756 - * Sets value of attribute; attribute is created if there is no such attribute yet
1.1757 - *
1.1758 - * @since S60 v3.1
1.1759 - * @param aLocalName Attribute name
1.1760 - * @param aValue Attribute value
1.1761 - * @param aNamespaceUri Namespace URI - default is NULL
1.1762 - * @param aPrefix Namespace prefix - default is NULL
1.1763 - *
1.1764 - * @note
1.1765 - * If prefix is not NULL (or ""), then namespace URI may not be empty
1.1766 - * see http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
1.1767 - */
1.1768 + /**
1.1769 + Sets the value of the given attribute. The attribute is created if there
1.1770 + is no such attribute yet.
1.1771 +
1.1772 + Note: If prefix is not KNullDesC8 (or an empty descriptor),
1.1773 + then the namespace URI may not be empty see
1.1774 + http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
1.1775 +
1.1776 + Copies are taken of descripters passed in.
1.1777 + @see KNullDesC8
1.1778 +
1.1779 + @param aLocalName Attribute name
1.1780 + @param aValue Attribute value
1.1781 + @param aNamespaceUri Namespace URI - default is KNullDesC8
1.1782 + @param aPrefix Namespace prefix - default is KNullDesC8
1.1783 + @leave KXmlEngErrNullNode The element is NULL
1.1784 + @leave KXmlEngErrWrongUseOfAPI Attribute name not specified
1.1785 + @leave - One of the system-wide error codes
1.1786 + */
1.1787 IMPORT_C void SetAttributeL(const TDesC8& aLocalName,
1.1788 const TDesC8& aValue,
1.1789 const TDesC8& aNamespaceUri = KNullDesC8,
1.1790 const TDesC8& aPrefix = KNullDesC8);
1.1791
1.1792 - /**
1.1793 - * Removes attribute with given name and namespace URI(if such exists).
1.1794 - * Memory allocated for the attribute is freed.
1.1795 - *
1.1796 - * @since S60 v3.1
1.1797 - * @param aLocalName Name of the attribute
1.1798 - * @param aNamespaceUri Attribute namespace URI, default is NULL
1.1799 - */
1.1800 + /**
1.1801 + Removes the attribute with the given name and namespace URI (if it exists).
1.1802 + Memory allocated for the attribute is freed.
1.1803 +
1.1804 + @see KNullDesC8
1.1805 +
1.1806 + @param aLocalName Name of the attribute
1.1807 + @param aNamespaceUri Attribute namespace URI, default is KNullDesC8
1.1808 + @leave - One of the system-wide error codes
1.1809 + */
1.1810 IMPORT_C void RemoveAttributeL(const TDesC8& aLocalName,
1.1811 const TDesC8& aNamespaceUri = KNullDesC8);
1.1812
1.1813 - /**
1.1814 - * Retrieves attribute node from specific namespace by its name.
1.1815 - *
1.1816 - * @since S60 v3.1
1.1817 - * @param aLocalName Name of the attribute
1.1818 - * @param aNamespaceUri Attribute namespace URI, default is NULL
1.1819 - * @return Attribute node with matching namespace URI and name
1.1820 - */
1.1821 + /**
1.1822 + Retrieves an attribute node with a specific namespace by its name.
1.1823 +
1.1824 + @see KNullDesC8
1.1825 +
1.1826 + @param aLocalName Name of the attribute
1.1827 + @param aNamespaceUri Attribute namespace URI, default is KNullDesC8
1.1828 + @return Attribute node with matching namespace URI and name, NULL if not found.
1.1829 + @leave - One of the system-wide error codes
1.1830 + */
1.1831 IMPORT_C TXmlEngAttr AttributeNodeL(const TDesC8& aLocalName,
1.1832 const TDesC8& aNamespaceUri = KNullDesC8) const;
1.1833
1.1834 /**
1.1835 - * Check if element has attribute with given parameters.
1.1836 - *
1.1837 - * @since S60 v3.1
1.1838 - * @param aLocalName Name of attribute
1.1839 - * @param aNamespaceUri Namespace uri, default is NULL.
1.1840 - * @return TRUE if the element holds an attribute with such namespace URI and name.
1.1841 - *
1.1842 - * Same result gives AttributeNodeL(uri,name).NotNull()
1.1843 - */
1.1844 + Check if the element has an attribute with given parameters.
1.1845 +
1.1846 + This function is the same as AttributeNodeL(uri,name).NotNull().
1.1847 +
1.1848 + @see KNullDesC8
1.1849 +
1.1850 + @param aLocalName Name of attribute
1.1851 + @param aNamespaceUri Namespace uri, default is KNullDesC8.
1.1852 + @return ETrue if the element holds an attribute with such namespace URI and name.
1.1853 + @leave - One of the system-wide error codes
1.1854 + */
1.1855 inline TBool HasAttributeL(const TDesC8& aLocalName,
1.1856 const TDesC8& aNamespaceUri = KNullDesC8) const;
1.1857
1.1858 - /**
1.1859 - * Links attribute into tree
1.1860 - *
1.1861 - * @since S60 v3.1
1.1862 - * @param aNewAttr new attribute
1.1863 - *
1.1864 - * The replaced attribute node is not returned and just deleted
1.1865 - */
1.1866 + /**
1.1867 + Adds an attribute to this element. If an attribute of the same name
1.1868 + exists, it will be destroyed.
1.1869 +
1.1870 + @param aNewAttr The new attribute
1.1871 + @leave KXmlEngErrNullNode The element or attribute is NULL
1.1872 + @leave - One of the system-wide error codes
1.1873 + */
1.1874 IMPORT_C void SetAttributeNodeL(TXmlEngAttr aNewAttr);
1.1875 };
1.1876
1.1877
1.1878 +#include <xml/dom/xmlengelement.inl>
1.1879
1.1880 -#include "xmlengelement.inl"
1.1881 +#endif /* XMLENGELEMENT_H */
1.1882
1.1883 -#endif /* XMLENGINE_ELEMENT_H_INCLUDED */