//! Bluest is a cross-platform [Bluetooth Low Energy] (BLE) library for [Rust]. It currently supports Windows (version
//! 10 and later), MacOS/iOS, and Linux. Android support is planned.
//!
//! The goal of Bluest is to create a *thin* abstraction on top of the platform-specific Bluetooth APIs in order to
//! provide safe, cross-platform access to Bluetooth LE devices. The crate currently supports the GAP Central and
//! GATT Client roles. Peripheral and Server roles are not supported.
//!
//! [Rust]: https://www.rust-lang.org/
//! [Bluetooth Low Energy]: https://www.bluetooth.com/specifications/specs/
//!
//! # Usage
//!
//! ```rust,no_run
//!# use bluest::Adapter;
//!# use futures_util::StreamExt;
//!# #[tokio::main]
//!# async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!let adapter = Adapter::default().await.ok_or("Bluetooth adapter not found")?;
//!adapter.wait_available().await?;
//!
//!println!("starting scan");
//!let mut scan = adapter.scan(&[]).await?;
//!println!("scan started");
//!while let Some(discovered_device) = scan.next().await {
//! println!(
//! "{}{}: {:?}",
//! discovered_device.device.name().as_deref().unwrap_or("(unknown)"),
//! discovered_device
//! .rssi
//! .map(|x| format!(" ({}dBm)", x))
//! .unwrap_or_default(),
//! discovered_device.adv_data.services
//! );
//!}
//!#
//!# Ok(())
//!# }
//! ```
//!
//! # Overview
//!
//! The primary functions provided by Bluest are:
//!
//! - Device discovery:
//! - [Scanning][Adapter::scan] for devices and receiving advertisements
//! - Finding [connected devices][Adapter::connected_devices]
//! - [Opening][Adapter::open_device] previously found devices
//! - [Connecting][Adapter::connect_device] to discovered devices
//! - [Pairing][Device::pair] with devices
//! - Accessing remote GATT services:
//! - Discovering device [services][Device::discover_services]
//! - Discovering service [characteristics][Service::discover_characteristics]
//! - Discovering characteristic [descriptors][Characteristic::discover_descriptors]
//! - [Read][Characteristic::read], [write][Characteristic::write] (including
//! [write without response][Characteristic::write_without_response]), and
//! [notify/indicate][Characteristic::notify] operations on remote characteristics
//! - [Read][Descriptor::read] and [write][Descriptor::write] operations on characteristic descriptors
//!
//! # Asynchronous runtimes
//!
//! On non-linux platforms, Bluest should work with any asynchronous runtime. On linux the underlying `bluer` crate
//! requires the Tokio runtime and Bluest makes use of Tokio's `block_in_place` API (which requires Tokio's
//! multi-threaded runtime) to make a few methods synchronous. Linux-only asynchronous versions of those methods are
//! also provided, which should be preferred in platform-specific code.
//!
//! # Platform specifics
//!
//! Because Bluest aims to provide a thin abstraction over the platform-specific APIs, the available APIs represent the
//! lowest common denominator of APIs among the supported platforms. In most cases Apple's CoreBluetooth API is the
//! most restricted and therefore imposes the limit on what can be supported in a cross platform library. For example,
//! CoreBluetooth never exposes the Bluetooth address of devices to applications, therefore there is no method on
//! `Device` for retrieving an address or even any Bluetooth address struct in the crate.
//!
//! Most Bluest APIs should behave consistently across all supported platforms. Those APIs with significant differences
//! in behavior are summarized in the table below.
//!
//!| Method | MacOS/iOS | Windows | Linux |
//!|--------------------------------------------|:---------:|:-------:|:-----:|
//!| [`Adapter::connect_device`][Adapter::connect_device] | ✅ | ✨ | ✅ |
//!| [`Adapter::disconnect_device`][Adapter::disconnect_device] | ✅ | ✨ | ✅ |
//!| [`Device::name`][Device::name] | ✅ | ✅ | ⌛️ |
//!| [`Device::is_paired`][Device::is_paired] | ❌ | ✅ | ✅ |
//!| [`Device::pair`][Device::pair] | ✨ | ✅ | ✅ |
//!| [`Device::pair_with_agent`][Device::pair_with_agent] | ✨ | ✅ | ✅ |
//!| [`Device::unpair`][Device::unpair] | ❌ | ✅ | ✅ |
//!| [`Device::rssi`][Device::rssi] | ✅ | ❌ | ❌ |
//!| [`Service::uuid`][Service::uuid] | ✅ | ✅ | ⌛️ |
//!| [`Service::is_primary`][Service::is_primary] | ✅ | ❌ | ✅ |
//!| [`Characteristic::uuid`][Characteristic::uuid] | ✅ | ✅ | ⌛️ |
//!| [`Descriptor::uuid`][Descriptor::uuid] | ✅ | ✅ | ⌛️ |
//!
//! ✅ = supported
//! ✨ = managed automatically by the OS, this method is a no-op
//! ⌛️ = the underlying API is async so this method uses Tokio's `block_in_place` API internally
//! ❌ = returns a [`NotSupported`][error::ErrorKind::NotSupported] error
//!
//! Also, the errors returned by APIs in a given situation may not be consistent from platform to platform. For example,
//! Linux's bluez API does not return the underlying Bluetooth protocol error in a useful way, whereas the other
//! platforms do. Where it is possible to return a meaningful error, Bluest will attempt to do so. In other cases,
//! Bluest may return an error with a [`kind`][Error::kind] of [`Other`][error::ErrorKind::Other] and you would need to
//! look at the platform-specific [`source`][std::error::Error::source] of the error for more information.
//!
//! # Feature flags
//!
//! The `serde` feature is available to enable serializing/deserializing device
//! identifiers.
//!
//! # Examples
//!
//! Examples demonstrating basic usage are available in the [examples folder].
//!
//! [examples folder]: https://github.com/alexmoon/bluest/tree/master/bluest/examples
use HashMap;
pub use Uuid;
pub use Adapter;
pub use BluetoothUuidExt;
pub use Characteristic;
pub use Descriptor;
pub use Device;
pub use Error;
pub use Service;
pub use DeviceId;
pub use Uuid;
use crate bluer as sys;
use crate corebluetooth as sys;
use crate windows as sys;
/// Convenience alias for a result with [`Error`]
pub type Result<T, E = Error> = Result;
/// Events generated by [`Adapter`]
/// Represents a device discovered during a scan operation
/// Data included in a Bluetooth advertisement or scan reponse.
/// Manufacturer specific data included in Bluetooth advertisements. See the Bluetooth Core Specification Supplement
/// §A.1.4 for details.
/// GATT characteristic properties as defined in the Bluetooth Core Specification, Vol 3, Part G, §3.3.1.1.
/// Extended properties are also included as defined in §3.3.3.1.