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}