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