S60 Map and Navigation API

DN0667838
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

16.10.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API Description
Use cases
API class structure
Using the Map and Navigation API
Show map
Show map of an area
Show landmarks on map
Show map from current location
Show landmarks on map code example
Select location from map
Start navigation
Error handling
Memory overhead
Extensions to the API
See also
Glossary
Abbreviations
Definitions
References

 


Purpose

This API enables client to access map and navigation features of the provider application. Following are the most important use cases: showing map (optionally with landmarks), selecting a location from map, engaging navigation.

 


S60 or Symbian OS exceptions

This API is available from S60 release 3.2 onwards.

 


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:

  • Show map
    • Show map of an area
    • Show landmarks on map
    • Show map from current location
  • Select a location from map
  • Start navigation

 


API class structure

This API provides two main interfaces to map and navigation features:
  • CMnMapView - for displaying map on screen
  • CMnNavigator - for starting navigation

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.

Figure 1: Map and Navigation API Class Structure

 


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:
  • The provider application closes too, if started in chained (embedded) mode.
  • If started standalone:
    • if no views are open (e.g. map view or navigation view), the provider application closes.
    • if any view is open, the provider application remains running until closed by the user.
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.
Figure 2: Typical sequence for chained mode

Following diagram depicts typical sequence when provider is executed in standalone mode.

Figure 3: Typical sequence for 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.

Figure 4: Show Map of an Area sequence diagram

 


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.
Figure 5: Show Landmarks on Map sequence diagram

 


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.

 


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 );
}

 


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.

Figure 6: Select From Map sequence diagram

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;
            }
        }
    }    

 


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.
Figure 7: Start Navigation sequence diagram

 


Error handling

This API uses only standard Symbian OS leave codes. Panic codes are defined in the mnerrors.h header file.
Panic code Reason
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.

 


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:
  • Map and Navigation Provider Discovery API
  • Geocoding API
  • Map and Navigation AIW API
  • Landmarks API
  • Location Acquisition API

 


Glossary

 


Abbreviations

Table: Abbreviations
None  

 


Definitions

Table: 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 this features for clients of Map and Navigation API and Geocoding API.

 


References

None

 

Back to top