S60 Map and Navigation AIW API |
DN0667577 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.0 |
12.09.2006 |
Approved |
|
![]() |
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.
![]() |
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).
![]() |
The main use cases provided by the API are the following:
![]() |
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.
![]() |
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.
![]() |
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
![]() |
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 ); }
![]() |
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:
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 ); }
![]() |
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.
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. |
_LIT( KRequestText, "Select some location" ); TAiwGenericParam param( EGenericParamRequestText, TAiwVariant( KRequestText ) ); aParamList.AppendL( param );
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; }
![]() |
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.
![]() |
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.
![]() |
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) |
![]() |
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.
![]() |