Android
android.location
public class

android.location.LocationManager

java.lang.Object
android.location.LocationManager

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).

Summary

Constants

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

Public Methods

          void  addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent)
Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius.
          void  addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)
Creates a mock location provider and adds it to the set of active providers.
          void  clearTestProviderEnabled(String provider)
Removes any mock enabled value associated with the given provider.
          void  clearTestProviderLocation(String provider)
Removes any mock location associated with the given provider.
          void  clearTestProviderStatus(String provider)
Removes any mock status values associated with the given provider.
          List<String 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<String getProviders(Criteria criteria, boolean enabledOnly)
Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do.
          List<String getProviders(boolean enabledOnly)
Returns a list of the names of location providers.
          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  removeTestProvider(String provider)
Removes the mock location provider with the given name.
          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.
          void  setTestProviderEnabled(String provider, boolean enabled)
Sets a mock enabled value for the given provider.
          void  setTestProviderLocation(String provider, Location loc)
Sets a mock location for the given provider.
          void  setTestProviderStatus(String provider, int status, Bundle extras, long updateTime)
Sets mock status values for the given provider.
Methods inherited from class java.lang.Object

Details

Constants

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"

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"

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"

Public Methods

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

Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius. When the device detects that it has entered or exited the area surrounding the location, the given PendingIntent will be used to create an Intent to be fired.

The fired Intent will have a boolean extra added with key KEY_PROXIMITY_ENTERING. If the value is true, the device is entering the proximity region; if false, it is exiting.

Due to the approximate nature of position estimation, if the device passes through the given area briefly, it is possible that no Intent will be fired. Similarly, an Intent could be fired if the device passes very close to the given area but does not actually enter it.

After the number of milliseconds given by the expiration parameter, the location manager will delete this proximity alert and no longer monitor it. A value of -1 indicates that there should be no expiration time.

Internally, this method uses both NETWORK_PROVIDER and GPS_PROVIDER.

Parameters

latitude the latitude of the central point of the alert region
longitude the longitude of the central point of the alert region
radius the radius of the central point of the alert region, in meters
expiration time for this proximity alert, in milliseconds, or -1 to indicate no expiration
intent a PendingIntent that will be used to generate an Intent to fire when entry to or exit from the alert region is detected

Throws

SecurityException if no permission exists for the required providers.

public void addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)

Creates a mock location provider and adds it to the set of active providers.

Parameters

name the provider name

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if a provider with the given name already exists

public void clearTestProviderEnabled(String provider)

Removes any mock enabled value associated with the given provider.

Parameters

provider the provider name

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

public void clearTestProviderLocation(String provider)

Removes any mock location associated with the given provider.

Parameters

provider the provider name

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

public void clearTestProviderStatus(String provider)

Removes any mock status values associated with the given provider.

Parameters

provider the provider name

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

public List<String> 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

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

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

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.

public List<String> 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

public List<String> 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

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

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

public void removeTestProvider(String provider)

Removes the mock location provider with the given name.

Parameters

provider the provider name

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

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

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 milliseconds have elapsed since the last update and the position has changed by minDistance meters, a new notification may be provided. To obtain notifications as frequently as possible, set both parameters to 0.

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
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.

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 milliseconds have elapsed since the last update and the position has changed by minDistance meters, a new notification may be provided. To obtain notifications as frequently as possible, set both parameters to 0.

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
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.

public void setTestProviderEnabled(String provider, boolean enabled)

Sets a mock enabled value for the given provider. This value will be used in place of any actual value from the provider.

Parameters

provider the provider name
enabled the mock enabled value

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

public void setTestProviderLocation(String provider, Location loc)

Sets a mock location for the given provider. This location will be used in place of any actual location from the provider.

Parameters

provider the provider name
loc the mock location

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists

public void setTestProviderStatus(String provider, int status, Bundle extras, long updateTime)

Sets mock status values for the given provider. These values will be used in place of any actual values from the provider.

Parameters

provider the provider name
status the mock status
extras a Bundle containing mock extras
updateTime the mock update time

Throws

SecurityException if the ACCESS_MOCK_LOCATION permission is not present
IllegalArgumentException if no provider with the given name exists
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48