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

The BlackBerryCriteria is an extension of the Criteria object. It allows an application to specific an enhanced set GPS criteria that is used by the JSR179 Extension implementation. The additional criteria consists of the following:

1. Setting specific GPS modes. This Extension will therefore allow an application to specific the specific GPS modes it requires witihin the criteria object.

2. Specifying a failover mode. An application can specify a failover GPS mode in case the first mode returns a failure.

3. Specify a subsequent mode. An application can specify the GPS mode to use after a GPS fix is obtained with the first mode.

4. Specify a GPS restart interval. This interval is used by the implementation to wait for a time period before automatically restarting the GPS - this applies only when a fix could not be obtained leading to the GPS to stop. There is a maximum and minimum intervals, 15 minutes and 2 seconds respectively. Also, the implementation will allow a maximum of 3 automatic retries only.

5. Specify whether satellite tracking information is required. The satellite tracking information consists of the number of satellites in view, their ids, signal quality, elevation and azimuth.

Since:
BlackBerry API 5.0.0

Field Summary
 
Fields inherited from class javax.microedition.location.Criteria
NO_REQUIREMENT, POWER_USAGE_HIGH, POWER_USAGE_LOW, POWER_USAGE_MEDIUM
 
Constructor Summary
BlackBerryCriteria()
           This default constructor sets the default GPS mode in the following order of preference depending on whether that mode is supported on the BlackBerry Smartphone:Autonomous, Assisted, Cellsite.
BlackBerryCriteria(int mode)
           This constructor allows an application to set the GPS mode.
 
Method Summary
 int getFailoverMode()
           Returns the failover GPS mode set by the application, or the GPS_MODE_NONE if not set.
 int getFailoverTimeout()
           Returns the failover timeout.
 int getGPSRestartInterval()
           Returns the GPS restart interval.
 int getMaximumGPSRestart()
           Returns the maximum number of GPS restart.
 int getMaximumRetryBeforeFailOver()
           Returns the maximum number of GPS retries before a failover happens.
 int getMode()
           Returns the primary mode set by the application, or the default mode if not set.
 int getSubsequentMode()
           Returns the subsequent GPS mode set by the application, or the GPS_MODE_NONE if not set.
 boolean isFailOverModeOn()
           Returns whether the application has set a failover mode.
 boolean isGPSRestartModeOn()
           Returns whether the application has set the GPS restart mode on.
 boolean isSatelliteInfoRequired()
          Method to query whether the satellite tracking information flag was set in the BlackBerryCriteria object.
 boolean isSatelliteInfoRequiredAfterGPSFix()
          Method to query whether the satellite tracking info is still required after a GPS fix is obtained.
 boolean isSubsequentModeOn()
           Returns whether the application has set the subsequent mode on.
 void setFailoverMode(int mode, int maximumRetry, int timeout)
           This method allows an application to set the GPS failover mode.
 void setGPSRestartInterval(int interval, int maximumRetry)
           This method allows an application to set the GPS restart interval.
 void setMode(int mode)
           This method allows an application to set the GPS mode.
 void setSatelliteInfoRequired(boolean enable, boolean stopWhenGPSFixObtained)
          This method allows an application to indicate whether it requires Satellite tracking information This is applicable when using Internal GPS only (not BlueTooth GPS).
 void setSubsequentMode(int mode)
           This method allows an application to set the GPS mode to use after a successful first fix.
 
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
 



Constructor Detail

BlackBerryCriteria

public BlackBerryCriteria()

This default constructor sets the default GPS mode in the following order of preference depending on whether that mode is supported on the BlackBerry Smartphone:Autonomous, Assisted, Cellsite. Note that not all modes are supported on all BlackBerry Smartphones and networks.

Since:
BlackBerry API 5.0.0

BlackBerryCriteria

public BlackBerryCriteria(int mode)
                   throws UnsupportedOperationException

This constructor allows an application to set the GPS mode. On a CDMA BlackBerry Smartphones a GPS mode of GPSInfo.GPS_MODE_ASSIST will be mapped to GPSInfo.GPS_MODE_CDMA_MS_BASED. Application desiring specific GPS Assisted modes on CDMA Smartphones will need to choose one of Assisted GPS modes described in the GPSInfo class.

Parameters:
mode - - a GPS mode supported on the BlackBerry Smartphone
Throws:
UnsupportedOperationException - - if the required mode is not available.
Since:
BlackBerry API 5.0.0


Method Detail

setSatelliteInfoRequired

public void setSatelliteInfoRequired(boolean enable,
                                     boolean stopWhenGPSFixObtained)
This method allows an application to indicate whether it requires Satellite tracking information This is applicable when using Internal GPS only (not BlueTooth GPS).

Parameters:
enable - - true to indicates satellite tracking data is required, false otherwise.
stopWhenGPSFixObtained - - true to indicate that satellite tracking data is not required after a GPS fix is obtained, false otherwise
Since:
BlackBerry API 5.0.0

isSatelliteInfoRequired

public boolean isSatelliteInfoRequired()
Method to query whether the satellite tracking information flag was set in the BlackBerryCriteria object. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
true indicates that satellite tracking information flag was set, false otherwise
Since:
BlackBerry API 5.0.0

isSatelliteInfoRequiredAfterGPSFix

public boolean isSatelliteInfoRequiredAfterGPSFix()
Method to query whether the satellite tracking info is still required after a GPS fix is obtained. This is applicable when using Internal GPS only (not BlueTooth GPS).

Parameters:
true - indicates that satellite tracking information is still required after a GPS fix, false otherwise
Since:
BlackBerry API 5.0.0

setMode

public void setMode(int mode)
             throws UnsupportedOperationException

This method allows an application to set the GPS mode. On a CDMA BlackBerry Smartphones a GPS mode of GPSInfo.GPS_MODE_ASSIST will be mapped to GPSInfo.GPS_MODE_CDMA_MS_BASED. Application desiring specific GPS Assisted modes on CDMA Smartphones will need to choose one of Assisted GPS modes described in the GPSInfo class.

Parameters:
mode - - a GPS mode supported on the BlackBerry Smartphone
Throws:
UnsupportedOperationException - - if the required mode is not available.
Since:
BlackBerry API 5.0.0

getMode

public int getMode()

Returns the primary mode set by the application, or the default mode if not set.

Returns:
int - a GPS mode supported on the BlackBerry Smartphone
Since:
BlackBerry API 5.0.0

setFailoverMode

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

This method allows an application to set the GPS failover mode. The failover mode is the mode the GPS chipset will use if the GPS chipset returned an error with the first mode. This is applicable when using Internal GPS only (not BlueTooth GPS).

Parameters:
mode - - a GPS mode supported on the BlackBerry Smartphone. On a CDMA BlackBerry Smartphones a GPS mode of GPSInfo.GPS_MODE_ASSIST will be mapped to GPSInfo.GPS_MODE_CDMA_MS_BASED. Application desiring specific GPS Assisted modes on CDMA Smartphones will need to choose one of Assisted GPS modes described in the GPSInfo class.
maximumRetry - - the maximum number of GPS retries (using the first mode) before a failover happens. A retry is triggered when the GPS chipset reports a failure. The retry value can only be between 0 and 3. If the value is less than 0 then a default of 0 (no retry) will be used.
timeout - - the maximum wait time (in seconds) to get a fix before a failover occurs. The range of timeout value is between 30 to 300 seconds. A timeout value of less than 30 seconds will be adjusted to 30 seconds. Similarly, a timeout value of greater than 300 seconds will be 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 the GPS_MODE_NONE if not set. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
int - the failover GPS mode
Since:
BlackBerry API 5.0.0

getFailoverTimeout

public int getFailoverTimeout()

Returns the failover timeout. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
int - the maximum wait time (in seconds) to get a fix before a failover occurs. -1 if failover is not set by application.
Since:
BlackBerry API 5.0.0

isFailOverModeOn

public boolean isFailOverModeOn()

Returns whether the application has set a failover mode. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
boolean - true if the failover mode has been set.
Since:
BlackBerry API 5.0.0

setGPSRestartInterval

public void setGPSRestartInterval(int interval,
                                  int maximumRetry)

This method allows an application to set the GPS restart interval. The restart interval is the amount of time JSR179 Extension will wait before it automatically restarts GPS after a failure.

Parameters:
interval - - the time (in seconds) JSR179 Extension will wait before automatically restarting the GPS. The interval ranges between 2 and 900 seconds. Any value less than 2 seconds will be adjusted to 2 seconds and any value greater than 900 seconds will be adjusted to 900 seconds.
maximumRetry - - the maximum number of GPS restarts. This value ranges from 1 to 3. If the value is less than 1 then a default of 3 will be used.
Since:
BlackBerry API 5.0.0

getGPSRestartInterval

public int getGPSRestartInterval()

Returns the GPS restart interval.

Returns:
int - the time JSR179 Extension will wait before automatically restarting the GPS. -1 if GPS restart is not set by the application.
Since:
BlackBerry API 5.0.0

isGPSRestartModeOn

public boolean isGPSRestartModeOn()

Returns whether the application has set the GPS restart mode on.

Returns:
boolean - true if the GPS restart mode has been set.
Since:
BlackBerry API 5.0.0

getMaximumGPSRestart

public int getMaximumGPSRestart()

Returns the maximum number of GPS restart.

Returns:
int - the maximum number of GPS restarts configured. -1 if GPS restart is not set by the application.
Since:
BlackBerry API 5.0.0

getMaximumRetryBeforeFailOver

public int getMaximumRetryBeforeFailOver()

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

Returns:
int - the maximum number of GPS restarts configured.
Since:
BlackBerry API 5.0.0

setSubsequentMode

public void setSubsequentMode(int mode)

This method allows an application to set the GPS mode to use after a successful first fix. This is applicable when using Internal GPS only (not BlueTooth GPS).

Parameters:
mode - - a GPS mode supported on the BlackBerry Smartphone. On a CDMA BlackBerry Smartphones a GPS mode of GPSInfo.GPS_MODE_ASSIST will be mapped to GPSInfo.GPS_MODE_CDMA_MS_BASED. Application desiring specific GPS Assisted modes on CDMA Smartphones will need to choose one of Assisted GPS modes described in the GPSInfo class.
Throws:
UnsupportedOperationException - - if the required mode is not available.
Since:
BlackBerry API 5.0.0

getSubsequentMode

public int getSubsequentMode()

Returns the subsequent GPS mode set by the application, or the GPS_MODE_NONE if not set. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
int - the subsequent GPS mode
Since:
BlackBerry API 5.0.0

isSubsequentModeOn

public boolean isSubsequentModeOn()

Returns whether the application has set the subsequent mode on. This is applicable when using Internal GPS only (not BlueTooth GPS).

Returns:
boolean - true if the subsequent mode has been set.
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.