diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/xmlengdocument.h --- 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 + +#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& 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& 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& 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: + * - name + * - &name + * - &name; + * where name is the name of the entity + * @return Created node + * + * @note < , > , ' , " and other predefined 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& 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 */