The main entry point for interacting with the Fused Location Provider.
Constant Summary
String | KEY_MOCK_LOCATION | Key used for the Bundle extra in Location
object holding a boolean indicating whether the location was set using
setMockLocation(Location) . |
String | KEY_VERTICAL_ACCURACY | Key used for the Bundle extra in Location
object holding a float indicating the estimated vertical accuracy of the location, in
meters. |
Public Method Summary
Task<Void> |
flushLocations()
Flushes any locations currently being batched and sends them to all registered
LocationListener s,
LocationCallback s,
and PendingIntent s.
|
Task<Location> |
getCurrentLocation(int priority, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current
location of the device.
|
Task<Location> |
getCurrentLocation(CurrentLocationRequest
request, CancellationToken cancellationToken)
Returns a single location fix representing the best estimate of the current
location of the device.
|
Task<Location> |
getLastLocation(LastLocationRequest
request)
Returns the most recent historical location currently available according to
the given request.
|
Task<Location> |
getLastLocation()
Returns the most recent historical location currently available.
|
Task<LocationAvailability> |
getLocationAvailability()
Returns the availability of location data.
|
Task<Void> |
removeLocationUpdates(LocationCallback
callback)
Removes all location updates for the given callback.
|
Task<Void> |
removeLocationUpdates(PendingIntent
callbackIntent)
Removes all location updates for the given pending intent.
|
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 .
|
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 .
|
Task<Void> |
requestLocationUpdates(LocationRequest
request, PendingIntent
pendingIntent)
Requests location updates with the given request and results delivered via the
specified
PendingIntent .
|
Task<Void> | |
Task<Void> |
setMockMode(boolean mockMode)
Sets whether or not the Fused Location Provider is in mock mode.
|
Inherited Method Summary
Constants
public static final String KEY_MOCK_LOCATION
Key used for the Bundle extra in Location
object holding a boolean indicating whether the location was set using
setMockLocation(Location)
. If the value is false this extra is not set.
public static final String KEY_VERTICAL_ACCURACY
Key used for the Bundle extra in Location
object holding a float indicating the estimated vertical accuracy of the location, in
meters.
We define vertical accuracy at 68% confidence. Specifically, as 1-side of the
2-sided range above and below the estimated altitude reported by Location.getAltitude()
,
within which there is a 68% probability of finding the true altitude.
In the case where the underlying distribution is assumed Gaussian normal, this would be considered 1 standard deviation.
For example, if Location.getAltitude()
returns 150, and this extra returns 20 then there is a 68% probability of the true
altitude being between 130 and 170 meters.
If you're targeting Android O+ devices you should use directly
Location.hasVerticalAccuracy()
and
Location.getVerticalAccuracyMeters()
.
Public Methods
public 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.
When the returned Task
is
complete, then you can assume that any pending batched locations have already been
delivered.
public 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, null will be returned. Background apps calling this method may be throttled, and thus may be returned null results more often.
Clients may supply an optional CancellationToken
which may be used to cancel the request.
Parameters
priority | Priority
used to obtain location |
---|---|
cancellationToken | optional CancellationToken
to cancel the request |
public 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 historical location if a recent enough location fix exists, or may compute a fresh location. If unable to retrieve a current location fix, null will be returned. Background apps calling this method may be throttled, and thus may be returned null results more often.
Clients may supply an optional CancellationToken
which may be used to cancel the request.
Parameters
request | CurrentLocationRequest
with parameters detailing how to obtain the current location |
---|---|
cancellationToken | optional CancellationToken
to cancel the request |
public Task<Location> getLastLocation (LastLocationRequest request)
Returns the most recent historical location currently available according to the given request. Will return null if no matching historical location is available.
public Task<Location> getLastLocation ()
Returns the most recent historical location currently available. Will return null if no historical location is available. The historical location may be of an arbitrary age, so clients should check how old the location is to see if it suits their purposes.
public Task<LocationAvailability> getLocationAvailability ()
Returns the availability of location data. When
LocationAvailability.isLocationAvailable()
returns true, then the location
returned by
getLastLocation()
will be reasonably up to date within the hints specified
by the active LocationRequest
s.
If the client isn't connected to Google Play services and the request times out, null is returned.
Note it's always possible for
getLastLocation()
to return null even when this method returns true (e.g.
location settings were disabled between calls).
public Task<Void> removeLocationUpdates (LocationCallback callback)
Removes all location updates for the given callback.
public Task<Void> removeLocationUpdates (PendingIntent callbackIntent)
Removes all location updates for the given pending intent.
public 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
.
A previous request for location updates for the same callback 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.
Use
removeLocationUpdates(LocationCallback)
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.
public 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
. A
previous request for location updates for the same callback 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.
Use
removeLocationUpdates(LocationCallback)
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.
If the given Looper
is null,
the Looper associated with the calling thread will be used instead.
Throws
IllegalStateException | if looper is null and the calling thread has not called
Looper.prepare() |
---|
public 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 (for
example, when the client application is upgraded, restarted, removed, or force-quit),
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.
public 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.
Parameters
location | valid location to set as the next FLP location |
---|
Throws
SecurityException | if security requirements are not met |
---|
public 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.
Parameters
mockMode | the mock mode state to set for the Fused Location Provider APIs |
---|
Throws
SecurityException | if security requirements are not met |
---|