Docs: Adds brief instructions for how to do Wi-Fi scan.
Bug: 67967771
Test: Ran make ds-docs.
We don't actually document how to do a Wi-Fi scan anywhere on DAC;
at the moment, this seems like the place where it makes the most sense
to provide that guidance.
The forcing function for doing this is that a new doc explicitly
recommends that devs do Wi-Fi scans in certain cases, but doesn't
have a place to link to that tells them how to do so. That doc
plans to send readers here.
Change-Id: Ic35fb77d323e825e5bd5b4eec2716730f0d531e1
diff --git a/wifi/java/android/net/wifi/WifiManager.java b/wifi/java/android/net/wifi/WifiManager.java
index c89a9a4..f1e7eaf 100644
--- a/wifi/java/android/net/wifi/WifiManager.java
+++ b/wifi/java/android/net/wifi/WifiManager.java
@@ -67,6 +67,7 @@
* leaks within the calling process.
* <p>
* It deals with several categories of items:
+ * </p>
* <ul>
* <li>The list of configured networks. The list can be viewed and updated, and
* attributes of individual entries can be modified.</li>
@@ -78,9 +79,11 @@
* <li>It defines the names of various Intent actions that are broadcast upon
* any sort of change in Wi-Fi state.
* </ul>
+ * <p>
* This is the API to use when performing Wi-Fi specific operations. To perform
* operations that pertain to network connectivity at an abstract level, use
* {@link android.net.ConnectivityManager}.
+ * </p>
*/
@SystemService(Context.WIFI_SERVICE)
public class WifiManager {
@@ -1522,7 +1525,21 @@
* Request a scan for access points. Returns immediately. The availability
* of the results is made known later by means of an asynchronous event sent
* on completion of the scan.
- * @return {@code true} if the operation succeeded, i.e., the scan was initiated
+ * <p>
+ * To initiate a Wi-Fi scan, declare the
+ * {@link android.Manifest.permission#CHANGE_WIFI_STATE}
+ * permission in the manifest, and perform these steps:
+ * </p>
+ * <ol style="1">
+ * <li>Invoke the following method:
+ * {@code ((WifiManager) getSystemService(WIFI_SERVICE)).startScan()}</li>
+ * <li>
+ * Register a BroadcastReceiver to listen to
+ * {@code SCAN_RESULTS_AVAILABLE_ACTION}.</li>
+ * <li>When a broadcast is received, call:
+ * {@code ((WifiManager) getSystemService(WIFI_SERVICE)).getScanResults()}</li>
+ * </ol>
+ * @return {@code true} if the operation succeeded, i.e., the scan was initiated.
*/
public boolean startScan() {
return startScan(null);