Retrieving a location provider

Development Guide

Search This Document

Download PDF

After you specify the GPS mode, you must retrieve the location provider that your application uses to support the GPS mode. A location provider represents the source of the location information and it works based on given criteria (for example, the horizontal accuracy and the power usage) .

If the application uses the Criteria class from the JSR 179 package to specify a GPS mode, then the application must retrieve an instance of the LocationProvider class. If the application uses the BlackBerryCriteria class, then the application must retrieve an instance of the BlackBerryLocationProvider class.

A BlackBerryLocationProvider object extends the javax.microedition.location.LocationProvider class. You can use BlackBerryLocationProvider to perform the following actions:

Process a location request that you specify in the net.rim.device.api.gps.BlackBerryCriteria object.
Pause and resume the location listener.
Retrieve the GPS receiver type including an internal or a Bluetoothenabled GPS receiver.

When the location listener is in a paused state, the application does not receive GPS fixes. The location listener can be in a ready state while also in a paused state.

Retrieve a location provider by using the LocationProvider class

Import the required classes.
```
import javax.microedition.location.*;
```

Create a class and a constructor.

public class handleGPS
{
   public handleGPS()
   {
   }
}

In the constructor, create an instance of the Criteria class.
```
Criteria myCriteria = new Criteria();
```

In the constructor, configure the Criteria object to use the specified GPS mode. In the following code sample, autonomous mode is specified by invoking setCostAllowed(false).

int myMode = 2; // AUTONOMOUS

switch ( myMode )
{
   case 0: // CELLSITE
      myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);
      myCriteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);
      myCriteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT);
      myCriteria.setCostAllowed(true);
      break;

   case 1: // ASSIST
      myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);
      myCriteria.setHorizontalAccuracy(100);
      myCriteria.setVerticalAccuracy(100);
      myCriteria.setCostAllowed(true);
      break;

   case 2: // AUTONOMOUS
      myCriteria.setCostAllowed(false);
      break;
}

In the constructor, create a try/catch block. Within the block, create a LocationProvider object by invoking getInstance().

try
{
    LocationProvider myProvider =
        LocationProvider.getInstance(myCriteria);
}
catch ( LocationException lex )
{
    return;
}

Code sample: Retrieving a location provider by using the LocationProvider class

import javax.microedition.location.*;

public class handleGPS
{
    public handleGPS()
    {
        Criteria myCriteria = new Criteria();

        int myMode = 2; // AUTONOMOUS

        switch ( myMode )
        {
            case 0: // CELLSITE
                myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);
                myCriteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);
                myCriteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT);
                myCriteria.setCostAllowed(true);
                break;

            case 1: // ASSIST
                myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);
                myCriteria.setHorizontalAccuracy(100);
                myCriteria.setVerticalAccuracy(100);
                myCriteria.setCostAllowed(true);
                break;

            case 2: // AUTONOMOUS
                myCriteria.setCostAllowed(false);
                break;
        }

        try
        {
            LocationProvider myProvider = LocationProvider.getInstance(myCriteria);
        }
        catch ( LocationException lex )
        {
            return;
        }
    }
}

Controlling location tracking by using the BlackBerryLocationProvider class

The net.rim.device.api.gps.BlackBerryLocationProvider class extends the javax.microedition.location.LocationProvider class and it is required for BlackBerry device applications that use the BlackBerry extensions to JSR 179. You can use the methods that are provided in the BlackBerryLocationProvider class to control location tracking.

Method	Description
`getProviderType()`	This method retrieves the source of the location information. The source is either an internal or external GPS receiver.
`pauseLocationTracking(int interval)`	This method pauses location tracking and stops receiving GPS fixes. You can pass an interval parameter, specified in seconds, to make sure that the GPS receiver remains active during the pause interval. You can pass an interval of 0 to indefinitely stop location tracking and make the GPS receiver inactive.
`resumeLocationTracking()`	This method resumes location tracking after it is in a paused state.
`stopLocationTracking()`	This method stops location tracking only if tracking was previously started. Your application must invoke `BlackBerryLocationProvider.reset()` before it restarts location tracking by using the same location provider.

Control location tracking by using the BlackBerryLocationProvider class

You can pause, resume, and stop location tracking by using the net.rim.device.api.gps.BlackBerryLocationProvider class.

Import the required classes.

import net.rim.device.api.gps.*;
import javax.microedition.location.*;

Create a new class and a constructor.

public class handleGPS
{
    static BlackBerryLocationProvider myProvider;

    public handleGPS()
    {
    }
}

In the constructor, create a try/catch block. In the block, create an instance of the BlackBerryCriteria class by passing the GPS mode as a parameter to the constructor.
```
try
{
    BlackBerryCriteria myCriteria =
      new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);
}
catch ( UnsupportedOperationException uoex )
{
    return;
}
```

In the try part of the block, create a new try/catch block. In this block, create an instance of the BlackBerryLocationProvider class by retrieving an instance of the BlackBerryCriteria class. Invoke setLocationListener() by passing the interval value, timeout value, and maximum age as parameters to add a LocationListener.

try
{
    myProvider = (BlackBerryLocationProvider)
      LocationProvider.getInstance(myCriteria);
    myProvider.setLocationListener(new handleGPSListener(), 10, -1, -1);
}
catch ( LocationException lex )
{
    return;
}

myProvider.pauseLocationTracking(30);
myProvider.resumeLocationTracking();
myProvider.stopLocationTracking();

Outside of the try/catch block, invoke pauseLocationTracking(), resumeLocationTracking(), or stopLocationTracking() to pause, resume, or stop location tracking.
```
myProvider.pauseLocationTracking(30);
myProvider.resumeLocationTracking();
myProvider.stopLocationTracking();
```

In the class, implement the LocationListener interface. Implement the basic framework for the locationUpdated() method, and the providerStateChanged() method.

public static class handleGPSListener implements LocationListener
{
    public void locationUpdated(LocationProvider provider, Location location)
    {
        if (location.isValid())
        {}
        else
        {}
    }

    public void providerStateChanged(LocationProvider provider, int newState)
    {
        if (newState == LocationProvider.AVAILABLE)
        {}
        else if (newState == LocationProvider.OUT_OF_SERVICE)
        {}
        else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE )
        {}
    }
}

Code sample: Using the BlackBerryLocationProvider class to control location tracking

import net.rim.device.api.gps.*;
import javax.microedition.location.*;

public class handleGPS
{
    static BlackBerryLocationProvider myProvider;

    public handleGPS()
    {
        try
        {
            BlackBerryCriteria myCriteria =
              new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);

            try
            {
                myProvider = (BlackBerryLocationProvider)
                  LocationProvider.getInstance(myCriteria);
                myProvider.setLocationListener(new handleGPSListener(), 10, -1, -1);
            }
            catch ( LocationException lex )
            {
                return;
            }

            myProvider.pauseLocationTracking(30);
            myProvider.resumeLocationTracking();
            myProvider.stopLocationTracking();
        }
        catch ( UnsupportedOperationException uoex )
        {
            return;
        }

        return;
    }

    public static class handleGPSListener implements LocationListener
    {
        public void locationUpdated(LocationProvider provider, Location location)
        {
            if (location.isValid())
            {
                // do something
            }
            else
            {
                // invalid location
            }
        }

        public void providerStateChanged(LocationProvider provider, int newState)
        {
            if (newState == LocationProvider.AVAILABLE)
            {
                // available
            }
            else if (newState == LocationProvider.OUT_OF_SERVICE)
            {
                // GPS unavailable due to IT policy specification
            }
            else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE )
            {
                // no GPS fix
            }
        }
    }
}

Retrieve a location provider by using the BlackBerryLocationProvider class

Import the required classes.

import net.rim.device.api.gps.*;
import javax.microedition.location.*;

Create a class and a constructor.

public class handleGPS
{
    static BlackBerryCriteria myCriteria;

    public handleGPS()
    {
    }
}

In the constructor, create a try/catch block. In the block, create an instance of the BlackBerryCriteria class and pass the GPS mode to the constructor. Create a second try/catch block, then create an instance of the BlackBerryLocationProvider class by invoking getInstance() to retrieve an instance of the BlackBerryCriteria object.

        try
        {
            myCriteria = new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);

            try
            {
                BlackBerryLocationProvider myProvider =
                  (BlackBerryLocationProvider)
                    LocationProvider.getInstance(myCriteria);
            }
            catch ( LocationException lex )
            {
                return;
            }
        }
        catch ( UnsupportedOperationException ex )
        {
            return;
        }
    }
}

Next topic: Retrieving the location of a BlackBerry device

Previous topic: Code sample: Specifying the PDE server information

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation