Skip to content

Commit da1e394

Browse files
colemancdacolemancda
committed
Add availability annotations
1 parent 31ead5c commit da1e394

13 files changed

Lines changed: 321 additions & 28 deletions

‎Sources/AndroidBluetooth/AndroidCentral.swift‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,19 @@ import AndroidOS
2020
import AndroidContent
2121
import AndroidManifest
2222

23-
/// Android GATT Central
23+
/// Android GATT Central Manager implementation.
24+
///
25+
/// This class provides a GATT Central Manager implementation for Android using the Android Bluetooth APIs.
26+
/// It enables BLE scanning, device connection, service discovery, and characteristic operations.
27+
///
28+
/// The implementation requires Android API Level 18 or higher for basic BLE functionality.
29+
/// Some features require higher API levels:
30+
/// - API 21+: `BluetoothLeScanner` for improved scanning
31+
/// - API 23+: Transport selection for `connectGatt()`
32+
/// - API 31+: New permission model (`BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`)
33+
///
34+
/// - Since: API Level 18
35+
@available(Android 18, *)
2436
public final class AndroidCentral: CentralManager {
2537

2638
public typealias Advertisement = AndroidLowEnergyAdvertisementData

‎Sources/AndroidBluetooth/BluetoothA2dp.swift‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22
import SwiftJava
33
import CSwiftJavaJNI
44

5+
/// This class provides the public APIs to control the Bluetooth A2DP profile.
6+
///
7+
/// BluetoothA2dp is a proxy object for controlling the Bluetooth A2DP Service via IPC.
8+
/// Use `BluetoothAdapter.getProfileProxy()` to get the BluetoothA2dp proxy object.
9+
///
10+
/// Each method is protected with its appropriate permission.
11+
///
12+
/// - Since: API Level 11
13+
@available(Android 11, *)
514
@JavaClass("android.bluetooth.BluetoothA2dp", implements: BluetoothProfile.self)
615
open class BluetoothA2dp: JavaObject {
716
@JavaMethod

‎Sources/AndroidBluetooth/BluetoothAdapter.swift‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,17 @@ import JavaTime
66
import JavaUtil
77
import JavaLangUtil
88

9+
/// Represents the local device Bluetooth adapter.
10+
///
11+
/// The `BluetoothAdapter` lets you perform fundamental Bluetooth tasks, such as initiate
12+
/// device discovery, query a list of bonded (paired) devices, instantiate a `BluetoothDevice` using a known MAC address,
13+
/// and create a `BluetoothServerSocket` to listen for connection requests from other devices, and start a scan for Bluetooth LE devices.
14+
///
15+
/// To get a `BluetoothAdapter` representing the local Bluetooth adapter, call the `BluetoothManager.getAdapter()` method on `BluetoothManager`.
16+
/// On API level 17 and lower, use the static `getDefaultAdapter()` method.
17+
///
18+
/// - Since: API Level 5
19+
@available(Android 5, *)
920
@JavaClass("android.bluetooth.BluetoothAdapter")
1021
open class BluetoothAdapter: JavaObject {
1122
@JavaMethod
@@ -32,9 +43,20 @@ open class BluetoothAdapter: JavaObject {
3243
@JavaMethod
3344
open func isDiscovering() -> Bool
3445

46+
/// Returns whether LE 2M PHY feature is supported.
47+
///
48+
/// - Returns: `true` if chipset supports LE 2M PHY feature, `false` otherwise.
49+
/// - Since: API Level 26
50+
@available(Android 26, *)
3551
@JavaMethod
3652
open func isLe2MPhySupported() -> Bool
3753

54+
/// Returns whether LE Audio is supported.
55+
///
56+
/// - Returns: `FEATURE_SUPPORTED` if LE Audio is supported, `FEATURE_NOT_SUPPORTED` if not supported,
57+
/// or an error code.
58+
/// - Since: API Level 33
59+
@available(Android 33, *)
3860
@JavaMethod
3961
open func isLeAudioSupported() -> Int32
4062

@@ -47,21 +69,51 @@ open class BluetoothAdapter: JavaObject {
4769
@JavaMethod
4870
open func closeProfileProxy(_ arg0: Int32, _ arg1: BluetoothProfile?)
4971

72+
/// Starts a scan for Bluetooth LE devices, looking for devices that advertise given services.
73+
///
74+
/// - Since: API Level 18
75+
/// - Deprecated: Use `BluetoothLeScanner.startScan()` instead (API 21+)
76+
@available(Android 18, deprecated: 21, message: "Use BluetoothLeScanner.startScan() instead")
5077
@JavaMethod
5178
open func startLeScan(_ arg0: [UUID?], _ arg1: BluetoothAdapter.LeScanCallback?) -> Bool
5279

80+
/// Starts a scan for Bluetooth LE devices.
81+
///
82+
/// - Since: API Level 18
83+
/// - Deprecated: Use `BluetoothLeScanner.startScan()` instead (API 21+)
84+
@available(Android 18, deprecated: 21, message: "Use BluetoothLeScanner.startScan() instead")
5385
@JavaMethod
5486
open func startLeScan(_ arg0: BluetoothAdapter.LeScanCallback?) -> Bool
5587

88+
/// Stops an ongoing Bluetooth LE device scan.
89+
///
90+
/// - Since: API Level 18
91+
/// - Deprecated: Use `BluetoothLeScanner.stopScan()` instead (API 21+)
92+
@available(Android 18, deprecated: 21, message: "Use BluetoothLeScanner.stopScan() instead")
5693
@JavaMethod
5794
open func stopLeScan(_ arg0: BluetoothAdapter.LeScanCallback?)
5895

96+
/// Returns a `BluetoothLeAdvertiser` object for Bluetooth LE Advertising operations, or `nil` if Bluetooth LE Advertising is not supported on this adapter.
97+
///
98+
/// - Returns: `BluetoothLeAdvertiser` instance, or `nil` if not supported.
99+
/// - Since: API Level 21
100+
@available(Android 21, *)
59101
@JavaMethod
60102
open func getBluetoothLeAdvertiser() -> BluetoothLeAdvertiser!
61103

104+
/// Returns a `BluetoothLeScanner` object for Bluetooth LE scan operations.
105+
///
106+
/// - Returns: `BluetoothLeScanner` instance.
107+
/// - Since: API Level 21
108+
@available(Android 21, *)
62109
@JavaMethod
63110
open func getBluetoothLeScanner() -> BluetoothLeScanner!
64111

112+
/// Get the current discoverable timeout value.
113+
///
114+
/// - Returns: the discoverable timeout value in seconds.
115+
/// - Since: API Level 33
116+
@available(Android 33, *)
65117
@JavaMethod
66118
open func getDiscoverableTimeout() -> Duration!
67119

@@ -74,21 +126,52 @@ open class BluetoothAdapter: JavaObject {
74126
@JavaMethod
75127
open func isOffloadedScanBatchingSupported() -> Bool
76128

129+
/// Returns whether LE Coded PHY feature is supported.
130+
///
131+
/// - Returns: `true` if chipset supports LE Coded PHY feature, `false` otherwise.
132+
/// - Since: API Level 26
133+
@available(Android 26, *)
77134
@JavaMethod
78135
open func isLeCodedPhySupported() -> Bool
79136

137+
/// Returns whether LE Extended Advertising feature is supported.
138+
///
139+
/// - Returns: `true` if chipset supports LE Extended Advertising feature, `false` otherwise.
140+
/// - Since: API Level 26
141+
@available(Android 26, *)
80142
@JavaMethod
81143
open func isLeExtendedAdvertisingSupported() -> Bool
82144

145+
/// Returns whether LE Periodic Advertising feature is supported.
146+
///
147+
/// - Returns: `true` if chipset supports LE Periodic Advertising feature, `false` otherwise.
148+
/// - Since: API Level 26
149+
@available(Android 26, *)
83150
@JavaMethod
84151
open func isLePeriodicAdvertisingSupported() -> Bool
85152

153+
/// Returns whether LE Audio Broadcast Source is supported.
154+
///
155+
/// - Returns: `FEATURE_SUPPORTED` if supported, `FEATURE_NOT_SUPPORTED` if not supported,
156+
/// or an error code.
157+
/// - Since: API Level 33
158+
@available(Android 33, *)
86159
@JavaMethod
87160
open func isLeAudioBroadcastSourceSupported() -> Int32
88161

162+
/// Returns the maximum LE advertising data length in bytes, if LE Extended Advertising feature is supported.
163+
///
164+
/// - Returns: the maximum LE advertising data length.
165+
/// - Since: API Level 26
166+
@available(Android 26, *)
89167
@JavaMethod
90168
open func getLeMaximumAdvertisingDataLength() -> Int32
91169

170+
/// Returns the maximum number of connected audio devices.
171+
///
172+
/// - Returns: the maximum number of connected audio devices.
173+
/// - Since: API Level 30
174+
@available(Android 30, *)
92175
@JavaMethod
93176
open func getMaxConnectedAudioDevices() -> Int32
94177

@@ -98,12 +181,30 @@ open class BluetoothAdapter: JavaObject {
98181
@JavaMethod
99182
open func listenUsingRfcommWithServiceRecord(_ arg0: String, _ arg1: UUID?) throws -> BluetoothServerSocket!
100183

184+
/// Create a listening, secure L2CAP Connection-oriented Channel (CoC) `BluetoothServerSocket`.
185+
///
186+
/// - Returns: a listening L2CAP CoC `BluetoothServerSocket`.
187+
/// - Throws: IOException on error, for example Bluetooth not available, or insufficient permissions.
188+
/// - Since: API Level 29
189+
@available(Android 29, *)
101190
@JavaMethod
102191
open func listenUsingL2capChannel() throws -> BluetoothServerSocket!
103192

193+
/// Create a listening, insecure L2CAP Connection-oriented Channel (CoC) `BluetoothServerSocket`.
194+
///
195+
/// - Returns: a listening L2CAP CoC `BluetoothServerSocket`.
196+
/// - Throws: IOException on error, for example Bluetooth not available, or insufficient permissions.
197+
/// - Since: API Level 29
198+
@available(Android 29, *)
104199
@JavaMethod
105200
open func listenUsingInsecureL2capChannel() throws -> BluetoothServerSocket!
106201

202+
/// Returns whether LE Audio Broadcast Assistant is supported.
203+
///
204+
/// - Returns: `FEATURE_SUPPORTED` if supported, `FEATURE_NOT_SUPPORTED` if not supported,
205+
/// or an error code.
206+
/// - Since: API Level 33
207+
@available(Android 33, *)
107208
@JavaMethod
108209
open func isLeAudioBroadcastAssistantSupported() -> Int32
109210

‎Sources/AndroidBluetooth/BluetoothDevice.swift‎

Lines changed: 91 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,21 @@ import JavaUtil
77
import JavaLangUtil
88
import Bluetooth
99

10+
/// Represents a remote Bluetooth device.
11+
///
12+
/// A `BluetoothDevice` lets you create a connection with the respective device or query
13+
/// information about it, such as the name, address, class, and bonding state.
14+
///
15+
/// This class is really just a thin wrapper for a Bluetooth hardware address. Objects of
16+
/// this class are immutable. Operations on this class are performed on the remote Bluetooth
17+
/// hardware address, using the `BluetoothAdapter` that was used to create this `BluetoothDevice`.
18+
///
19+
/// To get a `BluetoothDevice`, use `BluetoothAdapter.getRemoteDevice(String)` to create one
20+
/// representing a device of a known MAC address (which you can get through device discovery with `BluetoothAdapter`)
21+
/// or get one from the set of bonded devices returned by `BluetoothAdapter.getBondedDevices()`.
22+
///
23+
/// - Since: API Level 5
24+
@available(Android 5, *)
1025
@JavaClass("android.bluetooth.BluetoothDevice", implements: Parcelable.self)
1126
open class BluetoothDevice: JavaObject {
1227
@JavaMethod
@@ -15,15 +30,28 @@ open class BluetoothDevice: JavaObject {
1530
@JavaMethod
1631
open func writeToParcel(_ arg0: Parcel?, _ arg1: Int32)
1732

18-
/**
19-
Returns the address type of this BluetoothDevice, one of ADDRESS_TYPE_PUBLIC, ADDRESS_TYPE_RANDOM, ADDRESS_TYPE_ANONYMOUS, or ADDRESS_TYPE_UNKNOWN.
20-
*/
33+
/// Returns the address type of this BluetoothDevice.
34+
///
35+
/// - Returns: One of `ADDRESS_TYPE_PUBLIC`, `ADDRESS_TYPE_RANDOM`, `ADDRESS_TYPE_ANONYMOUS`, or `ADDRESS_TYPE_UNKNOWN`.
36+
/// - Since: API Level 31
37+
@available(Android 31, *)
2138
@JavaMethod
2239
open func getAddressType() -> Int32
2340

41+
/// Get the locally modifiable name (alias) of the remote device.
42+
///
43+
/// - Returns: the locally modifiable name (alias) of the remote device, or `null` if not set.
44+
/// - Since: API Level 31
45+
@available(Android 31, *)
2446
@JavaMethod
2547
open func getAlias() -> String
2648

49+
/// Sets the locally modifiable name (alias) of the remote device.
50+
///
51+
/// - Parameter arg0: the alias to set, or `null` to remove the alias.
52+
/// - Returns: status code indicating whether the operation succeeded.
53+
/// - Since: API Level 31
54+
@available(Android 31, *)
2755
@JavaMethod
2856
open func setAlias(_ arg0: String) -> Int32
2957

@@ -45,25 +73,36 @@ open class BluetoothDevice: JavaObject {
4573
@JavaMethod
4674
open func setPin(_ arg0: [Int8]) -> Bool
4775

48-
/**
49-
Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
50-
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
51-
52-
Requires `Manifest.permission.BLUETOOTH_CONNECT`
53-
*/
76+
/// Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
77+
/// For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
78+
///
79+
/// - Parameter context: The running app's context.
80+
/// - Parameter autoConnect: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
81+
/// - Parameter callback: GATT callback handler that will receive asynchronous callbacks.
82+
/// - Returns: The `BluetoothGatt` instance.
83+
/// - Throws: IllegalArgumentException if callback is null.
84+
/// - Note: Requires `Manifest.permission.BLUETOOTH_CONNECT`
85+
/// - Since: API Level 18
86+
@available(Android 18, *)
5487
@JavaMethod
5588
public func connectGatt(
5689
context: AndroidContent.Context?,
5790
autoConnect: Bool,
5891
callback: BluetoothGattCallback?
5992
) throws -> BluetoothGatt!
6093

61-
/**
62-
Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
63-
For apps targeting `Build.VERSION_CODES.S` or or higher, this requires the `Manifest.permission.BLUETOOTH_CONNECT` permission which can be gained with Activity.requestPermissions(String[], int).
64-
65-
Requires `Manifest.permission.BLUETOOTH_CONNECT`
66-
*/
94+
/// Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
95+
/// For apps targeting `Build.VERSION_CODES.S` or or higher, this requires the `Manifest.permission.BLUETOOTH_CONNECT` permission which can be gained with Activity.requestPermissions(String[], int).
96+
///
97+
/// - Parameter context: The running app's context.
98+
/// - Parameter autoConnect: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
99+
/// - Parameter callback: GATT callback handler that will receive asynchronous callbacks.
100+
/// - Parameter transport: Preferred transport for GATT connections to remote dual-mode devices.
101+
/// - Returns: The `BluetoothGatt` instance.
102+
/// - Throws: IllegalArgumentException if callback is null.
103+
/// - Note: Requires `Manifest.permission.BLUETOOTH_CONNECT`
104+
/// - Since: API Level 23
105+
@available(Android 23, *)
67106
@JavaMethod
68107
internal func connectGatt(
69108
_ context: AndroidContent.Context?,
@@ -75,31 +114,36 @@ open class BluetoothDevice: JavaObject {
75114
/// Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations.
76115
///
77116
/// - Parameter context: The running app's context.
78-
///
79117
/// - Parameter autoConnect: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
80-
///
81118
/// - Parameter callback: GATT callback handler that will receive asynchronous callbacks.
82-
///
83119
/// - Parameter transport: Preferred transport for GATT connections to remote dual-mode devices
84-
///
85120
/// - Returns: The method returns a ``BluetoothGatt`` instance.
86-
///
121+
/// - Throws: IllegalArgumentException if callback is null.
87122
/// - Note: Requires `Manifest.permission.BLUETOOTH_CONNECT`
123+
/// - Since: API Level 23
124+
@available(Android 23, *)
88125
public func connectGatt(
89126
context: AndroidContent.Context,
90127
autoConnect: Bool = false,
91128
callback: BluetoothGattCallback,
92129
transport: BluetoothTransport = .auto
93-
) throws-> BluetoothGatt! {
130+
) throws -> BluetoothGatt! {
94131
try connectGatt(context, autoConnect, callback, transport.rawValue)
95132
}
96133

97-
/**
98-
Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
99-
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
100-
101-
Requires Manifest.permission.BLUETOOTH_CONNECT
102-
*/
134+
/// Connect to GATT Server hosted by this device. Caller acts as GATT client. The callback is used to deliver results to Caller, such as connection status as well as any further GATT client operations. The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct GATT client operations.
135+
/// For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_CONNECT permission which can be gained with Activity.requestPermissions(String[], int).
136+
///
137+
/// - Parameter context: The running app's context.
138+
/// - Parameter autoConnect: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).
139+
/// - Parameter callback: GATT callback handler that will receive asynchronous callbacks.
140+
/// - Parameter transport: Preferred transport for GATT connections to remote dual-mode devices.
141+
/// - Parameter phy: preferred PHY for connections to remote LE device.
142+
/// - Returns: The `BluetoothGatt` instance.
143+
/// - Throws: IllegalArgumentException if callback is null.
144+
/// - Note: Requires `Manifest.permission.BLUETOOTH_CONNECT`
145+
/// - Since: API Level 26
146+
@available(Android 26, *)
103147
@JavaMethod
104148
public func connectGatt(
105149
_ context: AndroidContent.Context?,
@@ -119,15 +163,35 @@ open class BluetoothDevice: JavaObject {
119163
_ handler: Handler?
120164
) -> BluetoothGatt!
121165
*/
166+
/// Create an L2CAP Connection-oriented Channel (CoC) `BluetoothSocket` that can be used to start a secure outgoing connection to the remote device with the same dynamic protocol/service multiplexer (PSM) value.
167+
///
168+
/// - Parameter arg0: dynamic PSM value from remote device.
169+
/// - Returns: a Bluetooth L2CAP CoC socket ready for outgoing connection.
170+
/// - Throws: IOException on error, for example Bluetooth not available, or insufficient permissions.
171+
/// - Since: API Level 29
172+
@available(Android 29, *)
122173
@JavaMethod
123174
open func createL2capChannel(_ arg0: Int32) throws -> BluetoothSocket!
124175

176+
/// Confirm passkey for BLUETOOTH_ADMIN_PERM.
177+
///
178+
/// - Parameter arg0: `true` to confirm the passkey, `false` to decline.
179+
/// - Returns: `true` confirmation has been sent out, `false` for error.
180+
/// - Since: API Level 19
181+
@available(Android 19, *)
125182
@JavaMethod
126183
open func setPairingConfirmation(_ arg0: Bool) -> Bool
127184

128185
@JavaMethod
129186
open func createRfcommSocketToServiceRecord(_ arg0: UUID?) throws -> BluetoothSocket!
130187

188+
/// Create an L2CAP Connection-oriented Channel (CoC) `BluetoothSocket` that can be used to start an insecure outgoing connection to the remote device with the same dynamic protocol/service multiplexer (PSM) value.
189+
///
190+
/// - Parameter arg0: dynamic PSM value from remote device.
191+
/// - Returns: a Bluetooth L2CAP CoC socket ready for outgoing connection.
192+
/// - Throws: IOException on error, for example Bluetooth not available, or insufficient permissions.
193+
/// - Since: API Level 29
194+
@available(Android 29, *)
131195
@JavaMethod
132196
open func createInsecureL2capChannel(_ arg0: Int32) throws -> BluetoothSocket!
133197

0 commit comments

Comments
 (0)