A C library for discovering, connecting to, and interacting with Bluetooth Low Energy (BLE) peripherals on Windows 10 and above. More...

#include <cstdint>
#include "bletypes.h"

Include dependency graph for cble.h:

Go to the source code of this file.

Typedefs
using	bluetooth_address_t = Systemic::BluetoothLE::bluetooth_address_t
	Type for a Bluetooth address.

using	BleRequestStatus = Systemic::BluetoothLE::BleRequestStatus
	Enumeration for peripheral requests statuses.

using	ConnectionEvent = Systemic::BluetoothLE::ConnectionEvent
	Peripheral connection events.

using	ConnectionEventReason = Systemic::BluetoothLE::ConnectionEventReason
	Peripheral connection event reasons.

using	CharacteristicProperties = Systemic::BluetoothLE::CharacteristicProperties
	Characteristic properties (standard BLE values).

using	characteristic_index_t = std::uint32_t
	Type for the index of a characteristic instance in a service.

typedef void(*	BluetoothStateUpdateCallback) (Systemic::BluetoothLE::BleAdapterState state)
	Callback notifying of a change of the host device Bluetooth state, for example radio turned on or off.

typedef void(*	DiscoveredPeripheralCallback) (const char *advertisementDataJson)
	Callback notifying of the discovery of a BLE peripheral, with its advertisement data as a JSON string.

typedef void(*	RequestStatusCallback) (BleRequestStatus status)
	Callback notifying of the status of a BLE request.

typedef void(*	PeripheralConnectionEventCallback) (bluetooth_address_t address, ConnectionEvent connectionEvent, ConnectionEventReason reason)
	Callback notifying of a change connection state of a peripheral, with the reason for the change.

typedef void(*	ValueReadCallback) (const void *data, size_t length, BleRequestStatus status)
	Callback notifying of the value read from a peripheral's characteristic.

typedef void(*	ValueChangedCallback) (const void *data, size_t length)
	Callback notifying of a value change for a peripheral's characteristic.

Functions
Library life cycle
bool	sgBleInitialize (bool apartmentSingleThreaded, BluetoothStateUpdateCallback onCentralStateUpdate)
	Initializes the library for accessing BLE peripherals.

void	sgBleShutdown ()
	Shuts down the library.

Peripherals scanning
bool	sgBleStartScan (const char *requiredServicesUuids, DiscoveredPeripheralCallback onDiscoveredPeripheral)
	Starts scanning for BLE peripherals advertising the given list of services.

void	sgBleStopScan ()
	Stops an on-going BLE scan.

Peripherals life cycle
bool	sgBleCreatePeripheral (bluetooth_address_t address, PeripheralConnectionEventCallback onPeripheralConnectionEvent)
	Creates a Peripheral for the BLE peripheral with the given Bluetooth address.

void	sgBleReleasePeripheral (bluetooth_address_t address)
	Releases the Peripheral object associated with the given Bluetooth address.

Peripheral connection and disconnection
void	sgBleConnectPeripheral (bluetooth_address_t address, const char *requiredServicesUuids, bool autoReconnect, RequestStatusCallback onRequestStatus)
	Connects to the given peripheral.

void	sgBleDisconnectPeripheral (bluetooth_address_t address, RequestStatusCallback onRequestStatus)
	Immediately disconnects the given peripheral.

Peripheral operations
Valid only for connected peripherals.
const char *	sgBleGetPeripheralName (bluetooth_address_t address)
	Returns the name of the given peripheral.

int	sgBleGetPeripheralMtu (bluetooth_address_t address)
	Returns the Maximum Transmission Unit (MTU) for the given peripheral.

Services operations
Valid only for connected peripherals.
const char *	sgBleGetDiscoveredServices (bluetooth_address_t address)
	Returns the list of discovered services for the given peripheral.

const char *	sgBleGetServiceCharacteristics (bluetooth_address_t address, const char *serviceUuid)
	Returns the list of discovered characteristics for the given peripheral's service.

Characteristics operations
Valid only for connected peripherals.
int	sgBleGetCharacteristicProperties (bluetooth_address_t address, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex)
	Returns the standard BLE properties of the specified service's characteristic for the given peripheral.

void	sgBleReadCharacteristic (bluetooth_address_t address, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex, ValueReadCallback onValueRead)
	Sends a request to read the value of the specified service's characteristic for the given peripheral.

void	sgBleWriteCharacteristic (bluetooth_address_t address, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex, const void *data, const size_t length, bool withoutResponse, RequestStatusCallback onRequestStatus)
	Sends a request to write to the specified service's characteristic for the given peripheral.

void	sgBleSetNotifyCharacteristic (bluetooth_address_t address, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex, ValueChangedCallback onValueChanged, RequestStatusCallback onRequestStatus)
	Subscribes or unsubscribes for value changes of the specified service's characteristic for the given peripheral.

Miscellaneous
void	sgFreeString (char *str)
	Deallocates a string returned by any of the sgBle* methods.

Detailed Description

A C library for discovering, connecting to, and interacting with Bluetooth Low Energy (BLE) peripherals on Windows 10 and above.

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).

Those functions are thread safe.

Function Documentation

◆ sgBleConnectPeripheral()

void sgBleConnectPeripheral	(	bluetooth_address_t	address,
		const char *	requiredServicesUuids,
		bool	autoReconnect,
		RequestStatusCallback	onRequestStatus
	)

Connects to the given peripheral.

This request timeouts after 7 to 8 seconds, as of Windows 10 21H1.

Note: sgBleCreatePeripheral() must be called first.

Parameters

address	The Bluetooth address of the peripheral.
requiredServicesUuids	Comma separated list of services UUIDs that the peripheral should support, may be null or empty.
autoReconnect	Whether to automatically reconnect after an unexpected disconnection (i.e. not requested by a call to sgBleDisconnectPeripheral()).
onRequestStatus	Called when the request has completed (successfully or not).

◆ sgBleCreatePeripheral()

bool sgBleCreatePeripheral	(	bluetooth_address_t	address,
		PeripheralConnectionEventCallback	onPeripheralConnectionEvent
	)

Creates a Peripheral for the BLE peripheral with the given Bluetooth address.

The underlying object is not returned, instead the peripheral must be referenced by its Bluetooth address. Call sgBleReleasePeripheral() to destroy the object.

Usually a scan is run first to discover available peripherals through their advertisement data. But if the BLE address is know in advance, the peripheral may be created without scanning for it.

Parameters

address	The Bluetooth address of the peripheral.
onPeripheralConnectionEvent	Called when the peripheral connection state changes. The callback must stay valid until the peripheral is released.

Returns: Whether the peripheral object was successfully created.

◆ sgBleDisconnectPeripheral()

void sgBleDisconnectPeripheral	(	bluetooth_address_t	address,
		RequestStatusCallback	onRequestStatus
	)

Immediately disconnects the given peripheral.

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

Parameters

address	The Bluetooth address of the peripheral.
onRequestStatus	Called when the request has completed (successfully or not).

◆ sgBleGetCharacteristicProperties()

int sgBleGetCharacteristicProperties	(	bluetooth_address_t	address,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex
	)

Returns the standard BLE properties of the specified service's characteristic for the given peripheral.

Parameters

address	The Bluetooth address of a connected peripheral.
serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.

Returns: The standard BLE properties of a service's characteristic, or zero if the call failed. See CharacteristicProperties for the different values (it may be a combination of them).

◆ sgBleGetDiscoveredServices()

const char * sgBleGetDiscoveredServices ( bluetooth_address_t address )

Returns the list of discovered services for the given peripheral.

Parameters

address The Bluetooth address of a connected peripheral.

Returns: A comma separated list of services UUIDs, or null if the call failed.

Remarks: The caller should free the returned string with either a call to sgFreeString() or CoTaskMemFree().
.NET marshaling automatically takes care of it.

◆ sgBleGetPeripheralMtu()

int sgBleGetPeripheralMtu ( bluetooth_address_t address )

Returns the Maximum Transmission Unit (MTU) for the given peripheral.

Parameters

address The Bluetooth address of a connected peripheral.

Returns: The MTU of the peripheral, or zero if the call failed.

◆ sgBleGetPeripheralName()

const char * sgBleGetPeripheralName ( bluetooth_address_t address )

Returns the name of the given peripheral.

Parameters

address The Bluetooth address of a connected peripheral.

Returns: The name of the peripheral, or null if the call failed.

Remarks: The caller should free the returned string with either a call to sgFreeString() or CoTaskMemFree().
.NET marshaling automatically takes care of it.

◆ sgBleGetServiceCharacteristics()

const char * sgBleGetServiceCharacteristics	(	bluetooth_address_t	address,
		const char *	serviceUuid
	)

Returns the list of discovered characteristics for the given peripheral's service.

The same characteristic may be listed several times according to the peripheral's configuration.

Parameters

address	The Bluetooth address of a connected peripheral.
serviceUuid	The service UUID for which to retrieve the characteristics.

Returns: A comma separated list of characteristics UUIDs, or null if the call failed.

Remarks: The caller should free the returned string with either a call to sgFreeString() or CoTaskMemFree().
.NET marshaling automatically takes care of it.

◆ sgBleInitialize()

bool sgBleInitialize	(	bool	apartmentSingleThreaded,
		BluetoothStateUpdateCallback	onCentralStateUpdate
	)

Initializes the library for accessing BLE peripherals.

Parameters

apartmentSingleThreaded	Whether to initialize COM apartment as single thread or multi-threaded
onBluetoothEvent	Called when the host device Bluetooth state changes.

Returns: Whether the initialization was successful.

◆ sgBleReadCharacteristic()

void sgBleReadCharacteristic	(	bluetooth_address_t	address,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		ValueReadCallback	onValueRead
	)

Sends a request to read the value of the specified service's characteristic for the given peripheral.

The call fails if the characteristic is not readable.

Parameters

address	The Bluetooth address of a connected peripheral.
serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
onValueRead	Called when the request has completed (successfully or not) and with the data read from the characteristic.

Returns

◆ sgBleReleasePeripheral()

void sgBleReleasePeripheral ( bluetooth_address_t address )

Releases the Peripheral object associated with the given Bluetooth address.

Parameters

address The Bluetooth address of the peripheral.

◆ sgBleSetNotifyCharacteristic()

void sgBleSetNotifyCharacteristic	(	bluetooth_address_t	address,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		ValueChangedCallback	onValueChanged,
		RequestStatusCallback	onRequestStatus
	)

Subscribes or unsubscribes for value changes of the specified service's characteristic for the given peripheral.

Replaces a previously registered value change callback for the same characteristic. The call fails if the characteristic doesn't support notifications.

Parameters

address	The Bluetooth address of a connected peripheral.
serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
onValueChanged	Called when the value of the characteristic changes. Pass null to unsubscribe. The callback must stay valid until the characteristic is unsubscribed or the peripheral is released.
onRequestStatus	Called when the request has completed (successfully or not).

◆ sgBleShutdown()

void sgBleShutdown ( )

Shuts down the library.

Scanning is stopped and all peripherals are disconnected and removed.

◆ sgBleStartScan()

bool sgBleStartScan	(	const char *	requiredServicesUuids,
		DiscoveredPeripheralCallback	onDiscoveredPeripheral
	)

Starts scanning for BLE peripherals advertising the given list of services.

If a scan is already running, it is updated to run with the new parameters.

Parameters

requiredServicesUuids	Comma separated list of services UUIDs that the peripheral should advertise, may be null or empty.
onDiscoveredPeripheral	Called every time an advertisement packet with the required services is received. The advertisement data is passed as a JSON string. The callback must stay valid until the scan is stopped.

Returns: Whether the scan was successfully started.

◆ sgBleWriteCharacteristic()

void sgBleWriteCharacteristic	(	bluetooth_address_t	address,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		const void *	data,
		const size_t	length,
		bool	withoutResponse,
		RequestStatusCallback	onRequestStatus
	)

Sends a request to write to the specified service's characteristic for the given peripheral.

The call fails if the characteristic is not writable.

Parameters

address	The Bluetooth address of a connected peripheral.
serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
data	A pointer to the data to write to the characteristic (may be null if length is zero).
length	The size in bytes of the data.
withoutResponse	Whether to wait for the peripheral to respond.
onRequestStatus	Called when the request has completed (successfully or not).

Returns

◆ sgFreeString()

void sgFreeString ( char * str )

Deallocates a string returned by any of the sgBle* methods.

Unity's marshaling handles the deallocation automatically.

Parameters

str	A c-string pointer returned by any of the sgBle* methods.

Typedefs

Functions

Detailed Description

Function Documentation

◆ sgBleConnectPeripheral()

◆ sgBleCreatePeripheral()

◆ sgBleDisconnectPeripheral()

◆ sgBleGetCharacteristicProperties()

◆ sgBleGetDiscoveredServices()

◆ sgBleGetPeripheralMtu()

◆ sgBleGetPeripheralName()

◆ sgBleGetServiceCharacteristics()

◆ sgBleInitialize()

◆ sgBleReadCharacteristic()

◆ sgBleReleasePeripheral()

◆ sgBleSetNotifyCharacteristic()

◆ sgBleShutdown()

◆ sgBleStartScan()

◆ sgBleWriteCharacteristic()

◆ sgFreeString()