/*

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