The main entry point for interacting with the Fused Location Provider (FLP). In order to
obtain an instance of this class, see LocationServices
.
In order to use most location APIs, clients are required to hold either the Manifest.permission.ACCESS_COARSE_LOCATION
permission or the Manifest.permission.ACCESS_FINE_LOCATION
.
Clients holding only the coarse permission will
receive locations that have been obfuscated to hide the device's exact location, and only
reveal the approximate area of the device. In addition, clients with only the coarse
permission will receive location updates at a throttled rate to avoid wasting power to derive
approximate locations. Applications which do not require exact location to work properly
(such as a weather app potentially) are encouraged to request only the coarse location
permission. From Android 12 onwards, the user may force any app to use coarse location even
if it has requested fine location, so apps should carefully test their behavior with only the
coarse location permission to ensure their functionality works as expected.
If clients have only the coarse or fine location permission, they will not receive locations while they are in the background. Whether an app is in the background or foreground is normally determined by whether it is currently showing any UI to the user. Apps may also use a foreground location service to maintain their foreground status when they would normally be in the background.
If clients also hold the
Manifest.permission.ACCESS_BACKGROUND_LOCATION
permission, they may receive
locations while in the background even if the above conditions are not met.
There are several types of use cases for location. One of the most common is simply
obtaining a single location in order to determine where the device is now, and continue from
there. The
getCurrentLocation(CurrentLocationRequest, CancellationToken)
API is designed with
exactly this use case in mind. On the other hand, if repeated location updates are required,
such as when tracking the user's location over time,
requestLocationUpdates(LocationRequest, Executor, LocationListener)
or one of its
variants is better suited. Clients are encourage to familiarize themselves with the full
range of APIs available in this class to understand which is best suited for their needs.
Constant Summary
String | KEY_MOCK_LOCATION | This constant is deprecated. Use
Location.isMock()
on Android S and above, otherwise use
LocationCompat.isMock() from the compat libraries instead. |
String | KEY_VERTICAL_ACCURACY | This constant is deprecated. Use
Location.getVerticalAccuracyMeters() on Android O and above, otherwise use
LocationCompat.getVerticalAccuracyMeters() from the compat libraries
instead. |
Public Method Summary
abstract Task<Void> |
flushLocations()
Flushes any locations currently being batched and sends them to all registered
LocationListener s,
LocationCallback s,
and PendingIntent s.
|
abstract Task<Location> |
getCurrentLocation(int priority, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current
location of the device.
|
abstract Task<Location> |
getCurrentLocation(CurrentLocationRequest
request, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current
location of the device.
|
abstract Task<Location> |
getLastLocation(LastLocationRequest
request)
Returns the most recent cached location from the past currently available.
|
abstract Task<Location> |
getLastLocation()
Returns the most recent cached location from the past currently available.
|
abstract Task<LocationAvailability> |
getLocationAvailability()
Returns the estimated availability of location data.
|
abstract Task<Void> |
removeDeviceOrientationUpdates(DeviceOrientationListener
listener)
This method is deprecated. Use
FusedOrientationProviderClient.removeOrientationUpdates(DeviceOrientationListener)
instead.
|
abstract Task<Void> |
removeLocationUpdates(LocationListener
listener)
Removes all location updates for the given listener.
|
abstract Task<Void> |
removeLocationUpdates(LocationCallback
callback)
Removes all location updates for the given callback.
|
abstract Task<Void> |
removeLocationUpdates(PendingIntent
pendingIntent)
Removes all location updates for the given pending intent.
|
abstract Task<Void> |
requestDeviceOrientationUpdates(DeviceOrientationRequest
request, Executor
executor,
DeviceOrientationListener listener)
This method is deprecated. Use
FusedOrientationProviderClient.requestOrientationUpdates(DeviceOrientationRequest,
Executor, DeviceOrientationListener) instead.
|
abstract Task<Void> |
requestDeviceOrientationUpdates(DeviceOrientationRequest
request,
DeviceOrientationListener listener, Looper looper)
This method is deprecated. Use
FusedOrientationProviderClient.requestOrientationUpdates(DeviceOrientationRequest,
Executor, DeviceOrientationListener) instead.
|
abstract Task<Void> |
requestLocationUpdates(LocationRequest
request, LocationListener
listener, Looper looper)
Requests location updates with the given request and results delivered to the
given listener on the specified
Looper .
|
abstract Task<Void> |
requestLocationUpdates(LocationRequest
request, Executor
executor, LocationCallback
callback)
Requests location updates with the given request and results delivered to the
given callback on the specified
Executor .
|
abstract Task<Void> |
requestLocationUpdates(LocationRequest
request, Executor
executor, LocationListener
listener)
Requests location updates with the given request and results delivered to the
given listener on the specified
Executor .
|
abstract Task<Void> |
requestLocationUpdates(LocationRequest
request, LocationCallback
callback, Looper looper)
Requests location updates with the given request and results delivered to the
given callback on the specified
Looper .
|
abstract Task<Void> |
requestLocationUpdates(LocationRequest
request, PendingIntent
pendingIntent)
Requests location updates with the given request and results delivered via the
specified
PendingIntent .
|
abstract Task<Void> | |
abstract Task<Void> |
setMockMode(boolean mockMode)
Sets whether or not the Fused Location Provider is in mock mode.
|
Constants
public static final String KEY_MOCK_LOCATION
This constant is deprecated.
Use Location.isMock()
on Android S and above, otherwise use
LocationCompat.isMock() from the compat libraries instead.
Key used for the Bundle extra in Location
object indicating whether this is a mock location.
public static final String KEY_VERTICAL_ACCURACY
This constant is deprecated.
Use
Location.getVerticalAccuracyMeters()
on Android O and above, otherwise use
LocationCompat.getVerticalAccuracyMeters() from the compat libraries instead.
Key used for the Bundle extra in Location
object holding a float indicating the estimated vertical accuracy of the location, in
meters.
Public Methods
public abstract Task<Void> flushLocations ()
Flushes any locations currently being batched and sends them to all registered
LocationListener
s,
LocationCallback
s,
and PendingIntent
s.
This call is only useful when batching is specified using
LocationRequest.setMaxWaitTime(long)
, otherwise locations are already
delivered immediately when available.
public abstract Task<Location> getCurrentLocation (int priority, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current location of the device. This may return a cached location if a recent enough location fix exists, or may compute a fresh location. If unable to retrieve a current location fix before timing out, null will be returned.
The behavior of this method can be modified in important ways through various
parameters of CurrentLocationRequest
,
and clients are encouraged to familiarize themselves with CurrentLocationRequest
and the
getCurrentLocation(CurrentLocationRequest, CancellationToken)
overload.
See
getCurrentLocation(CurrentLocationRequest, CancellationToken)
for more
documentation.
public abstract Task<Location> getCurrentLocation (CurrentLocationRequest request, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current location of the device. This may return a cached location if a recent enough location fix exists, or may compute a fresh location. If unable to retrieve a current location fix before timing out, null will be returned.
Clients may supply an optional CancellationToken
which may be used to cancel the request.
This API has the same background
location limits that apply to
requestLocationUpdates(LocationRequest, PendingIntent)
and all location
APIs, so clients may note that this API fails to return a location more often when
invoked from the background.
There are many parameters of CurrentLocationRequest
that can substantially affect the latency and behavior of this API - in particular,
clients are encouraged to select a
CurrentLocationRequest.getMaxUpdateAgeMillis()
that best suits their needs,
and to review all parameters of the request to familiarize themselves with the
options.
public abstract Task<Location> getLastLocation (LastLocationRequest request)
Returns the most recent cached location from the past currently available. Will return null if no such cached location is available. The returned location may be of an arbitrary age, so clients should check how old the location is to see if it suits their purposes.
See
getLastLocation()
for more documentation.
public abstract Task<Location> getLastLocation ()
Returns the most recent cached location from the past currently available. Will return null if no such cached location is available. The returned location may be of an arbitrary age, so clients should check how old the location is to see if it suits their purposes.
Since this method simply checks caches for pre-computed locations it is generally cheap and quick to return.
However, clients should still avoid calling this method in a tight loop or otherwise
wasting system resources. If a client wishes to be informed of new locations passively,
registering a location request with Priority.PRIORITY_PASSIVE
through
requestLocationUpdates(LocationRequest, Executor, LocationListener)
or
similar APIs is far more efficient than calling this method over and over
indefinitely.
If a client needs the current location of the device and is checking to see if a
cached location is recent enough to be useful, but will need to calculate a new
location otherwise, clients are recommended to use
getCurrentLocation(CurrentLocationRequest, CancellationToken)
which can take
advantage of a cached location or calculate a new location if necessary in a single
method call.
public abstract Task<LocationAvailability> getLocationAvailability ()
Returns the estimated availability of location data. If
LocationAvailability.isLocationAvailable()
returns true then it is likely
(but not guaranteed) that Fused Location Provider APIs will be able to derive and
return fresh location updates. If
LocationAvailability.isLocationAvailable()
returns false, then it is likely
(but not guaranteed) that Fused Location Provider APIs will be unable to derive and
return fresh location updates, though there may be cached locations available.
public abstract Task<Void> removeDeviceOrientationUpdates (DeviceOrientationListener listener)
This method is deprecated.
Use
FusedOrientationProviderClient.removeOrientationUpdates(DeviceOrientationListener)
instead.
Removes all device orientation updates for the given listener.
public abstract Task<Void> removeLocationUpdates (LocationListener listener)
Removes all location updates for the given listener.
public abstract Task<Void> removeLocationUpdates (LocationCallback callback)
Removes all location updates for the given callback.
public abstract Task<Void> removeLocationUpdates (PendingIntent pendingIntent)
Removes all location updates for the given pending intent.
public abstract Task<Void> requestDeviceOrientationUpdates (DeviceOrientationRequest request, Executor executor, DeviceOrientationListener listener)
This method is deprecated.
Use
FusedOrientationProviderClient.requestOrientationUpdates(DeviceOrientationRequest,
Executor, DeviceOrientationListener)
instead.
Requests device orientation updates with the given request and delivers results to
the given listener on the specified Executor
.
A previous request for device orientation for the same listener will be replaced by this request.
Device orientation updates will only be served if the requesting app is in foreground.
Use
removeDeviceOrientationUpdates(DeviceOrientationListener)
to stop device
orientation updates once no longer needed.
public abstract Task<Void> requestDeviceOrientationUpdates (DeviceOrientationRequest request, DeviceOrientationListener listener, Looper looper)
This method is deprecated.
Use
FusedOrientationProviderClient.requestOrientationUpdates(DeviceOrientationRequest,
Executor, DeviceOrientationListener)
instead.
Requests device orientation updates with the given request and delivers results to
the given listener on the specified Looper
.
A previous device orientation request for the same listener will be replaced by this request.
Device orientation updates will only be served if the requesting app is in foreground.
Throws
IllegalStateException | if looper is null and the calling thread has not called
Looper.prepare() . |
---|
public abstract Task<Void> requestLocationUpdates (LocationRequest request, LocationListener listener, Looper looper)
Requests location updates with the given request and results delivered to the given
listener on the specified Looper
.
See
requestLocationUpdates(LocationRequest, Executor, LocationListener)
for more
documentation.
Throws
IllegalStateException | if looper is null and the calling thread has not called
Looper.prepare() |
---|
public abstract Task<Void> requestLocationUpdates (LocationRequest request, Executor executor, LocationCallback callback)
Requests location updates with the given request and results delivered to the given
callback on the specified Executor
.
If the given Looper
is null,
the Looper associated with the calling thread will be used instead.
See
requestLocationUpdates(LocationRequest, Executor, LocationListener)
for more
documentation.
public abstract Task<Void> requestLocationUpdates (LocationRequest request, Executor executor, LocationListener listener)
Requests location updates with the given request and results delivered to the given
listener on the specified Executor
.
A previous request for location updates for the same listener will be replaced by this
request. If the location request has a priority higher than Priority.PRIORITY_PASSIVE
,
a wakelock may be held on the client's behalf while delivering locations.
Use
removeLocationUpdates(LocationListener)
to stop location updates once no
longer needed.
Depending on the arguments passed in through the LocationRequest
,
cached locations from the past may be delivered when the listener is first registered.
Clients should ensure they are checking location timestamps appropriately if
necessary.
Location requests that do not specify batching (see LocationRequest.isBatched()
)
are guaranteed to receive locations that are monotonically increasing in time (they
will never receive a location that appears to travel backwards in time compared to the
prior location). Location requests that allow for batching are guaranteed that every
location within a batch will be monotonically increasing in time, but may receive
out-of-order locations when compared across separate batches, and must be prepared to
handle such locations correctly for their own needs.
public abstract Task<Void> requestLocationUpdates (LocationRequest request, LocationCallback callback, Looper looper)
Requests location updates with the given request and results delivered to the given
callback on the specified Looper
.
If the given Looper
is null,
the Looper associated with the calling thread will be used instead.
See
requestLocationUpdates(LocationRequest, Executor, LocationListener)
for more
documentation.
Throws
IllegalStateException | if looper is null and the calling thread has not called
Looper.prepare() |
---|
public abstract Task<Void> requestLocationUpdates (LocationRequest request, PendingIntent pendingIntent)
Requests location updates with the given request and results delivered via the
specified PendingIntent
.
A previous request for location updates for the same pending intent will be replaced by
this request. If the location request has a priority higher than Priority.PRIORITY_PASSIVE
,
a wakelock may be held on the client's behalf while delivering locations. A wakelock
will not be held while delivering availability updates.
Location updates should be extracted from the received Intent
via
LocationResult.hasResult(Intent)
and
LocationResult.extractResult(Intent)
. Availability updates should be
extracted from the Intent
via
LocationAvailability.hasLocationAvailability(Intent)
and
LocationAvailability.extractLocationAvailability(Intent)
.
This method is suited for receiving location updates in the background, even when
the receiving app may have been killed by the system. Using a PendingIntent
allows the target component to be started and receive location updates. For foreground
use cases prefer to listen for location updates via a listener or callback instead of a
pending intent.
PendingIntent
location requests are automatically removed when the client application is reset (when
the client application is upgraded or removed, or the user force-restarts or
force-quits it), or if the pending intent is canceled.
Use
removeLocationUpdates(PendingIntent)
to stop location updates once no longer
needed.
Depending on the arguments passed in through the LocationRequest
,
locations from the past may be delivered when the callback is first registered. Clients
should ensure they are checking location timestamps appropriately if necessary.
Location requests that do not specify batching (see LocationRequest.isBatched()
)
are guaranteed to receive locations that are monotonically increasing in time (they
will never receive a location that appears to travel backwards in time compared to the
prior location). Location requests that allow for batching may receive such
out-of-order locations, and must be prepared to handle such locations correctly for
their own needs.
This API will not work for instant apps, since they are
intended to run only in the foreground and will be disconnected otherwise. Instant apps
should prefer to use any of the overloads that accept LocationListener
or LocationCallback
instead.
public abstract Task<Void> setMockLocation (Location location)
Sets the mock location of the Fused Location Provider.
Delivers the given location to the FLP as if it was coming from an underlying
location source. Normal FLP logic around receiving and delivering location will
generally apply. For this reason the timestamps of the location should be set
appropriately, as the FLP may expect monotonically increasing timestamps. When this
location is reported to FLP clients it will be marked as a mock location (see
Location.isMock()
or
LocationCompat.isMock() from the compat libraries).
This API can only be successfully used while the FLP is in mock mode. Clients must
fulfill the same security requirements as for
setMockMode(boolean)
as well.
public abstract Task<Void> setMockMode (boolean mockMode)
Sets whether or not the Fused Location Provider is in mock mode.
Entering mock mode clears the FLP's cached locations, and ensures that the FLP will
only report locations set through
setMockLocation(Location)
. Exiting mock mode will clear any mock locations
set from the FLP's cache as well. Mock mode affects all location clients using the FLP,
including location clients in other processes and derivative APIs such as geofencing
and so forth. Because this affects all FLP usage, clients should always ensure they
properly set the mock mode to false when finished.
Successfully using this API on devices running Android M+ requires the client to
request the android.permission.ACCESS_MOCK_LOCATION
permission and to be
selected as the mock location app within the device developer settings. Using this API
on pre-M devices requires the Settings.Secure.ALLOW_MOCK_LOCATION
setting
to be enabled.