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:
API class structure
This API provides single interface to geocoding features:
CMnGeocoder class.
This
class represents the connection to a provider application. It defines asynchronous
methods for making geocoding requests.
Related APIs
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:
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.
Related APIs
CMnGeocoder::EOptionDialogDisabledCMnGeocoder::RetrieveGeocodingResultLCMnGeocoder::SetOptionsFindCoordinateByAddressL_TPositionFieldId
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.
Related APIs
CMnGeocoder::EOptionDialogDisabledCMnGeocoder::FindAddressByCoordinateLCMnGeocoder::RetrieveGeocodingResultLCMnGeocoder::SetOptions_TPositionFieldId
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 );
}
}
Related APIs
CActiveMGeocodingObserver::HandleGeocodingCompletedL
Error handling
This API uses only standard 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.
|
Related APIs
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:
Related APIs
CMnGeocoderCMnGeocoder::RemoveObserver()CMnGeocoder::SetObserverL()CMnMapViewCMnNavigatorNewChainedLNewL