/*

* Copyright (c) 2009 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:   ?Description

*

*/

#ifndef IA_UPDATE_XML_SUB_PARSER_H

#define IA_UPDATE_XML_SUB_PARSER_H

#include <e32base.h>

#include <e32cmn.h>

#include <xml/contenthandler.h>

#include <f32file.h>

/**

 * CIAUpdateXmlSubParser is the parent class 

 * for IA Update XML sub parsers and provides the basic functionality

 * that is common for all the IA Update XML sub parsers.

 * This class can not be instantiated itself. So, child classes

 * must be created to finalize the functionality.

 *

 * @since S60 v3.2

 */

class CIAUpdateXmlSubParser : public CBase,

                              public Xml::MContentHandler

    {

public:

    /**

     * Destructor

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual ~CIAUpdateXmlSubParser();

public: // Xml::MContentHandler

    /**

     * @see Xml::MContentHandler::OnStartDocumentL

     *

     * Initializes this sub parser and its sub parsers. 

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual void OnStartDocumentL( const Xml::RDocumentParameters& aDocParam, 

                                            TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnEndDocumentL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual void OnEndDocumentL( TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnStartElementL

     *

     * If necessary, this function can set the current sub parser for this 

     * sub parser by finding the correct subparser from the sub parser array.

     * ElementTagInfoEquals function is used for comparison. 

     * When the current sub parser is set, then element handling is

     * forwarded to the subparser until end tag of the element is reached.

     * The forwarding makes it possible to create a structural element

     * handling. If forwarding is not required, then child classes

     * can handle elements directly in their implementation of this function.

     * This function will set the AcceptData flag to a correct state.

     *

     * Child classes may provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */    

    IMPORT_C virtual void OnStartElementL( const Xml::RTagInfo& aElement, 

                                           const Xml::RAttributeArray& aAttributes, 

                                           TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnEndElementL

     *

     * If current sub parser is set for this sub parser, hanling of the elements 

     * is forwarded to the sub parser. ElementTagInfoEquals function is used to 

     * check if the current subparser has finished its job. If sub parser is not

     * needed, then sub parser is set to NULL and the responsibility of 

     * handling elements is given back to this class object.

     * This function will set the AcceptData flag to a correct state.

     *

     * Child classes may provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */                                  

    IMPORT_C virtual void OnEndElementL( const Xml::RTagInfo& aElement, 

                                         TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnContentL

     *

     * If current sub parser is set for this sub parser, hanling of the elements 

     * is forwarded to the sub parser.

     *

     * Child classes may provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */                                

    IMPORT_C virtual void OnContentL( const TDesC8& aBytes, 

                                      TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnStartPrefixMappingL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */                             

    IMPORT_C virtual void OnStartPrefixMappingL( const RString& aPrefix, 

                                                 const RString& aUri, 

                                                 TInt aErrorCode);

    /**

     * @see Xml::MContentHandler::OnEndPrefixMappingL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */                                        

    IMPORT_C virtual void OnEndPrefixMappingL( const RString& aPrefix, 

                                               TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnIgnorableWhiteSpaceL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */    

    IMPORT_C virtual void OnIgnorableWhiteSpaceL( const TDesC8& aBytes, 

                                                  TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnSkippedEntityL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */    

    IMPORT_C virtual void OnSkippedEntityL( const RString& aName, 

                                            TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnProcessingInstructionL

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */    

    IMPORT_C virtual void OnProcessingInstructionL( const TDesC8& aTarget, 

                                                    const TDesC8& aData, 

                                                    TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::OnError

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual void OnError( TInt aErrorCode );

    /**

     * @see Xml::MContentHandler::GetExtendedInterface

     *

     * This contains only an empty implementation. Child classes may

     * provide their own implemenations if necessary.

     *

     * @since S60 v3.2

     */    

    IMPORT_C virtual TAny* GetExtendedInterface( const TInt32 aUid );

protected:

    /**

     * Constructor

     *

     * @since S60 v3.2

     */

    IMPORT_C CIAUpdateXmlSubParser();

    /**

     * 2nd. phase constructor.

     *

     * @note This may be a good place for the child classes to implement

     * a functionality that adds its sub browsers to the sub browser array

     * that is used to delegate element handling to correct places.

     *

     * @param aElementLocalName This value is the local name of the

     * element that this parser is for. ElementTagInfoEquals function uses

     * this as a default to check if this parser is meant for the element

     * that the platform XML parser gives.

     *

     * @since S60 v3.2

     */

    IMPORT_C virtual void ConstructL( const TDesC8& aElementLocalName );

    /**

     * @return const TDesC& Local name of this element.

     *

     * @since S60 v3.2

     */

    IMPORT_C const TDesC8& LocalName() const;

    /**

     * Gives the current sub parser of this sub parser if one has been set.

     * Sub parser is set when the element handling is forwarded to

     * a sub parser in OnStartElementL function. OnStartElementL function

     * of this class does it automatically. So, child classes can

     * use this functionality. NULL is returned if sub parser has

     * handled its job and OnEndElementL has been called for that

     * element.

     *

     * @return CIAUpdateXmlSubParser* Current sub parser or NULL if no

     * sub parser is in use. Ownerhsip is NOT transferred.

     *

     * @since S60 v3.2

     */

    IMPORT_C CIAUpdateXmlSubParser* CurrentSubParser() const;

    /**

     * This method can be used to get the array and

     * insert and remove sub parsers from it. 

     *

     * @return RPointerArray< CIAUpdateXmlSubParser >& Reference to the

     * sub parser array. 

     *

     * @since S60 v3.2

     */

    IMPORT_C RPointerArray< CIAUpdateXmlSubParser >& SubParsers();

    /**

     * Compares the tag information of the given object to the tag info 

     * of the main element of this parser.

     *

     * @note This default implementation compares only element local names.

     * The local name for this element is given in the ConstructL of 

     * this class. Child classes may implement their own functionality here.

     *

     * @note This value is used by OnStartElementL and OnEndElementL functions

     * when current subparser is checked for the given element.

     *

     * @param aElement Information about the element that has been gotten

     * from the XML parser.

     * @return TBool ETrue if tag infos match. 

     * EFalse if tag infos do not match. 

     *

     * @since S60 v3.2

     */

    IMPORT_C TBool ElementTagInfoEquals( const Xml::RTagInfo& aElement ) const;

    /**

     * This flag is used to check if this sub parser should handle the given element or content.

     * 

     * @return TBool If sub parser has forwarded the task to another sub parser 

     * or if the given element does not match the element of this sub parser, 

     * then this flag is EFalse. If this class object should handle the element and it

     * matches the element of this sub parser, then this flag is ETrue.

     *

     * @since S60 v3.2

     */

    IMPORT_C TBool AcceptData() const;    

    /**

     * This flag is used to check if this sub parser has handled its on starting element.

     * This is needed because sub element may have a same name with this element. So,

     * just name comparing is not enough.

     *

     * @return TBool ETrue if this sub parser has already handled its start element.

     * EFalse if this sub parser has not already handled its start element.

     *

     * @since S60 v3.2

     */

    IMPORT_C TBool IsElementStarted() const;

    /**

     * This flag is used to check if this sub parser has handled its on end element.

     * This is needed because sub element may have a same name with this element. So,

     * just name comparing is not enough.

     *

     * @return TBool ETrue if this sub parser has already handled its end element.

     * EFalse if this sub parser has not already handled its end element.

     *

     * @since S60 v3.2

     */

    IMPORT_C TBool IsElementEnded() const;

    /**

     * Informs how many unknown elements are in line with this parser.

     *

     * @return TInt Number of unknown elements that this parser have to handle

     * before new possible known elements can be handled.

     *

     * @since S60 v3.2

     */

    IMPORT_C TInt UnknownElementCounter() const;

private:

    // Prevent these if not implemented

    CIAUpdateXmlSubParser( const CIAUpdateXmlSubParser& aObject );

    CIAUpdateXmlSubParser& operator =( const CIAUpdateXmlSubParser& aObject );

private: // data

    // Local name of the element of this sub parser.

    HBufC8* iElementLocalName;

    // This array will contain other instances of the parsers that this

    // parser uses as subparsers. This way element hierarchy can be browsed

    // through.

    RPointerArray< CIAUpdateXmlSubParser > iSubParsers;    

    // iCurrentSubParser points to the subparser that this class object

    // forwards element handling to.

    // Notice, that the iSubParsers array has the ownership of the

    // subparsers. So, do not delete this object separately.

    // This is NULL if there is no current subparser in use.

    CIAUpdateXmlSubParser* iCurrentSubParser;

    // This flag is used to check if this sub parser should handle the given element or content.

    // If sub parser has given the task to another sub parser or if the given element does not

    // match the element of this sub parser, then this flag is EFalse.

    TBool iAcceptData;

    // This flag is used to check if this sub parser has handled its on starting element.

    // This is needed because sub element may have a same name with this element. So,

    // just name comparing is not enough.

    TBool iIsElementStarted;

    // This flag is used to check if this sub parser has handled its on ending element.

    // This is needed because sub element may have a same name with this element. So,

    // just name comparing is not enough.

    TBool iIsElementEnded;

    // Number of unknown elements that this parser have to handle

    // before new possible known elements can be handled.

    TInt iUnknownElementCounter;

    };

#endif // IA_UPDATE_XML_SUB_PARSER_H