Systemic::BluetoothLE::Peripheral Class Reference

Represents a Bluetooth Low Energy (BLE) peripheral. More...

#include <Peripheral.h>

Inheritance diagram for Systemic::BluetoothLE::Peripheral:

Public Member Functions
Constructor and destructor
	Peripheral (bluetooth_address_t bluetoothAddress, const std::function< void(ConnectionEvent, ConnectionEventReason)> &onConnectionEvent)
	Initializes a new instance of Peripheral with the given Bluetooth address and a callback for notifying of the peripheral connection events.
	~Peripheral ()
	Disconnects and destroys the Peripheral instance.
Connection and disconnection
std::future< BleRequestStatus >	connectAsync (std::vector< winrt::guid > requiredServices=std::vector< winrt::guid >{}, bool maintainConnection=false)
	Connects to the BLE peripheral.
void	disconnect ()
	Immediately disconnects the peripheral.
Getters
Always valid.
bluetooth_address_t	address () const
	Gets the Bluetooth address of the peripheral.
bool	isConnected () const
	Indicates whether the peripheral is connected.
bool	isReady () const
	Indicates whether the peripheral is ready.
Connected getters
Valid only for connected peripherals.
const wchar_t *	deviceId () const
	Gets the device id assigned by the system for the peripheral.
const wchar_t *	name () const
	Gets the name of the peripheral.
uint16_t	mtu () const
	Gets the Maximum Transmission Unit (MTU).
Services access
Valid only for peripherals in ready state.
std::shared_ptr< Service >	getDiscoveredService (const winrt::guid &uuid) const
	Gets the Service instance with the given UUID.
void	copyDiscoveredServices (std::vector< std::shared_ptr< Service > > &outServices) const
	Copy the discovered services to the given std::vector.

Detailed Description

Represents a Bluetooth Low Energy (BLE) peripheral.

The most common BLE operations are supported, such as reading the peripheral name, MTU, RSSI, listing services and characteristics.

Once created, a peripheral must be connected before most its methods may be used, and it must be ready before accessing the services. The peripheral becomes ready once all the required services have been discovered.

The connection method connectAsync() is asynchronous and returns a std::future.

A specific Service may be retrieved by its UUID with getDiscoveredService(). A service contains characteristics for which data may be read or written.

The Peripheral class internally stores a WinRT's BluetoothLEDevice and GattSession objects.

See also

https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothledevice

Constructor & Destructor Documentation

Peripheral()

Systemic::BluetoothLE::Peripheral::Peripheral	(	bluetooth_address_t	bluetoothAddress,
		const std::function< void(ConnectionEvent, ConnectionEventReason)> &	onConnectionEvent
	)

Initializes a new instance of Peripheral with the given Bluetooth address and a callback for notifying of the peripheral connection events.

Parameters

bluetoothAddress	The Bluetooth address of the BLE peripheral.
onConnectionEvent	Called when the connection status of the peripheral changes.

Member Function Documentation

address()

bluetooth_address_t Systemic::BluetoothLE::Peripheral::address

(

)

const

Gets the Bluetooth address of the peripheral.

Returns

The Bluetooth address of the peripheral.

connectAsync()

std::future< BleRequestStatus > Systemic::BluetoothLE::Peripheral::connectAsync	(	std::vector< winrt::guid >	requiredServices = std::vector<winrt::guid>{},
		bool	maintainConnection = false
	)

Connects to the BLE peripheral.

Concurrent calls are invalid and will return an error. This request timeouts after 7 to 8 seconds, as of Windows 10 21H1.

Parameters

requiredServices	List of services UUIDs that the peripheral should support, may be empty.
maintainConnection	Whether to automatically reconnect after an unexpected disconnection (i.e. not requested by a call to disconnect()).

Returns

A future with the resulting request status.

copyDiscoveredServices()

void Systemic::BluetoothLE::Peripheral::copyDiscoveredServices

(

std::vector< std::shared_ptr< Service > > &

outServices

)

const

Copy the discovered services to the given std::vector.

Parameters

outServices

The std::vector to which the discovered services are copied (appended).

deviceId()

const wchar_t * Systemic::BluetoothLE::Peripheral::deviceId

(

)

const

Gets the device id assigned by the system for the peripheral.

Returns

The device id assigned by the system.

disconnect()

void Systemic::BluetoothLE::Peripheral::disconnect

(

)

Immediately disconnects the peripheral.

As a consequence, any on-going request either fails or is canceled, including connection requests.

getDiscoveredService()

std::shared_ptr< Service > Systemic::BluetoothLE::Peripheral::getDiscoveredService

(

const winrt::guid &

uuid

)

const

Gets the Service instance with the given UUID.

Parameters

uuid	The UUID of the service.

Returns

The Service instance.

isConnected()

bool Systemic::BluetoothLE::Peripheral::isConnected

(

)

const

Indicates whether the peripheral is connected.

Services may not have been discovered yet.

Returns

Whether the peripheral is connected.

isReady()

bool Systemic::BluetoothLE::Peripheral::isReady

(

)

const

Indicates whether the peripheral is ready.

The peripheral is ready once it has successfully connected and discovered the required services.

Returns

Whether the peripheral is ready.

mtu()

uint16_t Systemic::BluetoothLE::Peripheral::mtu

(

)

const

Gets the Maximum Transmission Unit (MTU).

Returns

The MTU, or zero if it doesn't have a valid device.

name()

const wchar_t * Systemic::BluetoothLE::Peripheral::name

(

)

const

Gets the name of the peripheral.

Returns

The name of the peripheral, or null if it doesn't have a valid device.

---

The documentation for this class was generated from the following files:

• WinRTBle/src/LibWinRTBle/Systemic/BluetoothLE/Peripheral.h
• WinRTBle/src/LibWinRTBle/Peripheral.cpp