net.rim.device.api.gps
Class BlackBerryCriteria

java.lang.Object
  extended by javax.microedition.location.Criteria
      extended by 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:

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:

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:

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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.