From 7999fcb97d5e9ed461b1012c28770c370bf8f84a Mon Sep 17 00:00:00 2001 From: Travis Wyatt Date: Sun, 12 Apr 2020 12:33:52 -0700 Subject: [PATCH] Move KDoc to more discoverable classes/functions --- core/src/main/java/android/BluetoothDevice.kt | 19 +++++++++++++ core/src/main/java/device/CoroutinesDevice.kt | 20 ------------- core/src/main/java/gatt/CoroutinesGatt.kt | 23 --------------- core/src/main/java/gatt/Gatt.kt | 28 +++++++++++++++++++ 4 files changed, 47 insertions(+), 43 deletions(-) diff --git a/core/src/main/java/android/BluetoothDevice.kt b/core/src/main/java/android/BluetoothDevice.kt index d7af848..cc487d9 100644 --- a/core/src/main/java/android/BluetoothDevice.kt +++ b/core/src/main/java/android/BluetoothDevice.kt @@ -9,6 +9,25 @@ import android.content.Context import com.juul.able.device.ConnectGattResult import com.juul.able.device.CoroutinesDevice +/** + * Establishes a connection to the [BluetoothDevice], suspending until connection is successful or + * error occurs. + * + * To cancel an in-flight connection attempt, the Coroutine from which this method was called can be + * canceled: + * + * ``` + * fun connect(context: Context, device: BluetoothDevice) { + * connectJob = async { + * device.connectGatt(context) + * } + * } + * + * fun cancelConnection() { + * connectJob?.cancel() // cancels the above `connectGatt` + * } + * ``` + */ suspend fun BluetoothDevice.connectGatt( context: Context ): ConnectGattResult = asCoroutinesDevice().connectGatt(context) diff --git a/core/src/main/java/device/CoroutinesDevice.kt b/core/src/main/java/device/CoroutinesDevice.kt index f571052..2243f8e 100644 --- a/core/src/main/java/device/CoroutinesDevice.kt +++ b/core/src/main/java/device/CoroutinesDevice.kt @@ -9,7 +9,6 @@ import android.bluetooth.BluetoothGatt.STATE_CONNECTED import android.content.Context import android.os.RemoteException import com.juul.able.Able -import com.juul.able.android.connectGatt import com.juul.able.device.ConnectGattResult.Failure import com.juul.able.device.ConnectGattResult.Success import com.juul.able.gatt.CoroutinesGatt @@ -24,25 +23,6 @@ internal class CoroutinesDevice( private val device: BluetoothDevice ) : Device { - /** - * Establishes a connection to the [BluetoothDevice], suspending until connection is successful - * or error occurs. - * - * To cancel an in-flight connection attempt, the Coroutine from which this method was called - * can be canceled: - * - * ``` - * fun connect(context: Context, device: BluetoothDevice) { - * connectJob = async { - * device.connectGatt(context) - * } - * } - * - * fun cancelConnection() { - * connectJob?.cancel() // cancels the above `connectGatt` - * } - * ``` - */ override suspend fun connectGatt(context: Context): ConnectGattResult { val dispatcher = newSingleThreadContext("$DISPATCHER_NAME@$device") val callback = GattCallback(dispatcher) diff --git a/core/src/main/java/gatt/CoroutinesGatt.kt b/core/src/main/java/gatt/CoroutinesGatt.kt index 0f55064..7ec62de 100644 --- a/core/src/main/java/gatt/CoroutinesGatt.kt +++ b/core/src/main/java/gatt/CoroutinesGatt.kt @@ -52,19 +52,11 @@ class CoroutinesGatt internal constructor( } } - /** - * @throws [RemoteException] if underlying [BluetoothGatt.discoverServices] returns `false`. - * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. - */ override suspend fun discoverServices(): GattStatus = performBluetoothAction("discoverServices") { bluetoothGatt.discoverServices() } - /** - * @throws [RemoteException] if underlying [BluetoothGatt.readCharacteristic] returns `false`. - * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. - */ override suspend fun readCharacteristic( characteristic: BluetoothGattCharacteristic ): OnCharacteristicRead = @@ -72,12 +64,6 @@ class CoroutinesGatt internal constructor( bluetoothGatt.readCharacteristic(characteristic) } - /** - * @param value applied to [characteristic] when characteristic is written. - * @param writeType applied to [characteristic] when characteristic is written. - * @throws [RemoteException] if underlying [BluetoothGatt.writeCharacteristic] returns `false`. - * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. - */ override suspend fun writeCharacteristic( characteristic: BluetoothGattCharacteristic, value: ByteArray, @@ -89,11 +75,6 @@ class CoroutinesGatt internal constructor( bluetoothGatt.writeCharacteristic(characteristic) } - /** - * @param value applied to [descriptor] when descriptor is written. - * @throws [RemoteException] if underlying [BluetoothGatt.writeDescriptor] returns `false`. - * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. - */ override suspend fun writeDescriptor( descriptor: BluetoothGattDescriptor, value: ByteArray @@ -103,10 +84,6 @@ class CoroutinesGatt internal constructor( bluetoothGatt.writeDescriptor(descriptor) } - /** - * @throws [RemoteException] if underlying [BluetoothGatt.requestMtu] returns `false`. - * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. - */ override suspend fun requestMtu(mtu: Int): OnMtuChanged = performBluetoothAction("requestMtu") { bluetoothGatt.requestMtu(mtu) diff --git a/core/src/main/java/gatt/Gatt.kt b/core/src/main/java/gatt/Gatt.kt index f49b540..6b20cb0 100644 --- a/core/src/main/java/gatt/Gatt.kt +++ b/core/src/main/java/gatt/Gatt.kt @@ -14,8 +14,10 @@ import android.bluetooth.BluetoothGattDescriptor import android.bluetooth.BluetoothGattService import android.bluetooth.BluetoothProfile import android.bluetooth.BluetoothProfile.STATE_DISCONNECTED +import android.os.RemoteException import com.juul.able.Able import java.util.UUID +import kotlinx.coroutines.FlowPreview import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.firstOrNull import kotlinx.coroutines.flow.onEach @@ -80,26 +82,52 @@ class GattStatusFailure( interface Gatt { + @FlowPreview val onConnectionStateChange: Flow + + @FlowPreview val onCharacteristicChanged: Flow + /** + * @throws [RemoteException] if underlying [BluetoothGatt.discoverServices] returns `false`. + * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. + */ suspend fun discoverServices(): GattStatus val services: List fun getService(uuid: UUID): BluetoothGattService? + /** + * @throws [RemoteException] if underlying [BluetoothGatt.requestMtu] returns `false`. + * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. + */ suspend fun requestMtu(mtu: Int): OnMtuChanged + /** + * @throws [RemoteException] if underlying [BluetoothGatt.readCharacteristic] returns `false`. + * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. + */ suspend fun readCharacteristic( characteristic: BluetoothGattCharacteristic ): OnCharacteristicRead + /** + * @param value applied to [characteristic] when characteristic is written. + * @param writeType applied to [characteristic] when characteristic is written. + * @throws [RemoteException] if underlying [BluetoothGatt.writeCharacteristic] returns `false`. + * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. + */ suspend fun writeCharacteristic( characteristic: BluetoothGattCharacteristic, value: ByteArray, writeType: WriteType ): OnCharacteristicWrite + /** + * @param value applied to [descriptor] when descriptor is written. + * @throws [RemoteException] if underlying [BluetoothGatt.writeDescriptor] returns `false`. + * @throws [ConnectionLost] if [Gatt] disconnects while method is executing. + */ suspend fun writeDescriptor( descriptor: BluetoothGattDescriptor, value: ByteArray