Choosing a Parser Plug-in

Introduction

XML framework contains several parser plug-ins for a particular MIME type. XML framework provides further criteria to allow the Symbian developers to choose the suitable parser plug-in. This is useful for interoperability, porting open source and performance.

There are two ways of choosing a parser plug-in; in both cases, the MIME type of the file to be parsed must be known. Each implementation of plug-in parser is described by two string-based attributes in the parser’s plug-in registration information:

• MIME type - Specifies the MIME types supported by that implementation of plug-in parser.

• Variant identifier (optional) - Specifies the parser’s variant identifier (ID) string. The framework does not provide interpretation on the string to be placed. However, the parser provider must publish which variant ID must be used with the XML framework, so that their particular parser implementation is instantiated.

This functionality is provided in XML::CMatchData class which is supplied to three API methods (NewL, NewLC, and ParseBginL) of the XML::CParser class.

Call the constructor method of a CParser object with the MIME type as a parameter. However, specify a particular parser variant (usually identified by the name of its supplier) as described in the Procedure section.

Procedure

Follow the procedure given below to choose a parser plug-in and parse the XML:

1. Construct a CMatchData object, and set the data about the files and parser variant to it.

   // Create CMatchData object
   CMatchData *matchData = CMatchData::NewLC();
   
   // Set Type
   matchData->SetMimeTypeL( _LIT( “text/xml” ) );
   
   // Set variant string
   matchData->SetVariantL( _LIT( “LicenseeX” ) );
   

2. Construct an instance of a parser plug-in and pass the CMatchData object to its constructor method.

   // Call creation method (assumption that content handler was created previously)
   CParser* parser = CParser::NewLC( *matchData, *contentHandler );
   
   // Use the parser
   // ….
   
   // Destroy the parser and CMatchData object
   CleanupStack::PopAndDestroy( 2, matchData );
   

3. Call the parser plug-in to parse the XML.

   To parse a document, write code which includes calls to the parse methods of a CParser object from the global parse methods provided with the framework. The global parse methods are as follows:

   A: Xml::ParseL( Xml::CParser& aParser, const TDesC8& aContent )

   B: Xml::ParseL( Xml::CParser& aParser, RFs& aFs, const TDesC& aFilename )

   C: Xml::ParseL( Xml::CParser& aParser, RFile& aFile )

   The global parse methods call the following CParser object parse methods:

   • ParseBeginL()

   • ParseBeginL( const TDesC8& aDocumentMimeType )

   • ParseL( const TDesC8& aFragment )

   • ParseEndL()

   Note: Methods to be called depends on the nature of the input to the parser. Input may consist of one or several files, and it may be received in one piece or asynchronously in chunks. The files may be same or of different types, and asynchronous input may or may not be buffered before parsing.

   Global parse method A makes a single call to each of the CParser parse methods. This is the simplest approach but it works only while parsing a single file which has been buffered previously. Global parse methods B and C have the same functionality; the only difference is how they identify the input file (by name or from an RFile object). They call CParser::ParseL() in a loop and then call CParser::ParseEnd(). The use of a loop means that input does not have to be buffered, but only one file can be parsed by this technique. This is because of the functionality of the CParser parse methods.

   To parse several unbuffered documents of the same type, multiple calls to global parse method B or C are required. To parse several buffered documents possibly of different types, multiple calls to global parse method A are required. Other eventualities require individual calls to the parse methods of CParser.