diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/xmlengnode.h --- a/epoc32/include/xmlengnode.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/xmlengnode.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,805 @@ -xmlengnode.h +/* +* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* 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 +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Node class declaration +* +*/ + + + + + + + +#ifndef XMLENGINE_NODE_H_INCLUDED +#define XMLENGINE_NODE_H_INCLUDED + +#include + +// forward declaration +class TXmlEngNode; + +// Forward declarations +template class RXmlEngNodeList; + +class RXmlEngDocument; +class TXmlEngElement; +class TXmlEngAttr; +class TXmlEngTextNode; +class TXmlEngNamespace; +class TXmlEngComment; +class TXmlEngCDATASection; +class TXmlEngDocumentFragment; +class TXmlEngEntityReference; +class TXmlEngProcessingInstruction; +class MXmlEngUserData; +class TXmlEngBinaryContainer; +class TXmlEngChunkContainer; +class TXmlEngDataContainer; +class TXmlEngFileContainer; +// + +/** + * Instance of TXmlEngNode class represents an XML node in the DOM tree. + * + * Class implements methods that are similar for all XML node types + * i.e. element, attribute. + * + * Sample code for node tree modifications: + * @code + * RXmlEngDOMImplementation domImpl; + * domImpl.OpenL(); ///< opening DOM implementation object + * RXmlEngDocument iDoc; ///< iDoc with created nodes tree + * TXmlEngNode tmp = iDoc.DocumentElement(); + * ///< copying first child of iDoc to tmp2 node and appending it + * TXmlEngNode tmp2 = tmp.FirstChild().CopyL(); + * tmp.AppendChildL(tmp2); + * ///< copying next node to the first child of iDoc to the last child place + * tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild()); + * ///< replasing before last child with second child + * tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling()); + * ///< moving first child of iDoc to second child childrens + * tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling()); + * iDoc.Close(); ///< closing all opened objects + * domImpl.Close(); + * @endcode + * + * @lib XmlEngineDOM.lib + * @since S60 v3.1 + */ +class TXmlEngNode +{ +public: + /** + * The different element types carried by an XML tree. + * + * @note This is synchronized with DOM Level 3 values + * See http://www.w3.org/TR/DOM-Level-3-Core/ + * + */ + enum TXmlEngDOMNodeType { + EElement = 1, + EAttribute = 2, + EText = 3, + ECDATASection = 4, + EEntityReference = 5, + EEntity = 6, //> Not supported currently + EProcessingInstruction = 7, + EComment = 8, + EDocument = 9, + EDocumentType = 10, //> Not supported currently + EDocumentFragment = 11, + ENotation = 12, //> Not supported currently + ENamespaceDeclaration = 18, //> Not in DOM spec + EBinaryContainer = 30, //> Not in DOM spec + EChunkContainer = 31, //> Not in DOM spec + EFileContainer = 32 //> Not in DOM spec + }; + +public: + /** + * Default constructor + * + * @since S60 v3.1 + */ + inline TXmlEngNode(); + + /** + * Constructor + * + * @since S60 v3.1 + * @param aInternal node pointer + */ + inline TXmlEngNode(void* aInternal); + + /** + * Check if node is NULL + * + * @since S60 v3.1 + * @return TRUE if node is NULL in other case FALSE + */ + inline TBool IsNull() const; + + /** + * Check if node is NULL + * + * @since S60 v3.1 + * @return TRUE if node is not NULL in other case FALSE + */ + inline TBool NotNull()const; + + /** + * Cast node to attribute node. + * + * @since S60 v3.1 + * @return Attribute node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngAttr& AsAttr() const; + + /** + * Cast node to text node. + * + * @since S60 v3.1 + * @return Text node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngTextNode& AsText() const; + + /** + * Cast node to binary data container + * + * @since S60 v3.2 + * @return Binary container + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngBinaryContainer& AsBinaryContainer() const; + + /** + * Cast node to memory chunk container + * + * @since S60 v3.2 + * @return Chunk container + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngChunkContainer& AsChunkContainer() const; + + /** + * Cast node to file container + * + * @since S60 v3.2 + * @return File container + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngFileContainer& AsFileContainer() const; + + /** + * Cast node to memory chunk container + * + * @since S60 v3.1 + * @return Chunk container + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngDataContainer& AsDataContainer() const; + + /** + * Cast node to element node. + * + * @since S60 v3.1 + * @return Element node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngElement& AsElement() const; + + /** + * Cast node to comment node. + * + * @since S60 v3.1 + * @return Comment node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngComment& AsComment() const; + + /** + * Cast node to namespace node. + * + * @since S60 v3.1 + * @return Namespace node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngNamespace& AsNamespace() const; + + /** + * Cast node to CDATA section node. + * + * @since S60 v3.1 + * @return CDATA section node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngCDATASection& AsCDATASection() const; + + /** + * Cast node to entity reference node. + * + * @since S60 v3.1 + * @return Entity reference node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngEntityReference& AsEntityReference() const; + + /** + * Cast node to processing instruction node. + * + * @since S60 v3.1 + * @return Processing instruction node + * + * @note + * - Never cast nodes to a wrong node type! + * - Casting removes const'ness of the node + */ + inline TXmlEngProcessingInstruction& AsProcessingInstruction() const; + + /** + * Get innerXML string. This method returns all content of the node. + * Output text does not include node markup. + * + * @since S60 v3.1 + * @param aBuffer RBuf8 in which output should be save + * @return Size of output buffer + * @note Returned RBuf8 should be freed + */ + IMPORT_C TInt InnerXmlL(RBuf8& aBuffer); + + /** + * Get outerXML string. This method returns all content of the node. + * Output text includes node markup. + * + * @since S60 v3.1 + * @param aBuffer RBuf8 in which output should be save + * @return Size of output buffer + * @note Returned RBuf8 should be freed + */ + IMPORT_C TInt OuterXmlL(RBuf8& aBuffer); + + /** + * Moves the node to become the first in the list of its siblings + * Node is expected to have a parent. + * + * @since S60 v3.1 + */ + IMPORT_C void SetAsFirstSibling(); + + /** + * Moves the node to become the last in the list of its siblings + * Node is expected to have a parent. + * + * @since S60 v3.1 + */ + IMPORT_C void SetAsLastSibling(); + + /** + * Moves the node in the list of sibling nodes before another node + * Node is expected to have a parent. + * Do nothing if aSiblingNode is not one of node's siblings + * + * @since S60 v3.1 + * @param aSiblingNode Node that should be after current node + */ + IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode); + + /** + * Moves the node in the list of sibling nodes after another node + * Node is expected to have a parent. + * Do nothing if aSiblingNode is not one of the node's siblings + * + * @since S60 v3.1 + * @param aSiblingNode Node that should be after current node + */ + IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode); + + /** + * Moves the node to another part of the tree or another document + * The node is unliked from current postion (if any) and appended + * to the its new parent. + * + * @since S60 v3.1 + * @param aParent Parent node + * @return Node handle + * + * @note + * In many cases this method call should be followed by ReconcileNamespacesL() on the moved node + */ + inline TXmlEngNode MoveTo(TXmlEngNode aParent); + + /** + * Detaches a node from document tree + * + * @since S60 v3.1 + * @return This node, which is already not a part of any document + * @note Remember to use ReconcileNamespacesL() later, if extracted node (subtree) + * contains references to namespace declarations outside of the subtree. + * @see ReconcileNamespacesL() + * @note The document, from which the is being unlinked, becomes an owner of the node + * until it is linked elsewhere. + */ + IMPORT_C TXmlEngNode Unlink(); + + /** + * Ensures that namespaces referred to in the node and its descendants are + * in the scope the node. + * + * This method checks that all the namespaces declared within the given + * tree are properly declared. This is needed for example after Copy or Unlink + * and then Append operations. The subtree may still hold pointers to + * namespace declarations outside the subtree or they may be invalid/masked. As much + * as possible the function try to reuse the existing namespaces found in + * the new environment. If not possible, the new namespaces are redeclared + * on the top of the subtree. + * + * This method should be used after unlinking nodes and inserting to another + * document tree or to a another part of the original tree, if some nodes of the subtree + * are remove from the scope of a namespace declaration they refer to. + * + * When node is unlinked, it may still refer to namespace declarations from the previous location. + * It is important to reconcile subtree's namespaces if previous parent tree is to be destroyed. + * On the other hand, if the parent tree is not changed before pasting its unlinked part into another + * tree, then reconciliation is needed only after paste operation. + * + * @since S60 v3.1 + */ + IMPORT_C void ReconcileNamespacesL(); + + /** + * Unlinks the node and destroys it; all child nodes are destroyed as well and all memory is freed + * + * @note Document nodes cannot be "removed" with this method, uses RXmlEngDocument-specific methods. + * + * @since S60 v3.1 + */ + IMPORT_C void Remove(); + + /** + * Current node is replaced with another node (subtree). + * + * The replacement node is linked into document tree instead of this node. + * The replaced node is destroyed. + * + * @since S60 v3.1 + * @param aNode Node that repleace current node + * + * @see SubstituteFor(TXmlEngNode) + * + * In both cases the argument node is unlinked from its previous location + * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree). + * + * @note Replacement of a node with NULL TXmlEngNode is legal and equivalent to removing the node. + * @note Not applicable to document nodes + */ + IMPORT_C void ReplaceWith(TXmlEngNode aNode); + + /** + * Another node is put instead of the current node. + * + * Does the same as ReplaceWith(TXmlEngNode) but does not free node and just returns it. + * + * @since S60 v3.1 + * @param aNode Node that repleace current node + * @return Current node after unlinking it from document tree + * @see ReplaceWith(TXmlEngNode) + * + * In both cases the argument node is unlinked from its previous location + * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree) + * + * It is possible to use NULL TXmlEngNode object as an argument. In such case + * no new node will be put instead of unlinked one. + * + * @note Not applicable to document nodes + */ + IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode); + + /** + * Retrieves a "handle" for namespace declaration that applies to the node's namespace + * Note: DOM specs do not consider namespace declarations as a kind of nodes + * This API adds TXmlEngNamespace type of nodes, which is derived from TXmlEngNode. + * + * @since S60 v3.1 + * @return Object that represents namespace declaration and prefix binding that + * act on the node; returns NULL object (check using TXmlEngNamespace.IsNull() + * or TXmlEngNamespace.NotNull()) if no namespace associated + */ + IMPORT_C TXmlEngNamespace NamespaceDeclaration() const; + + /** + * Attaches a user data object to this node. The ownership of the object is transferred. + * When the (underlying) node is deleted the Destroy method of the MXmlEngUserData class will be + * called. If there already is a user data object associated with this node, it will be + * deleted before attaching the new object. + * + * @since S60 v3.1 + * @param aData Pointer to the data object. + * @return true if successful, false if for example underlying node type doesn't support + * attaching user data. + * @note Only TXmlEngElement and Attribute nodes currently support this feature. + * User data is not copied, when node is copied. + */ + IMPORT_C TBool AddUserData(MXmlEngUserData* aData); + + /** + * Returns the user data object attached to this node. Ownership is not transferred. + * + * @since S60 v3.1 + * @return Pointer to data object or NULL if it doesn't exist. + */ + IMPORT_C MXmlEngUserData* UserData() const; + + /** + * Removes the user data onject attached to this node. Ownership is transferred + * (the object is not deleted). + * + * @since S60 v3.1 + * @return Pointer to data object or NULL if it doesn't exist. + */ + IMPORT_C MXmlEngUserData* RemoveUserData(); + + /** + * Clones the node completely: all attributes and namespace declarations (for TXmlEngElement nodes), + * values and children nodes are copied as well. + * + * Document nodes cannot be copied with this method: RXmlEngDocument::CloneDocumentL() must be used. + * + * @since S60 v3.1 + * @return Complete copy of a node or leaves. + * @note The node should not be NULL! + */ + IMPORT_C TXmlEngNode CopyL() const; + + /** + * Creates a deep copy of the node and appends the subtree as a new child + * to the provided parent node. + * + * @since S60 v3.1 + * @return Created copy of the node after linking it into the target document tree. + * @note Document nodes cannot be copied with this method; use RXmlEngDocument::CloneDocumentL() + */ + IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const; + + /** + * Append a child node. + * + * This is universal operation for any types of nodes. + * Note, that some types of nodes cannot have children and + * some types of nodes are not allowed to be children of some other types. + * + * @since S60 v3.1 + * @param aNewChild Child node that should be added + * @return Appended node, which could changed as a result of adding it to + * list of child nodes (e.g. text nodes can coalesce together) + */ + IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild); + + /** + * Initializes a node list with all children of the node + * + * @since S60 v3.1 + * @param aList node list that should be initialized + */ + IMPORT_C void GetChildNodes(RXmlEngNodeList& aList) const; + + /** + * Get parent node of current node. + * + * @since S60 v3.1 + * @return Parent node of the node or NULL if no parent + */ + IMPORT_C TXmlEngNode ParentNode() const; + + /** + * Get first child of current node + * + * @since S60 v3.1 + * @return The first child node or NULL if no children + */ + IMPORT_C TXmlEngNode FirstChild() const; + + /** + * Get last child of current node + * + * @since S60 v3.1 + * @return The last child node or NULL if no children + */ + IMPORT_C TXmlEngNode LastChild() const; + + /** + * Get previous node of current node + * + * @since S60 v3.1 + * @return Previous node in a child list or NULL if no sibling before + */ + IMPORT_C TXmlEngNode PreviousSibling() const; + + /** + * Get fallowing node of current node + * + * @since S60 v3.1 + * @return Following node in a child list or NULL if no sibling after + */ + IMPORT_C TXmlEngNode NextSibling() const; + + /** + * Get document handle + * + * @since S60 v3.1 + * @return A document node of the DOM tree this node belongs to + * + * @note An instance of RXmlEngDocument class returns itself + */ + IMPORT_C RXmlEngDocument OwnerDocument() const; + + /** + * Fetches value of this node, depending on its type. + * + * @note It is better to always cast nodes to specific type and then use specific + * method for getting "node value" + * + * @since S60 v3.1 + * @return Node value + */ + IMPORT_C TPtrC8 Value() const; + + /** + * Get copy of node's text content + * What is returned depends on the node type. + * Method caller is responsible for freeing returned string. + * + * @since S60 v3.1 + * @return the content of the node + */ + IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const; + + /** + * Sets value of this node. + * + * @since S60 v3.1 + * @param aValue New value + */ + IMPORT_C void SetValueL(const TDesC8& aValue); + + /** + * Check if node content is "simple text". + * + * @since S60 v3.1 + * @return Whether the value of the node is presented by only one TXmlEngTextNode node + * + * If the value is "simple text" then it is possible to access it as TDOMString + * without making copy, which combines values of all text nodes and entity reference nodes. + * + * @see TXmlEngNode::Value(), TXmlEngAttr::Value(), TXmlEngElement::Text() + * + * This method is applicable to TXmlEngElement and TXmlEngAttr nodes. On other nodes FALSE is returned. + * + * @note + * Values (contents) of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, ProcessingInstuction data are + * always "simple". + * + * When the returned result is FALSE, getting value of the node would not returned + * whole contents because of either entity references present in the contents or + * the contents is mixed (for TXmlEngElement node). In this case WholeTextContentsCopyL() + * should be used. + * + * @see TXmlEngNode::WholeTextContentsCopyL() + */ + IMPORT_C TBool IsSimpleTextContents() const; + + /** + * Use NodeType() to find out the type of the node prior to casting object + * of TXmlEngNode class to one of its derived subclasses (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.) + * + * @since S60 v3.1 + * @return Type of the node + * + * @see TXmlEngDOMNodeType + */ + IMPORT_C TXmlEngDOMNodeType NodeType() const; + + /** + * Get node name + * + * @since S60 v3.1 + * @return Name of the node + * + * This method generally follows DOM spec : + * ------------------------------------------------------------------------------- + * The values of nodeName, nodeValue, and attributes vary according to the node + * type as follows: + * + * interface nodeName nodeValue attributes + * ------------------------------------------------------------------------------- + * Attr = Attr.name = Attr.value = null + * CDATASection = "#cdata-section" = CharacterData.data = null + * Comment = "#comment" = CharacterData.data = null + * Document = "#document" = null = null + * DocumentFragment = "#document-fragment" = null = null + * DocumentType = DocumentType.name = null = null + * Element = Element.tagName = null = NamedNodeMap + * Entity = entity name = null = null + * EntityReference = name of entity referenced = null = null + * Notation = notation name = null = null + * ProcessingInstruction = target = data = null + * Text = "#text" = CharacterData.data = null + * ------------------------------------------------------------------------------- + */ + IMPORT_C TPtrC8 Name() const; + + + /** + * Check if node has child nodes. + * + * @since S60 v3.1 + * @return True if the node is TXmlEngElement and has at least one child node + */ + IMPORT_C TBool HasChildNodes() const; + + /** + * Check if node has attributes. + * + * @since S60 v3.1 + * @return True if the node is TXmlEngElement and has at least one attribute + * + * @note Namespace-to-prefix bindings are not attributes. + */ + IMPORT_C TBool HasAttributes() const; + + /** + * Evaluates active base URI for the node by processing xml:base attributes of parents + * + * @since S60 v3.1 + * @return A copy of effective base URI for the node + * @note It's up to the caller to free the string + */ + IMPORT_C void BaseUriL(RBuf8& aBaseUri) const; + + /** + * Compares nodes. + * + * The nodes are the same if they are referring to the same in-memory + * data structure. + * + * @since S60 v3.1 + * @param aOther Node to compare + * @return TRUE if the same + */ + inline TBool IsSameNode(TXmlEngNode aOther) const; + + /** + * Get namespace uri. + * + * @since S60 v3.1 + * @return Namespace URI of a node + * - NULL is returned for elements and attributes that do not + * belong to any namespace. + * - bound namespace URI is returned for namespace declaration nodes (instances of TXmlEngNamespace). + * - NULL is returned to all other types of node. + * + * @note use IsNull() and NotNull() for testing returned result on the subject + * of having some URI + */ + IMPORT_C TPtrC8 NamespaceUri() const; + + /** + * Get namespace prefix. + * + * @since S60 v3.1 + * @return Prefix of a node + * Returns NULL for elements and attributes that do not have prefix + * (node belongs to the default namespace or does not belong to any namespace) + * NULL is also returned for all types of node other than TXmlEngElement or TXmlEngAttr + */ + IMPORT_C TPtrC8 Prefix() const; + + /** + * Check if nemespace is default for this node + * + * @since S60 v3.1 + * @param aNamespaceUri Namespace URI + * @return True if given namespace URI is a default one for the node (applicable to elements only) + * + * @note "" or NULL can be used to denote undefined namespace + */ + IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const; + + /** + * Searches the prefix that is bound to the given aNamespaceUri and + * applicable in the scope of this TXmlEngNode. + * + * @since S60 v3.1 + * @param aNamespaceUri Namespace Uri that should be found + * @return A sought prefix or NULL if not found or aNamespaceUri is the default namespace + * + * @see TXmlEngElement::LookupNamespaceByUriL(const TDesC8&) + */ + IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const; + + /** + * Searches the namespace URI that is bound to the given prefix. + * + * @since S60 v3.1 + * @param aPrefix Namespace prefix that should be found + * @return A sought URI or NULL if the prefix is not bound + * + * @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&) + */ + IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const; + +protected: + /** + * Unlinks the internal libxml2's node from double-linked list. + * Relinks neighbour nodes.The node stays virtually linked to its old neighbours! Use with care!! + * + * No checks are made; nor parent's, nor node's properties updated + * + * @since S60 v3.1 + */ + void DoUnlinkNode(); + + /** + * Inserts the node in a double-linked list of nodes before specified node. + * + * No checks are made; nor parent's, nor node's properties updated (except prev/next) + * + * @since S60 v3.1 + * @param aNode Target node + */ + void LinkBefore(TXmlEngNode aNode); + +protected: + /** Node pointer */ + void* iInternal; + +}; + +#include "xmlengnode.inl" + +#endif /* XMLENGINE_NODE_H_INCLUDED */