API Description
This API is intended for end-user applications, which possess any location-related
information and wish to use it with map and/or navigation 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 map views and navigation. Provider applications are application
servers and perform in their own processes and utilize their own views. Client
applications only request certain services via this API and these are executed
in a separate application.
Use cases
The main use cases provided by the API are following:
API class structure
This API provides two main interfaces to map and navigation features:
Each of these classes represent a connection to the provider application.
In order to instantiate them, it is needed to supply an instance of
CMnProvider,
defined in Map and Navigation Provider Discovery API, to
either NewL or NewChainedL methods.
Related APIs
CMnMapViewCMnNavigatorCMnProviderNewChainedLNewL
Using the Map and Navigation API
This API relies on functionality provided by external applications, Provider
applications, which are executed in a separate process from client. Access
to map views is provided by the
CMnMapView class and navigation
service is available through the CMnNavigator class. The
client creates these classes using either NewL or NewChainedL methods,
which differ in the way how the provider application is 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 thus 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.
The chained mode is similar to the embedded mode with the exception that the
child application is running in its own process.
CMnMapView has one asynchronous method, SelectFromMapL,
which must be completed or cancelled before next asynchronous request is made.
If this methods, then no asynchronous request is outstanding.
When these classes are destroyed, the connection to the provider application
is closed. The further behavior of the provider application depends on the
mode it was started:
Client can also set up observer object to be informed when provider application
exits, if it happens during the time
CMnMapView or
CMnNavigator object
is still in use. This may be caused, for example, if provider application
crashes or user closes it. Observer can be set up by calling
SetObserverL method
and removed by
RemoveObserverL, provided by both classes.
If such event is received, client has to destroy appropriate
CMnMapView or
CMnNavigator objects.
Client can use
MAknServerAppExitObserver-derived class
as observer. Handler function of this class provides default implementation,
which closes client application if provider application has been closed by
user by "Exit" menu option. This behavior is only valid for the case when
provider application is executed in chained mode. In standalone mode, provider
application is treated as "independent" on client application and hence client
does not need to be closed if provider application is closed.
General use of this API is described by following sequence:
-
Client creates object of needed service:
CMnMapView or CMnNavigator.
By using NewL or NewChainedL constructors,
client selects standalone or chained execution mode, respectively.
-
Client sets provider application exit observer by calling
SetObserverL.
-
Client specifies optional data, which is required to be taken into account,
when service is executed. For example, center point and radius of the map
area to be shown.
-
Client executes service by calling
CMnMapView::ShowMapL, CMnMapView::ShowCurrentLocationL, CMnMapView::SelectFromMapL or CMnNavigator::NavigateToL. User will be shown with
appropriate view.
-
In case of asynchronous operation, such as
CMnMapView::SelectFromMapL,
completion will be reported via TRequestStatus parameter,
passed to this function. Result can be retrieved after that.
-
Sequence can be completed by client, if it destroys
CMnMapView or CMnNavigator object,
or by user, if she closes provider application. In the latter case, completion
will be reported to exit observer, specified by SetObserverL.
Following diagram depicts typical sequence when provider is executed
in chained mode.
Following diagram depicts typical sequence when provider is executed in
standalone mode.
Show map
One of the main uses of this API is to show the map view on the screen.
The map is not drawn in any of client's views, but instead in provider application's
own views. The client can specify:
-
The area of the map to be drawn
-
Client's landmarks to be shown on the map
-
Whether current location should be marked on the map
If the client does not specify any of those, the provider application
shows the default map view (or last shown map, if any).
The client uses the
CMnMapView class in order to use
map features and the CMnMapView::ShowMapL method in order
to request the map view display. Whatever options are required they must be
set before ShowMapL is called as they only affect the next
call to this function and do not affect the currently displayed map.
Show map of an area
The simplest case is showing the map of some area. The area is defined
by central point and radius. Central point is the coordinate of the location
on the globe and the radius (in meters) defines what minimal area around this
location must be visible in the map view.
Show landmarks on map
This subcase is very similar to showing map of an area. Here the client
additionally specifies what landmarks should be shown on the map.
There are several ways of how the client can deliver data of landmarks,
which are to be shown:
-
"Linked landmarks" - the client specifies an array of IDs of landmarks
and URI of the landmark database, where those landmarks exist. This is the
most efficient way in terms of memory consumption and is recommended to be
used whenever applicable.
-
Landmark instances - the client specifies an array of instances of the
CPosLandmark class.
Use it for landmarks, which are not stored in landmark database. Note that
due to the fact that database information is not available for provider application,
category data from these landmarks cannot be used in map view. A big amount
of data may be needed to sent over to the provider application for every landmark
and all landmark data needs to be copied before being sent to the provider
application. It is recommended to avoid this approach whenever possible, as
it is the most memory-hungry method.
-
Packed landmarks - the client specifies an array of pointer descriptors
of buffers containing landmark data. See the
PosLandmarkSerialization class
description on how to pack a landmark to a buffer. This approach is similar
to sending landmark instances, but is slightly more efficient from the memory
consumption point of view, because data can be sent to the provider application
without copying. However this is only useful for those clients, which already
possess landmarks in packed form.
Use
CMnMapView::AddLandmarksToShowL overloads to specify
landmarks to show on map. These methods can be called any number of times
and all landmarks are added to the common list of landmarks, which is shown
when ShowMap is called next time. Use CMnMapView::ResetLandmarksToShow to
clear the list of landmarks.
If the map area is specified by the client, this area is visible in the
map view, otherwise the provider application automatically selects the area,
which covers all specified landmarks.
Related APIs
CMnMapView::AddLandmarksToShowLCMnMapView::ResetLandmarksToShowCPosLandmarkPosLandmarkSerialization
Show map from current location
Another extension to the showing map use case is to specify that the map
should be shown with the current location in the center. This is done by calling
CMnMapView::ShowCurrentLocationL instead
of ShowMapL. The map is centered at the current location
point and the central point setting of map area is ignored (but the radius
part of area settings is used). All other options are applicable in the same
way as they are for the ShowMapL call.
The map is only required to be drawn the first time centered to the current
location. If the current location moves, the map does not move automatically.
However, if the
CMnMapView::ECurrentLocationShowAlways option
is set, then map is updated if the current location goes beyond the visible
area.
Related APIs
CMnMapView::ECurrentLocationShowAlwaysCMnMapView::ShowCurrentLocationLShowMapL
Show landmarks on map code example
The following is the example of a function, which invokes map views. Its
input parameter is reference to the
CMnProvider class,
which the caller must obtain from Map and Navigation Provider Discovery
API. See documentation on this API for code examples on how to find
available provider applications.
void ShowMapL( CMnProvider& aProvider )
{
// 1. Connect to map provider
CMnMapView* mapview = CMnMapView::NewL( aProvider );
CleanupStack::PushL( mapview );
// 2a. Add some landmark instances to show
CPosLandmark* landmark = CPosLandmark::NewLC();
_LIT( KDummyLandmarkName, "DummyLandmark" );
landmark->SetLandmarkNameL( KDummyLandmarkName );
TLocality loc(TCoordinate( 0, 0, 3 ), 4, 5);
landmark->SetPositionL(loc);
RPointerArray<CPosLandmark> landmarks;
CleanupClosePushL( landmarks );
landmarks.AppendL( landmark );
// send it to provider application
mapview->AddLandmarksToShowL( landmarks );
// array and landmark can be destroyed now
CleanupStack::PopAndDestroy( &landmarks );
CleanupStack::PopAndDestroy( landmark );
// 2b. Add some "linked" landmarks to show
_LIT( KDatabaseUri, "file://c:testlandmarks.ldb" ); // must be URI of an existing database
const TPosLmItemId KTestLandmarkId = 12345; // must be valid ID of a landmark in the database
RArray<TPosLmItemId> landmarkIds;
CleanupClosePushL( landmarkIds );
landmarkIds.AppendL( KTestLandmarkId );
mapview->AddLandmarksToShowL( KDatabaseUri, landmarkIds );
// id array can be destroyed now
CleanupStack::PopAndDestroy( &landmarkIds );
// 3. Invoke map view
// both landmarks will be drawn on the map
mapview->ShowMapL();
// it is ok to disconnect now. Provider will not close
// until user closes the view
CleanupStack::PopAndDestroy( mapview );
}
Related APIs
Related APIs
CMnMapViewCMnMapView::ShowMapLShowMapL
Select location from map
A client may request a location selection service from the provider application.
All options are applicable in the same way as they are for the
ShowMapL call,
but two additional settings exist for this case:
-
Restricted selection - specifies that the user cannot select any location
from the map but must be restricted to select one of the landmarks specified
by the client (or refuse selection). Use the
CMnMapView::EOptionRestrictSelection option
with the CMnMapView::SetOptions method.
-
Request text - the client specifies that, when asked to select a location,
the user will see a specific request text, such as "Select destination". If
not set, the default localized text will be shown. Use
CMnMapView::SetCustomRequestTextL to
override the default text. Use CMnMapView::SetUseDefaultRequestText to
return to the default text.
Use
CMnMapView::SelectFromMapL to start user's selection
of a location from the map. This is an asynchronous request, when it is completed,
use CMnMapView::SelectionResultType to identify what type
of location has been selected and then one of the CMnMapView::RetrieveSelectionResult
overloads in order to retrieve actual data. Use CMnMapView::Cancel to
cancel selection.
The following code example demonstrates how clients call an asynchronous
selection from the map service, using active objects.
In this example, the application defines a class derived from
CActive,
which handles asynchronous selection operation. It also defines an observer
class with a callback method, which is called once the selection operation
is completed.
// The observer class
class MSelectionObserver
{
public:
// client of CActiveSelector must implement it
virtual void HandleSelectionCompletedL( CMnMapView& aMapView, TInt aError ) = 0;
};
// The asynchronous operation handler class
class CActiveSelector : public CActive
{
public:
CActiveSelector( MSelectionObserver& aObserver );
~CActiveSelector();
// CActive-related methods
void RunL();
void DoCancel();
TInt RunError( TInt aError );
// Initiates selection operation
void SelectL( CMnProvider& aProvider );
private:
// disconnects from provider, when operation is completed
void Reset();
private:
MSelectionObserver& iObserver;
CMnMapView* iMapView;
};
CActiveSelector::CActiveSelector( MSelectionObserver& aObserver )
: CActive( CActive::EPriorityStandard ),
iObserver( aObserver )
{
CActiveScheduler::Add( this );
}
CActiveSelector::~CActiveSelector()
{
Cancel();
}
void CActiveSelector::SelectL( CMnProvider& aProvider )
{
if ( IsActive() )
{
// avoid two simultaneous selection requests
User::Leave( KErrInUse );
}
// create connection
iMapView = CMnMapView::NewChainedL( aProvider );
// start request
iMapView->SelectFromMapL( iStatus );
SetActive();
}
void CActiveSelector::RunL()
{
// request is completed, inform observer
iObserver.HandleSelectionCompletedL( *iMapView, iStatus.Int() );
Reset(); // disconnect once observer has retrieved result
}
TInt CActiveSelector::RunError( TInt /*aError*/ )
{
Reset();
return KErrNone;
}
void CActiveSelector::DoCancel()
{
if ( IsActive() && iMapView )
{
iMapView->Cancel();
}
Reset();
}
void CActiveSelector::Reset()
{
delete iMapView;
iMapView = NULL;
}
The application can use this helper class as shown below. The client's
class overrides
MSelectionObserver::HandleSelectionCompletedL in
order to be informed when the selection operation is completed and retrieve
the selection result.
// Some client's class
class CClient : public CBase, public MSelectionObserver
{
...
public:
// this method starts selection
void SelectFromMapL();
protected:
void ConstructL();
protected: // from MSelectionObserver
// this is called by CActiveSelector when selection is done
void HandleSelectionCompletedL( CMnMapView& aMapView, TInt aError );
private:
CActiveSelector* iSelector;
CMnProvider* iProvider;
...
};
void CClient::ConstructL()
{
...
iSelector = new (ELeave) CActiveSelector( *this );
}
void CClient::SelectFromMapL()
{
// start selection using pre-chosen provider application
// iProvider must be initialized to some provider application,
// which supports CMnProvider::EServiceMapView
iSelector->SelectL( *iProvider );
}
void CClient::HandleSelectionCompletedL( CMnMapView& aMapView, TInt aError )
{
// selection is done, analyze error code first...
if ( aError )
{
// selection failed or cancelled ( aError == KErrCancel )
}
else
{
// ... and retrieve result
switch ( aMapView.SelectionResultType() )
{
case CMnMapView::ESelectionFreeLandmark:
{
// retrieve result landmark as free-location landmark
CPosLandmark* landmark = aMapView.RetrieveSelectionResultL();
...
delete landmark;
}
break;
case CMnMapView::ESelectionLandmarkIndex:
{
// retrieve result as index of one of non-linked landmarks,
// passed to CMnMapView::AddLandmarksToShowL
TInt index = KErrNotFound;
aMapView.RetrieveSelectionResultL( index );
}
break;
case CMnMapView::ESelectionLinkedLandmark:
{
// retrieve result landmark as one of linked landmark
TPosLmItemId id = KPosLmNullItemId;
HBufC* uri = NULL;
aMapView.RetrieveSelectionResultL( id, uri );
...
delete uri;
}
break;
default:
break;
}
}
}
Related APIs
CActiveCMnMapView::CancelCMnMapView::EOptionRestrictSelectionCMnMapView::SelectFromMapLCMnMapView::SelectionResultTypeCMnMapView::SetCustomRequestTextLCMnMapView::SetOptionsCMnMapView::SetUseDefaultRequestTextMSelectionObserver::HandleSelectionCompletedLShowMapL
Start navigation
This API also provides basic access to navigation services. Using the class
CMnNavigator the
client can engage navigation to a specified destination point. The starting
point is the current location and the destination is described by a landmark,
which must contain either coordinates or address information. The provider
application may implement navigation in different ways, not specified by this
API.
Related APIs
Error handling
This API uses only standard leave codes. Panic codes are defined
in the
mnerrors.h header file.
|
|
|
KMnPanicDuplicateRequest
|
Raised if client issues a new asynchronous request before the previous
one is completed or cancelled. For this API it happens if the client calls
CMnMapView::SelectFromMapL before
the previous request is completed or cancelled.
|
Related APIs
CMnMapView::SelectFromMapL
Memory overhead
The main concern about RAM usage is related to specifying landmarks to
be shown on the map. In order to reduce memory consumption it is recommended
to use overloads that accept landmarks database URI and set of landmark IDs,
if possible. Otherwise, all landmark data is copied when the landmark is prepared
to be sent to the provider application and thus more memory is required.
Extensions to the API
This API does not allow extending.
See also
See also related APIs:
Related APIs
CMnMapViewCMnMapView::SelectFromMapLCMnMapView::ShowCurrentLocationLCMnMapView::ShowMapLCMnNavigatorCMnNavigator::NavigateToLMAknServerAppExitObserverNewChainedLNewLRemoveObserverLSelectFromMapLSetObserverLTRequestStatus