Optional APIs Porting Guide

This chapter describes the JSR 179 Location API implementation in the Java Wireless Client software. It covers the structure of the source code, available implementations of its components, and a description of the porting steps both for the native layer and the JavaCall layer.

This chapter provides high level information about porting the Location API. For detailed information about each function in the porting layers, check out the API reference documentation that is included with the Java Wireless Client software.

---

Introduction

The JSR 179 Location API enables mobile applications to determine their current location. This API covers obtaining information about the present geographic location and orientation of the terminal and accessing a database of known landmarks stored in the device.

This API is in a single package, javax.microedition.location.

---

Implementation Description

In this chapter, jsr179-root is the root directory of the Location API source code and javacall-root is the root directory of the JavaCall API source code.

The Location API has two major parts corresponding to the public classes in javax.microedition.location:

• Access to persistent landmark store (LandmarkStore classes)
• Access to location information of terminal (LocationProvider classes)

These classes use some internal classes from com.sun.j2me.location.

LandmarkStore currently has two implementations:

• The java_global implementation provides all functionality necessary for LandmarkStore using Java platform classes. This implementation is platform independent and does not have any native interfaces.
• The platform_global implementation has a special dedicated layer of native interfaces that are ported to a specific platform.

The LandmarkStore implementation is chosen at compilation by assigning an appropriate value to JSR_179_STORE_IMPL option in jsr179-root/src/config/subsystem.gmk. See the makefile for the allowed values.

LocationProvider has only a platform_global implementation. A special dedicated layer of native interfaces is the porting layer.

The atan2 math function has two implementations:

• The java_global platform-independent implementation does not require porting to new platforms.
• The platform_global implementation has a native interface that needs to be ported to a specific platform.

The implementation of atan2 is chosen at compilation by assigning an appropriate value to JSR_179_ATAN2_IMPL in jsr179-root/src/config/subsystem.gmk.

LandmarkStore Implementation

Several internal properties in jsr179-root/src/config/common/properties_jsr179.xml define limitations of LandmarkStore:

The java_global implementation provides all functionality necessary for the Location API via some Java platform classes. This implementation does not have any interfaces to a platform. RMS record stores are used for the LandmarkStore implementation.

The platform_global implementation has a native porting layer for an efficient platform-dependent implementation of LandmarkStore. The platform_global implementation is appropriate if the LandmarkStore needs to be accessible from both Java platform applications and native applications.

LocationProvider implementation

The LocationProvider implementation has a dedicated native layer that hides all interactions with the device and is a porting layer for an efficient platform-dependent implementation.

Several internal properties in jsr179-root/src/config/common/properties_jsr179.xml define limitations of LocationProvider functionality:

Atan2 Implementation

The java_global implementation is platform independent.

The platform_global implementation is appropriate if your platform has its own optimized implementation.

---

Location API Code Structure

The Location API source code is as follows:

jsr179-root/src

  common       - common classes

    classes

      com      - implementation independent internal classes

      javax    - JSR 179 API package

    native     - native code for common part of JSR 179

      share    - platform independent parts of LocationProvider

      linux    - linux implemetation of LocationProvider

      javacall - JavaCall API implemetation of LocationProvider

      stubs    - empty implementation of LocationProvider

  config       - files for build configuration

  include      - Native porting API header

  java_global

    classes

      com      - LandmarkStore implementation

    native

      math     - atan2 implementation

  platform_global

    classes

      com      - LandmarkStore internal classes

    native

      javacall - JavaCall API implemetation of LandmarkStore and atan2

      share    - platform independent native source code

  tests

    i3test     - the JSR 179 i3 tests

javacall-root

 interface

   jsr179_location   - JavaCall API porting API headers

 implementation

   stubs

     jsr179_location  empty implementations

   win32

     jsr179_location  win32 implementations

---

Porting layer functionality

The major purpose of the porting API is an interaction with your device's location hardware to access location information a platform database of landmarks.

The platform_global implementation could be presented as the following set of layers:

FIGURE 4-1 Location API code structure

This document naturally focuses on the native porting API and the JavaCall porting API. All the platform-dependent functionality is placed in this code layer. To make the Location API work on a new platform, you must implement all the functions below the native or JavaCall porting API for the given target.

---

Native Porting Layer

This API covers accessing a database of known landmarks stored in the terminal and the present geographic location and orientation of the terminal.

Accessing Landmarks

Here are optional features whose availability depends on the landmark store implementation of the device and its possible relation to landmark stores shared with native applications:

• Creating and deleting landmark stores
• Adding and removing landmark categories

The porting layer includes the following:

• Gets landmark stores:
• jsr179_landmarkstorelist_open()
• jsr179_landmarkstorelist_close()
• jsr179_landmarkstorelist_next()

• Gets landmarks from native landmark store:
• jsr179_landmarklist_open()
• jsr179_landmarklist_close()
• jsr179_landmarklist_next()

• Gets categories from native landmark store:
• jsr179_categorylist_open()
• jsr179_categorylist_close()
• jsr179_categorylist_next()

• Adds or deletes a landmark to a landmark store or category:
• jsr179_landmark_add_to_landmarkstore()
• jsr179_landmark_add_to_category()
• jsr179_landmark_delete_from_landmarkstore()
• jsr179_landmark_delete_from_category()

• (Optional) Creates or deletes a landmark store or category:
• jsr179_landmarkstore_create()
• jsr179_landmarkstore_delete()
• jsr179_category_add()
• jsr179_category_delete()

Getting the Current Location

To calculate distance or azimuth, a platform-independent atan2 function implementation is provided. However, if your device can calculate atan2 by means of a native math library, it is efficient to use it.

The acquired location includes the following information:

• Only Latitude and Longitude are mandatory
• Altitude (Float.NAN if unknown)
• HorizontalAccuracy and VerticalAccuracy in meters (Float.NaN if unknown)
• LocationMethod (zero if unknown)
• Speed, Course (Float.NAN if unknown)
• AddressInfo (provided if supported)
• ExtraInfo (provided if supported)

For the specified location provider, the following infomation is provided:

• Default time related properties of a location provider
• The default interval, which specifies how often updates are provided for listener
• The default maximum age, which specifies the acceptable age for cached information for listener
• The default timeout, which specifies how late update can be from interval for listener
• The average time of receiving next location
• The recommended time interval for asking a new state
• The other properties for Critera

Following are the optional features whose availability depends on the used location methods:

• Altitude information
• Accuracy of altitude
• Course and speed information
• Textual address information related to the location
• Proximity monitoring

The porting layer includes the following functionality:

• Opens a location provider and gets information
• jsr179_provider_open()
• jsr179_provider_close()
• jsr179_provider_getinfo()
• jsr179_notify_location_event()

• Gets the current status of a location provider
• jsr179_provider_state()

• Gets the location info on request basis
• jsr179_update_set()
• jsr179_update_cancel()

• (Optional) Gets the proximity events
• jsr179_proximity_monitoring_add()
• jsr179_proximity_monitoring_cancel()
• jsr179_notify_location_proximity()

Acquisition of Terminal Orientation

The following features are optionally supported:

• Compass azimuth of the terminal orientation
• Pitch and roll 3D terminal orientation information

If the implementation chooses to support orientation, it must provide the azimuth information. Providing pitch and roll is optional.

The porting layer includes the following functionality:

• Opens and closes an orientation provider
• jsr179_provider_open()
• jsr179_provider_close()

• Gets orientation information
• jsr179_orientation_start()
• jsr179_orientation_finish()
• jsr179_notify_location_event()

Implementation Notes

This section describes general principles of the Location API.

Asynchronous Operation

Some functions operate asynchronously. In this case, the function returns quickly with JSR179_STATUSCODE_WOULD_BLOCK. When the operation completes, an event is required to be sent from the platform. See section on events for related information.

The following are the asynchronous functions:

• Opening location provider
• Orientation update
• Location update once
• Proximity update

Buffer Allocation

The following rules apply to buffer allocation:

• The buffer for an output parameter must be allocated by the caller.
• A parameter for the size of the buffer must be present if no predefined maximum size exists.

The exceptional cases are enumeration functions like *list_next(), which have the following rules:

• The platform allocates memory and returns its pointer in this case.
• The allocated memory is valid until the enumeration is closed.

Mandatory LandmarkStore Functions

• jsr179_landmark_add_to_landmarkstore()
• jsr179_landmark_add_to_category()
• jsr179_landmark_update()
• jsr179_landmark_delete_from_landmarkstore()
• jsr179_landmark_delete_from_category()
• jsr179_landmarkstorelist_open()
• jsr179_landmarkstorelist_close()
• jsr179_landmarkstorelist_next()
• jsr179_landmarklist_open()
• jsr179_landmarklist_close()
• jsr179_landmarklist_next()
• jsr179_category_add()
• jsr179_categorylist_open()
• jsr179_categorylist_close()
• jsr179_categorylist_next()

Optional LandmarkStore Functions

If com.sun.j2me.location.CreateLandmarkStoreSupported is set to true, implement jsr179_landmarkstore_create().

If com.sun.j2me.location.DeleteLandmarkStoreSupported is set to true, implement jsr179_landmarkstore_delete().

If com.sun.j2me.location.DeleteCategorySupported is set to true, implement jsr179_category_delete().

Mandatory LocationProvider Functions

• jsr179_property_get()
• jsr179_provider_getinfo()
• jsr179_provider_open()
• jsr179_provider_close()
• jsr179_provider_state()
• jsr179_update_set()
• jsr179_update_cancel()
• jsr179_location_get()

Optional LocationProvider Functions

The following functions can be implemented to obtain additional location information:

• jsr179_get_extrainfo()
• jsr179_get_addressinfo()

The following functions shall be implemented if com.sun.j2me.location.OrientationSupported is set to true:

• jsr179_orientation_start()
• jsr179_orientation_finish()

The following functions shall be implemented if com.sun.j2me.location.ProximitySupported is set to true:

• jsr179_proximity_monitoring_add()
• jsr179_proximity_monitoring_cancel()

Optional Atan2 Function

jsr179_atan2() should be implemented if the platform_global implementation of atan2 is chosen in jsr179-root/src/config/subsystem.gmk.

Callback functions

You must implement jsr179_notify_location_event().

If com.sun.j2me.location.ProximitySupported is set to true, implement jsr179_notify_location_proximity().

Porting JSR 179

This section explains how the JSR 179 code can be ported to a new platform. The new platform is represented here as new-platform.

Implementing LocationProvider

1. Create new-platform directory in jsr179-root/src/common/native.

2. Create jsr179_locationProvider_impl.c file in jsr179-root/src/common/native/new-platform and implement LocationProvider functions according to your platform.

3. Set values for com.sun.j2me.location.OrientationSupported and com.sun.j2me.location.ProximitySupported in jsr179-root/src/config/common/properties_jsr179.xml.

Implementing LandmarkStore

1. Create new-platform directory in jsr179-root/src/platform_global/native.

2. Create jsr179_landmarkStore_impl.c in jsr179-root/src/platform_global/native/new-platform and implement LandmarkStore functions according to your platform.

3. Set values for com.sun.j2me.location.CreateLandmarkStoreSupported, com.sun.j2me.location.DeleteLandmarkStoreSupported and com.sun.j2me.location.DeleteCategorySupported in jsr179-root/src/config/common/properties_jsr179.xml file.

4. Set JSR_179_STORE_IMPL to platform in jsr179-root/src/config/subsystem.gmk.

Implementing atan2

1. Create new-platform directory in jsr179-root/src/platform_global/native.

2. Create jsr179_math_kni.c in jsr179-root/src/common/native/new-platform and implement jsr179_atan2() for your platform.

3. Set JSR_179_ATAN2_IMPL to platform in jsr179-root/src/config/subsystem.gmk.

---

JavaCall Porting Layer

The location functions in the JavaCall API are much like the native porting functions, but porting occurs in a different layer.

Accessing Landmarks

The following optional features' availability depends on the landmark store implementation of the device and its possible relation to landmark stores shared with native applications:

• Creating and deleting landmark stores
• Adding and removing landmark categories

The porting layer includes the following functionality:

• Gets landmark stores
• javacall_landmarkstore_list_open()
• javacall_landmarkstore_list_close()
• javacall_landmarkstore_list_next()

• Gets landmarks from native landmark store
• javacall_landmarkstore_landmarklist_open()
• javacall_landmarkstore_landmarklist_close()
• javacall_landmarkstore_landmarklist_next()

• Gets categories from native landmark store
• javacall_landmarkstore_categorylist_open()
• javacall_landmarkstore_categorylist_close()
• javacall_landmarkstore_categorylist_next()

• Adds or deletes a landmark to landmark store or category
• javacall_landmarkstore_landmark_add_to_landmarkstore()
• javacall_landmarkstore_landmark_add_to_category()
• javacall_landmarkstore_landmark_delete_from_landmarkstore()
• javacall_landmarkstore_landmark_delete_from_category()

• (Optional) Creates or deletes a landmark store or category
• javacall_landmarkstore_create()
• javacall_landmarkstore_delete()
• javacall_landmarkstore_category_add()
• javacall_landmarkstore_category_delete()

Getting the Current Location

To calculate distance or azimuth, the platform independent atan2 function implementation is provided. However, if your platform provides atan2 functionality by means of a native math library, it is more efficient to use it.

The acquired location should include following information:

• Only Latitude and Longitude are mandatory
• Altitude (Float.NAN if unknown)
• HorizontalAccuracy and VerticalAccuracy in meters (Float.NaN if unknown)
• LocationMethod (zero if unknown)
• Speed, Course (Float.NAN if unknown)
• AddressInfo (provided if supported)
• ExtraInfo (provided if supported)

For the specified location provider, the following infomation should be provided:

• Default time related properties of a location provider
• The default interval, which is how often updates are generated for listener.
• The default maximum age, which is the acceptable age for cached info for listener
• The default timeout, which specifies how late update can be from interval for listener
• The average time of receiving next location
• The recommended time interval for asking a new state
• The other properties for Critera

The following optional features' availability depends on the used location methods.

• Altitude information
• Accuracy of altitude
• Course and speed information
• Textual address information related to the location
• Proximity monitoring

The porting layer includes the following functionality:

• Opens a location provider and gets information
• javacall_location_provider_open
• javacall_location_provider_close
• javacall_location_provider_getinfo
• javanotify_location_event

• Gets the current status of a location provider.
• javacall_location_provider_state

• Gets the location info on request basis.
• javacall_location_update_set
• javacall_location_update_cancel

• (Optional) Gets the proximity events
• javacall_location_proximity_monitoring_add
• javacall_location_proximity_monitoring_cancel
• javanotify_location_proximity

Acquisition of Terminal Orientation

The following features are optionally supported:

• Compass azimuth of the terminal orientation
• Pitch and roll 3D terminal orientation information

If the implementation chooses to support orientation, it must provide the azimuth information. Providing pitch and roll is optional.

The porting layer includes the following functionality:

• Opens and closes an orientation provider
• javacall_location_provider_open
• javacall_location_provider_close

• Gets orientation information
• javacall_location_orientation_start
• javacall_location_orientation_finish
• javanotify_location_event

Implementation Notes

This section describes general principles of the Location API.

Asynchronous Operation

Some functions operate asynchronously. In this case, the function returns quickly with JAVACALL_WOULD_BLOCK. When the operation completes, an event is required to be sent from the platform. See the section on events for related information.

The asynchronous functions are as follows:

• Opening location provider
• Orientation update
• Location update once
• Proximity update
• Unicode string representation

All unicode strings used in this API are NULL terminated.

Buffer Allocation

The following rules apply to buffer allocation:

• The buffer for an output parameter must be allocated by the caller.
• A parameter for the size of the buffer must be present if no predefined maximum size exists.

The exceptional cases are enumeration functions like *list_next(), which have the following rules:

• The platform allocates memory and returns its pointer in this case.
• The allocated memory is valid until the enumeration is closed.

Mandatory LandmarkStore Functions

• javacall_landmarkstore_landmark_add_to_landmarkstore()
• javacall_landmarkstore_landmark_add_to_category()
• javacall_landmarkstore_landmark_update()
• javacall_landmarkstore_landmark_delete_from_landmarkstore()
• javacall_landmarkstore_landmark_delete_from_category()
• javacall_landmarkstore_list_open()
• javacall_landmarkstore_list_close()
• javacall_landmarkstore_list_next()
• javacall_landmarkstore_landmarklist_open()
• javacall_landmarkstore_landmarklist_close()
• javacall_landmarkstore_landmarklist_next()
• javacall_landmarkstore_category_add()
• javacall_landmarkstore_categorylist_open()
• javacall_landmarkstore_categorylist_close()
• javacall_landmarkstore_categorylist_next()

Optional LandmarkStore Functions

If com.sun.j2me.location.CreateLandmarkStoreSupported is set to true, implement javacall_landmarkstore_create().

If com.sun.j2me.location.DeleteLandmarkStoreSupported is set to true, implement javacall_landmarkstore_delete().

If com.sun.j2me.location.DeleteCategorySupported is set to true, implement javacall_landmarkstore_category_delete().

Mandatory LocationProvider Functions

• javacall_location_property_get()
• javacall_location_provider_getinfo()
• javacall_location_provider_open()
• javacall_location_provider_close()
• javacall_location_provider_state()
• javacall_location_update_set()
• javacall_location_update_cancel()
• javacall_location_get()

Optional LocationProvider functions

Implement the following functions to obtain additional location information:

• javacall_location_get_extrainfo()
• javacall_location_get_addressinfo()

If com.sun.j2me.location.OrientationSupported is set to true, implement javacall_location_orientation_start() and javacall_location_orientation_finish().

If com.sun.j2me.location.ProximitySupported is set to true, implement javacall_location_proximity_monitoring_add() and javacall_location_proximity_monitoring_cancel().

Optional Atan2 Function

Implement jsr179_atan2 if platform_global implementation of atan2 is chosen in jsr179-root/src/config/subsystem.gmk.

Callback Functions

You must implement javanotify_location_event().

If com.sun.j2me.location.ProximitySupported is set to true, implement javanotify_location_proximity().

Porting JSR 179

This section explains how the JSR 179 code can be ported to a new platform using the JavaCall API. The new platform is represented here as new-platform.

Implementing LocationProvider

1. Create new-platform/jsr179_location directory in javacall-com/implementation directory.

Copy location.c from javacall-com/implementation/win32/jsr179_location to the new-platform/jsr179_location directory.

2. Rewrite functions in your new location.c according to the platform specifics.

3. Set the appropriate values for com.sun.j2me.location.OrientationSupported and com.sun.j2me.location.ProximitySupported properties in jsr179-root/src/config/common/properties_jsr179.xml.

Implementing LandmarkStore

1. Create new-platform/jsr179_location directory in javacall-com/implementation directory.

2. Copy landmarkstore.c from javacall-com/implementation/win32/jsr179_location to the new-platform/jsr179_location directory.

3. Rewrite functions in your new landmarkstore.c according to the platform specifics.

4. Set the appropriate values for com.sun.j2me.location.CreateLandmarkStoreSupported, com.sun.j2me.location.DeleteLandmarkStoreSupported and com.sun.j2me.location.DeleteCategorySupported in jsr179-root/src/config/common/properties_jsr179.xml.

5. Set value for JSR_179_STORE_IMPL to platform in jsr179-root/src/config/subsystem.gmk file.

Implementing atan2

1. Create new-platform/jsr179_location directory in javacall-com/implementation directory.

2. Copy location.c from javacall-com/implementation/win32/jsr179_location to the new-platform/jsr179_location directory.

3. Rewrite javacall_location_atan2() in your new location.c according to the platform specifics.

4. Set value for JSR_179_ATAN2_IMPL variable to platform in jsr179-root/src/config/subsystem.gmk file.

Optional APIs Porting Guide

05-2007

Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.