--- 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 <f32file.h>
-#include "xmlengnode.h"
-#include "xmlengserializationoptions.h"
+#include <xml/dom/xmlengnode.h>
+#include <xml/dom/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
- */
+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<TXmlEngDataContainer>& 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<TXmlEngDataContainer>& 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<TXmlEngDataContainer>& aList )
- *
- * @since S60 v3.2
- * @param aCid Content identifier
- * @param aChunk RChunk reference
- * @param aChunkOffset Offset to the binary data in aChunk
- * @param aDataSize Size of binary data in aChunk
- * @return Created node
- */
+ /**
+ 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<TXmlEngDataContainer>& 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<TXmlEngDataContainer>& 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<TXmlEngDataContainer>& 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:
- * - <i>name</i>
- * - <b>&</b><i>name</i>
- * - <b>&</b><i>name</i><b>;</b>
- * where <i>name</i> is the name of the entity
- * @return Created node
- *
- * @note < , > , ' , " and other <b>predefined</b> entity references
- * should not be created with this method. These entity refs are rather
- * "character references" and encoded/decoded automatically.
- */
+ 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<TXmlEngDataContainer>& 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<TXmlEngDataContainer>& 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 <xml/dom/xmlengdocument.inl>
-#endif /* XMLENGINE_DOCUMENT_H_INCLUDED */
+#endif /* XMLENGDOCUMENT_H */