Skip to main content

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}