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
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, getLastKnownLocation, 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

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