diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/xml/dom/xmlengdocument.h --- a/epoc32/include/xml/dom/xmlengdocument.h Wed Mar 31 12:27:01 2010 +0100 +++ b/epoc32/include/xml/dom/xmlengdocument.h Wed Mar 31 12:33:34 2010 +0100 @@ -1,478 +1,516 @@ -/* -* 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 -* -*/ - - +// 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 +// - -#ifndef XMLENGINE_DOCUMENT_H_INCLUDED -#define XMLENGINE_DOCUMENT_H_INCLUDED +/** + @file + @publishedAll + @released +*/ +#ifndef XMLENGDOCUMENT_H +#define XMLENGDOCUMENT_H #include -#include "xmlengnode.h" -#include "xmlengserializationoptions.h" +#include +#include -// 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 - */ +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. - * - * Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads. - * - * @since S60 v3.1 - */ + /** + 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. - * - * @since S60 v3.2 - * @param aDOMImpl DOM implementation object - * @return KErrNone if succeed. - */ + 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. - * - * @since S60 v3.2 - * @param aDOMImpl DOM implementation object - * @param aInternal Document pointer - * @return KErrNone if succeed. - */ + 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. - * - * @since S60 v3.2 - * @param aDOMImpl DOM implementation object - * @param aRoot element taht will be root of the DOM tree - * @return KErrNone if succeed. - */ + /** + 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 - * - * @since S60 v3.1 - */ + /** + 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, 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. - */ + /** + 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, 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. - */ + 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 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 - */ + /** + 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 - * - * @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 - */ + 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 complete copy of the document - * - * @since S60 v3.1 - * @return Complete copy of the document tree - */ + /** + 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 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 - */ + /** + 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) 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() - */ + /** + 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 - * - * @since S60 v3.1 - * @return Encoding of the source XML data. - */ + Get document encoding. + @return Encoding of the source XML data or TPtrC8("") if none. + */ IMPORT_C TPtrC8 XmlEncoding() const; /** - * Get xml version - * - * @since S60 v3.1 - * @return Version number of XML taken from XML declaration - */ + 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 or NULL - * - * @since S60 v3.1 - * @return Document URI - */ + 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 - * - * @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); + 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 location of the document. - * Document's URI is used as top-level base URI definition. - * - * @since S60 v3.1 - * @param aUri New document URI - */ + 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 a document - * - * @since S60 v3.1 - * @param aStandalone Is document standalone - */ + /** + Sets "standalone" attribute of XML declaration for the document + @param aStandalone Is the 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. - */ + /** + 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 document element - * - * @since S60 v3.1 - * @return A document element - the top-most element in the document tree - */ + Get the document element + @return The 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 - */ + /** + 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 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 - */ + 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 new text node and copies the content string into it. - * - * @since S60 v3.1 - * @param aCharacters Text node content - * @return Created node - */ + 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 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 - */ + /** + 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 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 - */ + /** + 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 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 - */ + /** + 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 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. - */ + /** + 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 new comment node and copies the content string into it. - * - * @since S60 v3.1 - * @param aText New comment - * @return Created node - */ + 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 new CDATA section node and copies the content into it. - * - * @since S60 v3.1 - * @param aContents CDATASection content - * @return Created node - */ + 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 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. - */ + 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 new processing instruction node and set its "target" and "data" values - * - * @since S60 v3.1 - * @param aTarget Target - * @param aData Data - * @return Created node - */ + 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); - /** - * 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) - */ + /** + 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); - /** - * 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) - */ + /** + 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 element with specified value of xml:id - * - * @since S60 v3.2 - * @param aValue Name of attribute - * @return found element or null-element. - */ + 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 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 ); + 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; @@ -483,81 +521,40 @@ protected: /** - * Constructor - * - * @since S60 v3.1 - * @param aInternal Document pointer - */ + Constructor + @param aInternal Document pointer + */ inline RXmlEngDocument(void* aInternal); /** - * DISABLED for document; CloneDocumentL() must be used - * - * @since S60 v3.1 - */ + DISABLED for document; CloneDocumentL() must be used + */ inline TXmlEngNode CopyL() const; /** - * DISABLED for document; Destroy() must be used - * - * @since S60 v3.1 - */ + DISABLED for document; Close() must be used + */ inline void Remove(); /** - * DISABLED for document; Destroy() must be used - * - * @since S60 v3.1 - */ + DISABLED for document; Close() must be used + */ inline void ReplaceWith(TXmlEngNode aNode); -private: + inline void ReplaceWithL(TXmlEngNode aNode); + /** - * 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. + 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; - /** - * "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: @@ -568,6 +565,6 @@ -#include "xmlengdocument.inl" +#include -#endif /* XMLENGINE_DOCUMENT_H_INCLUDED */ +#endif /* XMLENGDOCUMENT_H */