blew 0.1.0

Cross-platform async BLE library for Rust (Apple, Linux, Android)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

use super::types::{AdvertisingConfig, PeripheralEvent};
use crate::error::BlewResult;
use crate::gatt::service::GattService;
use crate::l2cap::{L2capChannel, types::Psm};
use crate::types::DeviceId;
use futures_core::Stream;
use std::future::Future;
use uuid::Uuid;

pub(crate) mod private {
    pub trait Sealed {}
}

/// Trait implemented by each platform backend for the peripheral (advertiser/GATT server) role.
///
/// This trait is **sealed**: external crates cannot implement it. See [`CentralBackend`](crate::central::backend::CentralBackend)
/// for the sealing rationale.
pub trait PeripheralBackend: private::Sealed + Send + Sync + 'static {
    /// The concrete `Stream` type yielded by [`events`](Self::events).
    type EventStream: Stream<Item = PeripheralEvent> + Send + Unpin + 'static;

    /// Construct and initialise the backend.
    fn new() -> impl Future<Output = BlewResult<Self>> + Send
    where
        Self: Sized;

    /// Returns `true` if the local Bluetooth adapter is powered on.
    fn is_powered(&self) -> impl Future<Output = BlewResult<bool>> + Send;

    /// Register a GATT service. Must be called before [`start_advertising`](Self::start_advertising).
    fn add_service(&self, service: &GattService) -> impl Future<Output = BlewResult<()>> + Send;

    /// Begin advertising. Returns [`BlewError::AlreadyAdvertising`](crate::error::BlewError::AlreadyAdvertising)
    /// if already active.
    fn start_advertising(
        &self,
        config: &AdvertisingConfig,
    ) -> impl Future<Output = BlewResult<()>> + Send;

    /// Stop advertising.
    fn stop_advertising(&self) -> impl Future<Output = BlewResult<()>> + Send;

    /// Push a characteristic value update to a single subscribed central.
    ///
    /// The notification is unicast to the central identified by `device_id`
    /// when the platform's GATT server API supports per-subscriber targeting
    /// (Apple, Android). On Linux/BlueZ, BlueZ's `CharacteristicNotifier`
    /// callback does not expose the remote device identity, so this degrades
    /// to a broadcast to every subscribed notifier for that characteristic.
    fn notify_characteristic(
        &self,
        device_id: &DeviceId,
        char_uuid: Uuid,
        value: Vec<u8>,
    ) -> impl Future<Output = BlewResult<()>> + Send;

    /// Publish an L2CAP CoC channel and return the OS-assigned PSM together with
    /// a stream of incoming [`L2capChannel`] connections.
    ///
    /// The caller should advertise the returned PSM (e.g. via a readable GATT
    /// characteristic) so that centrals know which PSM to connect on.
    ///
    /// Returns [`BlewError::NotSupported`](crate::error::BlewError::NotSupported) until
    /// the platform backend implements L2CAP.
    fn l2cap_listener(
        &self,
    ) -> impl Future<
        Output = BlewResult<(
            Psm,
            impl Stream<Item = BlewResult<(DeviceId, L2capChannel)>> + Send + 'static,
        )>,
    > + Send;

    /// Subscribe to peripheral-role events. Each call returns an independent stream.
    fn events(&self) -> Self::EventStream;
}