Import Android SDK Platform P [4524038]

/google/data/ro/projects/android/fetch_artifact \
    --bid 4524038 \
    --target sdk_phone_armv7-win_sdk \
    sdk-repo-linux-sources-4524038.zip

AndroidVersion.ApiLevel has been modified to appear as 28

Change-Id: Ic193bf1cf0cae78d4f2bfb4fbddfe42025c5c3c2

4 files changed, 136 insertions, 50 deletions

diff --git a/android/location/GnssMeasurementsEvent.java b/android/location/GnssMeasurementsEvent.java
index d66fd9c4..072a7fef 100644
--- a/android/location/GnssMeasurementsEvent.java
+++ b/android/location/GnssMeasurementsEvent.java
@@ -49,7 +49,7 @@ public final class GnssMeasurementsEvent implements Parcelable {
          * @hide
          */
         @Retention(RetentionPolicy.SOURCE)
-        @IntDef({STATUS_NOT_SUPPORTED, STATUS_READY, STATUS_LOCATION_DISABLED})
+        @IntDef({STATUS_NOT_SUPPORTED, STATUS_READY, STATUS_LOCATION_DISABLED, STATUS_NOT_ALLOWED})
         public @interface GnssMeasurementsStatus {}
 
         /**
@@ -72,6 +72,12 @@ public final class GnssMeasurementsEvent implements Parcelable {
         public static final int STATUS_LOCATION_DISABLED = 2;
 
         /**
+         * The client is not allowed to register for GNSS Measurements in general or in the
+         * requested mode.
+         */
+        public static final int STATUS_NOT_ALLOWED = 3;
+
+        /**
          * Reports the latest collected GNSS Measurements.
          */
         public void onGnssMeasurementsReceived(GnssMeasurementsEvent eventArgs) {}
diff --git a/android/location/LocalListenerHelper.java b/android/location/LocalListenerHelper.java
index d7d2c513..592d01d2 100644
--- a/android/location/LocalListenerHelper.java
+++ b/android/location/LocalListenerHelper.java
@@ -16,14 +16,14 @@
 
 package android.location;
 
-import com.android.internal.util.Preconditions;
-
 import android.annotation.NonNull;
 import android.content.Context;
 import android.os.Handler;
 import android.os.RemoteException;
 import android.util.Log;
 
+import com.android.internal.util.Preconditions;
+
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
@@ -46,6 +46,11 @@ abstract class LocalListenerHelper<TListener> {
         mTag = name;
     }
 
+    /**
+     * Adds a {@param listener} to the list of listeners on which callbacks will be executed. The
+     * execution will happen on the {@param handler} thread or alternatively in the callback thread
+     * if a  {@code null} handler value is passed.
+     */
     public boolean add(@NonNull TListener listener, Handler handler) {
         Preconditions.checkNotNull(listener);
         synchronized (mListeners) {
diff --git a/android/location/LocationManager.java b/android/location/LocationManager.java
index 968f596e..4802b235 100644
--- a/android/location/LocationManager.java
+++ b/android/location/LocationManager.java
@@ -19,6 +19,7 @@ package android.location;
 import com.android.internal.location.ProviderProperties;
 
 import android.Manifest;
+import android.annotation.NonNull;
 import android.annotation.RequiresPermission;
 import android.annotation.SuppressLint;
 import android.annotation.SystemApi;
@@ -184,6 +185,17 @@ public class LocationManager {
     public static final String MODE_CHANGED_ACTION = "android.location.MODE_CHANGED";
 
     /**
+     * Broadcast intent action when {@link android.provider.Settings.Secure#LOCATION_MODE} is
+     * about to be changed through Settings app or Quick Settings.
+     * For use with the {@link android.provider.Settings.Secure#LOCATION_MODE} API.
+     * If you're interacting with {@link #isProviderEnabled(String)}, use
+     * {@link #PROVIDERS_CHANGED_ACTION} instead.
+     *
+     * @hide
+     */
+    public static final String MODE_CHANGING_ACTION = "com.android.settings.location.MODE_CHANGING";
+
+    /**
      * Broadcast intent action indicating that the GPS has either started or
      * stopped receiving GPS fixes. An intent extra provides this state as a
      * boolean, where {@code true} means that the GPS is actively receiving fixes.
@@ -214,6 +226,12 @@ public class LocationManager {
     public static final String HIGH_POWER_REQUEST_CHANGE_ACTION =
         "android.location.HIGH_POWER_REQUEST_CHANGE";
 
+    /**
+     * The value returned by {@link LocationManager#getGnssHardwareModelName()} when the hardware
+     * does not support providing the actual value.
+     */
+    public static final String GNSS_HARDWARE_MODEL_NAME_UNKNOWN = "Model Name Unknown";
+
     // Map from LocationListeners to their associated ListenerTransport objects
     private HashMap<LocationListener,ListenerTransport> mListeners =
         new HashMap<LocationListener,ListenerTransport>();
@@ -1958,11 +1976,10 @@ public class LocationManager {
     }
 
     /**
-     * Returns the system information of the GPS hardware.
-     * May return 0 if GPS hardware is earlier than 2016.
-     * @hide
+     * Returns the model year of the GNSS hardware and software build.
+     *
+     * May return 0 if the model year is less than 2016.
      */
-    @TestApi
     public int getGnssYearOfHardware() {
         try {
             return mService.getGnssYearOfHardware();
@@ -1972,6 +1989,22 @@ public class LocationManager {
     }
 
     /**
+     * Returns the Model Name (including Vendor and Hardware/Software Version) of the GNSS hardware
+     * driver.
+     *
+     * Will return {@link LocationManager#GNSS_HARDWARE_MODEL_NAME_UNKNOWN} when the GNSS hardware
+     * abstraction layer does not support providing this value.
+     */
+    @NonNull
+    public String getGnssHardwareModelName() {
+        try {
+            return mService.getGnssHardwareModelName();
+        } catch (RemoteException e) {
+            throw e.rethrowFromSystemServer();
+        }
+    }
+
+    /**
      * Returns the batch size (in number of Location objects) that are supported by the batching
      * interface.
      *
diff --git a/android/location/LocationRequest.java b/android/location/LocationRequest.java
index 65e7cedf..6abba954 100644
--- a/android/location/LocationRequest.java
+++ b/android/location/LocationRequest.java
@@ -143,7 +143,7 @@ public final class LocationRequest implements Parcelable {
 
     private int mQuality = POWER_LOW;
     private long mInterval = 60 * 60 * 1000;   // 60 minutes
-    private long mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR);  // 10 minutes
+    private long mFastestInterval = (long) (mInterval / FASTEST_INTERVAL_FACTOR);  // 10 minutes
     private boolean mExplicitFastestInterval = false;
     private long mExpireAt = Long.MAX_VALUE;  // no expiry
     private int mNumUpdates = Integer.MAX_VALUE;  // no expiry
@@ -151,7 +151,11 @@ public final class LocationRequest implements Parcelable {
     private WorkSource mWorkSource = null;
     private boolean mHideFromAppOps = false; // True if this request shouldn't be counted by AppOps
 
-    private String mProvider = LocationManager.FUSED_PROVIDER;  // for deprecated APIs that explicitly request a provider
+    private String mProvider = LocationManager.FUSED_PROVIDER;
+            // for deprecated APIs that explicitly request a provider
+
+    /** If true, GNSS chipset will make strong tradeoffs to substantially restrict power use */
+    private boolean mLowPowerMode = false;
 
     /**
      * Create a location request with default parameters.
@@ -184,11 +188,11 @@ public final class LocationRequest implements Parcelable {
         }
 
         LocationRequest request = new LocationRequest()
-            .setProvider(provider)
-            .setQuality(quality)
-            .setInterval(minTime)
-            .setFastestInterval(minTime)
-            .setSmallestDisplacement(minDistance);
+                .setProvider(provider)
+                .setQuality(quality)
+                .setInterval(minTime)
+                .setFastestInterval(minTime)
+                .setSmallestDisplacement(minDistance);
         if (singleShot) request.setNumUpdates(1);
         return request;
     }
@@ -220,16 +224,17 @@ public final class LocationRequest implements Parcelable {
         }
 
         LocationRequest request = new LocationRequest()
-            .setQuality(quality)
-            .setInterval(minTime)
-            .setFastestInterval(minTime)
-            .setSmallestDisplacement(minDistance);
+                .setQuality(quality)
+                .setInterval(minTime)
+                .setFastestInterval(minTime)
+                .setSmallestDisplacement(minDistance);
         if (singleShot) request.setNumUpdates(1);
         return request;
     }
 
     /** @hide */
-    public LocationRequest() { }
+    public LocationRequest() {
+    }
 
     /** @hide */
     public LocationRequest(LocationRequest src) {
@@ -243,6 +248,7 @@ public final class LocationRequest implements Parcelable {
         mProvider = src.mProvider;
         mWorkSource = src.mWorkSource;
         mHideFromAppOps = src.mHideFromAppOps;
+        mLowPowerMode = src.mLowPowerMode;
     }
 
     /**
@@ -263,8 +269,8 @@ public final class LocationRequest implements Parcelable {
      * 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
+     * @throws InvalidArgumentException if the quality constant is not valid
      */
     public LocationRequest setQuality(int quality) {
         checkQuality(quality);
@@ -306,14 +312,14 @@ public final class LocationRequest implements Parcelable {
      * 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
+     * @throws InvalidArgumentException if the interval is less than zero
      */
     public LocationRequest setInterval(long millis) {
         checkInterval(millis);
         mInterval = millis;
         if (!mExplicitFastestInterval) {
-            mFastestInterval = (long)(mInterval / FASTEST_INTERVAL_FACTOR);
+            mFastestInterval = (long) (mInterval / FASTEST_INTERVAL_FACTOR);
         }
         return this;
     }
@@ -327,6 +333,34 @@ public final class LocationRequest implements Parcelable {
         return mInterval;
     }
 
+
+    /**
+     * Requests the GNSS chipset to run in a low power mode and make strong tradeoffs to
+     * substantially restrict power.
+     *
+     * <p>In this mode, the GNSS chipset will not, on average, run power hungry operations like RF &
+     * signal searches for more than one second per interval {@link #mInterval}
+     *
+     * @param enabled Enable or disable low power mode
+     * @return the same object, so that setters can be chained
+     * @hide
+     */
+    @SystemApi
+    public LocationRequest setLowPowerMode(boolean enabled) {
+        mLowPowerMode = enabled;
+        return this;
+    }
+
+    /**
+     * Returns true if low power mode is enabled.
+     *
+     * @hide
+     */
+    @SystemApi
+    public boolean isLowPowerMode() {
+        return mLowPowerMode;
+    }
+
     /**
      * Explicitly set the fastest interval for location updates, in
      * milliseconds.
@@ -353,8 +387,8 @@ public final class LocationRequest implements Parcelable {
      * 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
+     * @throws InvalidArgumentException if the interval is less than zero
      */
     public LocationRequest setFastestInterval(long millis) {
         checkInterval(millis);
@@ -397,9 +431,9 @@ public final class LocationRequest implements Parcelable {
 
         // Check for > Long.MAX_VALUE overflow (elapsedRealtime > 0):
         if (millis > Long.MAX_VALUE - elapsedRealtime) {
-          mExpireAt = Long.MAX_VALUE;
+            mExpireAt = Long.MAX_VALUE;
         } else {
-          mExpireAt = millis + elapsedRealtime;
+            mExpireAt = millis + elapsedRealtime;
         }
 
         if (mExpireAt < 0) mExpireAt = 0;
@@ -448,11 +482,14 @@ public final class LocationRequest implements Parcelable {
      * 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
+     * @throws InvalidArgumentException if numUpdates is 0 or less
      */
     public LocationRequest setNumUpdates(int numUpdates) {
-        if (numUpdates <= 0) throw new IllegalArgumentException("invalid numUpdates: " + numUpdates);
+        if (numUpdates <= 0) {
+            throw new IllegalArgumentException(
+                    "invalid numUpdates: " + numUpdates);
+        }
         mNumUpdates = numUpdates;
         return this;
     }
@@ -462,6 +499,7 @@ public final class LocationRequest implements Parcelable {
      *
      * <p>By default this is {@link Integer#MAX_VALUE}, which indicates that
      * locations are updated until the request is explicitly removed.
+     *
      * @return number of updates
      */
     public int getNumUpdates() {
@@ -539,8 +577,8 @@ public final class LocationRequest implements Parcelable {
      * 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
+     * @see android.app.AppOpsManager
      */
     @SystemApi
     public void setHideFromAppOps(boolean hideFromAppOps) {
@@ -587,27 +625,29 @@ public final class LocationRequest implements Parcelable {
 
     public static final Parcelable.Creator<LocationRequest> CREATOR =
             new Parcelable.Creator<LocationRequest>() {
-        @Override
-        public LocationRequest createFromParcel(Parcel in) {
-            LocationRequest request = new LocationRequest();
-            request.setQuality(in.readInt());
-            request.setFastestInterval(in.readLong());
-            request.setInterval(in.readLong());
-            request.setExpireAt(in.readLong());
-            request.setNumUpdates(in.readInt());
-            request.setSmallestDisplacement(in.readFloat());
-            request.setHideFromAppOps(in.readInt() != 0);
-            String provider = in.readString();
-            if (provider != null) request.setProvider(provider);
-            WorkSource workSource = in.readParcelable(null);
-            if (workSource != null) request.setWorkSource(workSource);
-            return request;
-        }
-        @Override
-        public LocationRequest[] newArray(int size) {
-            return new LocationRequest[size];
-        }
-    };
+                @Override
+                public LocationRequest createFromParcel(Parcel in) {
+                    LocationRequest request = new LocationRequest();
+                    request.setQuality(in.readInt());
+                    request.setFastestInterval(in.readLong());
+                    request.setInterval(in.readLong());
+                    request.setExpireAt(in.readLong());
+                    request.setNumUpdates(in.readInt());
+                    request.setSmallestDisplacement(in.readFloat());
+                    request.setHideFromAppOps(in.readInt() != 0);
+                    request.setLowPowerMode(in.readInt() != 0);
+                    String provider = in.readString();
+                    if (provider != null) request.setProvider(provider);
+                    WorkSource workSource = in.readParcelable(null);
+                    if (workSource != null) request.setWorkSource(workSource);
+                    return request;
+                }
+
+                @Override
+                public LocationRequest[] newArray(int size) {
+                    return new LocationRequest[size];
+                }
+            };
 
     @Override
     public int describeContents() {
@@ -623,6 +663,7 @@ public final class LocationRequest implements Parcelable {
         parcel.writeInt(mNumUpdates);
         parcel.writeFloat(mSmallestDisplacement);
         parcel.writeInt(mHideFromAppOps ? 1 : 0);
+        parcel.writeInt(mLowPowerMode ? 1 : 0);
         parcel.writeString(mProvider);
         parcel.writeParcelable(mWorkSource, 0);
     }
@@ -663,9 +704,10 @@ public final class LocationRequest implements Parcelable {
             s.append(" expireIn=");
             TimeUtils.formatDuration(expireIn, s);
         }
-        if (mNumUpdates != Integer.MAX_VALUE){
+        if (mNumUpdates != Integer.MAX_VALUE) {
             s.append(" num=").append(mNumUpdates);
         }
+        s.append(" lowPowerMode=").append(mLowPowerMode);
         s.append(']');
         return s.toString();
     }