Skip to main content

bluetooth_host/gatt/
client.rs

1//! The GATT client: discovery, reads, writes and subscriptions on a peer's
2//! server (Core Vol 3, Part G, 4).
3
4use bluetooth_adv::Uuid;
5
6use super::{uuid, Characteristic, Descriptor, Properties, Service};
7use crate::att::{ecode, op};
8use crate::connection::Connection;
9use crate::error::{Error, Result};
10
11/// The GATT client of one connection.
12#[derive(Clone)]
13pub struct Client {
14    pub(crate) conn: Connection,
15}
16
17fn le16(b: &[u8], i: usize) -> Result<u16> {
18    b.get(i..i + 2)
19        .map(|s| u16::from_le_bytes([s[0], s[1]]))
20        .ok_or_else(|| Error::Protocol("short ATT response".into()))
21}
22
23fn not_found(e: &Error) -> bool {
24    matches!(e, Error::Att { code, .. } if *code == ecode::ATTRIBUTE_NOT_FOUND)
25}
26
27impl Client {
28    async fn request(&self, pdu: Vec<u8>) -> Result<Vec<u8>> {
29        let c = &self.conn;
30        c.state.att.request(&c.host, &c.state, pdu).await
31    }
32
33    fn mtu(&self) -> usize {
34        usize::from(self.conn.state.att.mtu())
35    }
36
37    /// Exchanges the ATT MTU, offering `mtu` (23 to 517); returns the one in use.
38    pub async fn exchange_mtu(&self, mtu: u16) -> Result<u16> {
39        let c = &self.conn;
40        c.state.att.exchange_mtu(&c.host, &c.state, mtu).await
41    }
42
43    /// Every primary service.
44    pub async fn services(&self) -> Result<Vec<Service>> {
45        let mut out = Vec::new();
46        let mut start = 0x0001u16;
47        loop {
48            let mut pdu = vec![op::READ_BY_GROUP_REQ];
49            pdu.extend_from_slice(&start.to_le_bytes());
50            pdu.extend_from_slice(&0xffffu16.to_le_bytes());
51            pdu.extend_from_slice(&uuid::PRIMARY_SERVICE.to_le_bytes());
52            let rsp = match self.request(pdu).await {
53                Ok(r) => r,
54                Err(e) if not_found(&e) => break,
55                Err(e) => return Err(e),
56            };
57            let len = usize::from(
58                *rsp.get(1)
59                    .ok_or_else(|| Error::Protocol("empty response".into()))?,
60            );
61            if len != 6 && len != 20 {
62                return Err(Error::Protocol(format!(
63                    "Read By Group Type entry length {len}"
64                )));
65            }
66            let mut last = start;
67            for e in rsp[2..].chunks_exact(len) {
68                let (s, end) = (le16(e, 0)?, le16(e, 2)?);
69                let u = Uuid::from_le_bytes(&e[4..])
70                    .ok_or_else(|| Error::Protocol("bad service UUID".into()))?;
71                out.push(Service {
72                    uuid: u,
73                    name: u.name(),
74                    primary: true,
75                    start: s,
76                    end,
77                    characteristics: Vec::new(),
78                });
79                last = end;
80            }
81            if last == 0xffff || last < start {
82                break;
83            }
84            start = last + 1;
85        }
86        Ok(out)
87    }
88
89    /// Primary services with one UUID.
90    pub async fn services_by_uuid(&self, service: Uuid) -> Result<Vec<Service>> {
91        let mut out = Vec::new();
92        let mut start = 0x0001u16;
93        loop {
94            let mut pdu = vec![op::FIND_BY_TYPE_REQ];
95            pdu.extend_from_slice(&start.to_le_bytes());
96            pdu.extend_from_slice(&0xffffu16.to_le_bytes());
97            pdu.extend_from_slice(&uuid::PRIMARY_SERVICE.to_le_bytes());
98            pdu.extend_from_slice(&super::uuid_bytes(&service));
99            let rsp = match self.request(pdu).await {
100                Ok(r) => r,
101                Err(e) if not_found(&e) => break,
102                Err(e) => return Err(e),
103            };
104            let mut last = start;
105            for e in rsp[1..].as_chunks::<4>().0 {
106                let (s, end) = (le16(e, 0)?, le16(e, 2)?);
107                out.push(Service {
108                    uuid: service,
109                    name: service.name(),
110                    primary: true,
111                    start: s,
112                    end,
113                    characteristics: Vec::new(),
114                });
115                last = end;
116            }
117            if last == 0xffff || last < start {
118                break;
119            }
120            start = last + 1;
121        }
122        Ok(out)
123    }
124
125    /// The services a service includes: (include declaration handle, service).
126    pub async fn included(&self, service: &Service) -> Result<Vec<(u16, Service)>> {
127        let found = self
128            .read_by_type_all(service.start, service.end, Uuid::Uuid16(uuid::INCLUDE))
129            .await?;
130        let mut out = Vec::new();
131        for (h, v) in found {
132            let (s, end) = (le16(&v, 0)?, le16(&v, 2)?);
133            let u = match v.len() {
134                6 => Uuid::Uuid16(le16(&v, 4)?),
135                // A 128-bit service UUID is not in the declaration; read it.
136                _ => Uuid::from_le_bytes(&self.read(s).await?)
137                    .ok_or_else(|| Error::Protocol("bad included UUID".into()))?,
138            };
139            out.push((
140                h,
141                Service {
142                    uuid: u,
143                    name: u.name(),
144                    primary: false,
145                    start: s,
146                    end,
147                    characteristics: Vec::new(),
148                },
149            ));
150        }
151        Ok(out)
152    }
153
154    /// The characteristics of a service.
155    pub async fn characteristics(&self, service: &Service) -> Result<Vec<Characteristic>> {
156        let decls = self
157            .read_by_type_all(
158                service.start,
159                service.end,
160                Uuid::Uuid16(uuid::CHARACTERISTIC),
161            )
162            .await?;
163        let mut out: Vec<Characteristic> = Vec::new();
164        for (h, v) in decls {
165            if v.len() != 5 && v.len() != 19 {
166                return Err(Error::Protocol("bad characteristic declaration".into()));
167            }
168            let u = Uuid::from_le_bytes(&v[3..])
169                .ok_or_else(|| Error::Protocol("bad characteristic UUID".into()))?;
170            if let Some(prev) = out.last_mut() {
171                prev.end = h - 1;
172            }
173            out.push(Characteristic {
174                uuid: u,
175                name: u.name(),
176                declaration: h,
177                value_handle: le16(&v, 1)?,
178                properties: Properties(v[0]),
179                end: service.end,
180                descriptors: Vec::new(),
181            });
182        }
183        Ok(out)
184    }
185
186    /// The descriptors of a characteristic.
187    pub async fn descriptors(&self, c: &Characteristic) -> Result<Vec<Descriptor>> {
188        let mut out = Vec::new();
189        if c.value_handle >= c.end {
190            return Ok(out);
191        }
192        let mut start = c.value_handle + 1;
193        loop {
194            let mut pdu = vec![op::FIND_INFO_REQ];
195            pdu.extend_from_slice(&start.to_le_bytes());
196            pdu.extend_from_slice(&c.end.to_le_bytes());
197            let rsp = match self.request(pdu).await {
198                Ok(r) => r,
199                Err(e) if not_found(&e) => break,
200                Err(e) => return Err(e),
201            };
202            let size = match rsp.get(1) {
203                Some(1) => 4,
204                Some(2) => 18,
205                _ => return Err(Error::Protocol("bad Find Information format".into())),
206            };
207            let mut last = start;
208            for e in rsp[2..].chunks_exact(size) {
209                let h = le16(e, 0)?;
210                let u = Uuid::from_le_bytes(&e[2..])
211                    .ok_or_else(|| Error::Protocol("bad descriptor UUID".into()))?;
212                out.push(Descriptor { uuid: u, handle: h });
213                last = h;
214            }
215            if last >= c.end || last < start {
216                break;
217            }
218            start = last + 1;
219        }
220        Ok(out)
221    }
222
223    /// Discovers every primary service with its characteristics and descriptors.
224    pub async fn discover(&self) -> Result<Vec<Service>> {
225        let mut services = self.services().await?;
226        for s in &mut services {
227            let mut chars = self.characteristics(s).await?;
228            for c in &mut chars {
229                c.descriptors = self.descriptors(c).await?;
230            }
231            s.characteristics = chars;
232        }
233        Ok(services)
234    }
235
236    async fn read_by_type_all(
237        &self,
238        start: u16,
239        end: u16,
240        ty: Uuid,
241    ) -> Result<Vec<(u16, Vec<u8>)>> {
242        let mut out = Vec::new();
243        let mut s = start;
244        while s <= end {
245            let mut pdu = vec![op::READ_BY_TYPE_REQ];
246            pdu.extend_from_slice(&s.to_le_bytes());
247            pdu.extend_from_slice(&end.to_le_bytes());
248            pdu.extend_from_slice(&super::uuid_bytes(&ty));
249            let rsp = match self.request(pdu).await {
250                Ok(r) => r,
251                Err(e) if not_found(&e) => break,
252                Err(e) => return Err(e),
253            };
254            let len = usize::from(
255                *rsp.get(1)
256                    .ok_or_else(|| Error::Protocol("empty response".into()))?,
257            );
258            if len < 2 {
259                return Err(Error::Protocol("Read By Type entry too short".into()));
260            }
261            let mut last = s;
262            for e in rsp[2..].chunks_exact(len) {
263                let h = le16(e, 0)?;
264                out.push((h, e[2..].to_vec()));
265                last = h;
266            }
267            if last == 0xffff || last < s {
268                break;
269            }
270            s = last + 1;
271        }
272        Ok(out)
273    }
274
275    /// Reads every attribute of a type in a range: (handle, value).
276    pub async fn read_by_type(
277        &self,
278        start: u16,
279        end: u16,
280        ty: Uuid,
281    ) -> Result<Vec<(u16, Vec<u8>)>> {
282        self.read_by_type_all(start, end, ty).await
283    }
284
285    /// Reads a value, whole: a value that fills the response is continued
286    /// with Read Blob until it ends (a long read).
287    pub async fn read(&self, handle: u16) -> Result<Vec<u8>> {
288        let mut pdu = vec![op::READ_REQ];
289        pdu.extend_from_slice(&handle.to_le_bytes());
290        let rsp = self.request(pdu).await?;
291        let mut value = rsp[1..].to_vec();
292        let full = self.mtu() - 1;
293        let mut part = value.len();
294        while part == full && value.len() < 512 {
295            let mut pdu = vec![op::READ_BLOB_REQ];
296            pdu.extend_from_slice(&handle.to_le_bytes());
297            pdu.extend_from_slice(&(value.len() as u16).to_le_bytes());
298            let rsp = match self.request(pdu).await {
299                Ok(r) => r,
300                // The value was exactly one PDU long.
301                Err(Error::Att { code, .. })
302                    if code == ecode::ATTRIBUTE_NOT_LONG || code == ecode::INVALID_OFFSET =>
303                {
304                    break
305                }
306                Err(e) => return Err(e),
307            };
308            part = rsp.len() - 1;
309            value.extend_from_slice(&rsp[1..]);
310        }
311        Ok(value)
312    }
313
314    /// Reads a value from an offset (one Read Blob).
315    pub async fn read_blob(&self, handle: u16, offset: u16) -> Result<Vec<u8>> {
316        let mut pdu = vec![op::READ_BLOB_REQ];
317        pdu.extend_from_slice(&handle.to_le_bytes());
318        pdu.extend_from_slice(&offset.to_le_bytes());
319        Ok(self.request(pdu).await?[1..].to_vec())
320    }
321
322    /// Reads several values of known lengths in one request; the result is
323    /// their concatenation (Read Multiple).
324    pub async fn read_multiple(&self, handles: &[u16]) -> Result<Vec<u8>> {
325        if handles.len() < 2 {
326            return Err(Error::InvalidParameter(
327                "Read Multiple needs two or more handles".into(),
328            ));
329        }
330        let mut pdu = vec![op::READ_MULTIPLE_REQ];
331        for h in handles {
332            pdu.extend_from_slice(&h.to_le_bytes());
333        }
334        Ok(self.request(pdu).await?[1..].to_vec())
335    }
336
337    /// Reads several values in one request, each with its own length (Read
338    /// Multiple Variable Length).
339    pub async fn read_multiple_variable(&self, handles: &[u16]) -> Result<Vec<Vec<u8>>> {
340        let mut pdu = vec![op::READ_MULTIPLE_VAR_REQ];
341        for h in handles {
342            pdu.extend_from_slice(&h.to_le_bytes());
343        }
344        let rsp = self.request(pdu).await?;
345        let mut out = Vec::new();
346        let mut rest = &rsp[1..];
347        while rest.len() >= 2 {
348            let len = usize::from(u16::from_le_bytes([rest[0], rest[1]]));
349            let end = (2 + len).min(rest.len());
350            out.push(rest[2..end].to_vec());
351            rest = &rest[end..];
352        }
353        Ok(out)
354    }
355
356    /// Writes a value and waits for the response. A value longer than one
357    /// PDU is written with Prepare and Execute (a long write).
358    pub async fn write(&self, handle: u16, value: &[u8]) -> Result<()> {
359        if value.len() <= self.mtu() - 3 {
360            let mut pdu = vec![op::WRITE_REQ];
361            pdu.extend_from_slice(&handle.to_le_bytes());
362            pdu.extend_from_slice(value);
363            self.request(pdu).await?;
364            return Ok(());
365        }
366        self.reliable_write(&[(handle, value.to_vec())]).await
367    }
368
369    /// Writes without a response.
370    pub async fn write_without_response(&self, handle: u16, value: &[u8]) -> Result<()> {
371        if value.len() > self.mtu() - 3 {
372            return Err(Error::InvalidParameter(format!(
373                "{} octets do not fit in one Write Command (MTU {})",
374                value.len(),
375                self.mtu()
376            )));
377        }
378        let mut pdu = vec![op::WRITE_CMD];
379        pdu.extend_from_slice(&handle.to_le_bytes());
380        pdu.extend_from_slice(value);
381        let c = &self.conn;
382        c.state.att.command(&c.host, &c.state, &pdu).await
383    }
384
385    /// Writes several values atomically with Prepare Write, checking each
386    /// echo, then Execute Write; cancels on any mismatch (a reliable write).
387    pub async fn reliable_write(&self, writes: &[(u16, Vec<u8>)]) -> Result<()> {
388        let chunk = self.mtu() - 5;
389        for (handle, value) in writes {
390            let mut offset = 0usize;
391            loop {
392                let part = &value[offset..(offset + chunk).min(value.len())];
393                let mut pdu = vec![op::PREPARE_WRITE_REQ];
394                pdu.extend_from_slice(&handle.to_le_bytes());
395                pdu.extend_from_slice(&(offset as u16).to_le_bytes());
396                pdu.extend_from_slice(part);
397                let rsp = match self.request(pdu.clone()).await {
398                    Ok(r) => r,
399                    Err(e) => {
400                        let _ = self.request(vec![op::EXECUTE_WRITE_REQ, 0x00]).await;
401                        return Err(e);
402                    }
403                };
404                if rsp[1..] != pdu[1..] {
405                    let _ = self.request(vec![op::EXECUTE_WRITE_REQ, 0x00]).await;
406                    return Err(Error::Protocol(
407                        "the server echoed a different value; write cancelled".into(),
408                    ));
409                }
410                offset += part.len();
411                if offset >= value.len() {
412                    break;
413                }
414            }
415        }
416        self.request(vec![op::EXECUTE_WRITE_REQ, 0x01]).await?;
417        Ok(())
418    }
419
420    /// Turns notifications and indications on or off for a characteristic
421    /// by writing its Client Characteristic Configuration descriptor (found
422    /// by discovery when not yet known). Values arrive as
423    /// [`crate::ConnEvent::Notification`].
424    pub async fn subscribe(&self, c: &Characteristic, notify: bool, indicate: bool) -> Result<()> {
425        if notify && !c.properties.has(Properties::NOTIFY)
426            || indicate && !c.properties.has(Properties::INDICATE)
427        {
428            return Err(Error::InvalidParameter(format!(
429                "characteristic {} cannot {}",
430                c.uuid,
431                if notify { "notify" } else { "indicate" }
432            )));
433        }
434        let cccd = match c.cccd() {
435            Some(h) => h,
436            None => self
437                .descriptors(c)
438                .await?
439                .iter()
440                .find(|d| d.uuid == Uuid::Uuid16(uuid::CCCD))
441                .map(|d| d.handle)
442                .ok_or_else(|| Error::Protocol("the characteristic has no CCCD".into()))?,
443        };
444        let v = u16::from(notify) | (u16::from(indicate) << 1);
445        self.write(cccd, &v.to_le_bytes()).await
446    }
447
448    /// Finds a characteristic by value handle, discovering as needed.
449    pub async fn characteristic_at(&self, value_handle: u16) -> Result<Characteristic> {
450        for s in self.services().await? {
451            if s.start <= value_handle && value_handle <= s.end {
452                for mut c in self.characteristics(&s).await? {
453                    if c.value_handle == value_handle {
454                        c.descriptors = self.descriptors(&c).await?;
455                        return Ok(c);
456                    }
457                }
458            }
459        }
460        Err(Error::InvalidParameter(format!(
461            "no characteristic with value handle {value_handle:#06x}"
462        )))
463    }
464
465    /// Finds a characteristic by UUID (the first one), discovering as needed.
466    pub async fn characteristic(&self, u: Uuid) -> Result<Characteristic> {
467        for s in self.services().await? {
468            for mut c in self.characteristics(&s).await? {
469                if c.uuid == u {
470                    c.descriptors = self.descriptors(&c).await?;
471                    return Ok(c);
472                }
473            }
474        }
475        Err(Error::InvalidParameter(format!("no characteristic {u}")))
476    }
477}