S60 Geocoding API Specification

DN0667502
CONFIDENTIAL

©Nokia Corporation and/or its subsidiaries 2006
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.0

11.09.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API Description
Use cases
API class structure
Using the Geocoding API
Geocoding
Reverse geocoding
Geocoding handler example
Error handling
Memory overhead
Extensions to the API
See also
Glossary
Definitions

 


Purpose

Geocoding API accompanies Map and Navigation API and enables clients access geocoding features of provider applications, such as conversion street address to coordinates and backwards.

 


S60 or Symbian OS exceptions

This API is available on S60 release 3.2 and later.

 


API Description

This API is intended for end-user applications, which possess any location-related information and wish to utilize it with geocoding features. This is Client-Server type of Library API.

This API does not implement these features itself but instead serves as a gateway between client applications and provider applications, which actually implement geocoding services. Provider applications are application servers and perform in their own processes. Client applications can only request certain services, which are executed in a separate application.

 


Use cases

The main use cases provided by the API are the following:

  • Geocoding - retrieving coordinates for given address information
  • Reverse geocoding - retrieving address information for given coordinates

 


API class structure

This API provides single interface to geocoding features:CMnGeocoder class.
Figure 1: Geocoding API Class Structure
This class represents the connection to a provider application. It defines asynchronous methods for making geocoding requests.

 


Using the Geocoding API

This API relies on functionality provided by external applications, Provider Applications, which are executed in a separate process from client. Geocoding services are accessed through the CMnGeocoder class. Client creates it using either NewL or NewChainedL methods, which differ in the way in which the provider application will be executed.

There are two execution modes available: standalone (the user can switch between the client application and the provider application), initiated by the NewL method, and "chained" (when provider application's main window group is made child of client's window group, hiding the client application from the user and making it impossible to switch back until the provider application is closed), initiated by the NewChainedL method.

Some methods of CMnGeocoder are asynchronous, and they must be completed or cancelled before any other asynchronous requests are made. If an asynchronous method can leave, and it leaves, then no asynchronous request is outstanding.

The connection to the provider application is closed when this class is destroyed, but it does not necessarily mean that the provider application is closed too. This depends on user actions and/or provider application behavior.

When CMnGeocoder is destroyed, the connection to the provider application is closed. The further behavior of the provider application depends on the mode it was started in:
  • The provider application closes too, if started in chained (embedded) mode.
  • If started standalone:
    • if no views are open, the provider application closes.
    • if any view is open, the provider application remains running until it is closed by the user.
Client can also set up observer object to be informed when provider application exits, if it happens during the time CMnGeocoder object is still in use. This may be caused, for example, if application crashes or user closes it. Observer can be set up by calling CMnGeocoder::SetObserverL() and removed by CMnGeocoder::RemoveObserver(). If such event is received, client has to destroy appropriate CMnMapView or CMnNavigator objects.

 


Geocoding

Geocoding features allow client to find coordinates of a location, represented by address information. Address information can be supplied as a landmark, which has appropriate positioning fields set (see _TPositionFieldId in LbsFieldIds.h) or as a plain string. There are two different overloads of the FindCoordinateByAddressL method provided. These requests are asynchronous and must be completed or cancelled before new requests are issued.

The result can be retrieved by CMnGeocoder::RetrieveGeocodingResultL to a landmark. Coordinate information of the landmark is updated with the result of the operation (if it completed successfully).

Address information may be incomplete or ambiguous, in which case the provider application shows a dialog to the user asking to clarify the address. If it is not acceptable, use CMnGeocoder::EOptionDialogDisabled with the CMnGeocoder::SetOptions method to disable any dialogs and ensure silent execution of the request. Note that only one result is returned for geocoding requests, which means that if the address information cannot be resolved to coordinate, the request completes with an error.
Figure 2: Geocoding sequence diagram

 


Reverse geocoding

Reverse geocoding features allow the client to find the address of a location, represented by coordinates. The coordinate is supplied as a landmark, which has a coordinate information set. Use overloads of the CMnGeocoder::FindAddressByCoordinateL method. This is an asynchronous requests and must be completed or cancelled before new requests are issued.

The result can be retrieved by CMnGeocoder::RetrieveGeocodingResultL to a landmark. Address positioning fields of the landmark (see _TPositionFieldId in LbsFieldIds.h) will be updated accordingly to the result of the operation.

Sometimes several address information sets may be available for a coordinate (e.g. coordinate of the middle of a street is given), in which the case provider application shows a dialog to the user asking to clarify the case. If it is not acceptable, use CMnGeocoder::EOptionDialogDisabled with the CMnGeocoder::SetOptions method to disable any dialogs and ensure silent execution of the request. Note that only one result is returned for reverse geocoding requests, which means that in unclear case the request may be completed with an error.
Figure 3: Reverse geocoding sequence diagram

 


Geocoding handler example

This chapter shows how clients call asynchronous geocoding services using active objects.

In this example, the application defines a class derived from CActive, which handles asynchronous geocoding operations. It also defines an observer class with a callback method, which is called, once the requested operation is completed.

// The observer class
class MGeocodingObserver 
    {     
    public:
        // client must implement it
        virtual void HandleGeocodingCompletedL( CMnGeocoder& aGeocoder, TInt aError ) = 0;     
    }; 

// The asynchronous operation handler class
class CActiveSelector : public CActive
    {
    public:         
        CActiveSelector( MGeocodingObserver& aObserver );
        ~CActiveSelector();          
        
        // CActive-related methods
 	      void RunL();         
        void DoCancel();
        TInt RunError( TInt aError );          
        
        // Main operations
        
        // geocoding
        void FindCoordinateL( CPosLandmark& aAddress, CMnProvider& aProvider );
        // geocoding with plain string address 
        void FindCoordinateL( const TDesC& aPlainAddress, CMnProvider& aProvider );
        // reverse geocoding
        void FindAddressL( CPosLandmark& aCoordinate, CMnProvider& aProvider );
        
     private:        

        // disconnects from provider, when operation is completed         
        void Reset();
     
     private:         
        MGeocodingObserver&    iObserver;
        CMnGeocoder*           iGeocoder;     
     }; 

CActiveGeocoder::CActiveGeocoder( MObserver& aObserver ) 
:   CActive( CActive::EPriorityStandard ),
    iObserver( aObserver )
    {
    CActiveScheduler::Add( this );
    }

CActiveGeocoder::~CActiveGeocoder()
    {
    Cancel();
    }

void CActiveGeocoder::FindAddressL( CPosLandmark& aCoordinate, CMnProvider& aProvider )
    {
    if ( IsActive() )
        {
        // avoid two simultaneous asynchronous requests
        User::Leave( KErrInUse );
        }
        
    // create connection
    iGeocoder = CMnGeocoder::NewL( aProvider );
    
    // start request
    iGeocoder->FindAddressByCoordinateL( aCoordinate, iStatus );
    SetActive();
    }
    
void CActiveGeocoder::FindCoordinateL( CPosLandmark& aAddress, CMnProvider& aProvider )
    {
    if ( IsActive() )
        {
        // avoid two simultaneous asynchronous requests
        User::Leave( KErrInUse );
        }
        
    // create connection
    iGeocoder = CMnGeocoder::NewL( aProvider );
    
    // start request
    iGeocoder->FindCoordinateByAddressL( aAddress, iStatus );
    SetActive();
    }

void CActiveGeocoder::FindCoordinateL( const TDesC& aPlainAddress, CMnProvider& aProvider )
    {
    if ( IsActive() )
        {
        // avoid two simultaneous asynchronous requests
        User::Leave( KErrInUse );
        }
        
    // create connection
    iGeocoder = CMnGeocoder::NewL( aProvider );
    
    // start request
    iGeocoder->FindCoordinateByAddressL( aPlainAddress, iStatus );
    SetActive();
    }

void CActiveGeocoder::RunL()
    {
    // request is completed, inform observer
    iObserver.HandleGeocodingCompletedL( *iGeocoder, iStatus.Int() );
    Reset(); // disconnect once observer has retrieved result
    }
    
TInt CActiveGeocoder::RunError( TInt /*aError*/ )
    {
    Reset();
    return KErrNone;
    }

void CActiveGeocoder::DoCancel()
    {
    if ( IsActive() && iGeocoder )
        {
        iGeocoder->Cancel();
        }
    Reset();
    }
    
void CActiveGeocoder::Reset()
    {
    delete iGeocoder;
    iGeocoder = NULL;
    }

The application can use this helper class as shown below. Client's class overrides MGeocodingObserver::HandleGeocodingCompletedL in order to be informed when the geocoding operation is completed and retrieve the result.

// Some client's class
class CClient : public CBase, public MGeocodingObserver
    {
    ...
    public: // These methods start various geocoding operations
        void FetchAddressL();
        void FetchCoordinateL();
        void FetchCoordinateByPlainAddressL();
    
    protected: 
        void ConstructL();
    
    protected: // from MGeocodingObserver       
        // this is called by CActiveGeocoder when request done
        void HandleGeocodingCompletedL( CMnGeocoder& aGeocoder, TInt aError );

    private:
        CActiveGeocoder* iGeocoder;
        CMnProvider*     iProvider;
    };
    
void CMnTestClientAppUi::ConstructL()
    {
    ...
    iGeocoder = new (ELeave) CActiveGeocoder( *this );
    
    // iProvider must be initialized to some provider application, 
    // which supports CMnProvider::EServiceGeocoding
    }

void CClientAppUi::FetchAddressL()
    {
    CPosLandmark* landmark = CPosLandmark::NewLC();

    TLocality loc( TCoordinate( 61.5, 23.4, 0 ), 0, 0 );
    landmark->SetPositionL(loc);

    // start operation using pre-chosen provider application
    iGeocoder->FindAddressL( *landmark, *iProvider );

    CleanupStack::PopAndDestroy( landmark );
    }
    
void CClientAppUi::FetchCoordinateL()
    {
    CPosLandmark* landmark = CPosLandmark::NewLC();
    lm->SetPositionFieldL( EPositionFieldCity, _L("Tampere") );

    // start operation using pre-chosen provider application
    iGeocoder->FindCoordinateL( *landmark, *iProvider );

    CleanupStack::PopAndDestroy( landmark );
    }

void CClientAppUi::FetchCoordinateByPlainAddressL()
    {
    _LIT( KPlainAddress, "Visiokatu Tampere Finland" );

    // start operation using pre-chosen provider application
    iGeocoder->FindCoordinateL( KPlainAddress, *iProvider );
    }

void CClientAppUi::HandleGeocodingCompletedL( CMnGeocoder& aGeocoder, TInt aError )
    {
    // selection is done, analyze error code first...
    if ( aError )
        {
        // geocoding failed
        }
    else
        {
        // ... and retrieve result
        CPosLandmark* landmark = CPosLandmark::NewLC();
        aGeocoder.RetrieveGeocodingResultL( *landmark );
        
        // landmark contains requested data: address info or coordinate
        
        CleanupStack::PopAndDestroy( landmark );
        }
    }    

 


Error handling

This API uses only standard Symbian OS leave codes. Panic codes are defined in mnerrors.h header file.

Panic code Reason
KMnPanicDuplicateRequest Raised if the client issues a new asynchronous request before the previous one is completed or cancelled. For this API it happens if the client calls one of asynchronous requests before the previous request is completed or cancelled.

 


Memory overhead

The RAM usage of this API does not exceed usual overhead related to object creation.

 


Extensions to the API

This API does not allow extending.

 


See also

See also related APIs:
  • Map and Navigation Provider Discovery API
  • Map and Navigation API
  • Map and Navigation AIW API
  • Landmarks API
  • Location Acquisition API

 


Glossary

 


Definitions

Table: Geocoding API definitions

Landmark

A landmark is principally a location with a name.

Provider Application An application, which implements map, navigation and geocoding services and provides access to these features for clients of Map and Navigation API and Geocoding API.
Geocoding The process of translating address information to coordinates.
Reverse geocoding The process of resolving address information by coordinates.

Back to top