A model of a remote BLE characteristic. More...

#include <NimBLERemoteCharacteristic.h>

Public Member Functions
	~NimBLERemoteCharacteristic ()
	Destructor.

bool	canBroadcast ()
	Does the characteristic support broadcasting? More...

bool	canIndicate ()
	Does the characteristic support indications? More...

bool	canNotify ()
	Does the characteristic support notifications? More...

bool	canRead ()
	Does the characteristic support reading? More...

bool	canWrite ()
	Does the characteristic support writing? More...

bool	canWriteNoResponse ()
	Does the characteristic support writing with no response? More...

std::vector< NimBLERemoteDescriptor * >::iterator	begin ()
	Get iterator to the beginning of the vector of remote descriptor pointers. More...

std::vector< NimBLERemoteDescriptor * >::iterator	end ()
	Get iterator to the end of the vector of remote descriptor pointers. More...

NimBLERemoteDescriptor *	getDescriptor (const NimBLEUUID &uuid)
	Get the descriptor instance with the given UUID that belongs to this characteristic. More...

std::vector< NimBLERemoteDescriptor * > *	getDescriptors (bool refresh=false)
	Get a pointer to the vector of found descriptors. More...

void	deleteDescriptors ()
	Delete the descriptors in the descriptor vector. More...

size_t	deleteDescriptor (const NimBLEUUID &uuid)
	Delete descriptor by UUID. More...

uint16_t	getHandle ()
	Get the handle for this characteristic. More...

uint16_t	getDefHandle ()
	Get the handle for this characteristics definition. More...

NimBLEUUID	getUUID ()
	Get the UUID for this characteristic. More...

NimBLEAttValue	readValue (time_t *timestamp=nullptr)
	Read the value of the remote characteristic. More...

std::string	toString ()
	Convert a NimBLERemoteCharacteristic to a string representation;. More...

NimBLERemoteService *	getRemoteService ()
	Get the remote service associated with this characteristic. More...

uint8_t	readUInt8 () __attribute__((deprecated("Use template readValue<uint8_t>()")))
	Read a byte value. More...

uint16_t	readUInt16 () __attribute__((deprecated("Use template readValue<uint16_t>()")))
	Read an unsigned 16 bit value. More...

uint32_t	readUInt32 () __attribute__((deprecated("Use template readValue<uint32_t>()")))
	Read an unsigned 32 bit value. More...

float	readFloat () __attribute__((deprecated("Use template readValue<float>()")))
	Read a float value. More...

NimBLEAttValue	getValue (time_t *timestamp=nullptr)
	Get the value of the remote characteristic. More...

bool	subscribe (bool notifications=true, notify_callback notifyCallback=nullptr, bool response=false)
	Subscribe for notifications or indications. More...

bool	unsubscribe (bool response=false)
	Unsubscribe for notifications or indications. More...

bool	registerForNotify (notify_callback notifyCallback, bool notifications=true, bool response=true) __attribute__((deprecated("Use subscribe()/unsubscribe()")))
	backward-compatibility method for subscribe/unsubscribe notifications/indications More...

bool	writeValue (const uint8_t *data, size_t length, bool response=false)
	Write a new value to the remote characteristic from a data buffer. More...

bool	writeValue (const std::vector< uint8_t > &v, bool response=false)
	Write a new value to the remote characteristic from a std::vector<uint8_t>. More...

bool	writeValue (const char *s, bool response=false)
	Write a new value to the remote characteristic from a const char*. More...

template<typename T >
bool	writeValue (const T &s, bool response=false)
	Template to set the remote characteristic value to <type>val. More...

template<typename T >
bool	writeValue (const T &s, bool response=false)
	Template to set the remote characteristic value to <type>val. More...

template<typename T >
T	getValue (time_t *timestamp=nullptr, bool skipSizeCheck=false)
	Template to convert the remote characteristic data to <type>. More...

template<typename T >
T	readValue (time_t *timestamp=nullptr, bool skipSizeCheck=false)
	Template to convert the remote characteristic data to <type>. More...

Detailed Description

A model of a remote BLE characteristic.

Member Function Documentation

◆ begin()

std::vector< NimBLERemoteDescriptor * >::iterator NimBLERemoteCharacteristic::begin ( )

Get iterator to the beginning of the vector of remote descriptor pointers.

Returns: An iterator to the beginning of the vector of remote descriptor pointers.

◆ canBroadcast()

bool NimBLERemoteCharacteristic::canBroadcast ( )

Does the characteristic support broadcasting?

Returns: True if the characteristic supports broadcasting.

◆ canIndicate()

bool NimBLERemoteCharacteristic::canIndicate ( )

Does the characteristic support indications?

Returns: True if the characteristic supports indications.

◆ canNotify()

bool NimBLERemoteCharacteristic::canNotify ( )

Does the characteristic support notifications?

Returns: True if the characteristic supports notifications.

◆ canRead()

bool NimBLERemoteCharacteristic::canRead ( )

Does the characteristic support reading?

Returns: True if the characteristic supports reading.

◆ canWrite()

bool NimBLERemoteCharacteristic::canWrite ( )

Does the characteristic support writing?

Returns: True if the characteristic supports writing.

◆ canWriteNoResponse()

bool NimBLERemoteCharacteristic::canWriteNoResponse ( )

Does the characteristic support writing with no response?

Returns: True if the characteristic supports writing with no response.

◆ deleteDescriptor()

size_t NimBLERemoteCharacteristic::deleteDescriptor ( const NimBLEUUID & uuid )

Delete descriptor by UUID.

Parameters

[in] uuid The UUID of the descriptor to be deleted.

Returns: Number of descriptors left in the vector.

◆ deleteDescriptors()

void NimBLERemoteCharacteristic::deleteDescriptors ( )

Delete the descriptors in the descriptor vector.

We maintain a vector called m_descriptorVector that contains pointers to NimBLERemoteDescriptors object references. Since we allocated these in this class, we are also responsible for deleting them. This method does just that.

◆ end()

std::vector< NimBLERemoteDescriptor * >::iterator NimBLERemoteCharacteristic::end ( )

Get iterator to the end of the vector of remote descriptor pointers.

Returns: An iterator to the end of the vector of remote descriptor pointers.

◆ getDefHandle()

uint16_t NimBLERemoteCharacteristic::getDefHandle ( )

Get the handle for this characteristics definition.

Returns: The handle for this characteristic definition.

◆ getDescriptor()

NimBLERemoteDescriptor * NimBLERemoteCharacteristic::getDescriptor ( const NimBLEUUID & uuid )

Get the descriptor instance with the given UUID that belongs to this characteristic.

Parameters

[in] uuid The UUID of the descriptor to find.

Returns: The Remote descriptor (if present) or null if not present.

◆ getDescriptors()

std::vector< NimBLERemoteDescriptor * > * NimBLERemoteCharacteristic::getDescriptors ( bool refresh = false )

Get a pointer to the vector of found descriptors.

Parameters

[in] refresh If true the current descriptor vector will be cleared and
all descriptors for this characteristic retrieved from the peripheral.
If false the vector will be returned with the currently stored descriptors of this characteristic.

Returns: A pointer to the vector of descriptors for this characteristic.

◆ getHandle()

uint16_t NimBLERemoteCharacteristic::getHandle ( )

Get the handle for this characteristic.

Returns: The handle for this characteristic.

◆ getRemoteService()

NimBLERemoteService * NimBLERemoteCharacteristic::getRemoteService ( )

Get the remote service associated with this characteristic.

Returns: The remote service associated with this characteristic.

◆ getUUID()

NimBLEUUID NimBLERemoteCharacteristic::getUUID ( )

Get the UUID for this characteristic.

Returns: The UUID for this characteristic.

◆ getValue() [1/2]

NimBLEAttValue NimBLERemoteCharacteristic::getValue ( time_t * timestamp = nullptr )

Get the value of the remote characteristic.

Parameters

[in] timestamp A pointer to a time_t struct to store the time the value was read.

Returns: The value of the remote characteristic.

◆ getValue() [2/2]

template<typename T >

T NimBLERemoteCharacteristic::getValue	(	time_t *	timestamp = `nullptr`,
		bool	skipSizeCheck = `false`
	)

inline

Template to convert the remote characteristic data to <type>.

Template Parameters

T	The type to convert the data to.

Parameters

[in]	timestamp	A pointer to a time_t struct to store the time the value was read.
[in]	skipSizeCheck	If true it will skip checking if the data size is less than `sizeof(<type>)`.

Returns: The data converted to <type> or NULL if skipSizeCheck is false and the data is less than sizeof(<type>).

Use: getValue<type>(&timestamp, skipSizeCheck);

◆ readFloat()

float NimBLERemoteCharacteristic::readFloat ( )

Read a float value.

Returns: the float value.

◆ readUInt16()

uint16_t NimBLERemoteCharacteristic::readUInt16 ( )

Read an unsigned 16 bit value.

Returns: The unsigned 16 bit value.

Deprecated:: Use readValue<uint16_t>().

◆ readUInt32()

uint32_t NimBLERemoteCharacteristic::readUInt32 ( )

Read an unsigned 32 bit value.

Returns: the unsigned 32 bit value.

Deprecated:: Use readValue<uint32_t>().

◆ readUInt8()

uint8_t NimBLERemoteCharacteristic::readUInt8 ( )

Read a byte value.

Returns: The value as a byte

Deprecated:: Use readValue<uint8_t>().

◆ readValue() [1/2]

NimBLEAttValue NimBLERemoteCharacteristic::readValue ( time_t * timestamp = nullptr )

Read the value of the remote characteristic.

Parameters

[in] timestamp A pointer to a time_t struct to store the time the value was read.

Returns: The value of the remote characteristic.

◆ readValue() [2/2]

template<typename T >

T NimBLERemoteCharacteristic::readValue	(	time_t *	timestamp = `nullptr`,
		bool	skipSizeCheck = `false`
	)

inline

Template to convert the remote characteristic data to <type>.

Template Parameters

T	The type to convert the data to.

Parameters

[in]	timestamp	A pointer to a time_t struct to store the time the value was read.
[in]	skipSizeCheck	If true it will skip checking if the data size is less than `sizeof(<type>)`.

Returns: The data converted to <type> or NULL if skipSizeCheck is false and the data is less than sizeof(<type>).

Use: readValue<type>(&timestamp, skipSizeCheck);

◆ registerForNotify()

bool NimBLERemoteCharacteristic::registerForNotify	(	notify_callback	notifyCallback,
		bool	notifications = `true`,
		bool	response = `true`
	)

backward-compatibility method for subscribe/unsubscribe notifications/indications

Parameters

[in]	notifyCallback	A callback to be invoked for a notification. If NULL is provided then we will unregister for notifications.
[in]	notifications	If true, register for notifications, false register for indications.
[in]	response	If true, require a write response from the descriptor write operation.

Returns: true if successful.

Deprecated:: Use subscribe() / unsubscribe() instead.

◆ subscribe()

bool NimBLERemoteCharacteristic::subscribe	(	bool	notifications = `true`,
		notify_callback	notifyCallback = `nullptr`,
		bool	response = `false`
	)

Subscribe for notifications or indications.

Parameters

[in]	notifications	If true, subscribe for notifications, false subscribe for indications.
[in]	notifyCallback	A callback to be invoked for a notification.
[in]	response	If true, require a write response from the descriptor write operation. If NULL is provided then no callback is performed.

Returns: false if writing to the descriptor failed.

◆ toString()

std::string NimBLERemoteCharacteristic::toString ( )

Convert a NimBLERemoteCharacteristic to a string representation;.

Returns: a String representation.

◆ unsubscribe()

bool NimBLERemoteCharacteristic::unsubscribe ( bool response = false )

Unsubscribe for notifications or indications.

Parameters

[in] response bool if true, require a write response from the descriptor write operation.

Returns: false if writing to the descriptor failed.

◆ writeValue() [1/5]

bool NimBLERemoteCharacteristic::writeValue	(	const char *	char_s,
		bool	response = `false`
	)

Write a new value to the remote characteristic from a const char*.

Parameters

[in]	char_s	A character string to write to the remote characteristic.
[in]	response	Whether we require a response from the write.

Returns: false if not connected or otherwise cannot perform write.

◆ writeValue() [2/5]

bool NimBLERemoteCharacteristic::writeValue	(	const std::vector< uint8_t > &	vec,
		bool	response = `false`
	)

Write a new value to the remote characteristic from a std::vector<uint8_t>.

Parameters

[in]	vec	A std::vector<uint8_t> value to write to the remote characteristic.
[in]	response	Whether we require a response from the write.

Returns: false if not connected or otherwise cannot perform write.

◆ writeValue() [3/5]

template<typename T >

bool NimBLERemoteCharacteristic::writeValue	(	const T &	s,
		bool	response = `false`
	)

inline

Template to set the remote characteristic value to <type>val.

Parameters

[in]	s	The value to write.
[in]	response	True == request write response.

Only used for non-arrays and types without a c_str() method.

◆ writeValue() [4/5]

template<typename T >

bool NimBLERemoteCharacteristic::writeValue	(	const T &	s,
		bool	response = `false`
	)

inline

Template to set the remote characteristic value to <type>val.

Parameters

[in]	s	The value to write.
[in]	response	True == request write response.

Only used if the <type> has a c_str() method.

◆ writeValue() [5/5]

bool NimBLERemoteCharacteristic::writeValue	(	const uint8_t *	data,
		size_t	length,
		bool	response = `false`
	)

Write a new value to the remote characteristic from a data buffer.

Parameters

[in]	data	A pointer to a data buffer.
[in]	length	The length of the data in the data buffer.
[in]	response	Whether we require a response from the write.

Returns: false if not connected or otherwise cannot perform write.

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ canBroadcast()

◆ canIndicate()

◆ canNotify()

◆ canRead()

◆ canWrite()

◆ canWriteNoResponse()

◆ deleteDescriptor()

◆ deleteDescriptors()

◆ end()

◆ getDefHandle()

◆ getDescriptor()

◆ getDescriptors()

◆ getHandle()

◆ getRemoteService()

◆ getUUID()

◆ getValue() [1/2]

◆ getValue() [2/2]

◆ readFloat()

◆ readUInt16()

◆ readUInt32()

◆ readUInt8()

◆ readValue() [1/2]

◆ readValue() [2/2]

◆ registerForNotify()

◆ subscribe()

◆ toString()

◆ unsubscribe()

◆ writeValue() [1/5]

◆ writeValue() [2/5]

◆ writeValue() [3/5]

◆ writeValue() [4/5]

◆ writeValue() [5/5]