S60 Geocoding API Specification |
DN0667502 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.0 |
11.09.2006 |
Approved |
|
![]() |
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.
![]() |
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.
![]() |
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.
![]() |
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).
![]() |
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.
![]() |
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 ); } }
![]() |
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. |
![]() |
![]() |
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. |
![]() |