Skip to main content

webbluetooth_core/
gatt.rs

1//! The two attribute value-types the backends and the GATT tree share.
2//!
3//! They live here rather than beside `RemoteGattCharacteristic` because a
4//! backend produces them — every one of the six converts its platform's
5//! spelling of the properties byte on the way in — while the GATT tree only
6//! reads them. Anything both sides name has to sit below both.
7
8/// What a characteristic supports — `BluetoothCharacteristicProperties`.
9///
10/// The bit values are the Bluetooth ones, which CoreBluetooth uses directly and
11/// BlueZ spells as a list of flag strings; each backend converts on the way in.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
13pub struct CharacteristicProperties(pub u32);
14
15impl CharacteristicProperties {
16    /// Broadcast in an advertisement, via the Server Characteristic Configuration descriptor.
17    pub const BROADCAST: u32 = 0x001;
18    /// `readValue()` is permitted.
19    pub const READ: u32 = 0x002;
20    /// `writeValueWithoutResponse()` is permitted — no ATT acknowledgement.
21    pub const WRITE_WITHOUT_RESPONSE: u32 = 0x004;
22    /// `writeValueWithResponse()` is permitted.
23    pub const WRITE: u32 = 0x008;
24    /// The peer can push values, unacknowledged.
25    pub const NOTIFY: u32 = 0x010;
26    /// The peer can push values, each one acknowledged.
27    pub const INDICATE: u32 = 0x020;
28    /// Signed writes without a response are permitted.
29    pub const AUTHENTICATED_SIGNED_WRITES: u32 = 0x040;
30    /// A Characteristic Extended Properties descriptor exists.
31    ///
32    /// Says the descriptor is there, not what is in it — the two bits below
33    /// are what is in it.
34    pub const EXTENDED_PROPERTIES: u32 = 0x080;
35    /// Notifications require an encrypted link. CoreBluetooth's own bit; not in the ATT properties byte.
36    pub const NOTIFY_ENCRYPTION_REQUIRED: u32 = 0x100;
37    /// Indications require an encrypted link. CoreBluetooth's own bit.
38    pub const INDICATE_ENCRYPTION_REQUIRED: u32 = 0x200;
39    // The two bits below are *not* in the characteristic's properties byte.
40    // They live in the Characteristic Extended Properties descriptor, which
41    // `EXTENDED_PROPERTIES` merely says exists. These values continue past
42    // CoreBluetooth's, which stops at 0x200, so nothing collides.
43    /// Queued writes are permitted — a bit *inside* the Extended Properties descriptor.
44    pub const RELIABLE_WRITE: u32 = 0x400;
45    /// The User Description descriptor is writable — also inside Extended Properties.
46    pub const WRITABLE_AUXILIARIES: u32 = 0x800;
47
48    /// Whether one of the bits above is set.
49    #[inline]
50    pub fn has(self, bit: u32) -> bool {
51        self.0 & bit != 0
52    }
53    /// Whether [`Self::BROADCAST`] is set — `broadcast`.
54    #[inline]
55    pub fn broadcast(self) -> bool {
56        self.has(Self::BROADCAST)
57    }
58    /// Whether [`Self::READ`] is set — `read`.
59    #[inline]
60    pub fn read(self) -> bool {
61        self.has(Self::READ)
62    }
63    /// Whether [`Self::WRITE_WITHOUT_RESPONSE`] is set — `writeWithoutResponse`.
64    #[inline]
65    pub fn write_without_response(self) -> bool {
66        self.has(Self::WRITE_WITHOUT_RESPONSE)
67    }
68    /// Whether [`Self::WRITE`] is set — `write`.
69    #[inline]
70    pub fn write(self) -> bool {
71        self.has(Self::WRITE)
72    }
73    /// Whether [`Self::NOTIFY`] is set — `notify`.
74    #[inline]
75    pub fn notify(self) -> bool {
76        self.has(Self::NOTIFY)
77    }
78    /// Whether [`Self::INDICATE`] is set — `indicate`.
79    #[inline]
80    pub fn indicate(self) -> bool {
81        self.has(Self::INDICATE)
82    }
83    /// Whether [`Self::AUTHENTICATED_SIGNED_WRITES`] is set — `authenticatedSignedWrites`.
84    #[inline]
85    pub fn authenticated_signed_writes(self) -> bool {
86        self.has(Self::AUTHENTICATED_SIGNED_WRITES)
87    }
88    /// Whether an Extended Properties descriptor exists.
89    ///
90    /// Not the same question as [`Self::reliable_write`]: this says the
91    /// descriptor is there, not what is in it.
92    #[inline]
93    pub fn extended_properties(self) -> bool {
94        self.has(Self::EXTENDED_PROPERTIES)
95    }
96
97    /// `reliableWrite` — queued writes are applied atomically.
98    ///
99    /// Reported only where the platform distinguishes it. BlueZ and WinRT list
100    /// it as its own flag; CoreBluetooth and Android expose nothing beyond
101    /// "there is an Extended Properties descriptor", so on those this is
102    /// `false` even when the peer supports it, and
103    /// [`Self::extended_properties`] is what there is to go on.
104    #[inline]
105    pub fn reliable_write(self) -> bool {
106        self.has(Self::RELIABLE_WRITE)
107    }
108
109    /// `writableAuxiliaries` — the Characteristic User Description descriptor
110    /// is writable. Same platform caveat as [`Self::reliable_write`].
111    #[inline]
112    pub fn writable_auxiliaries(self) -> bool {
113        self.has(Self::WRITABLE_AUXILIARIES)
114    }
115}
116
117/// Whether a write waits for the peer to acknowledge it.
118#[derive(Debug, Clone, Copy, PartialEq, Eq)]
119pub enum WriteType {
120    /// Wait for the peer's ATT acknowledgement, and report a failure.
121    WithResponse,
122    /// Send and carry on. Faster, and the peer never says whether it arrived.
123    WithoutResponse,
124}