# Print output for @column tags ?>
public
class
LocationManager
extends Object
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 be notified when the device enters the proximity of a given geographical location.
Unless noted, all Location API methods require the Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
permissions. If your application only has the
coarse permission then it will not have access to fine location providers. Other providers will
still return location results, but the exact location will be obfuscated to a coarse level of
accuracy.
Requires the PackageManager#FEATURE_LOCATION
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Constants | |
---|---|
String |
EXTRA_LOCATION_ENABLED
Intent extra included with |
String |
EXTRA_PROVIDER_ENABLED
Intent extra included with |
String |
EXTRA_PROVIDER_NAME
Intent extra included with |
String |
GPS_PROVIDER
Name of the GNSS location provider. |
String |
KEY_LOCATION_CHANGED
Key used for an extra holding a |
String |
KEY_PROVIDER_ENABLED
Key used for an extra holding a boolean enabled/disabled 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
This constant is deprecated. Status changes are deprecated and no longer broadcast from Android Q onwards. |
String |
MODE_CHANGED_ACTION
Broadcast intent action when the device location enabled state 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 set of enabled location providers changes. |
Public methods | |
---|---|
boolean
|
addGpsStatusListener(GpsStatus.Listener listener)
This method is deprecated.
use |
boolean
|
addNmeaListener(OnNmeaMessageListener listener, Handler handler)
Adds an NMEA listener. |
boolean
|
addNmeaListener(OnNmeaMessageListener listener)
This method is deprecated.
Use |
boolean
|
addNmeaListener(GpsStatus.NmeaListener listener)
This method is deprecated.
Use |
boolean
|
addNmeaListener(Executor executor, OnNmeaMessageListener listener)
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 provider, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)
Creates a test location provider and adds it to the set of active providers. |
void
|
clearTestProviderEnabled(String provider)
This method is deprecated.
Use |
void
|
clearTestProviderLocation(String provider)
This method is deprecated. This method has always been a no-op, and may be removed in the future. |
void
|
clearTestProviderStatus(String provider)
This method is deprecated. This method has no effect. |
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. |
void
|
getCurrentLocation(String provider, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer)
Asynchronously returns a single current location fix. |
GnssCapabilities
|
getGnssCapabilities()
Returns the supported capabilities of the GNSS chipset. |
String
|
getGnssHardwareModelName()
Returns the Model Name (including Vendor and Hardware/Software Version) of the GNSS hardware driver. |
int
|
getGnssYearOfHardware()
Returns the model year of the GNSS hardware and software build. |
GpsStatus
|
getGpsStatus(GpsStatus status)
This method is deprecated.
GpsStatus APIs are deprecated, use |
Location
|
getLastKnownLocation(String provider)
Gets the last known location from the given provider, or null if there is no last known location. |
LocationProvider
|
getProvider(String provider)
Returns the information about the location provider with 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 providers that satisfy the given criteria. |
boolean
|
isLocationEnabled()
Returns the current enabled/disabled state of location. |
boolean
|
isProviderEnabled(String provider)
Returns the current enabled/disabled status of the given provider. |
boolean
|
registerAntennaInfoListener(Executor executor, GnssAntennaInfo.Listener listener)
Registers a Gnss Antenna Info listener. |
boolean
|
registerGnssMeasurementsCallback(Executor executor, GnssMeasurementsEvent.Callback callback)
Registers a GPS Measurement callback. |
boolean
|
registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
This method is deprecated.
Use |
boolean
|
registerGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback, Handler handler)
Registers a GPS Measurement callback. |
boolean
|
registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback, Handler handler)
Registers a GNSS Navigation Message callback. |
boolean
|
registerGnssNavigationMessageCallback(Executor executor, GnssNavigationMessage.Callback callback)
Registers a GNSS Navigation Message callback. |
boolean
|
registerGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
This method is deprecated.
Use |
boolean
|
registerGnssStatusCallback(GnssStatus.Callback callback)
This method is deprecated.
Use |
boolean
|
registerGnssStatusCallback(GnssStatus.Callback callback, Handler handler)
Registers a GNSS status callback. |
boolean
|
registerGnssStatusCallback(Executor executor, GnssStatus.Callback callback)
Registers a GNSS status callback. |
void
|
removeGpsStatusListener(GpsStatus.Listener listener)
This method is deprecated.
use |
void
|
removeNmeaListener(OnNmeaMessageListener listener)
Removes an NMEA listener. |
void
|
removeNmeaListener(GpsStatus.NmeaListener listener)
This method is deprecated.
Use |
void
|
removeProximityAlert(PendingIntent intent)
Removes the proximity alert with the given PendingIntent. |
void
|
removeTestProvider(String provider)
Removes the test location provider with the given name or does nothing if no such test location provider exists. |
void
|
removeUpdates(LocationListener listener)
Removes location updates for the specified |
void
|
removeUpdates(PendingIntent pendingIntent)
Removes location updates for the specified |
void
|
requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, LocationListener listener)
Register for location updates from the given provider with the given arguments. |
void
|
requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, LocationListener listener, Looper looper)
Register for location updates using a provider selected through the given Criteria, and a
callback on the specified |
void
|
requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, LocationListener listener, Looper looper)
Register for location updates using the named provider, and a callback on
the specified |
void
|
requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, Executor executor, LocationListener listener)
Register for location updates using the named provider, and a callback on
the specified |
void
|
requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, PendingIntent pendingIntent)
Register for location updates using a provider selected through the given Criteria, and
callbacks delivered via the provided |
void
|
requestLocationUpdates(long minTimeMs, float minDistanceM, Criteria criteria, Executor executor, LocationListener listener)
Register for location updates using a provider selected through the given Criteria, and a
callback on the specified |
void
|
requestLocationUpdates(String provider, long minTimeMs, float minDistanceM, PendingIntent pendingIntent)
Register for location updates using the named provider, and callbacks delivered via the
provided |
void
|
requestSingleUpdate(String provider, PendingIntent pendingIntent)
This method is deprecated.
Use |
void
|
requestSingleUpdate(Criteria criteria, PendingIntent pendingIntent)
This method is deprecated.
Use |
void
|
requestSingleUpdate(String provider, LocationListener listener, Looper looper)
This method is deprecated.
Use |
void
|
requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper)
This method is deprecated.
Use |
boolean
|
sendExtraCommand(String provider, String command, Bundle extras)
Sends additional commands to a location provider. |
void
|
setTestProviderEnabled(String provider, boolean enabled)
Sets the given test provider to be enabled or disabled. |
void
|
setTestProviderLocation(String provider, Location location)
Sets a new location for the given test provider. |
void
|
setTestProviderStatus(String provider, int status, Bundle extras, long updateTime)
This method is deprecated. This method has no effect. |
void
|
unregisterAntennaInfoListener(GnssAntennaInfo.Listener listener)
Unregisters a GNSS Antenna Info listener. |
void
|
unregisterGnssMeasurementsCallback(GnssMeasurementsEvent.Callback callback)
Unregisters a GPS Measurement callback. |
void
|
unregisterGnssNavigationMessageCallback(GnssNavigationMessage.Callback callback)
Unregisters a GNSS Navigation Message callback. |
void
|
unregisterGnssStatusCallback(GnssStatus.Callback callback)
Removes a GNSS status callback. |
Inherited methods | |
---|---|
public static final String EXTRA_LOCATION_ENABLED
Intent extra included with MODE_CHANGED_ACTION
broadcasts, containing the boolean
enabled state of location.
See also:
Constant Value: "android.location.extra.LOCATION_ENABLED"
public static final String EXTRA_PROVIDER_ENABLED
Intent extra included with PROVIDERS_CHANGED_ACTION
broadcasts, containing the
boolean enabled state of the location provider that has changed.
Constant Value: "android.location.extra.PROVIDER_ENABLED"
public static final String EXTRA_PROVIDER_NAME
Intent extra included with PROVIDERS_CHANGED_ACTION
broadcasts, containing the name
of the location provider that has changed.
Constant Value: "android.location.extra.PROVIDER_NAME"
public static final String GPS_PROVIDER
Name of the GNSS location provider.
This provider determines location using GNSS satellites. Depending on conditions, this
provider may take a while to return a location fix. Requires the
Manifest.permission.ACCESS_FINE_LOCATION
permission.
The extras Bundle for the GPS location provider can contain the following key/value pairs:
Constant Value: "gps"
public static final String KEY_LOCATION_CHANGED
Key used for an extra holding a Location
value when a location change is broadcast
using a PendingIntent.
Constant Value: "location"
public static final String KEY_PROVIDER_ENABLED
Key used for an extra holding a boolean enabled/disabled status value when a provider enabled/disabled event is broadcast using a PendingIntent.
Constant Value: "providerEnabled"
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 KEY_STATUS_CHANGED
This constant is deprecated.
Status changes are deprecated and no longer broadcast from Android Q onwards.
This key is no longer in use.
Key used for a Bundle extra holding an Integer status value when a status change is broadcast using a PendingIntent.
Constant Value: "status"
public static final String MODE_CHANGED_ACTION
Broadcast intent action when the device location enabled state changes. From Android R and
above, will include a boolean intent extra, EXTRA_LOCATION_ENABLED
, with the enabled
state of location.
Constant Value: "android.location.MODE_CHANGED"
public static final String NETWORK_PROVIDER
Name of the network location provider.
This provider determines location based on nearby of cell tower and WiFi access points. Results are retrieved by means of a network lookup.
Constant Value: "network"
public static final String PASSIVE_PROVIDER
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
only return locations generated by other providers. You can query the
Location#getProvider()
method to determine the actual provider that supplied the
location update. Requires the Manifest.permission.ACCESS_FINE_LOCATION
permission, although there is no guarantee of fine locations.
Constant Value: "passive"
public static final String PROVIDERS_CHANGED_ACTION
Broadcast intent action when the set of enabled location providers changes. To check the
status of a provider, use isProviderEnabled(java.lang.String)
. From Android Q and above, will
include a string intent extra, EXTRA_PROVIDER_NAME
, with the name of the provider
whose state has changed. From Android R and above, will include a boolean intent extra,
EXTRA_PROVIDER_ENABLED
, with the enabled state of the provider.
Constant Value: "android.location.PROVIDERS_CHANGED"
public boolean addGpsStatusListener (GpsStatus.Listener listener)
This method is deprecated.
use registerGnssStatusCallback(android.location.GnssStatus.Callback)
instead. No longer
supported in apps targeting S and above.
Adds a GPS status listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
listener |
GpsStatus.Listener : GPS status listener object to register |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean addNmeaListener (OnNmeaMessageListener listener, Handler handler)
Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
listener |
OnNmeaMessageListener : a OnNmeaMessageListener object to register
This value cannot be null . |
handler |
Handler : a handler with the looper that the listener runs on.
This value may be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
IllegalArgumentException |
if listener is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean addNmeaListener (OnNmeaMessageListener listener)
This method is deprecated.
Use addNmeaListener(android.location.OnNmeaMessageListener, android.os.Handler)
or addNmeaListener(java.util.concurrent.Executor, android.location.OnNmeaMessageListener)
instead.
Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
listener |
OnNmeaMessageListener : a OnNmeaMessageListener object to register
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean addNmeaListener (GpsStatus.NmeaListener listener)
This method is deprecated.
Use addNmeaListener(GpsStatus.NmeaListener)
instead.
No-op method to keep backward-compatibility.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
listener |
GpsStatus.NmeaListener : This value cannot be null . |
Returns | |
---|---|
boolean |
public boolean addNmeaListener (Executor executor, OnNmeaMessageListener listener)
Adds an NMEA listener.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
executor |
Executor : the Executor that the listener runs on.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
listener |
OnNmeaMessageListener : a OnNmeaMessageListener object to register
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public 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.
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
Manifest.permission.ACCESS_FINE_LOCATION
or
Manifest.permission.ACCESS_COARSE_LOCATION
.
From API version 17 and onwards, this method requires
Manifest.permission.ACCESS_FINE_LOCATION
permission.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
latitude |
double : the latitude of the central point of the
alert region |
longitude |
double : the longitude of the central point of the
alert region |
radius |
float : the radius of the central point of the
alert region, in meters |
expiration |
long : time for this proximity alert, in milliseconds,
or -1 to indicate no expiration |
intent |
PendingIntent : a PendingIntent that will be used to generate an Intent to
fire when entry to or exit from the alert region is detected
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if Manifest.permission.ACCESS_FINE_LOCATION
permission is not present |
public void addTestProvider (String provider, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy)
Creates a test location provider and adds it to the set of active providers. This provider will replace any provider with the same name that exists prior to this call.
Parameters | |
---|---|
provider |
String : the provider name
This value cannot be null . |
requiresNetwork |
boolean |
requiresSatellite |
boolean |
requiresCell |
boolean |
hasMonetaryCost |
boolean |
supportsAltitude |
boolean |
supportsSpeed |
boolean |
supportsBearing |
boolean |
powerRequirement |
int |
accuracy |
int |
Throws | |
---|---|
IllegalArgumentException |
if provider is null |
SecurityException |
if mock location app op is not set to allowed for your app. |
public void clearTestProviderEnabled (String provider)
This method is deprecated.
Use setTestProviderEnabled(java.lang.String, boolean)
instead.
Equivalent to calling setTestProviderEnabled(java.lang.String, boolean)
to disable a test
provider.
Parameters | |
---|---|
provider |
String : This value cannot be null . |
public void clearTestProviderLocation (String provider)
This method is deprecated.
This method has always been a no-op, and may be removed in the future.
Does nothing.
Parameters | |
---|---|
provider |
String : This value cannot be null . |
public void clearTestProviderStatus (String provider)
This method is deprecated.
This method has no effect.
This method has no effect as provider status has been deprecated and is no longer supported.
Parameters | |
---|---|
provider |
String : This value cannot be null . |
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<String> |
list of provider names
This value cannot be null . |
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 caller 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 order:
Note that the requirement on monetary cost is not removed in this process.
Parameters | |
---|---|
criteria |
Criteria : the criteria that need to be matched
This value cannot be null . |
enabledOnly |
boolean : if true then only enabled providers are included |
Returns | |
---|---|
String |
name of the provider that best matches the criteria, or null if none match |
Throws | |
---|---|
IllegalArgumentException |
if criteria is null |
public void getCurrentLocation (String provider, CancellationSignal cancellationSignal, Executor executor, Consumer<Location> consumer)
Asynchronously returns a single current location fix. This may activate sensors in order to
compute a new location, unlike getLastKnownLocation(java.lang.String)
, which will only return
a cached fix if available. The given callback will be invoked once and only once, either with
a valid location fix or with a null location fix if the provider was unable to generate a
valid location.
A client may supply an optional CancellationSignal
. If this is used to cancel the
operation, no callback should be expected after the cancellation.
This method may return locations from the very recent past (on the order of several seconds), but will never return older locations (for example, several minutes old or older). Clients may rely upon the guarantee that if this method returns a location, it will represent the best estimation of the location of the device in the present moment.
Clients calling this method from the background may notice that the method fails to
determine a valid location fix more often than while in the foreground. Background
applications may be throttled in their location accesses to some degree.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
cancellationSignal |
CancellationSignal : an optional signal that allows for cancelling this call
This value may be null . |
executor |
Executor : the callback will take place on this Executor
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
consumer |
Consumer : the callback invoked with either a Location or null
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if consumer is null |
SecurityException |
if no suitable permission is present |
public GnssCapabilities getGnssCapabilities ()
Returns the supported capabilities of the GNSS chipset.
Returns | |
---|---|
GnssCapabilities |
This value cannot be null . |
public String getGnssHardwareModelName ()
Returns the Model Name (including Vendor and Hardware/Software Version) of the GNSS hardware driver.
No device-specific serial number or ID is returned from this API.
Will return null when the GNSS hardware abstraction layer does not support providing this value.
Returns | |
---|---|
String |
public int getGnssYearOfHardware ()
Returns the model year of the GNSS hardware and software build. More details, such as build
date, may be available in getGnssHardwareModelName()
. May return 0 if the model year
is less than 2016.
Returns | |
---|---|
int |
public GpsStatus getGpsStatus (GpsStatus status)
This method is deprecated.
GpsStatus APIs are deprecated, use GnssStatus
APIs instead. No longer
supported in apps targeting S and above.
Retrieves information about the current status of the GPS engine. This should only be called
from within the GpsStatus.Listener#onGpsStatusChanged
callback to ensure that the
data is copied atomically.
The caller may either pass in an existing GpsStatus
object to be overwritten, or pass
null to create a new GpsStatus
object.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
status |
GpsStatus : object containing GPS status details, or null.
This value may be null . |
Returns | |
---|---|
GpsStatus |
status object containing updated GPS status. |
public Location getLastKnownLocation (String provider)
Gets the last known location from the given provider, or null if there is no last known location. The returned location may be quite old in some circumstances, so the age of the location should always be checked.
This will never activate sensors to compute a new location, and will only ever return a cached location.
See also getCurrentLocation(java.lang.String, android.os.CancellationSignal, java.util.concurrent.Executor, java.util.function.Consumer)
which
will always attempt to return a current location, but will potentially use additional power
in the course of the attempt as compared to this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
Returns | |
---|---|
Location |
the last known location for the given provider, or null if not available |
Throws | |
---|---|
SecurityException |
if no suitable permission is present |
IllegalArgumentException |
if provider is null or doesn't exist |
public LocationProvider getProvider (String provider)
Returns the information about the location provider with the given name, or null if no provider exists by that name.
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
Returns | |
---|---|
LocationProvider |
location provider information, or null if provider does not exist |
Throws | |
---|---|
IllegalArgumentException |
if provider is null |
public List<String> getProviders (boolean enabledOnly)
Returns a list of the names of location providers. Only providers that the caller has permission to access will be returned.
Parameters | |
---|---|
enabledOnly |
boolean : if true then only enabled providers are included |
Returns | |
---|---|
List<String> |
list of provider names
This value cannot be null . |
public List<String> getProviders (Criteria criteria, boolean enabledOnly)
Returns a list of the names of providers that satisfy the given criteria. Only providers that the caller has permission to access will be returned.
Parameters | |
---|---|
criteria |
Criteria : the criteria that providers must match
This value cannot be null . |
enabledOnly |
boolean : if true then only enabled providers are included |
Returns | |
---|---|
List<String> |
list of provider names |
Throws | |
---|---|
IllegalArgumentException |
if criteria is null |
public boolean isLocationEnabled ()
Returns the current enabled/disabled state of location. To listen for changes, see
MODE_CHANGED_ACTION
.
Returns | |
---|---|
boolean |
true if location is enabled and false if location is disabled. |
public boolean isProviderEnabled (String provider)
Returns the current enabled/disabled status of the given provider. To listen for changes, see
PROVIDERS_CHANGED_ACTION
.
Before API version Build.VERSION_CODES.LOLLIPOP
, this method would throw
SecurityException
if the location permissions were not sufficient to use the
specified provider.
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the provider exists and is enabled |
Throws | |
---|---|
IllegalArgumentException |
if provider is null |
public boolean registerAntennaInfoListener (Executor executor, GnssAntennaInfo.Listener listener)
Registers a Gnss Antenna Info listener. Only expect results if
GnssCapabilities#hasGnssAntennaInfo()
shows that antenna info is supported.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
executor |
Executor : the executor that the listener runs on.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
listener |
GnssAntennaInfo.Listener : a GnssAntennaInfo.Listener object to register.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the listener was added successfully, false otherwise. |
Throws | |
---|---|
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssMeasurementsCallback (Executor executor, GnssMeasurementsEvent.Callback callback)
Registers a GPS Measurement callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
executor |
Executor : the executor that the callback runs on.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
callback |
GnssMeasurementsEvent.Callback : a GnssMeasurementsEvent.Callback object to register.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
Throws | |
---|---|
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)
This method is deprecated.
Use registerGnssMeasurementsCallback(android.location.GnssMeasurementsEvent.Callback, android.os.Handler)
or registerGnssMeasurementsCallback(java.util.concurrent.Executor, android.location.GnssMeasurementsEvent.Callback)
instead.
Registers a GPS Measurement callback which will run on a binder thread.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
callback |
GnssMeasurementsEvent.Callback : a GnssMeasurementsEvent.Callback object to register.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
public boolean registerGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback, Handler handler)
Registers a GPS Measurement callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
callback |
GnssMeasurementsEvent.Callback : a GnssMeasurementsEvent.Callback object to register.
This value cannot be null . |
handler |
Handler : the handler that the callback runs on.
This value may be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
Throws | |
---|---|
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback, Handler handler)
Registers a GNSS Navigation Message callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
callback |
GnssNavigationMessage.Callback : a GnssNavigationMessage.Callback object to register.
This value cannot be null . |
handler |
Handler : the handler that the callback runs on.
This value may be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
Throws | |
---|---|
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssNavigationMessageCallback (Executor executor, GnssNavigationMessage.Callback callback)
Registers a GNSS Navigation Message callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
executor |
Executor : the looper that the callback runs on.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
callback |
GnssNavigationMessage.Callback : a GnssNavigationMessage.Callback object to register.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
Throws | |
---|---|
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)
This method is deprecated.
Use registerGnssNavigationMessageCallback(android.location.GnssNavigationMessage.Callback, android.os.Handler)
or registerGnssNavigationMessageCallback(java.util.concurrent.Executor, android.location.GnssNavigationMessage.Callback)
instead.
Registers a GNSS Navigation Message callback which will run on a binder thread.
Parameters | |
---|---|
callback |
GnssNavigationMessage.Callback : a GnssNavigationMessage.Callback object to register.
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the callback was added successfully, false otherwise. |
public boolean registerGnssStatusCallback (GnssStatus.Callback callback)
This method is deprecated.
Use registerGnssStatusCallback(android.location.GnssStatus.Callback, android.os.Handler)
or registerGnssStatusCallback(java.util.concurrent.Executor, android.location.GnssStatus.Callback)
instead.
Registers a GNSS status callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
callback |
GnssStatus.Callback : GNSS status callback object to register
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssStatusCallback (GnssStatus.Callback callback, Handler handler)
Registers a GNSS status callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
callback |
GnssStatus.Callback : GNSS status callback object to register
This value cannot be null . |
handler |
Handler : a handler with a looper that the callback runs on
This value may be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public boolean registerGnssStatusCallback (Executor executor, GnssStatus.Callback callback)
Registers a GNSS status callback.
Requires Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
executor |
Executor : the executor that the callback runs on
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
callback |
GnssStatus.Callback : GNSS status callback object to register
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the listener was successfully added |
Throws | |
---|---|
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if callback is null |
SecurityException |
if the ACCESS_FINE_LOCATION permission is not present |
public void removeGpsStatusListener (GpsStatus.Listener listener)
This method is deprecated.
use unregisterGnssStatusCallback(android.location.GnssStatus.Callback)
instead. No longer
supported in apps targeting S and above.
Removes a GPS status listener.
Parameters | |
---|---|
listener |
GpsStatus.Listener : GPS status listener object to remove |
public void removeNmeaListener (OnNmeaMessageListener listener)
Removes an NMEA listener.
Parameters | |
---|---|
listener |
OnNmeaMessageListener : a OnNmeaMessageListener object to remove
This value cannot be null . |
public void removeNmeaListener (GpsStatus.NmeaListener listener)
This method is deprecated.
Use removeNmeaListener(android.location.OnNmeaMessageListener)
instead.
No-op method to keep backward-compatibility.
Parameters | |
---|---|
listener |
GpsStatus.NmeaListener : This value cannot be null . |
public void removeProximityAlert (PendingIntent intent)
Removes the proximity alert with the given PendingIntent.
Before API version 17, this method could be used with
Manifest.permission.ACCESS_FINE_LOCATION
or
Manifest.permission.ACCESS_COARSE_LOCATION
.
From API version 17 and onwards, this method requires
Manifest.permission.ACCESS_FINE_LOCATION
permission.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
intent |
PendingIntent : the PendingIntent that no longer needs to be notified of
proximity alerts
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if intent is null |
SecurityException |
if Manifest.permission.ACCESS_FINE_LOCATION
permission is not present |
public void removeTestProvider (String provider)
Removes the test location provider with the given name or does nothing if no such test location provider exists.
Parameters | |
---|---|
provider |
String : the provider name
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null |
SecurityException |
if mock location app op is not set to allowed for your app. |
public void removeUpdates (LocationListener listener)
Removes location updates for the specified LocationListener
. Following this call,
the listener will no longer receive location updates.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
listener |
LocationListener : listener that no longer needs location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if listener is null |
public void removeUpdates (PendingIntent pendingIntent)
Removes location updates for the specified PendingIntent
. Following this call, the
PendingIntent will no longer receive location updates.
Parameters | |
---|---|
pendingIntent |
PendingIntent : pending intent that no longer needs location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if pendingIntent is null |
public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, LocationListener listener)
Register for location updates from the given provider with the given arguments. LocationListener
callbacks will take place on the given Looper
or Executor
.
If a null Looper
is supplied, the Looper of the calling thread will be used instead.
Only one request can be registered for each unique listener, so any subsequent requests with
the same listener will overwrite all associated arguments.
It may take a while to receive the first location update. If an immediate location is
required, applications may use the getLastKnownLocation(java.lang.String)
method.
The location update interval can be controlled using the minimum time parameter. The
elapsed time between location updates will never be less than this parameter, although it may
be more depending on location availability and other factors. Choosing a sensible value for
the minimum time parameter is important to conserve battery life. Every location update
requires power from a variety of sensors. Select a minimum time parameter 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 consider switching
to the PASSIVE_PROVIDER
instead.
The minimum distance 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 when the minimum time has elapsed. However it is more difficult for location providers to save power using the minimum distance parameter, so the minimum time parameter should be the primary tool for 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 turn on or modify active location providers, so
you do not need to be as careful about minimum time and minimum distance parameters. However,
if your application performs heavy work on a location update (such as network activity) then
you should select non-zero values for the parameters to rate-limit your update frequency in
the case another application enables a location provider with extremely fast updates.
In case the provider you have selected is disabled, location updates will cease, and a provider availability update will be sent. As soon as the provider is enabled again, another provider availability update will be sent and location updates will immediately resume.
When location callbacks are invoked, the system will hold a wakelock on your application's behalf for some period of time, but not indefinitely. If your application requires a long running wakelock within the location callback, you should acquire it yourself.
Prior to Jellybean, the minTime parameter was only a hint, and some location provider implementations ignored it. For Jellybean and onwards however, it is mandatory for Android compatible devices to observe both the minTime and minDistance parameters.
To unregister for location updates, use removeUpdates(android.location.LocationListener)
.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
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 |
public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, LocationListener listener, Looper looper)
Register for location updates using a provider selected through the given Criteria, and a
callback on the specified Looper
.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener)
for more detail on how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
criteria |
Criteria : contains parameters to choose the appropriate provider for location updates
This value cannot be null . |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
looper |
Looper : This value may be null . |
Throws | |
---|---|
IllegalArgumentException |
if criteria is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, LocationListener listener, Looper looper)
Register for location updates using the named provider, and a callback on
the specified Looper
.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener)
for more detail on how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
looper |
Looper : the looper handling listener callbacks, or null to use the looper of the
calling thread
This value may be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, Executor executor, LocationListener listener)
Register for location updates using the named provider, and a callback on
the specified Executor
.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener)
for more detail on how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
executor |
Executor : the executor handling listener callbacks
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, PendingIntent pendingIntent)
Register for location updates using a provider selected through the given Criteria, and
callbacks delivered via the provided PendingIntent
.
See requestLocationUpdates(java.lang.String, long, float, android.app.PendingIntent)
for more detail on
how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
criteria |
Criteria : contains parameters to choose the appropriate provider for location updates
This value cannot be null . |
pendingIntent |
PendingIntent : the pending intent to send location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if pendingIntent is null |
SecurityException |
if no suitable permission is present |
public void requestLocationUpdates (long minTimeMs, float minDistanceM, Criteria criteria, Executor executor, LocationListener listener)
Register for location updates using a provider selected through the given Criteria, and a
callback on the specified Executor
.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener)
for more detail on how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
criteria |
Criteria : contains parameters to choose the appropriate provider for location updates
This value cannot be null . |
executor |
Executor : the executor handling listener callbacks
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if criteria is null |
IllegalArgumentException |
if executor is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public void requestLocationUpdates (String provider, long minTimeMs, float minDistanceM, PendingIntent pendingIntent)
Register for location updates using the named provider, and callbacks delivered via the
provided PendingIntent
.
The delivered pending intents will contain extras with the callback information. The keys
used for the extras are KEY_LOCATION_CHANGED
and KEY_PROVIDER_ENABLED
. See
the documentation for each respective extra key for information on the values.
To unregister for location updates, use removeUpdates(android.app.PendingIntent)
.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener)
for more detail on how this method works.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
minTimeMs |
long : minimum time interval between location updates in milliseconds |
minDistanceM |
float : minimum distance between location updates in meters |
pendingIntent |
PendingIntent : the pending intent to send location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if pendingIntent is null |
SecurityException |
if no suitable permission is present |
public void requestSingleUpdate (String provider, PendingIntent pendingIntent)
This method is deprecated.
Use getCurrentLocation(java.lang.String, android.os.CancellationSignal, java.util.concurrent.Executor, java.util.function.Consumer)
instead as it does not carry a risk of extreme battery drain.
Register for a single location update using a named provider and pending intent.
See requestLocationUpdates(long, float, android.location.Criteria, android.app.PendingIntent)
for more detail
on how to use this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
pendingIntent |
PendingIntent : the pending intent to send location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if intent is null |
SecurityException |
if no suitable permission is present |
public void requestSingleUpdate (Criteria criteria, PendingIntent pendingIntent)
This method is deprecated.
Use getCurrentLocation(java.lang.String, android.os.CancellationSignal, java.util.concurrent.Executor, java.util.function.Consumer)
instead as it does not carry a risk of extreme battery drain.
Register for a single location update using a Criteria and pending intent.
See requestLocationUpdates(long, float, android.location.Criteria, android.app.PendingIntent)
for more detail
on how to use this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
criteria |
Criteria : contains parameters to choose the appropriate provider for location
updates
This value cannot be null . |
pendingIntent |
PendingIntent : the pending intent to send location updates
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if intent is null |
SecurityException |
if no suitable permission is present |
public void requestSingleUpdate (String provider, LocationListener listener, Looper looper)
This method is deprecated.
Use getCurrentLocation(java.lang.String, android.os.CancellationSignal, java.util.concurrent.Executor, java.util.function.Consumer)
instead as it does not carry a risk of extreme battery drain.
Register for a single location update using the named provider and a callback.
See requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener, android.os.Looper)
for
more detail on how to use this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
looper |
Looper : the looper handling listener callbacks, or null to use the looper of the
calling thread
This value may be null . |
Throws | |
---|---|
IllegalArgumentException |
if provider is null or doesn't exist |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public void requestSingleUpdate (Criteria criteria, LocationListener listener, Looper looper)
This method is deprecated.
Use getCurrentLocation(java.lang.String, android.os.CancellationSignal, java.util.concurrent.Executor, java.util.function.Consumer)
instead as it does not carry a risk of extreme battery drain.
Register for a single location update using a Criteria and a callback.
See requestLocationUpdates(long, float, android.location.Criteria, android.app.PendingIntent)
for more detail
on how to use this method.
Requires Manifest.permission.ACCESS_COARSE_LOCATION
or Manifest.permission.ACCESS_FINE_LOCATION
Parameters | |
---|---|
criteria |
Criteria : contains parameters to choose the appropriate provider for location updates
This value cannot be null . |
listener |
LocationListener : the listener to receive location updates
This value cannot be null . |
looper |
Looper : the looper handling listener callbacks, or null to use the looper of the
calling thread
This value may be null . |
Throws | |
---|---|
IllegalArgumentException |
if criteria is null |
IllegalArgumentException |
if listener is null |
SecurityException |
if no suitable permission is present |
public boolean sendExtraCommand (String provider, String command, Bundle extras)
Sends additional commands to a location provider. Can be used to support provider specific extensions to the Location Manager API.
Parameters | |
---|---|
provider |
String : a provider listed by getAllProviders()
This value cannot be null . |
command |
String : name of the command to send to the provider
This value cannot be null . |
extras |
Bundle : optional arguments for the command, or null
This value may be null . |
Returns | |
---|---|
boolean |
true always, the return value may be ignored |
public void setTestProviderEnabled (String provider, boolean enabled)
Sets the given test provider to be enabled or disabled.
Parameters | |
---|---|
provider |
String : the provider name
This value cannot be null . |
enabled |
boolean : the mock enabled value |
Throws | |
---|---|
SecurityException |
if mock location app op is not set to allowed for your app. |
IllegalArgumentException |
if provider is null or not a test provider |
public void setTestProviderLocation (String provider, Location location)
Sets a new location for the given test provider. This location will be identiable as a mock
location to all clients via Location#isFromMockProvider()
.
The location object must have a minimum number of fields set to be considered valid, as
per documentation on Location
class.
Parameters | |
---|---|
provider |
String : the provider name
This value cannot be null . |
location |
Location : the mock location
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if mock location app op is not set to allowed for your app. |
IllegalArgumentException |
if the provider is null or not a test provider |
IllegalArgumentException |
if the location is null or incomplete |
public void setTestProviderStatus (String provider, int status, Bundle extras, long updateTime)
This method is deprecated.
This method has no effect.
This method has no effect as provider status has been deprecated and is no longer supported.
Parameters | |
---|---|
provider |
String : This value cannot be null . |
status |
int |
extras |
Bundle : This value may be null . |
updateTime |
long |
public void unregisterAntennaInfoListener (GnssAntennaInfo.Listener listener)
Unregisters a GNSS Antenna Info listener.
Parameters | |
---|---|
listener |
GnssAntennaInfo.Listener : a GnssAntennaInfo.Listener object to remove.
This value cannot be null . |
public void unregisterGnssMeasurementsCallback (GnssMeasurementsEvent.Callback callback)
Unregisters a GPS Measurement callback.
Parameters | |
---|---|
callback |
GnssMeasurementsEvent.Callback : a GnssMeasurementsEvent.Callback object to remove.
This value cannot be null . |
public void unregisterGnssNavigationMessageCallback (GnssNavigationMessage.Callback callback)
Unregisters a GNSS Navigation Message callback.
Parameters | |
---|---|
callback |
GnssNavigationMessage.Callback : a GnssNavigationMessage.Callback object to remove.
This value cannot be null . |
public void unregisterGnssStatusCallback (GnssStatus.Callback callback)
Removes a GNSS status callback.
Parameters | |
---|---|
callback |
GnssStatus.Callback : GNSS status callback object to remove
This value cannot be null . |