1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   ?Description

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef IA_UPDATE_XML_SUB_PARSER_H

    21 #define IA_UPDATE_XML_SUB_PARSER_H

    22 

    23 

    24 #include <e32base.h>

    25 #include <e32cmn.h>

    26 #include <xml/contenthandler.h>

    27 #include <f32file.h>

    28 

    29 

    30 /**

    31  * CIAUpdateXmlSubParser is the parent class 

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

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

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

    35  * must be created to finalize the functionality.

    36  *

    37  * @since S60 v3.2

    38  */

    39 class CIAUpdateXmlSubParser : public CBase,

    40                               public Xml::MContentHandler

    41     {

    42 

    43 public:

    44     

    45     /**

    46      * Destructor

    47      *

    48      * @since S60 v3.2

    49      */

    50     IMPORT_C virtual ~CIAUpdateXmlSubParser();

    51 

    52 

    53 public: // Xml::MContentHandler

    54 

    55     /**

    56      * @see Xml::MContentHandler::OnStartDocumentL

    57      *

    58      * Initializes this sub parser and its sub parsers. 

    59      *

    60      * @since S60 v3.2

    61      */

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

    63                                             TInt aErrorCode );

    64                                    

    65     /**

    66      * @see Xml::MContentHandler::OnEndDocumentL

    67      *

    68      * This contains only an empty implementation. Child classes may

    69      * provide their own implemenations if necessary.

    70      *

    71      * @since S60 v3.2

    72      */

    73     IMPORT_C virtual void OnEndDocumentL( TInt aErrorCode );

    74                                    

    75     /**

    76      * @see Xml::MContentHandler::OnStartElementL

    77      *

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

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

    80      * ElementTagInfoEquals function is used for comparison. 

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

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

    83      * The forwarding makes it possible to create a structural element

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

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

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

    87      *

    88      * Child classes may provide their own implemenations if necessary.

    89      *

    90      * @since S60 v3.2

    91      */    

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

    93                                            const Xml::RAttributeArray& aAttributes, 

    94                                            TInt aErrorCode );

    95                                    

    96     /**

    97      * @see Xml::MContentHandler::OnEndElementL

    98      *

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

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

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

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

   103      * handling elements is given back to this class object.

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

   105      *

   106      * Child classes may provide their own implemenations if necessary.

   107      *

   108      * @since S60 v3.2

   109      */                                  

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

   111                                          TInt aErrorCode );

   112                                    

   113     /**

   114      * @see Xml::MContentHandler::OnContentL

   115      *

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

   117      * is forwarded to the sub parser.

   118      *

   119      * Child classes may provide their own implemenations if necessary.

   120      *

   121      * @since S60 v3.2

   122      */                                

   123     IMPORT_C virtual void OnContentL( const TDesC8& aBytes, 

   124                                       TInt aErrorCode );

   125                                    

   126     /**

   127      * @see Xml::MContentHandler::OnStartPrefixMappingL

   128      *

   129      * This contains only an empty implementation. Child classes may

   130      * provide their own implemenations if necessary.

   131      *

   132      * @since S60 v3.2

   133      */                             

   134     IMPORT_C virtual void OnStartPrefixMappingL( const RString& aPrefix, 

   135                                                  const RString& aUri, 

   136                                                  TInt aErrorCode);

   137                                    

   138     /**

   139      * @see Xml::MContentHandler::OnEndPrefixMappingL

   140      *

   141      * This contains only an empty implementation. Child classes may

   142      * provide their own implemenations if necessary.

   143      *

   144      * @since S60 v3.2

   145      */                                        

   146     IMPORT_C virtual void OnEndPrefixMappingL( const RString& aPrefix, 

   147                                                TInt aErrorCode );

   148                                    

   149     /**

   150      * @see Xml::MContentHandler::OnIgnorableWhiteSpaceL

   151      *

   152      * This contains only an empty implementation. Child classes may

   153      * provide their own implemenations if necessary.

   154      *

   155      * @since S60 v3.2

   156      */    

   157     IMPORT_C virtual void OnIgnorableWhiteSpaceL( const TDesC8& aBytes, 

   158                                                   TInt aErrorCode );

   159                                    

   160     /**

   161      * @see Xml::MContentHandler::OnSkippedEntityL

   162      *

   163      * This contains only an empty implementation. Child classes may

   164      * provide their own implemenations if necessary.

   165      *

   166      * @since S60 v3.2

   167      */    

   168     IMPORT_C virtual void OnSkippedEntityL( const RString& aName, 

   169                                             TInt aErrorCode );

   170                                    

   171     /**

   172      * @see Xml::MContentHandler::OnProcessingInstructionL

   173      *

   174      * This contains only an empty implementation. Child classes may

   175      * provide their own implemenations if necessary.

   176      *

   177      * @since S60 v3.2

   178      */    

   179     IMPORT_C virtual void OnProcessingInstructionL( const TDesC8& aTarget, 

   180                                                     const TDesC8& aData, 

   181                                                     TInt aErrorCode );

   182                                    

   183     /**

   184      * @see Xml::MContentHandler::OnError

   185      *

   186      * This contains only an empty implementation. Child classes may

   187      * provide their own implemenations if necessary.

   188      *

   189      * @since S60 v3.2

   190      */

   191     IMPORT_C virtual void OnError( TInt aErrorCode );

   192                                    

   193     /**

   194      * @see Xml::MContentHandler::GetExtendedInterface

   195      *

   196      * This contains only an empty implementation. Child classes may

   197      * provide their own implemenations if necessary.

   198      *

   199      * @since S60 v3.2

   200      */    

   201     IMPORT_C virtual TAny* GetExtendedInterface( const TInt32 aUid );

   202 

   203 

   204 protected:

   205     

   206     /**

   207      * Constructor

   208      *

   209      * @since S60 v3.2

   210      */

   211     IMPORT_C CIAUpdateXmlSubParser();

   212     

   213     /**

   214      * 2nd. phase constructor.

   215      *

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

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

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

   219      *

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

   221      * element that this parser is for. ElementTagInfoEquals function uses

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

   223      * that the platform XML parser gives.

   224      *

   225      * @since S60 v3.2

   226      */

   227     IMPORT_C virtual void ConstructL( const TDesC8& aElementLocalName );

   228 

   229     

   230     /**

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

   232      *

   233      * @since S60 v3.2

   234      */

   235     IMPORT_C const TDesC8& LocalName() const;

   236 

   237 

   238     /**

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

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

   241      * a sub parser in OnStartElementL function. OnStartElementL function

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

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

   244      * handled its job and OnEndElementL has been called for that

   245      * element.

   246      *

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

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

   249      *

   250      * @since S60 v3.2

   251      */

   252     IMPORT_C CIAUpdateXmlSubParser* CurrentSubParser() const;

   253 

   254 

   255     /**

   256      * This method can be used to get the array and

   257      * insert and remove sub parsers from it. 

   258      *

   259      * @return RPointerArray< CIAUpdateXmlSubParser >& Reference to the

   260      * sub parser array. 

   261      *

   262      * @since S60 v3.2

   263      */

   264     IMPORT_C RPointerArray< CIAUpdateXmlSubParser >& SubParsers();

   265     

   266     

   267     /**

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

   269      * of the main element of this parser.

   270      *

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

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

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

   274      *

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

   276      * when current subparser is checked for the given element.

   277      *

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

   279      * from the XML parser.

   280      * @return TBool ETrue if tag infos match. 

   281      * EFalse if tag infos do not match. 

   282      *

   283      * @since S60 v3.2

   284      */

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

   286 

   287 

   288     /**

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

   290      * 

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

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

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

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

   295      *

   296      * @since S60 v3.2

   297      */

   298     IMPORT_C TBool AcceptData() const;    

   299     

   300 

   301     /**

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

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

   304      * just name comparing is not enough.

   305      *

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

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

   308      *

   309      * @since S60 v3.2

   310      */

   311     IMPORT_C TBool IsElementStarted() const;

   312 

   313 

   314     /**

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

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

   317      * just name comparing is not enough.

   318      *

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

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

   321      *

   322      * @since S60 v3.2

   323      */

   324     IMPORT_C TBool IsElementEnded() const;

   325 

   326 

   327     /**

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

   329      *

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

   331      * before new possible known elements can be handled.

   332      *

   333      * @since S60 v3.2

   334      */

   335     IMPORT_C TInt UnknownElementCounter() const;

   336 

   337 

   338 private:

   339     

   340     // Prevent these if not implemented

   341     CIAUpdateXmlSubParser( const CIAUpdateXmlSubParser& aObject );

   342     CIAUpdateXmlSubParser& operator =( const CIAUpdateXmlSubParser& aObject );

   343 

   344 

   345 private: // data

   346 

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

   348     HBufC8* iElementLocalName;

   349 

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

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

   352     // through.

   353     RPointerArray< CIAUpdateXmlSubParser > iSubParsers;    

   354     

   355     // iCurrentSubParser points to the subparser that this class object

   356     // forwards element handling to.

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

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

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

   360     CIAUpdateXmlSubParser* iCurrentSubParser;

   361     

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

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

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

   365     TBool iAcceptData;

   366 

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

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

   369     // just name comparing is not enough.

   370     TBool iIsElementStarted;

   371 

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

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

   374     // just name comparing is not enough.

   375     TBool iIsElementEnded;

   376     

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

   378     // before new possible known elements can be handled.

   379     TInt iUnknownElementCounter;

   380     };

   381 

   382 #endif // IA_UPDATE_XML_SUB_PARSER_H

   383