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

import "UnityBridge.h"
import "SGBleErrors.h"

Include dependency graph for UnityBridge.mm:

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

void	sgBleShutdown ()
	Shuts down the library.

Peripherals scanning
bool	sgBleStartScan (const char *servicesUuids, bool allowDuplicates, 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 (peripheral_id_t peripheralId, PeripheralConnectionEventCallback onPeripheralConnectionEvent, request_index_t requestIndex)
	Creates a Peripheral for the BLE peripheral with the given Bluetooth address.

void	sgBleReleasePeripheral (peripheral_id_t peripheralId)
	Releases the Peripheral object associated with the given peripheral id.

Peripheral connection and disconnection
void	sgBleConnectPeripheral (peripheral_id_t peripheralId, const char *requiredServicesUuids, RequestStatusCallback onRequestStatus, request_index_t requestIndex)
	Connects to the given peripheral.

void	sgBleDisconnectPeripheral (peripheral_id_t peripheralId, RequestStatusCallback onRequestStatus, request_index_t requestIndex)
	Disconnects the given peripheral.

Peripheral operations
Valid only for connected peripherals.
const char *	sgBleGetPeripheralName (peripheral_id_t peripheralId)
	Gets the name of the given peripheral.

int	sgBleGetPeripheralMtu (peripheral_id_t peripheralId)
	Gets the Maximum Transmission Unit (MTU) for the given peripheral.

void	sgBleReadPeripheralRssi (peripheral_id_t peripheralId, RssiReadCallback onRssiRead, request_index_t requestIndex)
	Reads the Received Signal Strength Indicator (RSSI) of the given peripheral.

Services operations
Valid only for ready peripherals.
const char *	sgBleGetDiscoveredServices (peripheral_id_t peripheralId)
	Gets the list of discovered services for the given peripheral.

const char *	sgBleGetServiceCharacteristics (peripheral_id_t peripheralId, const char *serviceUuid)
	Gets the list of discovered characteristics for the given peripheral's service.

Characteristics operations
Valid only for connected peripherals.
characteristic_property_t	sgBleGetCharacteristicProperties (peripheral_id_t peripheralId, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex)
	Gets the standard BLE properties of the specified service's characteristic for the given peripheral.

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

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

void	sgBleSetNotifyCharacteristic (peripheral_id_t peripheralId, const char serviceUuid, const char characteristicUuid, characteristic_index_t instanceIndex, ValueReadCallback onValueChanged, RequestStatusCallback onRequestStatus, request_index_t requestIndex)
	Subscribes or unsubscribes for value changes of the specified service's characteristic for the given peripheral.

Detailed Description

C library for discovering, connecting to, and interacting with Bluetooth Low Energy (BLE) peripherals on iOS.

Attention: None of those functions are thread safe.

Function Documentation

◆ sgBleConnectPeripheral()

void sgBleConnectPeripheral	(	peripheral_id_t	peripheralId,
		const char *	requiredServicesUuids,
		RequestStatusCallback	onRequestStatus,
		request_index_t	requestIndex
	)

Connects to the given peripheral.

This request never timeouts.

Parameters

peripheralId	The UUID assigned by the system for the peripheral.
requiredServicesUuids	Comma separated list of services UUIDs that the peripheral should support, may be null or empty.
onRequestStatus	Called when the request has completed (successfully or not).
requestIndex	The index of this request, passed back when calling `onRequestStatus`.

◆ sgBleCreatePeripheral()

bool sgBleCreatePeripheral	(	peripheral_id_t	peripheralId,
		PeripheralConnectionEventCallback	onPeripheralConnectionEvent,
		request_index_t	requestIndex
	)

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 peripheral id. Call sgBleReleasePeripheral() to destroy the object.

A scan must first be run to discover available BLE peripherals through their advertisement data. The later includes the peripheral system id, a UUID assigned by the system.

Note: The the peripheral system id may change over long period of time.

Parameters

peripheralId	The UUID assigned by the system for the peripheral.
onPeripheralConnectionEvent	Called when the peripheral connection state changes. The callback must stay valid until the peripheral is released.
requestIndex	The index of this request, passed back when calling `onPeripheralConnectionEvent`.

Returns: Whether the peripheral object was successfully created.

◆ sgBleDisconnectPeripheral()

void sgBleDisconnectPeripheral	(	peripheral_id_t	peripheralId,
		RequestStatusCallback	onRequestStatus,
		request_index_t	requestIndex
	)

Disconnects the given peripheral.

Parameters

peripheralId	The UUID assigned by the system for the peripheral.
onRequestStatus	Called when the request has completed (successfully or not).
requestIndex	The index of this request, passed back when calling `onRequestStatus`.

◆ sgBleGetCharacteristicProperties()

characteristic_property_t sgBleGetCharacteristicProperties	(	peripheral_id_t	peripheralId,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex
	)

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

See also: https://developer.apple.com/documentation/corebluetooth/cbcharacteristicproperties?language=objc

Parameters

peripheralId	The UUID assigned by the system for the 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.

◆ sgBleGetDiscoveredServices()

const char * sgBleGetDiscoveredServices ( peripheral_id_t peripheralId )

Gets the list of discovered services for the given peripheral.

Parameters

peripheralId The UUID assigned by the system for the peripheral.

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

Remarks: The caller should free the returned string with a call to free().
Unity marshaling takes care of it.

◆ sgBleGetPeripheralMtu()

int sgBleGetPeripheralMtu ( peripheral_id_t peripheralId )

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

Parameters

peripheralId The UUID assigned by the system for the peripheral.

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

◆ sgBleGetPeripheralName()

const char * sgBleGetPeripheralName ( peripheral_id_t peripheralId )

Gets the name of the given peripheral.

Parameters

peripheralId The UUID assigned by the system for the peripheral.

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

Remarks: The caller should free the returned string with a call to free().
Unity marshaling takes care of it.

◆ sgBleGetServiceCharacteristics()

const char * sgBleGetServiceCharacteristics	(	peripheral_id_t	peripheralId,
		const char *	serviceUuid
	)

Gets 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

peripheralId	The UUID assigned by the system for the 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 a call to free().
Unity marshaling takes care of it.

◆ sgBleInitialize()

bool sgBleInitialize ( BluetoothStateUpdateCallback onBluetoothEvent )

Initializes the library for accessing BLE peripherals.

Parameters

onBluetoothEvent Called when the host device Bluetooth state changes.

Returns: Whether the initialization was successful.

◆ sgBleReadCharacteristic()

void sgBleReadCharacteristic	(	peripheral_id_t	peripheralId,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		ValueReadCallback	onValueRead,
		request_index_t	requestIndex
	)

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

peripheralId	The UUID assigned by the system for the 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.
requestIndex	The index of this request, passed back when calling `onRequestStatus`.

◆ sgBleReadPeripheralRssi()

void sgBleReadPeripheralRssi	(	peripheral_id_t	peripheralId,
		RssiReadCallback	onRssiRead,
		request_index_t	requestIndex
	)

Reads the Received Signal Strength Indicator (RSSI) of the given peripheral.

Parameters

peripheralId	The UUID assigned by the system for the peripheral.
onRssiRead	Called with the read RSSI.
requestIndex	The index of this request, passed back when calling `onRssiRead`.

◆ sgBleReleasePeripheral()

void sgBleReleasePeripheral ( peripheral_id_t peripheralId )

Releases the Peripheral object associated with the given peripheral id.

Parameters

peripheralId The UUID assigned by the system for the peripheral.

◆ sgBleSetNotifyCharacteristic()

void sgBleSetNotifyCharacteristic	(	peripheral_id_t	peripheralId,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		ValueReadCallback	onValueChanged,
		RequestStatusCallback	onRequestStatus,
		request_index_t	requestIndex
	)

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

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

Parameters

peripheralId	The UUID assigned by the system for the 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).
requestIndex	The index of this request, passed back when calling `onRequestStatus`.

◆ sgBleShutdown()

void sgBleShutdown ( )

Shuts down the library.

Scanning is stopped and all peripherals are disconnected and removed.

◆ sgBleStartScan()

bool sgBleStartScan	(	const char *	servicesUuids,
		bool	allowDuplicates,
		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

servicesUuids	Comma separated list of services UUIDs. Peripherals advertising at least one of the services will be reported. Notify for all peripherals if the list is null or empty.
allowDuplicates	If `false`, let the system coalesces multiple discoveries of the same peripheral into a single discovery event which preserves battery life. If `true`, generates a discovery event each time it receives an advertising packet from the peripheral
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	(	peripheral_id_t	peripheralId,
		const char *	serviceUuid,
		const char *	characteristicUuid,
		characteristic_index_t	instanceIndex,
		const void *	data,
		const size_t	length,
		bool	withoutResponse,
		RequestStatusCallback	onRequestStatus,
		request_index_t	requestIndex
	)

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

peripheralId	The UUID assigned by the system for the 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).
requestIndex	The index of this request, passed back when calling `onRequestStatus`.

Functions

Detailed Description

Function Documentation

◆ sgBleConnectPeripheral()

◆ sgBleCreatePeripheral()

◆ sgBleDisconnectPeripheral()

◆ sgBleGetCharacteristicProperties()

◆ sgBleGetDiscoveredServices()

◆ sgBleGetPeripheralMtu()

◆ sgBleGetPeripheralName()

◆ sgBleGetServiceCharacteristics()

◆ sgBleInitialize()

◆ sgBleReadCharacteristic()

◆ sgBleReadPeripheralRssi()

◆ sgBleReleasePeripheral()

◆ sgBleSetNotifyCharacteristic()

◆ sgBleShutdown()

◆ sgBleStartScan()

◆ sgBleWriteCharacteristic()