webbluetooth_core/state.rs
1//! What the adapter is doing, and what that means for a caller.
2//!
3//! Every backend needs this enum and every backend needs the same mapping from
4//! it to [`Availability`], so both live here once. They used to be declared
5//! four times and matched on six times, which is four places for the enum to
6//! drift and six for the mapping to disagree.
7
8use crate::error::{Availability, Error, Result};
9
10/// Mirrors `CBManagerState`, which is the most detailed of the platforms'
11/// answers; the others widen into it.
12///
13/// This is the union of what the platforms can report, so on any one target
14/// some variants are never constructed — Android reads its adapter state
15/// synchronously and is never `Unknown`; Windows never reports `Unauthorized`
16/// because WinRT fails the call instead. That is a fact about each platform
17/// rather than dead code, and every variant is still matched in
18/// [`Self::availability`].
19#[allow(dead_code)]
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub enum ManagerState {
22 /// Not yet reported, or reported as resetting.
23 Unknown,
24 /// This machine has no Bluetooth LE.
25 Unsupported,
26 /// This process may not use it.
27 Unauthorized,
28 /// The radio is off.
29 PoweredOff,
30 /// Usable.
31 PoweredOn,
32}
33
34impl ManagerState {
35 /// Whether Bluetooth can be used, and if not, why.
36 pub fn availability(self) -> std::result::Result<(), Availability> {
37 match self {
38 Self::PoweredOn => Ok(()),
39 Self::PoweredOff => Err(Availability::PoweredOff),
40 Self::Unauthorized => Err(Availability::Unauthorized),
41 Self::Unsupported => Err(Availability::Unsupported),
42 Self::Unknown => Err(Availability::Unknown),
43 }
44 }
45
46 /// The same question, as the error an operation should fail with.
47 pub fn require_powered_on(self) -> Result<()> {
48 self.availability().map_err(Error::NotAvailable)
49 }
50}
51
52#[cfg(test)]
53mod tests {
54 use super::*;
55
56 #[test]
57 fn only_powered_on_is_usable() {
58 assert!(ManagerState::PoweredOn.availability().is_ok());
59 for state in [
60 ManagerState::PoweredOff,
61 ManagerState::Unauthorized,
62 ManagerState::Unsupported,
63 ManagerState::Unknown,
64 ] {
65 assert!(state.availability().is_err(), "{state:?} is not usable");
66 }
67 }
68
69 /// The distinction matters to a caller: "turn Bluetooth on" and "this
70 /// machine has none" call for different responses, so the reason has to
71 /// survive the mapping rather than collapsing into one error.
72 #[test]
73 fn the_reason_survives() {
74 assert_eq!(
75 ManagerState::PoweredOff.availability(),
76 Err(Availability::PoweredOff)
77 );
78 assert_eq!(
79 ManagerState::Unsupported.availability(),
80 Err(Availability::Unsupported)
81 );
82 assert!(matches!(
83 ManagerState::Unauthorized.require_powered_on(),
84 Err(Error::NotAvailable(Availability::Unauthorized))
85 ));
86 }
87}