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

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:
A list 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





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.