net.rim.device.api.gps
Class BlackBerryLocation

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





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.