The starting point for determining device location is the LocationProvider class, which represents the source of the location information. A LocationProvider object represents a specific way of using a location provider module to obtain location information. For example, a GPS receiver can be used for standalone GPS and assisted GPS (separate location providers). You can create a LocationProvider object in one of two ways:
Call the LocationProvider.getInstance(Criteria criteria) method. Use the Criteria parameter to specify what kind of a location provider is accepted. The platform selects the location provider that best meets the specified criteria. This approach is supported by all devices that support the Location API.
Call the LocationUtil.getLocationProvider(int[] preferredMethods, String parameters) method to explicitly specify which location provider to use. This approach is only supported on Series 40 devices with Java Runtime 1.0.0 for Series 40 or newer.
Both methods return a LocationProvider object for the selected location provider. Use this object to retrieve the location information.
The following code snippets shows how to specify the criteria for selecting a location provider and how to retrieve a location provider based on those criteria.
// Specify the criteria for selecting a location provider
Criteria criteria = new Criteria();
criteria.setHorizontalAccuracy(25); // 25m
criteria.setVerticalAccuracy(25); // 25m
criteria.setPreferredResponseTime(Criteria.NO_REQUIREMENT);
criteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_HIGH);
criteria.setCostAllowed(false);
criteria.setSpeedAndCourseRequired(true);
criteria.setAltitudeRequired(true);
criteria.setAddressInfoRequired(true);
// Retrieve a location provider based on the above criteria
LocationProvider provider;
try {
provider = LocationProvider.getInstance(criteria);
if (provider != null) {
// Location provider matching specified criteria found,
// send a selection event
}
} catch(LocationException le) {
// No location providers available,
// handle the exception
}
If the device does not have any built-in location provider modules available or is not connected to an external location provider module, the LocationProvider.getInstance method throws a LocationException. A return value other than null indicates that a location provider was found.
The LocationUtil.getLocationProvider method is only supported on Series 40 devices with Java Runtime 1.0.0 for Series 40 or newer.
The LocationUtil.getLocationProvider method uses the Location class constants (each corresponding to a specific location-providing method) to specify which location provider to use. Each location provider corresponds to a specific bitwise combination of constants:
|
Location provider |
Definition |
|---|---|
|
Standalone GPS |
(MTA_UNASSISTED | MTE_SATELLITE | MTY_TERMINALBASED) |
|
Assisted GPS (AGPS) |
(MTA_ASSISTED | MTE_SATELLTITE | MTY_TERMINALBASED) |
|
Online cell ID or WLAN |
(MTA_ASSISTED | MTE_CELLID | MTE_SHORTRANGE | MTY_NETWORKBASED) |
|
Offline cell ID |
(MTA_UNASSISTED | MTE_CELLID | MTY_TERMINALBASED) |
The following code snippet shows how to retrieve a location provider based on standalone GPS.
// Specify the location-providing methods for standalone GPS
int[] methods = {(Location.MTA_UNASSISTED | Location.MTE_SATELLITE | Location.MTY_TERMINALBASED)};
// Retrieve the location provider
LocationProvider provider = LocationUtil.getLocationProvider(methods, null);
For more information about cell-ID-based location providers, see section Cell ID positioning.