Expand description
The portable half of webbluetooth, and the contract its backends meet.
Everything here is platform-independent: the error vocabulary, the UUID registry, the filters, the two blocklists, the grant store, the scan hub. None of it knows whether it is talking to CoreBluetooth, BlueZ, WinRT, the Android framework, a raw HCI socket or the browser’s own Web Bluetooth.
§Why this is a crate and not a module
A backend has to reach this code — it converts platform errors into
Error, platform UUIDs into BluetoothUuid, and publishes sightings
into a ScanHub. While the backends lived in the same
crate as the public API, “reach this code” meant crate::, and that cost
two things.
The first is that a backend could reach anything, including the public
API above it, and three of them did. The second is that anything two
backends both needed had nowhere to live: RestoredScan was written out
six times, once per backend, because a shared type would have had to sit in
a module that every backend could see and no backend could be sure of.
§What checks that the backends agree
Only one of them is ever compiled, so five are invisible to any one build.
tests/backend_surface.rs reads all six as source and compares the methods
they declare, on whatever host it runs on. A trait would have been the
obvious mechanism and does not fit — three of those methods take
self: &Arc<Self>, which a trait cannot declare, and a trait would still
only check the backend already being compiled.
§What is not here
The Web Bluetooth objects themselves — Bluetooth, BluetoothDevice, the
GATT tree — are in webbluetooth, above this. They are what a caller
holds; this is what they are built out of.
L2CAP is not here either, and for a different reason: a channel is a
platform socket rather than a portable value, so the glue that adapts one
lives in webbluetooth beside the backend selection. The specification has
no L2CAP, so nothing in the portable model is missing it.
§Stability
This crate exists so webbluetooth and the six backend crates can share a
vocabulary. Everything it exports is public because a backend in another
crate has to name it — not because it is an API to build on. Depend on
webbluetooth.
Re-exports§
pub use adapter::AdapterInfo;pub use adapter::ConnectionParameters;pub use adapter::ConnectionPhy;pub use adapter::ConnectionPriority;pub use adapter::Pairing;pub use adapter::Phy;pub use capabilities::Protocol;pub use capabilities::ProtocolCapabilities;pub use chooser::Candidate;pub use chooser::Candidates;pub use chooser::DeviceChooser;pub use error::Authorization;pub use error::Availability;pub use error::Error;pub use error::Result;pub use filter::Advertisement;pub use filter::DataPrefix;pub use filter::DeviceFilter;pub use filter::RequestDeviceOptions;pub use gatt::CharacteristicProperties;pub use gatt::WriteType;pub use l2cap::ChannelSink;pub use l2cap::Closed;pub use l2cap::L2capChannel;pub use l2cap::PlatformChannel;pub use l2cap::Psm;pub use restoration::Restoration;pub use restoration::RestoredScan;pub use state::ManagerState;pub use timer::sleep;pub use timer::timeout;pub use uuid::BluetoothUuid;pub use uuid::IntoUuid;pub use futures_channel;
Modules§
- adapter
- The controllers themselves.
- address
- Telling a Bluetooth address from a platform-minted device identifier.
- backlog
- A bounded queue for things a peer sends us.
- blocklist
- The GATT blocklist.
- capabilities
- Compile-time Bluetooth protocol capability reporting.
- chooser
- Choosing a device — the part a browser draws a dialog for.
- error
- Errors, named after the
DOMExceptions the Web Bluetooth spec throws. - filter
requestDeviceoptions, and matching them against an advertisement.- gatt
- The two attribute value-types the backends and the GATT tree share.
- grants
- Grants that outlive the process.
- l2cap
- L2CAP connection-oriented channels — the portable half.
- peripheral
- The peripheral role’s definitions: what a GATT server publishes. What a peripheral publishes, independent of how.
- registry
- The device registry, shared by every backend.
- restoration
- Picking up a Bluetooth session the system interrupted.
- scan
- Fan-out for the one radio scan a controller can run.
- state
- What the adapter is doing, and what that means for a caller.
- timer
- Runtime-agnostic timers.
- uuid
BluetoothUUID— always the canonical 128-bit lowercase form.
Macros§
- forward_
to_ registry - The methods every backend forwards to its registry, unchanged.