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