Accessing Google Webservices

Overview

To begin, you will need to download the Web Services API and supporting documentation from the google web site.

Before you can use the API, you will need to register to get an unlock code from Google, you can do this at the second step of the download page on google.

Because this example concentrates more on the use of XML and HTTP, over and above the use of the UIQ and Series 60 API, the rest of the article will concentrate on the engine.

The engine code is located in three files, GoogleItEngine.cpp that does the construction of the XML, the http request and the parsing of the resultant XML data.

GoogleItQueryBuilder.cpp that constructs the query based on data in the model. GoogleItQueryParser.cpp that parses the resultant data and puts it into the model.

The supplied samples contain both a UIQ and a Series 6o client that share a common set of code for the engine, parser and generator but have tweaks for the S60 and UIQ user interfaces.

Terms

The Google Web Services API provides a SOAP compliant http web interface to do a google query programatically.

SOAP or Simple Object Access Protocol is a well specified XML API that is used to make procedure calls across processes, between machines and even operating systems. Because the SOAP specification is both open and text based this makes it easy to call other SOAP interface implementations.

In order to define the procedure call each vendor that creates a SOAP service, will have a Web Services Definition Language (WSDL) file that defines the procedures and properties of the functions avaliable on their server. Google provides such a WSDL in their sdk, called GoogleSearch.wsdl.

For more information on SOAP download the specification from the W3C.org web site.

There are samples on Nokia's web site which show how to use the HTTP API's.

Sample

The sample breaks the model down into the three major components of a Symbian application and is modelled after the Model Observer View design pattern.

The first is the Document/Model. The model holds a runtime representation of the data, the document is concerned with loading and saving the model.

The second is the application UI and views. The views holds a representation of the data from the model. In this case there are a number of views that are used to display the query being executed, the progress of the query, the results or the query and any error information.

The third is the Engine which does all the work by launching the HTTP session and then handling data flows both to and from the Google HTTP server.

Below are a list of the more important classes in the sample:

CGoogleItModel

This holds the shared state information for the project that is shared between the engine and the application user interface/views. This is used to hold the query and the results of the query once the query has been submitted. The views use this to display the results and the search/query dialog uses this to store the google query prior to submitting it to the http client.

MGoogleItEngineObserver

This is the link between the application user interface and the engine. Whenever an event happens in the engine, the application user interface is notified via this callback interface function. This then updates the current view with the new information from the engine. Typically this new information will be obtained from the model.

The CGoogleItEngine calls this function and the CGoogleItAppUI implements it. It is designed to provide a bridge or the minimal subset of functions required by then engine to update the user interface.

CGoogleItEngine

This is the main class in the application. It constructs an HTTP session, builds the XML query and parses the XML response, all the while informing the registered observer (in this case the AppUI) about significant events.

To kick off a Google request, call CGoogleItEngine::ExecuteL and this will then launch a Google session and report progress back via the observer function This function starts the HTTP client and constructs the HTTP request which in turn starts the HTTP transaction. It is at this point that the CGoogleQueryBuilder class is instantiated to provide the generator to construct the XML POST query data as a string.

After the request has been generated, the data is posted to the google webserver using the HTTP POST command. All the progress of the transaction will be reported back via the MHFRunL function which will in turn report back to the observer the progress of the query operation. Inside this function,

when the THTTPEvent::EGotResponseBodyData state is entered, the SOAP response from the google web server appended to the current text until the entire message is read.

When the THTTPEvent::EResponseComplete state is entered, the data is parsed using the SyExpat XML parser and the parsed data is stored in the model.

The AppUIView class is then notified via the callback that the engine has completed and there is data so it will update the views.

GoogleItQueryBuilder

This class constructs the text for the SOAP query. It does this by building an XML string with the required data if the format suitable for a Google Soap query. This class is particularly suitable for generic SOAP requests that can be constructed on the fly.

The actual request string was designed by looking at the sample queries supplied with the Google SDK which was downloaded from Google.

Remember it is here you will need to put in your key to actually access the Google webservices server.

GoogleItQueryParser

This is where most of the work is done in the project. Here the parser either parses the entire string from the google server response or it will incrementally parse the response until the HTTP transaction reports there is no more data to be received from the server.

The StartElement method defines what kind of item is to be parsed and then the CharacterData function parses that data and stores it in the model structure for the views and Application UI to use. The EndElement call then decides where the newly read element is to be stored.

Building the projects

The first thing that will need to be done will build the SyExpat project. Hopefully you have downloaded the code for the parser and built the DLL and samples to make sure they work. As far as I know the project compiles on Symbian 7.0s and later as well as with DevStudio, Borland Builder and Code Warrior.

Once this is completed you can then build the GoogleIt sample project in the GoogleIt/Group folder. This is the primary project that links in the HTTP engine, the XML parser and the main user interface and engine code. This can be found in the googleit.mmp file.

Some useful defines

In the engine LOG_REQUEST may be defined, in which case the xml request will be saved to the root of drive c, in a file called GIQuery.xml.

Additionally if LOG_RESPONSE is defined, the response from the Google Webservice server will be stored in a file called GIResponse.xml.

If _INCREMENTAL_ is defined then the incremental form of SyExpat is used. If it is not then the xml response is gathered together into a string and it is parsed once all the data has been received. These two different forms show the different parsing methods that make the parser so useful in Symbian.

Conclusion

This sample has shown how to develop a Web Service consumer that can access the functionality of a companies' SOAP API to interface with their systems using your Symbian phone.

The example integrates well with the Symbian architecture as it reuses the HTPP engine and the XML engine to deliver a new application, thus promoting high code and component reuse.

GoogleIt_Final-2.zip