/*

 * Copyright (c) 2002-2005 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:        Class extends Symbian XML framework parser functionality

 *

 */

 #ifndef SEN_XMLREADER_H

 #define SEN_XMLREADER_H

 //  INCLUDES

 #include <Xml/Parser.h>

 #include <Xml/ParserFeature.h> // for TParserFeature enumeration

 #include <Xml/ContentHandler.h>

 #include <badesca.h>

 using namespace Xml;

 // CONSTANTS

 const TInt KSenDefaultParserFeature = (TInt)EReportNamespaceMapping;

 // FORWARD DECLARATIONS

 class MSenContentHandlerClient;

 class RFs;

 // CLASS DECLARATION

 /**

 *  Class extends Symbian XML framework parser functionality

 *  Callers of this class must register some handler which will

 *  then receive XML callback events from underlying Symbian

 *  XML framework.

 *  @lib SenXML.dll

 *  @since Series60 3.0

 */

 class CSenXmlReader : public CBase, public MContentHandler 

     {

     public:  // Constructors and destructor

         /**

         * Standard two-phase constructor.

         * Creates new parser instance using default

         * MIME type "text/xml" (KXmlParserMimeType).

         * @since Series60 3.0

         * @return pointer to a new CSenXmlReader instance.

         */

         IMPORT_C static CSenXmlReader* NewL();

         /**

         * Standard two-phase constructor.

         * Creates new parser instance using default

         * MIME type "text/xml" (KXmlParserMimeType).

         * @since Series60 3.0

         * @return pointer to a new CSenXmlReader instance

         * which is left on cleanup stack.

         */

         IMPORT_C static CSenXmlReader* NewLC();

         /**

         * A constructor with parser feature enabling. Uses default

         * parser MIME type "text/xml" (KXmlParserMimeType).        

         * @since Series60 3.0

         * @param aParserFeature is typically some enumeration introduced 

         *      in Xml::TParserFeature or some other feature introduced in 

         *      some XML parser implementation.

         *  Leave codes:

         *      KErrArgument    if aParserFeature value is negative.

         */ 

         IMPORT_C static CSenXmlReader* NewL(TInt aParserFeature);

         /**

         * A constructor with parser feature enabling. Uses default

         * parser MIME type "text/xml" (KXmlParserMimeType). 

         * @since Series60 3.0

         * @param aParserMimeType is the XML parser MIME type.

         *      If descriptor is of zero-length, then default 

         *      MIME type KXmlParserMimeType is used ("text/xml").

         *      Availability of other MIME types depends on 

         *      underlying parser implementation.

         * @param aParserFeature is typically some enumeration introduced 

         *      in Xml::TParserFeature or some other feature introduced in 

         *      some XML parser implementation.

         *  Leave codes:

         *      KErrArgument    if aParserFeature value is negative.

         */ 

         IMPORT_C static CSenXmlReader* NewLC(TInt aParserFeature);

         /**

         * A constructor with parser MIME type.

         * Standard two-phase constructor.

         * @since Series60 3.0

         * @param aParserMimeType is the XML parser MIME type.

         *      If descriptor is of zero-length, then default 

         *      MIME type KXmlParserMimeType is used ("text/xml").

         *      Availability of other MIME types depends on 

         *      underlying parser implementation.

         * @return pointer to a new CSenXmlReader instance.

         */

         IMPORT_C static CSenXmlReader* NewL(const TDesC8& aParserMimeType);

         /**

         * A constructor with parser MIME type.

         * @since Series60 3.0

         * @param aParserMimeType is the XML parser MIME type.

         *      If descriptor is of zero-length, then default 

         *      MIME type KXmlParserMimeType is used ("text/xml").

         *      Availability of other MIME types depends on 

         *      underlying parser implementation.

         * @return pointer to a new CSenXmlReader instance

         * which is left on cleanup stack.

         */

         IMPORT_C static CSenXmlReader* NewLC(const TDesC8& aParserMimeType);

         /**

         * A constructor with parser MIME type and parser feature enabling.

         * @since Series60 3.0

         * @param aParserFeature is typically some enumeration introduced 

         *      in Xml::TParserFeature or some other feature introduced in 

         *      some XML parser implementation.

         *  Leave codes:

         *      KErrArgument    if aParserFeature value is negative.

         */ 

         IMPORT_C static CSenXmlReader* NewL(const TDesC8& aParserMimeType,

                                             TInt aParserFeature);

         /**

         * A constructor with parser MIME type and parser feature enabling.

         * @since Series60 3.0

         * @param aParserMimeType is the XML parser MIME type.

         *      If descriptor is of zero-length, then default 

         *      MIME type KXmlParserMimeType is used ("text/xml").

         *      Availability of other MIME types depends on 

         *      underlying parser implementation.

         * @param aParserFeature is typically some enumeration introduced 

         *      in Xml::TParserFeature or some other feature introduced in 

         *      some XML parser implementation.

         *  Leave codes:

         *      KErrArgument    if aParserFeature value is negative.

         */ 

         IMPORT_C static CSenXmlReader* NewLC(const TDesC8& aParserMimeType,

                                              TInt aParserFeature);

         /**

         * Destructor.

         */

         IMPORT_C virtual ~CSenXmlReader();

         // New functions

         /**

         * Method to allow client to register a content event handler (for XML) for

         * the current reader.

         * @since Series60 3.0

         * @param aContentHandler The new event handler.

         */

         IMPORT_C virtual void SetContentHandler(

                     MSenContentHandlerClient& aContentHandler);

         /**

         * Method for checking which feature has been enabled in the parser.

         * @since Series60 3.0

         * @return the corresponding integer id of the feature

         */

         IMPORT_C virtual TInt EnabledParserFeature();

         /**

         * @deprecated - use EnabledParserFeature() instead.

         */

         IMPORT_C virtual TInt ParserFeature();

         /**

         * Method for enabling a parser feature.

         * @since Series60 3.0

         * @param aParserFeature is typically some enumeration introduced 

         *           in Xml::TParserFeature or some other feature introduced in 

         *           some XML parser implementation.

         * @return KErrNone or some system-wide error code, if an error has 

         *         occurred.

         */

         TInt SetParserFeature(TInt aParserFeature);     

         /**

         * Parse an XML buffer.

         * @since Series60 3.0

         * @param aBuff Buffer containing document to parse.

         * Note that this method will also leave, if an error

         * is returned from Symbian XML framework. Here are

         * the corresponding enums, and their respective

         * error code values (-1000, -999... and up)

         * (XML-specific errors returned by the XML parser)

         * [from XmlParserErrors.h]

     	* EXmlParserError = -1000,

     	* EXmlSyntax = 2+EXmlParserError,		// -998

     	* EXmlNoElements,						// -997

     	* EXmlInvalidToken,					    // -996

     	* EXmlUnclosedToken,					// -995

     	* EXmlPartialChar,                      // -994

     	* EXmlTagMismatch,                      // -993

     	* EXmlDuplicateAttribute,               // -992

     	* EXmlJunkAfterDocElement,              // -991

     	* EXmlPeRef,                            // -990

     	* EXmlUndefinedEntity,                  // -989

     	* EXmlRecursiveEntity,                  // -988

     	* EXmlAsyncEntity,                      // -987

     	* EXmlBadCharRef,                       // -986

     	* EXmlBinaryEntityRef,                  // -985

     	* EXmlAttributeExternalEntityRef,       // -984

     	* EXmlMisplacedPi,                      // -983

     	* EXmlUnknownEncoding,                  // -982

     	* EXmlIncorrectEncoding,                // -981

     	* EXmlUnclosedCdata,                    // -980

     	* EXmlExternalEntityHandling,           // -979

     	* EXmlNotStandalone,                    // -978

     	* EXmlUnexpectedState,                  // -977

     	* EXmlEntityDeclInPe,                   // -976

     	* EXmlDtdRequired,                      // -975

     	* EXmlFeatureLockedWhileParsing         // -974

         */

         IMPORT_C void ParseL(const TDesC8& aBuff);

         /**

         * Parse an XML document.

         * @since Series60 3.0

         * @param aRFs An open filesession.

         * @param aFileToParse Filename of file to parse.

         */

         IMPORT_C void ParseL(RFs &aRFs, const TDesC& aFileToParse);

         // Functions from base classes 

         // Callback functions implementing Symbian MContentHandler interface

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *               be avoided calling SetContentHandlerL() method prior

         *               parsing some XML document.

         */

         virtual void OnStartDocumentL(const RDocumentParameters& aDocParam, 

                                       TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnEndDocumentL(TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnStartElementL(const RTagInfo& aElement, 

                                      const RAttributeArray& aAttributes, 

                                      TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnEndElementL(const RTagInfo& aElement, TInt aErrorCode);

         /**

         * @since Series60 3.0

         * @param aBytes is the actual XML data, content in UTF-8 form

         * @param aErrorCode KErrNone, or some system-wide error code

         *        if an error has occured.

         */

         virtual void OnContentL(const TDesC8& aBytes, TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnStartPrefixMappingL(const RString& aPrefix, 

                                            const RString& aUri, 

                                            TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnEndPrefixMappingL(const RString& aPrefix, TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnIgnorableWhiteSpaceL(const TDesC8& aBytes, TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnSkippedEntityL(const RString& aName, TInt aErrorCode);

         /**

         * @since Series60 3.0

         *   Leave codes:

         *       KErrSenXmlContentHandlerNotSet  if XML content handler

         *       for this XML reader has not been set. This leave can

         *       be avoided calling SetContentHandlerL() method prior

         *       parsing some XML document.

         */

         virtual void OnProcessingInstructionL(const TDesC8& aTarget, 

                                               const TDesC8& aData, 

                                               TInt aErrorCode);

         /**

         * OnError is a callback method signalled by Symbian XML

         * framework. Current implementation of this class issues

         * a leave in original ParseL() call on any received by

         * this callback implementation. Used leave code will be

         * the received error code.

         *

         * @since Series60 3.0

         * @param aErrorCode is one of the Symbian XML framework

         * errors listed in XmlFrameworkErrors.h

         *

         * Currently any s

         *

         * If content handler was not set, ParseL will leaves with

         * KErrSenXmlContentHandlerNotSet.

         */

         virtual void OnError(TInt aErrorCode);

         /**

         * This method obtains the interface matching the specified UID.

         * @since Series60 3.0

         * @param    aUid    the UID identifying the required interface.

         * @return   NULL    if no interface matching the UID is found or

         *                    if content handler was not set. Otherwise, 

         *                    returns pointer to the interface.

         */

         virtual TAny* GetExtendedInterface(const TInt32 aUid);

     protected:

         /**

         * C++ constructor.

         */

         IMPORT_C CSenXmlReader(TInt aParserFeature);

         /**

         * Symbian 2nd phase constructor.

         * @param aParserMimeType sets the MIME type of 

         * this XML parser.

         */

         void ConstructL(const TDesC8& aParserMimeType);

         // New functions

         /**

         * This method re-initializes encapsulated CParser class instance.

         * @since Series60 3.0

         */

         void RecreateParserL();

     private:

         static void CleanupParser(TAny* apReader);

         void CleanUp();

     private:    // Data

             // Owned instance of Symbian XML framework (default) XML parser

         CParser* iParser;

             // Not owned pointer to XML content handler.

         MSenContentHandlerClient* iContentHandler;

         // Owned pointer to XML namespace prefix strings

         CDesC8Array* ipNsPrefixes;

         // Owned pointer to XML namespace URI strings

         CDesC8Array* ipNsUris;

         // Owned string pool for XML attribute handling.

         RStringPool iStringPool;

             // Integer indicating currently enabled features

         TInt iEnabledFeature;

     };

 #endif  // SEN_XMLREADER_H

 // End of File