Skip to main content

webbluetooth_android/
lib.rs

1//! Android BLE from pure Rust, with no dependencies.
2//!
3//! ## License
4//! MIT — Copyright © 2025 [Eugene Hauptmann](https://github.com/eugenehp)
5// The adapter: this platform expressed as the portable model.
6// Public so `webbluetooth` can reach it, and not an API anyone else
7// should call: the facade is what a caller holds. Hidden from the docs
8// for the same reason, which also keeps the same 38 adapter methods from
9// being documented six times over.
10#[doc(hidden)]
11pub mod backend;
12// The peripheral-role adapter: a GATT server expressed as the portable model.
13#[cfg(target_os = "android")]
14pub mod peripheral_backend;
15
16pub mod ble;
17pub mod bluetooth;
18#[cfg(feature = "classic-l2cap")]
19pub mod classic_l2cap;
20pub mod dex;
21pub mod jni;
22pub mod l2cap;
23#[cfg(feature = "rfcomm")]
24pub mod rfcomm;
25pub mod runtime;
26
27use dex::DexBuilder;
28
29/// The package the generated classes live in.
30pub const PACKAGE: &str = "dev/webbluetooth";
31
32/// Every callback class this crate synthesises, as `(name, dex)`.
33///
34/// Each one subclasses an abstract Android callback and declares its overrides
35/// `native`, so `RegisterNatives` can bind them to Rust functions. The method
36/// signatures are the ones Android declares — a mismatch does not fail at
37/// registration, it fails the first time the framework tries to call in.
38pub fn dex_classes() -> Vec<(&'static str, Vec<u8>)> {
39    vec![
40        ("gatt", gatt_callback_dex()),
41        ("scan", scan_callback_dex()),
42        #[cfg(feature = "classic")]
43        ("classic-discovery", classic_discovery_receiver_dex()),
44        ("server", gatt_server_callback_dex()),
45        ("advertise", advertise_callback_dex()),
46    ]
47}
48
49/// `BluetoothGattCallback` — the GATT client.
50pub fn gatt_callback_dex() -> Vec<u8> {
51    // Built from the native table rather than beside it.
52    //
53    // `RegisterNatives` rejects the whole table if a single name is not
54    // declared by the class, so the two have to agree exactly. They used to be
55    // two lists with a test counting them, which catches a mismatch only after
56    // someone writes one — and is fixed by editing the count. Deriving one
57    // from the other means there is nothing to keep in step.
58    let mut builder = DexBuilder::new(
59        &format!("{PACKAGE}/GattCallback"),
60        "android/bluetooth/BluetoothGattCallback",
61    );
62    for (name, descriptor, _) in crate::bluetooth::gatt_natives() {
63        builder = builder.native_method(name, descriptor);
64    }
65    builder.build()
66}
67
68/// `ScanCallback` — LE discovery.
69pub fn scan_callback_dex() -> Vec<u8> {
70    DexBuilder::new(
71        &format!("{PACKAGE}/ScanCallback"),
72        "android/bluetooth/le/ScanCallback",
73    )
74    .native_method("onScanResult", "(ILandroid/bluetooth/le/ScanResult;)V")
75    .native_method("onBatchScanResults", "(Ljava/util/List;)V")
76    .native_method("onScanFailed", "(I)V")
77    .build()
78}
79
80/// `BroadcastReceiver` — Bluetooth Classic discovery.
81#[cfg(feature = "classic")]
82pub fn classic_discovery_receiver_dex() -> Vec<u8> {
83    DexBuilder::new(
84        &format!("{PACKAGE}/ClassicDiscoveryReceiver"),
85        "android/content/BroadcastReceiver",
86    )
87    .native_method(
88        "onReceive",
89        "(Landroid/content/Context;Landroid/content/Intent;)V",
90    )
91    .build()
92}
93
94/// `BluetoothGattServerCallback` — the peripheral role.
95pub fn gatt_server_callback_dex() -> Vec<u8> {
96    const DEVICE: &str = "Landroid/bluetooth/BluetoothDevice;";
97    const CHARACTERISTIC: &str = "Landroid/bluetooth/BluetoothGattCharacteristic;";
98    const DESCRIPTOR: &str = "Landroid/bluetooth/BluetoothGattDescriptor;";
99    const SERVICE: &str = "Landroid/bluetooth/BluetoothGattService;";
100    DexBuilder::new(
101        &format!("{PACKAGE}/GattServerCallback"),
102        "android/bluetooth/BluetoothGattServerCallback",
103    )
104    .native_method("onConnectionStateChange", &format!("({DEVICE}II)V"))
105    .native_method("onServiceAdded", &format!("(I{SERVICE})V"))
106    .native_method(
107        "onCharacteristicReadRequest",
108        &format!("({DEVICE}II{CHARACTERISTIC})V"),
109    )
110    .native_method(
111        "onCharacteristicWriteRequest",
112        &format!("({DEVICE}I{CHARACTERISTIC}ZZI[B)V"),
113    )
114    .native_method(
115        "onDescriptorReadRequest",
116        &format!("({DEVICE}II{DESCRIPTOR})V"),
117    )
118    .native_method(
119        "onDescriptorWriteRequest",
120        &format!("({DEVICE}I{DESCRIPTOR}ZZI[B)V"),
121    )
122    .native_method("onNotificationSent", &format!("({DEVICE}I)V"))
123    .native_method("onMtuChanged", &format!("({DEVICE}I)V"))
124    .build()
125}
126
127/// `AdvertiseCallback` — advertising.
128pub fn advertise_callback_dex() -> Vec<u8> {
129    DexBuilder::new(
130        &format!("{PACKAGE}/AdvertiseCallback"),
131        "android/bluetooth/le/AdvertiseCallback",
132    )
133    .native_method(
134        "onStartSuccess",
135        "(Landroid/bluetooth/le/AdvertiseSettings;)V",
136    )
137    .native_method("onStartFailure", "(I)V")
138    .build()
139}