net.rim.device.api.gps
Class BlackBerryCriteria

java.lang.Object
  javax.microedition.location.Criteria
      net.rim.device.api.gps.BlackBerryCriteria

public class BlackBerryCriteria
extends Criteria

Represents an extension of the JSR179 Criteria object. You can use the BlackBerryCriteria class to specify an enhanced set of criteria, which is used by the JSR179 extension implementation.

The following criteria settings are available in the BlackBerryCriteria class:

• Specifying a location mode. You can specify the location mode (GPS or geolocation) you want to use in the Criteria object. Valid location modes are defined in the GPSInfo and LocationInfo classes.
• Setting a failover mode if the first mode fails. You cannot use GPSInfo.GPS_MODE_CELLSITE or the geolocation modes that are defined in LocationInfo as the failover mode.
• Specifying a subsequent mode. After retrieving a location using the first mode, you can specify a different mode to retrieve the next location. You cannot use GPSInfo.GPS_MODE_CELLSITE or the geolocation modes that are defined in LocationInfo as the subsequent mode.
• Specifying a GPS restart interval. This interval indicates the time period to wait before automatically restarting the GPS receiver. This applies only to situations where a fix cannot be obtained, which leads to the GPS receiver stopping. The interval must be a value between 2 seconds and 15 minutes. The maximum number of automatic retries is 3.
• Specifying whether satellite tracking information is required. The satellite tracking information consists of the number of satellites that are in view, the satellite IDs, signal quality, elevation and azimuth.
• Specifying geolocation with GPS updates. During the timeout period specified in the location request, a GPS fix is provided to the application as soon as it is available. If a GPS fix is not available during the specified time period, a geolocation fix is provided (if available). This mode can be used for single and multiple location requests.
• Specifying geolocation with GPS updates to retrieve the first available fix, regardless of the location source (GPS or geolocation). During the timeout period specified in the location request, the first location that is available from a location source is provided to the application. This mode can only be used for single fix requests.

To specify the required location mode to use, call BlackBerryCriteria.BlackBerryCriteria(int mode), or accept the default mode that is available on the device by calling BlackBerryCriteria.BlackBerryCriteria(). Valid location modes are defined in the GPSInfo and LocationInfo classes.

Code sample: Requesting location updates using the default location mode

In the following example, location updates are retrieved at a regular interval from any location source that is available. GPS location updates are preferred, however, whenever a GPS fix is unavailable, a possibly less accurate geolocation fix is accepted.

There is no preferred GPS mode, so the default BlackBerryCriteria constructor is used to retrieve the default GPS mode. The option to retrieve geolocation with GPS updates is then enabled.

      try { //setup Criteria
          bbCriteria = new BlackBerryCriteria()); // use default mode on the device
          bbCriteria.enableGeolocationWithGPS();  // retrieve geolocation fix if GPS fix unavailable
      } catch (UnsupportedOperationException uoe) {}
      

The application can then use the BlackBerryCriteria object to get a BlackBerryLocationProvider instance to set up the location listener for the multiple update request.

      try { //setup LocationProvider
          bbProvider = (BlackBerryLocationProvider)LocationProvider.getInstance(bbCriteria);
          bbprovider.setLocationListener(myLocListener, interval, timeout, maxage);
      } catch (LocationException le) {}
 

GPS fixes or geolocation fixes (whenever GPS is unavailable) are provided to the LocationListener at the specified interval.

Since:

BlackBerry API 5.0.0

Field Summary
static int	FASTEST_FIX_PREFERRED Indicates that the first available location is preferred, regardless of the location source.

Fields inherited from class javax.microedition.location.Criteria

NO_REQUIREMENT, POWER_USAGE_HIGH, POWER_USAGE_LOW, POWER_USAGE_MEDIUM

Constructor Summary

BlackBerryCriteria()
Constructs a BlackBerryCriteria instance that sets the primary location mode to the default GPS mode in the following order of preference, depending on whether that mode is supported on the BlackBerry device: assisted, autonomous, and cellsite.

BlackBerryCriteria(int mode)
Constructs a BlackBerryCriteria instance that allows an application to set the primary location mode.

Method Summary
void	enableGeolocationWithGPS() Specifies geolocation with GPS updates.
void	enableGeolocationWithGPS(int mode) Specifies geolocation with GPS updates, with the option to retrieve the fastest single fix that is available.
int	getFailoverMode() Returns the failover GPS mode set by the application, or returns GPSInfo.GPS_MODE_NONE if a mode is not set.
int	getFailoverTimeout() Returns the failover timeout.
int	getGPSRestartInterval() Returns the GPS restart interval.
int	getMaximumGPSRestart() Returns the maximum number of times to restart the GPS receiver.
int	getMaximumRetryBeforeFailOver() Returns the maximum number of GPS retries before a failover occurs.
int	getMode() Returns the primary location mode specified by the application.
int	getSubsequentMode() Returns the GPS mode that is used for subsequent location requests.
boolean	isFailOverModeOn() Indicates whether a failover mode was set.
boolean	isGPSRestartModeOn() Indicates whether the GPS restart mode is on.
boolean	isSatelliteInfoRequired() Determines whether the satellite tracking information flag was set in the BlackBerryCriteria object.
boolean	isSatelliteInfoRequiredAfterGPSFix() Determines whether satellite tracking information is required after a GPS fix is obtained.
boolean	isSubsequentModeOn() Indicates whether the subsequent mode is on.
void	setFailoverMode(int mode, int maximumRetry, int timeout) Sets the GPS failover mode to use when the initial mode that was specified in the criteria fails.
void	setGPSRestartInterval(int interval, int maximumRetry) Sets the GPS restart interval.
void	setMode(int mode) Sets the primary location mode.
void	setSatelliteInfoRequired(boolean enable, boolean stopWhenGPSFixObtained) Specifies whether satellite tracking information is required.
void	setSubsequentMode(int mode) Sets the GPS mode to use after successfully retrieving the first location.

Methods inherited from class javax.microedition.location.Criteria

equals, getHorizontalAccuracy, getPreferredPowerConsumption, getPreferredResponseTime, getVerticalAccuracy, isAddressInfoRequired, isAllowedToCost, isAltitudeRequired, isSpeedAndCourseRequired, setAddressInfoRequired, setAltitudeRequired, setCostAllowed, setHorizontalAccuracy, setPreferredPowerConsumption, setPreferredResponseTime, setSpeedAndCourseRequired, setVerticalAccuracy

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FASTEST_FIX_PREFERRED

public static final int FASTEST_FIX_PREFERRED

Indicates that the first available location is preferred, regardless of the location source.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

BlackBerryCriteria

public BlackBerryCriteria()

Constructs a BlackBerryCriteria instance that sets the primary location mode to the default GPS mode in the following order of preference, depending on whether that mode is supported on the BlackBerry device: assisted, autonomous, and cellsite. An assisted mode is returned as the default mode if PDE credentials are authenticated or are not required.

Not all modes are supported on all BlackBerry devices and wireless networks. The assisted mode GPSInfo.GPS_MODE_CDMA_MS_BASED is returned if the network supports extended CDMA modes.

Since:

BlackBerry API 5.0.0

BlackBerryCriteria

public BlackBerryCriteria(int mode)
                   throws UnsupportedOperationException

Constructs a BlackBerryCriteria instance that allows an application to set the primary location mode.

For BlackBerry devices that operate on CDMA networks, the GPS mode GPSInfo.GPS_MODE_ASSIST maps to GPSInfo.GPS_MODE_CDMA_MS_BASED.

Parameters:

mode - A location mode that is supported on the BlackBerry device. Valid location modes are defined in GPSInfo and LocationInfo.

Throws:

UnsupportedOperationException - if the required mode is not available.

Since:

BlackBerry API 5.0.0

Method Detail

enableGeolocationWithGPS

public void enableGeolocationWithGPS()

Specifies geolocation with GPS updates. When this option is enabled, a geolocation is provided if a GPS location is unavailable during the timeout period. By default, this option is disabled. Once enabled, it is enabled for the life time of the BlackBerryCriteria object. To disable this option, a new Criteria instance is required.

This option has no affect on other settings in the BlackBerryCriteria.

Since:

BlackBerry API 6.0.0

enableGeolocationWithGPS

public void enableGeolocationWithGPS(int mode)

Specifies geolocation with GPS updates, with the option to retrieve the fastest single fix that is available. This option applies only to single fix requests. The first location that is available, within the time period, is provided from either the geolocation service or GPS. By default, this option is disabled. Once enabled, it is enabled for the life time of the BlackBerryCriteria object. To disable this option, a new Criteria instance is required.

This option has no affect on other settings in the BlackBerryCriteria.

This method should be called before passing in the BlackBerryCriteria instance to LocationProvider.getInstance().

Parameters:

mode - BlackBerryCriteria.FASTEST_FIX_PREFERRED

Throws:

UnsupportedOperationException - if the required mode is not supported.

Since:

BlackBerry API 6.0.0

setSatelliteInfoRequired

public void setSatelliteInfoRequired(boolean enable,
                                     boolean stopWhenGPSFixObtained)

Specifies whether satellite tracking information is required. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Parameters:

enable - true if satellite tracking information is required, false otherwise.

stopWhenGPSFixObtained - true if satellite tracking data is not required after a GPS fix is obtained, false otherwise.

Since:

BlackBerry API 5.0.0

isSatelliteInfoRequired

public boolean isSatelliteInfoRequired()

Determines whether the satellite tracking information flag was set in the BlackBerryCriteria object. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

true if the satellite tracking information flag is set, false otherwise.

Since:

BlackBerry API 5.0.0

isSatelliteInfoRequiredAfterGPSFix

public boolean isSatelliteInfoRequiredAfterGPSFix()

Determines whether satellite tracking information is required after a GPS fix is obtained. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

true if satellite tracking information is required after a GPS fix is obtained, false otherwise.

Since:

BlackBerry API 5.0.0

setMode

public void setMode(int mode)
             throws UnsupportedOperationException

Sets the primary location mode.

For BlackBerry devices that operate on CDMA networks, the GPS mode GPSInfo.GPS_MODE_ASSIST maps to GPSInfo.GPS_MODE_CDMA_MS_BASED.

Parameters:

mode - A location mode that is supported on the BlackBerry device. Location modes are defined in the GPSInfo and LocationInfo classes.

Throws:

UnsupportedOperationException - if the required mode is not available.

Since:

BlackBerry API 5.0.0

getMode

public int getMode()

Returns the primary location mode specified by the application. If a mode was not specified in the Criteria object, the default mode is returned.

Returns:

A location mode supported by the BlackBerry device.

Since:

BlackBerry API 5.0.0

setFailoverMode

public void setFailoverMode(int mode,
                            int maximumRetry,
                            int timeout)
                     throws UnsupportedOperationException

Sets the GPS failover mode to use when the initial mode that was specified in the criteria fails. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Parameters:

mode - One of the following supported GPS modes:

• GPSInfo.GPS_MODE_ASSIST
• GPSInfo.GPS_MODE_AUTONOMOUS
• GPSInfo.GPS_MODE_CDMA_MS_BASED
• GPSInfo.GPS_MODE_CDMA_DATA_OPTIMAL
• GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL
• GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL

Note: For BlackBerry devices that operate on CDMA networks, the GPS mode GPSInfo.GPS_MODE_ASSIST maps to GPSInfo.GPS_MODE_CDMA_MS_BASED.

maximumRetry - The maximum number of GPS retries (using the first mode) before a failover occurs. A retry is triggered when the GPS receiver reports a failure. The retry value can be between 0 and 3. If the value is less than 0, a default value of 0 (no retry) is used.

timeout - The maximum wait time (in seconds) to get a fix before a failover occurs. The range of timeout values is between 30 to 300 seconds. A timeout value less than 30 seconds is adjusted to 30 seconds. A timeout value greater than 300 seconds is adjusted to 300 seconds.

Throws:

UnsupportedOperationException - if the required mode is not available.

Since:

BlackBerry API 5.0.0

getFailoverMode

public int getFailoverMode()

Returns the failover GPS mode set by the application, or returns GPSInfo.GPS_MODE_NONE if a mode is not set. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

The failover GPS mode.

Since:

BlackBerry API 5.0.0

getFailoverTimeout

public int getFailoverTimeout()

Returns the failover timeout. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

The maximum wait time (in seconds) to get a fix before a failover occurs. A value of -1 is returned if a failover was not set.

Since:

BlackBerry API 5.0.0

isFailOverModeOn

public boolean isFailOverModeOn()

Indicates whether a failover mode was set. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

true if a failover mode was set, false otherwise.

Since:

BlackBerry API 5.0.0

setGPSRestartInterval

public void setGPSRestartInterval(int interval,
                                  int maximumRetry)

Sets the GPS restart interval. The restart interval is the amount of time to wait before automatically restarting the GPS receiver after a failure occurs.

Parameters:

interval - The time (in seconds) to wait before automatically restarting the GPS receiver. The interval range is between 2 and 900 seconds. Any value less than 2 seconds is adjusted to 2 seconds and any value greater than 900 seconds is adjusted to 900 seconds.

maximumRetry - The maximum number of times to restart the GPS receiver. This value ranges from 1 to 3. If the value is less than 1, 3 is used.

Since:

BlackBerry API 5.0.0

getGPSRestartInterval

public int getGPSRestartInterval()

Returns the GPS restart interval.

Returns:

The time before automatically restarting the GPS receiver. A value of -1 is returned if a GPS restart interval was not set.

Since:

BlackBerry API 5.0.0

isGPSRestartModeOn

public boolean isGPSRestartModeOn()

Indicates whether the GPS restart mode is on.

Returns:

true if the GPS restart mode is on, false otherwise.

Since:

BlackBerry API 5.0.0

getMaximumGPSRestart

public int getMaximumGPSRestart()

Returns the maximum number of times to restart the GPS receiver.

Returns:

The maximum number of times to start the GPS Receiver. A value of -1 is returned if the number of GPS restarts was not set.

Since:

BlackBerry API 5.0.0

getMaximumRetryBeforeFailOver

public int getMaximumRetryBeforeFailOver()

Returns the maximum number of GPS retries before a failover occurs.

Returns:

The maximum number of GPS restarts that are configured.

Since:

BlackBerry API 5.0.0

setSubsequentMode

public void setSubsequentMode(int mode)

Sets the GPS mode to use after successfully retrieving the first location. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Parameters:

mode - One of the following supported GPS modes:

• GPSInfo.GPS_MODE_ASSIST
• GPSInfo.GPS_MODE_AUTONOMOUS
• GPSInfo.GPS_MODE_CDMA_MS_ASSIST
• GPSInfo.GPS_MODE_CDMA_MS_BASED
• GPSInfo.GPS_MODE_CDMA_DATA_OPTIMAL
• GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL
• GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL

Note: For BlackBerry devices that operate on CDMA networks, the GPS mode GPSInfo.GPS_MODE_ASSIST maps to GPSInfo.GPS_MODE_CDMA_MS_BASED.

Throws:

UnsupportedOperationException - if the required mode is not available.

Since:

BlackBerry API 5.0.0

getSubsequentMode

public int getSubsequentMode()

Returns the GPS mode that is used for subsequent location requests. If a mode was not specified, GPSInfo.GPS_MODE_NONE is returned.

This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

The GPS mode that is used for subsequent location requests.

Since:

BlackBerry API 5.0.0

isSubsequentModeOn

public boolean isSubsequentModeOn()

Indicates whether the subsequent mode is on. This method applies only when using internal GPS receivers, not Bluetooth GPS receivers.

Returns:

true if the subsequent mode is on, false otherwise.

Since:

BlackBerry API 5.0.0