<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-E16070E5-379A-5818-81CC-B00059A40084"><title>Choosing a Parser Plug-in</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This section explains how to specify a particular XML parser in a client application. </p> <section><title>Introduction</title> <p>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. </p> <p>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: </p> <ul><li id="GUID-C90EB73B-3EB3-576D-9482-B34419E9FDF6"><p> <b>MIME type</b> - Specifies the MIME types supported by that implementation of plug-in parser. </p> </li> <li id="GUID-FF9E5CD6-5012-5C42-BFFE-332B7074E6C0"><p> <b> Variant identifier</b> (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. </p> </li> </ul> <p>This functionality is provided in <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita#GUID-5748D958-9480-3358-A399-6B92293B86D9/GUID-7F10FDA9-35DF-3D02-B561-D43680B0E8D0"><apiname>XML::CMatchData</apiname></xref> class which is supplied to three API methods (<codeph>NewL</codeph>, <codeph>NewLC</codeph>, and <codeph>ParseBginL</codeph>) of the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita#GUID-5748D958-9480-3358-A399-6B92293B86D9/GUID-1FDF909C-BA22-3C39-9A49-D804C54BAEAE"><apiname>XML::CParser</apiname></xref> class. </p> <p>Call the constructor method of a <xref href="GUID-3C824E3B-68AB-31C5-A3D7-26A73B53D076.dita"><apiname>CParser</apiname></xref> 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. </p> </section> <section><title>Procedure</title> <p>Follow the procedure given below to choose a parser plug-in and parse the XML: </p> <ol id="GUID-A0C24252-C9BA-5073-809F-ED87CA0674FD"><li id="GUID-AE8B4D9D-C92C-5B6B-81A5-AE5690996D50"><p>Construct a <xref href="GUID-A6CF939C-110C-3FA4-8C2E-0B48C04D9CFB.dita"><apiname>CMatchData</apiname></xref> object, and set the data about the files and parser variant to it. </p> <codeblock id="GUID-153866B2-277C-5FEE-9E6E-C02D90BA0D8F" xml:space="preserve">

// Create CMatchData object

CMatchData *matchData = CMatchData::NewLC();

// Set Type

matchData->SetMimeTypeL( _LIT( “text/xml” ) );

// Set variant string

matchData->SetVariantL( _LIT( “LicenseeX” ) );

</codeblock> </li> <li id="GUID-5E140D20-7239-57C6-896C-F68CF7285CEC"><p>Construct an instance of a parser plug-in and pass the <xref href="GUID-A6CF939C-110C-3FA4-8C2E-0B48C04D9CFB.dita"><apiname>CMatchData</apiname></xref> object to its constructor method. </p> <codeblock id="GUID-438AC57A-8B36-5782-8C67-E853F00B142E" xml:space="preserve">

// 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 );

</codeblock> </li> <li id="GUID-C1216537-EC67-5A3C-BE71-398D6A986117"><p>Call the parser plug-in to parse the XML. </p> <p>To parse a document, write code which includes calls to the parse methods of a <codeph>CParser</codeph> object from the global parse methods provided with the framework. The global parse methods are as follows: </p> <p> <b>A</b>: <xref href="GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2.dita#GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2/GUID-85604159-4639-37FD-BAA1-D06E038AD121"><apiname>Xml::ParseL( Xml::CParser&amp; aParser,

                const TDesC8&amp; aContent )</apiname></xref>  </p> <p> <b>B</b>: <xref href="GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2.dita#GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2/GUID-5DF681F2-723F-3738-8E1E-A40BE1552254"><apiname>Xml::ParseL( Xml::CParser&amp; aParser,

                RFs&amp; aFs, const TDesC&amp; aFilename )</apiname></xref>  </p> <p> <b>C</b>: <xref href="GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2.dita#GUID-908E14FD-9FFF-30ED-A9D2-EE812A56E5C2/GUID-00CD527D-2E77-3074-A669-E162997FE1B0"><apiname>Xml::ParseL( Xml::CParser&amp; aParser,

                RFile&amp; aFile )</apiname></xref>  </p> <p>The global parse methods call the following <codeph>CParser</codeph> object parse methods: </p> <ul><li id="GUID-1FC654D3-861B-5D8F-B82B-0F88408CB9A7"><p> <xref href="GUID-59C7BEDF-9A63-35D4-8612-8AB13A4B6F4A.dita"><apiname>ParseBeginL()</apiname></xref>  </p> </li> <li id="GUID-07B4CCBB-403D-5992-9C4D-D21B4A3D0226"><p> <xref href="GUID-6E512056-8D93-39C6-9569-7EAEA2E53780.dita"><apiname>ParseBeginL( const TDesC8&amp; aDocumentMimeType

                     )</apiname></xref>  </p> </li> <li id="GUID-564A5D9A-72AB-5BD2-A5F7-A0C8B9FB6B33"><p> <xref href="GUID-7B8C6104-07E0-35E4-A4A0-1AB764818BF1.dita"><apiname>ParseL( const TDesC8&amp; aFragment )</apiname></xref>  </p> </li> <li id="GUID-9A4CB6F9-3215-5F6E-AEA7-D5623A7F8812"><p> <xref href="GUID-66E9E3B3-3D78-36F3-B009-61B3F6939DAC.dita"><apiname>ParseEndL()</apiname></xref>  </p> </li> </ul> <p> <b>Note</b>: 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. </p> <p>Global parse method <b>A</b> makes a single call to each of the <xref href="GUID-3C824E3B-68AB-31C5-A3D7-26A73B53D076.dita"><apiname>CParser</apiname></xref> 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>B</b> and <b>C</b> have the same functionality; the only difference is how they identify the input file (by name or from an <codeph>RFile</codeph> object). They call <codeph>CParser::ParseL()</codeph> in a loop and then call <codeph>CParser::ParseEnd()</codeph>. 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 <codeph>CParser</codeph> parse methods. </p> <p>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 <codeph>CParser</codeph>. </p> </li> </ol> </section> </conbody></concept>