CharacteristicBase Class Reference

Base class for a BLE characteristic. More...

#include <cs_CharacteristicBase.h>

Inheritance diagram for CharacteristicBase:

Collaboration diagram for CharacteristicBase:

Classes
struct	chunked_notification_t

Public Member Functions
	CharacteristicBase ()
virtual	~CharacteristicBase ()
cs_ret_code_t	setName (const char *const name)
	Set the name of this characteristic. More...
cs_ret_code_t	setUuid (uint16_t uuid)
	Set the UUID of this characteristic. More...
cs_ret_code_t	setConfig (const characteristic_config_t &config)
	Set configuration for this characteristic. More...
cs_ret_code_t	setEventHandler (const characteristic_callback_t &closure)
	Register an event handler. More...
cs_ret_code_t	setValueBuffer (buffer_ptr_t buffer, cs_buffer_size_t size)
	Set the buffer to be used for the (plain text) characteristic value. More...
cs_ret_code_t	setInitialValueLength (cs_buffer_size_t size)
	Set the initial value length. More...
cs_ret_code_t	init (Service *svc)
	Initialize the characteristic: add it to the softdevice. More...
cs_ret_code_t	updateValue (uint16_t length)
	Call this function when you changed the characteristic value. More...
cs_ret_code_t	notify (uint16_t length=0, uint16_t offset=0)
	Notify or indicate the characteristic value. More...
cs_data_t	getValue ()
	Get the current (plain text) value. More...
uint16_t	getValueHandle ()
	Get the value handle. More...
uint16_t	getCccdHandle ()
	Get the CCCD handle. More...
bool	isSubscribedForNotifications ()
	Return true when the client subscribed for notifications or indications. More...

Protected Member Functions
void	onWrite (uint16_t length)
	Function to be called by the stack when this characteristic is written over BLE. More...
void	onNotificationDone ()
	Function to be called by the stack when the notification or indication has been sent. More...
void	onCccdWrite (const uint8_t *data, uint16_t size)
	Function to be called by the stack when this characteristic configuration is written over BLE. More...
void	onConnect ()
	Function to be called by the stack on connect. More...
void	onDisconnect ()
	Function to be called by the stack on disconnect. More...

Protected Attributes
friend	Service

Private Member Functions
cs_ret_code_t	initEncryptedBuffer ()
	Initialize the encrypted buffer. More...
void	deinitEncryptedBuffer ()
	Deallocates the encrypted buffer if it was allocated. More...
cs_ret_code_t	setGattValue ()
	Update the gatt value in the softdevice. More...
cs_ret_code_t	notifyMultipart ()
	Notify the value in parts. More...
uint16_t	getGattValueMaxLength ()
	Return the maximum length of the value used by the GATT server. More...
uint16_t	getGattValueLength ()
	Return the actual length of the value used by the GATT server. More...
uint8_t *	getGattValue ()
	Return the pointer to the memory where the value is accessed by the GATT server. More...
bool	isEncrypted ()
	Returns true when the characteristic value is or should be encrypted. More...

Private Attributes
bool	_initialized = false
	Whether this characteristic has been initialized. More...
const char *	_name = nullptr
	Name of this characteristic. More...
uint16_t	_uuid = 0
	UUID of this characteristic. More...
characteristic_config_t	_config = characteristic_config_t()
	The configuration of the characteristic. More...
characteristic_callback_t	_callback = {}
	The callback to call. More...
ble_gatts_char_handles_t	_handles = ble_gatts_char_handles_t()
	Handles, set by softdevice at init. More...
Service *	_service = nullptr
	Reference to corresponding service, set at init. More...
cs_data_t	_buffer = {}
	The buffer holding the (plain text) characteristic value. More...
uint16_t	_valueLength = 0
	Actual length of (plain text) data stored in the buffer. More...
cs_data_t	_encryptedBuffer = {}
	The buffer holding the encrypted characteristic value. More...
uint16_t	_encryptedValueLength = 0
	Actual length of the (encrypted) data stored in the buffer. More...
bool	_notificationPending = false
	Flag to indicate if notification or indication is pending to be sent. More...
uint16_t	_notificationOffset = 0
	When using the notification chunker, this is the current offset of the value to notify next. More...
bool	_subscribedForNotifications = false
	Whether the central subscribed for notifications. More...
bool	_subscribedForIndications = false
	Whether the central subscribed for indication. More...

Detailed Description

Base class for a BLE characteristic.

It provides:

• Easy configuration.
• Keeping up the state.
• Chunked notifications.
• An event callback.
• Automatic encryption when setting the value, decryption when receiving a value.

Constructor & Destructor Documentation

CharacteristicBase()

CharacteristicBase::CharacteristicBase

(

)

~CharacteristicBase()

virtual CharacteristicBase::~CharacteristicBase ( )

inlinevirtual

Member Function Documentation

deinitEncryptedBuffer()

void CharacteristicBase::deinitEncryptedBuffer ( )

private

Deallocates the encrypted buffer if it was allocated.

getCccdHandle()

uint16_t CharacteristicBase::getCccdHandle

(

)

Get the CCCD handle.

getGattValue()

uint8_t * CharacteristicBase::getGattValue ( )

private

Return the pointer to the memory where the value is accessed by the GATT server.

With encryption, this is the encrypted buffer. Without encryption, this is the value buffer.

getGattValueLength()

uint16_t CharacteristicBase::getGattValueLength ( )

private

Return the actual length of the value used by the GATT server.

With encryption, this is the length of the encrypted value. Without encryption, this is the same as the value size.

getGattValueMaxLength()

uint16_t CharacteristicBase::getGattValueMaxLength ( )

private

Return the maximum length of the value used by the GATT server.

With encryption, this is the maximum length that the value can be when encrypted. Without encryption, this is the same as the buffer size.

getValue()

cs_data_t CharacteristicBase::getValue

(

)

Get the current (plain text) value.

getValueHandle()

uint16_t CharacteristicBase::getValueHandle

(

)

Get the value handle.

init()

cs_ret_code_t CharacteristicBase::init

(

Service *

svc

)

Initialize the characteristic: add it to the softdevice.

Should be done after configuring name, permissions, value, etc.

initEncryptedBuffer()

cs_ret_code_t CharacteristicBase::initEncryptedBuffer ( )

private

Initialize the encrypted buffer.

Allocates a buffer if no shared encrypted buffer is used. Checks if the encrypted buffer is of correct size.

isEncrypted()

bool CharacteristicBase::isEncrypted ( )

private

Returns true when the characteristic value is or should be encrypted.

isSubscribedForNotifications()

bool CharacteristicBase::isSubscribedForNotifications

(

)

Return true when the client subscribed for notifications or indications.

notify()

cs_ret_code_t CharacteristicBase::notify	(	uint16_t	length = 0,
		uint16_t	offset = 0
	)

Notify or indicate the characteristic value.

When using the notification chunker, this will start sending the value in chunks.

Parameters

[in]	length	Number of bytes to send. Use 0 to send min(value size, max notification size) bytes.
[in]	offset	Offset in bytes of the value to send.

notifyMultipart()

cs_ret_code_t CharacteristicBase::notifyMultipart ( )

private

Notify the value in parts.

onCccdWrite()

void CharacteristicBase::onCccdWrite ( const uint8_t *  data, uint16_t  size  )

protected

Function to be called by the stack when this characteristic configuration is written over BLE.

onConnect()

void CharacteristicBase::onConnect ( )

protected

Function to be called by the stack on connect.

onDisconnect()

void CharacteristicBase::onDisconnect ( )

protected

Function to be called by the stack on disconnect.

onNotificationDone()

void CharacteristicBase::onNotificationDone ( )

protected

Function to be called by the stack when the notification or indication has been sent.

onWrite()

void CharacteristicBase::onWrite ( uint16_t  length )

protected

Function to be called by the stack when this characteristic is written over BLE.

setConfig()

cs_ret_code_t CharacteristicBase::setConfig

(

const characteristic_config_t &

config

)

Set configuration for this characteristic.

Must be done before init.

setEventHandler()

cs_ret_code_t CharacteristicBase::setEventHandler

(

const characteristic_callback_t &

closure

)

Register an event handler.

Must be done before init.

setGattValue()

cs_ret_code_t CharacteristicBase::setGattValue ( )

private

Update the gatt value in the softdevice.

setInitialValueLength()

cs_ret_code_t CharacteristicBase::setInitialValueLength

(

cs_buffer_size_t

size

)

Set the initial value length.

Must be done before init.

setName()

cs_ret_code_t CharacteristicBase::setName

(

const char *const

name

)

Set the name of this characteristic.

You must keep the string in memory. This is already the case when using a string literal: setName("myName");

setUuid()

cs_ret_code_t CharacteristicBase::setUuid

(

uint16_t

uuid

)

Set the UUID of this characteristic.

Must be done before init. The service UUID will be used as base.

setValueBuffer()

cs_ret_code_t CharacteristicBase::setValueBuffer	(	buffer_ptr_t	buffer,
		cs_buffer_size_t	size
	)

Set the buffer to be used for the (plain text) characteristic value.

Must be done before init.

updateValue()

cs_ret_code_t CharacteristicBase::updateValue

(

uint16_t

length

)

Call this function when you changed the characteristic value.

Parameters

[in]

length

The new length of the characteristic value.

Member Data Documentation

_buffer

cs_data_t CharacteristicBase::_buffer = {}

private

The buffer holding the (plain text) characteristic value.

_callback

characteristic_callback_t CharacteristicBase::_callback = {}

private

The callback to call.

_config

characteristic_config_t CharacteristicBase::_config = characteristic_config_t()

private

The configuration of the characteristic.

_encryptedBuffer

cs_data_t CharacteristicBase::_encryptedBuffer = {}

private

The buffer holding the encrypted characteristic value.

_encryptedValueLength

uint16_t CharacteristicBase::_encryptedValueLength = 0

private

Actual length of the (encrypted) data stored in the buffer.

_handles

ble_gatts_char_handles_t CharacteristicBase::_handles = ble_gatts_char_handles_t()

private

Handles, set by softdevice at init.

_initialized

bool CharacteristicBase::_initialized = false

private

Whether this characteristic has been initialized.

_name

const char* CharacteristicBase::_name = nullptr

private

Name of this characteristic.

_notificationOffset

uint16_t CharacteristicBase::_notificationOffset = 0

private

When using the notification chunker, this is the current offset of the value to notify next.

_notificationPending

bool CharacteristicBase::_notificationPending = false

private

Flag to indicate if notification or indication is pending to be sent.

_service

Service* CharacteristicBase::_service = nullptr

private

Reference to corresponding service, set at init.

_subscribedForIndications

bool CharacteristicBase::_subscribedForIndications = false

private

Whether the central subscribed for indication.

_subscribedForNotifications

bool CharacteristicBase::_subscribedForNotifications = false

private

Whether the central subscribed for notifications.

_uuid

uint16_t CharacteristicBase::_uuid = 0

private

UUID of this characteristic.

_valueLength

uint16_t CharacteristicBase::_valueLength = 0

private

Actual length of (plain text) data stored in the buffer.

Service

friend CharacteristicBase::Service

protected

---

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

• source/include/ble/cs_CharacteristicBase.h