Collapse all Symbian^3 Application Developer Library

CMnGeocoder Class Reference

class CMnGeocoder : public CBase

Both geocoding (address to coordinate) and "reverse geocoding" (coordinate to address) features are provided by this class. Further in documentation they are all referred to as "geocoding" if not specified otherwise.

Geocoding operations are asynchronous, they can be cancelled by Cancel() . However only one asynchronous request can be issued at a time, otherwise client will be panicked with KMnPanicDuplicateRequest.

To create an instance of the class, use NewL or NewChainedL methods. They require an instance of CMnProvider , defined in Map and Navigation Provider Discovery API.

Main methods are FindCoordinateByAddressL (two overloads) and FindAddressByCoordinateL . Other methods define optional information that changes behavior of the class and others help to retrieve results of main methods' execution.

Since: 3.1 mnclientlib.dll

Inherits from

CMnGeocoder
- CBase

Public Member Functions
	~CMnGeocoder ()
IMPORT_C void	Cancel ()
IMPORT_C void	FindAddressByCoordinateL (const CPosLandmark &, TRequestStatus &)
IMPORT_C void	FindCoordinateByAddressL (const CPosLandmark &, TRequestStatus &)
IMPORT_C void	FindCoordinateByAddressL (const TDesC &, TRequestStatus &)
IMPORT_C CMnGeocoder *	NewChainedL ( CMnProvider &)
IMPORT_C CMnGeocoder *	NewL ( CMnProvider &)
IMPORT_C TOptions	Options ()
IMPORT_C void	RemoveExitObserver ()
IMPORT_C void	RetrieveGeocodingResultL ( CPosLandmark &)
IMPORT_C void	SetExitObserverL ( MAknServerAppExitObserver &)
IMPORT_C void	SetOptions ( TOptions )

Private Member Functions
	CMnGeocoder ()
void	ConstructChainedL ( CMnProvider &)
void	ConstructCommonL ( CMnProvider &)
void	ConstructNewL ( CMnProvider &)

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TOption { EOptionNone = 0x00, EOptionDialogDisabled = 0x01 }

Public Member Type Definitions
typedef	TUint32 TOptions

Private Attributes
CApaServerAppExitMonitor *	iExitMonitor
TOptions	iOptions
RMnGeocodingServiceClient *	iSession

Constructor & Destructor Documentation

CMnGeocoder()

CMnGeocoder

(

)

[private]

C++ constructor

~CMnGeocoder()

IMPORT_C

~CMnGeocoder

(

)

Destructor

Member Functions Documentation

Cancel()

IMPORT_C void

Cancel

(

)

ConstructChainedL(CMnProvider &)

void

ConstructChainedL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

ConstructCommonL(CMnProvider &)

void

ConstructCommonL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

ConstructNewL(CMnProvider &)

void

ConstructNewL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

FindAddressByCoordinateL(const CPosLandmark &, TRequestStatus &)

IMPORT_C void	FindAddressByCoordinateL	(	const CPosLandmark &	aLandmark,
			TRequestStatus &	aRequest
		)

Coordinate information from passed landmark will be used. Any other helper information (like coverage radius, existing address information) can also be used. If it is not desired, then this information should be removed from landmark by client.

Only one address will be the result of this operation. If any ambiguities arise during translation, then Provider Application may query user to solve it. Set EOptionDialogDisabled to prevent this. Additional information (other than coordinate) found in landmark cannot be a reason for such a request.

Use RetrieveGeocodingResultL() to retrieve results of the operation.

This method can leave in case of memory lack or other system error. If it leaves, no asynchronous request is outstanding.

panic: "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request is issued before previous one is completed.

Parameters

const CPosLandmark & aLandmark	Landmark containing address information
TRequestStatus & aRequest	Contains result of the request, when it is completed. KErrNotFound if given address couldn't be resolved to coordinate (also due to disabling of query dialog). KErrCancel, if user has cancelled the operation. KErrArgument, if input landmark does not contain coordinate information (latitude and longitude are required). KErrNone if request is completed successfully.

FindCoordinateByAddressL(const CPosLandmark &, TRequestStatus &)

IMPORT_C void	FindCoordinateByAddressL	(	const CPosLandmark &	aLandmark,
			TRequestStatus &	aRequest
		)

Address information from passed landmark will be used.

Only one coordinate will be the result of this operation. If any ambiguities arise during translation, then Provider Application may query the user to solve it. Set EOptionDialogDisabled to prevent this.

Use RetrieveGeocodingResultL() to retrieve results of the operation.

This method can leave in case of memory lack or other system error. If it leaves, no asynchronous request is outstanding.

panic: "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request is issued before previous one is completed.

Parameters

const CPosLandmark & aLandmark	Landmark containing address information
TRequestStatus & aRequest	Contains result of the request, when it is completed. KErrNotFound if given address couldn't be resolved to coordinate (also due to disabling of query dialog). KErrCancel, if user has cancelled the operation. KErrArgument, if input landmark does not contain address information. KErrNone if request is completed successfully.

FindCoordinateByAddressL(const TDesC &, TRequestStatus &)

IMPORT_C void	FindCoordinateByAddressL	(	const TDesC &	aAddress,
			TRequestStatus &	aRequest
		)

This is the another overload, which accepts address input as plain string.

Use RetrieveGeocodingResultL() to retrieve results of the operation.

This method can leave in case of memory lack or other system error. If it leaves, no asynchronous request is outstanding.

panic: "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request is issued before previous one is completed.

Parameters

const TDesC & aAddress	Plain address. Format of this string is not defined, this is barely how human user writes addresses down.
TRequestStatus & aRequest	Contains result of the request, when it is completed. KErrNotFound if given address couldn't be resolved to coordinate (also due to disabling of query dialog). KErrCancel, if user has cancelled the operation. KErrNone if request is completed successfully.

NewChainedL(CMnProvider &)

IMPORT_C CMnGeocoder *

NewChainedL

(

CMnProvider &

aProvider

)

[static]

leave: KErrNotSupported Selected Provider Application does not support CMnProvider::EServiceGeocoding .

Parameters

CMnProvider & aProvider

Provider Application to be used for geocoding.

NewL(CMnProvider &)

IMPORT_C CMnGeocoder *

NewL

(

CMnProvider &

aProvider

)

[static]

leave: KErrNotSupported Selected Provider Application does not support CMnProvider::EServiceGeocoding .

Parameters

CMnProvider & aProvider

Provider Application to be used for geocoding.

Options()

IMPORT_C TOptions

Options

(

)

const

RemoveExitObserver()

IMPORT_C void

RemoveExitObserver

(

)

RetrieveGeocodingResultL(CPosLandmark &)

IMPORT_C void

RetrieveGeocodingResultL

(

CPosLandmark &

aTargetLandmark

)

If last operation result was address then address information in the passed landmark is updated. If last operation result were coordinates, then coordinate information of the landmark is updated. Note that landmark is not stored in any database, client has to do it itself if needed.

Target landmark parameter does not have to be a different landmark then that was passed for geocoding or reverse geocoding. However, all address or coordinate (depending on last operation result type) information will be updated in target landmark.

Issuing next geocoding request discards current result.

leave: KErrNotFound Result is not available.

Parameters

CPosLandmark & aTargetLandmark

This landmark will be updated according to last operation result.

SetExitObserverL(MAknServerAppExitObserver &)

IMPORT_C void

SetExitObserverL

(

MAknServerAppExitObserver &

aObserver

)

leave: KErrAlreadyExists if observer is already set.

Parameters

MAknServerAppExitObserver & aObserver

Exit observer.

SetOptions(TOptions)

IMPORT_C void

SetOptions

(

TOptions

aOptions

)

Parameters

TOptions aOptions

Bitmap of TOption values.

Member Enumerations Documentation

Enum TOption

Enumerators

EOptionNone = 0x00	Default value
EOptionDialogDisabled = 0x01	Defines that no queries to user are allowed during geocoding operations

Member Type Definitions Documentation

Typedef TOptions

typedef TUint32

TOptions

Type for bitmap of TOption values.

Member Data Documentation

CApaServerAppExitMonitor * iExitMonitor

CApaServerAppExitMonitor *

iExitMonitor

[private]

TOptions iOptions

TOptions

iOptions

[private]

RMnGeocodingServiceClient * iSession

RMnGeocodingServiceClient *

iSession

[private]