S60 Map Image Conversion Plug-In API

DN0735015
CONFIDENTIAL

©Nokia Corporation and/or its subsidiaries 2007
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

23.02.2007

Approved

 


Table of Contents

Purpose
API availability
API description
Use cases
API class structure
Using Map Image Conversion Plug-In API
Implementing coordinate converter
Image to world coordinate conversion
World to image coordinate conversion
Creating ECom plug-in
Examples
Error handling
Memory overhead
Extensions to the API
See also
Glossary
Abbreviations
Definitions
References

 


Purpose

This API is intended for implementation by Map and Navigation provider applications, which support MapImage service. This API declares ECom interface, which exposes two functions for converting world coordinates to image coordinates and vice versa. This functionality is used by Map Image API implementation.

This document is intended for developers of Map and Navigation provider applications, which are going to support MapImage service.

 


API availability

This API is available since S60 release 5.0.

 


API description

This API is a method call Framework API.

The implementation of this API is the second part of Map and Navigation Provider application's support for the MapImage service. Service itself implements map rendering and is part of the provider application server. Rendering engines can use various projections and the client needs a way to calculate world coordinates corresponding to a particular point on map image and vice versa. Such functionality is exposed by provider applications by implementing this API.

The implementation of this API is loaded as ECom plug-in into the process of the client of Map Image API.

 


Use cases

The main use case of this API is:
  • Implementing coordinate conversions.

 


API class structure

CMnCoordinateConverterBase is the base class for implementation. It declares two virtual methods, which give access to actual coordinate conversions:
  • GetWorldCoordinate - finds world coordinate corresponding to an offset on map image
  • GetImageCoordinate - finds offset in map image corresponding to given world coordinate
Such calculation requires additional information used during image rendering and implementations access it via the MapImageParams() method.
Figure 1: Map Image Conversion plug-In API class structure

 


Using Map Image Conversion Plug-In API

In order to complete support for MapImage service and implement coordinate conversion plug-in, the Map and Navigation Provider application has to:
  1. Create a class derived from CMnCoordinateConverter and implement its abstract methods.
  2. Create an ECom plug-in DLL and export a factory function, which returns pointer to the new instance of that class.

 


Implementing coordinate converter

Coordinate converter should create a class derived from CMnCoordinateConverter and implement its two abstract functions. These two functions together should allow the client to perform image-to-world and world-to-image type of coordinate conversion an infinite amount of time.

The image itself is not provided for calculations, but instead the all input given to rendering engine is accessible via MapImageParams() (which returns reference to the TMnMapImageParams class, defined in Map Image API). In addition to client-defined parameters, it also contains projection ID, which is the internal identifier of a projection, which has been used during rendering of the image, described by that instance of the class.

The calculation should be solely based on that information (and knowledge of rendering engine). Implementation must not make any IPC calls to rendering engine process and should perform as if it does not exist at all. In other words, the converter should be usable, even if no image has been actually rendered.

 


Image to world coordinate conversion

This conversion is represented by the GetWorldCoordinate() method. It accepts as input a TCoordinate object, which contains coordinates of some location on Earth. The output of that function is the offset in map image, which represents that location.

Below is an example of the implementation of that function. CMyCoordConverter is assumed to be derived from CMnCoordinateConverterBase.

TInt CMyCoordConverter::GetWorldCoordinate(
  const TPoint& aImageOffset,
  TCoordinate& aCoordinate )
{
TMnMapImageParams& params = MapImageParams();

// check projection, some value representing projection
// algorithm of rendering engine of MapImage service implementation
if ( params.ProjectionId() != KMyProjectionId )
  {
  return KErrArgument;
  }


// Retrieve center of image as follows
TCoordinate center;
params.GetCenterPoint( center );

TReal latitude, longitude;
// Apply projection formula to calculate latitude and longitude
// using any needed info from params.

// Return result as coordinate
aCoordinate.SetCoordinate( latitude, longitude, 0); // zero altitude
return KErrNone; // successfully found world coordinate
}

 


World to image coordinate conversion

This conversion is represented by the GetWorldCoordinate() method. It accepts as input a TCoordinate object, which contains coordinates of some location on Earth. Output of that function shall be the offset in map image, which represents that location.

Below is the example of implementation of that function. CMyCoordConverter is assumed derived from CMnCoordinateConverterBase.

TInt CMyCoordConverter::GetImageCoordinate(
  const TCoordinate& aCoordinate,
  TPoint& aImageOffset )
{
TMnMapImageParams& params = MapImageParams();

// check projection, some value representing projection
// algorithm of rendering engine of MapImage service implementation
if ( params.ProjectionId() != KMyProjectionId )
  {
  return KErrArgument;
  }


// Retrieve center of image as follows
TCoordinate center;
params.GetCenterPoint( center );

TReal latitude = aCoordinate.Latitude();
TReal longitude = aCoordinate.Longitude();

TInt x, y;
// Apply projection formula to calculate x and y
// using any needed info from params.

// Return result as TPoint
aImageOffset = TPoint( x, y );
return KErrNone; // successfully found image coordinate
}

 


Creating ECom plug-in

Implementation of CMnCoordinateConverter must be exposed as an ECom plug-in DLL. Read more about ECom plug-ins in Symbian OS documentation and keep in mind the following important aspects:
  1. Interface, which that ECom plug-in provides implementation for, has UID defined by the KMnMapImageConverterIf value from mnpluginuids.hrh.
  2. Data field of ECom registration file, must contain SID of appropriate executable, which implements MapImage service.
  3. ECom plug-in DLL should have capabilities ALL-Tcb in order to be usable by system applications. If it has less capabilities, it might be unavailable for some of those. The implementation cannot expect any capabilities from the process it will be executed in.
  4. ECom plug-in DLL must be a part of signed installation package.

 


Examples

Let's assume that SID of the server application (which implements MapImage service) this plug-in is supposed to be used with, is 0x10203A4B. Let's also assume that DLL UID of the ECom plug-in is 0x10203A4C and implementation UID is 0x10203A4D. Actual UIDs must be allocated by developer from Symbian.

Here is an example of MMP file for the plug-in:

TARGET          mycoordconverter.dll
TARGETTYPE      PLUGIN
UID             0x10009D8D 0x10203A4C

CAPABILITY      ALL - TCB
SOURCE          mycoordconvertermain.cpp

SYSTEMINCLUDE   \epoc32\include

// ECom registration resource file
START RESOURCE  mycoordconverter.rss
TARGET          mycoordconverter.rsc
TARGETPATH      \resource\plugins
END

LIBRARY         euser.lib
LIBRARY         mnclientlib.lib
LIBRARY         lbs.lib

Below is an example of ECom registration file, mycoordconverterplugin.rss.

#include <registryinfov2.rh>
#include <mnpluginuids.hrh> // defines interface UID

RESOURCE REGISTRY_INFO r_mycoordconverterplugin_reginfo
{
resource_format_version = RESOURCE_FORMAT_VERSION_2;
// DLL UID of the DLL
dll_uid = 0x10203A4C;
interfaces =
    {
    INTERFACE_INFO
        {
        // UID of coordinate converter interface,
        // defined in mnpluginuids.hrh
        interface_uid = KMnMapImageConverterIf;
        implementations =
            {
            IMPLEMENTATION_INFO
                {
                // The licensee needs to allocate this UID from Symbian
                implementation_uid = 0x10203A4D;
                version_no = 1;
                display_name = "MyCoordinateConverter";
                // SID of provider application executable
                default_data = "10203A4B";
                }
            };
        }
    };
}

Note that the default_data field, which contains SID of the server application: the SID must be written in exactly 8 (eight) hexadecimal digits and A-F characters must be capital.

And finally, the example code of exporting factory function, mycoordconvertermain.cpp.

// Table of implementations
const TImplementationProxy ImplementationTable[] =
    {
    // Note! UID below is implementation UID, not DLL UID.
    IMPLEMENTATION_PROXY_ENTRY( 0x10203A4D, CMyCoordConverter::NewL ),
    };

// Note this function must be exported at ordinal 1
EXPORT_C const TImplementationProxy* ImplementationGroupProxy(
    TInt& aTableCount)
    {
    aTableCount = 1;
    return ImplementationTable;
    }

CMyCoordConverter is assumed derived from CMnCoordinateConverterBase.

 


Error handling

Implementation must not panic. All error cases must be informed via the return value of conversion methods. See documentation of the CMnCoordinateConverterBase class for allowed error codes.

 


Memory overhead

Implementation must try not to use memory excessively, because it will be loaded into the client's process. However, whenever there is not enough memory to perform calculations, the appropriate method should inform it by returning the KErrNoMemory error code.

 


Extensions to the API

This API does not have extension points.

 


See also

See also related APIs:
  • Map Image API
  • Map and Navigation Provider API

 


Glossary

 


Abbreviations

Table:
None  

 


Definitions

Table:
None  

 


References

None  

Back to top