/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

/** @file

@publishedAll

@released

*/

#ifndef XMLENGDOMPARSER_H

#define XMLENGDOMPARSER_H

#include <f32file.h>

class RXmlEngDOMImplementation;

class RXmlEngDocument;

/** 

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 

*/

class RXmlEngDOMParser

{

public:

    /** Default constructor */

    IMPORT_C RXmlEngDOMParser();

    /** 

	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

    */

    IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl);

    /** Closes the parser. */

    IMPORT_C void Close();

	/** 

	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

    */

    IMPORT_C void ParseChunkL(const TDesC8& aBuffer);

	/** 

	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

    */

    IMPORT_C RXmlEngDocument FinishL();

    /** 

	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

	*/

    IMPORT_C RXmlEngDocument ParseFileL(RFs &aRFs, const TDesC& aFileName, TUint aChunkSize = 0);

    /** 

    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

    */

    IMPORT_C RXmlEngDocument ParseFileL(const TDesC& aFileName, TUint aChunkSize = 0);

	/** 

	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

    */

    IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer);  

    /** 

    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

    */

    IMPORT_C TInt GetLastParsingError();

private:

    RXmlEngDocument ParseFileWithoutChunksL(RFs& aRFs, const TDesC& aFileName);

    void Cleanup();

private:

    void* iInternal;

    TInt iError;

    RXmlEngDOMImplementation* iImpl;

};

#endif /* XMLENGDOMPARSER_H */