WifiManager: startScan throttling

Changes in the CL:
a) Mark startScan() as deprecated so that we can take away this API in
future releases.
b) Modify the documentation regarding scan throttling to indicate that
both foreground & background apps are subject to throttling.

Bug: 68987915
Test: Compiles
Change-Id: I938237b186c39c6b4cfec9dcdbd9b9d196bae0cc

2 files changed, 9 insertions, 6 deletions

diff --git a/api/current.txt b/api/current.txt
index b2121a85313d..c9003b41022f 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -27268,7 +27268,7 @@ package android.net.wifi {
     method public void setTdlsEnabledWithMacAddress(java.lang.String, boolean);
     method public boolean setWifiEnabled(boolean);
     method public void startLocalOnlyHotspot(android.net.wifi.WifiManager.LocalOnlyHotspotCallback, android.os.Handler);
-    method public boolean startScan();
+    method public deprecated boolean startScan();
     method public void startWps(android.net.wifi.WpsInfo, android.net.wifi.WifiManager.WpsCallback);
     method public int updateNetwork(android.net.wifi.WifiConfiguration);
     field public static final java.lang.String ACTION_PICK_WIFI_NETWORK = "android.net.wifi.PICK_WIFI_NETWORK";
diff --git a/wifi/java/android/net/wifi/WifiManager.java b/wifi/java/android/net/wifi/WifiManager.java
index 3700bdbd8329..3b118e7e76ac 100644
--- a/wifi/java/android/net/wifi/WifiManager.java
+++ b/wifi/java/android/net/wifi/WifiManager.java
@@ -695,11 +695,11 @@ public class WifiManager {
      * representing if the scan was successful or not.
      * Scans may fail for multiple reasons, these may include:
      * <ol>
-     * <li>A non-privileged app requested too many scans in a certain period of time.
-     * This may lead to additional scan request rejections via "scan throttling".
-     * See
-     * <a href="https://developer.android.com/preview/features/background-location-limits.html">
-     * here</a> for details.
+     * <li>An app requested too many scans in a certain period of time.
+     * This may lead to additional scan request rejections via "scan throttling" for both
+     * foreground and background apps.
+     * Note: Apps holding android.Manifest.permission.NETWORK_SETTINGS permission are
+     * exempted from scan throttling.
      * </li>
      * <li>The device is idle and scanning is disabled.</li>
      * <li>Wifi hardware reported a scan failure.</li>
@@ -1596,7 +1596,10 @@ public class WifiManager {
      * {@code ((WifiManager) getSystemService(WIFI_SERVICE)).getScanResults()}</li>
      * </ol>
      * @return {@code true} if the operation succeeded, i.e., the scan was initiated.
+     * @deprecated The ability for apps to trigger scan requests will be removed in a future
+     * release.
      */
+    @Deprecated
     public boolean startScan() {
         return startScan(null);
     }