1 /*

     2 * Copyright (c) 2005 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 the License "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:  Feeds parsers base class.

    15 *

    16 */

    17 

    18 

    19 #ifndef FEED_PARSER_H

    20 #define FEED_PARSER_H

    21 

    22 

    23 // INCLUDES

    24 #include <e32base.h>

    25 #include <xmlengdom.h>

    26 

    27 // CONSTANTS

    28 

    29 // MACROS

    30 

    31 // FORWARD DECLARATIONS

    32 class CFeedParser;

    33 class CXmlUtils;

    34 class RXmlEngDocument;

    35 class TXmlEngElement;

    36 class MFeedParserObserver;

    37 

    38 // DATA TYPES

    39 typedef void (*ElementHandlerFunctionL)(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

    40         TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);

    41 

    42 struct ElementHandlerMapEntry

    43     {

    44     TPtrC8                   iElementNamespace;

    45     TPtrC8                   iElementName;

    46     TInt                     iValueId;

    47     ElementHandlerFunctionL  iElementHandlerL;

    48     };

    49 

    50 // FUNCTION PROTOTYPES

    51 

    52 // CLASS DECLARATION

    53 

    54 

    55 /**

    56 *  Feeds parsers base class.

    57 *

    58 *  \b Library: FeedsEngine.lib

    59 *

    60 *  @since 3.0

    61 */

    62 class CFeedParser: public CBase

    63     {

    64     public:  // Destructor

    65         /**

    66         * Destructor.

    67         */        

    68         virtual ~CFeedParser();

    69         

    70         

    71     protected:

    72         /**

    73         * C++ default constructor.

    74         */

    75         CFeedParser(CXmlUtils& aXmlUtils);

    76 

    77 

    78     public:  // New Methods

    79         /**

    80         * Creates a Feed instance from the given document.

    81         *

    82         * @since 3.0

    83         * @param aDocument A document.

    84         * @param aObserver The parser's observer.

    85         * @return void

    86         */

    87         virtual void ParseFeedL(RXmlEngDocument aDocument,

    88                 MFeedParserObserver& aObserver) = 0;

    89 

    90         

    91     protected:  // New Methods

    92         /**

    93         * Add a feed ElementHandler mapping.  See AddMappingL.

    94         *

    95         * @since 3.0

    96         * @param aNamespace The namespace for this mapping -- utf8 encoding.

    97         * @param aElementName The element name for this mapping -- utf8 encoding.

    98         * @param aValueId The normalized value-id.

    99         * @param aHandler The element handler function.

   100         * @return void.

   101         */

   102         void AddFeedMappingL(const TDesC8& aNamespace, const TDesC8& aElementName,

   103                 TInt aValueId, ElementHandlerFunctionL aHandler);

   104 

   105         /**

   106         * Add a feed ElementHandler mapping.  See AddMappingL.

   107         *

   108         * @since 3.0

   109         * @param aNode A node.

   110         * @param aObserver The parser's observer.

   111         * @return void.

   112         */

   113         void HandleFeedChildL(TXmlEngElement aNode, MFeedParserObserver& aObserver) const;

   114         

   115         /**

   116         * Add a item ElementHandler mapping.  See AddMappingL.

   117         *

   118         * @since 3.0

   119         * @param aNamespace The namespace for this mapping -- utf8 encoding.

   120         * @param aElementName The element name for this mapping -- utf8 encoding.

   121         * @param aValueId The normalized value-id.

   122         * @param aHandler The element handler function.

   123         * @return void.

   124         */

   125         void AddItemMappingL(const TDesC8& aNamespace, const TDesC8& aElementName,

   126                 TInt aValueId, ElementHandlerFunctionL aHandler);

   127 

   128         /**

   129         * Add an item ElementHandler mapping.  See AddMappingL.

   130         *

   131         * @since 3.0

   132         * @param aNode A node.

   133         * @param aObserver The parser's observer.

   134         * @return void.

   135         */

   136         void HandleItemChildL(TXmlEngElement aNode, MFeedParserObserver& aObserver) const;

   137 

   138          /**

   139         * An ElementHandler function that extracts the value from the 

   140         * child text nodes.

   141         *

   142         * @since 3.0

   143         * @param aParser The parser calling this method.

   144         * @param aXmlUtils The xml util instance.

   145         * @param aNode A node.

   146         * @param aValueId The normalized value-id.

   147         * @param aObserver The parser's observer.

   148         * @return void.

   149         */

   150         static void ElementHandlerCDataL(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

   151                 TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);

   152 

   153          /**

   154         * An ElementHandler function that extracts the value from the 

   155         * child text nodes then resolves any html entities and removes any markup.

   156         *

   157         * @since 3.0

   158         * @param aParser The parser calling this method.

   159         * @param aXmlUtils The xml util instance.

   160         * @param aNode A node.

   161         * @param aValueId The normalized value-id.

   162         * @param aObserver The parser's observer.

   163         * @return void.

   164         */

   165         static void ElementHandlerTextL(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

   166                 TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);

   167 

   168         /**

   169         * An ElementHandler function that extracts the value from a child

   170         * url element.  If the element doesn't contain any elements and it contains

   171         * text it is extracted instead.

   172         *

   173         * @since 3.0

   174         * @param aParser The parser calling this method.

   175         * @param aXmlUtils The xml util instance.

   176         * @param aNode A node.

   177         * @param aValueId The normalized value-id.

   178         * @param aObserver The parser's observer.

   179         * @return void.

   180         */

   181         static void ElementHandlerUrlChildL(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

   182                 TXmlEngElement aNode,  TInt aValueId, MFeedParserObserver& aObserver);

   183 

   184         /**

   185         * An ElementHandler function that extracts the value from the 

   186         * child text nodes.  It further performs url related clean up.

   187         *

   188         * @since 3.0

   189         * @param aParser The parser calling this method.

   190         * @param aXmlUtils The xml util instance.

   191         * @param aNode A node.

   192         * @param aValueId The normalized value-id.

   193         * @param aObserver The parser's observer.

   194         * @return void.

   195         */

   196         static void ElementHandlerUrlL(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

   197                 TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);

   198             

   199         /**

   200         * An ElementHandler function that extracts the date from the 

   201         * child text nodes.  It can handle date formats defined in RFC 3339, RFC 822,

   202         * RFC 1123, RFC 850, and RFC 1036

   203         *

   204         * @since 3.0

   205         * @param aParser The parser calling this method.

   206         * @param aXmlUtils The xml util instance.

   207         * @param aNode A node.

   208         * @param aValueId The normalized value-id.

   209         * @param aObserver The parser's observer.

   210         * @return void.

   211         */

   212         static void ElementHandlerDateL(const CFeedParser& aParser, CXmlUtils& aXmlUtils, 

   213                 TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);

   214             

   215                             

   216     private:  // New Methods

   217         /**

   218         * Makes a mapping between an element's namespance and name with the normalized

   219         * value-id (i.e. title or description) and a function which extracts out

   220         * relevant data and applies it to a provided ValueHolder using the value-id 

   221         * (see HandleChildL).

   222         *

   223         * @since 3.0

   224         * @param aMappings Either iFeedMappings or iItemMapping.

   225         * @param aNamespace The namespace for this mapping.

   226         * @param aElementName The element name for this mapping.

   227         * @param aValueId The normalized value-id.

   228         * @param aHandler The element handler function.

   229         * @return void.

   230         */

   231         void AddMappingL(RArray<ElementHandlerMapEntry>& aMappings, const TDesC8& aNamespace, 

   232                 const TDesC8& aElementName, TInt aValueId, ElementHandlerFunctionL aHandler);

   233 

   234         /**

   235         * Using the mapping defined by calls to AddMappingL it passes aNode, 

   236         * aValueHolder and associated value-id to the associated function.  The method

   237         * does what is needed to extract the relevant values from the node and applies

   238         * them on aValueHolder (using the normalized value-id).

   239         *

   240         * @since 3.0

   241         * @param aMappings Either iFeedMappings or iItemMapping.

   242         * @param aNode A node.

   243         * @param aObserver The parser's observer.

   244         * @return void.

   245         */

   246         void HandleChildL(const RArray<ElementHandlerMapEntry>& aMappings, TXmlEngElement aNode, 

   247                 MFeedParserObserver& aObserver) const;

   248 

   249         /**

   250         * Converts the given RFC 3339 date into a TTime.

   251         *

   252         * @since 3.1

   253         * @param aDateStr The date string.

   254         * @param aDate The resulting TTime.

   255         * @return void.

   256         */

   257         static void ParseRFC3339L(const TDesC8& aDateStr, TTime& aDate);

   258 

   259     

   260     private:  // Data

   261         RArray<ElementHandlerMapEntry> iFeedMappings;

   262         RArray<ElementHandlerMapEntry> iItemMappings;

   263         

   264         

   265     protected:  // Data

   266         CXmlUtils&                     iXmlUtils;

   267     };

   268 

   269 #endif      // FEED_PARSER_H

   270             

   271 // End of File