Building an XML Parser for Symbian (part 3)

Introduction

The previous two articles detailed the criteria for an XML parser and how the chosen parser, Expat, was ported over to the Symbian operating System.

However the parser does suffer from one drawback, as it is entirly C based it has no object oriented features and so it is not based on Symbian programming idioms and metaphors.

To make the Expat parser more Symbian friendly it was split into four parts. The first part is the Symbian base class, the Symbian Parser object itself and the third and fourth are the mixin interfaces that allow for callbacks when an element type is detected and so allowing your C++ objects to have data copied to their members.

There are two files in the project. The header file, SyExpat.h is the header file the has the enums, interfaces and class definitions for the expat parser. The second file is SyExpat.cpp which holds the implementations of the class.

All the enum, structs and classes as well as their members and methods have been documented using Doxygen as is common with Symbian applications. This can be found in the HTML directory (start with index.html)

One important thing to note is that throughout the parser you should not assume strings are null terminated! Descriptors are used throughout the C++ class.

CExpatParserBase

This is the base class for all parsers and is the class that is intended to be inherited from. Because it can be inherited, the constructor is protected - you will need to provide your own constructor in derived classes in order to instantiate an instance of the parser object.

Because there is so much functionality I will only cover the basics of using the parser here. There is copious documentation both in the samples, in the header files and in the Doxygen generated help files to assist.

Assuming an instance of a derived parser has been created with NewL or NewLC, you can pass a block of data to the Parse function, or aquire a buffer using GetBuffer and then fill it. The Parse and ParseBuffer can then be called multiple times to parse the data until the aIsFinal parameter is set to ETrue, in which case the parser will then terminate, either with a code of EStatusError or EStatusOk.

To do anything useful however you need to set a handler for the document and also possibly for the declarations using the SetHandler function. As the parser is incrementally parsing the data it will call the various methods of the handler attached to your object, allowing you to handle the xml correctly.

If there is an error, the current byte position, column and row can be obtained from the parser instance, this will allow the application to report the error in a more descriptive manner. Currently the parser parsing context is not maintained as this is wasteful on memory.

MSyDocHandler

This is the core handler for basic XML items. Both elements and attributes do not just consist of a name, they can also contain a prefix and the namespace attached to the prefix. This functionality is encapsulated in the TQualified structure. Elements will be defined in the iLocalName which will never be empty. All the methods for the parser are clearly documented and explained in the header file, and generated documentation.

MSyDeclHandler

The declaration handler handles declaration type items. These are normally not used. The only method handler that requires explanation is the Standalone method which will allow parsing to stop if the document has any external entity definitions.

CSyParser

This is a very lightweight wrapper over the parser object. It instantiates and exposes the methods of the parser via this class. It is expected most developers will use this class to access the parser when handling generic xml parsing as it provides the most flexible implementation. This class can be instantiated using the NewL and NewLC functions as is common with the Symbian Resource/Instaniate/Aquire pattern.

CSyContextualParser

This class provides methods to save the current handler for the parser on a Last-In-First-Out stack basis and replace it with a new handler. When you have finished with the parser then you can pop the handler from the internal stack and parsing will resume with the handler that was originally placed on the stack. This is a useful pattern where elements map to structures or class that can be easily parsed.

Download

The download has been provided as a zip file. This has all the files needed to build the Symbian DLL as well as the example code and help files as generated by Doxygen.

SyExpat.zip

Samples

There are two samples illustrating the functionality and resuablility of the parser. These samples have been ported from the samples provided by Expat but been updated for the OneBridge client. The first sample is the Elements sample and this just takes a generic string and parses it, calling the handler for each instance element, comment, processing instruction etc encountered. The second sample is slightly more complex in that it requires an xml file to read from which needs to be located in the root of your C drive. This will then incrementally parse the file in blocks of 128 bytes until the end of the file is reached.

What's not implemented

The most significant section not implemented is the ExternalEntity declaration. However as it is expected that entities and especially external entities will not be handled on devices as they will require loading them from a web site over say GPRS which is slow. Furthermore this will also affect the parsing as the parser is synchronous when parsing entities. It is envisaged that this will be addressed very soon. Of course I am still testing this and any revisions can soon be downloaded from the download section of toddsoftware.com

CSyGenerator

I have included the XML generator even though it is not discussed here (it will be part of another article).

This allows XML to be generated to an output writer and is the reverse of the parser.

Conclusion

This concludes the third part of developing and XML parser for the Symbian Operating System.

The next article will concentrate on an XML generator so XML can be efficiently and easily generated. Fortunatly this is much easier exercise than parsing and is a lot more straight forward to explain.

And finally a hint at things to come, the final article of the group will highlight an application that does searches using the google web services API built on the parser and generator from the preceding articles.