public final class LocationRequest extends Object implements Parcelable
LocationManager
.
LocationRequest objects are used to request a quality of service for location updates from the Location Manager.
For example, if your application wants high accuracy location
it should create a location request with setQuality(int)
set to
ACCURACY_FINE
or POWER_HIGH
, and it should set
setInterval(long)
to less than one second. This would be
appropriate for mapping applications that are showing your location
in real-time.
At the other extreme, if you want negligible power
impact, but to still receive location updates when available, then use
setQuality(int)
with POWER_NONE
. With this request your
application will not trigger (and therefore will not receive any
power blame) any location updates, but will receive locations
triggered by other applications. This would be appropriate for
applications that have no firm requirement for location, but can
take advantage when available.
In between these two extremes is a very common use-case, where
applications definitely want to receive
updates at a specified interval, and can receive them faster when
available, but still want a low power impact. These applications
should consider POWER_LOW
combined with a faster
setFastestInterval(long)
(such as 1 minute) and a slower
setInterval(long)
(such as 60 minutes). They will only be assigned
power blame for the interval set by setInterval(long)
, but can
still receive locations triggered by other applications at a rate up
to setFastestInterval(long)
. This style of request is appropriate for
many location aware applications, including background usage. Do be
careful to also throttle setFastestInterval(long)
if you perform
heavy-weight work after receiving an update - such as using the network.
Activities should strongly consider removing all location
request when entering the background
(for example at Activity.onPause()
), or
at least swap the request to a larger interval and lower quality.
Future version of the location manager may automatically perform background
throttling on behalf of applications.
Applications cannot specify the exact location sources that are used by Android's Fusion Engine. In fact, the system may have multiple location sources (providers) running and may fuse the results from several sources into a single Location object.
Location requests from applications with
android.Manifest.permission#ACCESS_COARSE_LOCATION
and not
android.Manifest.permission#ACCESS_FINE_LOCATION
will
be automatically throttled to a slower interval, and the location
object will be obfuscated to only show a coarse level of accuracy.
All location requests are considered hints, and you may receive locations that are more accurate, less accurate, and slower than requested.
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static int |
ACCURACY_BLOCK
Used with
setQuality(int) to request "block" level accuracy. |
static int |
ACCURACY_CITY
Used with
setQuality(int) to request "city" level accuracy. |
static int |
ACCURACY_FINE
Used with
setQuality(int) to request the most accurate locations available. |
static Parcelable.Creator<LocationRequest> |
CREATOR |
static int |
POWER_HIGH
Used with
setQuality(int) to allow high power consumption for location. |
static int |
POWER_LOW
Used with
setQuality(int) to request low power impact. |
static int |
POWER_NONE
Used with
setQuality(int) to require no direct power impact (passive locations). |
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_ELIDE_DUPLICATES, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
LocationRequest() |
LocationRequest(LocationRequest src) |
Modifier and Type | Method and Description |
---|---|
static LocationRequest |
create()
Create a location request with default parameters.
|
static LocationRequest |
createFromDeprecatedCriteria(Criteria criteria,
long minTime,
float minDistance,
boolean singleShot) |
static LocationRequest |
createFromDeprecatedProvider(String provider,
long minTime,
float minDistance,
boolean singleShot) |
void |
decrementNumUpdates() |
int |
describeContents()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation.
|
long |
getExpireAt()
Get the request expiration time, in milliseconds since boot.
|
long |
getFastestInterval()
Get the fastest interval of this request, in milliseconds.
|
boolean |
getHideFromAppOps() |
long |
getInterval()
Get the desired interval of this request, in milliseconds.
|
int |
getNumUpdates()
Get the number of updates requested.
|
String |
getProvider() |
int |
getQuality()
Get the quality of the request.
|
float |
getSmallestDisplacement() |
WorkSource |
getWorkSource() |
static String |
qualityToString(int quality) |
LocationRequest |
setExpireAt(long millis)
Set the request expiration time, in millisecond since boot.
|
LocationRequest |
setExpireIn(long millis)
Set the duration of this request, in milliseconds.
|
LocationRequest |
setFastestInterval(long millis)
Explicitly set the fastest interval for location updates, in
milliseconds.
|
void |
setHideFromAppOps(boolean hideFromAppOps)
Sets whether or not this location request should be hidden from AppOps.
|
LocationRequest |
setInterval(long millis)
Set the desired interval for active location updates, in milliseconds.
|
LocationRequest |
setNumUpdates(int numUpdates)
Set the number of location updates.
|
LocationRequest |
setProvider(String provider) |
LocationRequest |
setQuality(int quality)
Set the quality of the request.
|
LocationRequest |
setSmallestDisplacement(float meters) |
void |
setWorkSource(WorkSource workSource)
Sets the WorkSource to use for power blaming of this location request.
|
String |
toString()
Returns a string representation of the object.
|
void |
writeToParcel(Parcel parcel,
int flags)
Flatten this object in to a Parcel.
|
public static final int ACCURACY_FINE
setQuality(int)
to request the most accurate locations available.
This may be up to 1 meter accuracy, although this is implementation dependent.
public static final int ACCURACY_BLOCK
setQuality(int)
to request "block" level accuracy.
Block level accuracy is considered to be about 100 meter accuracy, although this is implementation dependent. Using a coarse accuracy such as this often consumes less power.
public static final int ACCURACY_CITY
setQuality(int)
to request "city" level accuracy.
City level accuracy is considered to be about 10km accuracy, although this is implementation dependent. Using a coarse accuracy such as this often consumes less power.
public static final int POWER_NONE
setQuality(int)
to require no direct power impact (passive locations).
This location request will not trigger any active location requests, but will receive locations triggered by other applications. Your application will not receive any direct power blame for location work.
public static final int POWER_LOW
setQuality(int)
to request low power impact.
This location request will avoid high power location work where possible.
public static final int POWER_HIGH
setQuality(int)
to allow high power consumption for location.
This location request will allow high power location work.
public static final Parcelable.Creator<LocationRequest> CREATOR
public LocationRequest()
public LocationRequest(LocationRequest src)
public static LocationRequest create()
Default parameters are for a low power, slowly updated location.
It can then be adjusted as required by the applications before passing
to the LocationManager
public static LocationRequest createFromDeprecatedProvider(String provider, long minTime, float minDistance, boolean singleShot)
public static LocationRequest createFromDeprecatedCriteria(Criteria criteria, long minTime, float minDistance, boolean singleShot)
public LocationRequest setQuality(int quality)
Use with a accuracy constant such as ACCURACY_FINE
, or a power
constant such as POWER_LOW
. You cannot request both and accuracy and
power, only one or the other can be specified. The system will then
maximize accuracy or minimize power as appropriate.
The quality of the request is a strong hint to the system for which
location sources to use. For example, ACCURACY_FINE
is more likely
to use GPS, and POWER_LOW
is more likely to use WIFI & Cell tower
positioning, but it also depends on many other factors (such as which sources
are available) and is implementation dependent.
setQuality(int)
and setInterval(long)
are the most important parameters
on a location request.
quality
- an accuracy or power constantInvalidArgumentException
- if the quality constant is not validpublic int getQuality()
public LocationRequest setInterval(long millis)
The location manager will actively try to obtain location updates for your application at this interval, so it has a direct influence on the amount of power used by your application. Choose your interval wisely.
This interval is inexact. You may not receive updates at all (if
no location sources are available), or you may receive them
slower than requested. You may also receive them faster than
requested (if other applications are requesting location at a
faster interval). The fastest rate that you will receive
updates can be controlled with setFastestInterval(long)
.
Applications with only the coarse location permission may have their interval silently throttled.
An interval of 0 is allowed, but not recommended, since location updates may be extremely fast on future implementations.
setQuality(int)
and setInterval(long)
are the most important parameters
on a location request.
millis
- desired interval in millisecond, inexactInvalidArgumentException
- if the interval is less than zeropublic long getInterval()
public LocationRequest setFastestInterval(long millis)
This controls the fastest rate at which your application will
receive location updates, which might be faster than
setInterval(long)
in some situations (for example, if other
applications are triggering location updates).
This allows your application to passively acquire locations at a rate faster than it actively acquires locations, saving power.
Unlike setInterval(long)
, this parameter is exact. Your
application will never receive updates faster than this value.
If you don't call this method, a fastest interval
will be selected for you. It will be a value faster than your
active interval (setInterval(long)
).
An interval of 0 is allowed, but not recommended, since location updates may be extremely fast on future implementations.
If setFastestInterval(long)
is set slower than setInterval(long)
,
then your effective fastest interval is setInterval(long)
.
millis
- fastest interval for updates in milliseconds, exactInvalidArgumentException
- if the interval is less than zeropublic long getFastestInterval()
The system will never provide location updates faster
than the minimum of getFastestInterval()
and
getInterval()
.
public LocationRequest setExpireIn(long millis)
The duration begins immediately (and not when the request is passed to the location manager), so call this method again if the request is re-used at a later time.
The location manager will automatically stop updates after the request expires.
The duration includes suspend time. Values less than 0 are allowed, but indicate that the request has already expired.
millis
- duration of request in millisecondspublic LocationRequest setExpireAt(long millis)
This expiration time uses the same time base as SystemClock.elapsedRealtime()
.
The location manager will automatically stop updates after the request expires.
The duration includes suspend time. Values before SystemClock.elapsedRealtime()
are allowed, but indicate that the request has already expired.
millis
- expiration time of request, in milliseconds since boot including suspendpublic long getExpireAt()
This value can be compared to SystemClock.elapsedRealtime()
to determine
the time until expiration.
public LocationRequest setNumUpdates(int numUpdates)
By default locations are continuously updated until the request is explicitly removed, however you can optionally request a set number of updates. For example, if your application only needs a single fresh location, then call this method with a value of 1 before passing the request to the location manager.
numUpdates
- the number of location updates requestedInvalidArgumentException
- if numUpdates is 0 or lesspublic int getNumUpdates()
By default this is Integer.MAX_VALUE
, which indicates that
locations are updated until the request is explicitly removed.
public void decrementNumUpdates()
public LocationRequest setProvider(String provider)
public String getProvider()
public LocationRequest setSmallestDisplacement(float meters)
public float getSmallestDisplacement()
public void setWorkSource(WorkSource workSource)
No permissions are required to make this call, however the LocationManager
will throw a SecurityException when requesting location updates if the caller
doesn't have the android.Manifest.permission#UPDATE_DEVICE_STATS
permission.
workSource
- WorkSource defining power blame for this location request.public WorkSource getWorkSource()
public void setHideFromAppOps(boolean hideFromAppOps)
Hiding a location request from AppOps will remove user visibility in the UI as to this request's existence. It does not affect power blaming in the Battery page.
No permissions are required to make this call, however the LocationManager
will throw a SecurityException when requesting location updates if the caller
doesn't have the android.Manifest.permission#UPDATE_APP_OPS_STATS
permission.
hideFromAppOps
- If true AppOps won't keep track of this location request.AppOpsManager
public boolean getHideFromAppOps()
public int describeContents()
Parcelable
Parcelable.writeToParcel(Parcel, int)
,
the return value of this method must include the
Parcelable.CONTENTS_FILE_DESCRIPTOR
bit.describeContents
in interface Parcelable
Parcelable.CONTENTS_FILE_DESCRIPTOR
public void writeToParcel(Parcel parcel, int flags)
Parcelable
writeToParcel
in interface Parcelable
parcel
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.public static String qualityToString(int quality)
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())