Interface Peripheral

src/api/mod.rs:256–381

/// as well as functions for communication.
#[async_trait]
pub trait Peripheral: Send + Sync + Clone + Debug {
    /// Returns the unique identifier of the peripheral.
    fn id(&self) -> PeripheralId;

    /// Returns the MAC address of the peripheral.
    fn address(&self) -> BDAddr;

    /// Returns the currently negotiated mtu size
    fn mtu(&self) -> u16;

    /// Returns the set of properties associated with the peripheral. These may be updated over time
    /// as additional advertising reports are received.
    async fn properties(&self) -> Result<Option<PeripheralProperties>>;

    /// The set of services we've discovered for this device. This will be empty until
    /// `discover_services` is called.
    fn services(&self) -> BTreeSet<Service>;

    /// The set of characteristics we've discovered for this device. This will be empty until
    /// `discover_services` is called.
    fn characteristics(&self) -> BTreeSet<Characteristic> {
        self.services()
            .iter()
            .flat_map(|service| service.characteristics.clone().into_iter())
            .collect()
    }

    /// Returns true iff we are currently connected to the device.
    async fn is_connected(&self) -> Result<bool>;

    /// Creates a connection to the device. If this method returns Ok there has been successful
    /// connection. Note that peripherals allow only one connection at a time. Operations that
    /// attempt to communicate with a device will fail until it is connected.
    async fn connect(&self) -> Result<()>;

    /// Like [`connect`](Peripheral::connect), but returns [`Error::TimedOut`](crate::Error::TimedOut)
    /// if the connection is not established within the given duration.
    async fn connect_with_timeout(&self, timeout: Duration) -> Result<()> {
        tokio::time::timeout(timeout, self.connect())
            .await
            .map_err(|_| crate::Error::TimedOut(timeout))?
    }

    /// Terminates a connection to the device.
    async fn disconnect(&self) -> Result<()>;

    /// Discovers all services for the device, including their characteristics.
    async fn discover_services(&self) -> Result<()>;

    /// Like [`discover_services`](Peripheral::discover_services), but returns
    /// [`Error::TimedOut`](crate::Error::TimedOut) if discovery does not complete within the
    /// given duration.
    async fn discover_services_with_timeout(&self, timeout: Duration) -> Result<()> {
        tokio::time::timeout(timeout, self.discover_services())
            .await
            .map_err(|_| crate::Error::TimedOut(timeout))?
    }