diff -r 2fe1408b6811 -r e1b950c65cb4 epoc32/include/xmlengdocument.h --- a/epoc32/include/xmlengdocument.h Tue Mar 16 16:12:26 2010 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,573 +0,0 @@ -/* -* 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 */