Beginning Android

LocationManager will give you a List of providers, which you can then present to the user for selection.

Or, you can create and populate a Criteria object, stating the particulars of what you want out of a LocationProvider, such as the following:

• setAltitudeRequired() to indicate if you need the current altitude or not

• setAccuracy() to set a minimum level of accuracy, in meters, for the position

• setCostAllowed() to control if the provider must be free or not (i.e., if it can incur a cost on behalf of the device user)

Given a filled-in Criteria object, call getBestProvider() on your LocationManager, and Android will sift through the criteria and give you the best answer. Note that not all of your criteria may be met — all but the monetary-cost criterion might be relaxed if nothing matches.

You are also welcome to hard-wire in a LocationProvider name (e.g., gps), perhaps just for testing purposes.

Once you know the name of the LocationProvider, you can call getLastKnownPosition() to find out where you were recently. Note, however, that “recently” might be fairly out-of-date (e.g., if the phone was turned off) or even null if there has been no location recorded for that provider yet. On the other hand, getLastKnownPosition() incurs no monetary or power cost, since the provider does not need to be activated to get the value.

These methods return a Location object, which can give you the latitude and longitude of the device in degrees as a Java double. If the particular location provider offers other data, you can get at that as well:

• For altitude, hasAltitude() will tell you if there is an altitude value, and getAltitude() will return the altitude in meters.

• For bearing (i.e., compass-style direction), hasBearing() will tell you if there is a bearing available, and getBearing() will return it as degrees east of true north.

• For speed, hasSpeed() will tell you if the speed is known, and getSpeed() will return the speed in meters per second.

A more likely approach to getting the Location from a LocationProvider, though, is to register for updates, as described in the next section.

On the Move

Not all location providers are necessarily immediately responsive. GPS, for example, requires activating a radio and getting a fix from the satellites before you get a location. That is why Android does not offer a getMeMyCurrentLocationNow() method. Combine that with the fact that your users may well want their movements to be reflected in your application, and you are probably best off registering for location updates and using that as your means of getting the current location.

The Weather and WeatherPlus sample applications (available in the Source Code area at http://apress.com) show how to register for updates — call requestLocationUpdates () on your LocationManager instance. This takes four parameters:

1. The name of the location provider you wish to use

2. How long, in milliseconds, must have elapsed before we might get a location update

3. How far, in meters, the device must have moved before we might get a location update

4. A LocationListener that will be notified of key location-related events, as shown in the following code:

LocationListener onLocationChange = new LocationListener() {
 public void onLocationChanged(Location location) {
  updateForecast(location);
 }
 public void onProviderDisabled(String provider) {
  // required for interface, not used
 }
 public void onProviderEnabled(String provider) {
  // required for interface, not used
 }
 public void onStatusChanged(String provider, int status,
  Bundle extras) {
  // required for interface, not used
 }
};

Here, all we do is call updateForecast() with the Location supplied to the onLocationChanged() callback method. The updateForecast() implementation, as shown in Chapter 30, builds a Web page with the current forecast for the location and sends a broadcast so the activity knows an update is available.

When you no longer need the updates, call removeUpdates() with the LocationListener you registered.

Are We There Yet? Are We There Yet? Are We There Yet?

Sometimes you want to know not where you are now, or even when you move, but when you get to where you’re going. This could be an end destination, or it could be getting to the next step on a set of directions so you can give the user the next turn.

To accomplish this, LocationManager offers addProximityAlert(). This registers a PendingIntent, which will be fired off when the device gets within a certain distance of a certain location. The addProximityAlert() method takes the following as parameters:

• The latitude and longitude of the position that you are interested in.

• A radius, specifying how close you should be to that position for the Intent to be raised.

• A duration for the registration, in milliseconds — after this period, the registration automatically lapses. A value of -1 means the registration lasts until you manually remove it via removeProximityAlert() .

• The PendingIntent to be raised when the device is within the “target zone” expressed by the position and radius.

Note that it is not guaranteed that you will actually receive an Intent if there is an interruption in location services or if the device is not in the target zone during the period of time the proximity alert is active. For example, if the position is off by a bit and the radius is a little too tight, the device might only skirt the edge of the target zone, or go by so quickly that the device’s location isn’t sampled while in the target zone.