<?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