diff -r 000000000000 -r e35f40988205 xml/xmldomandxpath/inc/xmlenginedom/xmlengdocument.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/xmldomandxpath/inc/xmlenginedom/xmlengdocument.h Thu Dec 17 09:29:21 2009 +0200 @@ -0,0 +1,570 @@ +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// Document node functions +// + + + +/** + @file + @publishedAll + @released +*/ +#ifndef XMLENGDOCUMENT_H +#define XMLENGDOCUMENT_H + +#include + +#include +#include + +class RXmlEngDOMImplementation; + +/** +This class represents an XML document in the DOM tree. It stores all nodes +and associated information about the XML document. + +This class implements the interface. Another class, RXmlEngDOMImplementation, +provides the implementation. An instance of RXmlEngDOMImplementation must be +constructed and opened first and passed to RXmlEngDocument::OpenL(). +*/ +class RXmlEngDocument : public TXmlEngNode +{ +public: + /** + Default constructor. An instance of RXmlEngDocument must be "opened" with + one of OpenL() overloads before methods are invoked on the object. + */ + IMPORT_C RXmlEngDocument(); + + /** + Opens the document. + @param aDOMImpl An opened DOM implementation object + @leave - One of the system-wide error codes + */ + IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl); + + /** + Opens the document, initializing it with the internal state pointer from + another RXmlEngDocument. This document becomes an alias for the document + whose state is represented by aInternal and a change in either document + will be reflected in the other. Close() need only be called once, however, + it is not an error to call Close() on each RXmlEngDocument. + + @param aDOMImpl An opened DOM implementation object + @param aInternal The internal document state to initialize this object with + @leave - One of the system-wide error codes + */ + IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal); + + /** + Opens the document and adds aRoot as the root of the DOM tree. If aRoot is + currently part of another document, it will be unlinked. Ownership is + transferred to this document. + + @param aDOMImpl An opened DOM implementation object + @param aRoot The element that will be the root of the DOM tree + @leave - One of the system-wide error codes + */ + IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot); + + /** + Closes document: All owned nodes, child nodes, and namespaces are freed. All + data containers on the data container list are freed. + */ + IMPORT_C void Close(); + + /** + Serializes document tree into a file. For nodes containing binary data in + the form of BinaryDataContainer, FileContainer or ChunkContainer, the + client can implement custom serialization by implementing the + MXmlEngDataSerializer interface and saving a pointer to the customer + serializer in the iDataSerializer member of the aSaveOptions parameter. If + no custom serialization is specified, the binary data container nodes are + serialized like text nodes. + + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not + need to be owned by this document. + + @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 bytes written + @leave KXmlEngErrWrongEncoding Encoding not understood + @leave KXmlEngErrWrongUseOfAPI Document is NULL + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size + @leave - One of the system-wide error codes + */ + 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, the + client can implement custom serialization by implementing the + MXmlEngDataSerializer interface and saving a pointer to the customer + serializer in the iDataSerializer member of the aSaveOptions parameter. If + no custom serialization is specified, the binary data container nodes are + serialized like text nodes. + + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not + need to be owned by this document. + + @param aRFs An open 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 bytes written + @leave KXmlEngErrWrongEncoding Encoding not understood + @leave KXmlEngErrWrongUseOfAPI Document is NULL + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size + @leave - One of the system-wide error codes + */ + IMPORT_C TInt SaveL( RFs& aRFs, + const TDesC& aFileName, + TXmlEngNode aRoot = TXmlEngNode(), + const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const; + + /** + Serializes 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, the client can + implement custom serialization by implementing the MXmlEngDataSerializer + interface and saving a pointer to the customer serializer in the + iDataSerializer member of the aSaveOptions parameter. If no custom + serialization is specified, the binary data container nodes are serialized + like text nodes. + + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not + need to be owned by this document. + + @param aStream An output stream to write the serialized DOM tree + @param aRoot Root node to be serialized + @param aSaveOptions Options that control how serialization is performed + @return Number of bytes written + @leave KXmlEngErrWrongEncoding Encoding not understood + @leave KXmlEngErrWrongUseOfAPI Document is NULL + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size + @leave - One of the system-wide error codes + */ + IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream, + TXmlEngNode aRoot = TXmlEngNode(), + const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const; + + /** + Saves document tree into memory buffer. + + Any existing contents in aBuffer will be deleted. The memory required for + aBuffer will be allocated by this method. The method caller must Close() + aBuffer. + + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not + need to be owned by this document. + + @param aBuffer Resulting buffer + @param aRoot The root of the subtree to serialize + @param aSaveOptions Options that control how serialization is performed + @return Size of buffer + @leave KXmlEngErrWrongEncoding Encoding not understood + @leave KXmlEngErrWrongUseOfAPI Document is NULL + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size + @leave - One of the system-wide error codes + */ + IMPORT_C TInt SaveL(RBuf8& aBuffer, + TXmlEngNode aRoot = TXmlEngNode(), + const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const; + + /** + Creates a complete copy of the document and transfers ownership to the + caller. The caller is required to call Close() on the new document. The + new document is independant from this document and this document may be + changed or closed without affecting the new document. + + @return Complete copy of the document + @leave - One of the system-wide error codes + */ + IMPORT_C RXmlEngDocument CloneDocumentL() const; + + /** + Creates a new element from a specific namespace to be the root of the + document tree. Any existing document element of the document is destroyed. + + @param aName Element name + @param aNamespaceUri Element namespace URI + @param aPrefix Element namemespace prefix + @return The new root element + @leave KXmlEngErrWrongUseOfAPI No name has been specified + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName, + const TDesC8& aNamespaceUri = KNullDesC8, + const TDesC8& aPrefix = KNullDesC8); + + /** + Replaces (and destroys) the document element. + + Note: Use TXmlEngElement::ReconcileNamespacesL() on the new document + element if it or its descendants can contain references to namespace + declarations outside of the element. + + @param aNewDocElement New document element + @see TXmlEngElement::ReconcileNamespacesL() + */ + IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement); + + /** + Get document encoding. + @return Encoding of the source XML data or TPtrC8("") if none. + */ + IMPORT_C TPtrC8 XmlEncoding() const; + + /** + Get xml version + @return Version number reported by the XML declaration or TPtrC8("") if none. + */ + IMPORT_C TPtrC8 XmlVersion() const; + + /** + Retrieves base URI (if defined) of the document + @return Document URI or TPtrC8("") if none. + */ + IMPORT_C TPtrC8 DocumentUri() const; + + /** + Check if document is standalone + @return ETrue if standalone="true" was specified in the 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. + @param aVersion Version string + @leave - One of the system-wide error codes + */ + IMPORT_C void SetXmlVersionL(const TDesC8& aVersion); + + /** + Sets the location of the document. The document's URI is used as the + top-level base URI definition. + @param aUri Document URI + @leave - One of the system-wide error codes + */ + IMPORT_C void SetDocumentUriL(const TDesC8& aUri); + + /** + Sets "standalone" attribute of XML declaration for the document + @param aStandalone Is the document standalone + */ + IMPORT_C void SetStandalone(TBool aStandalone); + + /** + Get the DOM implementation. Ownership is not transferred. Any operation + on the returned object will affect this document directly, in particular, + a call to RXmlEngDOMImplementation::Close() will cause further operations + on this document to fail. + + @return Object that represents current DOM implementation + */ + IMPORT_C RXmlEngDOMImplementation Implementation() const; + + /** + Get the document element + @return The document element -- the top-most element in the document tree + */ + IMPORT_C TXmlEngElement DocumentElement() const; + + /** + Sets the "document" property on the node and all its descendants to be this + RXmlEngDocument node + @param aSource Node that should be added. + @return Adopted node + @leave KXmlEngErrWrongUseOfAPI The node has a parent node, the node is + already owned by this document, or the node is a document. + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource); + + /** + Creates a new attribute. + + aValue should represent the correct value of an attribute if it is put + as-is into an XML file (with all characters correctly escaped with entity + references when XML spec requires) + + The TXmlEngElement class provides a rich set of attribute creation methods, + which not only create attributes but also link them into elements. + + @see TXmlEngElement + + There is no way to create attributes with namespaces (despite the DOM spec); + you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead + + The returned attribute is the only reference to the allocated memory until + you have attached the attribute to some element node. + + @param aName Name of the atribute; no prefix allowed + @param aValue Value of the attribute (optional) + @return The newly created attribute + @leave KXmlEngErrWrongUseOfAPI No name specified + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName, + const TDesC8& aValue = KNullDesC8); + + /** + Creates a new text node and copies the content string into it. + @param aCharacters Text node content + @return The created node + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8); + + /** + Creates a new binary container and copies the specified cid and data into + it. A pointer to the container is stored in the document's data container + list that can be fetched using GetDataContainerList(). + + @see GetDataContainerList( RArray& aList ) + @param aCid Content identifier + @param aData Binary octets + @return The new binary container + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid, + const TDesC8& aData ); + + /** + Creates a new chunk container and copies the specified cid into it. A + reference to a memory chunk is stored in the container. The memory chunk + must stay in scope for the lifetime of the container. A pointer to the + container is stored in the document's data container list that can be + fetched using GetDataContainerList(). + + @see GetDataContainerList( RArray& aList ) + @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 The new chunk container + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid, + const RChunk& aChunk, + const TInt aChunkOffset, + const TInt aDataSize ); + + /** + Creates a new file container and copies the specified cid into it. A + reference to a file is stored in the container. aFile must stay in scope + of the lifetime of the container. A pointer to the container is stored in + the document's data container list that can be fetched using + GetDataContainerList(). + + @see GetDataContainerList( RArray& aList ) + @param aCid Content identifier + @param aFile The file to reference + @return The new file container + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid, + const RFile& aFile ); + + /** + Creates a new element node that belongs to the specific namespace. A + namespace declaration node is created on the element. + + If the provided namespace uri is NULL, the element will be created without + namespace. + + @param aNamespaceUri Namespace of new element + @param aPrefix Prefix to use for the namespace binding and the QName of the element + @param aLocalName Local name of the element + @return The created element + @leave KXmlEngErrWrongUseOfAPI No name specified + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName, + const TDesC8& aNamespaceUri = KNullDesC8, + const TDesC8& aPrefix = KNullDesC8); + + /** + Creates a new comment node and copies the specified string into it. + @param aText New comment + @return The created node + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8); + + /** + Creates a new CDATA section node and copies the specified string into it. + @param aContents CDATASection content + @return The created node + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8); + + /** + Creates a new entity reference node and copies the specified string into + it. + + Note: < , > , ' , " and other predefined entity references + should not be created with this method. These entity references are rather + "character references" and are encoded/decoded automatically. + + @param aEntityRef is a string in one of these forms: + - name + - &name + - &name; + where name is the name of the entity + @return The new entity reference + @leave KXmlEngErrWrongUseOfAPI No entity specified + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef); + + /** + Creates a new empty Document Fragment node. The document fragment is owned by + this document. + @return The created document fragment + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngDocumentFragment CreateDocumentFragmentL(); + + /** + Creates a new processing instruction node and copies "target" and "data" + into it. + + @param aTarget Target + @param aData Data + @return The created processing instruction + @leave KXmlEngErrWrongUseOfAPI No target specified + @leave - One of the system-wide error codes + */ + IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget, + const TDesC8& aData = KNullDesC8); + + /** + Sets the specified attribute as a xml:id attribute, starting at + aStartElement and recursing through the subtree. To set the specified + attribute as a xml:id attribute for the entire DOM tree, see + RegisterXmlId(const TDesC8&,const TDesC8&). + + @param aStartElement Root of the subtree to recurse + @param aLocalName Name of the attribute + @param aNamespaceUri Namespace of the new element (default empty) + @leave KXmlEngErrWrongUseOfAPI The starting element is NULL, the attribute + name is not specified, the starting element is the document, or the + starting element does not belong to a document. + @leave KErrAlreadyExists The attribute is already set to be xml:id + @leave - One of the system-wide error codes + */ + IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement, + const TDesC8& aLocalName, + const TDesC8& aNamespaceUri = KNullDesC8); + + /** + Sets the specified attribute as a xml:id attribute, recursing through the + entire DOM tree. In order to specify a subtree only, see + RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8). + + @param aLocalName Name of attribute + @param aNamespaceUri Namespace of new element (default empty) + @leave KXmlEngErrWrongUseOfAPI The document is NULL + @leave KErrAlreadyExists The attribute is already set to be xml:id + @leave - One of the system-wide error codes + */ + IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName, + const TDesC8& aNamespaceUri = KNullDesC8); + + /** + Looks for an element with the specified xml:id attribute + @param aValue Name of attribute + @return The found element or a NULL element if not found + @leave - One of the system-wide error codes + */ + 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 a data container when the data + container (or one of its predecessors) is removed from the document or + becomes part of another document. Unlinking a data container (or one of its + predecessors) doesn't remove ownership of the data container from this + document so the list might contain containers that are not linked to this + document anymore. + + @param aList Array of data containers + @return KErrNone if successful or one of the system wide error codes otherwise + */ + IMPORT_C TInt GetDataContainerList( RArray& aList ); + +protected: + friend class RXmlEngDOMParser; + friend class TXmlEngNode; + friend class TXmlEngAttr; + friend class TXmlEngElement; + friend class RXmlEngDOMImplementation; + +protected: + /** + Constructor + @param aInternal Document pointer + */ + inline RXmlEngDocument(void* aInternal); + + /** + DISABLED for document; CloneDocumentL() must be used + */ + inline TXmlEngNode CopyL() const; + + /** + DISABLED for document; Close() must be used + */ + inline void Remove(); + + /** + DISABLED for document; Close() must be used + */ + inline void ReplaceWith(TXmlEngNode aNode); + inline void ReplaceWithL(TXmlEngNode aNode); + + /** + DISABLED for document; Close() must be used + */ + inline TXmlEngNode SubstituteForL(TXmlEngNode aNode); + +private: + TInt SaveNodeL( TXmlEngNode aNode, + RBuf8& aBuffer, + MXmlEngOutputStream* aOutputStream = NULL, + TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const; + + void InitOwnedNodeListL(); + void TakeOwnership(TXmlEngNode aNode); + void RemoveOwnership(TXmlEngNode aNode); + +protected: + /** Pointer to DOM implementation object */ + RXmlEngDOMImplementation* iImpl; + +};// class RXmlEngDocument + + + +#include + +#endif /* XMLENGDOCUMENT_H */