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

    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

    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

    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 */

    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 	 */

    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      */

    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     */

    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 	 */

    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 	*/

   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     */                        

   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     */

   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     */

   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     */

   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     */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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     */

   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     */

   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      */

   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     */

   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     */

   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     */

   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     */  

   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      */

   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      */

   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:  < , > , ' , " 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     */

   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     */

   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     */

   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     */

   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      */

   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 );

   486      * Constructor

   524     Constructor

   487      *

   525 	@param aInternal Document pointer

   488      * @since S60 v3.1

   526 	*/

   489 	 * @param aInternal Document pointer

   490 	 */

   494      * DISABLED for document; CloneDocumentL() must be used

   530     DISABLED for document; CloneDocumentL() must be used

   495      *

   531 	*/

   496      * @since S60 v3.1

   497 	 */

   501      * DISABLED for document; Destroy() must be used

   535     DISABLED for document; Close() must be used

   502      *

   536 	*/    

   503      * @since S60 v3.1

   504 	 */    

   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

   512     inline void ReplaceWith(TXmlEngNode aNode);

   548     inline TXmlEngNode SubstituteForL(TXmlEngNode aNode);

   549 

   571 #include "xmlengdocument.inl"

   568 #include <xml/dom/xmlengdocument.inl>

   572 

   569 

   573 #endif /* XMLENGINE_DOCUMENT_H_INCLUDED */

   570 #endif /* XMLENGDOCUMENT_H */