Map and Navigation Provider APIChanges in Map and Navigation Provider API documentation
Changes in Map and Navigation Provider API
PurposeThis API provides interface for implementation by Map and Navigation Provider applications. It enables these applications to provide their map, navigation and geocoding services to the interested client applications in the system. It also defines how the provider application registers its support to these services within the system. This API is based on Server Application Service API concept (see the Symbian Foundation documentation for details). API descriptionThis is a Framework API: the client has to implement classes and methods defined by this API. It is intended for applications, which are capable of map, navigation and geocoding services and want to expose those to other applications. Further in the document these services will be referred to as "map and navigation services". This API does not implement map and navigation services itself but instead is a server side of a gateway between client applications and provider applications, which actually implement map views, navigation and geocoding requests. The client side of this gateway is represented by following APIs:
Use casesThe main use cases provided by the API are the following:
API class structureThis API provides three main interfaces to map and navigation features implementations:
These classes represent map and navigation services, which can be implemented
by provider application. They are derived from
In addition to the C++ classes, this API defines resource data structure
Related APIs
Using Map and Navigation APIRegister support of Map and Navigation servicesClient applications use APIs defined by Map and Navigation Framework to access Map and Navigation services. Services are defined by this API and implemented by provider applications. Map and Navigation FW serves as a gateway between clients and providers. There may be several provider applications in the system, which implement Map and Navigation services, and in order to expose these services to clients, provider applications must register in Map and Navigation FW. This will allow the system to find the provider application when a client application requests map and navigation services. Registration consists of two mandatory steps:
These steps are described in details in next chapters. Service support declarationThere are three Map and Navigation services defined in MnAppServiceUids.hrh. They correspond to three service classes defined by this API as shown in the following table. Applications may support all of these services or only some of them. If an application declares support for a service, it means that this application implements appropriate service classes defined by this API. Map and Navigation application services
Which services are supported is declared in application registration resource file (usually named in form MyApplication_reg.rss). This is generic technique for application servers and more details on that can be found from "Server applications" article in the Symbian platform document chapter "Application framework". Here only specifics related to Map and Navigation FW will be covered. Provider application lists implemented services in the
In this example, the application supports MapView service. Literally it
means that when queried by Application FW this application provides implementation
of this service. (Application returns its own implementation of the
Base service classes, defined in this API cover the whole services, but applications are not required to support all the functionality defined in these services. The application must specify what pieces of functionality, or "features", of each service are supported. In MnAppServiceUids.hrh file, the following service features are defined: Map and Navigation service features
Applications must explicitly specify, which features of each service are
supported, because this information is used by Map and Navigation FW to improve
performance of client's requests. For example, if it is known that the client
wants to show map views only, but is not interested in selection from map,
then M&N FW will return all providers, which support
Standard
In this example, application declares support for both features of
The complete example of registration file of hypothetical "TestProvider" application, which fully supports Map and Navigation services, is given below.
Note that the
Related APIs
Additional info in installation packageClients use Map and Navigation Provider Discovery API to get information
about available provider applications. The
This information is taken from applications installation package, which is required as part of application registration in Map and Navigation FW. For ROM-based applications a stub installation package must be provided. Installation package is also required for security reasons. Below is an example of installation package source file for the TestProvider application: See details about installation packages in the Symbian Foundation documentation.
Related APIs
Implement servicesThe main part of application's support of Map and Navigation services is implementation of service classes. Map and Navigation services are represented by three service classes, which
are derived from
If a service is not implemented, the provider application should not declare it in the resource file and then it will not be asked for these services by Application Framework and therefore does not need to implement the appropriate service class at all. All three service classes contain virtual methods, which represent separate
service features and must be implemented by the provider application, if service
support is declared. If some features are not supported, the implementation
must leave from appropriate methods with
Other methods are helpers and are not intended for implementation by provider application. From a high level, the provider application, when used as an application server, is operated as follows:
At the moment, only one service is requested from the application at the moment. If client requests another service from the same provider application, a new instance of application will be started. This is illustrated in the following diagram: Application startup The provider application should do two things at this stage:
The first step is achieved by calling
Determination of execution mode is done by overriding
Execution modes Provider application may be started in two different execution modes: standalone (the user can switch between client application and provider application), and "chained" (when the 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 chained mode is similar to the embedded mode with the exception that the child application (here, provider application) is running in its own process. In chained mode the provider application looks like one of the views of client application. It should display the "Back" button as right softkey instead of "Exit" to emphasize that pressing this button will return the user to the previous view in the application where the user originally was. The "Exit" option must still be present in the Options menu. By selecting this command the user can close the client application (as well as this provider application, of course). In standalone mode, the provider application looks as it would be started from the main menu and should behave as usual: the "Exit" button is shown. Creating server and services Override
Implement
See more details on that in the Symbian platform documentation. Service classes returned by server class must be implementations of base
service classes, defined by this API:
Service closure When service class is destroyed, the client is not interested in provider's service anymore. The further behavior of provider application depends on the mode it was started in:
The following examples explain these rules.
The application can handle this by overriding
The
Application closure The provider application may also be closed by the user, when they select
the "Exit" or "Back" command. The provider application must inform the client
correctly about the way it has been closed. This is done by calling
Implementing MapView serviceMapView service (
MapView service features-to-methods mapping
The provider application is not required to support all of the features
of the services. It must specify which features are supported in resource
file and provide leaving implementation for not supported ones. Implementation
must leave with
HandleShowMapL This method should be implemented in the way that map view is displayed on the screen. The actual content of the view is determined by the provider application, however it must obey parameters given by the client application. These additional parameters can be retrieved by calling protected methods
of
This is a synchronous request. Client's request is completed when this method exits, therefore it should exit immediately after the map view is shown. Landmarks arrays should not be accessed after returning from this method as they might be changed by the client application. Implementations should copy array data if later access to landmark lists is needed. Generally the implementation should ignore changes in other parameters
after exit from
Below is the diagram showing how provider applications should implement
the
Map view can be dismissed by the user by selecting the "Exit" or "Back" command. In that case the application must shut down informing the client about the exit reason as described in the beginning of this chapter. Below is the code example of how to read landmarks requested to be shown on the map. HandleShowCurrentLocationL Implementation of this method is very much the same as for
HandleSelectFromMapL This feature is asynchronous: implementation should show a map view on
the screen, from which the user can select a location, and exit from the method.
When the user selects a location (or cancels selection), implementation completes
the request with one of the
All the additional parameters defined for
Landmarks arrays are guaranteed to be unchanged until the request is not
completed or cancelled. It is done to make sure that indexes used with
There are some other parameters that can be specified by the client for this feature:
Below is the diagram showing how provider applications should implement
the
The application must not shut down if the user made a selection, the client will need to make another request for retrieving result data, and the application must keep alive to allow that. If the user has cancelled the selection (for example, by pressing the "Cancel" command), the application can close safely informing the client about exit. However it is not required, the client can close the application by destroying MapView service. Note: the application must not continue working if the MapView service is closed, because the user view (here, selection view) is already closed and is not needed for the user. This is contrary to simple map showing, where the view is not closed as part of sequence flow. Below is the dummy code example of completing selection request, where
the first landmark given by client is returned as selection result, if selection
was restricted, or a random location is returned. This code is assumed as
a part of member method of a class implementing
Related APIs
Implementing Navigation serviceNavigation service (
Navigation service feature-to-method mapping If the provider application declares support for the KMnAppNavigationService service, it must implement the KMnSvcFeatureNavigateTo feature, because it is the only feature of that service. If navigation is not supported no support for this service should be declared. HandleNavigateToL Navigation service is defined less strictly in comparison to MapView service.
Entry method
Implementation is supposed to activate the navigation view and return from this method as soon as the view is activated. Navigation view should execute the navigation or allow the user to start navigation. Exact navigation functionality is not defined, it may depend on application capabilities. For example, some applications implement full navigation with map view and voice guidance, while others can provide only route planning and so forth. Below is the diagram showing how provider applications should implement
Related APIs
Implementing Geocoding serviceGeocoding service (
Geocoding service features-to-methods mapping
Provider application is not required to support all of the features of
the services. It must specify which features are supported in resource file
and provide leaving implementation for not supported ones. Implementation
must leave with
All features of this service are asynchronous: implementation must return
from Handle methods as soon as possible and report completeness by calling
During processing this request if any ambiguity exists, the implementation can ask the user for clarification (for example, clarification of address information or selection of one of possible addresses for given coordinates in case of coordinate given in the middle of a street or joint). There is only one additional parameter, which must be taken into account:
HandleFindAddressByCoordinateL Implementation retrieves coordinate information from given landmark, and
starts searching for appropriate address information. When address information
is found, it must call
Below is the diagram showing how provider applications should implement
the
Below is the dummy example of serving and completing this request. In this
example, request is completed immediately upon receiving.
HandleFindCoordinateByAddressL with CPosLandmark input This method receives input as a landmark, which has address fields set. Every address field is a part of street address information, which makes it easier for implementation to understand where is the country name and where is the building number, etc. However, address information in the input might be incomplete (some fields are missing or text is incomplete). Implementation can ask user for clarification if allowed by options, otherwise it must attempt to do its best effort to solve ambiguities. Result should be given in the form of landmark, which coordinate corresponds to given address. Below is the dummy example of serving and completing this request. In this
example, request is completed immediately upon receiving.
HandleFindCoordinateByAddressL with plain string input This method receives address as a plain string, which requires from implementation some capabilities to analyze the input string and get the street address information from it. Ambiguities may be clarified from user if allowed by options. Result should be given in the form of landmark, the coordinate of which corresponds to the given address. Below is the dummy example of serving and completing this request. In this
example, request is completed immediately upon receiving.
Related APIs
Implementing MapImage serviceMapImage service (
MapImage service features-to-methods mapping
Provider application is not required to support all of the features of
the service. It must specify, which features are supported, in resource file
and implementation must leave with
All features of this service are asynchronous: implementation must return
from
Implementation of this service is supposed to render map image of an area
to a bitmap object supplied by client. Various parameters, which define what
area of world should be drawn and how, are defined in the
Projection and coordinate conversions Implementations can use different projections for map rendering (although it is not recommended to use projection, which cause heavy shape distortions). Usually the best approach is to use same projection as is used for normal map rendering as in MapView or Navigation services. That means there is no way for client to calculate world coordinates from image coordinates and vice versa. Therefore, implementation of this service must also provide implementation of Map Image Conversion Plug-In API: an ECom plug-in, which implements such coordinate conversions. This plug-in will be loaded into client's process. If given implementation utilizes several projections, it needs to inform
its coordinate conversion plug-in about how exactly an image was rendered
to be able to perform coordinate conversion appropriately. There is one parameter
in
Even if the current version of the provider application utilizes only single projection, it might be useful to assign it an ID and use it in this field. This may help to ensure future compatibility of different versions of this service implementation and coordinate conversion plug-in. See Map Image Conversion Plug-In API for further details on implementing coordinate conversion plug-in. Visible items The
One specific note goes to the
HandleRenderingL Implementation reads map image parameters from
The main option to consider is
This is asynchronous request and implementation should exit this method
as soon as possible. When rendering is completed, it should complete this
request by calling
If this request is cancelled by the client during processing, then
Below is the diagram showing how provider applications should implement
this service.
Below is the dummy example of serving and completing this request. In this
example, request is completed immediately upon receiving.
Related APIs
Related APIs
Implementation guidelinesThe behavior of provider application affects look and feel of client applications. Therefore below some implementation guidelines are given, which should be followed. It will help to keep overall user experience generic and good. Split implementationMap and Navigation application deal with a large amounts of content data and implement a number of use cases. This implies that such applications are complex but also that they are big. Startup times may be high due to the need to allocate huge amounts of memory, initialize many internal engines. However, when executed via Map and Navigation FW, not all features of applications are needed. For example, when serving geocoding, rendering engine is not needed and therefore should not be initialized. If clarification dialog is disabled, then no UI needed at all and it also should not be loaded. Landmark data is not used in this use case and so no connection to landmark databases should be open. The main thing to be considered is that Map and Navigation FW starts new instance of the provider application for every new connection made by client. It means that if client uses MapView, Navigation and Geocoding services, it will start three instances of the application. The best approaches are:
Minimize service start-up timeWhen started in server mode, the provider application should minimize time, required for getting the user to the target view. The application should not start with default views, which take long time to load. The application should not try to load all resources it needs in normal case, until service class is created and it is clear what is required by client application and what needs to be loaded and what can be omitted. For example, there is no need to load all landmarks from all landmark databases for map view service, because only those landmarks, which are requested by client, need to be shown. Running backgroundGeocoding service should not show any UI, if disabled by client. However, when server application is started it shows still by default some UI elements: command and status bars. This should be avoided and it can be achieved by moving implementation of geocoding service to a separate application, which is started in background. The same applies for the MapImage service. It also should be run in the background, because clients draw rendered map image bitmaps on their own UI. This can be done by putting directive
into application's APP_REGISTRATION_INFO resource.As such this application makes no interest for user and therefore it should be hidden from main menu. This is done by adding to
the same resource.Following is the full example of such registration file.
Related APIs
Reuse navigating instanceIf several navigation views are running at the same time (which is possible, if the user starts it from different applications), the user gets "not best" experience. It is recommended that the provider application, when requested for navigation, tries to identify if some other of its instances is already running navigation and cancels that navigation in favor of a newly started one. For better compatibility it should be done in the way as if the user would stop old navigation manually (i.e. by closing old navigating instance). SecurityImplementations must not compromise Platform Security. That means that when and if the client's request requires some functionality, which is usually protected by capabilities, those capabilities must be checked and in case of absence of such, operation must not be performed. Let's consider implementations, which store their content on network. Some
or all client requests may require accessing network in order to execute them.
If client does not have the
Client capabilities can be read from the message object, which is involved
in every communication between client and server.
When service is refused due to lack of capabilities, implementation must
complete client's request with error code
Related APIs
Error handlingThis API uses standard leave codes of the Symbian platform. Panic codes are defined in the mnerrors.h header file.
Provider application reports the following error codes for specific cases:
Related APIs
Memory overheadThe main concern about RAM usage is related to set of landmarks requested
to be shown on map. The clients can send landmarks as instances, not only
as linked landmarks, these instances are kept in provider application's memory
(implementation of
Related APIs
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|
