/*

 * 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 &lt; , &gt; , &apos; , &quot; 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 */