xml/xmlfw/src/xmlframework/parser.cpp
changeset 0 e35f40988205
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/xmlfw/src/xmlframework/parser.cpp	Thu Dec 17 09:29:21 2009 +0200
@@ -0,0 +1,507 @@
+// Copyright (c) 2003-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:
+//
+
+#include <f32file.h>
+
+#include <xml/parser.h>
+#include <xml/matchdata.h>
+
+#include "parserimpl.h"
+
+
+using namespace Xml;
+
+
+CParser::CParser() : CBase() , iImpl(0)
+	{
+	}
+
+/**  This method creates a parser that is ready to parse documents 
+of the specified mime type.
+
+If there are multiple parser plugins in the system which can parse the 
+mime type, the XML framework will choose a parser. 
+
+The criteria used to choose a parser, from many matching parsers, is as follows:
+
+- A Symbian-supplied parser (with variant field set to "Symbian") will be selected by default. 
+If there are multiple Symbian-supplied parsers, the one with the lowest Uid will be selected. 
+Otherwise, the non-Symbian parser with the lowest Uid will be selected.
+
+@return	A constructed parser
+
+@param	aParserMimeType The mime type of the documents to parse (e.g. "txt/xml").
+@param	aCallback 		The handler for parser generated events.
+
+@leave KErrNoMemory If there is not enough memory to create parser or
+					one of system wide error codes. 
+					
+@leave KErrXmlParserPluginNotFound
+					If Xml framework is unable to find a parser 	
+					based on data provided in aParserMimeType.
+					
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@see CParser::NewL(const CMatchData& aCriteria, MContentHandler& aCallback)
+*/
+EXPORT_C CParser* CParser::NewL(const TDesC8& aParserMimeType, MContentHandler& aCallback)
+	{
+	CParser* self=NewLC(aParserMimeType, aCallback);
+	CleanupStack::Pop(self);
+	return self;
+	}
+
+/**  This method is similar to NewL, but leaves the created parser on the
+cleanup stack.
+
+@return	A constructed parser
+
+@param	aParserMimeType The mime type of the documents to parse (e.g. "txt/xml").
+@param	aCallback 		The handler for parser generated events.
+
+@leave KErrNoMemory If there is not enough memory to create parser or 
+					one of system wide error codes. 
+					
+@leave KErrXmlParserPluginNotFound
+					If Xml framework is unable to find a parser 	
+					based on data provided in aParserMimeType.
+		
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@see CParser::NewL(const TDesC8& aParserMimeType, MContentHandler& aCallback)		
+@see CParser::NewLC(const CMatchData& aCriteria, MContentHandler& aCallback)					
+*/
+EXPORT_C CParser* CParser::NewLC(const TDesC8& aParserMimeType, MContentHandler& aCallback)
+	{
+	CParser* self = new (ELeave) CParser;
+	CleanupStack::PushL(self);
+	self->ConstructL(aParserMimeType, aCallback);
+	return self;
+	}
+		
+/**  
+This method constructs the object with default settings
+
+@param aParserMimeType Parser Mime type
+@param aCallback Event handler
+
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@internalComponent
+*/
+		
+void CParser::ConstructL(const TDesC8& aParserMimeType, MContentHandler& aCallback)
+	{
+	// create parser implementaion class if or created yet. 
+	if (!iImpl)
+		{
+		iImpl = new (ELeave) TParserImpl;
+		}
+		
+	// create CMatchData object with default parameters and adequate mime type
+	CMatchData* matchData = CMatchData::NewLC();
+	matchData->SetMimeTypeL(aParserMimeType);
+	iImpl->OpenL(*matchData, aCallback);
+	CleanupStack::PopAndDestroy(matchData);
+	} 
+
+/**  
+This method constructs the object according to the details specified in CMatchData object
+
+@param aMatchData Detailed parser information 
+@param aCallback Event handler
+
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@internalComponent
+*/
+void CParser::ConstructL(const CMatchData& aMatchData, MContentHandler& aCallback)
+	{
+	if (!iImpl)
+		{
+		iImpl = new (ELeave) TParserImpl;
+		}
+	iImpl->OpenL(aMatchData, aCallback);
+	}
+	
+/**  This method is the destructor for the object.*/
+CParser::~CParser()
+	{
+	if (iImpl)
+		{
+		iImpl->Close();
+		delete iImpl;
+		iImpl = NULL;
+		}
+	}
+
+
+const TUint  KDefChunkSize				= 0x100;
+
+
+/** 
+This convenience Xml function may be used to parse the file named in aFilename 
+using the supplied parser. It reads the file in chunks and passes these to 
+CParser::ParseL(). When the end of file is reach CParser::ParseEndL() is called.
+It assumes the caller has successfully created a valid parser with a valid
+MContentHandler reference and has called ParserBeginL().
+
+@param aParser   A valid CParser object to perform the parsing which has 
+                 already had ParseBeginL() called.
+@param aFs       The file server session to use
+@param aFilename The filename of the file to open, read and parse
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void Xml::ParseL(CParser& aParser, RFs& aFs, const TDesC& aFilename)
+	{
+	RFile file;
+	
+	User::LeaveIfError(file.Open(aFs, aFilename, EFileRead|EFileShareReadersOnly));
+	CleanupClosePushL(file);
+	
+	TBuf8<KDefChunkSize> data;
+	User::LeaveIfError(file.Read(data,:: KDefChunkSize));
+	TUint length = data.Length();
+
+	while (length)
+		{
+		aParser.ParseL(data);
+		User::LeaveIfError(file.Read(data, KDefChunkSize));
+		length = data.Length();
+		}
+	aParser.ParseEndL();
+	CleanupStack::PopAndDestroy(&file);
+	}
+
+/** 
+This convenience Xml function may be used to parse the file held in aFile 
+using the supplied parser. It reads the file in chunks and passes these to 
+CParser::ParseL(). When the end of file is reach CParser::ParseEndL() is called.
+It assumes the caller has successfully created a valid parser with a valid
+MContentHandler reference and has called ParserBeginL().
+
+@param aParser   A valid CParser object to perform the parsing which has 
+                 already had ParseBeginL() called.
+@param aFilename Open file handle to the file to read and parse
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void Xml::ParseL(CParser& aParser, RFile& aFile)
+	{
+	TBuf8<KDefChunkSize> data;
+	User::LeaveIfError(aFile.Read(data,:: KDefChunkSize));
+	TUint length = data.Length();
+
+	while (length)
+		{
+		aParser.ParseL(data);
+		User::LeaveIfError(aFile.Read(data, KDefChunkSize));
+		length = data.Length();
+		}
+	aParser.ParseEndL();
+	} 
+
+/** 
+This convenience Xml function may be used to parse the XML document held in a
+descriptor in memory using the supplied parser. This variant function does call 
+ParseBeginL() to reset the parser to the default parser as selected for the 
+mime type given at creation time. It passes the entire descriptor into  
+CParser::ParseL(). When this returns it calls CParser::ParseEndL().
+It assumes the caller has successfully created a valid parser with a valid
+MContentHandler reference.
+
+This API can be used when parsing different kinds of documents with
+the majority being parsed associated with the default parser/mime type.
+
+@param aParser   A valid CParser object to perform the parsing
+@param aContent  The entire XML document content to parse
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void Xml::ParseL(CParser& aParser, const TDesC8& aContent)
+	{
+	aParser.ParseBeginL(); // resets to default mime type
+	aParser.ParseL(aContent);
+	aParser.ParseEndL();
+	}
+
+
+/** This method tells the parser that we're going to start parsing a document
+using the parser associated with this mime type.
+
+@param aDocumentMimeType the mime type of the document
+*/
+EXPORT_C void CParser::ParseBeginL(const TDesC8& aDocumentMimeType)
+	{
+	// create CMatchData object with default parameters and adequate mime type
+	CMatchData* matchData = CMatchData::NewLC();
+	matchData->SetMimeTypeL(aDocumentMimeType);
+	iImpl->SetMimeTypeL(*matchData);
+	CleanupStack::PopAndDestroy();
+	}
+
+/** This method tells the parser that we're going to start parsing a document 
+using the default mime type specified on construction.
+
+The processor chain and features will be cleared if the parser currently 
+set is not the default, all old features are removed as these generally 
+have no meaning between parsers.
+
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void CParser::ParseBeginL()
+	{
+	iImpl->ResetMimeTypeL();
+	}
+
+
+/** This method tells the parser to parse a fragment of a document. 
+Could be the whole document. ParseEndL should be called once the whole document has
+been parsed. 
+
+The parser currently set will be used.
+
+@param aFragment the fragment to parse
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void CParser::ParseL(const TDesC8& aFragment)
+	{
+	iImpl->ParseChunkL(aFragment);
+	}
+
+
+/** This method tells the parser that we've finished parsing the current document
+and should be called after calling CParser::ParseL for the final time,
+as this will initiate error callbacks via MContentHandler, and clean up memory
+where appropriate, should an error have occured during the parsing process.
+Such an error could occur when trying to parse a truncated document.
+@leave ...       One of the system wide error codes or one of the Xml 
+                 specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void CParser::ParseEndL()
+	{
+	iImpl->ParseLastChunkL(_L8(""));
+	}
+	
+	
+	
+/** This method changes the client and plugin chain.
+
+@param			aCallback the client at the end of the callback
+				chain that is to receive the parsed document information.
+@param			aPlugins a list of plugin implementation uids that
+				make up the callback chain.
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void CParser::SetProcessorChainL(const RContentProcessorUids& aPlugins)
+	{
+	iImpl->SetProcessorChainL(aPlugins);
+	}	
+	
+	
+/** This method enables a specific feature of the parser.
+
+@return KErrNone if successful, KErrNotSupported if the parser doesn't support the feature.
+@param aParserFeature The parser feature that must be enabled.
+@see TParserFeature
+*/
+EXPORT_C TInt CParser::EnableFeature(TInt aParserFeature)
+	{
+	return iImpl->EnableFeature(aParserFeature);
+	}
+
+/** This method disables a specific feature of the parser.
+
+@return	KErrNone if successful, KErrNotSupported if the feature can't be disabled.
+@param aParserFeature The parser feature that must be disabled.
+@see TParserFeature 
+*/
+EXPORT_C TInt CParser::DisableFeature(TInt aParserFeature)
+	{
+	return iImpl->DisableFeature(aParserFeature);
+	}
+
+/** This method tell whether a specific feature of the parser is enabled.
+@return	True if the feature is enabled.
+@see				TParserFeature 
+*/
+EXPORT_C TBool CParser::IsFeatureEnabled(TInt aParserFeature) const
+	{
+	return iImpl->IsFeatureEnabled(aParserFeature);
+	}
+
+
+
+/** This method preloads a string dictionary prior to parsing.
+
+@param			aPublicId  the public identifier representing the 
+				document dtd. 
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+*/
+EXPORT_C void CParser::AddPreloadedDictionaryL(const TDesC8& aPublicId)
+	{
+	iImpl->AddPreloadedDictionaryL(aPublicId);
+	}
+	
+
+
+/** This method obtains a handle to the current string pool.
+
+@return				handle to the current string pool.
+*/
+EXPORT_C RStringPool& CParser::StringPool()
+	{
+	return iImpl->StringPool();
+	}
+
+
+/** This method obtains a handle to the current StringDictionaryCollection.
+
+@return				handle to the current StringDictionaryCollection.
+*/
+EXPORT_C RStringDictionaryCollection& CParser::StringDictionaryCollection()
+	{
+	return iImpl->StringDictionaryCollection();
+	}
+
+
+/**  This method creates the particular parser specified in CMatchData parameter.
+
+The parser plugin resolution process is based on mime type and variant field. 
+Both are provided in CMatchData parameter. Mime Type is a mandatory string 
+for the resolution process and it is matched against the data field of plugin resource files. 
+Variant string is optional. If it exists, it is matched against the first entry 
+of the opaque data field of plugin resource files. 	
+	
+If the query is narrowed down to many parsers, the XML framework might either leave with 
+an error (KErrXmlMoreThanOneParserMatched), or choose a parser. The behaviour is specified 
+by LeaveOnMany flag. The default value of the flag is FALSE ('choose a parser' behaviour). 
+
+The criteria used to choose a parser, from many matching parsers, is as follows:
+	
+- If the optional Variant field is specified, the XML framework will choose the parser with
+the lowest Uid from the list. 
+
+- If the optional Variant field is not specified, a Symbian-supplied parser (with variant 
+field set to "Symbian") will be selected by default. If there are multiple Symbian-supplied 
+parsers, the one with the lowest Uid will be selected. Otherwise, the non-Symbian parser 
+with the lowest Uid will be selected.
+
+Case sensitivity of the string matching process is applied according to the relevant flag 
+in CMatchData. 
+The default value is TRUE (Case Sensitivity enabled). 
+
+Only ROM-based parsers are returned if the relevant flag is set in CMatchData.
+The default value is FALSE (all parsers are considered).
+	
+@return	A constructed parser
+
+@param	aCriteria 	The specific information about required parser 
+					(mime type, variant data).
+@param	aCallback 	The xml/wbxml event handler.
+
+@leave KErrNoMemory If there is not enough memory to create parser or 
+					one of system wide error codes. 
+
+@leave KErrXmlParserPluginNotFound 	
+					If Xml framework is unable to find a parser 	
+					based on data provided in CMatchData.
+								
+@leave KErrXmlMoreThanOneParserMatched 	
+					If Xml framework narrowed down the query 
+					to many parsers and a user requested to leave 
+					in such case (LeaveOnMany flag set). 
+
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@see CMatchData
+*/
+EXPORT_C CParser* CParser::NewL(const CMatchData& aCriteria, MContentHandler& aCallback)
+	{
+	CParser* me = CParser::NewLC(aCriteria, aCallback);
+	CleanupStack::Pop(me);
+	return me;
+	}
+	
+/** This method creates the particular parser specified in CMatchData parameter.
+It performs the same way as NewL with the exception that it leaves the object 
+on the cleanup stack. 
+
+@return	A constructed parser
+
+@param	aCriteria 	The specific information about required parser 
+					(mime type, version, variant data).
+@param	aCallback 	The xml/wbxml event handler.
+
+@leave KErrNoMemory If there is not enough memory to create parser or 
+					one of system wide error codes. 
+
+@leave KErrXmlParserPluginNotFound 	
+					If Xml framework is unable to find a parser 	
+					based on data provided in CMatchData.
+								
+@leave KErrXmlMoreThanOneParserMatched 	
+					If Xml framework narrowed down the query 
+					to many parsers and a user requested to leave 
+					in such case (LeaveOnMany flag set). 
+
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@see CParser::NewL(const CMatchData& aCriteria, MContentHandler& aCallback)
+@see CMatchData
+*/
+EXPORT_C CParser* CParser::NewLC(const CMatchData& aCriteria, MContentHandler& aCallback)
+	{
+	CParser* me = new (ELeave) CParser();
+	CleanupStack::PushL(me);
+	me->ConstructL(aCriteria, aCallback);
+	return me;
+	}
+
+/** This method tells the parser that we're going to start parsing a document
+using the parser associated with given CMatchData criteria.
+
+@param aCriteria 		The specific information about required parser 
+					(mime type, version, variant data).
+
+
+@leave KErrNoMemory 	If there is not enough memory to create parser.
+
+@leave KErrArgument 	If the data specified in CMatchData are not sufficient.
+
+@leave KErrXmlParserPluginNotFound 	
+					If Xml framework is unable to find a parser 	
+					based on data provided in CMatchData.
+								
+@leave KErrXmlMoreThanOneParserMatched 	
+					If Xml framework narrowed down the query 
+					to many parsers and a user requested to leave 
+					in such case (LeaveOnMany flag set). 
+					
+@leave ...      One of the system wide error codes or one of the Xml 
+                specific ones defined in XmlFrameworkErrors.h
+@see CMatchData					
+*/
+EXPORT_C void CParser::ParseBeginL(const CMatchData& aCriteria)
+	{
+	iImpl->SetMimeTypeL(aCriteria);
+	}
+
+