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;
18pub mod dex;
19pub mod jni;
20pub mod l2cap;
21pub mod runtime;
22
23use dex::DexBuilder;
24
25/// The package the generated classes live in.
26pub const PACKAGE: &str = "dev/webbluetooth";
27
28/// Every callback class this crate synthesises, as `(name, dex)`.
29///
30/// Each one subclasses an abstract Android callback and declares its overrides
31/// `native`, so `RegisterNatives` can bind them to Rust functions. The method
32/// signatures are the ones Android declares — a mismatch does not fail at
33/// registration, it fails the first time the framework tries to call in.
34pub fn dex_classes() -> Vec<(&'static str, Vec<u8>)> {
35    vec![
36        ("gatt", gatt_callback_dex()),
37        ("scan", scan_callback_dex()),
38        ("server", gatt_server_callback_dex()),
39        ("advertise", advertise_callback_dex()),
40    ]
41}
42
43/// `BluetoothGattCallback` — the GATT client.
44pub fn gatt_callback_dex() -> Vec<u8> {
45    // Built from the native table rather than beside it.
46    //
47    // `RegisterNatives` rejects the whole table if a single name is not
48    // declared by the class, so the two have to agree exactly. They used to be
49    // two lists with a test counting them, which catches a mismatch only after
50    // someone writes one — and is fixed by editing the count. Deriving one
51    // from the other means there is nothing to keep in step.
52    let mut builder = DexBuilder::new(
53        &format!("{PACKAGE}/GattCallback"),
54        "android/bluetooth/BluetoothGattCallback",
55    );
56    for (name, descriptor, _) in crate::bluetooth::gatt_natives() {
57        builder = builder.native_method(name, descriptor);
58    }
59    builder.build()
60}
61
62/// `ScanCallback` — LE discovery.
63pub fn scan_callback_dex() -> Vec<u8> {
64    DexBuilder::new(
65        &format!("{PACKAGE}/ScanCallback"),
66        "android/bluetooth/le/ScanCallback",
67    )
68    .native_method("onScanResult", "(ILandroid/bluetooth/le/ScanResult;)V")
69    .native_method("onBatchScanResults", "(Ljava/util/List;)V")
70    .native_method("onScanFailed", "(I)V")
71    .build()
72}
73
74/// `BluetoothGattServerCallback` — the peripheral role.
75pub fn gatt_server_callback_dex() -> Vec<u8> {
76    const DEVICE: &str = "Landroid/bluetooth/BluetoothDevice;";
77    const CHARACTERISTIC: &str = "Landroid/bluetooth/BluetoothGattCharacteristic;";
78    const DESCRIPTOR: &str = "Landroid/bluetooth/BluetoothGattDescriptor;";
79    const SERVICE: &str = "Landroid/bluetooth/BluetoothGattService;";
80    DexBuilder::new(
81        &format!("{PACKAGE}/GattServerCallback"),
82        "android/bluetooth/BluetoothGattServerCallback",
83    )
84    .native_method("onConnectionStateChange", &format!("({DEVICE}II)V"))
85    .native_method("onServiceAdded", &format!("(I{SERVICE})V"))
86    .native_method(
87        "onCharacteristicReadRequest",
88        &format!("({DEVICE}II{CHARACTERISTIC})V"),
89    )
90    .native_method(
91        "onCharacteristicWriteRequest",
92        &format!("({DEVICE}I{CHARACTERISTIC}ZZI[B)V"),
93    )
94    .native_method(
95        "onDescriptorReadRequest",
96        &format!("({DEVICE}II{DESCRIPTOR})V"),
97    )
98    .native_method(
99        "onDescriptorWriteRequest",
100        &format!("({DEVICE}I{DESCRIPTOR}ZZI[B)V"),
101    )
102    .native_method("onNotificationSent", &format!("({DEVICE}I)V"))
103    .native_method("onMtuChanged", &format!("({DEVICE}I)V"))
104    .build()
105}
106
107/// `AdvertiseCallback` — advertising.
108pub fn advertise_callback_dex() -> Vec<u8> {
109    DexBuilder::new(
110        &format!("{PACKAGE}/AdvertiseCallback"),
111        "android/bluetooth/le/AdvertiseCallback",
112    )
113    .native_method(
114        "onStartSuccess",
115        "(Landroid/bluetooth/le/AdvertiseSettings;)V",
116    )
117    .native_method("onStartFailure", "(I)V")
118    .build()
119}