Skip to main content

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 capabilities;
62pub mod chooser;
63/// Bluetooth Classic addresses, discovery vocabulary, and transport endpoints.
64#[cfg(feature = "classic")]
65pub mod classic;
66pub mod error;
67pub mod filter;
68pub mod gatt;
69pub mod grants;
70pub mod l2cap;
71#[cfg(feature = "le-audio")]
72pub mod le_audio;
73#[cfg(feature = "mesh")]
74pub mod mesh;
75/// The peripheral role's definitions: what a GATT server publishes.
76pub mod peripheral;
77#[cfg(feature = "profiles")]
78pub mod profiles;
79#[cfg(any(feature = "raw-acl", feature = "raw-sco", feature = "le-audio"))]
80pub mod raw;
81pub mod registry;
82pub mod restoration;
83pub mod scan;
84/// Bluetooth Classic SDP data elements and service records.
85#[cfg(feature = "classic")]
86pub mod sdp;
87pub mod state;
88pub mod timer;
89pub mod uuid;
90/// Conversions to and from the `uuid` crate's `Uuid`. Feature `uuid`.
91#[cfg(feature = "uuid")]
92mod uuid_interop;
93
94pub use adapter::{
95    AdapterInfo, ConnectionParameters, ConnectionPhy, ConnectionPriority, Pairing, Phy,
96};
97pub use capabilities::{Protocol, ProtocolCapabilities};
98pub use chooser::{Candidate, Candidates, DeviceChooser};
99#[cfg(feature = "classic")]
100pub use classic::{
101    BluetoothAddress, ClassOfDevice, ClassicAddressError, ClassicDevice, ClassicPsm,
102    ClassicSecurity, RfcommChannel,
103};
104pub use error::{Authorization, Availability, Error, Result};
105pub use filter::{Advertisement, DataPrefix, DeviceFilter, RequestDeviceOptions};
106pub use gatt::{CharacteristicProperties, WriteType};
107pub use l2cap::{ChannelSink, Closed, L2capChannel, PlatformChannel, Psm};
108#[cfg(feature = "le-audio")]
109pub use le_audio::{CodecError, IsoConfiguration, IsoMetadata, IsoStream, Lc3Codec, Lc3Frame};
110#[cfg(feature = "mesh")]
111pub use mesh::{
112    MeshAddress, MeshNetworkPdu, NetworkHeader, ProvisioningEvent, ProvisioningFailure,
113    ProvisioningSession, ProvisioningState, ProvisioningTransitionError,
114};
115#[cfg(feature = "profiles")]
116pub use profiles::a2dp::{
117    negotiate as negotiate_a2dp, negotiate_sbc_capabilities, negotiate_sbc_parameters,
118    AvdtpCapabilitiesError, AvdtpDiscoverError, AvdtpEndpointType, AvdtpError, AvdtpMediaType,
119    AvdtpMessageType, AvdtpPacketType, AvdtpResponse, AvdtpResponseResult, AvdtpSbcCapability,
120    AvdtpServiceCategory, AvdtpSignalIdentifier, AvdtpSignalingPacket,
121    AvdtpStreamEndpointDescriptor, AvdtpStreamEndpointId, Capability as A2dpCapability,
122    Codec as A2dpCodec, Configuration as A2dpConfiguration,
123    NegotiationError as A2dpNegotiationError, SbcAllocation, SbcChannelMode, SbcConfiguration,
124    SbcFrame, SbcMediaError, SbcMediaPacket,
125};
126#[cfg(feature = "profiles")]
127pub use profiles::avrcp::{
128    absolute_volume, playback_status, Command as AvrcpCommand, Event as AvrcpEvent,
129    Metadata as AvrcpMetadata, PassThrough as AvrcpPassThrough, PlaybackStatus,
130};
131#[cfg(feature = "profiles")]
132pub use profiles::data::{
133    parse_obex_header, DunState, ObexError, ObexHeader, ObexOperation, ObexPacket, PanRole,
134};
135#[cfg(feature = "profiles")]
136pub use profiles::hfp::{
137    encode_command, AtError, AtLine, AtParser, CallCommand, CallInfo, CallState,
138};
139#[cfg(feature = "profiles")]
140pub use profiles::hid::{
141    HidError, HidPacket, InputValue, ReportDescriptor, ReportField, TransactionType,
142};
143#[cfg(feature = "profiles")]
144pub use profiles::pan::{
145    ControlMessage as PanControlMessage, Error as PanError, Frame as PanFrame,
146    PacketType as PanPacketType,
147};
148#[cfg(feature = "profiles")]
149pub use profiles::{Profile, ProfileRequest, ProfileRole};
150#[cfg(feature = "raw-acl")]
151pub use raw::AclPacket;
152#[cfg(feature = "le-audio")]
153pub use raw::IsoPacket;
154#[cfg(feature = "raw-sco")]
155pub use raw::ScoPacket;
156pub use restoration::{Restoration, RestoredScan};
157#[cfg(feature = "classic")]
158pub use sdp::{SdpDataElement, SdpError, SdpServiceRecord};
159pub use state::ManagerState;
160pub use timer::{sleep, timeout};
161pub use uuid::{BluetoothUuid, IntoUuid};