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

The BlackBerryLocation class represents the extended set of location information. This includes partial location data (satellite count and average satellite signal strengh) that is produced before a complete GPS position can be obtained, the GPS mode used to get the location, and the status of the GPS fix.

Just like 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 doesn't have valid coordinates, but the getError() method can provide information about the reason why it was not possible to provide a valid Location. The periodic location updates to the LocationListener may return invalid Location objects if it isn't possible to determine the location.

Since:

BlackBerry API 5.0.0

Field Summary
static int	FAILOVER_MODE_ON Constant to indicate that the BlackBerryLocation object is produced as a result of a GPS failover.
static int	GPS_ERROR Constant to indicate that the BlackBerryLocation object is produced as a result of a GPS error.
static int	GPS_FIX_COMPLETE Constant to indicate that a complete GPS fix is available.
static int	GPS_FIX_PARTIAL Constant to indicate that the GPS fix contains satellite tracking information only.
static int	GPS_FIX_UNAVAILABLE Constant to indicate that a GPS fix is unavailable.
static int	SUBSEQUENT_MODE_ON Constant to indicate 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() This method returns the data source used to produce the GPS fix.
int	getError() This method returns the error associated with the BlackBerryLocation object, if any.
int	getGPSMode() Returns the mode used by the GPS system.
int	getSatelliteCount() Returns the current number of satellite count in view.
Enumeration	getSatelliteInfo() Returns the details of all satellites that were tracked.
int	getStatus() This method 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

Constant to indicate 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

Constant to indicate that the GPS fix contains satellite tracking information only. This is produced when an application has requested 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

Constant to indicate that a complete GPS fix is available. Satellite tracking information is present if it was requested by the application.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

GPS_ERROR

public static final int GPS_ERROR

Constant to indicate 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

Constant to indicate 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 produced an error and 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

Constant to indicate 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()

This method returns the error associated with the BlackBerryLocation object, if any.

Returns:

a GPS error. The GPS Error will typically be one of the errors defined in the GPSInfo class.

Since:

BlackBerry API 5.0.0

getStatus

public int getStatus()

This method returns the status of the BlackBerryLocation object.

Returns:

status which can be one of:

GPS_FIX_UNAVAILABLE

GPS_FIX_PARTIAL

GPS_FIX_COMPLETE

GPS_ERROR

FAILOVER_MODE_ON

SUBSEQUENT_MODE_ON

Since:

BlackBerry API 5.0.0

getDataSource

public int getDataSource()

This method returns the data source used to produce the GPS fix. The data source can either be internal GPS or Bluetooth GPS.

Returns:

GPS data source which is one of:

1 (GPSInfo.GPS_DEVICE_INTERNAL) - Internal GPS

2 (GPSInfo.GPS_DEVICE_BLUETOOTH) - Bluetooth GPS

Since:

BlackBerry API 5.0.0

getSatelliteCount

public int getSatelliteCount()

Returns the current number of satellite count in view.

Returns:

number of satellite in view

Since:

BlackBerry API 5.0.0

getSatelliteInfo

public Enumeration getSatelliteInfo()

Returns the details of all satellites that were tracked.

Returns:

a list of the satellites being tracked. If no satellites are tracked then null is returned.

Since:

BlackBerry API 5.0.0

getGPSMode

public int getGPSMode()

Returns the mode used by the GPS system.

Returns:

mode used by the GPS system to provide the location data

Since:

BlackBerry API 5.0.0

getAverageSatelliteSignalQuality

public int getAverageSatelliteSignalQuality()

Returns the average satellite signal quality - Carrier to Noise Ratio in dB.

Returns:

average satellite signal quality (range 0 to 60 dB)

Since:

BlackBerry API 5.0.0