S60 Map and Navigation Provider Discovery API

DN0669115
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

10.12.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API Description
Use cases
API class structure
Using the Map and Navigation Provider Discovery API
Find providers
Find all providers
Find providers by services
Retrieve provider information
Error handling
Memory overhead
Extensions to the API
See also
Glossary
Definitions

 


Purpose

This API enables client to find out what provider applications are installed and available to use with Map and Navigation API and Geocoding API and retrieve their related information.

 


S60 or Symbian OS exceptions

This API is available from S60 release 3.2 onwards.

 


API Description

This API is intended for applications, which utilize Map and Navigation API and/or Geocoding API. It gives access to the list of available provider applications, which can be used with those APIs and detailed information about them.

 


Use cases

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

  • Find provider applications:
    • Find all provider applications
    • Find provider applications by services
  • Retrieve provider application information

 


API class structure

This API provides two main classes:
  • CMnProvider - includes information about the provider application, related to Map and Navigation and Geocoding APIs
  • MnProviderFinder - allows discovering available provider applications.
Figure 1: Map and Navigation Provider Discovery API Class Structure
MnProviderFinder is a static class. The CMnProvider instance can be only retrieved from the result of discovery operations executed by MnProviderFinder.

 


Using the Map and Navigation Provider Discovery API

This API is a helper for Map and Navigation API and Geocoding API. Its main purpose is to find provider applications, which can be used with these APIs, and supply related information on them.

 


Find providers

In order to find provider applications for map view, navigation and geocoding services, the client uses the MnProviderFinder class. It is a static class, which implements two use cases: find all provider applications or find only those applications, which support specific features.

 


Find all providers

The MnProviderFinder class defines the overload of the FindProvidersL method, which accepts only one parameter - output list of pointers to the provider information class, CMnProvider. The result is the list of all provider applications available in the system. Detailed information about what particular services they support can be found in the CMnProvider::SupportedServices method.
Figure 2: Find All Providers sequence diagram

The following example shows how to find a specific provider application (explicitly identified by its application UID) among all available provider applications. The example is given in the form of a function, which retrieves a list of all providers, compares all providers with the given UID and returns the matching one, if found. The client gets ownership of the object. The function leaves if no match is found.

CMnProvider* GetProviderL( TInt aUid )
{
    CMnProvider* provider = NULL;
    RPointerArray<CMnProvider> providers;

    // get all providers
    MnProviderFinder::FindProvidersL( providers );

    // now find the one, which matches given UID
    for ( TInt i = 0; i < providers.Count(); i++ )
        {
        if ( providers[i]->Uid().iUid == aUid )
            {
            provider = providers[i];
            break;
            }
        }

    // cleanup array and return result
    if ( provider )
        {
        // if found, remove it from the array
        TInt pos = providers.Find( provider );
        providers.Remove( pos );

        // others are destroyed
        providers.ResetAndDestroy();
        }
    else
        {
        // if nothing's found, destroy all and leave
        providers.ResetAndDestroy();
        User::Leave( KErrNotFound );
        }
    return provider;
    }

 


Find providers by services

If a client is only interested in providers, which support particular services, it can retrieve such a list by calling another overload of the FindProvidersL method, the one which accepts the second argument of type CMnProvider::TServices. This data type is a bitmap of constants, defined in CMnProvider::TService, each of which represents a specific map and navigation service. Provider applications, which do not support any of the specified services are not returned.
Figure 3: Find providers by services sequence diagram

The following example shows how to find a provider application, which supports specified services among all available provider applications. The example is given in the form of a function, which retrieves a list of providers, supporting specified services and returns the first one found. The client gets ownership of the object. The function returns NULL if a match is not found.

CMnProvider* GetFirstProviderL( CMnProvider::TServices aServicesNeeded )
    {
    RPointerArray<CMnProvider> providers;

    MnProviderFinder::FindProvidersL( providers, aServicesNeeded );

    TInt count = providers.Count();
    CMnProvider* provider = NULL;

    if ( count )
        {
        provider = providers[0];
        providers.Remove( 0 );
        }

    providers.ResetAndDestroy();
    return provider;
    }

The input parameter of the function is the bitmap of service constants, defined in the CMnProvider class. Callers may request that the provider should support only a single service or a set of services.

// find provider for map view service
CMnProvider* mapViewProvider = GetFirstProviderL( CMnProvider::EServiceMapView );

// find provider for geocoding and navigation services
const CMnProvider::TServices neededServices = 
       CMnProvider::EServiceNavigation | 
       CMnProvider::EServiceGeocoding;
CMnProvider* geocodingAndNavigationProvider = GetFirstProviderL( neededServices );

Note that in the latter case, if no providers support both geocoding and navigation services, NULL is returned.

 


Retrieve provider information

Provider application information can be retrieved from the CMnProvider class. Methods of the class return various information about the provider application, such as application and vendor localized names, application UID and version, supported services. See CMnProvider class documentation for details.

 


Error handling

This API uses only standard Symbian OS leave codes.

 


Memory overhead

The RAM 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 API
  • Geocoding API

 


Glossary

 


Definitions

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

Back to top