public class LocationManager extends Object
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 android.Manifest.permission#ACCESS_COARSE_LOCATION
or
android.Manifest.permission#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.
Modifier and Type | Field and Description |
---|---|
static String |
EXTRA_GPS_ENABLED
The lookup key for a boolean that indicates whether GPS is enabled or
disabled.
|
static String |
FUSED_PROVIDER
Name of the Fused location provider.
|
static String |
GPS_ENABLED_CHANGE_ACTION
Broadcast intent action indicating that the GPS has either been
enabled or disabled.
|
static String |
GPS_FIX_CHANGE_ACTION
Broadcast intent action indicating that the GPS has either started or
stopped receiving GPS fixes.
|
static String |
GPS_PROVIDER
Name of the GPS location provider.
|
static String |
HIGH_POWER_REQUEST_CHANGE_ACTION
Broadcast intent action indicating that a high power location requests
has either started or stopped being active.
|
static String |
KEY_LOCATION_CHANGED
Key used for a Bundle extra holding a Location value
when a location change is broadcast using a PendingIntent.
|
static 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.
|
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 |
KEY_STATUS_CHANGED
Key used for a Bundle extra holding an Integer status value
when a status change is broadcast using a PendingIntent.
|
static String |
MODE_CHANGED_ACTION
Broadcast intent action when
Settings.Secure.LOCATION_MODE changes. |
static String |
NETWORK_PROVIDER
Name of the network location provider.
|
static String |
PASSIVE_PROVIDER
A special location provider for receiving locations without actually initiating
a location fix.
|
static String |
PROVIDERS_CHANGED_ACTION
Broadcast intent action when the configured location providers
change.
|
Constructor and Description |
---|
LocationManager(Context context,
ILocationManager service) |
Modifier and Type | Method and Description |
---|---|
void |
addGeofence(LocationRequest request,
Geofence fence,
PendingIntent intent)
Add a geofence with the specified LocationRequest quality of service.
|
boolean |
addGpsMeasurementListener(GpsMeasurementsEvent.Listener listener)
Deprecated.
Not supported anymore.
|
boolean |
addGpsNavigationMessageListener(GpsNavigationMessageEvent.Listener listener)
Deprecated.
Not supported anymore.
|
boolean |
addGpsStatusListener(GpsStatus.Listener listener)
Deprecated.
use
registerGnssStatusCallback(GnssStatus.Callback) instead. |
boolean |
addNmeaListener(GnssNmeaListener listener)
Adds an NMEA listener.
|
boolean |
addNmeaListener(GnssNmeaListener listener,
Handler handler)
Adds an NMEA listener.
|
boolean |
addNmeaListener(GpsStatus.NmeaListener listener)
Deprecated.
use
addNmeaListener(OnNmeaMessageListener) instead. |
boolean |
addNmeaListener(OnNmeaMessageListener listener)
Adds an NMEA listener.
|
boolean |
addNmeaListener(OnNmeaMessageListener listener,
Handler handler)
Adds an NMEA listener.
|
void |
addProximityAlert(double latitude,
double longitude,
float radius,
long expiration,
PendingIntent intent)
Set 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.
|
int |
getGnssYearOfHardware()
Returns the system information of the GPS hardware.
|
GpsStatus |
getGpsStatus(GpsStatus status)
Deprecated.
|
Location |
getLastKnownLocation(String provider)
Returns a Location indicating the data from the last known
location fix obtained from the given provider.
|
Location |
getLastLocation()
Get the last known location.
|
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(boolean enabledOnly)
Returns a list of the names of location providers.
|
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.
|
boolean |
isProviderEnabled(String provider)
Returns the current enabled/disabled status of the given provider.
|
boolean |
registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
Registers a GPS Measurement callback.
|
boolean |
registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback,
Handler handler)
Registers a GPS Measurement callback.
|
boolean |
registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
Registers a GNSS Navigation Message callback.
|
boolean |
registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback,
Handler handler)
Registers a GNSS Navigation Message callback.
|
boolean |
registerGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback)
Registers a GNSS Navigation Message callback.
|
boolean |
registerGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback,
Handler handler)
Registers a GNSS Navigation Message callback.
|
boolean |
registerGnssStatusCallback(GnssStatus.Callback callback)
Registers a GNSS status listener.
|
boolean |
registerGnssStatusCallback(GnssStatus.Callback callback,
Handler handler)
Registers a GNSS status listener.
|
boolean |
registerGnssStatusCallback(GnssStatusCallback callback)
Registers a GNSS status listener.
|
boolean |
registerGnssStatusCallback(GnssStatusCallback callback,
Handler handler)
Registers a GNSS status listener.
|
void |
removeAllGeofences(PendingIntent intent)
Remove all geofences registered to the specified pending intent.
|
void |
removeGeofence(Geofence fence,
PendingIntent intent)
Remove a single geofence.
|
void |
removeGpsMeasurementListener(GpsMeasurementsEvent.Listener listener)
Deprecated.
|
void |
removeGpsNavigationMessageListener(GpsNavigationMessageEvent.Listener listener)
Deprecated.
use
#unregisterGnssNavigationMessageCallback(GnssMeasurements.Callback)
instead |
void |
removeGpsStatusListener(GpsStatus.Listener listener)
Deprecated.
use
unregisterGnssStatusCallback(GnssStatus.Callback) instead. |
void |
removeNmeaListener(GnssNmeaListener listener)
Removes an NMEA listener.
|
void |
removeNmeaListener(GpsStatus.NmeaListener listener)
Deprecated.
use
removeNmeaListener(OnNmeaMessageListener) instead. |
void |
removeNmeaListener(OnNmeaMessageListener listener)
Removes an NMEA listener.
|
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 all location updates for the specified LocationListener.
|
void |
removeUpdates(PendingIntent intent)
Removes all location updates for the specified pending intent.
|
void |
requestLocationUpdates(LocationRequest request,
LocationListener listener,
Looper looper)
Register for fused location updates using a LocationRequest and callback.
|
void |
requestLocationUpdates(LocationRequest request,
PendingIntent intent)
Register for fused location updates using a LocationRequest and a pending intent.
|
void |
requestLocationUpdates(long minTime,
float minDistance,
Criteria criteria,
LocationListener listener,
Looper looper)
Register for location updates using a Criteria, and a callback
on the specified looper thread.
|
void |
requestLocationUpdates(long minTime,
float minDistance,
Criteria criteria,
PendingIntent intent)
Register for location updates using a Criteria and pending intent.
|
void |
requestLocationUpdates(String provider,
long minTime,
float minDistance,
LocationListener listener)
Register for location updates using the named provider, and a
pending intent.
|
void |
requestLocationUpdates(String provider,
long minTime,
float minDistance,
LocationListener listener,
Looper looper)
Register for location updates using the named provider, and a callback on
the specified looper thread.
|
void |
requestLocationUpdates(String provider,
long minTime,
float minDistance,
PendingIntent intent)
Register for location updates using the named provider, and a
pending intent.
|
void |
requestSingleUpdate(Criteria criteria,
LocationListener listener,
Looper looper)
Register for a single location update using a Criteria and
a callback.
|
void |
requestSingleUpdate(Criteria criteria,
PendingIntent intent)
Register for a single location update using a Criteria and pending intent.
|
void |
requestSingleUpdate(String provider,
LocationListener listener,
Looper looper)
Register for a single location update using the named provider and
a callback.
|
void |
requestSingleUpdate(String provider,
PendingIntent intent)
Register for a single location update using a named provider and pending intent.
|
boolean |
sendExtraCommand(String provider,
String command,
Bundle extras)
Sends additional commands to a location provider.
|
boolean |
sendNiResponse(int notifId,
int userResponse)
Used by NetInitiatedActivity to report user response
for network initiated GPS fix requests.
|
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.
|
void |
unregisterGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
Unregisters a GPS Measurement callback.
|
void |
unregisterGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
Unregisters a GNSS Navigation Message callback.
|
void |
unregisterGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback)
Unregisters a GNSS Navigation Message callback.
|
void |
unregisterGnssStatusCallback(GnssStatus.Callback callback)
Removes a GNSS status listener.
|
void |
unregisterGnssStatusCallback(GnssStatusCallback callback)
Removes a GNSS status listener.
|
public static final String NETWORK_PROVIDER
This provider determines location based on availability of cell tower and WiFi access points. Results are retrieved by means of a network lookup.
public static final String GPS_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.Manifest.permission#ACCESS_FINE_LOCATION
.
The extras Bundle for the GPS location provider can contain the following key/value pairs:
public static final String PASSIVE_PROVIDER
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 Location.getProvider()
method to determine
the origin of the location update. Requires the permission
android.Manifest.permission#ACCESS_FINE_LOCATION
, although if the GPS is
not enabled this provider might only return coarse fixes.
public static final String FUSED_PROVIDER
This provider combines inputs for all possible location sources
to provide the best possible Location fix. It is implicitly
used for all API's that involve the LocationRequest
object.
public static final String KEY_PROXIMITY_ENTERING
public static final String KEY_STATUS_CHANGED
public static final String KEY_PROVIDER_ENABLED
public static final String KEY_LOCATION_CHANGED
public static final String GPS_ENABLED_CHANGE_ACTION
true
means enabled.EXTRA_GPS_ENABLED
,
Constant Field Valuespublic static final String PROVIDERS_CHANGED_ACTION
isProviderEnabled(String)
. If you're interacting with the
Settings.Secure.LOCATION_MODE
API, use MODE_CHANGED_ACTION
instead.public static final String MODE_CHANGED_ACTION
Settings.Secure.LOCATION_MODE
changes.
For use with the Settings.Secure.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.public static final String GPS_FIX_CHANGE_ACTION
true
means that the GPS is actively receiving fixes.EXTRA_GPS_ENABLED
,
Constant Field Valuespublic static final String EXTRA_GPS_ENABLED
true
means GPS is enabled. Retrieve it with
Intent.getBooleanExtra(String,boolean)
.public static final String HIGH_POWER_REQUEST_CHANGE_ACTION
OP_MONITOR_HIGH_POWER_LOCATION
.public LocationManager(Context context, ILocationManager service)
public List<String> getAllProviders()
All providers are returned, including ones that are not permitted to be accessed by the calling activity or are currently disabled.
public List<String> getProviders(boolean enabledOnly)
enabledOnly
- if true then only the providers which are currently
enabled are returned.public LocationProvider getProvider(String name)
name
- the provider nameIllegalArgumentException
- if name is null or does not existSecurityException
- if the caller is not permitted to access the
given provider.public List<String> getProviders(Criteria criteria, boolean enabledOnly)
criteria
- the criteria that the returned providers must matchenabledOnly
- if true then only the providers which are currently
enabled are returned.public String getBestProvider(Criteria criteria, boolean enabledOnly)
Note that the requirement on monetary cost is not removed in this process.
criteria
- the criteria that need to be matchedenabledOnly
- if true then only a provider that is currently enabled is returnedpublic void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener)
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
provider
- the name of the provider with which to registerminTime
- minimum time interval between location updates, in millisecondsminDistance
- minimum distance between location updates, in meterslistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called for
each location updateIllegalArgumentException
- if provider is null or doesn't exist
on this deviceIllegalArgumentException
- if listener is nullRuntimeException
- if the calling thread has no LooperSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper)
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
provider
- the name of the provider with which to registerminTime
- minimum time interval between location updates, in millisecondsminDistance
- minimum distance between location updates, in meterslistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called for
each location updatelooper
- a Looper object whose message queue will be used to
implement the callback mechanism, or null to make callbacks on the calling
threadIllegalArgumentException
- if provider is null or doesn't existIllegalArgumentException
- if listener is nullSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(long minTime, float minDistance, Criteria criteria, LocationListener listener, Looper looper)
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
minTime
- minimum time interval between location updates, in millisecondsminDistance
- minimum distance between location updates, in meterscriteria
- contains parameters for the location manager to choose the
appropriate provider and parameters to compute the locationlistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called for
each location updatelooper
- a Looper object whose message queue will be used to
implement the callback mechanism, or null to make callbacks on the calling
threadIllegalArgumentException
- if criteria is nullIllegalArgumentException
- if listener is nullSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(String provider, long minTime, float minDistance, PendingIntent 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 registerminTime
- minimum time interval between location updates, in millisecondsminDistance
- minimum distance between location updates, in metersintent
- a PendingIntent
to be sent for each location updateIllegalArgumentException
- if provider is null or doesn't exist
on this deviceIllegalArgumentException
- if intent is nullSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(long minTime, float minDistance, Criteria criteria, PendingIntent 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
LocationListener.onProviderDisabled(java.lang.String)
,
LocationListener.onProviderEnabled(java.lang.String)
or
LocationListener.onStatusChanged(java.lang.String, int, android.os.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 millisecondsminDistance
- minimum distance between location updates, in meterscriteria
- contains parameters for the location manager to choose the
appropriate provider and parameters to compute the locationintent
- a PendingIntent
to be sent for each location updateIllegalArgumentException
- if criteria is nullIllegalArgumentException
- if intent is nullSecurityException
- if no suitable permission is presentpublic void requestSingleUpdate(String provider, LocationListener listener, Looper looper)
See requestLocationUpdates(long, float, Criteria, PendingIntent)
for more detail on how to use this method.
provider
- the name of the provider with which to registerlistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called when
the location update is availablelooper
- a Looper object whose message queue will be used to
implement the callback mechanism, or null to make callbacks on the calling
threadIllegalArgumentException
- if provider is null or doesn't existIllegalArgumentException
- if listener is nullSecurityException
- if no suitable permission is presentpublic void requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper)
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 locationlistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called when
the location update is availablelooper
- a Looper object whose message queue will be used to
implement the callback mechanism, or null to make callbacks on the calling
threadIllegalArgumentException
- if criteria is nullIllegalArgumentException
- if listener is nullSecurityException
- if no suitable permission is presentpublic void requestSingleUpdate(String provider, PendingIntent 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 registerintent
- a PendingIntent
to be sent for the location updateIllegalArgumentException
- if provider is null or doesn't existIllegalArgumentException
- if intent is nullSecurityException
- if no suitable permission is presentpublic void requestSingleUpdate(Criteria criteria, PendingIntent 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 locationintent
- a PendingIntent
to be sent for the location updateIllegalArgumentException
- if provider is null or doesn't existIllegalArgumentException
- if intent is nullSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(LocationRequest request, LocationListener listener, Looper looper)
Upon a location update, the system delivers the new Location
to the
provided LocationListener
, by calling its LocationListener.onLocationChanged(android.location.Location)
method.
The system will automatically select and enable the best providers
to compute a location for your application. It may use only passive
locations, or just a single location source, or it may fuse together
multiple location sources in order to produce the best possible
result, depending on the quality of service requested in the
LocationRequest
.
LocationRequest can be null, in which case the system will choose default, low power parameters for location updates. You will occasionally receive location updates as available, without a major power impact on the system. If your application just needs an occasional location update without any strict demands, then pass a null LocationRequest.
Only one LocationRequest can be registered for each unique callback or pending intent. So a subsequent request with the same callback or pending intent will over-write the previous LocationRequest.
If a pending intent is supplied then location updates
are sent with a key of KEY_LOCATION_CHANGED
and a
Location
value. If a callback is supplied
then location updates are made using the
LocationListener.onLocationChanged(android.location.Location)
callback, on the specified
Looper thread. If a LocationListener
is used
but with a null Looper then the calling thread must already
be a Looper
thread (such as the main thread) and
callbacks will occur on this thread.
Provider status updates and availability updates are deprecated
because the system is performing provider fusion on the applications
behalf. So LocationListener.onProviderDisabled(java.lang.String)
,
LocationListener.onProviderEnabled(java.lang.String)
, LocationListener.onStatusChanged(java.lang.String, int, android.os.Bundle)
will not be called, and intents with extra keys of
KEY_PROVIDER_ENABLED
or KEY_STATUS_CHANGED
will not
be received.
To unregister for Location updates, use: removeUpdates(LocationListener)
.
request
- quality of service required, null for default low powerlistener
- a LocationListener
whose
LocationListener.onLocationChanged(android.location.Location)
method will be called when
the location update is availablelooper
- a Looper object whose message queue will be used to
implement the callback mechanism, or null to make callbacks on the calling
threadIllegalArgumentException
- if listener is nullSecurityException
- if no suitable permission is presentpublic void requestLocationUpdates(LocationRequest request, PendingIntent intent)
Upon a location update, the system delivers the new Location
with your provided
PendingIntent
, as the value for KEY_LOCATION_CHANGED
in the intent's extras.
To unregister for Location updates, use: removeUpdates(PendingIntent)
.
See requestLocationUpdates(LocationRequest, LocationListener, Looper)
for more detail.
request
- quality of service required, null for default low powerintent
- a PendingIntent
to be sent for the location updateIllegalArgumentException
- if intent is nullSecurityException
- if no suitable permission is presentpublic void removeUpdates(LocationListener listener)
Following this call, updates will no longer occur for this listener.
listener
- listener object that no longer needs location updatesIllegalArgumentException
- if listener is nullpublic void removeUpdates(PendingIntent intent)
Following this call, updates will no longer for this pending intent.
intent
- pending intent object that no longer needs location updatesIllegalArgumentException
- if intent is nullpublic void addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent)
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
android.Manifest.permission#ACCESS_FINE_LOCATION
or
android.Manifest.permission#ACCESS_COARSE_LOCATION
.
From API version 17 and onwards, this method requires
android.Manifest.permission#ACCESS_FINE_LOCATION
permission.
latitude
- the latitude of the central point of the
alert regionlongitude
- the longitude of the central point of the
alert regionradius
- the radius of the central point of the
alert region, in metersexpiration
- time for this proximity alert, in milliseconds,
or -1 to indicate no expirationintent
- a PendingIntent that will be used to generate an Intent to
fire when entry to or exit from the alert region is detectedSecurityException
- if android.Manifest.permission#ACCESS_FINE_LOCATION
permission is not presentpublic void addGeofence(LocationRequest request, Geofence fence, PendingIntent intent)
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.
The geofence engine fuses results from all location providers to
provide the best balance between accuracy and power. Applications
can choose the quality of service required using the
LocationRequest
object. If it is null then a default,
low power geo-fencing implementation is used. It is possible to cross
a geo-fence without notification, but the system will do its best
to detect, using LocationRequest
as a hint to trade-off
accuracy and power.
The power required by the geofence engine can depend on many factors,
such as quality and interval requested in LocationRequest
,
distance to nearest geofence and current device velocity.
request
- quality of service required, null for default low powerfence
- a geographical description of the geofence areaintent
- pending intent to receive geofence updatesIllegalArgumentException
- if fence is nullIllegalArgumentException
- if intent is nullSecurityException
- if android.Manifest.permission#ACCESS_FINE_LOCATION
permission is not presentpublic void removeProximityAlert(PendingIntent intent)
Before API version 17, this method could be used with
android.Manifest.permission#ACCESS_FINE_LOCATION
or
android.Manifest.permission#ACCESS_COARSE_LOCATION
.
From API version 17 and onwards, this method requires
android.Manifest.permission#ACCESS_FINE_LOCATION
permission.
intent
- the PendingIntent that no longer needs to be notified of
proximity alertsIllegalArgumentException
- if intent is nullSecurityException
- if android.Manifest.permission#ACCESS_FINE_LOCATION
permission is not presentpublic void removeGeofence(Geofence fence, PendingIntent intent)
This removes only the specified geofence associated with the specified pending intent. All other geofences remain unchanged.
fence
- a geofence previously passed to addGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent)
intent
- a pending intent previously passed to addGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent)
IllegalArgumentException
- if fence is nullIllegalArgumentException
- if intent is nullSecurityException
- if android.Manifest.permission#ACCESS_FINE_LOCATION
permission is not presentpublic void removeAllGeofences(PendingIntent intent)
intent
- a pending intent previously passed to addGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent)
IllegalArgumentException
- if intent is nullSecurityException
- if android.Manifest.permission#ACCESS_FINE_LOCATION
permission is not presentpublic boolean isProviderEnabled(String provider)
If the user has enabled this provider in the Settings menu, true is returned otherwise false is returned
Callers should instead use
Settings.Secure.LOCATION_MODE
unless they depend on provider-specific APIs such as
requestLocationUpdates(String, long, float, LocationListener)
.
Before API version Build.VERSION_CODES.LOLLIPOP
, this
method would throw SecurityException
if the location permissions
were not sufficient to use the specified provider.
provider
- the name of the providerIllegalArgumentException
- if provider is nullpublic Location getLastLocation()
This location could be very old so use
Location.getElapsedRealtimeNanos()
to calculate its age. It can
also return null if no previous location is available.
Always returns immediately.
SecurityException
- if no suitable permission is presentpublic Location getLastKnownLocation(String 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 providerSecurityException
- if no suitable permission is presentIllegalArgumentException
- if provider is null or doesn't existpublic void addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)
name
- the provider nameSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if a provider with the given name already existspublic void removeTestProvider(String provider)
provider
- the provider nameSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existspublic void setTestProviderLocation(String provider, Location loc)
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 nameloc
- the mock locationSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existsIllegalArgumentException
- if the location is incompletepublic void clearTestProviderLocation(String provider)
provider
- the provider nameSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existspublic void setTestProviderEnabled(String provider, boolean enabled)
provider
- the provider nameenabled
- the mock enabled valueSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existspublic void clearTestProviderEnabled(String provider)
provider
- the provider nameSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existspublic void setTestProviderStatus(String provider, int status, Bundle extras, long updateTime)
provider
- the provider namestatus
- the mock statusextras
- a Bundle containing mock extrasupdateTime
- the mock update timeSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name existspublic void clearTestProviderStatus(String provider)
provider
- the provider nameSecurityException
- if mock location app op
is not set to allowed
for your app.IllegalArgumentException
- if no provider with the given name exists@Deprecated public boolean addGpsStatusListener(GpsStatus.Listener listener)
registerGnssStatusCallback(GnssStatus.Callback)
instead.listener
- GPS status listener object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not present@Deprecated public void removeGpsStatusListener(GpsStatus.Listener listener)
unregisterGnssStatusCallback(GnssStatus.Callback)
instead.listener
- GPS status listener object to removepublic boolean registerGnssStatusCallback(GnssStatusCallback callback)
callback
- GNSS status listener object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic boolean registerGnssStatusCallback(GnssStatusCallback callback, Handler handler)
callback
- GNSS status listener object to registerhandler
- the handler that the callback runs on.SecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic void unregisterGnssStatusCallback(GnssStatusCallback callback)
callback
- GNSS status listener object to removepublic boolean registerGnssStatusCallback(GnssStatus.Callback callback)
callback
- GNSS status listener object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic boolean registerGnssStatusCallback(GnssStatus.Callback callback, Handler handler)
callback
- GNSS status listener object to registerhandler
- the handler that the callback runs on.SecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic void unregisterGnssStatusCallback(GnssStatus.Callback callback)
callback
- GNSS status listener object to remove@Deprecated public boolean addNmeaListener(GpsStatus.NmeaListener listener)
addNmeaListener(OnNmeaMessageListener)
instead.listener
- a GpsStatus.NmeaListener
object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not present@Deprecated public void removeNmeaListener(GpsStatus.NmeaListener listener)
removeNmeaListener(OnNmeaMessageListener)
instead.listener
- a GpsStatus.NmeaListener
object to removepublic boolean addNmeaListener(GnssNmeaListener listener)
listener
- a GnssNmeaListener
object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic boolean addNmeaListener(GnssNmeaListener listener, Handler handler)
listener
- a GnssNmeaListener
object to registerhandler
- the handler that the listener runs on.SecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic void removeNmeaListener(GnssNmeaListener listener)
listener
- a GnssNmeaListener
object to removepublic boolean addNmeaListener(OnNmeaMessageListener listener)
listener
- a OnNmeaMessageListener
object to registerSecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic boolean addNmeaListener(OnNmeaMessageListener listener, Handler handler)
listener
- a OnNmeaMessageListener
object to registerhandler
- the handler that the listener runs on.SecurityException
- if the ACCESS_FINE_LOCATION permission is not presentpublic void removeNmeaListener(OnNmeaMessageListener listener)
listener
- a OnNmeaMessageListener
object to remove@Deprecated public boolean addGpsMeasurementListener(GpsMeasurementsEvent.Listener listener)
registerGnssMeasurementsCallback(android.location.GnssMeasurementsEvent.Callback)
instead.public boolean registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
callback
- a GnssMeasurementsEvent.Callback
object to register.true
if the callback was added successfully, false
otherwise.public boolean registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback, Handler handler)
callback
- a GnssMeasurementsEvent.Callback
object to register.handler
- the handler that the callback runs on.true
if the callback was added successfully, false
otherwise.@Deprecated public void removeGpsMeasurementListener(GpsMeasurementsEvent.Listener listener)
unregisterGnssMeasurementsCallback(GnssMeasurementsEvent.Callback)
instead.unregisterGnssMeasurementsCallback(android.location.GnssMeasurementsEvent.Callback)
instead.public void unregisterGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
callback
- a GnssMeasurementsEvent.Callback
object to remove.@Deprecated public boolean addGpsNavigationMessageListener(GpsNavigationMessageEvent.Listener listener)
registerGnssNavigationMessageCallback(android.location.GnssNavigationMessageEvent.Callback)
instead.@Deprecated public void removeGpsNavigationMessageListener(GpsNavigationMessageEvent.Listener listener)
#unregisterGnssNavigationMessageCallback(GnssMeasurements.Callback)
insteadunregisterGnssNavigationMessageCallback(android.location.GnssNavigationMessageEvent.Callback)
instead.public boolean registerGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback)
callback
- a GnssNavigationMessageEvent.Callback
object to register.true
if the callback was added successfully, false
otherwise.public boolean registerGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback, Handler handler)
callback
- a GnssNavigationMessageEvent.Callback
object to register.handler
- the handler that the callback runs on.true
if the callback was added successfully, false
otherwise.public void unregisterGnssNavigationMessageCallback(GnssNavigationMessageEvent.Callback callback)
callback
- a GnssNavigationMessageEvent.Callback
object to remove.public boolean registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
callback
- a GnssNavigationMessage.Callback
object to register.true
if the callback was added successfully, false
otherwise.public boolean registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback, Handler handler)
callback
- a GnssNavigationMessage.Callback
object to register.handler
- the handler that the callback runs on.true
if the callback was added successfully, false
otherwise.public void unregisterGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
callback
- a GnssNavigationMessage.Callback
object to remove.@Deprecated public GpsStatus getGpsStatus(GpsStatus status)
GpsStatus.Listener.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.public int getGnssYearOfHardware()
public boolean sendExtraCommand(String provider, String command, Bundle extras)
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.public boolean sendNiResponse(int notifId, int userResponse)