The model of a BLE Characteristic. More...

#include <NimBLECharacteristic.h>

Inherits NimBLELocalValueAttribute.

Public Member Functions
	NimBLECharacteristic (const char uuid, uint16_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t maxLen=BLE_ATT_ATTR_MAX_LEN, NimBLEService pService=nullptr)
	Construct a characteristic.

	NimBLECharacteristic (const NimBLEUUID &uuid, uint16_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t maxLen=BLE_ATT_ATTR_MAX_LEN, NimBLEService *pService=nullptr)
	Construct a characteristic.

	~NimBLECharacteristic ()
	Destructor.

std::string	toString () const
	Return a string representation of the characteristic.

void	addDescriptor (NimBLEDescriptor *pDescriptor)
	Add a descriptor to the characteristic.

void	removeDescriptor (NimBLEDescriptor *pDescriptor, bool deleteDsc=false)
	Remove a descriptor from the characteristic.

uint16_t	getProperties () const
	Get the properties of the characteristic.

void	setCallbacks (NimBLECharacteristicCallbacks *pCallbacks)
	Set the callback handlers for this characteristic.

bool	indicate (uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Send an indication.

bool	indicate (const uint8_t *value, size_t length, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Send an indication.

bool	notify (uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Send a notification.

bool	notify (const uint8_t *value, size_t length, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Send a notification.

NimBLEDescriptor *	createDescriptor (const char *uuid, uint32_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t maxLen=BLE_ATT_ATTR_MAX_LEN)
	Create a new BLE Descriptor associated with this characteristic.

NimBLEDescriptor *	createDescriptor (const NimBLEUUID &uuid, uint32_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t maxLen=BLE_ATT_ATTR_MAX_LEN)
	Create a new BLE Descriptor associated with this characteristic.

NimBLE2904 *	create2904 ()
	Create a Characteristic Presentation Format Descriptor for this characteristic.

NimBLEDescriptor *	getDescriptorByUUID (const char *uuid, uint16_t index=0) const
	Return the BLE Descriptor for the given UUID.

NimBLEDescriptor *	getDescriptorByUUID (const NimBLEUUID &uuid, uint16_t index=0) const
	Return the BLE Descriptor for the given UUID.

NimBLEDescriptor *	getDescriptorByHandle (uint16_t handle) const
	Return the BLE Descriptor for the given handle.

NimBLEService *	getService () const
	Get the service that owns this characteristic.

NimBLECharacteristicCallbacks *	getCallbacks () const
	Get the callback handlers for this characteristic.

template<typename T >
bool	notify (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a notification with a value from a struct or array.

template<typename T >
bool	notify (const T &s, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a notification with a value from a class that has a c_str() and length() method.

template<typename T >
bool	notify (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a notification with a value from a class that has a data() and size() method with value_type.

template<typename T >
bool	notify (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a notification with a value from a class that has a data() and size() method without value_type.

template<typename T >
bool	indicate (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send an indication with a value from a struct or array.

template<typename T >
bool	indicate (const T &s, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a indication with a value from a class that has a c_str() and length() method.

template<typename T >
bool	indicate (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a indication with a value from a class that has a data() and size() method with value_type.

template<typename T >
bool	indicate (const T &v, uint16_t connHandle=BLE_HS_CONN_HANDLE_NONE) const
	Template to send a indication with a value from a class that has a data() and size() method without value_type.

Detailed Description

The model of a BLE Characteristic.

A BLE Characteristic is an identified value container that manages a value. It is exposed by a BLE service and can be read and written to by a BLE client.

Constructor & Destructor Documentation

◆ NimBLECharacteristic() [1/2]

NimBLECharacteristic::NimBLECharacteristic	(	const char *	uuid,
		uint16_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	maxLen = `BLE_ATT_ATTR_MAX_LEN`,
		NimBLEService *	pService = `nullptr`
	)

Construct a characteristic.

Parameters

[in]	uuid	- UUID (const char*) for the characteristic.
[in]	properties	- Properties for the characteristic.
[in]	maxLen	- The maximum length in bytes that the characteristic value can hold. (Default: 512 bytes for esp32, 20 for all others).
[in]	pService	- pointer to the service instance this characteristic belongs to.

◆ NimBLECharacteristic() [2/2]

NimBLECharacteristic::NimBLECharacteristic	(	const NimBLEUUID &	uuid,
		uint16_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	maxLen = `BLE_ATT_ATTR_MAX_LEN`,
		NimBLEService *	pService = `nullptr`
	)

Construct a characteristic.

Parameters

[in]	uuid	- UUID for the characteristic.
[in]	properties	- Properties for the characteristic.
[in]	maxLen	- The maximum length in bytes that the characteristic value can hold. (Default: 512 bytes for esp32, 20 for all others).
[in]	pService	- pointer to the service instance this characteristic belongs to.

Member Function Documentation

◆ addDescriptor()

void NimBLECharacteristic::addDescriptor ( NimBLEDescriptor * pDescriptor )

Add a descriptor to the characteristic.

Parameters

[in] pDescriptor A pointer to the descriptor to add.

◆ create2904()

NimBLE2904 * NimBLECharacteristic::create2904 ( )

Create a Characteristic Presentation Format Descriptor for this characteristic.

Returns: A pointer to a NimBLE2904 descriptor.

◆ createDescriptor() [1/2]

NimBLEDescriptor * NimBLECharacteristic::createDescriptor	(	const char *	uuid,
		uint32_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	maxLen = `BLE_ATT_ATTR_MAX_LEN`
	)

Create a new BLE Descriptor associated with this characteristic.

Parameters

[in]	uuid	- The UUID of the descriptor.
[in]	properties	- The properties of the descriptor.
[in]	maxLen	- The max length in bytes of the descriptor value.

Returns: The new BLE descriptor.

◆ createDescriptor() [2/2]

NimBLEDescriptor * NimBLECharacteristic::createDescriptor	(	const NimBLEUUID &	uuid,
		uint32_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	maxLen = `BLE_ATT_ATTR_MAX_LEN`
	)

Create a new BLE Descriptor associated with this characteristic.

Parameters

[in]	uuid	- The UUID of the descriptor.
[in]	properties	- The properties of the descriptor.
[in]	maxLen	- The max length in bytes of the descriptor value.

Returns: The new BLE descriptor.

◆ getDescriptorByHandle()

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByHandle ( uint16_t handle ) const

Return the BLE Descriptor for the given handle.

Parameters

[in] handle The handle of the descriptor.

Returns: A pointer to the descriptor object or nullptr if not found.

◆ getDescriptorByUUID() [1/2]

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByUUID	(	const char *	uuid,
		uint16_t	index = `0`
	)		const

Return the BLE Descriptor for the given UUID.

Parameters

[in]	uuid	The UUID of the descriptor.
[in]	index	The index of the descriptor to return (used when multiple descriptors have the same UUID).

Returns: A pointer to the descriptor object or nullptr if not found.

◆ getDescriptorByUUID() [2/2]

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByUUID	(	const NimBLEUUID &	uuid,
		uint16_t	index = `0`
	)		const

Return the BLE Descriptor for the given UUID.

Parameters

[in]	uuid	The UUID of the descriptor.
[in]	index	The index of the descriptor to return (used when multiple descriptors have the same UUID).

Returns: A pointer to the descriptor object or nullptr if not found.

◆ getProperties()

uint16_t NimBLECharacteristic::getProperties ( ) const

Get the properties of the characteristic.

Returns: The properties of the characteristic.

◆ indicate() [1/6]

template<typename T >

bool NimBLECharacteristic::indicate	(	const T &	s,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a indication with a value from a class that has a c_str() and length() method.

Parameters

[in]	s	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

◆ indicate() [2/6]

template<typename T >

bool NimBLECharacteristic::indicate	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send an indication with a value from a struct or array.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

<type> size must be evaluatable by sizeof().

◆ indicate() [3/6]

template<typename T >

bool NimBLECharacteristic::indicate	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a indication with a value from a class that has a data() and size() method with value_type.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

Correctly calculates byte size for containers with multi-byte element types.

◆ indicate() [4/6]

template<typename T >

bool NimBLECharacteristic::indicate	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a indication with a value from a class that has a data() and size() method without value_type.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

◆ indicate() [5/6]

bool NimBLECharacteristic::indicate	(	const uint8_t *	value,
		size_t	length,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

Send an indication.

Parameters

[in]	value	A pointer to the data to send.
[in]	length	The length of the data to send.
[in]	connHandle	Connection handle to send an individual indication, or BLE_HS_CONN_HANDLE_NONE to send the indication to all subscribed clients.

Returns: True if the indication was sent successfully, false otherwise.

◆ indicate() [6/6]

bool NimBLECharacteristic::indicate ( uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE ) const

Send an indication.

Parameters

[in] connHandle Connection handle to send an individual indication, or BLE_HS_CONN_HANDLE_NONE to send the indication to all subscribed clients.

Returns: True if the indication was sent successfully, false otherwise.

◆ notify() [1/6]

template<typename T >

bool NimBLECharacteristic::notify	(	const T &	s,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a notification with a value from a class that has a c_str() and length() method.

Parameters

[in]	s	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

◆ notify() [2/6]

template<typename T >

bool NimBLECharacteristic::notify	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a notification with a value from a struct or array.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

<type> size must be evaluatable by sizeof().

◆ notify() [3/6]

template<typename T >

bool NimBLECharacteristic::notify	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a notification with a value from a class that has a data() and size() method with value_type.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

Correctly calculates byte size for containers with multi-byte element types.

◆ notify() [4/6]

template<typename T >

bool NimBLECharacteristic::notify	(	const T &	v,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

inline

Template to send a notification with a value from a class that has a data() and size() method without value_type.

Parameters

[in]	v	The value to send.
[in]	connHandle	Optional, a connection handle to send the notification to.

◆ notify() [5/6]

bool NimBLECharacteristic::notify	(	const uint8_t *	value,
		size_t	length,
		uint16_t	connHandle = `BLE_HS_CONN_HANDLE_NONE`
	)		const

Send a notification.

Parameters

[in]	value	A pointer to the data to send.
[in]	length	The length of the data to send.
[in]	connHandle	Connection handle to send an individual notification, or BLE_HS_CONN_HANDLE_NONE to send the notification to all subscribed clients.

Returns: True if the notification was sent successfully, false otherwise.

◆ notify() [6/6]

bool NimBLECharacteristic::notify ( uint16_t connHandle = BLE_HS_CONN_HANDLE_NONE ) const

Send a notification.

Parameters

[in] connHandle Connection handle to send an individual notification, or BLE_HS_CONN_HANDLE_NONE to send the notification to all subscribed clients.

Returns: True if the notification was sent successfully, false otherwise.

◆ removeDescriptor()

void NimBLECharacteristic::removeDescriptor	(	NimBLEDescriptor *	pDescriptor,
		bool	deleteDsc = `false`
	)

Remove a descriptor from the characteristic.

Parameters

[in]	pDescriptor	A pointer to the descriptor instance to remove from the characteristic.
[in]	deleteDsc	If true it will delete the descriptor instance and free it's resources.

◆ setCallbacks()

void NimBLECharacteristic::setCallbacks ( NimBLECharacteristicCallbacks * pCallbacks )

Set the callback handlers for this characteristic.

Parameters

[in] pCallbacks An instance of a NimBLECharacteristicCallbacks class
used to define any callbacks for the characteristic.

◆ toString()

std::string NimBLECharacteristic::toString ( ) const

Return a string representation of the characteristic.

Returns: A string representation of the characteristic.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NimBLECharacteristic() [1/2]

◆ NimBLECharacteristic() [2/2]

Member Function Documentation

◆ addDescriptor()

◆ create2904()

◆ createDescriptor() [1/2]

◆ createDescriptor() [2/2]

◆ getDescriptorByHandle()

◆ getDescriptorByUUID() [1/2]

◆ getDescriptorByUUID() [2/2]

◆ getProperties()

◆ indicate() [1/6]

◆ indicate() [2/6]

◆ indicate() [3/6]

◆ indicate() [4/6]

◆ indicate() [5/6]

◆ indicate() [6/6]

◆ notify() [1/6]

◆ notify() [2/6]

◆ notify() [3/6]

◆ notify() [4/6]

◆ notify() [5/6]

◆ notify() [6/6]

◆ removeDescriptor()

◆ setCallbacks()

◆ toString()