net.rim.device.api.gps
Class BlackBerryLocationProvider

java.lang.Object
  javax.microedition.location.LocationProvider
      net.rim.device.api.gps.BlackBerryLocationProvider

public abstract class BlackBerryLocationProvider
extends LocationProvider

This is the starting point for applications using the JSR179 Extension API. A BlackBerryLocationProvider is an extension of the LocationProvider class in the JSR179 API. This extension allows an application to do the following:

1. Process a location request as specified in the BlackBerryCriteria object.
2. Pause and resume the location listener. When pausing the location listener, the application can specify the interval at which to keep the GPS warm. While in the pause state, the application will not receive any GPS fix.
3. Retrieve the GPS provider type, an internal GPS receiver or Bluetooth GPS receiver.

To support concurrent GPS and Geolocation location updates, it is possible to have a GPS BlackBerryLocationProvider along with a Geolocation BlackBerryLocationProvider within the same application.

An application needs to create two separate threads to request separate instances of BlackBerryLocationProvider, One thread to set the GPS location mode, and the other thread to set the geolocation mode as shown in the following example:

//In the Geolocation thread
try {
    BlackBerryLocationProvider provider =
        (BlackBerryLocationProvider)LocationProvider.getInstance(new BlackBerryCriteria(LocationInfo.GEOLOCATION_MODE_CELL));
} catch (LocationException) {
}

//In the GPS thread
try {
    BlackBerryLocationProvider provider =
        (BlackBerryLocationProvider)LocationProvider.getInstance(new BlackBerryCriteria(GPSInfo.GPS_MODE_CDMA_MS_BASED));
} catch (LocationException ) {
}
 

For multiple updates, an application can choose to implement one or two separate LocationListener instances to process the concurrent location updates. To determine the source of the BlackBerryLocation obtained from the BlackBerryLocationProvider instances, use BlackBerryLocation.getDataSource() or BlackBerryLocation.getGPSMode() .

Since:

BlackBerry API 5.0.0

Field Summary
static int	PAUSED Availability status code: the location provider is paused.

Fields inherited from class javax.microedition.location.LocationProvider

AVAILABLE, OUT_OF_SERVICE, TEMPORARILY_UNAVAILABLE

Method Summary
static Location	getLastKnownLocation() Returns the latest known location that the implementation has.
Location	getLocation(int maxAge, int timeout) Retrieves a Location with the constraints given by the Criteria associated with this class.
int	getProviderType() Returns the type of provider that is used.
void	pauseLocationTracking(int interval) This method allows the application to pause the location tracking.
void	resumeLocationTracking() This method allows an application to resume the location tracking.
void	stopLocationTracking() This method allows an application to stop the location tracking.

Methods inherited from class javax.microedition.location.LocationProvider

addProximityListener, getInstance, getLocation, getState, removeProximityListener, reset, setLocationListener

Methods inherited from class java.lang.Object

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

Field Detail

PAUSED

public static final int PAUSED

Availability status code: the location provider is paused.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Method Detail

getLastKnownLocation

public static Location getLastKnownLocation()

Returns the latest known location that the implementation has. This is the best estimate that the implementation has for the previously known location.

Applications can use this method to obtain the last known location and check the timestamp and other fields to determine if this is recent enough and good enough for the application to use without needing to make a new request for the current location.

Returns:

a location object. null is returned if the implementation doesn't have any previous location information.

Throws:

SecurityException - if the calling application does not have a permission to query the location information

Since:

BlackBerry API 7.0.0

getLocation

public Location getLocation(int maxAge,
                            int timeout)
                     throws LocationException,
                            InterruptedException

Retrieves a Location with the constraints given by the Criteria associated with this class. If no result could be retrieved, a LocationException is thrown. If the location can't be determined within the timeout period specified in the parameter, the method shall throw a LocationException.

If the provider is temporarily unavailable, the implementation shall wait and try to obtain the location until the timeout expires. If the provider is permanently unavailable, then the LocationException is thrown immediately.

Note that the individual Location returned might not fulfil exactly the criteria used for selecting this LocationProvider. The Criteria is used to select a location provider that typically is able to meet the defined criteria, but not necessarily for every individual location measurement.

Parameters:

maxAge - the time period in seconds within which the cached location on the device is considered acceptable. -1 is used to indicate that maxAge is to be ignored and the cached location is to be returned.

timeout - a timeout value in seconds an application is willing to wait to obtain a location.

Returns:

a BlackBerryLocation indicating the current location of the device. If successful, a location is returned as soon as it is available within the timeout period.

Throws:

LocationException - if the location couldn't be retrieved or if the timeout period expired, or if location query is disallowed by IT Policy or user, or if this method is called from the event thread.

InterruptedException - if the operation is interrupted by calling reset() from another thread

SecurityException - if the calling application does not have a permission to query the location information

IllegalArgumentException - if the timeout = 0 or timeout < -1

Since:

BlackBerry API 7.0.0

pauseLocationTracking

public void pauseLocationTracking(int interval)

This method allows the application to pause the location tracking. The application will not receive any GPS fix in this state.

Parameters:

interval - - use to keep the GPS warm for the application. A value of 0 means that the GPS will not be kept warm. A value greater than 0 will trigger the GPS to wake up at the interval specified.

Since:

BlackBerry API 5.0.0

resumeLocationTracking

public void resumeLocationTracking()

This method allows an application to resume the location tracking. This will have an effect only if the application had made a prior request to pause the location tracking.

Since:

BlackBerry API 5.0.0

stopLocationTracking

public void stopLocationTracking()

This method allows an application to stop the location tracking. This will have an effect only if the application had made a prior request to start the location tracking.

Invoking stopLocationTracking() will stop and clear the tracking session. To restart the location tracking session using the same location provider, the application must invoke reset() and then add a new listener to the location provider.

Since:

BlackBerry API 5.0.0

getProviderType

public int getProviderType()

Returns the type of provider that is used.

Returns:

provider type, which can be one of the following:

• GPSInfo.GPS_DEVICE_INTERNAL
• GPSInfo.GPS_DEVICE_BLUETOOTH
• LocationInfo.LOCATION_SOURCE_GEOLOCATION

Since:

BlackBerry API 5.0.0