webbluetooth_core/lib.rs
1//! The portable half of `webbluetooth`, and the contract its backends meet.
2//!
3//! Everything here is platform-independent: the error vocabulary, the UUID
4//! registry, the filters, the two blocklists, the grant store, the scan hub.
5//! None of it knows whether it is talking to CoreBluetooth, BlueZ, WinRT, the
6//! Android framework, a raw HCI socket or the browser's own Web Bluetooth.
7//!
8//! # Why this is a crate and not a module
9//!
10//! A backend has to reach this code — it converts platform errors into
11//! [`Error`], platform UUIDs into [`BluetoothUuid`], and publishes sightings
12//! into a [`ScanHub`](scan::ScanHub). While the backends lived in the same
13//! crate as the public API, "reach this code" meant `crate::`, and that cost
14//! two things.
15//!
16//! The first is that a backend could reach *anything*, including the public
17//! API above it, and three of them did. The second is that anything two
18//! backends both needed had nowhere to live: [`RestoredScan`] was written out
19//! six times, once per backend, because a shared type would have had to sit in
20//! a module that every backend could see and no backend could be sure of.
21//!
22//! # What checks that the backends agree
23//!
24//! Only one of them is ever compiled, so five are invisible to any one build.
25//! `tests/backend_surface.rs` reads all six as source and compares the methods
26//! they declare, on whatever host it runs on. A trait would have been the
27//! obvious mechanism and does not fit — three of those methods take
28//! `self: &Arc<Self>`, which a trait cannot declare, and a trait would still
29//! only check the backend already being compiled.
30//!
31//! # What is not here
32//!
33//! The Web Bluetooth objects themselves — `Bluetooth`, `BluetoothDevice`, the
34//! GATT tree — are in `webbluetooth`, above this. They are what a caller
35//! holds; this is what they are built out of.
36//!
37//! L2CAP is not here either, and for a different reason: a channel is a
38//! platform socket rather than a portable value, so the glue that adapts one
39//! lives in `webbluetooth` beside the backend selection. The specification has
40//! no L2CAP, so nothing in the portable model is missing it.
41//!
42//! # Stability
43//!
44//! This crate exists so `webbluetooth` and the six backend crates can share a
45//! vocabulary. Everything it exports is public because a backend in another
46//! crate has to name it — not because it is an API to build on. Depend on
47//! `webbluetooth`.
48
49// Re-exported so `forward_to_registry!`, expanded in a backend crate, can name
50// the channel type without that crate having to depend on futures-channel.
51// Everything public here is named by a backend in another crate, which makes
52// "what is this for" a question somebody actually has to answer.
53#![warn(missing_docs)]
54
55pub use futures_channel;
56
57pub mod adapter;
58pub mod address;
59pub mod backlog;
60pub mod blocklist;
61pub mod chooser;
62pub mod error;
63pub mod filter;
64pub mod gatt;
65pub mod grants;
66pub mod l2cap;
67/// The peripheral role's definitions: what a GATT server publishes.
68pub mod peripheral;
69pub mod registry;
70pub mod restoration;
71pub mod scan;
72pub mod state;
73pub mod timer;
74pub mod uuid;
75/// Conversions to and from the `uuid` crate's `Uuid`. Feature `uuid`.
76#[cfg(feature = "uuid")]
77mod uuid_interop;
78
79pub use adapter::{
80 AdapterInfo, ConnectionParameters, ConnectionPhy, ConnectionPriority, Pairing, Phy,
81};
82pub use chooser::{Candidate, Candidates, DeviceChooser};
83pub use error::{Authorization, Availability, Error, Result};
84pub use filter::{Advertisement, DataPrefix, DeviceFilter, RequestDeviceOptions};
85pub use gatt::{CharacteristicProperties, WriteType};
86pub use l2cap::{ChannelSink, Closed, L2capChannel, PlatformChannel, Psm};
87pub use restoration::{Restoration, RestoredScan};
88pub use state::ManagerState;
89pub use timer::{sleep, timeout};
90pub use uuid::{BluetoothUuid, IntoUuid};