Skip to main content

Crate webbluetooth_core

Crate webbluetooth_core 

Source
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
requestDevice options, 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.