Parsing an XML document using Content Handler

This section explains how to parse an XML document by implementing the content handler functionality of the parser framework.

MContentHandler class defines the interface required by a client of the XML framework. It allows a client to be placed in a chain with other clients such as a Parser or a Validator, and therefore allows the flow of information within chain. It provides callbacks similar to that of the SAX 2.0 interface.

Introduction

Consider a scenario when an application with numerous settings require the settings being saved, so that when the application is restarted after a shutdown, the settings are available. This can be achieved (while ensuring the cross-platform compatibility) by saving the setting in an XML file, which the application parses on start-up. The application responds to the XML statements by implementing the MContentHandler interface. Since the parser detects tags and their content, it calls the associated content handler functions to respond with the required behaviour.

The callback functions which an implementation of MContentHandler must provide are depicted in the table. These correspond to functions defined in the ContentHandler interface of the SAX specification. The last parameter of each function is an error code. If no error has taken place, then the KErrNone null error code is returned by the framework.

MContentHandler callback	SAX specification function
`OnStartDocumentL()`	`startDocument()`
`OnEndDocumentL()`	`endDocument()`
`OnStartElementL()`	`startElement()`
`OnEndElementL()`	`endElement()`
`OnContentL()`	`characters()`
`OnStartPrefixMappingL()`	`startPrefixMapping()`
`OnEndPrefixMappingL()`	`endPrefixMapping()`
`OnIgnorableWhiteSpaceL()`	`ignorableWhitespace()`
`OnSkippedEntityL()`	`skippedEntity()`
`OnProcessingInstructionL()`	`processingInstruction()`
`OnError()`
`GetExtendedInterface()`

The following table lists the classes that are parameter of functions that must be implemented:

Class	Description
RDocumentParameters	Contains the character set which the document uses.
RAttributeArray	Consists of an array of RAttribute objects. The array holds the name (as an RTagInfo object), value and type of each attribute of the element.
RTagInfo	Contains information about an XML tag, its namespace URI and prefix, and its local name.

Procedure

Follow the steps given below to understand how to parse an XML document by implementing the content handler functionality:

Implement the MContentHandler interface.

The following code snippet illustrates how to implement MContentHandler:

class CMyContentHandler : public CBase, public MContentHandler
{
public:
    // A callback to indicate the start of the document. 
    void CXmlExample::OnStartDocumentL( const RDocumentParameters&, TInt )
    {
    iConsole->Printf( KOnStartDoc );
    iConsole->Printf( KPressAKey );
    iConsole->Getch();

    iNumElements = 0;
    iNumSkippedEntities = 0;
    iNumPrefixMappings = 0;
    iNumPrefixUnmappings = 0;
    }
    
// A callback to indicate an element has been parsed.     
void CXmlExample::OnStartElementL( const RTagInfo&, const RAttributeArray&, TInt )
    {
    iConsole->Printf( KOnStartEle );

    if( iLeaveOnStartElement )
        {    
        if( iNumElements++ == 0 )
                  {
                  iConsole->Printf( KOnStartErr, KExpectedLeaveCode );
            User::After( 1 );
                  User::Leave( KExpectedLeaveCode );
                  }

           iNumElements++;
        }
    }
  
// implementations of the other callbacks
// ...

}

Instantiate the ContentHandler object in the client application code and pass it to the constructor method of a parser object.

...
CMyContentHandler* ch = CMyContentHandler::NewL();
CParser* parser = CParser::NewLC( KXmlMimeType,ch );
parser->ParseL( myXMLdata ); // this will result in callbacks to ch
...