1.1 --- a/epoc32/include/xmlengnode.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/xmlengnode.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,805 @@
1.4 -xmlengnode.h
1.5 +/*
1.6 +* Copyright (c) 2004-2006 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 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Node class declaration
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +#ifndef XMLENGINE_NODE_H_INCLUDED
1.29 +#define XMLENGINE_NODE_H_INCLUDED
1.30 +
1.31 +#include <e32base.h>
1.32 +
1.33 +// forward declaration
1.34 +class TXmlEngNode;
1.35 +
1.36 +// Forward declarations
1.37 +template<class T> class RXmlEngNodeList;
1.38 +
1.39 +class RXmlEngDocument;
1.40 +class TXmlEngElement;
1.41 +class TXmlEngAttr;
1.42 +class TXmlEngTextNode;
1.43 +class TXmlEngNamespace;
1.44 +class TXmlEngComment;
1.45 +class TXmlEngCDATASection;
1.46 +class TXmlEngDocumentFragment;
1.47 +class TXmlEngEntityReference;
1.48 +class TXmlEngProcessingInstruction;
1.49 +class MXmlEngUserData;
1.50 +class TXmlEngBinaryContainer;
1.51 +class TXmlEngChunkContainer;
1.52 +class TXmlEngDataContainer;
1.53 +class TXmlEngFileContainer;
1.54 +//
1.55 +
1.56 +/**
1.57 + * Instance of TXmlEngNode class represents an XML node in the DOM tree.
1.58 + *
1.59 + * Class implements methods that are similar for all XML node types
1.60 + * i.e. element, attribute.
1.61 + *
1.62 + * Sample code for node tree modifications:
1.63 + * @code
1.64 + * RXmlEngDOMImplementation domImpl;
1.65 + * domImpl.OpenL(); ///< opening DOM implementation object
1.66 + * RXmlEngDocument iDoc; ///< iDoc with created nodes tree
1.67 + * TXmlEngNode tmp = iDoc.DocumentElement();
1.68 + * ///< copying first child of iDoc to tmp2 node and appending it
1.69 + * TXmlEngNode tmp2 = tmp.FirstChild().CopyL();
1.70 + * tmp.AppendChildL(tmp2);
1.71 + * ///< copying next node to the first child of iDoc to the last child place
1.72 + * tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild());
1.73 + * ///< replasing before last child with second child
1.74 + * tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling());
1.75 + * ///< moving first child of iDoc to second child childrens
1.76 + * tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling());
1.77 + * iDoc.Close(); ///< closing all opened objects
1.78 + * domImpl.Close();
1.79 + * @endcode
1.80 + *
1.81 + * @lib XmlEngineDOM.lib
1.82 + * @since S60 v3.1
1.83 + */
1.84 +class TXmlEngNode
1.85 +{
1.86 +public:
1.87 + /**
1.88 + * The different element types carried by an XML tree.
1.89 + *
1.90 + * @note This is synchronized with DOM Level 3 values
1.91 + * See http://www.w3.org/TR/DOM-Level-3-Core/
1.92 + *
1.93 + */
1.94 + enum TXmlEngDOMNodeType {
1.95 + EElement = 1,
1.96 + EAttribute = 2,
1.97 + EText = 3,
1.98 + ECDATASection = 4,
1.99 + EEntityReference = 5,
1.100 + EEntity = 6, //> Not supported currently
1.101 + EProcessingInstruction = 7,
1.102 + EComment = 8,
1.103 + EDocument = 9,
1.104 + EDocumentType = 10, //> Not supported currently
1.105 + EDocumentFragment = 11,
1.106 + ENotation = 12, //> Not supported currently
1.107 + ENamespaceDeclaration = 18, //> Not in DOM spec
1.108 + EBinaryContainer = 30, //> Not in DOM spec
1.109 + EChunkContainer = 31, //> Not in DOM spec
1.110 + EFileContainer = 32 //> Not in DOM spec
1.111 + };
1.112 +
1.113 +public:
1.114 + /**
1.115 + * Default constructor
1.116 + *
1.117 + * @since S60 v3.1
1.118 + */
1.119 + inline TXmlEngNode();
1.120 +
1.121 + /**
1.122 + * Constructor
1.123 + *
1.124 + * @since S60 v3.1
1.125 + * @param aInternal node pointer
1.126 + */
1.127 + inline TXmlEngNode(void* aInternal);
1.128 +
1.129 + /**
1.130 + * Check if node is NULL
1.131 + *
1.132 + * @since S60 v3.1
1.133 + * @return TRUE if node is NULL in other case FALSE
1.134 + */
1.135 + inline TBool IsNull() const;
1.136 +
1.137 + /**
1.138 + * Check if node is NULL
1.139 + *
1.140 + * @since S60 v3.1
1.141 + * @return TRUE if node is not NULL in other case FALSE
1.142 + */
1.143 + inline TBool NotNull()const;
1.144 +
1.145 + /**
1.146 + * Cast node to attribute node.
1.147 + *
1.148 + * @since S60 v3.1
1.149 + * @return Attribute node
1.150 + *
1.151 + * @note
1.152 + * - Never cast nodes to a wrong node type!
1.153 + * - Casting removes const'ness of the node
1.154 + */
1.155 + inline TXmlEngAttr& AsAttr() const;
1.156 +
1.157 + /**
1.158 + * Cast node to text node.
1.159 + *
1.160 + * @since S60 v3.1
1.161 + * @return Text node
1.162 + *
1.163 + * @note
1.164 + * - Never cast nodes to a wrong node type!
1.165 + * - Casting removes const'ness of the node
1.166 + */
1.167 + inline TXmlEngTextNode& AsText() const;
1.168 +
1.169 + /**
1.170 + * Cast node to binary data container
1.171 + *
1.172 + * @since S60 v3.2
1.173 + * @return Binary container
1.174 + *
1.175 + * @note
1.176 + * - Never cast nodes to a wrong node type!
1.177 + * - Casting removes const'ness of the node
1.178 + */
1.179 + inline TXmlEngBinaryContainer& AsBinaryContainer() const;
1.180 +
1.181 + /**
1.182 + * Cast node to memory chunk container
1.183 + *
1.184 + * @since S60 v3.2
1.185 + * @return Chunk container
1.186 + *
1.187 + * @note
1.188 + * - Never cast nodes to a wrong node type!
1.189 + * - Casting removes const'ness of the node
1.190 + */
1.191 + inline TXmlEngChunkContainer& AsChunkContainer() const;
1.192 +
1.193 + /**
1.194 + * Cast node to file container
1.195 + *
1.196 + * @since S60 v3.2
1.197 + * @return File container
1.198 + *
1.199 + * @note
1.200 + * - Never cast nodes to a wrong node type!
1.201 + * - Casting removes const'ness of the node
1.202 + */
1.203 + inline TXmlEngFileContainer& AsFileContainer() const;
1.204 +
1.205 + /**
1.206 + * Cast node to memory chunk container
1.207 + *
1.208 + * @since S60 v3.1
1.209 + * @return Chunk container
1.210 + *
1.211 + * @note
1.212 + * - Never cast nodes to a wrong node type!
1.213 + * - Casting removes const'ness of the node
1.214 + */
1.215 + inline TXmlEngDataContainer& AsDataContainer() const;
1.216 +
1.217 + /**
1.218 + * Cast node to element node.
1.219 + *
1.220 + * @since S60 v3.1
1.221 + * @return Element node
1.222 + *
1.223 + * @note
1.224 + * - Never cast nodes to a wrong node type!
1.225 + * - Casting removes const'ness of the node
1.226 + */
1.227 + inline TXmlEngElement& AsElement() const;
1.228 +
1.229 + /**
1.230 + * Cast node to comment node.
1.231 + *
1.232 + * @since S60 v3.1
1.233 + * @return Comment node
1.234 + *
1.235 + * @note
1.236 + * - Never cast nodes to a wrong node type!
1.237 + * - Casting removes const'ness of the node
1.238 + */
1.239 + inline TXmlEngComment& AsComment() const;
1.240 +
1.241 + /**
1.242 + * Cast node to namespace node.
1.243 + *
1.244 + * @since S60 v3.1
1.245 + * @return Namespace node
1.246 + *
1.247 + * @note
1.248 + * - Never cast nodes to a wrong node type!
1.249 + * - Casting removes const'ness of the node
1.250 + */
1.251 + inline TXmlEngNamespace& AsNamespace() const;
1.252 +
1.253 + /**
1.254 + * Cast node to CDATA section node.
1.255 + *
1.256 + * @since S60 v3.1
1.257 + * @return CDATA section node
1.258 + *
1.259 + * @note
1.260 + * - Never cast nodes to a wrong node type!
1.261 + * - Casting removes const'ness of the node
1.262 + */
1.263 + inline TXmlEngCDATASection& AsCDATASection() const;
1.264 +
1.265 + /**
1.266 + * Cast node to entity reference node.
1.267 + *
1.268 + * @since S60 v3.1
1.269 + * @return Entity reference node
1.270 + *
1.271 + * @note
1.272 + * - Never cast nodes to a wrong node type!
1.273 + * - Casting removes const'ness of the node
1.274 + */
1.275 + inline TXmlEngEntityReference& AsEntityReference() const;
1.276 +
1.277 + /**
1.278 + * Cast node to processing instruction node.
1.279 + *
1.280 + * @since S60 v3.1
1.281 + * @return Processing instruction node
1.282 + *
1.283 + * @note
1.284 + * - Never cast nodes to a wrong node type!
1.285 + * - Casting removes const'ness of the node
1.286 + */
1.287 + inline TXmlEngProcessingInstruction& AsProcessingInstruction() const;
1.288 +
1.289 + /**
1.290 + * Get innerXML string. This method returns all content of the node.
1.291 + * Output text does not include node markup.
1.292 + *
1.293 + * @since S60 v3.1
1.294 + * @param aBuffer RBuf8 in which output should be save
1.295 + * @return Size of output buffer
1.296 + * @note Returned RBuf8 should be freed
1.297 + */
1.298 + IMPORT_C TInt InnerXmlL(RBuf8& aBuffer);
1.299 +
1.300 + /**
1.301 + * Get outerXML string. This method returns all content of the node.
1.302 + * Output text includes node markup.
1.303 + *
1.304 + * @since S60 v3.1
1.305 + * @param aBuffer RBuf8 in which output should be save
1.306 + * @return Size of output buffer
1.307 + * @note Returned RBuf8 should be freed
1.308 + */
1.309 + IMPORT_C TInt OuterXmlL(RBuf8& aBuffer);
1.310 +
1.311 + /**
1.312 + * Moves the node to become the first in the list of its siblings
1.313 + * Node is expected to have a parent.
1.314 + *
1.315 + * @since S60 v3.1
1.316 + */
1.317 + IMPORT_C void SetAsFirstSibling();
1.318 +
1.319 + /**
1.320 + * Moves the node to become the last in the list of its siblings
1.321 + * Node is expected to have a parent.
1.322 + *
1.323 + * @since S60 v3.1
1.324 + */
1.325 + IMPORT_C void SetAsLastSibling();
1.326 +
1.327 + /**
1.328 + * Moves the node in the list of sibling nodes before another node
1.329 + * Node is expected to have a parent.
1.330 + * Do nothing if aSiblingNode is not one of node's siblings
1.331 + *
1.332 + * @since S60 v3.1
1.333 + * @param aSiblingNode Node that should be after current node
1.334 + */
1.335 + IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode);
1.336 +
1.337 + /**
1.338 + * Moves the node in the list of sibling nodes after another node
1.339 + * Node is expected to have a parent.
1.340 + * Do nothing if aSiblingNode is not one of the node's siblings
1.341 + *
1.342 + * @since S60 v3.1
1.343 + * @param aSiblingNode Node that should be after current node
1.344 + */
1.345 + IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode);
1.346 +
1.347 + /**
1.348 + * Moves the node to another part of the tree or another document
1.349 + * The node is unliked from current postion (if any) and appended
1.350 + * to the its new parent.
1.351 + *
1.352 + * @since S60 v3.1
1.353 + * @param aParent Parent node
1.354 + * @return Node handle
1.355 + *
1.356 + * @note
1.357 + * In many cases this method call should be followed by ReconcileNamespacesL() on the moved node
1.358 + */
1.359 + inline TXmlEngNode MoveTo(TXmlEngNode aParent);
1.360 +
1.361 + /**
1.362 + * Detaches a node from document tree
1.363 + *
1.364 + * @since S60 v3.1
1.365 + * @return This node, which is already not a part of any document
1.366 + * @note Remember to use ReconcileNamespacesL() later, if extracted node (subtree)
1.367 + * contains references to namespace declarations outside of the subtree.
1.368 + * @see ReconcileNamespacesL()
1.369 + * @note The document, from which the is being unlinked, becomes an owner of the node
1.370 + * until it is linked elsewhere.
1.371 + */
1.372 + IMPORT_C TXmlEngNode Unlink();
1.373 +
1.374 + /**
1.375 + * Ensures that namespaces referred to in the node and its descendants are
1.376 + * in the scope the node.
1.377 + *
1.378 + * This method checks that all the namespaces declared within the given
1.379 + * tree are properly declared. This is needed for example after Copy or Unlink
1.380 + * and then Append operations. The subtree may still hold pointers to
1.381 + * namespace declarations outside the subtree or they may be invalid/masked. As much
1.382 + * as possible the function try to reuse the existing namespaces found in
1.383 + * the new environment. If not possible, the new namespaces are redeclared
1.384 + * on the top of the subtree.
1.385 + *
1.386 + * This method should be used after unlinking nodes and inserting to another
1.387 + * document tree or to a another part of the original tree, if some nodes of the subtree
1.388 + * are remove from the scope of a namespace declaration they refer to.
1.389 + *
1.390 + * When node is unlinked, it may still refer to namespace declarations from the previous location.
1.391 + * It is important to reconcile subtree's namespaces if previous parent tree is to be destroyed.
1.392 + * On the other hand, if the parent tree is not changed before pasting its unlinked part into another
1.393 + * tree, then reconciliation is needed only after paste operation.
1.394 + *
1.395 + * @since S60 v3.1
1.396 + */
1.397 + IMPORT_C void ReconcileNamespacesL();
1.398 +
1.399 + /**
1.400 + * Unlinks the node and destroys it; all child nodes are destroyed as well and all memory is freed
1.401 + *
1.402 + * @note Document nodes cannot be "removed" with this method, uses RXmlEngDocument-specific methods.
1.403 + *
1.404 + * @since S60 v3.1
1.405 + */
1.406 + IMPORT_C void Remove();
1.407 +
1.408 + /**
1.409 + * Current node is replaced with another node (subtree).
1.410 + *
1.411 + * The replacement node is linked into document tree instead of this node.
1.412 + * The replaced node is destroyed.
1.413 + *
1.414 + * @since S60 v3.1
1.415 + * @param aNode Node that repleace current node
1.416 + *
1.417 + * @see SubstituteFor(TXmlEngNode)
1.418 + *
1.419 + * In both cases the argument node is unlinked from its previous location
1.420 + * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree).
1.421 + *
1.422 + * @note Replacement of a node with NULL TXmlEngNode is legal and equivalent to removing the node.
1.423 + * @note Not applicable to document nodes
1.424 + */
1.425 + IMPORT_C void ReplaceWith(TXmlEngNode aNode);
1.426 +
1.427 + /**
1.428 + * Another node is put instead of the current node.
1.429 + *
1.430 + * Does the same as ReplaceWith(TXmlEngNode) but does not free node and just returns it.
1.431 + *
1.432 + * @since S60 v3.1
1.433 + * @param aNode Node that repleace current node
1.434 + * @return Current node after unlinking it from document tree
1.435 + * @see ReplaceWith(TXmlEngNode)
1.436 + *
1.437 + * In both cases the argument node is unlinked from its previous location
1.438 + * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree)
1.439 + *
1.440 + * It is possible to use NULL TXmlEngNode object as an argument. In such case
1.441 + * no new node will be put instead of unlinked one.
1.442 + *
1.443 + * @note Not applicable to document nodes
1.444 + */
1.445 + IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode);
1.446 +
1.447 + /**
1.448 + * Retrieves a "handle" for namespace declaration that applies to the node's namespace
1.449 + * Note: DOM specs do not consider namespace declarations as a kind of nodes
1.450 + * This API adds TXmlEngNamespace type of nodes, which is derived from TXmlEngNode.
1.451 + *
1.452 + * @since S60 v3.1
1.453 + * @return Object that represents namespace declaration and prefix binding that
1.454 + * act on the node; returns NULL object (check using TXmlEngNamespace.IsNull()
1.455 + * or TXmlEngNamespace.NotNull()) if no namespace associated
1.456 + */
1.457 + IMPORT_C TXmlEngNamespace NamespaceDeclaration() const;
1.458 +
1.459 + /**
1.460 + * Attaches a user data object to this node. The ownership of the object is transferred.
1.461 + * When the (underlying) node is deleted the Destroy method of the MXmlEngUserData class will be
1.462 + * called. If there already is a user data object associated with this node, it will be
1.463 + * deleted before attaching the new object.
1.464 + *
1.465 + * @since S60 v3.1
1.466 + * @param aData Pointer to the data object.
1.467 + * @return true if successful, false if for example underlying node type doesn't support
1.468 + * attaching user data.
1.469 + * @note Only TXmlEngElement and Attribute nodes currently support this feature.
1.470 + * User data is not copied, when node is copied.
1.471 + */
1.472 + IMPORT_C TBool AddUserData(MXmlEngUserData* aData);
1.473 +
1.474 + /**
1.475 + * Returns the user data object attached to this node. Ownership is not transferred.
1.476 + *
1.477 + * @since S60 v3.1
1.478 + * @return Pointer to data object or NULL if it doesn't exist.
1.479 + */
1.480 + IMPORT_C MXmlEngUserData* UserData() const;
1.481 +
1.482 + /**
1.483 + * Removes the user data onject attached to this node. Ownership is transferred
1.484 + * (the object is not deleted).
1.485 + *
1.486 + * @since S60 v3.1
1.487 + * @return Pointer to data object or NULL if it doesn't exist.
1.488 + */
1.489 + IMPORT_C MXmlEngUserData* RemoveUserData();
1.490 +
1.491 + /**
1.492 + * Clones the node completely: all attributes and namespace declarations (for TXmlEngElement nodes),
1.493 + * values and children nodes are copied as well.
1.494 + *
1.495 + * Document nodes cannot be copied with this method: RXmlEngDocument::CloneDocumentL() must be used.
1.496 + *
1.497 + * @since S60 v3.1
1.498 + * @return Complete copy of a node or leaves.
1.499 + * @note The node should not be NULL!
1.500 + */
1.501 + IMPORT_C TXmlEngNode CopyL() const;
1.502 +
1.503 + /**
1.504 + * Creates a deep copy of the node and appends the subtree as a new child
1.505 + * to the provided parent node.
1.506 + *
1.507 + * @since S60 v3.1
1.508 + * @return Created copy of the node after linking it into the target document tree.
1.509 + * @note Document nodes cannot be copied with this method; use RXmlEngDocument::CloneDocumentL()
1.510 + */
1.511 + IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const;
1.512 +
1.513 + /**
1.514 + * Append a child node.
1.515 + *
1.516 + * This is universal operation for any types of nodes.
1.517 + * Note, that some types of nodes cannot have children and
1.518 + * some types of nodes are not allowed to be children of some other types.
1.519 + *
1.520 + * @since S60 v3.1
1.521 + * @param aNewChild Child node that should be added
1.522 + * @return Appended node, which could changed as a result of adding it to
1.523 + * list of child nodes (e.g. text nodes can coalesce together)
1.524 + */
1.525 + IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild);
1.526 +
1.527 + /**
1.528 + * Initializes a node list with all children of the node
1.529 + *
1.530 + * @since S60 v3.1
1.531 + * @param aList node list that should be initialized
1.532 + */
1.533 + IMPORT_C void GetChildNodes(RXmlEngNodeList<TXmlEngNode>& aList) const;
1.534 +
1.535 + /**
1.536 + * Get parent node of current node.
1.537 + *
1.538 + * @since S60 v3.1
1.539 + * @return Parent node of the node or NULL if no parent
1.540 + */
1.541 + IMPORT_C TXmlEngNode ParentNode() const;
1.542 +
1.543 + /**
1.544 + * Get first child of current node
1.545 + *
1.546 + * @since S60 v3.1
1.547 + * @return The first child node or NULL if no children
1.548 + */
1.549 + IMPORT_C TXmlEngNode FirstChild() const;
1.550 +
1.551 + /**
1.552 + * Get last child of current node
1.553 + *
1.554 + * @since S60 v3.1
1.555 + * @return The last child node or NULL if no children
1.556 + */
1.557 + IMPORT_C TXmlEngNode LastChild() const;
1.558 +
1.559 + /**
1.560 + * Get previous node of current node
1.561 + *
1.562 + * @since S60 v3.1
1.563 + * @return Previous node in a child list or NULL if no sibling before
1.564 + */
1.565 + IMPORT_C TXmlEngNode PreviousSibling() const;
1.566 +
1.567 + /**
1.568 + * Get fallowing node of current node
1.569 + *
1.570 + * @since S60 v3.1
1.571 + * @return Following node in a child list or NULL if no sibling after
1.572 + */
1.573 + IMPORT_C TXmlEngNode NextSibling() const;
1.574 +
1.575 + /**
1.576 + * Get document handle
1.577 + *
1.578 + * @since S60 v3.1
1.579 + * @return A document node of the DOM tree this node belongs to
1.580 + *
1.581 + * @note An instance of RXmlEngDocument class returns itself
1.582 + */
1.583 + IMPORT_C RXmlEngDocument OwnerDocument() const;
1.584 +
1.585 + /**
1.586 + * Fetches value of this node, depending on its type.
1.587 + *
1.588 + * @note It is better to always cast nodes to specific type and then use specific
1.589 + * method for getting "node value"
1.590 + *
1.591 + * @since S60 v3.1
1.592 + * @return Node value
1.593 + */
1.594 + IMPORT_C TPtrC8 Value() const;
1.595 +
1.596 + /**
1.597 + * Get copy of node's text content
1.598 + * What is returned depends on the node type.
1.599 + * Method caller is responsible for freeing returned string.
1.600 + *
1.601 + * @since S60 v3.1
1.602 + * @return the content of the node
1.603 + */
1.604 + IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const;
1.605 +
1.606 + /**
1.607 + * Sets value of this node.
1.608 + *
1.609 + * @since S60 v3.1
1.610 + * @param aValue New value
1.611 + */
1.612 + IMPORT_C void SetValueL(const TDesC8& aValue);
1.613 +
1.614 + /**
1.615 + * Check if node content is "simple text".
1.616 + *
1.617 + * @since S60 v3.1
1.618 + * @return Whether the value of the node is presented by only one TXmlEngTextNode node
1.619 + *
1.620 + * If the value is <i>"simple text"</i> then it is possible to access it as TDOMString
1.621 + * without making copy, which combines values of all text nodes and entity reference nodes.
1.622 + *
1.623 + * @see TXmlEngNode::Value(), TXmlEngAttr::Value(), TXmlEngElement::Text()
1.624 + *
1.625 + * This method is applicable to TXmlEngElement and TXmlEngAttr nodes. On other nodes FALSE is returned.
1.626 + *
1.627 + * @note
1.628 + * Values (contents) of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, ProcessingInstuction data are
1.629 + * always "simple".
1.630 + *
1.631 + * When the returned result is FALSE, getting value of the node would not returned
1.632 + * whole contents because of either entity references present in the contents or
1.633 + * the contents is mixed (for TXmlEngElement node). In this case WholeTextContentsCopyL()
1.634 + * should be used.
1.635 + *
1.636 + * @see TXmlEngNode::WholeTextContentsCopyL()
1.637 + */
1.638 + IMPORT_C TBool IsSimpleTextContents() const;
1.639 +
1.640 + /**
1.641 + * Use NodeType() to find out the type of the node prior to casting object
1.642 + * of TXmlEngNode class to one of its derived subclasses (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.)
1.643 + *
1.644 + * @since S60 v3.1
1.645 + * @return Type of the node
1.646 + *
1.647 + * @see TXmlEngDOMNodeType
1.648 + */
1.649 + IMPORT_C TXmlEngDOMNodeType NodeType() const;
1.650 +
1.651 + /**
1.652 + * Get node name
1.653 + *
1.654 + * @since S60 v3.1
1.655 + * @return Name of the node
1.656 + *
1.657 + * This method generally follows DOM spec :
1.658 + * -------------------------------------------------------------------------------
1.659 + * The values of nodeName, nodeValue, and attributes vary according to the node
1.660 + * type as follows:
1.661 + *
1.662 + * interface nodeName nodeValue attributes
1.663 + * -------------------------------------------------------------------------------
1.664 + * Attr = Attr.name = Attr.value = null
1.665 + * CDATASection = "#cdata-section" = CharacterData.data = null
1.666 + * Comment = "#comment" = CharacterData.data = null
1.667 + * Document = "#document" = null = null
1.668 + * DocumentFragment = "#document-fragment" = null = null
1.669 + * DocumentType = DocumentType.name = null = null
1.670 + * Element = Element.tagName = null = NamedNodeMap
1.671 + * Entity = entity name = null = null
1.672 + * EntityReference = name of entity referenced = null = null
1.673 + * Notation = notation name = null = null
1.674 + * ProcessingInstruction = target = data = null
1.675 + * Text = "#text" = CharacterData.data = null
1.676 + * -------------------------------------------------------------------------------
1.677 + */
1.678 + IMPORT_C TPtrC8 Name() const;
1.679 +
1.680 +
1.681 + /**
1.682 + * Check if node has child nodes.
1.683 + *
1.684 + * @since S60 v3.1
1.685 + * @return True if the node is TXmlEngElement and has at least one child node
1.686 + */
1.687 + IMPORT_C TBool HasChildNodes() const;
1.688 +
1.689 + /**
1.690 + * Check if node has attributes.
1.691 + *
1.692 + * @since S60 v3.1
1.693 + * @return True if the node is TXmlEngElement and has at least one attribute
1.694 + *
1.695 + * @note Namespace-to-prefix bindings are not attributes.
1.696 + */
1.697 + IMPORT_C TBool HasAttributes() const;
1.698 +
1.699 + /**
1.700 + * Evaluates active base URI for the node by processing xml:base attributes of parents
1.701 + *
1.702 + * @since S60 v3.1
1.703 + * @return A copy of effective base URI for the node
1.704 + * @note It's up to the caller to free the string
1.705 + */
1.706 + IMPORT_C void BaseUriL(RBuf8& aBaseUri) const;
1.707 +
1.708 + /**
1.709 + * Compares nodes.
1.710 + *
1.711 + * The nodes are the same if they are referring to the same in-memory
1.712 + * data structure.
1.713 + *
1.714 + * @since S60 v3.1
1.715 + * @param aOther Node to compare
1.716 + * @return TRUE if the same
1.717 + */
1.718 + inline TBool IsSameNode(TXmlEngNode aOther) const;
1.719 +
1.720 + /**
1.721 + * Get namespace uri.
1.722 + *
1.723 + * @since S60 v3.1
1.724 + * @return Namespace URI of a node
1.725 + * - NULL is returned for elements and attributes that do not
1.726 + * belong to any namespace.
1.727 + * - bound namespace URI is returned for namespace declaration nodes (instances of TXmlEngNamespace).
1.728 + * - NULL is returned to all other types of node.
1.729 + *
1.730 + * @note use IsNull() and NotNull() for testing returned result on the subject
1.731 + * of having some URI
1.732 + */
1.733 + IMPORT_C TPtrC8 NamespaceUri() const;
1.734 +
1.735 + /**
1.736 + * Get namespace prefix.
1.737 + *
1.738 + * @since S60 v3.1
1.739 + * @return Prefix of a node
1.740 + * Returns NULL for elements and attributes that do not have prefix
1.741 + * (node belongs to the default namespace or does not belong to any namespace)
1.742 + * NULL is also returned for all types of node other than TXmlEngElement or TXmlEngAttr
1.743 + */
1.744 + IMPORT_C TPtrC8 Prefix() const;
1.745 +
1.746 + /**
1.747 + * Check if nemespace is default for this node
1.748 + *
1.749 + * @since S60 v3.1
1.750 + * @param aNamespaceUri Namespace URI
1.751 + * @return True if given namespace URI is a default one for the node (applicable to elements only)
1.752 + *
1.753 + * @note "" or NULL can be used to denote undefined namespace
1.754 + */
1.755 + IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const;
1.756 +
1.757 + /**
1.758 + * Searches the prefix that is bound to the given aNamespaceUri and
1.759 + * applicable in the scope of this TXmlEngNode.
1.760 + *
1.761 + * @since S60 v3.1
1.762 + * @param aNamespaceUri Namespace Uri that should be found
1.763 + * @return A sought prefix or NULL if not found or aNamespaceUri is the default namespace
1.764 + *
1.765 + * @see TXmlEngElement::LookupNamespaceByUriL(const TDesC8&)
1.766 + */
1.767 + IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const;
1.768 +
1.769 + /**
1.770 + * Searches the namespace URI that is bound to the given prefix.
1.771 + *
1.772 + * @since S60 v3.1
1.773 + * @param aPrefix Namespace prefix that should be found
1.774 + * @return A sought URI or NULL if the prefix is not bound
1.775 + *
1.776 + * @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&)
1.777 + */
1.778 + IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const;
1.779 +
1.780 +protected:
1.781 + /**
1.782 + * Unlinks the internal libxml2's node from double-linked list.
1.783 + * Relinks neighbour nodes.The node stays virtually linked to its old neighbours! Use with care!!
1.784 + *
1.785 + * No checks are made; nor parent's, nor node's properties updated
1.786 + *
1.787 + * @since S60 v3.1
1.788 + */
1.789 + void DoUnlinkNode();
1.790 +
1.791 + /**
1.792 + * Inserts the node in a double-linked list of nodes before specified node.
1.793 + *
1.794 + * No checks are made; nor parent's, nor node's properties updated (except prev/next)
1.795 + *
1.796 + * @since S60 v3.1
1.797 + * @param aNode Target node
1.798 + */
1.799 + void LinkBefore(TXmlEngNode aNode);
1.800 +
1.801 +protected:
1.802 + /** Node pointer */
1.803 + void* iInternal;
1.804 +
1.805 +};
1.806 +
1.807 +#include "xmlengnode.inl"
1.808 +
1.809 +#endif /* XMLENGINE_NODE_H_INCLUDED */