An encapsulation of various parameters for requesting location through FusedLocationProviderClient.
There are a variety of different situations where various types of applications may want
to use different request parameters. For example, clients that are showing the user's
location in realtime may consider a Priority.PRIORITY_HIGH_ACCURACY
request with a short interval. At the other extreme, a client that wants a negligible power
impact while still receiving opportunistic locations could use a Priority.PRIORITY_PASSIVE
request so that the client will not trigger any location updates, but can still receive
locations updates triggered by other client's location requests. See the documentation around
all the various parameters of LocationRequest for more information.
Clients should consider using
LocationRequest.Builder.setMinUpdateIntervalMillis(long) to limit the fastest rate
at which their location callbacks may be invoked (and thus limit the amount of power usage
they may be blamed for).
Clients cannot specify the exact sensors, such as GNSS, that will be used in order to
satisfy location requests. In fact, FusedLocationProviderClient
may fuse the results from many different sensors into a single location in order to more
accurately estimate the device's location.
Location requests from clients with only the Manifest.permission.ACCESS_COARSE_LOCATION
permission may be throttled to a slower interval, and the returned location will be
obfuscated to only show a coarse level of accuracy. Since on later Android levels a user can
force any application to receive only the coarse permissions, applications should ensure they
are testing these scenarios before release as well.
Many location requests parameters are considered hints or best-effort only, and you may receive locations that are more/less accurate and faster/slower than expected.
Location requests that do not specify batching (see 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 is monotonically increasing in time, but may receive out-of-order locations
across different batches, and must be prepared to handle such locations correctly for their
own needs.
Nested Class Summary
| class | LocationRequest.Builder | Builder for LocationRequest. |
|
Constant Summary
| int | PRIORITY_BALANCED_POWER_ACCURACY | This constant is deprecated. Use
Priority.PRIORITY_BALANCED_POWER_ACCURACY instead. |
| int | PRIORITY_HIGH_ACCURACY | This constant is deprecated. Use
Priority.PRIORITY_HIGH_ACCURACY instead. |
| int | PRIORITY_LOW_POWER | This constant is deprecated. Use
Priority.PRIORITY_LOW_POWER instead. |
| int | PRIORITY_NO_POWER | This constant is deprecated. Use
Priority.PRIORITY_PASSIVE
instead. |
Inherited Constant Summary
Field Summary
| public static final Creator<LocationRequest> | CREATOR |
Public Method Summary
| static LocationRequest |
create()
This method is deprecated. Use
LocationRequest.Builder instead. May be removed in a future
release.
|
| boolean | |
| long |
getDurationMillis()
The duration of this request.
|
| long |
getExpirationTime()
This method is deprecated. Use
getDurationMillis() instead. Using this method will return the
duration added to the current elapsed realtime, which may give unexpected
results. May be removed in a future release.
|
| long |
getFastestInterval()
This method is deprecated. Use
getMinUpdateIntervalMillis() instead. May be removed in a future
release.
|
| int |
getGranularity()
The
Granularity
of locations returned for this request.
|
| long |
getInterval()
This method is deprecated. Use
getIntervalMillis() instead. May be removed in a future
release.
|
| long |
getIntervalMillis()
The desired interval of location updates.
|
| long |
getMaxUpdateAgeMillis()
The maximum age of an initial historical location delivered for this request.
|
| long |
getMaxUpdateDelayMillis()
The longest a location update may be delayed.
|
| int |
getMaxUpdates()
The maximum number of updates delivered to this request.
|
| long |
getMaxWaitTime()
This method is deprecated. Use
getMaxUpdateDelayMillis() instead. May be removed in a future
release.
|
| float |
getMinUpdateDistanceMeters()
The minimum distance required between consecutive location updates.
|
| long |
getMinUpdateIntervalMillis()
The fastest allowed interval of location updates.
|
| int |
getNumUpdates()
This method is deprecated. Use
getMaxUpdates() instead. May be removed in a future release.
|
| int |
getPriority()
The
Priority
of the location request.
|
| float |
getSmallestDisplacement()
This method is deprecated. Use
getMinUpdateDistanceMeters() instead.
|
| int |
hashCode()
|
| boolean |
isBatched()
True if this request allows batching (i.e.
|
| boolean |
isFastestIntervalExplicitlySet()
This method is deprecated. Do not use. May be removed in a future
release.
|
| boolean |
isPassive()
True if the priority is
Priority.PRIORITY_PASSIVE.
|
| boolean |
isWaitForAccurateLocation()
If this request is
Priority.PRIORITY_HIGH_ACCURACY, this will delay delivery of initial
low accuracy locations for a small amount of time in case a high accuracy
location can be delivered instead.
|
| LocationRequest |
setExpirationDuration(long durationMillis)
This method is deprecated. Use
LocationRequest.Builder.setDurationMillis(long) instead. May be
removed in a future release.
|
| LocationRequest |
setExpirationTime(long elapsedRealtime)
This method is deprecated. Use
LocationRequest.Builder.setDurationMillis(long) instead. Using this
method will express the expiration time in terms of duration, which may give
unexpected results. May be removed in a future release.
|
| LocationRequest |
setFastestInterval(long fastestIntervalMillis)
This method is deprecated. Use
LocationRequest.Builder.setMinUpdateIntervalMillis(long) instead.
May be removed in a future release.
|
| LocationRequest |
setInterval(long intervalMillis)
This method is deprecated. Use
LocationRequest.Builder.setIntervalMillis(long) instead. May be
removed in a future release.
|
| LocationRequest |
setMaxWaitTime(long maxWaitTimeMillis)
This method is deprecated. Use
LocationRequest.Builder.setMaxUpdateDelayMillis(long) instead. May
be removed in a future release.
|
| LocationRequest |
setNumUpdates(int maxUpdates)
This method is deprecated. Use
LocationRequest.Builder.setMaxUpdates(int) instead. May be removed
in a future release.
|
| LocationRequest |
setPriority(int priority)
This method is deprecated. Use
LocationRequest.Builder.setPriority(int) instead. May be removed in
a future release.
|
| LocationRequest |
setSmallestDisplacement(float smallestDisplacementMeters)
This method is deprecated. Use
LocationRequest.Builder.setMinUpdateDistanceMeters(float) instead.
May be removed in a future release.
|
| LocationRequest |
setWaitForAccurateLocation(boolean waitForAccurateLocation)
This method is deprecated. Use
LocationRequest.Builder.setWaitForAccurateLocation(boolean) instead.
May be removed in a future release.
|
| String |
toString()
|
| void |
writeToParcel(Parcel parcel, int
flags)
|
Inherited Method Summary
Constants
public static final int PRIORITY_BALANCED_POWER_ACCURACY
This constant is deprecated.
Use
Priority.PRIORITY_BALANCED_POWER_ACCURACY instead.
public static final int PRIORITY_HIGH_ACCURACY
This constant is deprecated.
Use
Priority.PRIORITY_HIGH_ACCURACY instead.
public static final int PRIORITY_LOW_POWER
This constant is deprecated.
Use Priority.PRIORITY_LOW_POWER
instead.
public static final int PRIORITY_NO_POWER
This constant is deprecated.
Use Priority.PRIORITY_PASSIVE
instead.
Fields
public static final Creator<LocationRequest> CREATOR
Public Methods
public static LocationRequest create ()
This method is deprecated.
Use LocationRequest.Builder
instead. May be removed in a future release.
public boolean equals (Object object)
public long getDurationMillis ()
The duration of this request. A location request will not receive any locations
after it has expired, and will be removed shortly thereafter. A value of Long.MAX_VALUE
implies an infinite duration.
public long getExpirationTime ()
This method is deprecated.
Use
getDurationMillis() instead. Using this method will return the duration added
to the current elapsed realtime, which may give unexpected results. May be removed in a
future release.
public long getFastestInterval ()
This method is deprecated.
Use
getMinUpdateIntervalMillis() instead. May be removed in a future release.
public int getGranularity ()
The Granularity
of locations returned for this request. This controls whether fine or coarse locations
may be returned.
public long getInterval ()
This method is deprecated.
Use
getIntervalMillis() instead. May be removed in a future release.
public long getIntervalMillis ()
The desired interval of location updates. Location updates may arrive faster than
this interval (but no faster than specified by
getMinUpdateIntervalMillis()) or slower than this interval (if the request
is being throttled for example).
public long getMaxUpdateAgeMillis ()
The maximum age of an initial historical location delivered for this request. A
value of 0 indicates that no initial historical location will be delivered, only
freshly derived locations. A value Long.MAX_VALUE
represents an effectively unbounded maximum age.
This parameter applies only to a historical location which may be delivered as the very first location for a location request. Subsequent locations will always be freshly derived, and this parameter does not apply to them.
public long getMaxUpdateDelayMillis ()
The longest a location update may be delayed. This parameter controls location
batching behavior. If this is set to a value at least 2x larger than the interval
specified by
getIntervalMillis(), then a device may (but is not required to) save power
by delivering locations in batches. If clients do not require immediate delivery,
consider setting this value as high as is reasonable to allow for additional power
savings.
For example, if a request is made with a 2s interval and a 10s maximum update delay, this implies that the device may choose to deliver batches of 5 locations every 10s (where each location should represent a point in time ~2s after the previous).
Support for batching may vary by device type, so simply allowing batching via this parameter does not imply a client will receive batched results on all devices.
FusedLocationProviderClient.flushLocations() may be used to flush locations
that have been batched, but not delivered yet.
Location requests that allow for batching may receive out-of-order locations, and
must be prepared to handle such locations correctly for their own needs. See
isBatched()
for more information.
public int getMaxUpdates ()
The maximum number of updates delivered to this request. A location request will not
receive any locations after the maximum number of updates has been reached, and will be
removed shortly thereafter. A value of Integer.MAX_VALUE
implies an unlimited number of updates.
public long getMaxWaitTime ()
This method is deprecated.
Use
getMaxUpdateDelayMillis() instead. May be removed in a future release.
public float getMinUpdateDistanceMeters ()
The minimum distance required between consecutive location updates. If a derived location update is not at least the specified distance away from the previous location update delivered to the client, it will not be delivered. This may also allow additional power savings under some circumstances.
public long getMinUpdateIntervalMillis ()
The fastest allowed interval of location updates. Location updates may arrive faster
than the desired interval (getIntervalMillis()),
but will never arrive faster than specified here. FLP APIs make some allowance for
jitter with the minimum update interval, so clients need not worry about location
updates that arrive a couple milliseconds too early being rejected.
public int getNumUpdates ()
This method is deprecated.
Use
getMaxUpdates() instead. May be removed in a future release.
public int getPriority ()
The Priority
of the location request.
public float getSmallestDisplacement ()
This method is deprecated.
Use
getMinUpdateDistanceMeters() instead.
public int hashCode ()
public boolean isBatched ()
True if this request allows batching (i.e.
getMaxUpdateDelayMillis() is at least 2x
getIntervalMillis()). Note that simply because a request allows batching
does not guarantee it will receive batched results, as this often depends on hardware
support and other factors.
Location requests that are not batched 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. Out-of-order locations may not be evaluated against other location request constraints, such as the minimum update interval or minimum update distance, due to their out-of-order nature.
public boolean isFastestIntervalExplicitlySet ()
This method is deprecated.
Do not use. May be removed in a future release.
public boolean isPassive ()
True if the priority is Priority.PRIORITY_PASSIVE.
public boolean isWaitForAccurateLocation ()
If this request is
Priority.PRIORITY_HIGH_ACCURACY, this will delay delivery of initial low
accuracy locations for a small amount of time in case a high accuracy location can be
delivered instead.
public LocationRequest setExpirationDuration (long durationMillis)
This method is deprecated.
Use
LocationRequest.Builder.setDurationMillis(long) instead. May be removed in a
future release.
public LocationRequest setExpirationTime (long elapsedRealtime)
This method is deprecated.
Use
LocationRequest.Builder.setDurationMillis(long) instead. Using this method
will express the expiration time in terms of duration, which may give unexpected results.
May be removed in a future release.
public LocationRequest setFastestInterval (long fastestIntervalMillis)
This method is deprecated.
Use
LocationRequest.Builder.setMinUpdateIntervalMillis(long) instead. May be
removed in a future release.
public LocationRequest setInterval (long intervalMillis)
This method is deprecated.
Use
LocationRequest.Builder.setIntervalMillis(long) instead. May be removed in a
future release.
public LocationRequest setMaxWaitTime (long maxWaitTimeMillis)
This method is deprecated.
Use
LocationRequest.Builder.setMaxUpdateDelayMillis(long) instead. May be removed
in a future release.
public LocationRequest setNumUpdates (int maxUpdates)
This method is deprecated.
Use
LocationRequest.Builder.setMaxUpdates(int) instead. May be removed in a future
release.
public LocationRequest setPriority (int priority)
This method is deprecated.
Use
LocationRequest.Builder.setPriority(int) instead. May be removed in a future
release.
public LocationRequest setSmallestDisplacement (float smallestDisplacementMeters)
This method is deprecated.
Use
LocationRequest.Builder.setMinUpdateDistanceMeters(float) instead. May be
removed in a future release.
public LocationRequest setWaitForAccurateLocation (boolean waitForAccurateLocation)
This method is deprecated.
Use
LocationRequest.Builder.setWaitForAccurateLocation(boolean) instead. May be
removed in a future release.