--- a/epoc32/include/xmlengdocument.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/xmlengdocument.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,573 @@
-xmlengdocument.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: Document node functions
+*
+*/
+
+
+
+
+
+
+#ifndef XMLENGINE_DOCUMENT_H_INCLUDED
+#define XMLENGINE_DOCUMENT_H_INCLUDED
+
+#include <f32file.h>
+
+#include "xmlengnode.h"
+#include "xmlengserializationoptions.h"
+
+// FORWARD DECLARATION
+class RXmlEngDOMImplementation;
+
+/**
+ * Instance of RXmlEngDocument class represents an XML document in the DOM tree.
+ *
+ * Is a storage all nodes and information about XML data.
+ *
+ * @lib XmlEngineDOM.lib
+ * @since S60 v3.1
+ */
+class RXmlEngDocument : public TXmlEngNode
+{
+public:
+ /**
+ * Default constructor.
+ *
+ * Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads.
+ *
+ * @since S60 v3.1
+ */
+ IMPORT_C RXmlEngDocument();
+
+ /**
+ * Opens the document.
+ *
+ * @since S60 v3.2
+ * @param aDOMImpl DOM implementation object
+ * @return KErrNone if succeed.
+ */
+ IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl);
+
+ /**
+ * Opens the document.
+ *
+ * @since S60 v3.2
+ * @param aDOMImpl DOM implementation object
+ * @param aInternal Document pointer
+ * @return KErrNone if succeed.
+ */
+ IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal);
+
+ /**
+ * Opens the document.
+ *
+ * @since S60 v3.2
+ * @param aDOMImpl DOM implementation object
+ * @param aRoot element taht will be root of the DOM tree
+ * @return KErrNone if succeed.
+ */
+ IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot);
+
+ /**
+ * Closes document
+ *
+ * @since S60 v3.1
+ */
+ IMPORT_C void Close();
+
+ /**
+ * Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
+ * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
+ * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
+ * custom serialization is specified, the binary data container nodes are serialized like text nodes.
+ *
+ * @since S60 v3.2
+ * @param aFileName A file name (with path)
+ * @param aRoot Root node to be serialized
+ * @param aSaveOptions Options that control how serialization is performed
+ * @return Number of byte written
+ * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
+ */
+ IMPORT_C TInt SaveL( const TDesC& aFileName,
+ TXmlEngNode aRoot = TXmlEngNode(),
+ const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
+
+ /**
+ * Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
+ * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
+ * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
+ * custom serialization is specified, the binary data container nodes are serialized like text nodes.
+ *
+ * @since S60 v3.2
+ * @param aRFs File Server session
+ * @param aFileName A file name (with path)
+ * @param aRoot Root node to be serialized
+ * @param aSaveOptions Options that control how serialization is performed
+ * @return Number of byte written
+ * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
+ */
+ IMPORT_C TInt SaveL( RFs& aRFs,
+ const TDesC& aFileName,
+ TXmlEngNode aRoot = TXmlEngNode(),
+ const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
+
+ /**
+ * Serializes a document tree into provided output stream, which supports progressive writing of data.
+ * For nodes containing binary data in the form of BinaryDataContainer, FileContainer or ChunkContainer,
+ * client can implement custom serialization by implementing the interface MXmlEngDataSerializer and specify
+ * the pointer in iDataSerializer member of aSaveOptions parameter. If no custom serialization is specified,
+ * the binary data container nodes are serialized like text nodes.
+ *
+ * @since S60 v3.1
+ * @param aStream An output stream to write serialized DOM tree
+ * @param aRoot Root node to be serialized
+ * @param aSaveOptions Options that control how serialization is performed
+ * @return Number of byte written
+ * @leave KXmlEngErrWrongUseOfAPI or one of general codes (e.g.KErrNoMemory)
+ * @see MXmlEngOutputStream
+ */
+ IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream,
+ TXmlEngNode aRoot = TXmlEngNode(),
+ const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
+
+ /**
+ * Saves document tree into memory buffer
+ *
+ * @since S60 v3.1
+ * @param aBuffer Resulting buffer
+ * @param aRoot A "root" of the subtree to serialize
+ * @param aSaveOptions Various options to be effective during serialization
+ * @return Number of bytes in updated buffer
+ * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding.
+ *
+ * @note Result returned via aBuffer argument owns the memory buffer; it is up to
+ * method caller to free it like in this sample:
+ *
+ * @see TXmlEngSerializationOptions
+ */
+ IMPORT_C TInt SaveL(RBuf8& aBuffer,
+ TXmlEngNode aRoot = TXmlEngNode(),
+ const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const;
+
+ /**
+ * Creates complete copy of the document
+ *
+ * @since S60 v3.1
+ * @return Complete copy of the document tree
+ */
+ IMPORT_C RXmlEngDocument CloneDocumentL() const;
+
+ /**
+ * Creates new element from specific namespace to be a root of the document tree.
+ * Any existing document element of the document is destroyed
+ *
+ * @since S60 v3.1
+ * @param aName Element name
+ * @param aNamespaceUri Element namespace URI
+ * @param aPrefix Element namemespace prefix
+ * @return A new root element
+ */
+ IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName,
+ const TDesC8& aNamespaceUri = KNullDesC8,
+ const TDesC8& aPrefix = KNullDesC8);
+
+ /**
+ * Replaces (and destroys) document element with another one
+ * New document element is added as the last child to the document node
+ *
+ * @since S60 v3.1
+ * @param aNewDocElement New document tree
+ *
+ * @note Use TXmlEngElement::ReconcileNamespacesL() on the new document element
+ * if it or its descendants can contain references to namespace declarations
+ * out of the element
+ * @see TXmlEngElement::ReconcileNamespacesL()
+ */
+ IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement);
+
+ /**
+ * Get document encoding
+ *
+ * @since S60 v3.1
+ * @return Encoding of the source XML data.
+ */
+ IMPORT_C TPtrC8 XmlEncoding() const;
+
+ /**
+ * Get xml version
+ *
+ * @since S60 v3.1
+ * @return Version number of XML taken from XML declaration
+ */
+ IMPORT_C TPtrC8 XmlVersion() const;
+
+ /**
+ * Retrieves base URI (if defined) of the document or NULL
+ *
+ * @since S60 v3.1
+ * @return Document URI
+ */
+ IMPORT_C TPtrC8 DocumentUri() const;
+
+ /**
+ * Check if document is standalone
+ *
+ * @since S60 v3.1
+ * @return Whether standalone="true" was specified in XML declaration in the source XML file.
+ */
+ IMPORT_C TBool IsStandalone() const;
+
+ /**
+ * Sets XML version number to be shown in XML declaration when document is serialized.
+ *
+ * @since S60 v3.1
+ * @param aVersion New version
+ */
+ IMPORT_C void SetXmlVersionL(const TDesC8& aVersion);
+
+ /**
+ * Sets location of the document.
+ * Document's URI is used as top-level base URI definition.
+ *
+ * @since S60 v3.1
+ * @param aUri New document URI
+ */
+ IMPORT_C void SetDocumentUriL(const TDesC8& aUri);
+
+ /**
+ * Sets 'standalone' attribute of XML declaration for a document
+ *
+ * @since S60 v3.1
+ * @param aStandalone Is document standalone
+ */
+ IMPORT_C void SetStandalone(TBool aStandalone);
+
+ /**
+ * Get dom implementation.
+ *
+ * @since S60 v3.1
+ * @return Object that represents current DOM implementation
+ *
+ * @note There is no practical use of implementation object in this version
+ * of API other than for creating new RXmlEngDocument instances, but
+ * it will change in the future, when an implementation object
+ * is used for changing configuration settings at run-time.
+ */
+ IMPORT_C RXmlEngDOMImplementation Implementation() const;
+
+ /**
+ * Get document element
+ *
+ * @since S60 v3.1
+ * @return A document element - the top-most element in the document tree
+ */
+ IMPORT_C TXmlEngElement DocumentElement() const;
+
+ /**
+ * Sets "document" property on the node and all its descendants to be this RXmlEngDocument node
+ *
+ * @since S60 v3.1
+ * @param aSource Node that should be added.
+ * @return Adopted node
+ */
+ IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource);
+
+ /**
+ * Creates new attribute,
+ *
+ * @since S60 v3.1
+ * @param aName Name of the atribute; no prefix allowed
+ * @param aValue Value of the attribute (optional)
+ * @return Handler to the newly created attribute
+ *
+ * @note
+ * aValue should represent a correct value of an attribute if it is put as is into XML file
+ * (with all characters correctly escaped with entity references when XML spec requires)
+ *
+ * TXmlEngElement class provides a rich set of attribute creation methods, which not
+ * just create attribute but also link it into element.
+ *
+ * There is no way to create attributes with namespace (despite the DOM spec);
+ * you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
+ *
+ * Returned handler is the only reference to the allocated memory
+ * until you have attached the attribute to some element node
+ */
+ IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName,
+ const TDesC8& aValue = KNullDesC8);
+
+ /**
+ * Creates new text node and copies the content string into it.
+ *
+ * @since S60 v3.1
+ * @param aCharacters Text node content
+ * @return Created node
+ */
+ IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8);
+
+ /**
+ * Creates new binary container and copies the content string into it.
+ * Pointer to the container is stored in the document's
+ * data container list that can be fetched using GetDataContainerList().
+ * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
+ *
+ * @since S60 v3.2
+ * @param aCid Content identifier
+ * @param aData Binary octets
+ * @return Created node
+ */
+ IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid,
+ const TDesC8& aData );
+
+ /**
+ * Creates new chunk container that stores reference to
+ * memory chunk.
+ * Pointer to the container is stored in the document's
+ * data container list that can be fetched using GetDataContainerList().
+ * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
+ *
+ * @since S60 v3.2
+ * @param aCid Content identifier
+ * @param aChunk RChunk reference
+ * @param aChunkOffset Offset to the binary data in aChunk
+ * @param aDataSize Size of binary data in aChunk
+ * @return Created node
+ */
+ IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid,
+ const RChunk& aChunk,
+ const TInt aChunkOffset,
+ const TInt aDataSize );
+
+ /**
+ * Creates new file container that stores reference to
+ * file in file system.
+ * Pointer to the container is stored in the document's
+ * data container list that can be fetched using GetDataContainerList().
+ * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
+ *
+ * @since S60 v3.2
+ * @param aCid Content identifier
+ * @param aFile RFile reference
+ * @return Created node
+ */
+ IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid,
+ const RFile& aFile );
+
+ /**
+ * Creates new element node that belongs to specific namespace.
+ * A namespace declaration node is created on the element.
+ *
+ * @since S60 v3.1
+ * @param aNamespaceUri Namespace of new element
+ * @param aPrefix Prefix to use for namespace binding and QName of the element
+ * @param aLocalName Local name of the element
+ * @return Created node
+ * @note If null namespace uri is provided element will be created without namespace.
+ */
+ IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8,
+ const TDesC8& aPrefix = KNullDesC8);
+
+ /**
+ * Creates new comment node and copies the content string into it.
+ *
+ * @since S60 v3.1
+ * @param aText New comment
+ * @return Created node
+ */
+ IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8);
+
+ /**
+ * Creates new CDATA section node and copies the content into it.
+ *
+ * @since S60 v3.1
+ * @param aContents CDATASection content
+ * @return Created node
+ */
+ IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8);
+
+ /**
+ * Creates new entity reference node for aEntityName entity
+ *
+ * @since S60 v3.1
+ * @param aEntityRef is a string in one of the forms:
+ * - <i>name</i>
+ * - <b>&</b><i>name</i>
+ * - <b>&</b><i>name</i><b>;</b>
+ * where <i>name</i> is the name of the entity
+ * @return Created node
+ *
+ * @note < , > , ' , " and other <b>predefined</b> entity references
+ * should not be created with this method. These entity refs are rather
+ * "character references" and encoded/decoded automatically.
+ */
+ IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef);
+
+ /**
+ * Creates new processing instruction node and set its "target" and "data" values
+ *
+ * @since S60 v3.1
+ * @param aTarget Target
+ * @param aData Data
+ * @return Created node
+ */
+ IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget,
+ const TDesC8& aData = KNullDesC8);
+
+ /**
+ * Registers specified attribute as xml:id.
+ * First parametr allows user, to specify sub-tree, not to search whole document.
+ * To search whole tree see @see RegisterXmlId(const TDesC8,const TDesC8)
+ *
+ * @since S60 v3.2
+ * @param aStartElement Root of tree to search (should be part of the document)
+ * @param aLocalName Name of attribute
+ * @param aNamespaceUri Namespace of new element (default empty)
+ */
+ IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement,
+ const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8);
+
+ /**
+ * Registers specified attribute as xml:id.
+ * Not to search whole tree see @see RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8)
+ *
+ * @since S60 v3.2
+ * @param aLocalName Name of attribute
+ * @param aNamespaceUri Namespace of new element (default empty)
+ */
+ IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName,
+ const TDesC8& aNamespaceUri = KNullDesC8);
+
+ /**
+ * Looks for element with specified value of xml:id
+ *
+ * @since S60 v3.2
+ * @param aValue Name of attribute
+ * @return found element or null-element.
+ */
+ IMPORT_C TXmlEngElement FindElementByXmlIdL(const TDesC8& aValue ) const;
+
+ /**
+ * Retrieves an array of data containers owned by this document.
+ *
+ * @note The document ceases to be the owner of data container when data container
+ * (or one of its predecessors) is removed from the document or data container
+ * (or one of its predecessors) becomes a part of another document.
+ * Unlinking data container (or one of its predecessors) doesn't remove
+ * ownership of data container from the this document so the list might
+ * contain containers that are not linked to this document anymore.
+ * @since S60 v3.2
+ * @param aList Array of data containers
+ */
+ IMPORT_C void GetDataContainerList( RArray<TXmlEngDataContainer>& aList );
+
+protected:
+ friend class RXmlEngDOMParser;
+ friend class TXmlEngNode;
+ friend class TXmlEngAttr;
+ friend class TXmlEngElement;
+ friend class RXmlEngDOMImplementation;
+
+protected:
+ /**
+ * Constructor
+ *
+ * @since S60 v3.1
+ * @param aInternal Document pointer
+ */
+ inline RXmlEngDocument(void* aInternal);
+
+ /**
+ * DISABLED for document; CloneDocumentL() must be used
+ *
+ * @since S60 v3.1
+ */
+ inline TXmlEngNode CopyL() const;
+
+ /**
+ * DISABLED for document; Destroy() must be used
+ *
+ * @since S60 v3.1
+ */
+ inline void Remove();
+
+ /**
+ * DISABLED for document; Destroy() must be used
+ *
+ * @since S60 v3.1
+ */
+ inline void ReplaceWith(TXmlEngNode aNode);
+private:
+ /**
+ * Main implementation of SaveL() functions that puts together all common code
+ * and serializes to buffer or output stream.
+ *
+ * @since S60 v3.2
+ * @param aNode Root node to be serialized
+ * @param aBuffer buffer with serialized data.
+ * @param aOutputStream stream that should be used during serialization
+ * @param aSaveOptions Options that control how serialization is performed
+ * @return Number of bytes written
+ * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
+ */
+ TInt SaveNodeL( TXmlEngNode aNode,
+ RBuf8& aBuffer,
+ MXmlEngOutputStream* aOutputStream = NULL,
+ TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const;
+
+ /**
+ * "Secondary" constructor that should be called on every newly created document node.
+ * Initializes container for nodes owned by the document.
+ *
+ * The need for such secondary constructor is in the fact that underlying libxml2
+ * library knows nothing about ownership of unlinked nodes -- this feature is
+ * implemented in C++ DOM wrapper.
+ *
+ * @since S60 v3.1
+ */
+ void InitOwnedNodeListL();
+
+ /**
+ * Adds aNode to the list of owned nodes - the nodes that are not linked yet into a
+ * document tree, but still destroyed with the document that owns them.
+ *
+ * @since S60 v3.1
+ * @param aNode Node that should be added to document
+ *
+ * In case of OOM (during growing node list container) the argument node is freed with
+ * xmlFreeNode()
+ */
+ void TakeOwnership(TXmlEngNode aNode);
+
+ /**
+ * Remove aNode from the list of owned nodes.
+ *
+ * @since S60 v3.1
+ * @param aNode Node that should be removed from document
+ */
+ void RemoveOwnership(TXmlEngNode aNode);
+
+protected:
+ /** Pointer to DOM implementation object */
+ RXmlEngDOMImplementation* iImpl;
+
+};// class RXmlEngDocument
+
+
+
+#include "xmlengdocument.inl"
+
+#endif /* XMLENGINE_DOCUMENT_H_INCLUDED */