File	Doc	Category	Size	Date	Package
LocationRequest.java	API Doc	Android 5.1 API	24600	Thu Mar 12 22:22:30 GMT 2015	android.location

LocationRequest

• java.lang.Object

Fields Summary
public static final int	ACCURACY_FINE Used with {@link #setQuality} 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 Used with {@link #setQuality} 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 Used with {@link #setQuality} 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 Used with {@link #setQuality} 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 Used with {@link #setQuality} to request low power impact. This location request will avoid high power location work where possible.
public static final int	POWER_HIGH Used with {@link #setQuality} to allow high power consumption for location. This location request will allow high power location work.
private static final double	FASTEST_INTERVAL_FACTOR By default, mFastestInterval = FASTEST_INTERVAL_MULTIPLE * mInterval
private int	mQuality
private long	mInterval
private long	mFastestInterval
private boolean	mExplicitFastestInterval
private long	mExpireAt
private int	mNumUpdates
private float	mSmallestDisplacement
private android.os.WorkSource	mWorkSource
private boolean	mHideFromAppOps
private String	mProvider
public static final Parcelable.Creator	CREATOR

Constructors Summary
public LocationRequest() hide
public LocationRequest(LocationRequest src) hide mQuality = src.mQuality; mInterval = src.mInterval; mFastestInterval = src.mFastestInterval; mExplicitFastestInterval = src.mExplicitFastestInterval; mExpireAt = src.mExpireAt; mNumUpdates = src.mNumUpdates; mSmallestDisplacement = src.mSmallestDisplacement; mProvider = src.mProvider; mWorkSource = src.mWorkSource; mHideFromAppOps = src.mHideFromAppOps;

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} return a new location request // 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) hide 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) hide 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() hide 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 expiration time of request, in milliseconds since boot including suspend 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 fastest interval in milliseconds, exact return mFastestInterval;
public boolean	getHideFromAppOps() hide return mHideFromAppOps;
public long	getInterval() Get the desired interval of this request, in milliseconds. return desired interval in milliseconds, inexact 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 number of updates return mNumUpdates;
public java.lang.String	getProvider() hide return mProvider;
public int	getQuality() Get the quality of the request. return an accuracy or power constant return mQuality;
public float	getSmallestDisplacement() hide return mSmallestDisplacement;
public android.os.WorkSource	getWorkSource() hide return mWorkSource;
public static java.lang.String	qualityToString(int quality) hide 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. param millis expiration time of request, in milliseconds since boot including suspend return the same object, so that setters can be chained 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. param millis duration of request in milliseconds return the same object, so that setters can be chained 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}. param millis fastest interval for updates in milliseconds, exact throws InvalidArgumentException if the interval is less than zero return the same object, so that setters can be chained 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. param hideFromAppOps If true AppOps won't keep track of this location request. see android.app.AppOpsManager hide 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. param millis desired interval in millisecond, inexact throws InvalidArgumentException if the interval is less than zero return the same object, so that setters can be chained 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. param numUpdates the number of location updates requested throws InvalidArgumentException if numUpdates is 0 or less return the same object, so that setters can be chained if (numUpdates <= 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates); mNumUpdates = numUpdates; return this;
public android.location.LocationRequest	setProvider(java.lang.String provider) hide 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. param quality an accuracy or power constant throws InvalidArgumentException if the quality constant is not valid return the same object, so that setters can be chained checkQuality(quality); mQuality = quality; return this;
public android.location.LocationRequest	setSmallestDisplacement(float meters) hide 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. param workSource WorkSource defining power blame for this location request. hide 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);