ble_windows_server/

lib.rs

//! # Windows BLE GATT Server
//!
//! A simple, ergonomic BLE GATT server library for Windows using WinRT APIs.
//!
//! ## Features
//! - Create BLE GATT services with multiple read/notify characteristics
//! - Automatic adapter discovery and selection
//! - Async/await support with Tokio
//! - Simple data broadcast via notifications
//!
//! ## Example
//! ```no_run
//! use ble_windows_server::WindowsBLEGattServer;
//! use uuid::Uuid;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let service_uuid = Uuid::parse_str("12345678-1234-5678-1234-567812345678")?;
//!     let char_uuid = Uuid::from_u128(service_uuid.as_u128() + 1);
//!     let mut server = WindowsBLEGattServer::new("MyDevice".into(), service_uuid);
//!     server.add_characteristic("message", char_uuid, "A message");
//!
//!     server.start().await?;
//!     server.notify("message", b"Hello BLE!").await?;
//!
//!     Ok(())
//! }
//! ```

use std::collections::HashMap;
use std::sync::Arc;
use thiserror::Error;
use tokio::sync::RwLock;
use windows::core::GUID;
use windows::{
    Devices::Bluetooth::GenericAttributeProfile::*,
    Devices::Bluetooth::*,
    Devices::Enumeration::*,
    Devices::Radios::*,
    Foundation::TypedEventHandler,
    Storage::Streams::DataWriter,
};

// ============================================================================
// SECTION: Error Types
// ============================================================================

/// SRS-001: Unified error type for all BLE operations.
///
/// Covers Windows API errors, initialization failures, and runtime operations.
#[derive(Error, Debug)]
pub enum BleError {
    #[error("Windows API error: {0}")]
    Windows(#[from] windows::core::Error),

    #[error("Initialization failed: {0}")]
    Init(String),

    #[error("Operation failed: {0}")]
    Operation(String),

    #[error("No Bluetooth adapters found")]
    NoAdapters,

    #[error("Server not started")]
    NotStarted,

    #[error("Unknown characteristic: {0}")]
    UnknownCharacteristic(String),
}

/// SRS-002: Standard Result type alias for the library.
pub type Result<T> = std::result::Result<T, BleError>;

// ============================================================================
// SECTION: Adapter Discovery
// ============================================================================

/// SRS-003: Bluetooth adapter information.
///
/// Contains metadata about a discovered Bluetooth adapter.
#[derive(Debug, Clone)]
pub struct AdapterInfo {
    /// Index in the adapter list
    pub index: usize,
    /// Human-readable adapter name
    pub name: String,
    /// Windows device ID
    pub id: String,
    /// Whether this is the system default adapter
    pub is_default: bool,
    /// MAC address (if available)
    pub mac_address: Option<String>,
    /// Whether BLE is supported
    pub ble_supported: bool,
    /// Whether peripheral role is supported
    pub peripheral_supported: bool,
}

impl std::fmt::Display for AdapterInfo {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let default_marker = if self.is_default { " (Default)" } else { "" };
        let mac = self.mac_address.as_deref().unwrap_or("Unknown");
        write!(f, "[{}] {} - MAC: {}{}", self.index, self.name, mac, default_marker)
    }
}

/// SRS-004: Enumerate all Bluetooth adapters on the system.
///
/// Returns a list of available adapters with their capabilities.
pub async fn list_adapters() -> Result<Vec<AdapterInfo>> {
    let selector = BluetoothAdapter::GetDeviceSelector()?;
    let devices = DeviceInformation::FindAllAsyncAqsFilter(&selector)?
        .get()
        .map_err(BleError::Windows)?;

    let count = devices.Size()?;
    if count == 0 {
        return Err(BleError::NoAdapters);
    }

    // Get default adapter for comparison
    let default_id = BluetoothAdapter::GetDefaultAsync()?
        .get()
        .ok()
        .and_then(|a| a.DeviceId().ok())
        .map(|id| id.to_string());

    let mut adapters = Vec::with_capacity(count as usize);

    for i in 0..count {
        let device = devices.GetAt(i)?;
        let name = device.Name()?.to_string();
        let id = device.Id()?.to_string();
        let is_default = default_id.as_ref().map(|d| d == &id).unwrap_or(false);

        // Get detailed adapter info
        let (mac_address, ble_supported, peripheral_supported) =
            if let Ok(adapter) = BluetoothAdapter::FromIdAsync(&device.Id()?)?.get() {
                let mac = adapter.BluetoothAddress().ok().map(format_mac_address);
                let ble = adapter.IsLowEnergySupported().unwrap_or(false);
                let peripheral = adapter.IsPeripheralRoleSupported().unwrap_or(false);
                (mac, ble, peripheral)
            } else {
                (None, false, false)
            };

        adapters.push(AdapterInfo {
            index: i as usize,
            name,
            id,
            is_default,
            mac_address,
            ble_supported,
            peripheral_supported,
        });
    }

    Ok(adapters)
}

/// SRS-005: List all Bluetooth radios (debug utility).
///
/// Useful for diagnosing adapter issues.
pub async fn list_radios() -> Result<Vec<(String, bool)>> {
    let radios = Radio::GetRadiosAsync()?.get().map_err(BleError::Windows)?;
    let count = radios.Size()?;

    let mut result = Vec::new();
    for i in 0..count {
        let radio = radios.GetAt(i)?;
        if radio.Kind()? == RadioKind::Bluetooth {
            let name = radio.Name()?.to_string();
            let is_on = radio.State()? == RadioState::On;
            result.push((name, is_on));
        }
    }

    Ok(result)
}

// ============================================================================
// SECTION: Internal Structs
// ============================================================================

/// Configuration for a characteristic, collected before start().
struct CharacteristicConfig {
    uuid: Uuid,
    description: Option<String>,
}

/// Runtime state for a characteristic, populated by start().
struct RuntimeCharacteristic {
    data_buffer: Arc<RwLock<Vec<u8>>>,
    handle: GattLocalCharacteristic,
}

// ============================================================================
// SECTION: GATT Server
// ============================================================================

/// SRS-006: Windows BLE GATT Server.
///
/// A BLE peripheral that exposes a GATT service with multiple characteristics
/// supporting Read and Notify operations.
///
/// # Lifecycle
/// 1. Create with `new()`
/// 2. Add characteristics with `add_characteristic()`
/// 3. Optionally select adapter with `use_adapter()`
/// 4. Start with `start()`
/// 5. Send data with `notify(name, data)`
/// 6. Stop with `stop()` (or drop)
pub struct WindowsBLEGattServer {
    // Configuration
    device_name: String,
    service_uuid: Uuid,
    selected_adapter_id: Option<String>,

    // Characteristic configuration (ordered, populated before start())
    char_configs: Vec<(String, CharacteristicConfig)>,

    // Runtime state (populated by start())
    char_runtime: HashMap<String, RuntimeCharacteristic>,
    service_provider: Option<GattServiceProvider>,
}

impl WindowsBLEGattServer {
    /// SRS-007: Create a new BLE GATT server instance.
    ///
    /// After creation, add characteristics with `add_characteristic()` before calling `start()`.
    ///
    /// # Arguments
    /// * `device_name` - Name for the BLE device (may not appear in scans on Windows)
    /// * `service_uuid` - UUID for the GATT service
    pub fn new(device_name: String, service_uuid: Uuid) -> Self {
        Self {
            device_name,
            service_uuid,
            selected_adapter_id: None,
            char_configs: Vec::new(),
            char_runtime: HashMap::new(),
            service_provider: None,
        }
    }

    /// Register a characteristic on this service.
    ///
    /// Must be called before `start()`. Each characteristic is identified by a unique name
    /// that is used later to send notifications.
    ///
    /// # Arguments
    /// * `name` - Unique name used to reference this characteristic (e.g. "heart_rate")
    /// * `uuid` - UUID for the GATT characteristic
    /// * `description` - Human-readable description (creates a 0x2901 descriptor)
    pub fn add_characteristic(
        &mut self,
        name: impl Into<String>,
        uuid: Uuid,
        description: impl Into<String>,
    ) -> &mut Self {
        let desc_string = description.into();
        self.char_configs.push((
            name.into(),
            CharacteristicConfig {
                uuid,
                description: if desc_string.is_empty() { None } else { Some(desc_string) },
            },
        ));
        self
    }

    /// SRS-009: Select a specific Bluetooth adapter.
    ///
    /// Call before `start()` to use a non-default adapter.
    pub fn use_adapter(&mut self, adapter: &AdapterInfo) -> &mut Self {
        self.selected_adapter_id = Some(adapter.id.clone());
        self
    }

    /// SRS-010: Use the system default adapter.
    pub fn use_default_adapter(&mut self) -> &mut Self {
        self.selected_adapter_id = None;
        self
    }

    /// Get the device name.
    pub fn device_name(&self) -> &str {
        &self.device_name
    }

    /// Get the service UUID.
    pub fn service_uuid(&self) -> Uuid {
        self.service_uuid
    }

    /// Get the UUID of a characteristic by name.
    pub fn characteristic_uuid(&self, name: &str) -> Option<Uuid> {
        self.char_configs
            .iter()
            .find(|(n, _)| n == name)
            .map(|(_, cfg)| cfg.uuid)
    }

    /// List all configured characteristic names in registration order.
    pub fn characteristic_names(&self) -> Vec<&str> {
        self.char_configs.iter().map(|(n, _)| n.as_str()).collect()
    }

    /// Check if the server is currently running.
    pub fn is_running(&self) -> bool {
        self.service_provider.is_some()
    }

    /// SRS-011: Start the BLE GATT server.
    ///
    /// Creates the GATT service, registers all characteristics, and begins advertising.
    pub async fn start(&mut self) -> Result<()> {
        if self.is_running() {
            return Ok(());
        }

        if self.char_configs.is_empty() {
            return Err(BleError::Init(
                "No characteristics configured. Call add_characteristic() before start().".into(),
            ));
        }

        let service_guid = GUID::from_u128(self.service_uuid.as_u128());

        // Create service provider
        let provider_result = GattServiceProvider::CreateAsync(service_guid)?
            .get()
            .map_err(BleError::Windows)?;

        let service_provider = provider_result.ServiceProvider()?;
        let service = service_provider.Service()?;

        // Create each characteristic
        for (name, config) in &self.char_configs {
            let char_guid = GUID::from_u128(config.uuid.as_u128());

            let char_params = GattLocalCharacteristicParameters::new()?;
            char_params.SetCharacteristicProperties(
                GattCharacteristicProperties::Read | GattCharacteristicProperties::Notify,
            )?;
            char_params.SetReadProtectionLevel(GattProtectionLevel::Plain)?;

            // Set user description descriptor (0x2901) if configured
            if let Some(ref description) = config.description {
                char_params
                    .SetUserDescription(&windows::core::HSTRING::from(description.as_str()))?;
            }

            // Set initial value
            let initial_buffer = create_buffer(b"Ready")?;
            char_params.SetStaticValue(&initial_buffer)?;

            // Create characteristic on the service
            let char_result = service
                .CreateCharacteristicAsync(char_guid, &char_params)?
                .get()
                .map_err(BleError::Windows)?;

            if char_result.Error()? != BluetoothError::Success {
                return Err(BleError::Init(format!(
                    "Failed to create characteristic '{}': {:?}",
                    name,
                    char_result.Error()?
                )));
            }

            let characteristic = char_result.Characteristic()?;

            // Set up read handler with its own buffer
            let data_buffer = Arc::new(RwLock::new(Vec::<u8>::new()));
            let buffer_clone = data_buffer.clone();
            characteristic.ReadRequested(&TypedEventHandler::new(
                move |_: &Option<GattLocalCharacteristic>,
                      args: &Option<GattReadRequestedEventArgs>| {
                    if let Some(args) = args {
                        let request = args.GetRequestAsync()?.get()?;

                        let response = if let Ok(guard) = buffer_clone.try_read() {
                            if guard.is_empty() {
                                create_buffer(b"No data")?
                            } else {
                                create_buffer(&guard)?
                            }
                        } else {
                            create_buffer(b"Busy")?
                        };

                        request.RespondWithValue(&response)?;
                    }
                    Ok(())
                },
            ))?;

            self.char_runtime.insert(
                name.clone(),
                RuntimeCharacteristic {
                    data_buffer,
                    handle: characteristic,
                },
            );
        }

        // Store provider and start advertising
        self.service_provider = Some(service_provider.clone());

        let adv_params = GattServiceProviderAdvertisingParameters::new()?;
        adv_params.SetIsConnectable(true)?;
        adv_params.SetIsDiscoverable(true)?;
        service_provider.StartAdvertisingWithParameters(&adv_params)?;

        Ok(())
    }

    // ========================================================================
    // Notify Methods - SRS-013: Send notifications to subscribed clients
    // ========================================================================

    /// Send raw bytes as a notification on a named characteristic.
    ///
    /// This is the base method - all other notify methods use this internally.
    pub async fn notify(&self, name: &str, data: &[u8]) -> Result<()> {
        if self.service_provider.is_none() {
            return Err(BleError::NotStarted);
        }

        let rt = self
            .char_runtime
            .get(name)
            .ok_or_else(|| BleError::UnknownCharacteristic(name.to_string()))?;

        // Update buffer
        *rt.data_buffer.write().await = data.to_vec();

        // Send notification
        let buffer = create_buffer(data)?;
        rt.handle.NotifyValueAsync(&buffer)?.get().map_err(BleError::Windows)?;

        Ok(())
    }

    /// Send a string as a notification.
    pub async fn notify_str(&self, name: &str, s: &str) -> Result<()> {
        self.notify(name, s.as_bytes()).await
    }

    /// Send a formatted string as a notification.
    pub async fn notify_fmt(&self, name: &str, args: std::fmt::Arguments<'_>) -> Result<()> {
        self.notify_str(name, &args.to_string()).await
    }

    /// Send a u8 as a notification (1 byte).
    pub async fn notify_u8(&self, name: &str, value: u8) -> Result<()> {
        self.notify(name, &[value]).await
    }

    /// Send an i8 as a notification (1 byte).
    pub async fn notify_i8(&self, name: &str, value: i8) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send a u16 as a notification (2 bytes, little-endian).
    pub async fn notify_u16(&self, name: &str, value: u16) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send an i16 as a notification (2 bytes, little-endian).
    pub async fn notify_i16(&self, name: &str, value: i16) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send a u32 as a notification (4 bytes, little-endian).
    pub async fn notify_u32(&self, name: &str, value: u32) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send an i32 as a notification (4 bytes, little-endian).
    pub async fn notify_i32(&self, name: &str, value: i32) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send a u64 as a notification (8 bytes, little-endian).
    pub async fn notify_u64(&self, name: &str, value: u64) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send an i64 as a notification (8 bytes, little-endian).
    pub async fn notify_i64(&self, name: &str, value: i64) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send an f32 as a notification (4 bytes, IEEE 754).
    pub async fn notify_f32(&self, name: &str, value: f32) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send an f64 as a notification (8 bytes, IEEE 754).
    pub async fn notify_f64(&self, name: &str, value: f64) -> Result<()> {
        self.notify(name, &value.to_le_bytes()).await
    }

    /// Send a bool as a notification (1 byte: 0x00 or 0x01).
    pub async fn notify_bool(&self, name: &str, value: bool) -> Result<()> {
        self.notify(name, &[value as u8]).await
    }

    /// Send a JSON-serialized value as a notification.
    ///
    /// Requires the `json` feature to be enabled.
    #[cfg(feature = "json")]
    pub async fn notify_json<T: serde::Serialize>(&self, name: &str, value: &T) -> Result<()> {
        let json = serde_json::to_vec(value)
            .map_err(|e| BleError::Operation(format!("JSON serialization failed: {}", e)))?;
        self.notify(name, &json).await
    }

    /// SRS-014: Stop the BLE server.
    ///
    /// Stops advertising and releases resources.
    pub fn stop(&mut self) -> Result<()> {
        if let Some(provider) = self.service_provider.take() {
            provider.StopAdvertising()?;
        }
        self.char_runtime.clear();
        Ok(())
    }
}

impl Drop for WindowsBLEGattServer {
    fn drop(&mut self) {
        let _ = self.stop();
    }
}

// ============================================================================
// SECTION: Helper Functions
// ============================================================================

/// Convert bytes to a Windows IBuffer.
fn create_buffer(data: &[u8]) -> windows::core::Result<windows::Storage::Streams::IBuffer> {
    let writer = DataWriter::new()?;
    writer.WriteBytes(data)?;
    writer.DetachBuffer()
}

/// Format a Bluetooth MAC address from u64.
fn format_mac_address(address: u64) -> String {
    format!(
        "{:02X}:{:02X}:{:02X}:{:02X}:{:02X}:{:02X}",
        (address >> 40) & 0xFF,
        (address >> 32) & 0xFF,
        (address >> 24) & 0xFF,
        (address >> 16) & 0xFF,
        (address >> 8) & 0xFF,
        address & 0xFF
    )
}

// ============================================================================
// SECTION: Re-exports
// ============================================================================

pub use uuid::Uuid;