net.rim.device.api.gps
Class BlackBerryLocationProvider

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