| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| use bt_common::{PeerId, Uuid}; |
| use thiserror::Error; |
| |
| /// Errors that can be returned from GATT procedures. These errors are sent from |
| /// the peer. These are defined to match the Bluetooth Core Spec (v5.4, Vol 3, |
| /// Part F, Sec 3.4.1.1) |
| #[derive(Debug, Copy, Clone, PartialEq)] |
| pub enum GattError { |
| InvalidHandle = 1, |
| ReadNotPermitted = 2, |
| WriteNotPermitted = 3, |
| InvalidPdu = 4, |
| InsufficientAuthentication = 5, |
| RequestNotSupported = 6, |
| InvalidOffset = 7, |
| InsufficientAuthorization = 8, |
| InsufficientEncryptionKeySize = 12, |
| InvalidAttributeValueLength = 13, |
| UnlikelyError = 14, |
| InsufficientEncryption = 15, |
| InsufficientResources = 17, |
| ValueNotAllowed = 19, |
| ApplicationError80 = 128, |
| ApplicationError81 = 129, |
| ApplicationError82 = 130, |
| ApplicationError83 = 131, |
| ApplicationError84 = 132, |
| ApplicationError85 = 133, |
| ApplicationError86 = 134, |
| ApplicationError87 = 135, |
| ApplicationError88 = 136, |
| ApplicationError89 = 137, |
| ApplicationError8A = 138, |
| ApplicationError8B = 139, |
| ApplicationError8C = 140, |
| ApplicationError8D = 141, |
| ApplicationError8E = 142, |
| ApplicationError8F = 143, |
| ApplicationError90 = 144, |
| ApplicationError91 = 145, |
| ApplicationError92 = 146, |
| ApplicationError93 = 147, |
| ApplicationError94 = 148, |
| ApplicationError95 = 149, |
| ApplicationError96 = 150, |
| ApplicationError97 = 151, |
| ApplicationError98 = 152, |
| ApplicationError99 = 153, |
| ApplicationError9A = 154, |
| ApplicationError9B = 155, |
| ApplicationError9C = 156, |
| ApplicationError9D = 157, |
| ApplicationError9E = 158, |
| ApplicationError9F = 159, |
| WriteRequestRejected = 252, |
| CccDescriptorImproperlyConfigured = 253, |
| ProcedureAlreadyInProgress = 254, |
| OutOfRange = 255, |
| InvalidParameters = 257, |
| TooManyResults = 258, |
| } |
| |
| impl std::fmt::Display for GattError { |
| fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { |
| write!(f, "{:?}", self) |
| } |
| } |
| |
| impl std::error::Error for GattError {} |
| |
| impl TryFrom<u32> for GattError { |
| type Error = Error; |
| |
| fn try_from(value: u32) -> std::result::Result<Self, Self::Error> { |
| match value { |
| 1 => Ok(Self::InvalidHandle), |
| 2 => Ok(Self::ReadNotPermitted), |
| 3 => Ok(Self::WriteNotPermitted), |
| 4 => Ok(Self::InvalidPdu), |
| 5 => Ok(Self::InsufficientAuthentication), |
| 6 => Ok(Self::RequestNotSupported), |
| 7 => Ok(Self::InvalidOffset), |
| 8 => Ok(Self::InsufficientAuthorization), |
| 12 => Ok(Self::InsufficientEncryptionKeySize), |
| 13 => Ok(Self::InvalidAttributeValueLength), |
| 14 => Ok(Self::UnlikelyError), |
| 15 => Ok(Self::InsufficientEncryption), |
| 17 => Ok(Self::InsufficientResources), |
| 19 => Ok(Self::ValueNotAllowed), |
| 128 => Ok(Self::ApplicationError80), |
| 129 => Ok(Self::ApplicationError81), |
| 130 => Ok(Self::ApplicationError82), |
| 131 => Ok(Self::ApplicationError83), |
| 132 => Ok(Self::ApplicationError84), |
| 133 => Ok(Self::ApplicationError85), |
| 134 => Ok(Self::ApplicationError86), |
| 135 => Ok(Self::ApplicationError87), |
| 136 => Ok(Self::ApplicationError88), |
| 137 => Ok(Self::ApplicationError89), |
| 138 => Ok(Self::ApplicationError8A), |
| 139 => Ok(Self::ApplicationError8B), |
| 140 => Ok(Self::ApplicationError8C), |
| 141 => Ok(Self::ApplicationError8D), |
| 142 => Ok(Self::ApplicationError8E), |
| 143 => Ok(Self::ApplicationError8F), |
| 144 => Ok(Self::ApplicationError90), |
| 145 => Ok(Self::ApplicationError91), |
| 146 => Ok(Self::ApplicationError92), |
| 147 => Ok(Self::ApplicationError93), |
| 148 => Ok(Self::ApplicationError94), |
| 149 => Ok(Self::ApplicationError95), |
| 150 => Ok(Self::ApplicationError96), |
| 151 => Ok(Self::ApplicationError97), |
| 152 => Ok(Self::ApplicationError98), |
| 153 => Ok(Self::ApplicationError99), |
| 154 => Ok(Self::ApplicationError9A), |
| 155 => Ok(Self::ApplicationError9B), |
| 156 => Ok(Self::ApplicationError9C), |
| 157 => Ok(Self::ApplicationError9D), |
| 158 => Ok(Self::ApplicationError9E), |
| 159 => Ok(Self::ApplicationError9F), |
| 252 => Ok(Self::WriteRequestRejected), |
| 253 => Ok(Self::CccDescriptorImproperlyConfigured), |
| 254 => Ok(Self::ProcedureAlreadyInProgress), |
| 255 => Ok(Self::OutOfRange), |
| 257 => Ok(Self::InvalidParameters), |
| 258 => Ok(Self::TooManyResults), |
| x => Err(Error::Conversion(format!("Unknown GATT Error Value: {x}"))), |
| } |
| } |
| } |
| |
| #[derive(Error, Debug)] |
| #[non_exhaustive] |
| pub enum Error { |
| #[error("peer {0} was not recognized")] |
| PeerNotRecognized(PeerId), |
| #[error("peer {0} was disconnected")] |
| PeerDisconnected(PeerId), |
| #[error("conversion error: {0}")] |
| Conversion(String), |
| #[error("scan failed: {0}")] |
| ScanFailed(String), |
| #[error("another error: {0}")] |
| Other(#[from] Box<dyn std::error::Error + Send + Sync>), |
| #[error("GATT error: {0}")] |
| Gatt(#[from] GattError), |
| #[error("definition error: duplicate handle(s) {0:?}")] |
| DuplicateHandle(Vec<Handle>), |
| #[error("service for {0:?} already published")] |
| AlreadyPublished(crate::server::ServiceId), |
| #[error("Encoding/decoding error: {0}")] |
| Encoding(#[from] bt_common::packet_encoding::Error), |
| #[error("Periodic Advertising error: {0}")] |
| PeriodicAdvertising(crate::periodic_advertising::Error), |
| } |
| |
| impl Error { |
| pub fn other(e: impl std::error::Error + Send + Sync + 'static) -> Self { |
| Self::Other(Box::new(e)) |
| } |
| } |
| |
| impl From<String> for Error { |
| fn from(value: String) -> Self { |
| Self::Other(Box::<dyn std::error::Error + Send + Sync>::from(value)) |
| } |
| } |
| |
| impl From<&str> for Error { |
| fn from(value: &str) -> Self { |
| String::from(value).into() |
| } |
| } |
| |
| pub type Result<T> = core::result::Result<T, Error>; |
| |
| /// Handles are used as local-to-your-code identifiers for Characteristics and |
| /// Descriptors. |
| /// |
| /// Their value should be treated as opaque by clients of PeerService, |
| /// and are explicitly not guaranteed to be equal to a peer's attribute handles. |
| /// Stack implementations should provide unique handles for each Characteristic |
| /// and Descriptor within a PeerService for the client. It is not necessary or |
| /// expected for different clients of the same service to have the same handles. |
| /// |
| /// For LocalService publishing, Service Definitions are required to have no |
| /// duplicate Handles across their defined Characteristics and Descriptors. |
| /// Characteristic and ServiceDefinition will check and return |
| /// Error::DuplicateHandle. Handles in ServiceDefinitions should not match the |
| /// attribute handles in the local GATT server. They are local to your code for |
| /// use in correlating with ServiceEvents from peers. Stacks must translate |
| /// the actual GATT handles to the handles provided in the ServiceDefinition |
| /// for these events. |
| #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] |
| pub struct Handle(pub u64); |
| |
| /// Whether a service is marked as Primary or Secondary on the server. |
| #[derive(Clone, Copy, Debug, Eq, PartialEq)] |
| pub enum ServiceKind { |
| Primary, |
| Secondary, |
| } |
| |
| #[derive(Clone, Copy, Debug, Eq, PartialEq)] |
| pub enum WriteMode { |
| None, |
| Reliable, |
| WithoutResponse, |
| } |
| |
| /// Characteristic Properties, including Extended Properties |
| /// Determines how the Characteristic Value may be used. |
| /// |
| /// Defined in Core Spec 5.3, Vol 3 Part G Sec 3.3.1.1 and 3.3.3.1 |
| #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] |
| pub enum CharacteristicProperty { |
| Broadcast = 0x01, |
| Read = 0x02, |
| WriteWithoutResponse = 0x04, |
| Write = 0x08, |
| Notify = 0x10, |
| Indicate = 0x20, |
| AuthenticatedSignedWrites = 0x40, |
| ReliableWrite = 0x100, |
| WritableAuxiliaries = 0x200, |
| } |
| |
| /// Set of [`CharacteristicProperty`] flags associated with a GATT |
| /// Characteristic. |
| #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Hash)] |
| pub struct CharacteristicProperties(&'static [CharacteristicProperty]); |
| |
| impl CharacteristicProperties { |
| /// Characteristic is readable and can send notifications. |
| pub const READ_NOTIFY: Self = |
| Self(&[CharacteristicProperty::Read, CharacteristicProperty::Notify]); |
| |
| /// Characteristic can be broadcast and send notifications. |
| pub const BROADCAST_NOTIFY: Self = |
| Self(&[CharacteristicProperty::Broadcast, CharacteristicProperty::Notify]); |
| |
| /// Control Point property set: writable (with and without response) and can |
| /// send notifications. |
| pub const WRITE_NOTIFY: Self = Self(&[ |
| CharacteristicProperty::Write, |
| CharacteristicProperty::WriteWithoutResponse, |
| CharacteristicProperty::Notify, |
| ]); |
| |
| /// Readable, writable (with and without response), and can send |
| /// notifications. |
| pub const READ_WRITE_NOTIFY: Self = Self(&[ |
| CharacteristicProperty::Read, |
| CharacteristicProperty::Write, |
| CharacteristicProperty::WriteWithoutResponse, |
| CharacteristicProperty::Notify, |
| ]); |
| |
| /// Characteristic can send notifications or indications. |
| pub const NOTIFY_INDICATE: Self = |
| Self(&[CharacteristicProperty::Notify, CharacteristicProperty::Indicate]); |
| |
| pub fn contains(&self, property: CharacteristicProperty) -> bool { |
| self.0.contains(&property) |
| } |
| |
| pub fn is_disjoint(&self, other: &Self) -> bool { |
| for property in self.0.iter() { |
| if other.0.contains(property) { |
| return false; |
| } |
| } |
| true |
| } |
| } |
| |
| impl std::ops::Deref for CharacteristicProperties { |
| type Target = [CharacteristicProperty]; |
| |
| fn deref(&self) -> &Self::Target { |
| self.0 |
| } |
| } |
| |
| impl From<CharacteristicProperty> for CharacteristicProperties { |
| fn from(value: CharacteristicProperty) -> Self { |
| match value { |
| CharacteristicProperty::Broadcast => Self(&[CharacteristicProperty::Broadcast]), |
| CharacteristicProperty::Read => Self(&[CharacteristicProperty::Read]), |
| CharacteristicProperty::WriteWithoutResponse => { |
| Self(&[CharacteristicProperty::WriteWithoutResponse]) |
| } |
| CharacteristicProperty::Write => Self(&[CharacteristicProperty::Write]), |
| CharacteristicProperty::Notify => Self(&[CharacteristicProperty::Notify]), |
| CharacteristicProperty::Indicate => Self(&[CharacteristicProperty::Indicate]), |
| CharacteristicProperty::AuthenticatedSignedWrites => { |
| Self(&[CharacteristicProperty::AuthenticatedSignedWrites]) |
| } |
| CharacteristicProperty::ReliableWrite => Self(&[CharacteristicProperty::ReliableWrite]), |
| CharacteristicProperty::WritableAuxiliaries => { |
| Self(&[CharacteristicProperty::WritableAuxiliaries]) |
| } |
| } |
| } |
| } |
| |
| impl From<&'static [CharacteristicProperty]> for CharacteristicProperties { |
| fn from(value: &'static [CharacteristicProperty]) -> Self { |
| Self(value) |
| } |
| } |
| |
| impl<const N: usize> From<&'static [CharacteristicProperty; N]> for CharacteristicProperties { |
| fn from(value: &'static [CharacteristicProperty; N]) -> Self { |
| Self(value) |
| } |
| } |
| |
| #[derive(Debug, Clone, Copy, Default)] |
| pub struct SecurityLevels { |
| /// Encryption is required / provided |
| pub encryption: bool, |
| /// Authentication is required / provided |
| pub authentication: bool, |
| /// Authorization is required / provided |
| pub authorization: bool, |
| } |
| |
| impl SecurityLevels { |
| pub fn satisfied(&self, provided: SecurityLevels) -> bool { |
| (!self.encryption || provided.encryption) |
| && (!self.authentication || provided.authentication) |
| && (!self.authorization || provided.encryption) |
| } |
| |
| pub const fn encryption_required() -> Self { |
| Self { encryption: true, authentication: false, authorization: false } |
| } |
| } |
| |
| #[derive(Debug, Clone, Copy, Default)] |
| pub struct AttributePermissions { |
| /// If None, then this cannot be read. Otherwise the SecurityLevels given |
| /// are required to read. |
| pub read: Option<SecurityLevels>, |
| /// If None, then this cannot be written. Otherwise the SecurityLevels given |
| /// are required to write. |
| pub write: Option<SecurityLevels>, |
| /// If None, then this cannot be updated. Otherwise the SecurityLevels given |
| /// are required to update. |
| pub update: Option<SecurityLevels>, |
| } |
| |
| impl AttributePermissions { |
| pub fn with_levels(properties: &CharacteristicProperties, levels: &SecurityLevels) -> Self { |
| Self { |
| read: properties.contains(CharacteristicProperty::Read).then_some(levels.clone()), |
| write: properties.contains(CharacteristicProperty::Write).then_some(levels.clone()), |
| update: (!properties.is_disjoint(&CharacteristicProperties::NOTIFY_INDICATE)) |
| .then_some(levels.clone()), |
| } |
| } |
| } |
| |
| /// The different types of well-known Descriptors are defined here and should be |
| /// automatically read during service characteristic discovery by Stack |
| /// Implementations and included. Other Descriptor attribute values can be read |
| /// using [`PeerService::read_descriptor`]. |
| /// |
| /// Characteristic Extended Properties are included in the |
| /// CharacteristicProperties of the Characteristic. |
| /// This is a subset of the descriptors defined in the Core Specification (v5.4, |
| /// Vol 3 Part G Sec 3.3.3). Missing DescriptorTypes are handled internally |
| /// and are added automatically, and are omitted from descriptor APIs. |
| #[derive(Clone, Debug)] |
| pub enum DescriptorType { |
| UserDescription(String), |
| ServerConfiguration { |
| broadcast: bool, |
| }, |
| CharacteristicPresentation { |
| format: u8, |
| exponent: i8, |
| unit: u16, |
| name_space: u8, |
| description: u16, |
| }, |
| Other { |
| uuid: Uuid, |
| }, |
| } |
| |
| impl From<&DescriptorType> for Uuid { |
| fn from(value: &DescriptorType) -> Self { |
| // Values from https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/uuids/descriptors.yaml |
| match value { |
| DescriptorType::UserDescription(_) => Uuid::from_u16(0x2901), |
| DescriptorType::ServerConfiguration { .. } => Uuid::from_u16(0x2903), |
| DescriptorType::CharacteristicPresentation { .. } => Uuid::from_u16(0x2904), |
| DescriptorType::Other { uuid } => uuid.clone(), |
| } |
| } |
| } |
| |
| #[derive(Clone, Debug)] |
| pub struct Descriptor { |
| pub handle: Handle, |
| /// Permissions required needed to interact with this descriptor. May not |
| /// be accurate on clients until the descriptor is interacted with. |
| pub permissions: AttributePermissions, |
| pub r#type: DescriptorType, |
| } |
| |
| /// A Characteristic on a Service. Each Characteristic has a declaration, value, |
| /// and zero or more descriptors. |
| #[derive(Clone, Debug)] |
| pub struct Characteristic { |
| pub handle: Handle, |
| pub uuid: Uuid, |
| pub properties: CharacteristicProperties, |
| /// Attribute Permissions that apply to the value |
| pub permissions: AttributePermissions, |
| pub descriptors: Vec<Descriptor>, |
| } |
| |
| impl Characteristic { |
| pub fn properties(&self) -> &CharacteristicProperties { |
| &self.properties |
| } |
| |
| pub fn supports_property(&self, property: &CharacteristicProperty) -> bool { |
| self.properties.contains(*property) |
| } |
| |
| pub fn descriptors(&self) -> impl Iterator<Item = &Descriptor> { |
| self.descriptors.iter() |
| } |
| |
| pub fn handles(&self) -> impl Iterator<Item = Handle> + '_ { |
| std::iter::once(self.handle).chain(self.descriptors.iter().map(|d| d.handle)) |
| } |
| } |
