| /* |
| * Copyright (C) 2012 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.location; |
| |
| import static android.Manifest.permission.LOCATION_BYPASS; |
| |
| import static java.lang.Math.max; |
| import static java.lang.Math.min; |
| |
| import android.Manifest; |
| import android.annotation.FloatRange; |
| import android.annotation.IntDef; |
| import android.annotation.IntRange; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.RequiresFeature; |
| import android.annotation.RequiresPermission; |
| import android.annotation.SystemApi; |
| import android.compat.annotation.ChangeId; |
| import android.compat.annotation.EnabledAfter; |
| import android.content.pm.PackageManager; |
| import android.os.Build; |
| import android.os.Parcel; |
| import android.os.Parcelable; |
| import android.os.WorkSource; |
| import android.util.TimeUtils; |
| |
| import com.android.internal.util.Preconditions; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.util.Objects; |
| |
| |
| /** |
| * An encapsulation of various parameters for requesting location via {@link LocationManager}. |
| */ |
| public final class LocationRequest implements Parcelable { |
| |
| /** |
| * For apps targeting Android S and above, all LocationRequest objects marked as low power will |
| * throw exceptions if the caller does not have the LOCATION_HARDWARE permission, instead of |
| * silently dropping the low power part of the request. |
| * |
| * @hide |
| */ |
| @ChangeId |
| @EnabledAfter(targetSdkVersion = Build.VERSION_CODES.R) |
| public static final long LOW_POWER_EXCEPTIONS = 168936375L; |
| |
| /** |
| * Represents a passive only request. Such a request will not trigger any active locations or |
| * power usage itself, but may receive locations generated in response to other requests. |
| * |
| * @see LocationRequest#getIntervalMillis() |
| */ |
| public static final long PASSIVE_INTERVAL = Long.MAX_VALUE; |
| |
| /** @hide */ |
| @Retention(RetentionPolicy.SOURCE) |
| @IntDef({QUALITY_LOW_POWER, QUALITY_BALANCED_POWER_ACCURACY, QUALITY_HIGH_ACCURACY}) |
| public @interface Quality {} |
| |
| /** |
| * A quality constant indicating a location provider may choose to satisfy this request by |
| * providing very accurate locations at the expense of potentially increased power usage. Each |
| * location provider may interpret this field differently, but as an example, the network |
| * provider may choose to return only wifi based locations rather than cell based locations in |
| * order to have greater accuracy when this flag is present. |
| */ |
| public static final int QUALITY_HIGH_ACCURACY = 100; |
| |
| /** |
| * A quality constant indicating a location provider may choose to satisfy this request by |
| * equally balancing power and accuracy constraints. Each location provider may interpret this |
| * field differently, but location providers will generally use their default behavior when this |
| * flag is present. |
| */ |
| public static final int QUALITY_BALANCED_POWER_ACCURACY = 102; |
| |
| /** |
| * A quality constant indicating a location provider may choose to satisfy this request by |
| * providing less accurate locations in order to save power. Each location provider may |
| * interpret this field differently, but as an example, the network provider may choose to |
| * return cell based locations rather than wifi based locations in order to save power when this |
| * flag is present. |
| */ |
| public static final int QUALITY_LOW_POWER = 104; |
| |
| /** |
| * Used with {@link #setQuality} to request the most accurate locations available. |
| * |
| * <p>This may be up to 1 meter accuracy, although this is implementation dependent. |
| * |
| * @hide |
| * @deprecated Use {@link #QUALITY_HIGH_ACCURACY} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public static final int ACCURACY_FINE = QUALITY_HIGH_ACCURACY; |
| |
| /** |
| * Used with {@link #setQuality} to request "block" level accuracy. |
| * |
| * <p>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. |
| * |
| * @hide |
| * @deprecated Use {@link #QUALITY_BALANCED_POWER_ACCURACY} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public static final int ACCURACY_BLOCK = QUALITY_BALANCED_POWER_ACCURACY; |
| |
| /** |
| * Used with {@link #setQuality} to request "city" level accuracy. |
| * |
| * <p>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. |
| * |
| * @hide |
| * @deprecated Use {@link #QUALITY_LOW_POWER} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public static final int ACCURACY_CITY = QUALITY_LOW_POWER; |
| |
| /** |
| * Used with {@link #setQuality} to require no direct power impact (passive locations). |
| * |
| * <p>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. |
| * |
| * @hide |
| * @deprecated Use {@link #PASSIVE_INTERVAL} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public static final int POWER_NONE = 200; |
| |
| /** |
| * Used with {@link #setQuality} to request low power impact. |
| * |
| * <p>This location request will avoid high power location work where |
| * possible. |
| * |
| * @hide |
| * @deprecated Use {@link #QUALITY_LOW_POWER} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public static final int POWER_LOW = 201; |
| |
| /** |
| * Used with {@link #setQuality} to allow high power consumption for location. |
| * |
| * <p>This location request will allow high power location work. |
| * |
| * @hide |
| * @deprecated Use {@link #QUALITY_HIGH_ACCURACY} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public static final int POWER_HIGH = 203; |
| |
| private static final long IMPLICIT_MIN_UPDATE_INTERVAL = -1; |
| private static final double IMPLICIT_MIN_UPDATE_INTERVAL_FACTOR = 1D / 6D; |
| |
| private @Nullable String mProvider; |
| private @Quality int mQuality; |
| private long mIntervalMillis; |
| private long mMinUpdateIntervalMillis; |
| private long mExpireAtRealtimeMillis; |
| private long mDurationMillis; |
| private int mMaxUpdates; |
| private float mMinUpdateDistanceMeters; |
| private final long mMaxUpdateDelayMillis; |
| private boolean mHideFromAppOps; |
| private final boolean mAdasGnssBypass; |
| private boolean mBypass; |
| private boolean mLowPower; |
| private @Nullable WorkSource mWorkSource; |
| |
| /** |
| * @hide |
| * @deprecated Use the Builder to construct new LocationRequests. |
| */ |
| @SystemApi |
| @Deprecated |
| @NonNull |
| public static LocationRequest create() { |
| // 60 minutes is the default legacy interval |
| return new LocationRequest.Builder(60 * 60 * 1000).build(); |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use the Builder to construct new LocationRequests. |
| */ |
| @SystemApi |
| @Deprecated |
| @NonNull |
| public static LocationRequest createFromDeprecatedProvider(@NonNull String provider, |
| long intervalMillis, float minUpdateDistanceMeters, boolean singleShot) { |
| Preconditions.checkArgument(provider != null, "invalid null provider"); |
| |
| if (intervalMillis < 0) { |
| intervalMillis = 0; |
| } else if (intervalMillis == PASSIVE_INTERVAL) { |
| intervalMillis = Long.MAX_VALUE - 1; |
| } |
| if (minUpdateDistanceMeters < 0) { |
| minUpdateDistanceMeters = 0; |
| } |
| |
| int quality; |
| if (LocationManager.PASSIVE_PROVIDER.equals(provider)) { |
| quality = POWER_NONE; |
| } else if (LocationManager.GPS_PROVIDER.equals(provider)) { |
| quality = QUALITY_HIGH_ACCURACY; |
| } else { |
| quality = QUALITY_BALANCED_POWER_ACCURACY; |
| } |
| |
| return new LocationRequest.Builder(intervalMillis) |
| .setMinUpdateIntervalMillis(intervalMillis) |
| .setMinUpdateDistanceMeters(minUpdateDistanceMeters) |
| .setMaxUpdates(singleShot ? 1 : Integer.MAX_VALUE) |
| .build() |
| .setProvider(provider) |
| .setQuality(quality); |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use the Builder to construct new LocationRequests. |
| */ |
| @SystemApi |
| @Deprecated |
| @NonNull |
| public static LocationRequest createFromDeprecatedCriteria(@NonNull Criteria criteria, |
| long intervalMillis, float minUpdateDistanceMeters, boolean singleShot) { |
| Preconditions.checkArgument(criteria != null, "invalid null criteria"); |
| |
| if (intervalMillis < 0) { |
| intervalMillis = 0; |
| } else if (intervalMillis == PASSIVE_INTERVAL) { |
| intervalMillis = Long.MAX_VALUE - 1; |
| } |
| if (minUpdateDistanceMeters < 0) { |
| minUpdateDistanceMeters = 0; |
| } |
| |
| return new LocationRequest.Builder(intervalMillis) |
| .setQuality(criteria) |
| .setMinUpdateIntervalMillis(intervalMillis) |
| .setMinUpdateDistanceMeters(minUpdateDistanceMeters) |
| .setMaxUpdates(singleShot ? 1 : Integer.MAX_VALUE) |
| .build(); |
| } |
| |
| private LocationRequest( |
| @Nullable String provider, |
| long intervalMillis, |
| @Quality int quality, |
| long expireAtRealtimeMillis, |
| long durationMillis, |
| int maxUpdates, |
| long minUpdateIntervalMillis, |
| float minUpdateDistanceMeters, |
| long maxUpdateDelayMillis, |
| boolean hiddenFromAppOps, |
| boolean adasGnssBypass, |
| boolean bypass, |
| boolean lowPower, |
| WorkSource workSource) { |
| mProvider = provider; |
| mIntervalMillis = intervalMillis; |
| mQuality = quality; |
| mMinUpdateIntervalMillis = minUpdateIntervalMillis; |
| mExpireAtRealtimeMillis = expireAtRealtimeMillis; |
| mDurationMillis = durationMillis; |
| mMaxUpdates = maxUpdates; |
| mMinUpdateDistanceMeters = minUpdateDistanceMeters; |
| mMaxUpdateDelayMillis = maxUpdateDelayMillis; |
| mHideFromAppOps = hiddenFromAppOps; |
| mAdasGnssBypass = adasGnssBypass; |
| mBypass = bypass; |
| mLowPower = lowPower; |
| mWorkSource = Objects.requireNonNull(workSource); |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setProvider(@NonNull String provider) { |
| Preconditions.checkArgument(provider != null); |
| mProvider = provider; |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Providers are no longer an explicit part of a location request. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull String getProvider() { |
| return mProvider != null ? mProvider : LocationManager.FUSED_PROVIDER; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setQuality(int quality) { |
| switch (quality) { |
| case POWER_HIGH: |
| // fall through |
| case QUALITY_HIGH_ACCURACY: |
| mQuality = QUALITY_HIGH_ACCURACY; |
| break; |
| case QUALITY_BALANCED_POWER_ACCURACY: |
| mQuality = QUALITY_BALANCED_POWER_ACCURACY; |
| break; |
| case POWER_LOW: |
| // fall through |
| case QUALITY_LOW_POWER: |
| mQuality = QUALITY_LOW_POWER; |
| break; |
| case POWER_NONE: |
| mIntervalMillis = PASSIVE_INTERVAL; |
| break; |
| default: |
| throw new IllegalArgumentException("invalid quality: " + quality); |
| } |
| |
| return this; |
| } |
| |
| /** |
| * Returns the quality hint for this location request. The quality hint informs the provider how |
| * it should attempt to manage any accuracy vs power tradeoffs while attempting to satisfy this |
| * location request. |
| * |
| * @return the desired quality tradeoffs between accuracy and power |
| */ |
| public @Quality int getQuality() { |
| return mQuality; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setInterval(long millis) { |
| Preconditions.checkArgument(millis >= 0); |
| |
| // legacy clients don't know about the passive interval |
| if (millis == PASSIVE_INTERVAL) { |
| millis = Long.MAX_VALUE - 1; |
| } |
| |
| mIntervalMillis = millis; |
| if (mMinUpdateIntervalMillis > mIntervalMillis) { |
| mMinUpdateIntervalMillis = mIntervalMillis; |
| } |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #getIntervalMillis()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public long getInterval() { |
| return getIntervalMillis(); |
| } |
| |
| /** |
| * Returns the desired interval of location updates, or {@link #PASSIVE_INTERVAL} if this is a |
| * passive, no power request. A passive request will not actively generate location updates |
| * (and thus will not be power blamed for location), but may receive location updates generated |
| * as a result of other location requests. A passive request must always have an explicit |
| * minimum update interval set. |
| * |
| * <p>Locations may be available at a faster interval than specified here, see |
| * {@link #getMinUpdateIntervalMillis()} for the behavior in that case. |
| * |
| * @return the desired interval of location updates |
| */ |
| public @IntRange(from = 0) long getIntervalMillis() { |
| return mIntervalMillis; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setFastestInterval(long millis) { |
| Preconditions.checkArgument(millis >= 0); |
| mMinUpdateIntervalMillis = millis; |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #getMinUpdateIntervalMillis()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public long getFastestInterval() { |
| return getMinUpdateIntervalMillis(); |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setExpireAt(long millis) { |
| mExpireAtRealtimeMillis = max(millis, 0); |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Prefer {@link #getDurationMillis()} where possible. |
| */ |
| @SystemApi |
| @Deprecated |
| public long getExpireAt() { |
| return mExpireAtRealtimeMillis; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setExpireIn(long millis) { |
| mDurationMillis = millis; |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #getDurationMillis()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public long getExpireIn() { |
| return getDurationMillis(); |
| } |
| |
| /** |
| * Returns the duration for which location will be provided before the request is automatically |
| * removed. A duration of <code>Long.MAX_VALUE</code> represents an unlimited duration. |
| * |
| * @return the duration for which location will be provided |
| */ |
| public @IntRange(from = 1) long getDurationMillis() { |
| return mDurationMillis; |
| } |
| |
| /** |
| * @hide |
| */ |
| public long getExpirationRealtimeMs(long startRealtimeMs) { |
| long expirationRealtimeMs; |
| // Check for > Long.MAX_VALUE overflow (elapsedRealtime > 0): |
| if (mDurationMillis > Long.MAX_VALUE - startRealtimeMs) { |
| expirationRealtimeMs = Long.MAX_VALUE; |
| } else { |
| expirationRealtimeMs = startRealtimeMs + mDurationMillis; |
| } |
| return min(expirationRealtimeMs, mExpireAtRealtimeMillis); |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setNumUpdates(int numUpdates) { |
| if (numUpdates <= 0) { |
| throw new IllegalArgumentException( |
| "invalid numUpdates: " + numUpdates); |
| } |
| mMaxUpdates = numUpdates; |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #getMaxUpdates()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public int getNumUpdates() { |
| return getMaxUpdates(); |
| } |
| |
| /** |
| * Returns the maximum number of location updates for this request before the request is |
| * automatically removed. A max updates value of <code>Integer.MAX_VALUE</code> represents an |
| * unlimited number of updates. |
| */ |
| public @IntRange(from = 1, to = Integer.MAX_VALUE) int getMaxUpdates() { |
| return mMaxUpdates; |
| } |
| |
| /** |
| * Returns the minimum update interval. If location updates are available faster than the |
| * request interval then locations will only be updated if the minimum update interval has |
| * expired since the last location update. |
| * |
| * <p class=note><strong>Note:</strong> Some allowance for jitter is already built into the |
| * minimum update interval, so you need not worry about updates blocked simply because they |
| * arrived a fraction of a second earlier than expected. |
| * |
| * @return the minimum update interval |
| */ |
| public @IntRange(from = 0) long getMinUpdateIntervalMillis() { |
| if (mMinUpdateIntervalMillis == IMPLICIT_MIN_UPDATE_INTERVAL) { |
| return (long) (mIntervalMillis * IMPLICIT_MIN_UPDATE_INTERVAL_FACTOR); |
| } else { |
| // the min is only necessary in case someone use a deprecated function to mess with the |
| // interval or min update interval |
| return min(mMinUpdateIntervalMillis, mIntervalMillis); |
| } |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setSmallestDisplacement(float minDisplacementMeters) { |
| mMinUpdateDistanceMeters = Preconditions.checkArgumentInRange(minDisplacementMeters, 0, |
| Float.MAX_VALUE, "minDisplacementMeters"); |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #getMinUpdateDistanceMeters()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public float getSmallestDisplacement() { |
| return getMinUpdateDistanceMeters(); |
| } |
| |
| /** |
| * Returns the minimum distance between location updates. If a potential location update is |
| * closer to the last location update than the minimum update distance, then the potential |
| * location update will not occur. A value of 0 meters implies that no location update will ever |
| * be rejected due to failing this constraint. |
| * |
| * @return the minimum distance between location updates |
| */ |
| public @FloatRange(from = 0, to = Float.MAX_VALUE) float getMinUpdateDistanceMeters() { |
| return mMinUpdateDistanceMeters; |
| } |
| |
| /** |
| * Returns the maximum time any location update may be delayed, and thus grouped with following |
| * updates to enable location batching. If the maximum update delay is equal to or greater than |
| * twice the interval, then location providers may provide batched results. The maximum batch |
| * size is the maximum update delay divided by the interval. Not all devices or location |
| * providers support batching, and use of this parameter does not guarantee that the client will |
| * see batched results, or that batched results will always be of the maximum size. |
| * |
| * When available, batching can provide substantial power savings to the device, and clients are |
| * encouraged to take advantage where appropriate for the use case. |
| * |
| * @see LocationListener#onLocationChanged(java.util.List) |
| * @return the maximum time by which a location update may be delayed |
| */ |
| public @IntRange(from = 0) long getMaxUpdateDelayMillis() { |
| return mMaxUpdateDelayMillis; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public void setHideFromAppOps(boolean hiddenFromAppOps) { |
| mHideFromAppOps = hiddenFromAppOps; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #isHiddenFromAppOps()} instead. |
| */ |
| @SystemApi |
| @Deprecated |
| public boolean getHideFromAppOps() { |
| return isHiddenFromAppOps(); |
| } |
| |
| /** |
| * Returns true if this request should be ignored while updating app ops with location usage. |
| * This implies that someone else (usually the creator of the location request) is responsible |
| * for updating app ops. |
| * |
| * @return true if this request should be ignored while updating app ops with location usage |
| * |
| * @hide |
| */ |
| @SystemApi |
| public boolean isHiddenFromAppOps() { |
| return mHideFromAppOps; |
| } |
| |
| /** |
| * Returns true if this request may access GNSS even if location settings would normally deny |
| * this, in order to enable automotive safety features. This field is only respected on |
| * automotive devices, and only if the client is recognized as a legitimate ADAS (Advanced |
| * Driving Assistance Systems) application. |
| * |
| * @return true if all limiting factors will be ignored to satisfy GNSS request |
| * |
| * @hide |
| */ |
| @SystemApi |
| public boolean isAdasGnssBypass() { |
| return mAdasGnssBypass; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| @RequiresPermission(LOCATION_BYPASS) |
| public @NonNull LocationRequest setLocationSettingsIgnored(boolean locationSettingsIgnored) { |
| mBypass = locationSettingsIgnored; |
| return this; |
| } |
| |
| /** |
| * Returns true if location settings, throttling, background location limits, and any other |
| * possible limiting factors will be ignored in order to satisfy this request. |
| * |
| * @return true if all limiting factors will be ignored to satisfy this request |
| * |
| * @hide |
| */ |
| @SystemApi |
| public boolean isLocationSettingsIgnored() { |
| return mBypass; |
| } |
| |
| /** |
| * Returns true if any bypass flag is set on this request. For internal use only. |
| * |
| * @hide |
| */ |
| public boolean isBypass() { |
| return mAdasGnssBypass || mBypass; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public @NonNull LocationRequest setLowPowerMode(boolean enabled) { |
| mLowPower = enabled; |
| return this; |
| } |
| |
| /** |
| * @hide |
| * @deprecated Use {@link #isLowPower()} instead. |
| */ |
| @Deprecated |
| @SystemApi |
| public boolean isLowPowerMode() { |
| return isLowPower(); |
| } |
| |
| /** |
| * Returns true if extreme trade-offs should be made to save power for this request. This |
| * usually involves specialized hardware modes which can greatly affect the quality of |
| * locations. |
| * |
| * @return true if extreme trade-offs should be made to save power for this request |
| * |
| * @hide |
| */ |
| @SystemApi |
| public boolean isLowPower() { |
| return mLowPower; |
| } |
| |
| /** |
| * @hide |
| * @deprecated LocationRequests should be treated as immutable. |
| */ |
| @SystemApi |
| @Deprecated |
| public void setWorkSource(@Nullable WorkSource workSource) { |
| if (workSource == null) { |
| workSource = new WorkSource(); |
| } |
| mWorkSource = workSource; |
| } |
| |
| /** |
| * Returns the work source used for power blame for this request. If empty, the system is free |
| * to assign power blame as it deems most appropriate. |
| * |
| * @return the work source used for power blame for this request |
| * |
| * @hide |
| */ |
| @SystemApi |
| public @NonNull WorkSource getWorkSource() { |
| return mWorkSource; |
| } |
| |
| |
| public static final @NonNull Parcelable.Creator<LocationRequest> CREATOR = |
| new Parcelable.Creator<LocationRequest>() { |
| @Override |
| public LocationRequest createFromParcel(Parcel in) { |
| return new LocationRequest( |
| /* provider= */ in.readString(), |
| /* intervalMillis= */ in.readLong(), |
| /* quality= */ in.readInt(), |
| /* expireAtRealtimeMillis= */ in.readLong(), |
| /* durationMillis= */ in.readLong(), |
| /* maxUpdates= */ in.readInt(), |
| /* minUpdateIntervalMillis= */ in.readLong(), |
| /* minUpdateDistanceMeters= */ in.readFloat(), |
| /* maxUpdateDelayMillis= */ in.readLong(), |
| /* hiddenFromAppOps= */ in.readBoolean(), |
| /* adasGnssBypass= */ in.readBoolean(), |
| /* locationSettingsIgnored= */ in.readBoolean(), |
| /* lowPower= */ in.readBoolean(), |
| /* workSource= */ in.readTypedObject(WorkSource.CREATOR)); |
| } |
| |
| @Override |
| public LocationRequest[] newArray(int size) { |
| return new LocationRequest[size]; |
| } |
| }; |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(@NonNull Parcel parcel, int flags) { |
| parcel.writeString(mProvider); |
| parcel.writeLong(mIntervalMillis); |
| parcel.writeInt(mQuality); |
| parcel.writeLong(mExpireAtRealtimeMillis); |
| parcel.writeLong(mDurationMillis); |
| parcel.writeInt(mMaxUpdates); |
| parcel.writeLong(mMinUpdateIntervalMillis); |
| parcel.writeFloat(mMinUpdateDistanceMeters); |
| parcel.writeLong(mMaxUpdateDelayMillis); |
| parcel.writeBoolean(mHideFromAppOps); |
| parcel.writeBoolean(mAdasGnssBypass); |
| parcel.writeBoolean(mBypass); |
| parcel.writeBoolean(mLowPower); |
| parcel.writeTypedObject(mWorkSource, 0); |
| } |
| |
| @Override |
| public boolean equals(Object o) { |
| if (this == o) { |
| return true; |
| } |
| if (o == null || getClass() != o.getClass()) { |
| return false; |
| } |
| |
| LocationRequest that = (LocationRequest) o; |
| return mIntervalMillis == that.mIntervalMillis |
| && mQuality == that.mQuality |
| && mExpireAtRealtimeMillis == that.mExpireAtRealtimeMillis |
| && mDurationMillis == that.mDurationMillis |
| && mMaxUpdates == that.mMaxUpdates |
| && mMinUpdateIntervalMillis == that.mMinUpdateIntervalMillis |
| && Float.compare(that.mMinUpdateDistanceMeters, mMinUpdateDistanceMeters) == 0 |
| && mMaxUpdateDelayMillis == that.mMaxUpdateDelayMillis |
| && mHideFromAppOps == that.mHideFromAppOps |
| && mAdasGnssBypass == that.mAdasGnssBypass |
| && mBypass == that.mBypass |
| && mLowPower == that.mLowPower |
| && Objects.equals(mProvider, that.mProvider) |
| && Objects.equals(mWorkSource, that.mWorkSource); |
| } |
| |
| @Override |
| public int hashCode() { |
| return Objects.hash(mProvider, mIntervalMillis, mWorkSource); |
| } |
| |
| @NonNull |
| @Override |
| public String toString() { |
| StringBuilder s = new StringBuilder(); |
| s.append("Request["); |
| if (mProvider != null) { |
| s.append(mProvider).append(" "); |
| } |
| if (mIntervalMillis != PASSIVE_INTERVAL) { |
| s.append("@"); |
| TimeUtils.formatDuration(mIntervalMillis, s); |
| |
| switch (mQuality) { |
| case QUALITY_HIGH_ACCURACY: |
| s.append(" HIGH_ACCURACY"); |
| break; |
| case QUALITY_BALANCED_POWER_ACCURACY: |
| s.append(" BALANCED"); |
| break; |
| case QUALITY_LOW_POWER: |
| s.append(" LOW_POWER"); |
| break; |
| } |
| } else { |
| s.append("PASSIVE"); |
| } |
| if (mExpireAtRealtimeMillis != Long.MAX_VALUE) { |
| s.append(", expireAt=").append(TimeUtils.formatRealtime(mExpireAtRealtimeMillis)); |
| } |
| if (mDurationMillis != Long.MAX_VALUE) { |
| s.append(", duration="); |
| TimeUtils.formatDuration(mDurationMillis, s); |
| } |
| if (mMaxUpdates != Integer.MAX_VALUE) { |
| s.append(", maxUpdates=").append(mMaxUpdates); |
| } |
| if (mMinUpdateIntervalMillis != IMPLICIT_MIN_UPDATE_INTERVAL |
| && mMinUpdateIntervalMillis < mIntervalMillis) { |
| s.append(", minUpdateInterval="); |
| TimeUtils.formatDuration(mMinUpdateIntervalMillis, s); |
| } |
| if (mMinUpdateDistanceMeters > 0.0) { |
| s.append(", minUpdateDistance=").append(mMinUpdateDistanceMeters); |
| } |
| if (mMaxUpdateDelayMillis / 2 > mIntervalMillis) { |
| s.append(", maxUpdateDelay="); |
| TimeUtils.formatDuration(mMaxUpdateDelayMillis, s); |
| } |
| if (mLowPower) { |
| s.append(", lowPower"); |
| } |
| if (mHideFromAppOps) { |
| s.append(", hiddenFromAppOps"); |
| } |
| if (mAdasGnssBypass) { |
| s.append(", adasGnssBypass"); |
| } |
| if (mBypass) { |
| s.append(", bypass"); |
| } |
| if (mWorkSource != null && !mWorkSource.isEmpty()) { |
| s.append(", ").append(mWorkSource); |
| } |
| s.append(']'); |
| return s.toString(); |
| } |
| |
| /** |
| * A builder class for {@link LocationRequest}. |
| */ |
| public static final class Builder { |
| |
| private long mIntervalMillis; |
| private @Quality int mQuality; |
| private long mDurationMillis; |
| private int mMaxUpdates; |
| private long mMinUpdateIntervalMillis; |
| private float mMinUpdateDistanceMeters; |
| private long mMaxUpdateDelayMillis; |
| private boolean mHiddenFromAppOps; |
| private boolean mAdasGnssBypass; |
| private boolean mBypass; |
| private boolean mLowPower; |
| @Nullable private WorkSource mWorkSource; |
| |
| /** |
| * Creates a new Builder with the given interval. See {@link #setIntervalMillis(long)} for |
| * more information on the interval. |
| */ |
| public Builder(long intervalMillis) { |
| // gives us a range check |
| setIntervalMillis(intervalMillis); |
| |
| mQuality = QUALITY_BALANCED_POWER_ACCURACY; |
| mDurationMillis = Long.MAX_VALUE; |
| mMaxUpdates = Integer.MAX_VALUE; |
| mMinUpdateIntervalMillis = IMPLICIT_MIN_UPDATE_INTERVAL; |
| mMinUpdateDistanceMeters = 0; |
| mMaxUpdateDelayMillis = 0; |
| mHiddenFromAppOps = false; |
| mAdasGnssBypass = false; |
| mBypass = false; |
| mLowPower = false; |
| mWorkSource = null; |
| } |
| |
| /** |
| * Creates a new Builder with all parameters copied from the given location request. |
| */ |
| public Builder(@NonNull LocationRequest locationRequest) { |
| mIntervalMillis = locationRequest.mIntervalMillis; |
| mQuality = locationRequest.mQuality; |
| mDurationMillis = locationRequest.mDurationMillis; |
| mMaxUpdates = locationRequest.mMaxUpdates; |
| mMinUpdateIntervalMillis = locationRequest.mMinUpdateIntervalMillis; |
| mMinUpdateDistanceMeters = locationRequest.mMinUpdateDistanceMeters; |
| mMaxUpdateDelayMillis = locationRequest.mMaxUpdateDelayMillis; |
| mHiddenFromAppOps = locationRequest.mHideFromAppOps; |
| mAdasGnssBypass = locationRequest.mAdasGnssBypass; |
| mBypass = locationRequest.mBypass; |
| mLowPower = locationRequest.mLowPower; |
| mWorkSource = locationRequest.mWorkSource; |
| |
| // handle edge cases that can only happen with location request that has been modified |
| // by deprecated SystemApi methods |
| if (mIntervalMillis == PASSIVE_INTERVAL |
| && mMinUpdateIntervalMillis == IMPLICIT_MIN_UPDATE_INTERVAL) { |
| // this is the legacy default minimum update interval, so if we're forced to |
| // change the value, at least this should be unsuprising to legacy clients (which |
| // should be the only clients capable of getting in this weird state). |
| mMinUpdateIntervalMillis = 10 * 60 * 1000; |
| } |
| } |
| |
| /** |
| * Sets the request interval. The request interval may be set to {@link #PASSIVE_INTERVAL} |
| * which indicates this request will not actively generate location updates (and thus will |
| * not be power blamed for location), but may receive location updates generated as a result |
| * of other location requests. A passive request must always have an explicit minimum |
| * update interval set. |
| * |
| * <p>Locations may be available at a faster interval than specified here, see |
| * {@link #setMinUpdateIntervalMillis(long)} for the behavior in that case. |
| */ |
| public @NonNull Builder setIntervalMillis(@IntRange(from = 0) long intervalMillis) { |
| mIntervalMillis = Preconditions.checkArgumentInRange(intervalMillis, 0, Long.MAX_VALUE, |
| "intervalMillis"); |
| return this; |
| } |
| |
| /** |
| * Sets the request quality. The quality is a hint to providers on how they should weigh |
| * power vs accuracy tradeoffs. High accuracy locations may cost more power to produce, and |
| * lower accuracy locations may cost less power to produce. Defaults to |
| * {@link #QUALITY_BALANCED_POWER_ACCURACY}. |
| */ |
| public @NonNull Builder setQuality(@Quality int quality) { |
| Preconditions.checkArgument( |
| quality == QUALITY_LOW_POWER || quality == QUALITY_BALANCED_POWER_ACCURACY |
| || quality == QUALITY_HIGH_ACCURACY, |
| "quality must be a defined QUALITY constant, not %d", quality); |
| mQuality = quality; |
| return this; |
| } |
| |
| /** |
| * @hide |
| */ |
| public @NonNull Builder setQuality(@NonNull Criteria criteria) { |
| switch (criteria.getAccuracy()) { |
| case Criteria.ACCURACY_COARSE: |
| mQuality = QUALITY_BALANCED_POWER_ACCURACY; |
| break; |
| case Criteria.ACCURACY_FINE: |
| mQuality = QUALITY_HIGH_ACCURACY; |
| break; |
| default: { |
| if (criteria.getPowerRequirement() == Criteria.POWER_HIGH) { |
| mQuality = POWER_HIGH; |
| } else { |
| mQuality = POWER_LOW; |
| } |
| } |
| } |
| return this; |
| } |
| |
| /** |
| * Sets the duration this request will continue before being automatically removed. Defaults |
| * to <code>Long.MAX_VALUE</code>, which represents an unlimited duration. |
| */ |
| public @NonNull Builder setDurationMillis(@IntRange(from = 1) long durationMillis) { |
| mDurationMillis = Preconditions.checkArgumentInRange(durationMillis, 1, Long.MAX_VALUE, |
| "durationMillis"); |
| return this; |
| } |
| |
| /** |
| * Sets the maximum number of location updates for this request before this request is |
| * automatically removed. Defaults to <code>Integer.MAX_VALUE</code>, which represents an |
| * unlimited number of updates. |
| */ |
| public @NonNull Builder setMaxUpdates( |
| @IntRange(from = 1, to = Integer.MAX_VALUE) int maxUpdates) { |
| mMaxUpdates = Preconditions.checkArgumentInRange(maxUpdates, 1, Integer.MAX_VALUE, |
| "maxUpdates"); |
| return this; |
| } |
| |
| /** |
| * Sets an explicit minimum update interval. If location updates are available faster than |
| * the request interval then an update will only occur if the minimum update interval has |
| * expired since the last location update. Defaults to no explicit minimum update interval |
| * set, which means some sensible default between 0 and the interval will be chosen. The |
| * exact value is not specified at the moment. If an exact known value is required, clients |
| * should set an explicit value themselves. |
| * |
| * <p class=note><strong>Note:</strong> Some allowance for jitter is already built into the |
| * minimum update interval, so you need not worry about updates blocked simply because they |
| * arrived a fraction of a second earlier than expected. |
| * |
| * <p class="note"><strong>Note:</strong> When {@link #build()} is invoked, the minimum of |
| * the interval and the minimum update interval will be used as the minimum update interval |
| * of the built request. |
| */ |
| public @NonNull Builder setMinUpdateIntervalMillis( |
| @IntRange(from = 0) long minUpdateIntervalMillis) { |
| mMinUpdateIntervalMillis = Preconditions.checkArgumentInRange(minUpdateIntervalMillis, |
| 0, Long.MAX_VALUE, "minUpdateIntervalMillis"); |
| return this; |
| } |
| |
| /** |
| * Clears an explicitly set minimum update interval and reverts to an implicit minimum |
| * update interval (ie, the minimum update interval is some sensible default between 0 and |
| * the interval). |
| */ |
| public @NonNull Builder clearMinUpdateIntervalMillis() { |
| mMinUpdateIntervalMillis = IMPLICIT_MIN_UPDATE_INTERVAL; |
| return this; |
| } |
| |
| /** |
| * Sets the minimum update distance between location updates. If a potential location |
| * update is closer to the last location update than the minimum update distance, then |
| * the potential location update will not occur. Defaults to 0, which represents no minimum |
| * update distance. |
| */ |
| public @NonNull Builder setMinUpdateDistanceMeters( |
| @FloatRange(from = 0, to = Float.MAX_VALUE) float minUpdateDistanceMeters) { |
| mMinUpdateDistanceMeters = Preconditions.checkArgumentInRange(minUpdateDistanceMeters, |
| 0, Float.MAX_VALUE, "minUpdateDistanceMeters"); |
| return this; |
| } |
| |
| /** |
| * Sets the maximum time any location update may be delayed, and thus grouped with following |
| * updates to enable location batching. If the maximum update delay is equal to or greater |
| * than twice the interval, then location providers may provide batched results. Defaults to |
| * 0, which represents no batching allowed. |
| */ |
| public @NonNull Builder setMaxUpdateDelayMillis( |
| @IntRange(from = 0) long maxUpdateDelayMillis) { |
| mMaxUpdateDelayMillis = Preconditions.checkArgumentInRange(maxUpdateDelayMillis, 0, |
| Long.MAX_VALUE, "maxUpdateDelayMillis"); |
| return this; |
| } |
| |
| /** |
| * If set to true, indicates that app ops should not be updated with location usage due to |
| * this request. This implies that someone else (usually the creator of the location |
| * request) is responsible for updating app ops as appropriate. Defaults to false. |
| * |
| * <p>Permissions enforcement occurs when resulting location request is actually used, not |
| * when this method is invoked. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(Manifest.permission.UPDATE_APP_OPS_STATS) |
| public @NonNull Builder setHiddenFromAppOps(boolean hiddenFromAppOps) { |
| mHiddenFromAppOps = hiddenFromAppOps; |
| return this; |
| } |
| |
| /** |
| * If set to true, indicates that the client is an ADAS (Advanced Driving Assistance |
| * Systems) client, which requires access to GNSS even if location settings would normally |
| * deny this, in order to enable auto safety features. This field is only respected on |
| * automotive devices, and only if the client is recognized as a legitimate ADAS |
| * application. Defaults to false. |
| * |
| * <p>Permissions enforcement occurs when resulting location request is actually used, not |
| * when this method is invoked. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(LOCATION_BYPASS) |
| @RequiresFeature(PackageManager.FEATURE_AUTOMOTIVE) |
| public @NonNull Builder setAdasGnssBypass(boolean adasGnssBypass) { |
| mAdasGnssBypass = adasGnssBypass; |
| return this; |
| } |
| |
| /** |
| * If set to true, indicates that location settings, throttling, background location limits, |
| * and any other possible limiting factors should be ignored in order to satisfy this |
| * request. This is only intended for use in user initiated emergency situations, and |
| * should be used extremely cautiously. Defaults to false. |
| * |
| * <p>Permissions enforcement occurs when resulting location request is actually used, not |
| * when this method is invoked. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(LOCATION_BYPASS) |
| public @NonNull Builder setLocationSettingsIgnored(boolean locationSettingsIgnored) { |
| mBypass = locationSettingsIgnored; |
| return this; |
| } |
| |
| /** |
| * It set to true, indicates that extreme trade-offs should be made if possible to save |
| * power for this request. This usually involves specialized hardware modes which can |
| * greatly affect the quality of locations. Not all devices may support this. Defaults to |
| * false. |
| * |
| * <p>Permissions enforcement occurs when resulting location request is actually used, not |
| * when this method is invoked. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(Manifest.permission.LOCATION_HARDWARE) |
| public @NonNull Builder setLowPower(boolean lowPower) { |
| mLowPower = lowPower; |
| return this; |
| } |
| |
| /** |
| * Sets the work source to use for power blame for this location request. Defaults to an |
| * empty WorkSource, which implies the system is free to assign power blame as it determines |
| * best for this request (which usually means blaming the owner of the location listener). |
| * |
| * <p>Permissions enforcement occurs when resulting location request is actually used, not |
| * when this method is invoked. |
| * |
| * @hide |
| */ |
| @SystemApi |
| @RequiresPermission(Manifest.permission.UPDATE_DEVICE_STATS) |
| public @NonNull Builder setWorkSource(@Nullable WorkSource workSource) { |
| mWorkSource = workSource; |
| return this; |
| } |
| |
| /** |
| * Builds a location request from this builder. If an explicit minimum update interval is |
| * set, the minimum update interval of the location request will be the minimum of the |
| * interval and minimum update interval. |
| * |
| * <p>If building a passive request then you must have set an explicit minimum update |
| * interval. |
| * |
| * @throws IllegalStateException if building a passive request with no explicit minimum |
| * update interval set |
| * @return a new location request |
| */ |
| public @NonNull LocationRequest build() { |
| Preconditions.checkState(mIntervalMillis != PASSIVE_INTERVAL |
| || mMinUpdateIntervalMillis != IMPLICIT_MIN_UPDATE_INTERVAL, |
| "passive location requests must have an explicit minimum update interval"); |
| |
| return new LocationRequest( |
| null, |
| mIntervalMillis, |
| mQuality, |
| Long.MAX_VALUE, |
| mDurationMillis, |
| mMaxUpdates, |
| min(mMinUpdateIntervalMillis, mIntervalMillis), |
| mMinUpdateDistanceMeters, |
| mMaxUpdateDelayMillis, |
| mHiddenFromAppOps, |
| mAdasGnssBypass, |
| mBypass, |
| mLowPower, |
| new WorkSource(mWorkSource)); |
| } |
| } |
| } |
