net.rim.device.api.gps
Class GPSInfo
java.lang.Object
net.rim.device.api.gps.GPSInfo
public class GPSInfo
- extends Object
Provides access to device-specific Global Positioning System receiver information.
To access this information, the device must be equipped with a GPS receiver.
This class provides the following:
- constants that define GPS location sources, modes and error codes
that can be used by applications that use the Location API.
- GPS location sources - represents the GPS source (for example, internal GPS receiver).
These constants are used in
LocationInfo
methods to query the
available and supported location sources. These constants are also used in the
BlackBerryLocation
and BlackBerryLocationProvider
classes to
indicate the type of location source.
- GPS modes - represents the GPS mode to use when requesting a location fix. You can set a
specific GPS mode in a
BlackBerryCriteria
object.
These modes are also used to indicate the mode that was used to obtain a
BlackBerryLocation
.
- methods to query GPS configuration information for GPS modes and sources
- a method to query the error that was received when a GPS fix cannot be obtained
You can retrieve the last error that was received when a GPS fix is unsuccessful by
invoking GPSInfo.getLastGPSError()
. You can use the error code to help
determine why the application failed to obtain any GPS fix after
its LocationListener
receives a
LocationProvider.TEMPORARILY_UNAVAILABLE
event, or after it receives a LocationException from a
LocationProvider.getLocation()
call, as
in the following example:
if (GPSInfo.getLastGPSError() != GPSInfo.GPS_ERROR_NONE) {
// an error occurred, process it
} else {
// no additional error
}
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
Method Summary |
|
static int |
getDefaultGPSMode()
Provides the default GPS mode when GPS Criteria is not specified. |
|
static Enumeration |
getGPSDataSource()
Provides a list of GPS data sources. |
|
static int |
getLastGPSError()
Returns the last error received when a GPS fix could not be obtained. |
|
static boolean |
isGPSModeAvailable(int mode)
Determines whether a given GPS mode is available for use. |
GPS_ERROR_NONE
public static final int GPS_ERROR_NONE
An error status indicating no GPS error occured.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_NO_FIX_IN_ALLOTTED_TIME
public static final int GPS_ERROR_NO_FIX_IN_ALLOTTED_TIME
An error status indicating no GPS fix can be obtained in the allotted time.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_DEGRADED_FIX_IN_ALLOTTED_TIME
public static final int GPS_ERROR_DEGRADED_FIX_IN_ALLOTTED_TIME
An error status indicating a degraded GPS fix with poor accuracy.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_TIMEOUT_NO_FIX_NO_ASSIST_DATA
public static final int GPS_ERROR_TIMEOUT_NO_FIX_NO_ASSIST_DATA
An error status indicating no fix could be obtained in the allotted time,
and assisted mode could not be used.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_TIMEOUT_DEGRADED_FIX_NO_ASSIST_DATA
public static final int GPS_ERROR_TIMEOUT_DEGRADED_FIX_NO_ASSIST_DATA
An error status indicating a degraded fix with poor accuracy and assisted
mode could not be used.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_LOW_BATTERY
public static final int GPS_ERROR_LOW_BATTERY
An error status indicating low battery power on the device and a fix cannot be obtained.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_CHIPSET_DEAD
public static final int GPS_ERROR_CHIPSET_DEAD
An error status indicating the GPS chipset is inoperable and a fix cannot be obtained.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_INVALID_REQUEST
public static final int GPS_ERROR_INVALID_REQUEST
An error status indicating the GPS fix request is invalid.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_PRIVACY_ACCESS_DENIED
public static final int GPS_ERROR_PRIVACY_ACCESS_DENIED
An error status indicating a privacy setting denied access for obtaining a fix.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_ALMANAC_OUTDATED
public static final int GPS_ERROR_ALMANAC_OUTDATED
An error status indicating that the almanac is outdated.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_SERVICE_UNAVAILABLE
public static final int GPS_ERROR_SERVICE_UNAVAILABLE
An error status indicating that GPS is not available because there is no available
cellular service, data service or resources.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_GPS_LOCKED
public static final int GPS_ERROR_GPS_LOCKED
An error status indicating that the GPS is locked.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_NO_SATELLITE_IN_VIEW
public static final int GPS_ERROR_NO_SATELLITE_IN_VIEW
An error status indicating there are no satellites in view, or the
signal strength is too low to obtain a fix.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_AUTHENTICATION_FAILURE
public static final int GPS_ERROR_AUTHENTICATION_FAILURE
An error status indicating authentication failed with the network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_NETWORK_CONNECTION_FAILURE
public static final int GPS_ERROR_NETWORK_CONNECTION_FAILURE
An error status indicating a failure to connect to the data network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_ERROR_INVALID_NETWORK_CREDENTIAL
public static final int GPS_ERROR_INVALID_NETWORK_CREDENTIAL
An error status indicating invalid network credentials.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
GPS_MODE_NONE
public static final int GPS_MODE_NONE
Specifies no GPS mode.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CELLSITE
public static final int GPS_MODE_CELLSITE
- Specifies the cellsite GPS mode. If this mode is not supported by the wireless
service provider, the optimal geolocation is requested.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_ASSIST
public static final int GPS_MODE_ASSIST
Specifies the assisted GPS mode.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_AUTONOMOUS
public static final int GPS_MODE_AUTONOMOUS
Specifies the autonomous GPS mode.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CDMA_MS_BASED
public static final int GPS_MODE_CDMA_MS_BASED
Specifies the MS-BASED GPS mode which applies only to devices operating on the CDMA network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CDMA_MS_ASSIST
public static final int GPS_MODE_CDMA_MS_ASSIST
Specifies the MS-ASSIST GPS mode which applies only to devices operating on the CDMA network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CDMA_DATA_OPTIMAL
public static final int GPS_MODE_CDMA_DATA_OPTIMAL
Specifies the DATA OPTIMAL GPS mode which applies only to devices operating on the CDMA network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CDMA_SPEED_OPTIMAL
public static final int GPS_MODE_CDMA_SPEED_OPTIMAL
Specifies the SPEED OPTIMAL GPS mode which applies only to devices operating on the CDMA network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_CDMA_ACCURACY_OPTIMAL
public static final int GPS_MODE_CDMA_ACCURACY_OPTIMAL
Specifies the ACCURACY OPTIMAL GPS mode which applies only to devices operating on the CDMA network.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_MODE_BT
public static final int GPS_MODE_BT
Specifies using Bluetooth GPS.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_DEVICE_INTERNAL
public static final int GPS_DEVICE_INTERNAL
Indicates an internal GPS receiver.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
GPS_DEVICE_BLUETOOTH
public static final int GPS_DEVICE_BLUETOOTH
Indicates a Bluetooth GPS receiver.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
isGPSModeAvailable
public static boolean isGPSModeAvailable(int mode)
- Determines whether a given GPS mode is available for use.
If a Bluetooth GPS receiver is used, the GPS mode is irrelevant because
all GPS modes are available.
- Parameters:
mode
- The GPS mode can be one of the following:
GPSInfo.GPS_MODE_CELLSITE
GPSInfo.GPS_MODE_ASSIST
GPSInfo.GPS_MODE_AUTONOMOUS
GPSInfo.GPS_MODE_CDMA_MS_BASED
GPSInfo.GPS_MODE_CDMA_MS_ASSIST
GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL
GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL
GPSInfo.GPS_MODE_CDMA_DATA_OPTIMAL
GPSInfo.GPS_MODE_BT
- Returns:
true
if the GPS mode is available, false
otherwise.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getDefaultGPSMode
public static int getDefaultGPSMode()
- Provides the default GPS mode when GPS Criteria is not specified.
The default GPS mode is determined using the GPS capability supported by the network. The order of preference is
Assisted, Autonomous, and then Cellsite. An assisted mode is returned as the default mode only if PDE credentials
have been authenticated or are not required.
- Returns:
- The default GPS mode used. The GPS mode can be one the following:
GPSInfo.GPS_MODE_AUTONOMOUS
GPSInfo.GPS_MODE_ASSIST
(or GPSInfo.GPS_MODE_CDMA_MS_BASED
if extended CDMA modes are available)
GPSInfo.GPS_MODE_CELLSITE
GPSInfo.GPS_MODE_BT
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getGPSDataSource
public static Enumeration getGPSDataSource()
- Provides a list of GPS data sources.
- Returns:
- An enumeration of GPS data sources (String).
This includes internal GPS receivers and Bluetooth devices (if available).
Returns
null
if there is no GPS data source. - Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getLastGPSError
public static int getLastGPSError()
- Returns the last error received when a GPS fix could not be obtained.
- Returns:
- An error response code.
The error can be one following:
GPSInfo.GPS_ERROR_NONE
GPSInfo.GPS_ERROR_NO_FIX_IN_ALLOTTED_TIME
GPSInfo.GPS_ERROR_DEGRADED_FIX_IN_ALLOTTED_TIME
GPSInfo.GPS_ERROR_TIMEOUT_NO_FIX_NO_ASSIST_DATA
GPSInfo.GPS_ERROR_TIMEOUT_DEGRADED_FIX_NO_ASSIST_DATA
GPSInfo.GPS_ERROR_LOW_BATTERY
GPSInfo.GPS_ERROR_CHIPSET_DEAD
GPSInfo.GPS_ERROR_INVALID_REQUEST
GPSInfo.GPS_ERROR_PRIVACY_ACCESS_DENIED
GPSInfo.GPS_ERROR_ALMANAC_OUTDATED
GPSInfo.GPS_ERROR_SERVICE_UNAVAILABLE
GPSInfo.GPS_ERROR_GPS_LOCKED
GPSInfo.GPS_ERROR_NO_SATELLITE_IN_VIEW
GPSInfo.GPS_ERROR_AUTHENTICATION_FAILURE
GPSInfo.GPS_ERROR_NETWORK_CONNECTION_FAILURE
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal