From 47e9400f1e186c423ca0de5db798212e3b02bfdb Mon Sep 17 00:00:00 2001 From: Ningyuan Wang Date: Mon, 12 Jun 2017 14:40:49 -0700 Subject: [PATCH] Fix confusing javadoc for WifiManager.EXTRA_RESULTS_UPDATED This rephrases the javadoc for WifiManager.EXTRA_RESULTS_UPDATE and WifiManager.SCAN_RESULTS_AVAILABLE_ACTION, explaining the meaning of WifiManager.EXTRA_RESULTS_UPDATED in a better way. This also removes "supplicant" keyword in this javadoc because we no longer use supplicant for scan. Bug: 62273016 Test: compile Change-Id: Ib8ce2d6e8aaf70819c9e2622fb5acfcc14a0d593 --- wifi/java/android/net/wifi/WifiManager.java | 22 ++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/wifi/java/android/net/wifi/WifiManager.java b/wifi/java/android/net/wifi/WifiManager.java index c89a9a4583930..2a53326ad426b 100644 --- a/wifi/java/android/net/wifi/WifiManager.java +++ b/wifi/java/android/net/wifi/WifiManager.java @@ -675,16 +675,28 @@ public class WifiManager { @SystemApi public static final int CHANGE_REASON_CONFIG_CHANGE = 2; /** - * An access point scan has completed, and results are available from the supplicant. - * Call {@link #getScanResults()} to obtain the results. {@link #EXTRA_RESULTS_UPDATED} - * indicates if the scan was completed successfully. + * An access point scan has completed, and results are available. + * Call {@link #getScanResults()} to obtain the results. + * The broadcast intent may contain an extra field with the key {@link #EXTRA_RESULTS_UPDATED} + * and a {@code boolean} value indicating if the scan was successful. */ @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String SCAN_RESULTS_AVAILABLE_ACTION = "android.net.wifi.SCAN_RESULTS"; /** - * Lookup key for a {@code boolean} representing the result of previous {@link #startScan} - * operation, reported with {@link #SCAN_RESULTS_AVAILABLE_ACTION}. + * Lookup key for a {@code boolean} extra in intent {@link #SCAN_RESULTS_AVAILABLE_ACTION} + * representing if the scan was successful or not. + * Scans may fail for multiple reasons, these may include: + *
    + *
  1. 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 + * + * here for details. + *
    2. + *
  2. The device is idle and scanning is disabled.
    3. + *
  3. Wifi hardware reported a scan failure.
    4. + *
* @return true scan was successful, results are updated * @return false scan was not successful, results haven't been updated since previous scan */