android.location
public class
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
Public Constructors
| LocationManager(ILocationManager service, Handler handler) |
Public Methods
| void | addProximityAlert(double latitude, double longitude, float radius, long expiration, Intent intent) | ||||
| Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius. | |||||
| LocationProvider | getBestProvider(Criteria criteria) | ||||
| Returns the provider that best meets the given criteria. | |||||
| Location | getCurrentLocation(String provider) | ||||
| Returns a new location fix from the given provider. | |||||
| 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 location provider with the given name, or null if no provider exists by that name. | |||||
| int | getProviderStatus(String provider) | ||||
| Returns a information on the status of the given provider. | |||||
| List | getProviders() | ||||
| Returns a list of location providers. | |||||
| List | getProviders(Criteria criteria) | ||||
| Returns a list of LocationProviders that satisfy the given criteria, or null if none do. | |||||
| void | removeProximityAlert(Intent intent) | ||||
| Removes the proximity alert with the given intent. | |||||
| void | removeUpdates(Intent intent) | ||||
| Removes any current registration of the current activity with the given Intent. | |||||
| void | requestUpdates(LocationProvider provider, long minTime, float minDistance, Intent intent) | ||||
| Registers the current activity to be notified periodically by the named provider. | |||||
| void | requestUpdates(Criteria criteria, long minTime, float minDistance, Intent intent) | ||||
| Registers the current activity to be notified periodically by a provider meeting the given criteria for accuracy, power usage, etc. | |||||
Methods inherited
from class
java.lang.Object
Details
Public Constructors
public LocationManager(ILocationManager service, Handler handler)
Public Methods
public void addProximityAlert(double latitude, double longitude, float radius, long expiration, Intent 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 Intent will be fired.
The intent will have an extra added with key "entering" and a boolean value. 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, a number of providers may be used in order to minimize battery usage. Only providers for which there are valid permissions will be used.
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 | the Intent to fire when entry to the alert region is detected |
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|---|
| SecurityException | if no permission exists for the required providers. |
public LocationProvider getBestProvider(Criteria criteria)
Returns 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 (up to 10 km)
- bearing
- speed
- altitude
Note that the requirement on monetary cost is not removed in this process.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public Location getCurrentLocation(String provider)
Returns a new location fix from the given provider.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|---|
| SecurityException | if the provider is "gps" and the permission android.permission.ACCESS_GPS is not granted. |
| SecurityException | if the provider is "agps" and the permission android.permission.ACCESS_ASSISTED_GPS is not granted. |
| SecurityException | if the provider is "cell" and the permission android.permission.ACCESS_CELL_ID is not granted. |
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.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|---|
| SecurityException | if the provider is "gps" and the permission android.permission.ACCESS_GPS is not granted. |
| SecurityException | if the provider is "agps" and the permission android.permission.ACCESS_ASSISTED_GPS is not granted. |
| SecurityException | if the provider is "cell" and the permission android.permission.ACCESS_CELL_ID is not granted. |
public LocationProvider getProvider(String name)
Returns the location provider with the given name, or null if
no provider exists by that name.
Parameters
| name | the provider name |
|---|
Returns
- a LocationProvider, or null
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public int getProviderStatus(String provider)
Returns a information on the status of the given provider.
LocationProvider.OUT_OF_SERVICE is returned if the provider is
out of service, and this is not expected to change in the near
future; LocationProvider.TEMPRORAILY_UNAVAILABLE is returned if
the provider is temporarily unavailable but is expected to be available
shortly; and LocationProvider.AVAILABLE is returned if the
provider is currently available.
Parameters
| provider | a provider name |
|---|
Throws
| IllegalArgumentException | if the provider is unknown |
|---|---|
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
| SecurityException | if the provider is "gps" and the permission android.permission.ACCESS_GPS is not granted. |
| SecurityException | if the provider is "agps" and the permission android.permission.ACCESS_ASSISTED_GPS is not granted. |
| SecurityException | if the provider is "cell" and the permission android.permission.ACCESS_CELL_ID is not granted. |
public List getProviders()
Returns a list of location providers. Only providers that are permitted
to be accessed by the calling activity will be returned.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public List getProviders(Criteria criteria)
Returns a list 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.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public void removeProximityAlert(Intent intent)
Removes the proximity alert with the given intent.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public void removeUpdates(Intent intent)
Removes any current registration of the current activity with
the given Intent. Following this call, updates will no
longer occur from the provider for this intent.
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|
public void requestUpdates(LocationProvider provider, long minTime, float minDistance, Intent intent)
Registers the current activity to be notified periodically by
the named provider. Periodically, an Intent will be fired.
The fired Intent will be equivalent to the provided Intent in
the sense of the Intent.filterEquals() method. The location
data may be retrieved from the fired Intent as a Location
object by calling intent.getExtra("location").
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.
Parameters
| provider | the provider with which to register |
|---|---|
| minTime | the minimum time interval for notifications, in milliseconds |
| minDistance | the minimum distance interval for notifications, in meters |
| intent | an intent to be fired for each location update |
Throws
| IllegalArgumentException | if provider is null |
|---|---|
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
| SecurityException | if the provider is "gps" and the permission android.permission.ACCESS_GPS is not granted. |
| SecurityException | if the provider is "agps" and the permission android.permission.ACCESS_ASSISTED_GPS is not granted. |
| SecurityException | if the provider is "cell" and the permission android.permission.ACCESS_CELL_ID is not granted. |
public void requestUpdates(Criteria criteria, long minTime, float minDistance, Intent intent)
Registers the current activity to be notified periodically by a
provider meeting the given criteria for accuracy, power usage,
etc. Only providers that are permitted to be accessed by the calling
activity will be utilized.
Periodically, an Intent will be fired. The fired Intent will be equivalent to the provided Intent in the sense of the Intent.filterEquals() method. The location data may be retrieved from the fired Intent as a Location object by calling intent.getExtra("location").
The frequency of notification may be controlled using the minTime and minDistance parameters. If either minTime milliseconds have elapsed since the last update, or 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.
Parameters
| criteria | Criteria the criteria required for the provider |
|---|---|
| minTime | the minimum time interval for notifications, in milliseconds |
| minDistance | the minimum distance interval for notifications, in meters |
| intent | an Intent to be fired for each location update |
Throws
| SecurityException | if the permission android.permission.ACCESS_LOCATION is not granted. |
|---|---|
| SecurityException | if no permitted providers are found. |