Class and interface description

LocationProvider

The LocationProvider implementation uses the native Location acquisition API.

The default timeout for getLocation is set to:

• 2 * "average time to first fix", timeout >= 15s.

The “average time to first fix” value is retrieved from the native API for the used location technology.

The default values for setLocationListener are set to:

• interval = 1.25 * TTF (if terminal-based), 4 * TTF (if network-based)

• timeout = MIN(2 * TTF, interval)

• maxAge = 0.5 * interval

The “average time to next fix” (Time-to-Fix, TTF) value is retrieved from the native API for the used location technology.

State changes to and from AVAILABLE and TEMPORARILY_UNAVAILABLE are delayed to reduce the number of changes:

• From AVAILABLE to TEMPORARILY_UNAVAILABLE = 5 seconds

• From TEMPORARILY_UNAVAILABLE to AVAILABLE = 2 seconds

LandmarkStore

The LandmarkStore implementation uses the native Landmark APIs. Stores are always created on the default drive. The default drive is set by the native API and is the phone’s internal drive, which is non-removable. Store names are case insensitive.

Special syntax store name (x:), where x is a drive letter can be used, for example:

LandmarkStore.getInstance("My store (c:)")

This syntax is used in listLandmarkStores for stores that are found on other drives than the default drive and is also supported in getInstance and deleteLandmarkStore.

Maximum string lengths:

• Landmark name = 255

• Category name = 124

• Description = 4096

For createLandmarkStore the following apply:

• Drive cannot be specified using store name (x:), landmark stores are always created on the default drive.

• Case is preserved for store names.

• IllegalArgumentException is thrown if bad characters are used in the name (e.g. ‘:’).

• Created stores have predefined categories. This is done by the native implementation and it also decides the specific categories created.

For getLandmarks the following apply:

• Special search features:

  • * and ? are wildcards.

  • Empty string “” as category name finds uncategorized landmarks.

• Examples:

• getLandmarks("", "f*Bar") will match all uncategorized landmarks with names like “fooBar”, “foooBar”, “fBar” etc. (* matches 0 or more characters).

• getLandmarks("fooBa?", null) will match all landmarks in categories “fooBar”, “fooBaz” etc. (? matches exactly 1 character).

In S60 3rd edition FP1 and FP2, the performance of landmarks has been improved to give developers a possibility to optimize their Location-Based Java applications. Retrieving landmarks from the store has been optimized by initializing only minimal landmark attributes depending of which variant of LandmarkStore.getLandmarks() is used:

• LandmarkStore.getLandmarks() and LandmarkStore.getLandmarks( String category, String name ):

  • Initializes the names of the returned landmarks. It is recommended that this attribute is retrieved first from the returned landmarks if needed.

  • The description, coordinates and address information of the landmarks are read from the store when accessed by the client

• LandmarkStore.getLandmarks( String category, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude ):

  • Initializes the names and the position information of the returned landmarks. It is recommended that these attributes are retrieved first from the returned landmarks if needed.

  • Description and address information are read from the store when accessed by the client.

Enumerating the returned landmarks is now a very fast operation but the data of the landmarks should be accessed only when it is really needed by the client, that is, it is not recommended to enumerate all landmarks and get all landmark attributes from each landmark. Depending on the number of address information fields in the landmarks, Landmark.getAddressInfo() may be a slow operation if performed for huge amount of landmarks. Therefore it should be used only when necessary. Getting the name, description and coordinates of a landmark is quite efficient in most cases.

AddressInfo

The maximum string length for the address fields is 255.

Coordinates

The distance and azimuthTo methods of the Coordinates class call the native Location API. This means that the algorithm used is the same as in the native API.