Map and Navigation AIW API
Changes in Map and Navigation AIW API documentation
| Version |
Date |
Status |
Description |
|
1.0
|
12.09.2006
|
Approved
|
|
Changes in Map and Navigation AIW API
| Version |
Description |
|
1.0
|
First release
|
PurposeThis 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.
ConstraintsThis API is available on S60 release 3.2 and later.
API DescriptionThis 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 casesThe 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 structureThis 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
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.
Related APIs
CPosLandmarkKAiwCmdMnAddrByCoordKAiwCmdMnCoordByAddrKAiwCmdMnNavigateToKAiwCmdMnSelectFromMapKAiwCmdMnShowMapPosLandmarkSerializationTMnAiwCommonOptionsParamTMnAiwGeocodingOptionsParamTMnAiwMapViewOptionsParam
Using the Map and Navigation AIW APIThe 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:
-
Optional - this parameter may or may not be specified. If omitted, then
default values are used.
-
Mandatory - this parameter must be specified, otherwise service command
leaves with
KErrArgument.
They also may be:
-
Multiple - can be specified multiple times in
CAiwGenericParamList
-
Single - only single parameter of that type is expected in
CAiwGenericParamList.
If specified more than once, then only the first occurrence is used and any
other ones are ignored
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 mapThis 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 areaThe 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 ); }
Related APIs
CMnMapViewEGenericParamMnMapViewOptionsTMnAiwMapViewCommonOptions
Show landmarks on mapThis 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 ); }
Related APIs
CPosLandmarkPosLandmarkSerialization
Related APIs
EGenericParamLandmarkEGenericParamLandmarkDatabaseEGenericParamLandmarkIdEGenericParamLandmarkIdListEGenericParamMnCommonOptionsEGenericParamMnMapViewOptionsKAiwCmdMnShowMap
Select from mapThis 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; }
Related APIs
CAiwServiceHandlerCMnMapView::EOptionRestrictSelectionEGenericParamLandmarkEGenericParamLandmarkDatabaseEGenericParamLandmarkIdEGenericParamLandmarkIdListEGenericParamMnCommonOptionsEGenericParamMnMapViewOptionsEGenericParamRequestTextHandleNotifyLKAiwCmdMnSelectFromMapKAiwEventCompletedMAiwNotifyCallbackTMnAiwMapViewOptionsParam::iOptions
Start navigationAllows 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.
Related APIs
EGenericParamLandmarkEGenericParamMnCommonOptionsKAiwCmdMnNavigateTo
Resolve coordinates by addressStarts 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.
Related APIs
CAiwServiceHandlerEGenericParamLandmarkEGenericParamMnCommonOptionsEGenericParamMnGeocodingOptionsEGenericParamUnspecifiedEVariantTypeDesCKAiwCmdMnCoordByAddrKAiwEventCompletedMAiwNotifyCallbackTAiwVariant
Resolve address by coordinatesStarts 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.
Related APIs
CAiwServiceHandlerEGenericParamLandmarkEGenericParamMnCommonOptionsEGenericParamMnGeocodingOptionsKAiwCmdMnAddrByCoordKAiwEventCompletedMAiwNotifyCallback
ParametersThis 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)
|
Related APIs
)CBufFlatEGenericParamLandmarkIdEGenericParamLandmarkIdListPosLandmarkSerialization::PackLPosLandmarkSerialization::UnpackLTMnAiwCommonOptionsParamTMnAiwGeocodingOptionsParamTMnAiwMapViewOptionsParamTPosLmItemId
Error handlingThe 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 error codes defined in
e32err.h.
Related APIs
CAiwServiceHandler::ExecuteMenuCmdLCAiwServiceHandler::ExecuteServiceCmdLMAiwNotifyCallback::HandleNotifyL
Memory overheadThe memory usage of this API does not exceed usual overhead related to
object creation.
Extensions to the APIThis API does not allow extending.
See alsoSee also related APIs:
Related APIs
CAiwGenericParamListCAiwServiceHandlerEVariantTypeDesC8ExecuteMenuCmdLExecuteServiceCmdLInitialiseLInitializeMenuPaneLKAiwEventCompletedKErrArgumentKErrNotSupportedMAiwNotifyCallbackTMnAiwCommonOptionsParamTPckgTPtr8
Glossary
Abbreviations
Abbreviations
|
AIW
|
Application Interworking
|
|
FW
|
Framework
|
Definitions
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.
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|