The main entry point for interacting with the fused location provider.
Note: It's recommended to use Google Play services version 11.6.0 or higher, which includes bug fixes for this class.
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 token)
Returns a single current location fix on the device.
|
Task<Location> |
getLastLocation()
Returns the best most recent location currently available.
|
Task<LocationAvailability> |
getLocationAvailability()
Returns the availability of location data.
|
Task<Void> |
removeLocationUpdates(PendingIntent
callbackIntent)
Removes all location updates for the given pending intent.
|
Task<Void> |
removeLocationUpdates(LocationCallback
callback)
Removes all location updates for the given location result listener.
|
Task<Void> |
requestLocationUpdates(LocationRequest
request, LocationCallback
callback, Looper looper)
Requests location updates with a callback on the specified Looper thread.
|
Task<Void> |
requestLocationUpdates(LocationRequest
request, PendingIntent
callbackIntent)
Requests location updates with a callback on the specified PendingIntent.
|
Task<Void> | |
Task<Void> |
setMockMode(boolean isMockMode)
Sets whether or not the 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 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 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
hasVerticalAccuracy()
and
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
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 token)
Returns a single current location fix on the device. Unlike
getLastLocation()
that returns a cached location, this method could cause
active location computation on the device. A single fresh location will be returned if
the device location can be determined within reasonable time (tens of seconds),
otherwise null will be returned.
This method may return locations that are a few seconds old, but never returns much older locations. This is suitable for foreground applications that need a single fresh current location.
Background apps calling this method will be throttled under background location limits, so background apps may find the method returns null locations more often.
A client may supply a CancellationToken
to cancel the request. The client can listen to cancellation event by adding an
OnCanceledListener
to the returned task.
Parameters
priority | One of the PRIORITY_* in LocationRequest . |
---|---|
token | A CancellationToken
that can be used to cancel the current location request. |
Returns
- A single current location fix, or
null
if the location cannot be computed within reasonable time.
public Task<Location> getLastLocation ()
Returns the best most recent location currently available.
If a location is not available, which should happen very rarely, null will be returned. The best accuracy available while respecting the location permissions will be returned.
This method provides a simplified way to get location. It is particularly well suited for applications that do not require an accurate location and that do not want to maintain extra logic for location updates.
public Task<LocationAvailability> getLocationAvailability ()
Returns the availability of location data. When
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 (PendingIntent callbackIntent)
Removes all location updates for the given pending intent.
It is possible for this call to cancel the PendingIntent under some circumstances.
Parameters
callbackIntent | The PendingIntent that was used in
requestLocationUpdates(LocationRequest, PendingIntent) or is equal as
defined by
equals(Object) . |
---|
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
public Task<Void> removeLocationUpdates (LocationCallback callback)
Removes all location updates for the given location result listener.
Parameters
callback | The callback to remove. |
---|
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
public Task<Void> requestLocationUpdates (LocationRequest request, LocationCallback callback, Looper looper)
Requests location updates with a callback on the specified Looper thread.
This method is suited for the foreground use cases. For background use cases, the
PendingIntent
version of the method is recommended, see
requestLocationUpdates(LocationRequest, PendingIntent)
.
Any previous LocationRequests registered on this LocationListener will be replaced.
This call will keep the Google Play services connection active, so make sure to call
removeLocationUpdates(LocationCallback)
when you no longer need it,
otherwise you lose the benefits of the automatic connection management.
Callbacks for LocationCallback
will be made on the specified thread, which must already be a prepared looper
thread.
Parameters
request | The location request for the updates. |
---|---|
callback | The callback for the location updates. |
looper | The Looper object whose message queue will be used to implement the callback mechanism, or null to make callbacks on the calling thread. |
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
Throws
IllegalStateException | If looper is null and this method is executed in a thread that has not called Looper.prepare(). |
---|
public Task<Void> requestLocationUpdates (LocationRequest request, PendingIntent callbackIntent)
Requests location updates with a callback on the specified PendingIntent.
This method is suited for the background use cases, more specifically for receiving
location updates, even when the app has been killed by the system. In order to do so,
use a PendingIntent
for a started service. For foreground use cases, the LocationCallback
version of the method is recommended, see
requestLocationUpdates(LocationRequest, LocationCallback, Looper)
.
Any previously registered requests that have the same PendingIntent (as defined by
equals(Object)
) will be replaced by this request.
Both LocationResult
and LocationAvailability
are sent to the given PendingIntent. You can extract data from an Intent using
hasResult(Intent)
,
extractResult(Intent)
,
hasLocationAvailability(Intent)
, and
extractLocationAvailability(Intent)
.
Parameters
request | The location request for the updates. |
---|---|
callbackIntent | A pending intent to be sent for each location update. |
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
public Task<Void> setMockLocation (Location mockLocation)
Sets the mock location to be used for the location provider. This location will be used in place of any actual locations from the underlying providers (network or gps).
setMockMode(boolean)
must be called and set to true prior to calling this
method.
Care should be taken in specifying the timestamps as many applications require them to be monotonically increasing.
Parameters
mockLocation | The mock location. Must have a minimum number of fields set to be considered a
valild location, as per documentation in the Location
class. |
---|
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
Throws
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present or the
Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled. |
---|
public Task<Void> setMockMode (boolean isMockMode)
Sets whether or not the location provider is in mock mode.
The underlying providers (network and gps) will be stopped (except by direct
LocationManager
access), and only locations specified in
setMockLocation(Location)
will be reported. This will effect all location
clients connected using the FusedLocationProviderClient
,
including geofencer clients (i.e. geofences can be triggered based on mock
locations).
The client must remain connected in order for mock mode to remain active. If the client dies the system will return to its normal state.
Calls are not nested, and mock mode will be set directly regardless of previous calls.
Parameters
isMockMode | If true the location provider will be set to mock mode. If false it will be returned to its normal state. |
---|
Returns
- a Task for the call, check
isSuccessful()
to determine if it was successful.
Throws
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present or the
Settings.Secure.ALLOW_MOCK_LOCATION system setting is not enabled. |
---|