S60 Map Image Conversion Plug-In API |
DN0735015 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.0 |
23.02.2007 |
Approved |
|
![]() |
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.
![]() |
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.
![]() |
![]() |
![]() |
![]() |
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.
![]() |
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 }
![]() |
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 }
![]() |
![]() |
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.
![]() |
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.
![]() |