revert(wifi_scan)!: added back "can" APIs (#288)

- reverting #246 pull [most of it]

Author: daadu

packages/wifi_scan/README.md

@@ -33,79 +33,71 @@ This plugin allows Flutter apps to scan for nearby visible WiFi access points.
 ## Usage
 The entry point for the plugin is the singleton instance `WiFiScan.instance`.
 
-### Check support
-You can check if the platform has Wi-Fi scan capabilities with `WiFiScan.hasCapability` API, as shown below:
-```dart
-void _scan() async {
-  if(await WiFiScan.instance.hasCapability()){
-    // can safely call scan related functionalities
-  } else {
-    // fallback mechanism, like - show user that "scan" is not possible 
-  }
-}
-```
-
-For more details, you can read documentation of [`WiFiScan.hasCapability`][doc_hasCapability].
-
 ### Start scan
 You can trigger full WiFi scan with `WiFiScan.startScan` API, as shown below:
 ```dart
 void _startScan() async {
-  // start full scan async-ly
-  final error = await WiFiScan.instance.startScan(askPermissions: true);
-  if (error != null) {
-    switch(error) {
-      // handle error for values of StartScanErrors
-    }
+  // check platform support and necessary requirements
+  final can = await WiFiScan.instance.canStartScan(askPermissions: true);
+  switch(can) {
+    case CanStartScan.yes:
+      // start full scan async-ly
+      final isScanning = await WiFiScan.instance.startScan();
+      //...
+      break;
+    // ... handle other cases of CanStartScan values
   }
 }
 ```
 
 For more details, you can read documentation of [`WiFiScan.startScan`][doc_startScan], 
-[`StartScanErrors`][doc_StartScanErrors] and [`Result<ValueType, ErrorType>`][doc_Result].
+[`WiFiScan.canStartScan`][doc_canStartScan] and [`CanStartScan`][doc_enum_CanStartScan].
 
 ### Get scanned results
 You can get scanned results with `WiFiScan.getScannedResults` API, as shown below:
 ```dart
 void _getScannedResults() async {
-  // get scanned results
-  final result = await WiFiScan.instance.getScannedResults(askPermissions: true);
-  if (result.hasError){
-    switch (error){
-      // handle error for values of GetScannedResultErrors
-    }
-  } else {
-    final accessPoints = result.value;
-    // ...
+  // check platform support and necessary requirements
+  final can = await WiFiScan.instance.canGetScannedResults(askPermissions: true);
+  switch(can) {
+    case CanGetScannedResults.yes:
+      // get scanned results
+      final accessPoints = await WiFiScan.instance.getScannedResults();
+      // ...
+      break;
+    // ... handle other cases of CanGetScannedResults values
   }
 }
 ```
 
 > **NOTE:** `getScannedResults` API can be used independently of `startScan` API. This returns the latest available scanned results.
 
-For more details, you can read documentation of [`WiFiScan.getScannedResults`][doc_getScannedResults], 
-[`WiFiAccessPoint`][doc_WiFiAccessPoint], [`GetScannedResultsErrors`][doc_GetScannedResultsErrors] and 
-[`Result<ValueType, ErrorType>`][doc_Result].
+For more details, you can read documentation of [`WiFiScan.getScannedResults`][doc_getScannedResults],
+[`WiFiAccessPoint`][doc_WiFiAccessPoint],
+[`WiFiScan.canGetScannedResults`][doc_canGetScannedResults] and
+[`CanGetScannedResults`][doc_enum_CanGetScannedResults].
 
 ### Get notified when scanned results available
 You can get notified when new scanned results are available with `WiFiScan.onScannedResultsAvailable` API, as shown below:
 ```dart
 // initialize accessPoints and subscription
 List<WiFiAccessPoint> accessPoints = [];
-StreamSubscription<Result<List<WiFiAccessPoint>, GetScannedResultErrors>>? subscription;
+StreamSubscription<List<WiFiAccessPoint>>? subscription;
 
 void _startListeningToScannedResults() async {
-  // listen to onScannedResultsAvailable stream
-  subscription = WiFiScan.instance.onScannedResultsAvailable.listen((result) {
-    if (result.hasError){
-      switch (error){
-      // handle error for values of GetScannedResultErrors
-      }  
-    } else {
-      // update accessPoints
-      setState(() => accessPoints = result.value);
-    }
-  });
+  // check platform support and necessary requirements
+  final can = await WiFiScan.instance.canGetScannedResults(askPermissions: true);
+  switch(can) {
+    case CanGetScannedResults.yes:
+      // listen to onScannedResultsAvailable stream
+      subscription = WiFiScan.instance.onScannedResultsAvailable.listen((results) {
+        // update accessPoints
+        setState(() => accessPoints = results);
+      });
+      // ...
+      break;
+    // ... handle other cases of CanGetScannedResults values
+  }
 }
 
 // make sure to cancel subscription after you are done
@@ -122,9 +114,10 @@ Additionally, `WiFiScan.onScannedResultsAvailable` API can also be used with Flu
 > **NOTE:** `onScannedResultsAvailable` API can be used  independently of `startScan` API. The notification can also be result of a full scan performed by platform or other app.
 
 For more details, you can read documentation of 
-[`WiFiScan.onScannedResultsAvailable`][doc_onScannedResultsAvailable], 
-[`WiFiAccessPoint`][doc_WiFiAccessPoint], [`GetScannedResultsErrors`][doc_GetScannedResultsErrors] and 
-[`Result<ValueType, ErrorType>`][doc_Result].
+[`WiFiScan.onScannedResultsAvailable`][doc_onScannedResultsAvailable],
+[`WiFiAccessPoint`][doc_WiFiAccessPoint],
+[`WiFiScan.canGetScannedResults`][doc_canGetScannedResults] and
+[`CanGetScannedResults`][doc_enum_CanGetScannedResults].
 
 ## Resources
 - 📖[API docs][docs]
@@ -155,13 +148,13 @@ This project follows the [all-contributors][all_contributors] specification. Con
 [docs]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/wifi_scan-library.html
 [example]: https://github.com/flutternetwork/WiFiFlutter/tree/master/packages/wifi_scan/example
 
-[doc_hasCapability]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/hasCapability.html
 [doc_startScan]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/startScan.html
-[doc_StartScanErrors]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/StartScanErrors.html
-[doc_Result]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/Result-class.html
+[doc_canStartScan]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/canStartScan.html
+[doc_enum_CanStartScan]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/CanStartScan.html
 [doc_getScannedResults]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/getScannedResults.html
 [doc_WiFiAccessPoint]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiAccessPoint-class.html
-[doc_GetScannedResultsErrors]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/GetScannedResultsErrors.html
+[doc_canGetScannedResults]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/canGetScannedResults.html
+[doc_enum_CanGetScannedResults]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/CanGetScannedResults.html
 [doc_onScannedResultsAvailable]: https://pub.dev/documentation/wifi_scan/latest/wifi_scan/WiFiScan/onScannedResultsAvailable.html
 
 [flutter_StreamBuilder]: https://api.flutter.dev/flutter/widgets/StreamBuilder-class.html

packages/wifi_scan/android/src/main/kotlin/dev/flutternetwork/wifi/wifi_scan/WifiScanPlugin.kt

@@ -31,20 +31,21 @@ import kotlin.random.Random
 private const val ERROR_INVALID_ARGS = "InvalidArgs"
 private const val ERROR_NULL_ACTIVITY = "NullActivity"
 
-/** StartScanError codes */
-private const val ERROR_START_SCAN_NOT_SUPPORTED = 0
-private const val ERROR_START_SCAN_NO_LOC_PERM_REQUIRED = 1
-private const val ERROR_START_SCAN_NO_LOC_PERM_DENIED = 2
-private const val ERROR_START_SCAN_NO_LOC_PERM_UPGRADE_ACCURACY = 3
-private const val ERROR_START_SCAN_NO_LOC_DISABLED = 4
-private const val ERROR_START_SCAN_FAILED = 5
-
-/** GetScannedResultsError codes */
-private const val ERROR_GET_RESULTS_NOT_SUPPORTED = 0
-private const val ERROR_GET_RESULTS_NO_LOC_PERM_REQUIRED = 1
-private const val ERROR_GET_RESULTS_NO_LOC_PERM_DENIED = 2
-private const val ERROR_GET_RESULTS_NO_LOC_PERM_UPGRADE_ACCURACY = 3
-private const val ERROR_GET_RESULTS_NO_LOC_DISABLED = 4
+/** CanStartScan codes */
+private const val CAN_START_SCAN_NOT_SUPPORTED = 0
+private const val CAN_START_SCAN_YES = 1
+private const val CAN_START_SCAN_NO_LOC_PERM_REQUIRED = 2
+private const val CAN_START_SCAN_NO_LOC_PERM_DENIED = 3
+private const val CAN_START_SCAN_NO_LOC_PERM_UPGRADE_ACCURACY = 4
+private const val CAN_START_SCAN_NO_LOC_DISABLED = 5
+
+/** CanGetScannedResults codes */
+private const val CAN_GET_RESULTS_NOT_SUPPORTED = 0
+private const val CAN_GET_RESULTS_YES = 1
+private const val CAN_GET_RESULTS_NO_LOC_PERM_REQUIRED = 2
+private const val CAN_GET_RESULTS_NO_LOC_PERM_DENIED = 3
+private const val CAN_GET_RESULTS_NO_LOC_PERM_UPGRADE_ACCURACY = 4
+private const val CAN_GET_RESULTS_NO_LOC_DISABLED = 5
 
 /** Magic codes */
 private const val ASK_FOR_LOC_PERM = -1
@@ -141,31 +142,38 @@ class WifiScanPlugin : FlutterPlugin, MethodCallHandler, ActivityAware,
         eventSink = null
     }
 
+    override fun onRequestPermissionsResult(
+        requestCode: Int, permissions: Array<out String>, grantResults: IntArray
+    ): Boolean {
+        Log.d(
+            logTag,
+            "onRequestPermissionsResult: arguments ($requestCode, $permissions, $grantResults)"
+        )
+        Log.d(logTag, "requestPermissionCookie: $requestPermissionCookie")
+        return requestPermissionCookie[requestCode]?.invoke(grantResults) ?: false
+    }
+
     override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
         when (call.method) {
-            "hasCapability" -> result.success(true)
-            "startScan" -> {
+            "canStartScan" -> {
                 val askPermission = call.argument<Boolean>("askPermissions") ?: return result.error(
                     ERROR_INVALID_ARGS,
                     "askPermissions argument is null",
                     null
                 )
-                val errorCode = startScan(askPermission)
                 // if not ASK_FOR_LOC_PERM, send result
                 // else ask for permission - wait for user action - return result based on it
-                if (errorCode != ASK_FOR_LOC_PERM) {
-                    result.success(errorCode)
-                } else {
-                    askForLocationPermission { askResult ->
+                when (val canCode = canStartScan(askPermission)) {
+                    ASK_FOR_LOC_PERM -> askForLocationPermission { askResult ->
                         when (askResult) {
                             AskLocPermResult.GRANTED -> {
-                                result.success(startScan(askPermission = false))
+                                result.success(canStartScan(askPermission = false))
                             }
                             AskLocPermResult.UPGRADE_TO_FINE -> {
-                                result.success(ERROR_START_SCAN_NO_LOC_PERM_UPGRADE_ACCURACY)
+                                result.success(CAN_START_SCAN_NO_LOC_PERM_UPGRADE_ACCURACY)
                             }
                             AskLocPermResult.DENIED -> {
-                                result.success(ERROR_START_SCAN_NO_LOC_PERM_DENIED)
+                                result.success(CAN_START_SCAN_NO_LOC_PERM_DENIED)
                             }
                             AskLocPermResult.ERROR_NO_ACTIVITY -> {
                                 result.error(
@@ -176,30 +184,27 @@ class WifiScanPlugin : FlutterPlugin, MethodCallHandler, ActivityAware,
                             }
                         }
                     }
+                    else -> result.success(canCode)
                 }
             }
-            "getScannedResults" -> {
+            "startScan" -> result.success(startScan())
+            "canGetScannedResults" -> {
                 val askPermission = call.argument<Boolean>("askPermissions") ?: return result.error(
                     ERROR_INVALID_ARGS,
                     "askPermissions argument is null",
                     null
                 )
-                val mResult = getScannedResults(askPermission)
-                // if error != ASK_FOR_LOC_PERM, send result
-                // else ask for permission - wait for user action - return result based on it
-                if (mResult["error"] != ASK_FOR_LOC_PERM) {
-                    result.success(mResult)
-                } else {
-                    askForLocationPermission { askResult ->
+                when(val canCode = canGetScannedResults(askPermission)){
+                    ASK_FOR_LOC_PERM -> askForLocationPermission { askResult ->
                         when (askResult) {
                             AskLocPermResult.GRANTED -> {
-                                result.success(getScannedResults(askPermission = false))
+                                result.success(canGetScannedResults(askPermission = false))
                             }
                             AskLocPermResult.UPGRADE_TO_FINE -> {
-                                result.success(errorResult(ERROR_GET_RESULTS_NO_LOC_PERM_UPGRADE_ACCURACY))
+                                result.success(CAN_GET_RESULTS_NO_LOC_PERM_UPGRADE_ACCURACY)
                             }
                             AskLocPermResult.DENIED -> {
-                                result.success(errorResult(ERROR_GET_RESULTS_NO_LOC_PERM_DENIED))
+                                result.success(CAN_GET_RESULTS_NO_LOC_PERM_DENIED)
                             }
                             AskLocPermResult.ERROR_NO_ACTIVITY -> {
                                 result.error(
@@ -210,81 +215,64 @@ class WifiScanPlugin : FlutterPlugin, MethodCallHandler, ActivityAware,
                             }
                         }
                     }
+                    else -> result.success(canCode)
                 }
             }
+            "getScannedResults" -> result.success(getScannedResults())
             else -> result.notImplemented()
         }
     }
 
-    override fun onRequestPermissionsResult(
-        requestCode: Int, permissions: Array<out String>, grantResults: IntArray
-    ): Boolean {
-        Log.d(
-            logTag,
-            "onRequestPermissionsResult: arguments ($requestCode, $permissions, $grantResults)"
-        )
-        Log.d(logTag, "requestPermissionCookie: $requestPermissionCookie")
-        return requestPermissionCookie[requestCode]?.invoke(grantResults) ?: false
-    }
-
-    private fun startScan(askPermission: Boolean): Int? {
+    private fun canStartScan(askPermission: Boolean): Int {
         val hasLocPerm = hasLocationPermission()
         val isLocEnabled = isLocationEnabled()
-        // check all prerequisite conditions for startScan
-        val errorCode = when {
+        return when {
             // for SDK < P[28] : Not in guide, should not require any additional permissions
-            Build.VERSION.SDK_INT < Build.VERSION_CODES.P -> null
+            Build.VERSION.SDK_INT < Build.VERSION_CODES.P -> CAN_START_SCAN_YES
             // for SDK >= Q[29]: CHANGE_WIFI_STATE & ACCESS_x_LOCATION & "Location enabled"
-            hasLocPerm && isLocEnabled -> null
-            hasLocPerm -> ERROR_START_SCAN_NO_LOC_DISABLED
+            hasLocPerm && isLocEnabled -> CAN_START_SCAN_YES
+            hasLocPerm -> CAN_START_SCAN_NO_LOC_DISABLED
             askPermission -> ASK_FOR_LOC_PERM
-            else -> ERROR_START_SCAN_NO_LOC_PERM_REQUIRED
+            else -> CAN_START_SCAN_NO_LOC_PERM_REQUIRED
         }
-        // if any errorCode then return it
-        if (errorCode != null) return errorCode
-
-        // call startScan API - if failed then return ERROR_START_SCAN_FAILED
-        return if (wifi!!.startScan()) null else ERROR_START_SCAN_FAILED
     }
 
-    private fun getScannedResults(askPermission: Boolean): Map<String, Any?> {
+    private fun startScan(): Boolean = wifi!!.startScan()
+
+    private fun canGetScannedResults(askPermission: Boolean): Int {
         // check all prerequisite conditions
         // ACCESS_WIFI_STATE & ACCESS_x_LOCATION & "Location enabled"
         val hasLocPerm = hasLocationPermission()
         val isLocEnabled = isLocationEnabled()
-        val errorCode = when {
-            hasLocPerm && isLocEnabled -> null
-            hasLocPerm -> ERROR_GET_RESULTS_NO_LOC_DISABLED
+        return when {
+            hasLocPerm && isLocEnabled -> CAN_GET_RESULTS_YES
+            hasLocPerm -> CAN_GET_RESULTS_NO_LOC_DISABLED
             askPermission -> ASK_FOR_LOC_PERM
-            else -> ERROR_GET_RESULTS_NO_LOC_PERM_REQUIRED
+            else -> CAN_GET_RESULTS_NO_LOC_PERM_REQUIRED
         }
+    }
 
-        // if any errorCode then return it
-        if (errorCode != null) return errorResult(errorCode)
-
-        // return scannedResults
-        return mapOf("value" to wifi!!.scanResults.map { ap ->
-            mapOf(
-                "ssid" to ap.SSID,
-                "bssid" to ap.BSSID,
-                "capabilities" to ap.capabilities,
-                "frequency" to ap.frequency,
-                "level" to ap.level,
-                "timestamp" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR1) ap.timestamp else null,
-                "standard" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) ap.wifiStandard else null,
-                "centerFrequency0" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.centerFreq0 else null,
-                "centerFrequency1" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.centerFreq1 else null,
-                "channelWidth" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.channelWidth else null,
-                "isPasspoint" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.isPasspointNetwork else null,
-                "operatorFriendlyName" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.operatorFriendlyName else null,
-                "venueName" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.venueName else null,
-                "is80211mcResponder" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.is80211mcResponder else null
-            )
-        })
+    private fun getScannedResults(): List<Map<String, Any?>> = wifi!!.scanResults.map { ap ->
+        mapOf(
+            "ssid" to ap.SSID,
+            "bssid" to ap.BSSID,
+            "capabilities" to ap.capabilities,
+            "frequency" to ap.frequency,
+            "level" to ap.level,
+            "timestamp" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR1) ap.timestamp else null,
+            "standard" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) ap.wifiStandard else null,
+            "centerFrequency0" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.centerFreq0 else null,
+            "centerFrequency1" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.centerFreq1 else null,
+            "channelWidth" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.channelWidth else null,
+            "isPasspoint" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.isPasspointNetwork else null,
+            "operatorFriendlyName" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.operatorFriendlyName else null,
+            "venueName" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.venueName else null,
+            "is80211mcResponder" to if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) ap.is80211mcResponder else null
+        )
     }
 
     private fun onScannedResultsAvailable() {
-        eventSink?.success(getScannedResults(askPermission = false))
+        eventSink?.success(getScannedResults())
     }
 
     /**
@@ -349,6 +337,4 @@ class WifiScanPlugin : FlutterPlugin, MethodCallHandler, ActivityAware,
         LocationManagerCompat.isLocationEnabled(
             context.applicationContext.getSystemService(Context.LOCATION_SERVICE) as LocationManager
         )
-
-   private fun errorResult(code: Int): Map<String, Int> = mapOf("error" to code)
 }