android.location
Class LocationManager

java.lang.Object
  android.location.LocationManager

public class LocationManager
extends Object

This class provides access to the system location services. These services allow applications to obtain periodic updates of the device's geographical location, or to fire an application-specified Intent when the device enters the proximity of a given geographical location.

You do not instantiate this class directly; instead, retrieve it through Context.getSystemService(Context.LOCATION_SERVICE).

Field Summary

static String	GPS_PROVIDER Name of the GPS location provider.
static String	KEY_PROXIMITY_ENTERING Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..
static String	NETWORK_PROVIDER Name of the network location provider.

Method Summary

void	addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent)
List	getAllProviders() Returns a list of the names of all known location providers.
String	getBestProvider(Criteria criteria, boolean enabledOnly) Returns the name of the provider that best meets the given criteria.
Location	getLastKnownLocation(String provider) Returns a Location indicating the data from the last known location fix obtained from the given provider.
LocationProvider	getProvider(String name) Returns the information associated with the location provider of the given name, or null if no provider exists by that name.
List	getProviders(boolean enabledOnly) Returns a list of the names of location providers.
List	getProviders(Criteria criteria, boolean enabledOnly) Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do.
boolean	isProviderEnabled(String provider) Returns the current enabled/disabled status of the given provider.
void	removeProximityAlert(PendingIntent intent) Removes the proximity alert with the given PendingIntent.
void	removeUpdates(LocationListener listener) Removes any current registration for location updates of the current activity with the given LocationListener.
void	requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener) Registers the current activity to be notified periodically by the named provider.
void	requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper) Registers the current activity to be notified periodically by the named provider.

Methods inherited from class java.lang.Object

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

Field Detail

NETWORK_PROVIDER

public static final String NETWORK_PROVIDER

Name of the network location provider. This provider determines location based on availability of cell tower and WiFi access points. Results are retrieved by means of a network lookup. Requires either of the permissions android.permission.ACCESS_COARSE_LOCATION or android.permission.ACCESS_FINE_LOCATION.
Constant Value: "network"

See Also:

Constant Field Values

GPS_PROVIDER

public static final String GPS_PROVIDER

Name of the GPS location provider. This provider determines location using satellites. Depending on conditions, this provider may take a while to return a location fix. Requires the permission android.permissions.ACCESS_FINE_LOCATION.

The extras Bundle for the GPS location provider can contain the following key/value pairs:

• satellites - the number of satellites used to derive the fix

Constant Value: "gps"

See Also:

Constant Field Values

KEY_PROXIMITY_ENTERING

public static final String KEY_PROXIMITY_ENTERING

Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..
Constant Value: "entering"

See Also:

Constant Field Values

Method Detail

getAllProviders

public List getAllProviders()

Returns a list of the names of all known location providers. All providers are returned, including ones that are not permitted to be accessed by the calling activity or are currently disabled.

Returns:

list of Strings containing names of the providers

getProviders

public List getProviders(boolean enabledOnly)

Returns a list of the names of location providers. Only providers that are permitted to be accessed by the calling activity will be returned.

Parameters:

enabledOnly - if true then only the providers which are currently enabled are returned.

Returns:

list of Strings containing names of the providers

getProvider

public LocationProvider getProvider(String name)

Returns the information associated with the location provider of the given name, or null if no provider exists by that name.

Parameters:

name - the provider name

Returns:

a LocationProvider, or null

Throws:

IllegalArgumentException - if name is null

SecurityException - if the caller is not permitted to access the given provider.

getProviders

public List getProviders(Criteria criteria,
                         boolean enabledOnly)

Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do. Only providers that are permitted to be accessed by the calling activity will be returned.

Parameters:

criteria - the criteria that the returned providers must match

enabledOnly - if true then only the providers which are currently enabled are returned.

Returns:

list of Strings containing names of the providers

getBestProvider

public String getBestProvider(Criteria criteria,
                              boolean enabledOnly)

Returns the name of the provider that best meets the given criteria. Only providers that are permitted to be accessed by the calling activity will be returned. If several providers meet the criteria, the one with the best accuracy is returned. If no provider meets the criteria, the criteria are loosened in the following sequence:

• power requirement
• accuracy
• bearing
• speed
• altitude

Note that the requirement on monetary cost is not removed in this process.

Parameters:

criteria - the criteria that need to be matched

enabledOnly - if true then only a provider that is currently enabled is returned

Returns:

name of the provider that best matches the requirements

requestLocationUpdates

public void requestLocationUpdates(String provider,
                                   long minTime,
                                   float minDistance,
                                   LocationListener listener)

Registers the current activity to be notified periodically by the named provider. Periodically, the supplied LocationListener will be called with the current Location or with status updates.

It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.

The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime is greater than 0, the LocationManager could potentially rest for minTime milliseconds between location updates to conserve power. If minDistance is greater than 0, a location will only be broadcasted if the device moves by minDistance meters. To obtain notifications as frequently as possible, set both parameters to 0.

Background services should be careful about setting a sufficiently high minTime so that the device doesn't consume too much power by keeping the GPS or wireless radios on all the time. In particular, values under 60000ms are not recommended.

The calling thread must be a Looper thread such as the main thread of the calling Activity.

Parameters:

provider - the name of the provider with which to register

minTime - the minimum time interval for notifications, in milliseconds. This field is only used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value.

minDistance - the minimum distance interval for notifications, in meters

listener - a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update

Throws:

IllegalArgumentException - if provider is null or doesn't exist

IllegalArgumentException - if listener is null

RuntimeException - if the calling thread has no Looper

SecurityException - if no suitable permission is present for the provider.

requestLocationUpdates

public void requestLocationUpdates(String provider,
                                   long minTime,
                                   float minDistance,
                                   LocationListener listener,
                                   Looper looper)

Registers the current activity to be notified periodically by the named provider. Periodically, the supplied LocationListener will be called with the current Location or with status updates.

It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.

In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.

The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime is greater than 0, the LocationManager could potentially rest for minTime milliseconds between location updates to conserve power. If minDistance is greater than 0, a location will only be broadcasted if the device moves by minDistance meters. To obtain notifications as frequently as possible, set both parameters to 0.

Background services should be careful about setting a sufficiently high minTime so that the device doesn't consume too much power by keeping the GPS or wireless radios on all the time. In particular, values under 60000ms are not recommended.

The supplied Looper is used to implement the callback mechanism.

Parameters:

provider - the name of the provider with which to register

minTime - the minimum time interval for notifications, in milliseconds. This field is only used as a hint to conserve power, and actual time between location updates may be greater or lesser than this value.

minDistance - the minimum distance interval for notifications, in meters

listener - a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update

looper - a Looper object whose message queue will be used to implement the callback mechanism.

Throws:

IllegalArgumentException - if provider is null or doesn't exist

IllegalArgumentException - if listener is null

IllegalArgumentException - if looper is null

SecurityException - if no suitable permission is present for the provider.

removeUpdates

public void removeUpdates(LocationListener listener)

Removes any current registration for location updates of the current activity with the given LocationListener. Following this call, updates will no longer occur for this listener.

Parameters:

listener - {#link LocationListener} object that no longer needs location updates

Throws:

IllegalArgumentException - if listener is null

addProximityAlert

public void addProximityAlert(double latitude,
                              double longitude,
                              float radius,
                              long expiration,
                              PendingIntent intent)

removeProximityAlert

public void removeProximityAlert(PendingIntent intent)

Removes the proximity alert with the given PendingIntent.

Parameters:

intent - the PendingIntent that no longer needs to be notified of proximity alerts

isProviderEnabled

public boolean isProviderEnabled(String provider)

Returns the current enabled/disabled status of the given provider. If the user has enabled this provider in the Settings menu, true is returned otherwise false is returned

Parameters:

provider - the name of the provider

Returns:

true if the provider is enabled

Throws:

SecurityException - if no suitable permission is present for the provider.

IllegalArgumentException - if provider is null or doesn't exist

getLastKnownLocation

public Location getLastKnownLocation(String provider)

Returns a Location indicating the data from the last known location fix obtained from the given provider. This can be done without starting the provider. Note that this location could be out-of-date, for example if the device was turned off and moved to another location.

If the provider is currently disabled, null is returned.

Parameters:

provider - the name of the provider

Returns:

the last known location for the provider, or null

Throws:

SecurityException - if no suitable permission is present for the provider.

IllegalArgumentException - if provider is null or doesn't exist