S60 Map and Navigation AIW API

DN0667577
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

12.09.2006

Approved

 


Table of Contents

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

 


Purpose

This API enables the client to access map and navigation features of the provider application via AIW (Application Interworking). Following are the most important use cases: showing map (optionally with landmarks), selecting a location from map, engaging navigation, fetching address by coordinates and coordinates for address information.

 


S60 or Symbian OS exceptions

This API is available on S60 release 3.2 and later.

 


API Description

This API is intended for end-user applications, which possess any location-related information and wish to use it with map and navigation features. This is an AIW extension 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, navigation and geocoding. 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 they are executed in a separate application.

As an AIW extension API, this API allows application access map and navigation features, same as provided by Map and Navigation API and Geocoding API, without statically linking to corresponding libraries. Client applications only needs to link against AIW FW libraries (servicehandler.lib) and Landmarks API libraries in order to utilize data types defined by that API and used in protocol defined by this API (Map and Navigation AIW API).

 


Use cases

The main use cases provided by the API are the following:

  • Show map
  • Select a location from map
  • Start navigation
  • Resolve street address by coordinates
  • Resolve coordinates by street address

 


API class structure

This API does not provide any methods a client could call. Instead it defines a communication protocol, with which a client can invoke map and navigation services, provided by external applications (Provider Applications) via AIW Service Handler API. AIW Criteria API defines map and navigation AIW commands (in aiwcommon.hrh) and AIW Generic Parameter API defines parameter types (in aiwgenericparam.hrh). Following AIW commands for map and navigation services are defined by AIW Criteria API :
  • KAiwCmdMnShowMap - shows map view
  • KAiwCmdMnNavigateTo - starts navigation
  • KAiwCmdMnSelectFromMap - starts location selection (from map) request for user
  • KAiwCmdMnAddrByCoord - resolves street address for a given coordinate
  • KAiwCmdMnCoordByAddr - resolves coordinate for a given street address
This API defines several data structures, which are used as AIW parameters:
  • TMnAiwCommonOptionsParam - common options for all services
  • TMnAiwMapViewOptionsParam - options for map view service
  • TMnAiwGeocodingOptionsParam - options for geocoding service
Figure 1: Map and Navigation AIW API Class Structure

This API uses landmark objects as location-related data container. The CPosLandmark class from Landmarks API defines runtime landmark object data type. The client has to convert it to a plain buffer for transmission to provider applications by using the PosLandmarkSerialization class. The same class allows the client to reconstruct the CPosLandmark class from the buffer sent back from the provider application as a result of a requested operation. The following chapters contain more details on this.

 


Using the Map and Navigation AIW API

The client uses this API via AIW FW, AIW Service Handler API. That API provides methods to invoke specific map view, navigation and geocoding services. AIW FW allows services to be invoked directly by service command ID, or as a menu command. This API supports both types of invocation.

The client shall use CAiwServiceHandler methods to issue commands. See ExecuteServiceCmdL and ExecuteMenuCmdL methods for details. Some services are asynchronous, they require the MAiwNotifyCallback parameter. If it is NULL, then Execute methods leave with KErrArgument.

At the initialization phase (InitializeMenuPaneL and InitialiseL) any input and output parameters are ignored.

Parameters, which are defined as structures and with Semantic Id EVariantTypeDesC8, can be passed as TPckg or TPtr8.

Result of asynchronous operations is reported by KAiwEventCompleted event via MAiwNotifyCallback.

Wherever an address or coordinates are needed from a passed landmark, and they are missing, the result is KErrArgument.

Service command parameters may be:

They also may be:

The order of parameters is not defined if not specified otherwise.

This API relies on functionality provided by external applications, Provider Applications, which are executed in a separate process from the client. The client can specify in which mode those applications should be executed for each issued command.

There are two execution modes available: standalone (the user can switch between the client application and the provider application), 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). The client specifies the required mode using the TMnAiwCommonOptionsParam parameter. For each command the client invokes, a provider application is selected (by asking the user if many are found for this particular command), started, command executed and provider application disconnected. This means that issuing two commands (same or different) creates two different instances of the provider application.

The client application shall create AIW criteria for MIME datatype "application/x-landmark" to register AIW interest for map and navigation services. All service commands are independent and only a single menu item is created for a single service ID. Not all provider applications support all service commands. If the command is not supported by any provider application, then no menu item is available for this command and the result of direct command execution is KErrNotSupported.

The next chapters contain a detailed description of available commands and their parameters.

 


Show map

This is a basic AIW command related to landmarks. The client can request that the map should be displayed on screen and supply a set of landmarks to be shown on the map; specify the desired map area and whether the current location is to be drawn. Without any parameters, the last shown map is shown. See more details in the Parameters section.

Command ID:

KAiwCmdMnShowMap

Input parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Optional, Multiple Landmarks to be shown on map.
EGenericParamLandmarkDatabase followed by one or more EGenericParamLandmarkId or EGenericParamLandmarkIdList Optional, Multiple Linked landmarks to be shown on map.
EGenericParamMnMapViewOptions Optional, Single Various additional parameters, with detail on how the map should be shown.
EGenericParamMnCommonOptions Optional, Single Common options.

An area covering all specified landmarks is visible on the screen, unless the area radius is also specified in options parameter.

Output parameters:

None

 


Show map of an area

The simplest case is showing the map of some area. The area is defined by central point and radius. The central point is the coordinate of the location on the globe and radius (in meters) defines what minimal area around this location must be visible in the map view. These and other options are specified by the client as the input parameter EGenericParamMnMapViewOptions in the TMnAiwMapViewCommonOptions structure. The options have the same meaning as defined in CMnMapView from Map and Navigation API.

void CClientClass::ShowSimpleMapL( const TCoordinate& aCenter, TReal aRadius )
{
CAiwGenericParamList* inList = CAiwGenericParamList::NewL();
CleanupStack::PushL( inList );
CAiwGenericParamList* outList = CAiwGenericParamList::NewL();
CleanupStack::PushL( outList );

TMnAiwMapViewCommonOptions mapOptions;
mapOptions.iCenterPoint = aCenter;
mapOptions.iRadius = aRadius;
// to see current location mark, if visible in this area
mapOptions.iCurrentLocationOption = CMnMapView::ECurrentLocationEnabled;

TPckg<TMnAiwMapViewCommonOptions> mapOptionsPack( mapOptions );
TAiwGenericParam mapOptParam( EGenericParamMnMapViewOptions, TAiwVariant( mapOptionsPack ) );
inList->AppendL( mapOptParam );

// to run provider application chained
TMnAiwCommonOptionsParam options;
options.iRunChained = ETrue;

TPckg<TMnAiwCommonOptionsParam> optionsPack( options );
TAiwGenericParam optParam( EGenericParamMnCommonOptions, TAiwVariant( optionsPack ) );
inList->AppendL( optParam );

// Execute command
// (assuming iAiwServiceHandler is initialized member variable of type CAiwServiceHandler* )
iAiwServiceHandler->ExecuteServiceCmdL( KAiwCmdMnShowMap, *inList, *outList, 0, NULL );

// out list is ignored
CleanupStack::PopAndDestroy( outList );
CleanupStack::PopAndDestroy( inList );
}

 


Show landmarks on map

This case is very similar to showing the 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 a list or array of IDs of landmarks and URI of the landmark database, where those landmarks exist. Landmarks IDs should be preceded by database URI. This is the most efficient way in terms of memory consumption and is recommended to use whenever applicable.
  • Packed landmarks - the client specifies an array of instances of the CPosLandmark class, packed with PosLandmarkSerialization. Use it for landmarks, which are not stored in the landmark database. Note that due to the fact that database information is not available for the provider application, the category data from these landmarks cannot be used in the map view. As the packed landmark is essentially a copy of all landmark data, it is recommended to avoid this approach whenever possible, because it is very memory-hungry.

Any mix of landmark parameters can be used, but it is necessary that the list of landmark IDs (whether specified as a single array or as separate parameters) is immediately preceded by a database URI parameter of the database these landmarks belong to.

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.

Here are some examples of how a client can specify what landmarks should be shown on the map view, before the command is invoked.

// This method adds linked landmarks to the parameter list, 
// i.e. those residing in a database
void CClientClass::AddLinkedLandmarksToParamListL(
    const TDesC& aDatabaseUri, 
    RArray<TPosLmItemId>& aItemIds,
    CAiwGenericParamList& aParamList )
{
// first, add database URI
TAiwGenericParam param( EGenericParamLandmarkDatabase, TAiwVariant( aDatabaseUri ) );
aParamList.AppendL( param );

// then add landmark IDs, which belong to this database
for ( TInt i = 0; i < aItemIds.Count(); i++ )
    {
    TAiwGenericParam param( EGenericParamLandmarkId, TAiwVariant( aItemIds[i] ) );
    aParamList.AppendL( param );
    }
}
// This method adds landmarks, which are not in any database yet
void CClientClass::AddLandmarkToParamListL( 
    const CPosLandmark& aLandmark,
    CAiwGenericParamList& aParamList )
{
// pack landmark to a buffer
HBufC8* lmBuf = PosLandmarkSerialization::PackL( aLandmark );
CleanupStack::PushL( lmBuf );

// create parameter and add it to the parameter list
TAiwGenericParam param( EGenericParamLandmark, TAiwVariant( *lmBuf ) );
aParamList.AppendL( param );

CleanupStack::PopAndDestroy( lmBuf );
}

 


Select from map

This command allows the client to request that the user shall select a location from map. A map view with request text (e.g. "Select From Map") is shown to the user.

All options are applicable in the same way as they are for the Show Map command, 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 landmarks specified by the client (or refuse selection). Set CMnMapView::EOptionRestrictSelection to TMnAiwMapViewOptionsParam::iOptions and add it to the input parameter list.
  • Request text - the client specifies that the user can see specific request text, such as "Select destination", when asked to select a location. If not set, the default localized text is shown. Add the EGenericParamRequestText parameter to the input parameter list to override default text.
This is an asynchronous request. Completion is reported via MAiwNotifyCallback by KAiwEventCompleted. It is not possible to cancel the request explicitly, but it is automatically cancelled if the instance of CAiwServiceHandler, which was used to issue the request, is destroyed.

The selection result is returned in the form of a landmark ID and database URI (if one of linked landmarks has been selected) or as landmark instance (if any other location has been selected by the user). The user can select only one location and only one landmark is returned as result.

Command ID:

KAiwCmdMnSelectFromMap

Input parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Optional, Multiple Landmarks to be shown on map.
EGenericParamLandmarkDatabase followed by one or more EGenericParamLandmarkId or EGenericParamLandmarkIdList Optional, Multiple Linked landmarks to be shown on map.
EGenericParamMnMapViewOptions Optional, Single Various additional parameters, with detail on how the map should be shown.
EGenericParamMnCommonOptions Optional, Single Common options.
EGenericParamRequestText Optional, Single Custom request text for selection query. If missing or empty, then default text is used.

An area covering all specified landmarks is visible on screen, unless the area radius is also specified in options.

Output parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Optional, Single This is returned if one of given non-linked landmarks or a free location is selected.
EGenericParamLandmarkDatabase followed by EGenericParamLandmarkId Optional, Single These two parameters are returned if the selected landmark belongs to a database. This is always one of the landmarks specified for input.

The client can override default request text, before the command is invoked, as follows:
_LIT( KRequestText, "Select some location" );
TAiwGenericParam param( EGenericParamRequestText, TAiwVariant( KRequestText ) );
aParamList.AppendL( param );
The client application inherits from MAiwNotifyCallback and overrides HandleNotifyL in order to retrieve the result of this asynchronous request.
TInt CClientClass::HandleNotifyL(
    TInt /*aCmdId*/, TInt /*aEventId*/,
    CAiwGenericParamList& aEventParamList,
    const CAiwGenericParamList& /*aInParamList*/)
{
if ( aEventParamList.Count() && aEventParamList[0].SemanticId() == EGenericParamError )
    {
    // request failed, retrieve error code
    TInt error = aEventParamList[0].Value().AsTInt32();
    }
else if ( iOutList->Count() )
    {
    const TAiwGenericParam& param1 = (*iOutList)[0];
    if ( EGenericParamLandmark == param1.SemanticId() )
        {
        TPtrC8 landmarkData( param1.Value().AsData() );
        CPosLandmark* landmark = PosLandmarkSerialization::UnpackL( landmarkData );
        ...
        delete landmark;
        }
    else if ( EGenericParamLandmarkDatabase == param1.SemanticId() && 
              iOutList->Count() > 1 )
        {
        // EGenericParamLandmarkDatabase is defined as EVariantTypeDesC 
        TPtrC dbUri( param1.Value().AsDes() );

        // next param must be EGenericParamLandmarkId
        const TAiwGenericParam& param2 = (*iOutList)[1];
        if ( EGenericParamLandmarkId == param2.SemanticId() )
            {
            // EGenericParamLandmarkId is defined as EVariantTypeTInt32
            TPosLmItemId landmarkId = param2.Value().AsTInt32();
            }
        }
    else
        {
        // unknown parameter, ignore
        }
    }
else
    {
    // unexpected event, ignore
    }
return KErrNone;
}
    

 


Start navigation

Allows to start navigation to a desired destination. 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 (for example, it can be voice-guided navigation or just displaying route on map or as a list of turns, etc.). It is not possible to control navigation from the client side, only the user controls it by means of UI elements provided by the navigation application. This command is completed as soon as the navigation is started in the provider application. There is no notification when the user reaches the destination.

Command ID:

KAiwCmdMnNavigateTo

Input parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Mandatory, Single A landmark, which defines the destination point of navigation.
EGenericParamMnCommonOptions Optional, Single Common options.

Output parameters:

None.

The client invokes this command in the same way as shown in the code example in the Show map of an area section.

 


Resolve coordinates by address

Starts the geocoding request: finding coordinate by a given address. The address is specified as landmark, whose address information fields are used as address. The result container is specified as a landmark, whose coordinates are set as the result of conversion. The address can alternatively be specified as plain string.

This is an asynchronous request. Completion is reported via MAiwNotifyCallback by KAiwEventCompleted. It is not possible to cancel the request explicitly, but it is automatically cancelled if the instance of CAiwServiceHandler, which was used to issue the request, is destroyed.

Command ID:

KAiwCmdMnCoordByAddr

Input parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark or Plain string Mandatory, Single A landmark or a string, which defines the address. In the latter case Variant Type of the TAiwVariant parameter must be set as EVariantTypeDesC and Semantic ID is EGenericParamUnspecified.
EGenericParamMnGeocodingOptions Optional, Single Defines additional parameters of geocoding operation.
EGenericParamMnCommonOptions Optional, Single Common options.

Output parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Single A landmark, containing conversion result.

The client invokes this command and retrieves the result in the same way as shown in the code example in the Select From Map section.

 


Resolve address by coordinates

Starts the reverse geocoding request: finding address for a given coordinate. The coordinate is specified as a landmark, whose coordinate is used as input. The result container is specified as a landmark, whose address information fields is set as the result of the conversion.

This is an asynchronous request. Completion is reported via MAiwNotifyCallback by KAiwEventCompleted. It is not possible to cancel the request explicitly, but it is automatically cancelled if the instance of CAiwServiceHandler, which was used to issue the request, is destroyed.

Command ID:

KAiwCmdMnAddrByCoord

Input parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Mandatory, Single A landmark, which defines the coordinate.
EGenericParamMnGeocodingOptions Optional, Single Defines additional parameters of geocoding operation.
EGenericParamMnCommonOptions Optional, Single Common options.

Output parameters:

Parameter semantic id Occurrence Description
EGenericParamLandmark Single A landmark, containing conversion result.

The client invokes this command and retrieves the result in the same way as shown in the code example in the Select From Map section.

 


Parameters

This section describes parameters used for Map and Navigation AIW services. For every parameter its semantics and datatype are shown.

Meaning Semantic ID Type ID Description
Landmark EGenericParamLandmark EVariantTypeDesC8 Used to send a landmark instance to provider. The landmark is sent as a buffer, which contains landmark data and considered as not linked to any database. Thus its category information is unavailable for the provider application. Landmark can be packed into buffer using PosLandmarkSerialization::PackL from Landmarks API. Landmark can be unpacked from buffer using PosLandmarkSerialization::UnpackL from Landmarks API.
Landmark Database EGenericParamLandmarkDatabase EVariantTypeDesC In case the consumer wants to send a linked landmark, the database URI (as defined in Landmarks API, see CPosLandmarkDatabase::OpenL(const TDesC& aDatabaseUri)) shall be supplied by this parameter. It must be followed by the series of EGenericParamLandmarkId or EGenericParamLandmarkIdList. All landmark IDs found in the following parameter are considered from the database, specified in this parameter. Any landmark IDs not preceded with database URI are ignored.
Landmark ID EGenericParamLandmarkId EVariantTypeTInt32 In case the user wants to send a linked landmark, the landmark ID shall be supplied by this parameter. Its content is a single TPosLmItemId (defined in Landmarks API).
Landmark ID List EGenericParamLandmarkIdList EVariantTypeDesC8 In order to improve the performance in case the user wants to send a set of linked landmarks, landmark IDs shall be supplied by this parameter. Its content is a list of TPosLmItemId items (defined in Landmarks API) packed into flat buffer (see CBufFlat).
Common options parameter EGenericParamMnCommonOptions EVariantTypeDesC8 Common options for all Map and Navigation AIW commands. The content is a pointer descriptor of the structure TMnAiwCommonOptionsParam.
Map View command options EGenericParamMnMapViewOptions EVariantTypeDesC8 Options for services launching map views. The content is a pointer descriptor of the structure TMnAiwMapViewOptionsParam.
Geocoding common options EGenericParamMnGeocodingOptions EVariantTypeDesC8 Common options for geocoding services. The content is a pointer descriptor of the structure TMnAiwGeocodingOptionsParam.
Request text EGenericParamRequestText

EVariantTypeDesC Specifies the custom request text for commands, where the request to the user is shown. (E.g. the Select From Map command)

 


Error handling

The client is informed about command execution failure in two different ways, depending on the command nature. For synchronous commands, CAiwServiceHandler::ExecuteServiceCmdL or CAiwServiceHandler::ExecuteMenuCmdL leave in error case. For asynchronous operations, errors are reported as the first parameter in the event parameter list argument of MAiwNotifyCallback::HandleNotifyL as shown in the code example in Section Select From Map.

Error codes are standard Symbian OS error codes defined in e32err.h.

 


Memory overhead

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

 


Glossary

 


Abbreviations

Table: Abbreviations
AIW Application Interworking
FW Framework

 


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