* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

* under the terms of "Eclipse Public License v1.0"

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

* Description:

/** @file

@publishedAll

@released

*/

#ifndef XMLENGDOMPARSER_H

#define XMLENGDOMPARSER_H

This class implements methods for parsing XML data.  XML data may be parsed

from a chunk, file, or memory buffer.

Sample code for parsing from buffer:

@code

     RXmlEngDOMImplementation domImpl;

     domImpl.OpenL();              // opening DOM implementation object 

     RXmlEngDOMParser parser;

     parser.Open( domImpl );   // opening parser object

     RXmlEngDocument iDoc;

     iDoc =parser.ParseL( *aInput );   // parsing aInput - buffer  

     iDoc.Close();               // closing all opened objects

     parser.Close();

     domImpl.Close();

@endcode 

Sample code for parsing from file:

@code

     RXmlEngDOMImplementation domImpl;

     domImpl.OpenL();              // opening DOM implementation object 

     RXmlEngDOMParser parser;

     parser.Open( domImpl );   // opening parser object

     RXmlEngDocument iDoc;

     iDoc =parser.ParseFileL( aFileName );   // parsing from file  

     iDoc.Close();               // closing all openend objects

     parser.Close();

     domImpl.Close();

@endcode 

*/

    /** Default constructor */

	Opens the parser.  The RXmlEngDOMImplementation object passed as an

	argument may be used by multiple RXmlEngDOMParser objects.

	@param aDOMImpl DOM implementation object previously opened without error.

    @return KErrNone if successful, system wide error code otherwise

    */

    /** Closes the parser. */

	/** 

	Parses a chunk of XML data from a memory buffer and builds an internal DOM

	tree.  The DOM tree can be accessed by calling FinishL() to obtain a

	RXmlEngDocument.

	@see FinishL()

    @param aBuffer XML data buffer

	@see GetLastParsingError()

    @leave KXmlEngErrParsing Parsing error

	@leave KXmlEngErrWrongUseOfAPI OpenL() not previously called

	@leave - One of the system-wide error codes

    */

	/** 

	Creates a document from chunks of data previously parsed by ParseChunkL().

	Should be called after parsing all chunks.  Ownership of the returned

	RXmlEngDocument object is transferred to the caller of the method.

	RXmlEngDocument::Close() must be called when the document is no longer

	required.

	@see ParseChunkL()

    @return The created document

	@see GetLastParsingError()

    @leave KXmlEngErrParsing Parsing error

	@leave KXmlEngErrWrongUseOfAPI OpenL() or ParseChunkL() not previously 

	called

	@leave - One of the system-wide error codes

    */

	Parses XML file and builds a DOM RXmlEngDocument.  Ownership of the

	returned RXmlEngDocument object is transferred to the caller of the method.

	RXmlEngDocument::Close() must be called when the document is no longer

	required.

	@param aRFs Open file server session

    @param aFileName File name

	@param aChunkSize The number of bytes to parse from the file at a time, or 0

	if the whole file should be parsed at once.

    @return The created document

	@see GetLastParsingError()

    @leave KXmlEngErrParsing Parsing error

	@leave KXmlEngErrWrongUseOfAPI OpenL() not previously called

	@leave - One of the system-wide error codes

	*/

    Parses XML file and builds a DOM RXmlEngDocument.  Ownership of the

	returned RXmlEngDocument object is transferred to the caller of the method.

	RXmlEngDocument::Close() must be called when the document is no longer

	required.

	@param aFileName File name

	@param aChunkSize The number of bytes to parse from the file at a time, or 0

	if the whole file should be parsed at once.

    @return The created document

	@see GetLastParsingError()

    @leave KXmlEngErrParsing Parsing error

	@leave KXmlEngErrWrongUseOfAPI OpenL() not previously called

	@leave - One of the system-wide error codes

    */

	/** 

	Parses XML data from a memory buffer that holds the entire XML structure

	and builds a DOM RXmlEngDocument.  Ownership of the returned

	RXmlEngDocument object is transferred to the caller of the method.

	RXmlEngDocument::Close() must be called when the document is no longer

	required.

	@see ParseChunkL()

	@param aBuffer XML data buffer

    @return The created document

	@see GetLastParsingError()

    @leave KXmlEngErrParsing Parsing error

	@leave KXmlEngErrWrongUseOfAPI OpenL() not previously called

	@leave - One of the system-wide error codes

    */

    Return last parsing error code.  Error codes are positive numbers.

	@see xmlengerrors.h

	@return The last error returned by the parser or KErrNone if none

    */

    void Cleanup();

#endif /* XMLENGDOMPARSER_H */