Enable usage of Android ScanSettings (#159)

README.md

@@ -52,7 +52,25 @@ val advertisement = Scanner()
     .first { it.name?.startsWith("Example") }
 ```
 
-_**JavaScript:** Scanning for nearby peripherals is supported, but only available on Chrome 79+ with "Experimental Web
+### Android
+
+Android offers additional settings to customize scanning. They are available via the `scanSettings` property in the
+[`Scanner`] builder DSL. Simply set `scanSettings` property to an Android [`ScanSettings`] object, for example:
+
+```kotlin
+val scanner = Scanner {
+    scanSettings = ScanSettings.Builder()
+        .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
+        .build()
+}
+```
+
+_The `scanSettings` property is only available on Android and is considered a Kable obsolete API, meaning it will be
+removed when a DSL specific API becomes available._
+
+### JavaScript
+
+_Scanning for nearby peripherals is supported, but only available on Chrome 79+ with "Experimental Web
 Platform features" enabled via:_ `chrome://flags/#enable-experimental-web-platform-features`
 
 ## Peripheral
@@ -464,6 +482,7 @@ limitations under the License.
 [SensorTag sample app]: https://github.com/JuulLabs/sensortag
 [Coroutines with multithread support for Kotlin/Native]: https://github.com/Kotlin/kotlinx.coroutines/issues/462
 [Coroutine scope]: https://kotlinlang.org/docs/reference/coroutines/coroutine-context-and-dispatchers.html#coroutine-scope
+[`ScanSettings`]: https://developer.android.com/reference/kotlin/android/bluetooth/le/ScanSettings
 
 [`Advertisement`]: https://juullabs.github.io/kable/core/core/com.juul.kable/-advertisement/index.html
 [`advertisements`]: https://juullabs.github.io/kable/core/core/com.juul.kable/-scanner/index.html#%5Bcom.juul.kable%2FScanner%2Fadvertisements%2F%23%2FPointingToDeclaration%2F%5D%2FProperties%2F-328684452

core/api/core.api

@@ -158,6 +158,9 @@ public final class com/juul/kable/NotReadyException : java/io/IOException {
 	public fun <init> ()V
 }
 
+public abstract interface annotation class com/juul/kable/ObsoleteKableApi : java/lang/annotation/Annotation {
+}
+
 public final class com/juul/kable/OutOfOrderGattCallbackException : java/lang/IllegalStateException {
 }
 
@@ -227,8 +230,10 @@ public abstract interface class com/juul/kable/Scanner {
 
 public final class com/juul/kable/ScannerBuilder {
 	public fun <init> ()V
+	public final fun getScanSettings ()Landroid/bluetooth/le/ScanSettings;
 	public final fun getServices ()Ljava/util/List;
 	public final fun logging (Lkotlin/jvm/functions/Function1;)V
+	public final fun setScanSettings (Landroid/bluetooth/le/ScanSettings;)V
 	public final fun setServices (Ljava/util/List;)V
 }
 

core/src/androidMain/kotlin/Scanner.kt

@@ -22,6 +22,7 @@ public class ScanFailedException internal constructor(
 
 public class AndroidScanner internal constructor(
     private val filterServices: List<Uuid>?,
+    private val scanSettings: ScanSettings,
     logging: Logging,
 ) : Scanner {
 
@@ -62,7 +63,7 @@ public class AndroidScanner internal constructor(
                 ?.toList()
         bluetoothAdapter.bluetoothLeScanner.startScan(
             scanFilter,
-            ScanSettings.Builder().build(),
+            scanSettings,
             callback,
         )
 

core/src/androidMain/kotlin/ScannerBuilder.kt

@@ -1,11 +1,22 @@
 package com.juul.kable
 
+import android.bluetooth.le.ScanSettings
 import com.benasher44.uuid.Uuid
 import com.juul.kable.logs.Logging
 import com.juul.kable.logs.LoggingBuilder
 
 public actual class ScannerBuilder {
     public actual var services: List<Uuid>? = null
+
+    /**
+     * Allows for the [Scanner] to be configured via Android's [ScanSettings].
+     *
+     * This property will be removed in a future version, and will be replaced by a Kable provided DSL for configuring
+     * scanning.
+     */
+    @ObsoleteKableApi
+    public var scanSettings: ScanSettings = ScanSettings.Builder().build()
+
     private var logging: Logging = Logging()
 
     public actual fun logging(init: LoggingBuilder) {
@@ -14,6 +25,7 @@ public actual class ScannerBuilder {
 
     internal actual fun build(): Scanner = AndroidScanner(
         filterServices = services,
+        scanSettings = scanSettings,
         logging = logging,
     )
 }

core/src/commonMain/kotlin/Annotations.kt

@@ -0,0 +1,15 @@
+// ktlint-disable filename
+
+package com.juul.kable
+
+/**
+ * Marks declarations that are **obsolete** in Kable API, which means that the design of the corresponding declarations
+ * has known flaws/drawbacks and they will be redesigned or replaced in the future.
+ *
+ * Roughly speaking, these declarations will be deprecated in the future but there is no replacement for them yet, so
+ * they cannot be deprecated right away.
+ */
+@MustBeDocumented
+@Retention(value = AnnotationRetention.BINARY)
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+public annotation class ObsoleteKableApi