Systemic::BluetoothLE Namespace Reference

A collection of C++ classes that provides a simplified access to Bluetooth Low Energy peripherals. More...

Classes
class	AdvertisementData
	Stores an advertisement packet data type and it's associated binary data. More...
class	Characteristic
	Represents a service's characteristic of a Bluetooth Low Energy (BLE) peripheral. More...
class	ManufacturerData
	Stores a company id and it's associated binary data. More...
class	Peripheral
	Represents a Bluetooth Low Energy (BLE) peripheral. More...
class	ScannedPeripheral
	Holds the information from advertisement packet(s) received from a peripheral. More...
class	Scanner
	Implements scanning of Bluetooth Low Energy (BLE) peripherals. It stores and notifies of discovered peripherals with ScannedPeripheral objects. More...
class	Service
	Represents a primary service on a Bluetooth Low Energy (BLE) peripheral. More...
class	ServiceData
	Stores a company id and it's associated binary data. More...

Typedefs
using	bluetooth_address_t = std::uint64_t
	Type for a Bluetooth address.

Enumerations
enum class	BleAdapterState { Unsupported , Unavailable , Disabled , Enabled }
	Bluetooth adapter states. More...
enum class	BleRequestStatus {   Success , Error , InProgress , Canceled ,   Disconnected , InvalidPeripheral , InvalidCall , InvalidParameters ,   NotSupported , ProtocolError , AccessDenied , AdapterOff ,   Timeout }
	Peripheral requests statuses. More...
enum class	ConnectionEvent {   Connecting , Connected , FailedToConnect , Ready ,   Disconnecting , Disconnected }
	Peripheral connection events. More...
enum class	ConnectionEventReason {   Unknown = -1 , Success = 0 , Canceled , NotSupported ,   Timeout , LinkLoss , AdpaterOff , Peripheral }
	Peripheral connection event reasons. More...
enum	CharacteristicProperties {   None = 0 , Broadcast = 0x001 , Read = 0x002 , WriteWithoutResponse = 0x004 ,   Write = 0x008 , Notify = 0x010 , Indicate = 0x020 , SignedWrite = 0x040 ,   ExtendedProperties = 0x080 , NotifyEncryptionRequired = 0x100 , IndicateEncryptionRequired = 0x200 }
	Standard BLE values for characteristic properties, those are flags that can be combined. More...

Functions
std::future< BleAdapterState >	getAdapterStateAsync ()
	Returns the default Bluetooth adapter state.
std::future< bool >	subscribeAdapterStateChangedAsync (const std::function< void(BleAdapterState)> &onStateChanged)
	Subscribe to the default Bluetooth adapter radio state events.

Detailed Description

A collection of C++ classes that provides a simplified access to Bluetooth Low Energy peripherals.

Note

Some knowledge with Bluetooth Low Energy semantics is recommended for reading this documentation.

WinRT APIs are used to access Bluetooth. It allows communicating with devices without needing to first add them in Windows' Bluetooth devices manager.

Requires at least Windows 10 version 1709 (Fall Creators Update).

The Scanner class enables scanning for Bluetooth Low Energy peripherals. It stores and notifies of discovered peripherals with ScannedPeripheral objects.

The Peripheral class implements the most used BLE operation for communicating with BLE peripherals. After a successful connection, services and characteristics are discovered and made accessible through the Service and Characteristic classes.

Below is a diagram of the main classes of this library:

Classes diagram

Enumeration Type Documentation

BleAdapterState

enum class Systemic::BluetoothLE::BleAdapterState

strong

Bluetooth adapter states.

Enumerator
Unsupported	The system doesn't have a compatible Bluetooth adapter.
Unavailable	The radio of the default Bluetooth adapter is in a uncontrollable state.
Disabled	The radio of the default Bluetooth adapter is disabled or powered off.
Enabled	The radio of the default Bluetooth adapter is enabled and ready for use..

BleRequestStatus

enum class Systemic::BluetoothLE::BleRequestStatus

strong

Peripheral requests statuses.

Enumerator
Success	The request completed successfully.
Error	The request completed with a non-specific error.
InProgress	The request is still in progress.
Canceled	The request was canceled.
Disconnected	The request was aborted because the peripheral got disconnected.
InvalidPeripheral	The request did not run because the given peripheral is not valid.
InvalidCall	The request did not run because the operation is not valid or permitted.
InvalidParameters	The request did not run because some of its parameters are invalid.
NotSupported	The request failed because of the operation is not supported by the peripheral.
ProtocolError	The request failed because of BLE protocol error.
AccessDenied	The request failed because it was denied access.
AdapterOff	The request failed because the Bluetooth radio is off.
Timeout	The request did not succeed after the timeout period.

CharacteristicProperties

enum Systemic::BluetoothLE::CharacteristicProperties

Standard BLE values for characteristic properties, those are flags that can be combined.

Enumerator
Broadcast	Characteristic is broadcastable.
Read	Characteristic is readable.
WriteWithoutResponse	Characteristic can be written without response.
Write	Characteristic can be written.
Notify	Characteristic supports notification.
Indicate	Characteristic supports indication.
SignedWrite	Characteristic supports write with signature.
ExtendedProperties	Characteristic has extended properties.
NotifyEncryptionRequired	Characteristic notification uses encryption.
IndicateEncryptionRequired	Characteristic indication uses encryption.

ConnectionEvent

enum class Systemic::BluetoothLE::ConnectionEvent

strong

Peripheral connection events.

Enumerator
Connecting	Raised at the beginning of the connect sequence and is followed either by Connected or FailedToConnect.
Connected	Raised once the peripheral is connected, just before services are being discovered.
FailedToConnect	Raised when the peripheral fails to connect, the reason of failure is also given.
Ready	Raised after a Connected event, once the required services have been discovered.
Disconnecting	Raised at the beginning of a user initiated disconnect.
Disconnected	Raised when the peripheral is disconnected, the reason for the disconnection is also given.

ConnectionEventReason

enum class Systemic::BluetoothLE::ConnectionEventReason

strong

Peripheral connection event reasons.

Enumerator
Unknown	The disconnect happened for an unknown reason.
Success	The disconnect was initiated by user.
Canceled	Connection attempt canceled by user.
NotSupported	Peripheral doesn't have all required services.
Timeout	Peripheral didn't responded in time.
LinkLoss	Peripheral was disconnected while in "auto connect" mode.
AdpaterOff	The local device Bluetooth adapter is off.
Peripheral	Disconnection was initiated by peripheral.

Function Documentation

getAdapterStateAsync()

std::future< BleAdapterState > Systemic::BluetoothLE::getAdapterStateAsync

(

)

Returns the default Bluetooth adapter state.

Returns

The adapter state

subscribeAdapterStateChangedAsync()

std::future< bool > Systemic::BluetoothLE::subscribeAdapterStateChangedAsync

(

const std::function< void(BleAdapterState)> &

onStateChanged

)

Subscribe to the default Bluetooth adapter radio state events.

Parameters

onStateChanged

Called when the radio state changes

Returns

A future indicating whether the operation was successful.