Map Image Conversion Plug-In API

Changes in Map Image Conversion Plug-In API documentation

Version Date Status Description

1.0

23.02.2007

Approved

Changes in Map Image Conversion Plug-In API

Version Description

1.0

First version

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 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.

Map Image Conversion plug-In API class s...


Map Image Conversion plug-In API class structure

Related APIs
  • CMnCoordinateConverterBase
  • GetImageCoordinate
  • GetWorldCoordinate
  • MapImageParams()

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:

  • Create a class derived from CMnCoordinateConverter and implement its abstract methods.

  • 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
}
Related APIs
  • CMnCoordinateConverterBase
  • CMyCoordConverter
  • GetWorldCoordinate()
  • TCoordinate

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
}
Related APIs
  • CMnCoordinateConverterBase
  • CMyCoordConverter
  • GetWorldCoordinate()
  • TCoordinate
Related APIs
  • CMnCoordinateConverter
  • MapImageParams()
  • TMnMapImageParams

Creating ECom plug-in

Implementation of CMnCoordinateConverter must be exposed as an ECom plug-in DLL. Read more about ECom plug-ins in the Symbian platform documentation and keep in mind the following important aspects:

  • Interface, which that ECom plug-in provides implementation for, has UID defined by the KMnMapImageConverterIf value from mnpluginuids.hrh.

  • Data field of ECom registration file, must contain SID of appropriate executable, which implements MapImage service.

  • 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.

  • 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.

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
                {
                 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.

Related APIs
  • CMnCoordinateConverterBase
  • CMyCoordConverter
  • default_data
Related APIs
  • CMnCoordinateConverter
  • KMnMapImageConverterIf

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.

Related APIs
  • CMnCoordinateConverterBase

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.

Related APIs
  • KErrNoMemory

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

Related APIs
  • CMnCoordinateConverter

Glossary

Abbreviations

None

Definitions

None

References

None