/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:       DOM parser functions

*

*/

#ifndef XMLENGINE_DOMPARSER_H_INCLUDED

#define XMLENGINE_DOMPARSER_H_INCLUDED

#include <f32file.h>

class RXmlEngDOMImplementation;

class RXmlEngDocument;

/** 

 * DOM parser class implements methods for parsing XML data.

 *

 * Parse XML data in one chunk. Data can be parsed from 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 

 * 

 * @lib XmlEngineDOM.lib

 * @since S60 v3.1

 */

class RXmlEngDOMParser

{

public:

    /**

     * Default constructor

     */

    IMPORT_C RXmlEngDOMParser();

    /** 

     * Opens the parser.

     *

	 * @since S60 v3.2

	 * @param aDOMImpl DOM implementation object

     * @return KErrNone if succeed.

     */

    IMPORT_C TInt Open(RXmlEngDOMImplementation& aDOMImpl);

    /** 

     * Closes the parser.

     *

	 * @since S60 v3.2

	 */

    IMPORT_C void Close();

    /** 

     * Parses chunk of XML data from memory buffer and builds DOM RXmlEngDocument.

     *

     * @since S60 v3.2

     * @param aBuffer XML data buffer

     * 

     * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

     */

    IMPORT_C void ParseChunkL(const TDesC8& aBuffer);

    /** 

     * Creates document from parsed chunks of data.

     * Should be called after parsing of allchunks.

     * Ownership over returned RXmlEngDocument object is transferred to the caller of the method.

     *

     * @since S60 v3.2

     * @return RXmlEngDocument created document.

     * 

     * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

     */

    IMPORT_C RXmlEngDocument FinishL();

    /** 

     * Parses XML file and builds DOM RXmlEngDocument

     *

     * @since S60 v3.2

	 * @param aRFs File server session

     * @param aFileName File name

     * @param aChunkSize Size of chunk (if 0 chunks won't be used)

     * @return Document handle

     * 

     * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

	 */

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

    /** 

     * Parses XML file and builds DOM RXmlEngDocument

     *

     * @since S60 v3.2

	 * @param aFileName File name

     * @param aChunkSize Size of chunk (if 0 chunks won't be used)

     * @return Document handle

     * 

     * @leave KXmlEngErrParsing or one of general codes (e.g. KErrNoMemory)

     */

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

    /** 

     * Parses XML data from memory buffer and builds DOM RXmlEngDocument without chunks

     *

	 * @since S60 v3.1

	 * @param aBuffer XML data buffer

     * @return Document handle

     * 

     * @leave KXmlEngErrParsing code (besides system I/O error codes)

     */

    IMPORT_C RXmlEngDocument ParseL(const TDesC8& aBuffer);  

    /** 

     * Return last parsing error code. 

     *

     * @since S60 v3.2

	 * @return positive number

     *

     * @note Error codes are positive numbers. User can find them

     *         in XmlEngDErrors.h

     */

    IMPORT_C TInt GetLastParsingError();

private:

    /** 

     * Parses XML file and builds DOM RXmlEngDocument without usage of chunks

     *

     * @param aRFs File server session

     * @param aFileName File name

     * @return Document handle

     * 

     * @leave KXmlEngErrParsing code (besides system I/O error codes)

	 */

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

    /** 

     * Cleanup internal data.

     *

     * @since S60 v3.2

     */

    void Cleanup();

private:

    void* iInternal;

    TInt iError;

    RXmlEngDOMImplementation* iImpl;

};

#endif /* XMLENGINE_DOMPARSER_H_INCLUDED */