epoc32/include/xml/dom/xmlengdocument.h
branchSymbian3
changeset 4 837f303aceeb
parent 3 e1b950c65cb4
equal deleted inserted replaced
3:e1b950c65cb4 4:837f303aceeb
     1 /*
     1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 * Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). 
     2 // All rights reserved.
     3 * All rights reserved.
     3 // This component and the accompanying materials are made available
     4 * This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 * 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
     5 // which accompanies this distribution, and is available
     6 * which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     7 //
     8 *
     8 // Initial Contributors:
     9 * Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 * Nokia Corporation - initial contribution.
    10 //
    11 *
    11 // Contributors:
    12 * Contributors:
    12 //
    13 *
    13 // Description:
    14 * Description:       Document node functions
    14 // Document node functions
    15 *
    15 //
       
    16 
       
    17 
       
    18 
       
    19 /**
       
    20  @file
       
    21  @publishedAll
       
    22  @released
    16 */
    23 */
    17 
    24 #ifndef XMLENGDOCUMENT_H
    18 
    25 #define XMLENGDOCUMENT_H
    19 
       
    20 
       
    21 
       
    22 
       
    23 #ifndef XMLENGINE_DOCUMENT_H_INCLUDED
       
    24 #define XMLENGINE_DOCUMENT_H_INCLUDED
       
    25 
    26 
    26 #include <f32file.h> 
    27 #include <f32file.h> 
    27 
    28 
    28 #include "xmlengnode.h"
    29 #include <xml/dom/xmlengnode.h>
    29 #include "xmlengserializationoptions.h"
    30 #include <xml/dom/xmlengserializationoptions.h>
    30 
    31 
    31 // FORWARD DECLARATION
       
    32 class RXmlEngDOMImplementation;
    32 class RXmlEngDOMImplementation;
    33 
    33 
    34 /**
    34 /**
    35  * Instance of RXmlEngDocument class represents an XML document in the DOM tree.
    35 This class represents an XML document in the DOM tree.  It stores all nodes 
    36  * 
    36 and associated information about the XML document.  
    37  * Is a storage all nodes and information about XML data.
    37 
    38  * 
    38 This class implements the interface.  Another class, RXmlEngDOMImplementation,
    39  * @lib XmlEngineDOM.lib
    39 provides the implementation.  An instance of RXmlEngDOMImplementation must be
    40  * @since S60 v3.1
    40 constructed and opened first and passed to RXmlEngDocument::OpenL().
    41  */
    41 */
    42 class RXmlEngDocument : public TXmlEngNode
    42 class RXmlEngDocument : public TXmlEngNode
    43 {
    43 {
    44 public:    
    44 public:    
    45     /**
    45     /** 
    46      * Default constructor.
    46 	Default constructor.  An instance of RXmlEngDocument must be "opened" with
    47      *
    47 	one of OpenL() overloads before methods are invoked on the object.
    48      * Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads.
    48 	*/
    49      *
       
    50      * @since S60 v3.1
       
    51 	 */
       
    52     IMPORT_C RXmlEngDocument();
    49     IMPORT_C RXmlEngDocument();
    53     
    50     
    54     /** 
    51     /** 
    55      * Opens the document.
    52     Opens the document.
    56      *
    53 	@param aDOMImpl An opened DOM implementation object
    57 	 * @since S60 v3.2
    54 	@leave - One of the system-wide error codes
    58 	 * @param aDOMImpl DOM implementation object
    55     */
    59      * @return KErrNone if succeed.
       
    60      */
       
    61     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl);
    56     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl);
    62 	
    57 	
    63 	/** 
    58 	/** 
    64      * Opens the document.
    59 	Opens the document, initializing it with the internal state pointer from
    65      *
    60 	another RXmlEngDocument.  This document becomes an alias for the document
    66 	 * @since S60 v3.2
    61 	whose state is represented by aInternal and a change in either document
    67 	 * @param aDOMImpl DOM implementation object
    62 	will be reflected in the other.  Close() need only be called once, however,
    68  	 * @param aInternal Document pointer
    63 	it is not an error to call Close() on each RXmlEngDocument.
    69      * @return KErrNone if succeed.
    64 
    70      */
    65 	@param aDOMImpl An opened DOM implementation object
       
    66  	@param aInternal The internal document state to initialize this object with
       
    67 	@leave - One of the system-wide error codes
       
    68     */
    71     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal);
    69     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal);
    72     
    70     
       
    71 	/** 
       
    72 	Opens the document and adds aRoot as the root of the DOM tree.  If aRoot is
       
    73 	currently part of another document, it will be unlinked.  Ownership is
       
    74 	transferred to this document.
       
    75 
       
    76 	@param aDOMImpl An opened DOM implementation object
       
    77  	@param aRoot The element that will be the root of the DOM tree
       
    78 	@leave - One of the system-wide error codes
       
    79     */
       
    80     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot);
       
    81     
    73     /** 
    82     /** 
    74      * Opens the document.
    83 	Closes document:  All owned nodes, child nodes, and namespaces are freed.  All
    75      *
    84 	data containers on the data container list are freed.
    76 	 * @since S60 v3.2
    85 	*/
    77 	 * @param aDOMImpl DOM implementation object
       
    78  	 * @param aRoot element taht will be root of the DOM tree
       
    79      * @return KErrNone if succeed.
       
    80      */
       
    81     IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot);
       
    82     
       
    83     /**
       
    84      * Closes document
       
    85      *
       
    86      * @since S60 v3.1
       
    87 	 */
       
    88     IMPORT_C  void Close();
    86     IMPORT_C  void Close();
    89 
    87 
    90     /**
    88 	/**
    91      * Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
    89 	Serializes document tree into a file.  For nodes containing binary data in
    92      * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
    90 	the form of BinaryDataContainer, FileContainer or ChunkContainer, the
    93      * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
    91 	client can implement custom serialization by implementing the
    94      * custom serialization is specified, the binary data container nodes are serialized like text nodes.
    92 	MXmlEngDataSerializer interface and saving a pointer to the customer
    95      *
    93 	serializer in the iDataSerializer member of the aSaveOptions parameter. If
    96      * @since S60 v3.2
    94 	no custom serialization is specified, the binary data container nodes are
    97 	 * @param aFileName A file name (with path)
    95 	serialized like text nodes.
    98  	 * @param aRoot Root node to be serialized	
    96 
    99 	 * @param aSaveOptions Options that control how serialization is performed 
    97 	If no aRoot is provided, the entire DOM tree is serialized.  aRoot does not
   100      * @return Number of byte written
    98 	need to be owned by this document.
   101      * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
    99     
   102      */
   100 	@param aFileName A file name (with path)
       
   101  	@param aRoot Root node to be serialized	
       
   102 	@param aSaveOptions Options that control how serialization is performed 
       
   103     @return Number of bytes written
       
   104 	@leave KXmlEngErrWrongEncoding Encoding not understood
       
   105 	@leave KXmlEngErrWrongUseOfAPI Document is NULL
       
   106     @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
       
   107 	@leave - One of the system-wide error codes
       
   108 	*/
   103     IMPORT_C TInt SaveL( const TDesC& aFileName,
   109     IMPORT_C TInt SaveL( const TDesC& aFileName,
   104     					 TXmlEngNode aRoot = TXmlEngNode(),
   110     					 TXmlEngNode aRoot = TXmlEngNode(),
   105     					 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   111     					 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   106    
   112    
   107     /**
   113     /**
   108      * Serializes document tree into a file.  For nodes containing binary data in the form of BinaryDataContainer,
   114 	Serializes document tree into a file.  For nodes containing binary data in
   109      * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
   115 	the form of BinaryDataContainer, FileContainer or ChunkContainer, the
   110      * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
   116 	client can implement custom serialization by implementing the
   111      * custom serialization is specified, the binary data container nodes are serialized like text nodes.
   117 	MXmlEngDataSerializer interface and saving a pointer to the customer
   112      *
   118 	serializer in the iDataSerializer member of the aSaveOptions parameter. If
   113      * @since S60 v3.2
   119 	no custom serialization is specified, the binary data container nodes are
   114 	 * @param aRFs File Server session
   120 	serialized like text nodes.
   115 	 * @param aFileName A file name (with path)	 
   121     
   116  	 * @param aRoot Root node to be serialized	
   122 	If no aRoot is provided, the entire DOM tree is serialized.  aRoot does not
   117 	 * @param aSaveOptions Options that control how serialization is performed 
   123 	need to be owned by this document.
   118      * @return Number of byte written
   124     
   119      * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
   125 	@param aRFs An open file Server session
   120      */                        
   126 	@param aFileName A file name (with path)
       
   127  	@param aRoot Root node to be serialized	
       
   128 	@param aSaveOptions Options that control how serialization is performed 
       
   129     @return Number of bytes written
       
   130 	@leave KXmlEngErrWrongEncoding Encoding not understood
       
   131 	@leave KXmlEngErrWrongUseOfAPI Document is NULL
       
   132     @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
       
   133 	@leave - One of the system-wide error codes
       
   134     */                        
   121     IMPORT_C TInt SaveL( RFs& aRFs,
   135     IMPORT_C TInt SaveL( RFs& aRFs,
   122                          const TDesC& aFileName,
   136                          const TDesC& aFileName,
   123                          TXmlEngNode aRoot = TXmlEngNode(),
   137                          TXmlEngNode aRoot = TXmlEngNode(),
   124                          const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   138                          const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   125     
   139     
   126     /**
   140 	/**
   127      * Serializes a document tree into provided output stream, which supports progressive writing of data.
   141 	Serializes document tree into provided output stream, which supports
   128      * For nodes containing binary data in the form of BinaryDataContainer, FileContainer or ChunkContainer,
   142 	progressive writing of data.  For nodes containing binary data in the form
   129      * client can implement custom serialization by implementing the interface MXmlEngDataSerializer and specify
   143 	of BinaryDataContainer, FileContainer or ChunkContainer, the client can
   130      * the pointer in iDataSerializer member of aSaveOptions parameter. If no custom serialization is specified,
   144 	implement custom serialization by implementing the MXmlEngDataSerializer
   131      * the binary data container nodes are serialized like text nodes.
   145 	interface and saving a pointer to the customer serializer in the
   132      *
   146 	iDataSerializer member of the aSaveOptions parameter. If no custom
   133      * @since S60 v3.1
   147 	serialization is specified, the binary data container nodes are serialized
   134 	 * @param aStream  An output stream to write serialized DOM tree
   148 	like text nodes.
   135 	 * @param aRoot Root node to be serialized
   149 
   136 	 * @param aSaveOptions Options that control how serialization is performed	 	 
   150 	If no aRoot is provided, the entire DOM tree is serialized.  aRoot does not
   137      * @return Number of byte written
   151 	need to be owned by this document.
   138      * @leave KXmlEngErrWrongUseOfAPI or one of general codes (e.g.KErrNoMemory)
   152     
   139      * @see MXmlEngOutputStream
   153 	@param aStream  An output stream to write the serialized DOM tree
   140      */
   154  	@param aRoot Root node to be serialized	
       
   155 	@param aSaveOptions Options that control how serialization is performed 
       
   156     @return Number of bytes written
       
   157 	@leave KXmlEngErrWrongEncoding Encoding not understood
       
   158 	@leave KXmlEngErrWrongUseOfAPI Document is NULL
       
   159     @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
       
   160 	@leave - One of the system-wide error codes
       
   161     */
   141     IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream,
   162     IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream,
   142 						 TXmlEngNode aRoot = TXmlEngNode(),
   163 						 TXmlEngNode aRoot = TXmlEngNode(),
   143 						 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   164 						 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
   144 
   165 
   145     /**
   166     /**
   146      * Saves document tree into memory buffer
   167     Saves document tree into memory buffer.
   147      *
   168 
   148      * @since S60 v3.1
   169 	Any existing contents in aBuffer will be deleted.  The memory required for
   149 	 * @param aBuffer Resulting buffer
   170 	aBuffer will be allocated by this method.  The method caller must Close()
   150      * @param aRoot A "root" of the subtree to serialize
   171 	aBuffer.
   151      * @param aSaveOptions Various options to be effective during serialization
   172 
   152      * @return Number of bytes in updated buffer     
   173 	If no aRoot is provided, the entire DOM tree is serialized.  aRoot does not
   153      * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding.
   174 	need to be owned by this document.
   154      *
   175     
   155      * @note Result returned via aBuffer argument owns the memory buffer; it is up to 
   176 	@param aBuffer Resulting buffer
   156      *      method caller to free it like in this sample:
   177     @param aRoot The root of the subtree to serialize
   157      *
   178     @param aSaveOptions Options that control how serialization is performed
   158      * @see TXmlEngSerializationOptions
   179     @return Size of buffer 
   159      */
   180 	@leave KXmlEngErrWrongEncoding Encoding not understood
       
   181 	@leave KXmlEngErrWrongUseOfAPI Document is NULL
       
   182     @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
       
   183 	@leave - One of the system-wide error codes
       
   184     */
   160     IMPORT_C TInt SaveL(RBuf8& aBuffer, 
   185     IMPORT_C TInt SaveL(RBuf8& aBuffer, 
   161     					TXmlEngNode aRoot = TXmlEngNode(), 
   186     					TXmlEngNode aRoot = TXmlEngNode(), 
   162                         const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const;
   187                         const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const;
   163    
   188    
   164     /**
   189 	/**
   165      * Creates complete copy of the document
   190 	Creates a complete copy of the document and transfers ownership to the
   166      *
   191 	caller.  The caller is required to call Close() on the new document.  The
   167      * @since S60 v3.1
   192 	new document is independant from this document and this document may be
   168 	 * @return Complete copy of the document tree
   193 	changed or closed without affecting the new document.
   169      */
   194 
       
   195 	@return Complete copy of the document 
       
   196 	@leave - One of the system-wide error codes
       
   197     */
   170 	IMPORT_C RXmlEngDocument CloneDocumentL() const;
   198 	IMPORT_C RXmlEngDocument CloneDocumentL() const;
   171 
   199 
   172     /**
   200 	/**
   173      * Creates new element from specific namespace to be a root of the document tree.
   201 	Creates a new element from a specific namespace to be the root of the
   174      * Any existing document element of the document is destroyed
   202 	document tree.  Any existing document element of the document is destroyed.
   175      *
   203     
   176      * @since S60 v3.1
   204 	@param aName Element name
   177 	 * @param aName Element name
   205     @param aNamespaceUri Element namespace URI
   178      * @param aNamespaceUri Element namespace URI
   206     @param aPrefix Element namemespace prefix
   179      * @param aPrefix Element namemespace prefix
   207     @return The new root element
   180      * @return A new root element
   208 	@leave KXmlEngErrWrongUseOfAPI No name has been specified
   181      */
   209 	@leave - One of the system-wide error codes
       
   210     */
   182     IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName, 
   211     IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName, 
   183                                              const TDesC8& aNamespaceUri = KNullDesC8, 
   212                                              const TDesC8& aNamespaceUri = KNullDesC8, 
   184                                              const TDesC8& aPrefix = KNullDesC8);
   213                                              const TDesC8& aPrefix = KNullDesC8);
   185 
   214 
   186     /**
   215 	/**
   187      * Replaces (and destroys) document element with another one
   216 	Replaces (and destroys) the document element.  
   188      * New document element is added as the last child to the document node
   217 
   189      *
   218 	Note:  Use TXmlEngElement::ReconcileNamespacesL() on the new document
   190      * @since S60 v3.1
   219 	element if it or its descendants can contain references to namespace
   191 	 * @param aNewDocElement New document tree
   220 	declarations outside of the element.
   192      *
   221     
   193      * @note Use TXmlEngElement::ReconcileNamespacesL() on the new document element
   222 	@param aNewDocElement New document element
   194      *      if it or its descendants can contain references to namespace declarations
   223     @see TXmlEngElement::ReconcileNamespacesL()
   195      *      out of the element
   224     */
   196      * @see TXmlEngElement::ReconcileNamespacesL()
       
   197      */
       
   198     IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement);
   225     IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement);
   199 
   226 
   200     /**
   227     /**
   201      * Get document encoding
   228     Get document encoding.
   202      *
   229 	@return Encoding of the source XML data or TPtrC8("") if none.
   203      * @since S60 v3.1
   230     */
   204 	 * @return Encoding of the source XML data.
       
   205      */
       
   206     IMPORT_C TPtrC8 XmlEncoding() const;
   231     IMPORT_C TPtrC8 XmlEncoding() const;
   207 
   232 
   208     /**
   233     /**
   209      * Get xml version
   234     Get xml version
   210      *
   235 	@return Version number reported by the XML declaration or TPtrC8("") if none.
   211      * @since S60 v3.1
   236     */
   212 	 * @return Version number of XML taken from XML declaration
       
   213      */
       
   214     IMPORT_C TPtrC8 XmlVersion() const;
   237     IMPORT_C TPtrC8 XmlVersion() const;
   215   
   238   
   216     /**
   239     /**
   217      * Retrieves base URI (if defined) of the document or NULL
   240     Retrieves base URI (if defined) of the document
   218      *
   241 	@return Document URI or TPtrC8("") if none.
   219      * @since S60 v3.1
   242     */
   220 	 * @return Document URI
       
   221      */
       
   222     IMPORT_C TPtrC8 DocumentUri() const;
   243     IMPORT_C TPtrC8 DocumentUri() const;
   223 
   244 
   224     /**
   245     /**
   225      * Check if document is standalone
   246     Check if document is standalone
   226      *
   247 	@return ETrue if standalone="true" was specified in the XML declaration in
   227      * @since S60 v3.1
   248 	the source XML file.
   228 	 * @return Whether standalone="true" was specified in XML declaration in the source XML file.
   249     */
   229      */
   250 	IMPORT_C TBool IsStandalone() const;
   230     IMPORT_C TBool IsStandalone() const;
   251 
   231 
   252     /**
   232     /**
   253     Sets XML version number to be shown in XML declaration when document is serialized.
   233      * Sets XML version number to be shown in XML declaration when document is serialized.
   254 	@param aVersion Version string
   234      *
   255 	@leave - One of the system-wide error codes
   235      * @since S60 v3.1
   256     */
   236 	 * @param aVersion New version
       
   237      */
       
   238     IMPORT_C void  SetXmlVersionL(const TDesC8& aVersion);
   257     IMPORT_C void  SetXmlVersionL(const TDesC8& aVersion);
   239 
   258 
   240     /**
   259 	/**
   241      * Sets location of the document.
   260 	Sets the location of the document.  The document's URI is used as the
   242      * Document's URI is used as top-level base URI definition.
   261 	top-level base URI definition.
   243      *
   262 	@param aUri Document URI
   244      * @since S60 v3.1
   263 	@leave - One of the system-wide error codes
   245 	 * @param aUri New document URI
   264     */
   246      */
       
   247     IMPORT_C void  SetDocumentUriL(const TDesC8& aUri);
   265     IMPORT_C void  SetDocumentUriL(const TDesC8& aUri);
   248 
   266 
   249     /**
   267     /** 
   250      * Sets 'standalone' attribute of XML declaration for a document
   268 	Sets "standalone" attribute of XML declaration for the document
   251      *
   269 	@param aStandalone Is the document standalone
   252      * @since S60 v3.1
   270     */
   253 	 * @param aStandalone Is document standalone
       
   254      */
       
   255     IMPORT_C void  SetStandalone(TBool aStandalone);
   271     IMPORT_C void  SetStandalone(TBool aStandalone);
   256 
   272 
   257     /**
   273     /** 
   258      * Get dom implementation.
   274 	Get the DOM implementation.  Ownership is not transferred.  Any operation
   259      *
   275 	on the returned object will affect this document directly, in particular, 
   260      * @since S60 v3.1
   276 	a call to RXmlEngDOMImplementation::Close() will cause further operations
   261 	 * @return Object that represents current DOM implementation
   277 	on this document to fail.
   262      *
   278 
   263      * @note There is no practical use of implementation object in this version
   279 	@return Object that represents current DOM implementation
   264      *      of API other than for creating new RXmlEngDocument instances, but
   280     */
   265      *      it will change in the future, when an implementation object 
       
   266      *      is used for changing configuration settings at run-time.
       
   267      */
       
   268     IMPORT_C RXmlEngDOMImplementation Implementation() const;
   281     IMPORT_C RXmlEngDOMImplementation Implementation() const;
   269     
   282     
   270     /**
   283     /**
   271      * Get document element
   284     Get the document element
   272      *
   285 	@return The document element -- the top-most element in the document tree
   273      * @since S60 v3.1
   286     */
   274 	 * @return A document element - the top-most element in the document tree
       
   275      */
       
   276     IMPORT_C TXmlEngElement DocumentElement() const;
   287     IMPORT_C TXmlEngElement DocumentElement() const;
   277 
   288 
   278     /**
   289 	/**
   279      * Sets "document" property on the node and all its descendants to be this RXmlEngDocument node 
   290 	Sets the "document" property on the node and all its descendants to be this
   280      *
   291 	RXmlEngDocument node 
   281      * @since S60 v3.1
   292 	@param aSource Node that should be added.
   282 	 * @param aSource Node that should be added.
   293     @return Adopted node
   283      * @return Adopted node
   294 	@leave KXmlEngErrWrongUseOfAPI The node has a parent node, the node is
   284      */
   295 	already owned by this document, or the node is a document.
       
   296 	@leave - One of the system-wide error codes
       
   297     */
   285     IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource);
   298     IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource);
   286 
   299 
   287     /**
   300     /**
   288      * Creates new attribute,
   301     Creates a new attribute.
   289      *
   302 
   290      * @since S60 v3.1
   303 	aValue should represent the correct value of an attribute if it is put
   291 	 * @param aName Name of the atribute; no prefix allowed
   304 	as-is into an XML file (with all characters correctly escaped with entity
   292      * @param aValue Value of the attribute (optional)
   305 	references when XML spec requires)
   293      * @return Handler to the newly created attribute 
   306     
   294      * 
   307 	The TXmlEngElement class provides a rich set of attribute creation methods,
   295      * @note 
   308 	which not only create attributes but also link them into elements.
   296      * aValue should represent a correct value of an attribute if it is put as is into XML file
   309     
   297      * (with all characters correctly escaped with entity references when XML spec requires)
   310 	@see TXmlEngElement
   298      * 
   311     
   299      * TXmlEngElement class provides a rich set of attribute creation methods, which not
   312     There is no way to create attributes with namespaces (despite the DOM spec); 
   300      * just create attribute but also link it into element.
   313     you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
   301      * 
   314 
   302      * There is no way to create attributes with namespace (despite the DOM spec); 
   315 	The returned attribute is the only reference to the allocated memory until
   303      * you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
   316 	you have attached the attribute to some element node.
   304      *
   317 
   305      * Returned handler is the only reference to the allocated memory
   318 	@param aName Name of the atribute; no prefix allowed
   306      * until you have attached the attribute to some element node
   319     @param aValue Value of the attribute (optional)
   307      */
   320     @return The newly created attribute 
       
   321 	@leave KXmlEngErrWrongUseOfAPI No name specified
       
   322 	@leave - One of the system-wide error codes
       
   323     */
   308     IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName,
   324     IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName,
   309                                     const TDesC8& aValue = KNullDesC8);
   325                                     const TDesC8& aValue = KNullDesC8);
   310 
   326 
   311     /**
   327     /**
   312      * Creates new text node and copies the content string into it.
   328     Creates a new text node and copies the content string into it.
   313      *
   329 	@param aCharacters Text node content
   314      * @since S60 v3.1
   330     @return The created node
   315 	 * @param aCharacters Text node content
   331 	@leave - One of the system-wide error codes
   316      * @return Created node
   332     */
   317      */
       
   318     IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8);
   333     IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8);
   319 
   334 
   320     /**
   335 	/**
   321      * Creates new binary container and copies the content string into it.
   336 	Creates a new binary container and copies the specified cid and data into
   322      * Pointer to the container is stored in the document's 
   337 	it.  A pointer to the container is stored in the document's data container
   323      * data container list that can be fetched using GetDataContainerList().
   338 	list that can be fetched using GetDataContainerList().
   324      * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
   339 
   325      *
   340     @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
   326      * @since S60 v3.2
   341 	@param aCid Content identifier     
   327 	 * @param aCid Content identifier     
   342 	@param aData Binary octets
   328 	 * @param aData Binary octets
   343     @return The new binary container
   329      * @return Created node
   344 	@leave - One of the system-wide error codes
   330      */
   345     */
   331     IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid,
   346     IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid,
   332     												  const TDesC8& aData );
   347     												  const TDesC8& aData );
   333 
   348 
   334     /**
   349 	/**
   335      * Creates new chunk container that stores reference to 
   350 	Creates a new chunk container and copies the specified cid into it.  A
   336      * memory chunk.
   351 	reference to a memory chunk is stored in the container.  The memory chunk
   337      * Pointer to the container is stored in the document's 
   352 	must stay in scope for the lifetime of the container.  A pointer to the
   338      * data container list that can be fetched using GetDataContainerList().
   353 	container is stored in the document's data container list that can be
   339      * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )     
   354 	fetched using GetDataContainerList().
   340      *
   355 
   341      * @since S60 v3.2
   356     @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )     
   342 	 * @param aCid Content identifier 
   357 	@param aCid Content identifier 
   343 	 * @param aChunk RChunk reference
   358 	@param aChunk RChunk reference
   344 	 * @param aChunkOffset Offset to the binary data in aChunk
   359 	@param aChunkOffset Offset to the binary data in aChunk
   345 	 * @param aDataSize Size of binary data in aChunk
   360 	@param aDataSize Size of binary data in aChunk
   346      * @return Created node
   361     @return The new chunk container
   347      */
   362 	@leave - One of the system-wide error codes
       
   363     */
   348     IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid, 
   364     IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid, 
   349     												const RChunk& aChunk,
   365     												const RChunk& aChunk,
   350 					                                const TInt aChunkOffset,
   366 					                                const TInt aChunkOffset,
   351 					                                const TInt aDataSize );
   367 					                                const TInt aDataSize );
   352 
   368 
   353     /**
   369 	/**
   354      * Creates new file container that stores reference to 
   370 	Creates a new file container and copies the specified cid into it.  A
   355      * file in file system.
   371 	reference to a file is stored in the container.  aFile must stay in scope
   356      * Pointer to the container is stored in the document's 
   372 	of the lifetime of the container.  A pointer to the container is stored in
   357      * data container list that can be fetched using GetDataContainerList().
   373 	the document's data container list that can be fetched using
   358      * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )     
   374 	GetDataContainerList().
   359      *
   375 
   360      * @since S60 v3.2
   376     @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )     
   361 	 * @param aCid Content identifier
   377 	@param aCid Content identifier
   362 	 * @param aFile RFile reference
   378 	@param aFile The file to reference
   363      * @return Created node
   379     @return The new file container
   364      */
   380 	@leave - One of the system-wide error codes
       
   381     */
   365     IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid, 
   382     IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid, 
   366     											  const RFile& aFile );
   383     											  const RFile& aFile );
   367 
   384 
   368     /**
   385 	/**
   369      * Creates new element node that belongs to specific namespace.
   386 	Creates a new element node that belongs to the specific namespace.  A
   370      * A namespace declaration node is created on the element.
   387 	namespace declaration node is created on the element.
   371      *
   388 
   372      * @since S60 v3.1
   389 	If the provided namespace uri is NULL, the element will be created without
   373 	 * @param aNamespaceUri Namespace of new element
   390 	namespace.
   374      * @param aPrefix Prefix to use for namespace binding and QName of the element
   391 
   375      * @param aLocalName Local name of the element 
   392 	@param aNamespaceUri Namespace of new element
   376      * @return Created node
   393     @param aPrefix Prefix to use for the namespace binding and the QName of the element
   377      * @note If null namespace uri is provided element will be created without namespace.
   394     @param aLocalName Local name of the element 
   378      */  
   395     @return The created element
       
   396 	@leave KXmlEngErrWrongUseOfAPI No name specified
       
   397 	@leave - One of the system-wide error codes
       
   398     */  
   379     IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName, 
   399     IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName, 
   380                                      const TDesC8& aNamespaceUri = KNullDesC8, 
   400                                      const TDesC8& aNamespaceUri = KNullDesC8, 
   381                                      const TDesC8& aPrefix = KNullDesC8);
   401                                      const TDesC8& aPrefix = KNullDesC8);
   382 
   402 
   383     /**
   403     /**
   384      * Creates new comment node and copies the content string into it.
   404 	Creates a new comment node and copies the specified string into it.
   385      *
   405 	@param aText New comment
   386      * @since S60 v3.1
   406     @return The created node
   387 	 * @param aText New comment
   407 	@leave - One of the system-wide error codes
   388      * @return Created node
   408     */
   389      */
       
   390     IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8);
   409     IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8);
   391 
   410 
   392     /**
   411     /**
   393      * Creates new CDATA section node and copies the content into it.
   412 	Creates a new CDATA section node and copies the specified string into it.
   394      *
   413 	@param aContents CDATASection content
   395      * @since S60 v3.1
   414     @return The created node
   396 	 * @param aContents CDATASection content
   415 	@leave - One of the system-wide error codes
   397      * @return Created node
   416     */
   398      */
       
   399     IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8);
   417     IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8);
   400 
   418 
   401     /**
   419     /**
   402      * Creates new entity reference node for aEntityName entity
   420 	Creates a new entity reference node and copies the specified string into
   403      *
   421 	it.
   404      * @since S60 v3.1
   422 
   405 	 * @param aEntityRef is a string in one of the forms:
   423 	Note:  &lt; , &gt; , &apos; , &quot; and other predefined entity references
   406      *     -  <i>name</i>
   424 	should not be created with this method. These entity references are rather
   407      *     -  <b>&</b><i>name</i>
   425 	"character references" and are encoded/decoded automatically.
   408      *     -  <b>&</b><i>name</i><b>;</b>
   426 
   409      * where <i>name</i> is the name of the entity
   427 	@param aEntityRef is a string in one of these forms:
   410      * @return Created node
   428         -  name
   411      * 
   429         -  &name
   412      * @note &lt; , &gt; , &apos; , &quot; and other <b>predefined</b> entity references
   430         -  &name;
   413      *      should not be created with this method. These entity refs are rather 
   431     where name is the name of the entity
   414      *      "character references" and encoded/decoded automatically.
   432     @return The new entity reference
   415      */
   433 	@leave KXmlEngErrWrongUseOfAPI No entity specified
       
   434 	@leave - One of the system-wide error codes
       
   435     */
   416     IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef);
   436     IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef);
   417 
   437 
   418     /**
   438     /**
   419      * Creates new processing instruction node and set its "target" and "data" values
   439     Creates a new empty Document Fragment node.  The document fragment is owned by
   420      *
   440 	this document.
   421      * @since S60 v3.1
   441 	@return The created document fragment
   422 	 * @param aTarget Target
   442 	@leave - One of the system-wide error codes
   423      * @param aData Data
   443     */
   424      * @return Created node
   444     IMPORT_C TXmlEngDocumentFragment CreateDocumentFragmentL();
   425      */
   445 
       
   446 	/**
       
   447 	Creates a new processing instruction node and copies "target" and "data"
       
   448 	into it.
       
   449 	
       
   450 	@param aTarget Target
       
   451     @param aData Data
       
   452     @return The created processing instruction
       
   453 	@leave KXmlEngErrWrongUseOfAPI No target specified
       
   454 	@leave - One of the system-wide error codes
       
   455     */
   426     IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget, 
   456     IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget, 
   427                                                                  const TDesC8& aData = KNullDesC8);
   457                                                                  const TDesC8& aData = KNullDesC8);
   428                                                                  
   458                                                                  
   429     /**
   459 	/**
   430      * Registers specified attribute as xml:id.
   460 	Sets the specified attribute as a xml:id attribute, starting at
   431      * First parametr allows user, to specify sub-tree, not to search whole document.
   461 	aStartElement and recursing through the subtree.  To set the specified
   432      * To search whole tree see @see RegisterXmlId(const TDesC8,const TDesC8)
   462 	attribute as a xml:id attribute for the entire DOM tree, see
   433      *
   463 	RegisterXmlId(const TDesC8&,const TDesC8&).
   434      * @since S60 v3.2
   464 
   435      * @param aStartElement Root of tree to search (should be part of the document)
   465     @param aStartElement Root of the subtree to recurse
   436      * @param aLocalName Name of attribute
   466     @param aLocalName Name of the attribute
   437 	 * @param aNamespaceUri Namespace of new element (default empty)
   467 	@param aNamespaceUri Namespace of the new element (default empty)
   438      */
   468 	@leave KXmlEngErrWrongUseOfAPI The starting element is NULL, the attribute
       
   469 	name is not specified, the starting element is the document, or the
       
   470 	starting element does not belong to a document.
       
   471 	@leave KErrAlreadyExists The attribute is already set to be xml:id
       
   472 	@leave - One of the system-wide error codes
       
   473     */
   439     IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement,
   474     IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement,
   440                                  const TDesC8& aLocalName, 
   475                                  const TDesC8& aLocalName, 
   441                                  const TDesC8& aNamespaceUri = KNullDesC8);
   476                                  const TDesC8& aNamespaceUri = KNullDesC8);
   442 
   477 
   443     /**
   478 	/**
   444      * Registers specified attribute as xml:id.
   479 	Sets the specified attribute as a xml:id attribute, recursing through the
   445      * Not to search whole tree see @see RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8)
   480 	entire DOM tree.  In order to specify a subtree only, see
   446      *
   481 	RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8).
   447      * @since S60 v3.2
   482 
   448      * @param aLocalName Name of attribute
   483     @param aLocalName Name of attribute
   449 	 * @param aNamespaceUri Namespace of new element (default empty)
   484 	@param aNamespaceUri Namespace of new element (default empty)
   450      */
   485 	@leave KXmlEngErrWrongUseOfAPI The document is NULL
       
   486 	@leave KErrAlreadyExists The attribute is already set to be xml:id
       
   487 	@leave - One of the system-wide error codes
       
   488     */
   451     IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName, 
   489     IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName, 
   452                                  const TDesC8& aNamespaceUri = KNullDesC8);
   490                                  const TDesC8& aNamespaceUri = KNullDesC8);
   453        
   491        
   454     /**
   492     /**
   455      * Looks for element with specified value of xml:id
   493     Looks for an element with the specified xml:id attribute
   456      *
   494 	@param aValue Name of attribute
   457      * @since S60 v3.2
   495     @return The found element or a NULL element if not found
   458 	 * @param aValue Name of attribute
   496 	@leave - One of the system-wide error codes
   459      * @return found element or null-element.
   497     */
   460      */
       
   461     IMPORT_C TXmlEngElement FindElementByXmlIdL(const TDesC8& aValue ) const;  
   498     IMPORT_C TXmlEngElement FindElementByXmlIdL(const TDesC8& aValue ) const;  
   462 
   499 
   463     /**
   500     /**
   464      * Retrieves an array of data containers owned by this document.
   501     Retrieves an array of data containers owned by this document.
   465      *
   502 
   466 	 * @note The document ceases to be the owner of data container when data container
   503 	Note: The document ceases to be the owner of a data container when the data
   467 	 *		 (or one of its predecessors) is removed from the document or data container 
   504 	container (or one of its predecessors) is removed from the document or
   468 	 * 	 	 (or one of its predecessors) becomes a part of another document.
   505 	becomes part of another document.  Unlinking a data container (or one of its
   469 	 *		 Unlinking data container (or one of its predecessors) doesn't remove
   506 	predecessors) doesn't remove ownership of the data container from this
   470 	 *		 ownership of data container from the this document so the list might
   507 	document so the list might contain containers that are not linked to this
   471 	 *		 contain containers that are not linked to this document anymore.    
   508 	document anymore.    
   472      * @since S60 v3.2
   509 
   473 	 * @param aList Array of data containers
   510 	@param aList Array of data containers
   474      */
   511 	@return KErrNone if successful or one of the system wide error codes otherwise
   475     IMPORT_C void GetDataContainerList( RArray<TXmlEngDataContainer>& aList );         
   512     */
       
   513     IMPORT_C TInt GetDataContainerList( RArray<TXmlEngDataContainer>& aList );
   476                                                                  
   514                                                                  
   477 protected:
   515 protected:
   478     friend class RXmlEngDOMParser;
   516     friend class RXmlEngDOMParser;
   479     friend class TXmlEngNode;
   517     friend class TXmlEngNode;
   480     friend class TXmlEngAttr;
   518     friend class TXmlEngAttr;
   481     friend class TXmlEngElement;
   519     friend class TXmlEngElement;
   482     friend class RXmlEngDOMImplementation;
   520     friend class RXmlEngDOMImplementation;
   483 
   521 
   484 protected:
   522 protected:
   485     /**
   523     /**
   486      * Constructor
   524     Constructor
   487      *
   525 	@param aInternal Document pointer
   488      * @since S60 v3.1
   526 	*/
   489 	 * @param aInternal Document pointer
       
   490 	 */
       
   491     inline RXmlEngDocument(void* aInternal);
   527     inline RXmlEngDocument(void* aInternal);
   492 
   528 
   493     /**
   529     /**
   494      * DISABLED for document; CloneDocumentL() must be used
   530     DISABLED for document; CloneDocumentL() must be used
   495      *
   531 	*/
   496      * @since S60 v3.1
       
   497 	 */
       
   498     inline TXmlEngNode CopyL() const; 
   532     inline TXmlEngNode CopyL() const; 
   499 
   533 
   500     /**
   534     /**
   501      * DISABLED for document; Destroy() must be used
   535     DISABLED for document; Close() must be used
   502      *
   536 	*/    
   503      * @since S60 v3.1
       
   504 	 */    
       
   505     inline void Remove();
   537     inline void Remove();
   506 
   538 
   507     /**
   539     /**
   508      * DISABLED for document; Destroy() must be used
   540     DISABLED for document; Close() must be used
   509      *
   541 	*/ 
   510      * @since S60 v3.1
   542     inline void ReplaceWith(TXmlEngNode aNode);
       
   543     inline void ReplaceWithL(TXmlEngNode aNode);
       
   544     
       
   545     /**
       
   546     DISABLED for document; Close() must be used
   511 	 */ 
   547 	 */ 
   512     inline void ReplaceWith(TXmlEngNode aNode);
   548     inline TXmlEngNode SubstituteForL(TXmlEngNode aNode);
       
   549 
   513 private:
   550 private:
   514     /**
       
   515      * Main implementation of SaveL() functions that puts together all common code
       
   516      * and serializes to buffer or output stream.
       
   517      *
       
   518      * @since S60 v3.2
       
   519 	 * @param aNode Root node to be serialized     
       
   520 	 * @param aBuffer buffer with serialized data.
       
   521 	 * @param aOutputStream stream that should be used during serialization
       
   522 	 * @param aSaveOptions Options that control how serialization is performed
       
   523      * @return Number of bytes written
       
   524      * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.     
       
   525 	 */ 
       
   526 	TInt SaveNodeL( TXmlEngNode aNode,
   551 	TInt SaveNodeL( TXmlEngNode aNode,
   527 					RBuf8& aBuffer,
   552 					RBuf8& aBuffer,
   528                	    MXmlEngOutputStream* aOutputStream = NULL,
   553                	    MXmlEngOutputStream* aOutputStream = NULL,
   529                	    TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const;	
   554                	    TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const;	
   530 
   555 
   531     /**
       
   532      * "Secondary" constructor that should be called on every newly created document node.
       
   533      * Initializes container for nodes owned by the document.
       
   534      *
       
   535      * The need for such secondary constructor is in the fact that underlying libxml2
       
   536      * library knows nothing about ownership of unlinked nodes -- this feature is
       
   537      * implemented in C++ DOM wrapper.
       
   538      *
       
   539      * @since S60 v3.1
       
   540 	 */ 
       
   541     void InitOwnedNodeListL();
   556     void InitOwnedNodeListL();
   542 
       
   543     /**
       
   544      * Adds aNode to the list of owned nodes - the nodes that are not linked yet into a 
       
   545      * document tree, but still destroyed with the document that owns them.
       
   546      *
       
   547      * @since S60 v3.1
       
   548 	 * @param aNode Node that should be added to document
       
   549      *
       
   550      * In case of OOM (during growing node list container) the argument node is freed with
       
   551      * xmlFreeNode()
       
   552      */ 
       
   553     void TakeOwnership(TXmlEngNode aNode);
   557     void TakeOwnership(TXmlEngNode aNode);
   554 
       
   555     /**
       
   556      * Remove aNode from the list of owned nodes.
       
   557      *
       
   558      * @since S60 v3.1
       
   559 	 * @param aNode Node that should be removed from document
       
   560      */
       
   561     void RemoveOwnership(TXmlEngNode aNode);
   558     void RemoveOwnership(TXmlEngNode aNode);
   562 
   559 
   563 protected:
   560 protected:
   564     /**  Pointer to DOM implementation object */
   561     /**  Pointer to DOM implementation object */
   565     RXmlEngDOMImplementation* iImpl;
   562     RXmlEngDOMImplementation* iImpl;
   566 
   563 
   567 };// class RXmlEngDocument
   564 };// class RXmlEngDocument
   568 
   565 
   569 
   566 
   570 
   567 
   571 #include "xmlengdocument.inl"
   568 #include <xml/dom/xmlengdocument.inl>
   572 
   569 
   573 #endif /* XMLENGINE_DOCUMENT_H_INCLUDED */
   570 #endif /* XMLENGDOCUMENT_H */