| 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).
Unless noted, all Location API methods require
the ACCESS_COARSE_LOCATION or
ACCESS_FINE_LOCATION permissions.
If your application only has the coarse permission then it will not have
access to the GPS or passive location providers. Other providers will still
return location results, but the update rate will be throttled and the exact
location will be obfuscated to a coarse level of accuracy.
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| String | GPS_PROVIDER | Name of the GPS location provider. | |||||||||
| String | KEY_LOCATION_CHANGED | Key used for a Bundle extra holding a Location value when a location change is broadcast using a PendingIntent. | |||||||||
| String | KEY_PROVIDER_ENABLED | Key used for a Bundle extra holding an Boolean status value when a provider enabled/disabled event is broadcast using a PendingIntent. | |||||||||
| String | KEY_PROXIMITY_ENTERING | Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false).. | |||||||||
| String | KEY_STATUS_CHANGED | Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent. | |||||||||
| String | MODE_CHANGED_ACTION | Broadcast intent action when LOCATION_MODE changes. |
|||||||||
| String | NETWORK_PROVIDER | Name of the network location provider. | |||||||||
| String | PASSIVE_PROVIDER | A special location provider for receiving locations without actually initiating a location fix. | |||||||||
| String | PROVIDERS_CHANGED_ACTION | Broadcast intent action when the configured location providers change. | |||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Adds a GPS status listener.
| |||||||||||
Adds an NMEA listener.
| |||||||||||
Set a proximity alert for the location given by the position
(latitude, longitude) and the given radius.
| |||||||||||
Creates a mock location provider and adds it to the set of active providers.
| |||||||||||
Removes any mock enabled value associated with the given provider.
| |||||||||||
Removes any mock location associated with the given provider.
| |||||||||||
Removes any mock status values associated with the given provider.
| |||||||||||
Returns a list of the names of all known location providers.
| |||||||||||
Returns the name of the provider that best meets the given criteria.
| |||||||||||
Retrieves information about the current status of the GPS engine.
| |||||||||||
Returns a Location indicating the data from the last known
location fix obtained from the given provider.
| |||||||||||
Returns the information associated with the location provider of the
given name, or null if no provider exists by that name.
| |||||||||||
Returns a list of the names of location providers.
| |||||||||||
Returns a list of the names of LocationProviders that satisfy the given
criteria, or null if none do.
| |||||||||||
Returns the current enabled/disabled status of the given provider.
| |||||||||||
Removes a GPS status listener.
| |||||||||||
Removes an NMEA listener.
| |||||||||||
Removes the proximity alert with the given PendingIntent.
| |||||||||||
Removes the mock location provider with the given name.
| |||||||||||
Removes all location updates for the specified pending intent.
| |||||||||||
Removes all location updates for the specified LocationListener.
| |||||||||||
Register for location updates using a Criteria and pending intent.
| |||||||||||
Register for location updates using a Criteria, and a callback
on the specified looper thread.
| |||||||||||
Register for location updates using the named provider, and a
pending intent.
| |||||||||||
Register for location updates using the named provider, and a callback on
the specified looper thread.
| |||||||||||
Register for location updates using the named provider, and a
pending intent.
| |||||||||||
Register for a single location update using the named provider and
a callback.
| |||||||||||
Register for a single location update using a Criteria and
a callback.
| |||||||||||
Register for a single location update using a named provider and pending intent.
| |||||||||||
Register for a single location update using a Criteria and pending intent.
| |||||||||||
Sends additional commands to a location provider.
| |||||||||||
Sets a mock enabled value for the given provider.
| |||||||||||
Sets a mock location for the given provider.
| |||||||||||
Sets mock status values for the given provider.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
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
ACCESS_FINE_LOCATION.
The extras Bundle for the GPS location provider can contain the following key/value pairs:
Key used for a Bundle extra holding a Location value when a location change is broadcast using a PendingIntent.
Key used for a Bundle extra holding an Boolean status value when a provider enabled/disabled event is broadcast using a PendingIntent.
Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false)..
Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent.
Broadcast intent action when LOCATION_MODE changes.
For use with the LOCATION_MODE API.
If you're interacting with isProviderEnabled(String), use
PROVIDERS_CHANGED_ACTION instead.
In the future, there may be mode changes that do not result in
PROVIDERS_CHANGED_ACTION broadcasts.
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.
A special location provider for receiving locations without actually initiating a location fix.
This provider can be used to passively receive location updates
when other applications or services request them without actually requesting
the locations yourself. This provider will return locations generated by other
providers. You can query the getProvider() method to determine
the origin of the location update. Requires the permission
ACCESS_FINE_LOCATION, although if the GPS is
not enabled this provider might only return coarse fixes.
Broadcast intent action when the configured location providers
change. For use with isProviderEnabled(String). If you're interacting with the
LOCATION_MODE API, use MODE_CHANGED_ACTION
instead.
Adds a GPS status listener.
| listener | GPS status listener object to register |
|---|
| SecurityException | if the ACCESS_FINE_LOCATION permission is not present |
|---|
Adds an NMEA listener.
| listener | a GpsStatus.NmeaListener object to register |
|---|
| SecurityException | if the ACCESS_FINE_LOCATION permission is not present |
|---|
Set 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.
Before API version 17, this method could be used with
ACCESS_FINE_LOCATION or
ACCESS_COARSE_LOCATION.
From API version 17 and onwards, this method requires
ACCESS_FINE_LOCATION permission.
| 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 |
| SecurityException | if ACCESS_FINE_LOCATION
permission is not present
|
|---|
Creates a mock location provider and adds it to the set of active providers.
| name | the provider name |
|---|
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled |
|---|---|
| IllegalArgumentException | if a provider with the given name already exists |
Removes any mock enabled value associated with the given provider.
| provider | the provider name |
|---|
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
Removes any mock location associated with the given provider.
| provider | the provider name |
|---|
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
Removes any mock status values associated with the given provider.
| provider | the provider name |
|---|
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
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 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:
Note that the requirement on monetary cost is not removed in this process.
| criteria | the criteria that need to be matched |
|---|---|
| enabledOnly | if true then only a provider that is currently enabled is returned |
Retrieves information about the current status of the GPS engine.
This should only be called from the onGpsStatusChanged(int)
callback to ensure that the data is copied atomically.
The caller may either pass in a GpsStatus object to set with the latest
status information, or pass null to create a new GpsStatus object.
| status | object containing GPS status details, or null. |
|---|
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.
| provider | the name of the provider |
|---|
| SecurityException | if no suitable permission is present |
|---|---|
| IllegalArgumentException | if provider is null or doesn't exist |
Returns the information associated with the location provider of the given name, or null if no provider exists by that name.
| name | the provider name |
|---|
| IllegalArgumentException | if name is null or does not exist |
|---|---|
| SecurityException | if the caller is not permitted to access the given provider. |
Returns a list of the names of location providers.
| enabledOnly | if true then only the providers which are currently enabled are returned. |
|---|
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.
| criteria | the criteria that the returned providers must match |
|---|---|
| enabledOnly | if true then only the providers which are currently enabled are returned. |
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
Callers should instead use
LOCATION_MODE
unless they depend on provider-specific APIs such as
requestLocationUpdates(String, long, float, LocationListener).
| provider | the name of the provider |
|---|
| IllegalArgumentException | if provider is null |
|---|---|
| SecurityException | if no suitable permission is present |
Removes a GPS status listener.
| listener | GPS status listener object to remove |
|---|
Removes an NMEA listener.
| listener | a GpsStatus.NmeaListener object to remove
|
|---|
Removes the proximity alert with the given PendingIntent.
Before API version 17, this method could be used with
ACCESS_FINE_LOCATION or
ACCESS_COARSE_LOCATION.
From API version 17 and onwards, this method requires
ACCESS_FINE_LOCATION permission.
| intent | the PendingIntent that no longer needs to be notified of proximity alerts |
|---|
| IllegalArgumentException | if intent is null |
|---|---|
| SecurityException | if ACCESS_FINE_LOCATION
permission is not present
|
Removes the mock location provider with the given name.
| provider | the provider name |
|---|
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
Removes all location updates for the specified pending intent.
Following this call, updates will no longer for this pending intent.
| intent | pending intent object that no longer needs location updates |
|---|
| IllegalArgumentException | if intent is null |
|---|
Removes all location updates for the specified LocationListener.
Following this call, updates will no longer occur for this listener.
| listener | listener object that no longer needs location updates |
|---|
| IllegalArgumentException | if listener is null |
|---|
Register for location updates using a Criteria and pending intent.
The requestLocationUpdates() and
requestSingleUpdate() register the current activity to be
updated periodically by the named provider, or by the provider matching
the specified Criteria, with location and status updates.
It may take a while to receive the first location update. If
an immediate location is required, applications may use the
getLastKnownLocation(String) method.
Location updates are received either by LocationListener
callbacks, or by broadcast intents to a supplied PendingIntent.
If the caller supplied a pending intent, then location updates
are sent with a key of KEY_LOCATION_CHANGED and a
Location value.
The location update interval can be controlled using the minTime parameter. The elapsed time between location updates will never be less than minTime, although it can be more depending on the Location Provider implementation and the update interval requested by other applications.
Choosing a sensible value for minTime is important to conserve
battery life. Each location update requires power from
GPS, WIFI, Cell and other radios. Select a minTime value as high as
possible while still providing a reasonable user experience.
If your application is not in the foreground and showing
location to the user then your application should avoid using an active
provider (such as NETWORK_PROVIDER or GPS_PROVIDER),
but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes)
or greater. If your application is in the foreground and showing
location to the user then it is appropriate to select a faster
update interval.
The minDistance parameter can also be used to control the frequency of location updates. If it is greater than 0 then the location provider will only send your application an update when the location has changed by at least minDistance meters, AND at least minTime milliseconds have passed. However it is more difficult for location providers to save power using the minDistance parameter, so minTime should be the primary tool to conserving battery life.
If your application wants to passively observe location
updates triggered by other applications, but not consume
any additional power otherwise, then use the PASSIVE_PROVIDER
This provider does not actively turn on or modify active location
providers, so you do not need to be as careful about minTime and
minDistance. However if your application performs heavy work
on a location update (such as network activity) then you should
select non-zero values for minTime and/or minDistance to rate-limit
your update frequency in the case another application enables a
location provider with extremely fast updates.
In case the provider is disabled by the user, updates will stop,
and a provider availability update will be sent.
As soon as the provider is enabled again,
location updates will immediately resume and a provider availability
update sent. Providers can also send status updates, at any time,
with extra's specific to the provider. If a callback was supplied
then status and availability updates are via
onProviderDisabled(String),
onProviderEnabled(String) or
onStatusChanged(String, int, Bundle). Alternately, if a
pending intent was supplied then status and availability updates
are broadcast intents with extra keys of
KEY_PROVIDER_ENABLED or KEY_STATUS_CHANGED.
If a LocationListener is used but with no Looper specified
then the calling thread must already
be a Looper thread such as the main thread of the
calling Activity. If a Looper is specified with a LocationListener
then callbacks are made on the supplied Looper thread.
Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. From Jellybean and onwards it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
| minTime | minimum time interval between location updates, in milliseconds |
|---|---|
| minDistance | minimum distance between location updates, in meters |
| criteria | contains parameters for the location manager to choose the appropriate provider and parameters to compute the location |
| intent | a PendingIntent to be sent for each location update |
| IllegalArgumentException | if criteria is null |
|---|---|
| IllegalArgumentException | if intent is null |
| SecurityException | if no suitable permission is present |
Register for location updates using a Criteria, and a callback on the specified looper thread.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| minTime | minimum time interval between location updates, in milliseconds |
|---|---|
| minDistance | minimum distance between location updates, in meters |
| criteria | contains parameters for the location manager to choose the appropriate provider and parameters to compute the location |
| listener | a 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, or null to make callbacks on the calling thread |
| IllegalArgumentException | if criteria is null |
|---|---|
| IllegalArgumentException | if listener is null |
| SecurityException | if no suitable permission is present |
Register for location updates using the named provider, and a pending intent.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| provider | the name of the provider with which to register |
|---|---|
| minTime | minimum time interval between location updates, in milliseconds |
| minDistance | minimum distance between location updates, in meters |
| listener | a LocationListener whose
onLocationChanged(Location) method will be called for
each location update |
| IllegalArgumentException | if provider is null or doesn't exist on this device |
|---|---|
| IllegalArgumentException | if listener is null |
| RuntimeException | if the calling thread has no Looper |
| SecurityException | if no suitable permission is present |
Register for location updates using the named provider, and a callback on the specified looper thread.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| provider | the name of the provider with which to register |
|---|---|
| minTime | minimum time interval between location updates, in milliseconds |
| minDistance | minimum distance between location updates, in meters |
| listener | a 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, or null to make callbacks on the calling thread |
| IllegalArgumentException | if provider is null or doesn't exist |
|---|---|
| IllegalArgumentException | if listener is null |
| SecurityException | if no suitable permission is present |
Register for location updates using the named provider, and a pending intent.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| provider | the name of the provider with which to register |
|---|---|
| minTime | minimum time interval between location updates, in milliseconds |
| minDistance | minimum distance between location updates, in meters |
| intent | a PendingIntent to be sent for each location update |
| IllegalArgumentException | if provider is null or doesn't exist on this device |
|---|---|
| IllegalArgumentException | if intent is null |
| SecurityException | if no suitable permission is present |
Register for a single location update using the named provider and a callback.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| provider | the name of the provider with which to register |
|---|---|
| listener | a LocationListener whose
onLocationChanged(Location) method will be called when
the location update is available |
| looper | a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread |
| IllegalArgumentException | if provider is null or doesn't exist |
|---|---|
| IllegalArgumentException | if listener is null |
| SecurityException | if no suitable permission is present |
Register for a single location update using a Criteria and a callback.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| criteria | contains parameters for the location manager to choose the appropriate provider and parameters to compute the location |
|---|---|
| listener | a LocationListener whose
onLocationChanged(Location) method will be called when
the location update is available |
| looper | a Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread |
| IllegalArgumentException | if criteria is null |
|---|---|
| IllegalArgumentException | if listener is null |
| SecurityException | if no suitable permission is present |
Register for a single location update using a named provider and pending intent.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| provider | the name of the provider with which to register |
|---|---|
| intent | a PendingIntent to be sent for the location update |
| IllegalArgumentException | if provider is null or doesn't exist |
|---|---|
| IllegalArgumentException | if intent is null |
| SecurityException | if no suitable permission is present |
Register for a single location update using a Criteria and pending intent.
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
| criteria | contains parameters for the location manager to choose the appropriate provider and parameters to compute the location |
|---|---|
| intent | a PendingIntent to be sent for the location update |
| IllegalArgumentException | if provider is null or doesn't exist |
|---|---|
| IllegalArgumentException | if intent is null |
| SecurityException | if no suitable permission is present |
Sends additional commands to a location provider. Can be used to support provider specific extensions to the Location Manager API
| provider | name of the location provider. |
|---|---|
| command | name of the command to send to the provider. |
| extras | optional arguments for the command (or null). The provider may optionally fill the extras Bundle with results from the command. |
Sets a mock enabled value for the given provider. This value will be used in place of any actual value from the provider.
| provider | the provider name |
|---|---|
| enabled | the mock enabled value |
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
Sets a mock location for the given provider.
This location will be used in place of any actual location from the provider.
The location object must have a minimum number of fields set to be
considered a valid LocationProvider Location, as per documentation
on Location class.
| provider | the provider name |
|---|---|
| loc | the mock location |
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |
| IllegalArgumentException | if the location is incomplete |
Sets mock status values for the given provider. These values will be used in place of any actual values from the provider.
| provider | the provider name |
|---|---|
| status | the mock status |
| extras | a Bundle containing mock extras |
| updateTime | the mock update time |
| SecurityException | if the ACCESS_MOCK_LOCATION permission is not present
or the Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled |
|---|---|
| IllegalArgumentException | if no provider with the given name exists |