Methods Summary |
---|
private static void | checkDisplacement(float meters)
if (meters < 0.0f) {
throw new IllegalArgumentException("invalid displacement: " + meters);
}
|
private static void | checkInterval(long millis)
if (millis < 0) {
throw new IllegalArgumentException("invalid interval: " + millis);
}
|
private static void | checkProvider(java.lang.String name)
if (name == null) {
throw new IllegalArgumentException("invalid provider: " + name);
}
|
private static void | checkQuality(int quality)
switch (quality) {
case ACCURACY_FINE:
case ACCURACY_BLOCK:
case ACCURACY_CITY:
case POWER_NONE:
case POWER_LOW:
case POWER_HIGH:
break;
default:
throw new IllegalArgumentException("invalid quality: " + quality);
}
|
public static android.location.LocationRequest | create()Create a location request with default parameters.
Default parameters are for a low power, slowly updated location.
It can then be adjusted as required by the applications before passing
to the {@link LocationManager} // for deprecated APIs that explicitly request a provider
LocationRequest request = new LocationRequest();
return request;
|
public static android.location.LocationRequest | createFromDeprecatedCriteria(Criteria criteria, long minTime, float minDistance, boolean singleShot)
if (minTime < 0) minTime = 0;
if (minDistance < 0) minDistance = 0;
int quality;
switch (criteria.getAccuracy()) {
case Criteria.ACCURACY_COARSE:
quality = ACCURACY_BLOCK;
break;
case Criteria.ACCURACY_FINE:
quality = ACCURACY_FINE;
break;
default: {
switch (criteria.getPowerRequirement()) {
case Criteria.POWER_HIGH:
quality = POWER_HIGH;
default:
quality = POWER_LOW;
}
}
}
LocationRequest request = new LocationRequest()
.setQuality(quality)
.setInterval(minTime)
.setFastestInterval(minTime)
.setSmallestDisplacement(minDistance);
if (singleShot) request.setNumUpdates(1);
return request;
|
public static android.location.LocationRequest | createFromDeprecatedProvider(java.lang.String provider, long minTime, float minDistance, boolean singleShot)
if (minTime < 0) minTime = 0;
if (minDistance < 0) minDistance = 0;
int quality;
if (LocationManager.PASSIVE_PROVIDER.equals(provider)) {
quality = POWER_NONE;
} else if (LocationManager.GPS_PROVIDER.equals(provider)) {
quality = ACCURACY_FINE;
} else {
quality = POWER_LOW;
}
LocationRequest request = new LocationRequest()
.setProvider(provider)
.setQuality(quality)
.setInterval(minTime)
.setFastestInterval(minTime)
.setSmallestDisplacement(minDistance);
if (singleShot) request.setNumUpdates(1);
return request;
|
public void | decrementNumUpdates()
if (mNumUpdates != Integer.MAX_VALUE) {
mNumUpdates--;
}
if (mNumUpdates < 0) {
mNumUpdates = 0;
}
|
public int | describeContents()
return 0;
|
public long | getExpireAt()Get the request expiration time, in milliseconds since boot.
This value can be compared to {@link SystemClock#elapsedRealtime} to determine
the time until expiration.
return mExpireAt;
|
public long | getFastestInterval()Get the fastest interval of this request, in milliseconds.
The system will never provide location updates faster
than the minimum of {@link #getFastestInterval} and
{@link #getInterval}.
return mFastestInterval;
|
public boolean | getHideFromAppOps()
return mHideFromAppOps;
|
public long | getInterval()Get the desired interval of this request, in milliseconds.
return mInterval;
|
public int | getNumUpdates()Get the number of updates requested.
By default this is {@link Integer#MAX_VALUE}, which indicates that
locations are updated until the request is explicitly removed.
return mNumUpdates;
|
public java.lang.String | getProvider()
return mProvider;
|
public int | getQuality()Get the quality of the request.
return mQuality;
|
public float | getSmallestDisplacement()
return mSmallestDisplacement;
|
public android.os.WorkSource | getWorkSource()
return mWorkSource;
|
public static java.lang.String | qualityToString(int quality)
switch (quality) {
case ACCURACY_FINE:
return "ACCURACY_FINE";
case ACCURACY_BLOCK:
return "ACCURACY_BLOCK";
case ACCURACY_CITY:
return "ACCURACY_CITY";
case POWER_NONE:
return "POWER_NONE";
case POWER_LOW:
return "POWER_LOW";
case POWER_HIGH:
return "POWER_HIGH";
default:
return "???";
}
|
public android.location.LocationRequest | setExpireAt(long millis)Set the request expiration time, in millisecond since boot.
This expiration time uses the same time base as {@link SystemClock#elapsedRealtime}.
The location manager will automatically stop updates after
the request expires.
The duration includes suspend time. Values before {@link SystemClock#elapsedRealtime}
are allowed, but indicate that the request has already expired.
mExpireAt = millis;
if (mExpireAt < 0) mExpireAt = 0;
return this;
|
public android.location.LocationRequest | setExpireIn(long millis)Set the duration of this request, in milliseconds.
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.
long elapsedRealtime = SystemClock.elapsedRealtime();
// Check for > Long.MAX_VALUE overflow (elapsedRealtime > 0):
if (millis > Long.MAX_VALUE - elapsedRealtime) {
mExpireAt = Long.MAX_VALUE;
} else {
mExpireAt = millis + elapsedRealtime;
}
if (mExpireAt < 0) mExpireAt = 0;
return this;
|
public android.location.LocationRequest | setFastestInterval(long millis)Explicitly set the fastest interval for location updates, in
milliseconds.
This controls the fastest rate at which your application will
receive location updates, which might be faster than
{@link #setInterval} 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 {@link #setInterval}, 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 ({@link #setInterval}).
An interval of 0 is allowed, but not recommended, since
location updates may be extremely fast on future implementations.
If {@link #setFastestInterval} is set slower than {@link #setInterval},
then your effective fastest interval is {@link #setInterval}.
checkInterval(millis);
mExplicitFastestInterval = true;
mFastestInterval = millis;
return this;
|
public void | setHideFromAppOps(boolean hideFromAppOps)Sets whether or not this location request should be hidden from AppOps.
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 {@link android.Manifest.permission#UPDATE_APP_OPS_STATS} permission.
mHideFromAppOps = hideFromAppOps;
|
public android.location.LocationRequest | setInterval(long millis)Set the desired interval for active location updates, in milliseconds.
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 that you will receive
updates can be controlled with {@link #setFastestInterval}.
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.
{@link #setQuality} and {@link #setInterval} are the most important parameters
on a location request.
checkInterval(millis);
mInterval = millis;
if (!mExplicitFastestInterval) {
mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR);
}
return this;
|
public android.location.LocationRequest | setNumUpdates(int numUpdates)Set the number of location updates.
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.
if (numUpdates <= 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates);
mNumUpdates = numUpdates;
return this;
|
public android.location.LocationRequest | setProvider(java.lang.String provider)
checkProvider(provider);
mProvider = provider;
return this;
|
public android.location.LocationRequest | setQuality(int quality)Set the quality of the request.
Use with a accuracy constant such as {@link #ACCURACY_FINE}, or a power
constant such as {@link #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, {@link #ACCURACY_FINE} is more likely
to use GPS, and {@link #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.
{@link #setQuality} and {@link #setInterval} are the most important parameters
on a location request.
checkQuality(quality);
mQuality = quality;
return this;
|
public android.location.LocationRequest | setSmallestDisplacement(float meters)
checkDisplacement(meters);
mSmallestDisplacement = meters;
return this;
|
public void | setWorkSource(android.os.WorkSource workSource)Sets the WorkSource to use for power blaming of this location request.
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 {@link android.Manifest.permission#UPDATE_DEVICE_STATS} permission.
mWorkSource = workSource;
|
public java.lang.String | toString()
StringBuilder s = new StringBuilder();
s.append("Request[").append(qualityToString(mQuality));
if (mProvider != null) s.append(' ").append(mProvider);
if (mQuality != POWER_NONE) {
s.append(" requested=");
TimeUtils.formatDuration(mInterval, s);
}
s.append(" fastest=");
TimeUtils.formatDuration(mFastestInterval, s);
if (mExpireAt != Long.MAX_VALUE) {
long expireIn = mExpireAt - SystemClock.elapsedRealtime();
s.append(" expireIn=");
TimeUtils.formatDuration(expireIn, s);
}
if (mNumUpdates != Integer.MAX_VALUE){
s.append(" num=").append(mNumUpdates);
}
s.append(']");
return s.toString();
|
public void | writeToParcel(android.os.Parcel parcel, int flags)
parcel.writeInt(mQuality);
parcel.writeLong(mFastestInterval);
parcel.writeLong(mInterval);
parcel.writeLong(mExpireAt);
parcel.writeInt(mNumUpdates);
parcel.writeFloat(mSmallestDisplacement);
parcel.writeInt(mHideFromAppOps ? 1 : 0);
parcel.writeString(mProvider);
parcel.writeParcelable(mWorkSource, 0);
|