net.rim.device.api.gps
Class BlackBerryLocation

java.lang.Object
  javax.microedition.location.Location
      net.rim.device.api.gps.BlackBerryLocation

public class BlackBerryLocation
extends Location

Represents an extended set of location information. This includes partial location data (satellite count and average satellite signal strength) that is produced before a complete GPS position can be obtained, the location mode or source used to get the location, and the status of the GPS fix.

Similar to a Location object, a BlackBerryLocation object may also be either 'valid' or 'invalid'. The validity can be queried using the isValid() method. A valid Location object represents a location with valid coordinates. An invalid Location object does not have valid coordinates. You can use the getError() method to retrieve information about why a valid location could not be provided. The periodic location updates to the LocationListener might return invalid Location objects if a location cannot be determined.

Since:

BlackBerry API 5.0.0

Field Summary
static int	FAILOVER_MODE_ON Indicates that the BlackBerryLocation object is produced as a result of a GPS failover.
static int	GPS_ERROR Indicates that the BlackBerryLocation object is produced as a result of a GPS error.
static int	GPS_FIX_COMPLETE Indicates that a complete GPS fix is available.
static int	GPS_FIX_PARTIAL Indicates that the GPS fix contains satellite tracking information only.
static int	GPS_FIX_UNAVAILABLE Indicates that a GPS fix is unavailable.
static int	SUBSEQUENT_MODE_ON Indicates that the BlackBerryLocation object is produced when the GPS uses a subsequent mode.

Fields inherited from class javax.microedition.location.Location

MTA_ASSISTED, MTA_UNASSISTED, MTE_ANGLEOFARRIVAL, MTE_CELLID, MTE_SATELLITE, MTE_SHORTRANGE, MTE_TIMEDIFFERENCE, MTE_TIMEOFARRIVAL, MTY_NETWORKBASED, MTY_TERMINALBASED

Method Summary
int	getAverageSatelliteSignalQuality() Returns the average satellite signal quality (carrier-to-noise ratio in dB).
int	getDataSource() Returns the source that provides the location.
int	getError() Returns any errors associated with the BlackBerryLocation object.
int	getGPSMode() Returns the mode used to obtain this location.
int	getSatelliteCount() Returns the current number of satellites that are in view.
Enumeration	getSatelliteInfo() Returns the details of all satellites that are tracked.
int	getStatus() Returns the status of the BlackBerryLocation object.

Methods inherited from class javax.microedition.location.Location

getAddressInfo, getCourse, getExtraInfo, getLocationMethod, getQualifiedCoordinates, getSpeed, getTimestamp, isValid

Methods inherited from class java.lang.Object

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

Field Detail

GPS_FIX_UNAVAILABLE

public static final int GPS_FIX_UNAVAILABLE

Indicates that a GPS fix is unavailable.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GPS_FIX_PARTIAL

public static final int GPS_FIX_PARTIAL

Indicates that the GPS fix contains satellite tracking information only. This is produced when an application requests satellite information (setting a flag in the GPS criteria object). The satellite tracking information consists of satellite IDs, signal quality, elevation and azimuth.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GPS_FIX_COMPLETE

public static final int GPS_FIX_COMPLETE

Indicates that a complete GPS fix is available. Satellite tracking information is present if it is requested by the application.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GPS_ERROR

public static final int GPS_ERROR

Indicates that the BlackBerryLocation object is produced as a result of a GPS error.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

FAILOVER_MODE_ON

public static final int FAILOVER_MODE_ON

Indicates that the BlackBerryLocation object is produced as a result of a GPS failover. A failover occurs when the first GPS mode requested by the application produces an error and the implementation is switching to the failover mode set in the Criteria object by the application.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SUBSEQUENT_MODE_ON

public static final int SUBSEQUENT_MODE_ON

Indicates that the BlackBerryLocation object is produced when the GPS uses a subsequent mode. A subsequent GPS mode is used when the first GPS mode requested by the application produced a valid fix and the implementation is switching to the subsequent mode set in the Criteria object by the application.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

getError

public int getError()

Returns any errors associated with the BlackBerryLocation object.

Returns:

A GPS error. The GPS error can be one of the errors defined in the GPSInfo class.

Since:

BlackBerry API 5.0.0

getStatus

public int getStatus()

Returns the status of the BlackBerryLocation object.

Returns:

The status, which can be one of the following:

BlackBerryLocation.GPS_FIX_UNAVAILABLE
BlackBerryLocation.GPS_FIX_PARTIAL
BlackBerryLocation.GPS_FIX_COMPLETE
BlackBerryLocation.GPS_ERROR
BlackBerryLocation.FAILOVER_MODE_ON
BlackBerryLocation.SUBSEQUENT_MODE_ON

Since:

BlackBerry API 5.0.0

getDataSource

public int getDataSource()

Returns the source that provides the location.

Returns:

The location source as defined in the GPSInfo and LocationInfo classes.

Since:

BlackBerry API 5.0.0

getSatelliteCount

public int getSatelliteCount()

Returns the current number of satellites that are in view.

Returns:

The number of satellites that are in view.

Since:

BlackBerry API 5.0.0

getSatelliteInfo

public Enumeration getSatelliteInfo()

Returns the details of all satellites that are tracked.

This method requires that satellite information be made available after a GPS request is performed. To enable satellite information, the application must invoke BlackBerryCriteria.setSatelliteInfoRequired(boolean, boolean) prior to retrieving an instance of a LocationProvider.

Note: This method applies to multiple fix requests only. Satellite information cannot be retrieved for single fix requests.

Returns:

An Enumeration of SatelliteInfo of the satellites that are tracked. If no satellites are tracked, or satellite information is not available, null is returned.

Since:

BlackBerry API 5.0.0

getGPSMode

public int getGPSMode()

Returns the mode used to obtain this location.

Returns:

The mode used to obtain this location. Valid modes are defined in GPSInfo and LocationInfo classes.

Since:

BlackBerry API 5.0.0

getAverageSatelliteSignalQuality

public int getAverageSatelliteSignalQuality()

Returns the average satellite signal quality (carrier-to-noise ratio in dB).

This method requires that satellite information be made available after a GPS request is performed. To enable satellite information, the application must invoke BlackBerryCriteria.setSatelliteInfoRequired(boolean, boolean) prior to retrieving an instance of a LocationProvider.

Note: This method applies to multiple fix requests only. Satellite information cannot be retrieved for single fix requests.

Returns:

The average satellite signal quality (range 0 to 60 dB). If satellite information is not available, 0 is returned.

Since:

BlackBerry API 5.0.0