/*
* Copyright (c) 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 "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: Feeds parsers base class.
*
*/
#ifndef FEED_PARSER_H
#define FEED_PARSER_H
// INCLUDES
#include <e32base.h>
#include <xmlengdom.h>
// CONSTANTS
// MACROS
// FORWARD DECLARATIONS
class CFeedParser;
class CXmlUtils;
class RXmlEngDocument;
class TXmlEngElement;
class MFeedParserObserver;
// DATA TYPES
typedef void (*ElementHandlerFunctionL)(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
struct ElementHandlerMapEntry
{
TPtrC8 iElementNamespace;
TPtrC8 iElementName;
TInt iValueId;
ElementHandlerFunctionL iElementHandlerL;
};
// FUNCTION PROTOTYPES
// CLASS DECLARATION
/**
* Feeds parsers base class.
*
* \b Library: FeedsEngine.lib
*
* @since 3.0
*/
class CFeedParser: public CBase
{
public: // Destructor
/**
* Destructor.
*/
virtual ~CFeedParser();
protected:
/**
* C++ default constructor.
*/
CFeedParser(CXmlUtils& aXmlUtils);
public: // New Methods
/**
* Creates a Feed instance from the given document.
*
* @since 3.0
* @param aDocument A document.
* @param aObserver The parser's observer.
* @return void
*/
virtual void ParseFeedL(RXmlEngDocument aDocument,
MFeedParserObserver& aObserver) = 0;
protected: // New Methods
/**
* Add a feed ElementHandler mapping. See AddMappingL.
*
* @since 3.0
* @param aNamespace The namespace for this mapping -- utf8 encoding.
* @param aElementName The element name for this mapping -- utf8 encoding.
* @param aValueId The normalized value-id.
* @param aHandler The element handler function.
* @return void.
*/
void AddFeedMappingL(const TDesC8& aNamespace, const TDesC8& aElementName,
TInt aValueId, ElementHandlerFunctionL aHandler);
/**
* Add a feed ElementHandler mapping. See AddMappingL.
*
* @since 3.0
* @param aNode A node.
* @param aObserver The parser's observer.
* @return void.
*/
void HandleFeedChildL(TXmlEngElement aNode, MFeedParserObserver& aObserver) const;
/**
* Add a item ElementHandler mapping. See AddMappingL.
*
* @since 3.0
* @param aNamespace The namespace for this mapping -- utf8 encoding.
* @param aElementName The element name for this mapping -- utf8 encoding.
* @param aValueId The normalized value-id.
* @param aHandler The element handler function.
* @return void.
*/
void AddItemMappingL(const TDesC8& aNamespace, const TDesC8& aElementName,
TInt aValueId, ElementHandlerFunctionL aHandler);
/**
* Add an item ElementHandler mapping. See AddMappingL.
*
* @since 3.0
* @param aNode A node.
* @param aObserver The parser's observer.
* @return void.
*/
void HandleItemChildL(TXmlEngElement aNode, MFeedParserObserver& aObserver) const;
/**
* An ElementHandler function that extracts the value from the
* child text nodes.
*
* @since 3.0
* @param aParser The parser calling this method.
* @param aXmlUtils The xml util instance.
* @param aNode A node.
* @param aValueId The normalized value-id.
* @param aObserver The parser's observer.
* @return void.
*/
static void ElementHandlerCDataL(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
/**
* An ElementHandler function that extracts the value from the
* child text nodes then resolves any html entities and removes any markup.
*
* @since 3.0
* @param aParser The parser calling this method.
* @param aXmlUtils The xml util instance.
* @param aNode A node.
* @param aValueId The normalized value-id.
* @param aObserver The parser's observer.
* @return void.
*/
static void ElementHandlerTextL(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
/**
* An ElementHandler function that extracts the value from a child
* url element. If the element doesn't contain any elements and it contains
* text it is extracted instead.
*
* @since 3.0
* @param aParser The parser calling this method.
* @param aXmlUtils The xml util instance.
* @param aNode A node.
* @param aValueId The normalized value-id.
* @param aObserver The parser's observer.
* @return void.
*/
static void ElementHandlerUrlChildL(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
/**
* An ElementHandler function that extracts the value from the
* child text nodes. It further performs url related clean up.
*
* @since 3.0
* @param aParser The parser calling this method.
* @param aXmlUtils The xml util instance.
* @param aNode A node.
* @param aValueId The normalized value-id.
* @param aObserver The parser's observer.
* @return void.
*/
static void ElementHandlerUrlL(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
/**
* An ElementHandler function that extracts the date from the
* child text nodes. It can handle date formats defined in RFC 3339, RFC 822,
* RFC 1123, RFC 850, and RFC 1036
*
* @since 3.0
* @param aParser The parser calling this method.
* @param aXmlUtils The xml util instance.
* @param aNode A node.
* @param aValueId The normalized value-id.
* @param aObserver The parser's observer.
* @return void.
*/
static void ElementHandlerDateL(const CFeedParser& aParser, CXmlUtils& aXmlUtils,
TXmlEngElement aNode, TInt aValueId, MFeedParserObserver& aObserver);
private: // New Methods
/**
* Makes a mapping between an element's namespance and name with the normalized
* value-id (i.e. title or description) and a function which extracts out
* relevant data and applies it to a provided ValueHolder using the value-id
* (see HandleChildL).
*
* @since 3.0
* @param aMappings Either iFeedMappings or iItemMapping.
* @param aNamespace The namespace for this mapping.
* @param aElementName The element name for this mapping.
* @param aValueId The normalized value-id.
* @param aHandler The element handler function.
* @return void.
*/
void AddMappingL(RArray<ElementHandlerMapEntry>& aMappings, const TDesC8& aNamespace,
const TDesC8& aElementName, TInt aValueId, ElementHandlerFunctionL aHandler);
/**
* Using the mapping defined by calls to AddMappingL it passes aNode,
* aValueHolder and associated value-id to the associated function. The method
* does what is needed to extract the relevant values from the node and applies
* them on aValueHolder (using the normalized value-id).
*
* @since 3.0
* @param aMappings Either iFeedMappings or iItemMapping.
* @param aNode A node.
* @param aObserver The parser's observer.
* @return void.
*/
void HandleChildL(const RArray<ElementHandlerMapEntry>& aMappings, TXmlEngElement aNode,
MFeedParserObserver& aObserver) const;
/**
* Converts the given RFC 3339 date into a TTime.
*
* @since 3.1
* @param aDateStr The date string.
* @param aDate The resulting TTime.
* @return void.
*/
static void ParseRFC3339L(const TDesC8& aDateStr, TTime& aDate);
private: // Data
RArray<ElementHandlerMapEntry> iFeedMappings;
RArray<ElementHandlerMapEntry> iItemMappings;
protected: // Data
CXmlUtils& iXmlUtils;
};
#endif // FEED_PARSER_H
// End of File