Represents a GATT Characteristic with its declaration, value, and descriptors. More...

#include <characteristic.hpp>

Inheritance diagram for c7222::Characteristic:

Collaboration diagram for c7222::Characteristic:

Classes
struct	EventHandler
	Characteristic event handler structure. More...

Public Types
Types and Configuration Enums
Type definitions and configuration enums for characteristics.
enum class	Properties : uint8_t { kNone = 0x00 , kBroadcast = 0x01 , kRead = 0x02 , kWriteWithoutResponse = 0x04 , kWrite = 0x08 , kNotify = 0x10 , kIndicate = 0x20 , kAuthenticatedSignedWrites = 0x40 , kExtendedProperties = 0x80 }
	GATT Characteristic Properties as defined in Bluetooth Core Spec. More...

enum class	CCCDProperties : uint16_t { kNone = 0x0000 , kNotifications = 0x0001 , kIndications = 0x0002 }
	Client Characteristic Configuration Descriptor (CCCD) bit values. More...

enum class	SCCDProperties : uint16_t { kNone = 0x0000 , kBroadcasts = 0x0001 }
	Server Characteristic Configuration Descriptor (SCCD) bit values. More...

enum class	ExtendedProperties : uint16_t { kNone = 0x0000 , kReliableWrite = 0x0001 , kWritableAuxiliaries = 0x0002 }
	Characteristic Extended Properties bit values. More...

enum class	SecurityLevel : uint8_t { kNone = 0 , kEncryptionRequired = 1 , kAuthenticationRequired = 2 , kAuthorizationRequired = 3 }
	Security level requirements for read/write operations. More...

enum class	EventId : uint8_t { kHandleValueIndicationComplete , kAttEventEnd }
	Event IDs for Characteristic-related ATT events. More...

Public Member Functions
Core Accessors
Accessors for identifiers, handles, and validity checks.
const Uuid &	GetUuid () const
	Get the UUID of this characteristic.

Properties	GetProperties () const
	Get the properties of this characteristic.

uint16_t	GetValueHandle () const
	Get the handle of the Value attribute.

uint16_t	GetDeclarationHandle () const
	Get the handle of the Declaration attribute.

bool	IsValid () const
	Check if this characteristic is valid.

bool	IsThisCharacteristic (const Uuid &uuid, uint16_t handle) const
	Check if this characteristic matches the given UUID and handle.

bool	IsThisCharacteristic (const Uuid &uuid) const
	Check if this characteristic matches the given UUID.

bool	HasHandle (uint16_t handle) const
	Check if this characteristic owns the given handle.

Capability Checks
Helpers to query characteristic capability flags.
bool	HasBroadcast () const
	Check if characteristic supports broadcasts.

bool	CanRead () const
	Check if characteristic supports read operations.

bool	CanWriteWithoutResponse () const
	Check if characteristic supports write without response.

bool	CanWrite () const
	Check if characteristic supports write operations (with response).

bool	HasNotifications () const
	Check if characteristic supports notifications.

bool	HasIndications () const
	Check if characteristic supports indications.

bool	CanSignedWrite () const
	Check if characteristic supports authenticated signed writes.

bool	HasExtendedPropertiesCapability () const
	Check if characteristic properties flag has extended properties capability.

Security Requirement Checks
Helpers to inspect configured security requirements.
bool	ReadHasSecurityRequirement () const
	Check if characteristic has read permission bits set (requires authorization). Read permission bits 0 and 1 indicate security level requirements.

bool	WriteHasSecurityRequirement () const
	Check if characteristic has write permission bits set (requires authorization). Write permission bits 0 and 1 indicate security level requirements.

bool	ReadRequiresSC () const
	Check if characteristic read requires Secure Connections (SC).

bool	WriteRequiresSC () const
	Check if characteristic write requires Secure Connections (SC).

uint16_t	GetEncryptionKeySize () const
	Get the required encryption key size for this characteristic. Returns the encryption key size requirement encoded in bits 12-15.

bool	ReadRequiresAuthentication () const
	Check whether reads require authenticated pairing (MITM).

bool	WriteRequiresAuthentication () const
	Check whether writes require authenticated pairing (MITM).

bool	ReadRequiresAuthorization () const
	Check whether reads require application-level authorization.

bool	WriteRequiresAuthorization () const
	Check whether writes require application-level authorization.

bool	ReadRequiresEncryption () const
	Check whether reads require at least encrypted link security.

bool	WriteRequiresEncryption () const
	Check whether writes require at least encrypted link security.

bool	RequiresAuthentication () const
	Check whether any access requires authentication.

bool	RequiresAuthorization () const
	Check whether any access requires authorization.

bool	RequiresEncryption () const
	Check whether any access requires at least encrypted link security.

Security Configuration
APIs to configure required security levels.
void	SetReadSecurityLevel (SecurityLevel level)
	Set read security level requirement for this characteristic.

void	SetWriteSecurityLevel (SecurityLevel level)
	Set write security level requirement for this characteristic.

void	SetReadRequiresSecureConnections (bool required)
	Set Secure Connections requirement for reads.

void	SetWriteRequiresSecureConnections (bool required)
	Set Secure Connections requirement for writes.

void	SetEncryptionKeySize (uint8_t key_size)
	Set minimum encryption key size requirement.

SecurityLevel	GetReadSecurityLevel () const
	Get current read security level.

SecurityLevel	GetWriteSecurityLevel () const
	Get current write security level.

Permission Evaluation
Evaluate access permissions for a given connection state.
bool	IsReadPermitted (bool authorized, bool authenticated) const
	Check if read is permitted given the connection security state.

bool	IsWritePermitted (bool authorized, bool authenticated) const
	Check if write is permitted given the connection security state.

bool	Uses128BitUuid () const
	Check if characteristic has 128-bit UUID.

bool	IsDynamic () const
	Check if characteristic value is dynamic (can change).

Value Access
Read the current stored characteristic value.
const uint8_t *	GetValueData () const
	Get the current value data pointer. For dynamic values, this may change after SetValue() calls.

size_t	GetValueSize () const
	Get the size of the current value.

std::vector< uint8_t >	GetValueAsVector () const
	Get the complete value as a vector.

Value Updates
Update stored values and trigger update flow.
bool	SetValue (const uint8_t *data, size_t size)
	Set the characteristic value from raw bytes (pointer + size). Only allowed for dynamic characteristics.

bool	SetValue (std::vector< uint8_t > &&data)
	Set the characteristic value from an rvalue vector (move semantics). Only allowed for dynamic characteristics.

bool	SetValue (const std::vector< uint8_t > &data)
	Set the characteristic value from an lvalue vector (copy semantics). Only allowed for dynamic characteristics.

template<typename T >
bool	SetValue (const T &value)
	Set the characteristic value from a typed value (generic template). Converts any trivial type to bytes and stores as the value. Only allowed for dynamic characteristics.

Descriptor Management
Create and inspect standard and custom descriptors.
Attribute &	EnableCCCD ()
	Enable Client Characteristic Configuration Descriptor (CCCD). Required for characteristics with Notify or Indicate properties. Initializes CCCD with value {0x00, 0x00} (notifications and indications disabled).

bool	HasCCCD () const
	Check if CCCD descriptor is present.

bool	IsNotificationsEnabled () const
	Check if notifications are enabled via CCCD.

bool	IsIndicationsEnabled () const
	Check if indications are enabled via CCCD.

Attribute *	GetCCCD ()
	Get the CCCD descriptor.

const Attribute *	GetCCCD () const
	Get the CCCD descriptor (const version).

Attribute &	SetCCCDValue (CCCDProperties config)
	Set CCCD configuration value. Enables or configures notifications and/or indications. Automatically creates CCCD descriptor if not present.

Attribute &	EnableSCCD ()
	Enable Server Characteristic Configuration Descriptor (SCCD). Required for characteristics with Broadcast property. Initializes SCCD with value {0x00, 0x00} (broadcasts disabled).

bool	HasSCCD () const
	Check if SCCD descriptor is present.

bool	IsBroadcastEnabled () const
	Check if broadcasts are enabled via SCCD.

Attribute *	GetSCCD ()
	Get the SCCD descriptor.

const Attribute *	GetSCCD () const
	Get the SCCD descriptor (const version).

Attribute &	SetSCCDValue (SCCDProperties config)
	Set SCCD configuration value. Enables or disables broadcasts. Automatically creates SCCD descriptor if not present.

Attribute &	EnableExtendedProperties ()
	Enable Characteristic Extended Properties Descriptor. Defines additional characteristic properties beyond the standard properties byte. Initializes with value {0x00, 0x00} (no extended properties).

bool	HasExtendedProperties () const
	Check if Extended Properties descriptor is present.

Attribute *	GetExtendedProperties ()
	Get the Extended Properties descriptor.

const Attribute *	GetExtendedProperties () const
	Get the Extended Properties descriptor (const version).

Attribute &	SetExtendedPropertiesValue (ExtendedProperties config)
	Set Extended Properties configuration value. Configures reliable write and writable auxiliaries. Automatically creates Extended Properties descriptor if not present.

Attribute &	SetUserDescription (const std::string &description)
	Set the Characteristic User Description. Creates or updates the user-readable description of this characteristic.

const std::string *	SetUserDescriptionText (const std::string &description)
	Update the user description text if a User Description descriptor exists.

bool	HasUserDescription () const
	Check if User Description descriptor is present.

Attribute *	GetUserDescription ()
	Get the User Description descriptor.

const std::string &	GetUserDescriptionText () const
	Get the user description text.

const Attribute *	GetUserDescription () const
	Get the User Description descriptor (const version).

Attribute &	AddDescriptor (const Uuid &uuid, Attribute::Properties properties, const std::vector< uint8_t > &value, uint16_t handle=0)
	Add a custom descriptor to this characteristic. Allows extension with application-specific descriptors beyond CCCD and User Description.

size_t	GetDescriptorCount () const
	Get count of custom descriptors (excluding CCCD and User Description).

Attribute *	GetDescriptor (size_t index)
	Get a custom descriptor by index.

const Attribute *	GetDescriptor (size_t index) const
	Get a custom descriptor by index (const version).

Attribute Access
Access underlying Attribute objects.
Attribute &	GetDeclarationAttribute ()
	Get the Declaration Attribute. The declaration attribute contains properties, value handle, and UUID.

const Attribute &	GetDeclarationAttribute () const
	Get the Declaration Attribute (const version).

Attribute &	GetValueAttribute ()
	Get the Value Attribute. The value attribute holds the actual characteristic data.

const Attribute &	GetValueAttribute () const
	Get the Value Attribute (const version).

Event Handler Management
Register and manage characteristic event handlers.
void	AddEventHandler (EventHandler &handler)
	Register an event handler for this characteristic.

bool	RemoveEventHandler (const EventHandler &handler)
	Unregister an event handler from this characteristic.

void	ClearEventHandlers ()
	Clear all registered event handlers for this characteristic.

std::list< EventHandler * >	GetEventHandlers () const
	Get the list of registered event handlers.

Connection Handle Management
Manage the active connection handle used for updates.
void	SetConnectionHandle (uint16_t connection_handle)
	Set the connection handle for this characteristic.

uint16_t	GetConnectionHandle () const
	Get the current connection handle.

Stack Dispatch (Internal)
BLE stack entry points reserved for internal use.
virtual BleError	DispatchBleHciPacket (uint8_t packet_type, const uint8_t *packet_data, uint16_t packet_data_size)
	Dispatch BLE HCI packet to the appropriate event handler.

uint16_t	HandleAttributeRead (uint16_t attribute_handle, uint16_t offset, uint8_t *buffer, uint16_t buffer_size)
	Attribute read handler for BLE stack callbacks.

BleError	HandleAttributeWrite (uint16_t attribute_handle, uint16_t offset, const uint8_t *data, uint16_t size)
	Attribute write handler for BLE stack callbacks.

Public Member Functions inherited from c7222::MovableOnly
virtual	~MovableOnly ()=default

	MovableOnly (MovableOnly &&)=default

MovableOnly &	operator= (MovableOnly &&)=default

	MovableOnly ()=default

Public Member Functions inherited from c7222::NonCopyable
	NonCopyable (const NonCopyable &)=delete

NonCopyable &	operator= (const NonCopyable &)=delete

	NonCopyable (NonCopyable &&)=default

NonCopyable &	operator= (NonCopyable &&)=default

Protected Member Functions
Internal Event Fan-out
Internal event dispatch to registered handlers.
BleError	DispatchEvent (EventId event_id, const uint8_t *event_data, uint16_t event_data_size)
	Dispatch event to registered event handlers.

Internal Updates
Internal update/notification transport.
virtual BleError	UpdateValue ()
	Update the characteristic value and send notification/indication if enabled.

Protected Member Functions inherited from c7222::NonCopyable
	NonCopyable ()=default

	~NonCopyable ()=default

Friends
std::ostream &	operator<< (std::ostream &os, const Characteristic &characteristic)
	Stream insertion operator for Characteristic. Outputs the characteristic UUID, properties, security requirements, and descriptors.

Construction and Parsing
APIs for building or parsing characteristics.
	Characteristic (const Uuid &uuid, uint8_t properties, uint16_t declaration_handle, uint16_t value_handle)
	Construct a new Characteristic with declaration data. Creates the characteristic with proper declaration attribute. The value handle is typically declaration_handle + 1.

	Characteristic (Attribute &&decl_attribute, Attribute &&value_attr, std::list< Attribute > &&descriptor_attrs)
	Construct a Characteristic by moving parsed attributes.

	Characteristic (Characteristic &&other) noexcept
	Move constructor. Transfers ownership of all internal attributes and descriptors.

Characteristic &	operator= (Characteristic &&other) noexcept
	Move assignment operator. Transfers ownership of all internal attributes and descriptors.

	Characteristic ()=delete
	Construct a new Characteristic object (deleted). Prevents default construction without parameters.

	~Characteristic () override=default
	Destructor. Cleans up all managed attributes and descriptors.

static std::optional< Characteristic >	ParseFromAttributes (std::list< Attribute > &attributes)
	Parse the first characteristic from a list of attributes.

Detailed Description

Represents a GATT Characteristic with its declaration, value, and descriptors.

A GATT Characteristic consists of:

Characteristic Declaration attribute (mandatory)
Characteristic Value attribute (mandatory)
Client Characteristic Configuration Descriptor - CCCD (optional, for notifications/indications)
Characteristic User Description (optional, 0x2901)
Additional descriptors (optional)

The Characteristic Declaration contains:

1 byte: Properties (Read, Write, Notify, Indicate, etc.)
2 bytes: Value handle (little-endian, points to the Value attribute)
2 or 16 bytes: Characteristic UUID (16-bit or 128-bit)

Characteristics are identified by their UUID and are the primary data containers in a GATT Service.

Construction / Parsing

There are two common ways to create a Characteristic:

Manual construction: Use the constructor with UUID, properties, and handles. This is useful when you are assembling attributes in code. In this path, the Characteristic synthesizes its Declaration and Value attributes in memory and stores them using owned dynamic storage rather than relying on an external ATT DB image.
Parse from attributes: Use ParseFromAttributes() to extract the first characteristic from an ordered attribute list (Declaration, Value, then Descriptors). The extracted attributes are removed from the list and moved into the new Characteristic; no attribute rebuilding is performed. Callbacks are not copied.

Event Handling Model

The class provides event callbacks via EventHandlers. These are invoked when:

A client writes to the CCCD or SCCD (enabling/disabling notifications, indications, or broadcasts).
A client reads or writes the characteristic value (OnRead, OnWrite).
An indication completes (OnConfirmationComplete), which is driven by HCI events.

The application must:

Register handlers with AddEventHandler().
Ensure the handler instances outlive the Characteristic (stored as pointers).
Feed HCI events into DispatchBleHciPacket() so indication completion and flow control (ATT_EVENT_CAN_SEND_NOW) are processed.
Set a valid connection handle via SetConnectionHandle() to allow notifications/indications to be transmitted when values update.

User Description Descriptor (0x2901)

This class treats the Characteristic User Description descriptor as a read-only, application-controlled string. Design principles:

Single handler policy: all User Description descriptors share the same internal read handler and the same write handler that always rejects writes.
Centralized storage: the user-facing string is stored in user_description_text_ and served directly by the read handler.
Explicit configuration: SetUserDescription() creates the descriptor (if needed) and updates the stored text; SetUserDescriptionText() updates the text only when a descriptor already exists.

BTstack note: BTstack's .gatt files do not allow setting the User Description text for a characteristic. The descriptor can be declared (0x2901), but its contents must be provided by the application at runtime (e.g., via SetUserDescription() / SetUserDescriptionText()).

Debug Logging

Characteristic emits debug prints for value reads/writes and CCCD/SCCD updates when the compile definition C7222_BLE_DEBUG is enabled.

In this project, you can enable it via CMake:

-DC7222_BLE_DEBUG=ON

RPi Pico (BTstack) Integration

On the Pico W BLE stack, the GATT database is compiled into a binary Attribute DB (typically att_db.h/att_db.c). The AttributeServer parses that binary blob into Attribute objects. You can then call ParseFromAttributes() to peel one characteristic at a time from the ordered list.

Important implications:

Manually constructed characteristics do not reference ATT DB storage for their synthesized Declaration and Value attributes; those bytes are owned by the characteristic-side runtime representation.
Parsed static attributes keep pointers into the DB blob; the DB memory must remain valid for the lifetime of the Attribute/Characteristic.
Parsing moves the attribute objects; callbacks are not copied, so register callbacks after parsing as needed.

Descriptor Model (what, when, and storage)

This implementation mirrors the Bluetooth Core Spec descriptor types and chooses dynamic vs static storage based on whether the value must change at runtime or be written by a client.

CCCD (0x2902, Client Characteristic Configuration Descriptor)
- Required when Notify or Indicate is set in the characteristic properties (Vol 3, Part G, 3.3.3.3).
- Created lazily by EnableCCCD() or SetCCCDValue(); initial value is {0x00, 0x00}.
- Properties: kRead | kWrite | kDynamic.
- Dynamic because clients enable/disable notifications/indications at runtime, and writes must be accepted via the write callback.
SCCD (0x2903, Server Characteristic Configuration Descriptor)
- Required when Broadcast is set in the characteristic properties (Vol 3, Part G, 3.3.3.4).
- Created lazily by EnableSCCD() or SetSCCDValue(); initial value is {0x00, 0x00}.
- Properties: kRead | kWrite | kDynamic.
- Dynamic because clients can toggle broadcast behavior at runtime.
Characteristic Extended Properties (0x2900)
- Used when ExtendedProperties is set (Vol 3, Part G, 3.3.3.1).
- Created by EnableExtendedProperties() or SetExtendedPropertiesValue().
- Properties: kRead only (read-only metadata).
- Static because the server defines these bits; clients only read them.
Characteristic User Description (0x2901)
- Optional, user-facing label for UI/diagnostics (Vol 3, Part G, 3.3.3.2).
- Created by SetUserDescription() or when AddDescriptor() sees UUID 0x2901.
- Properties: kRead only in this implementation.
- Static because it is server-supplied text that does not change at runtime.
Additional/custom descriptors
- Created with AddDescriptor().
- Storage is dynamic only if Attribute::Properties::kDynamic is set; otherwise values are stored as static data.
- This lets application-specific descriptors choose mutability and permissions explicitly.

Value Attribute Updates (read/write flow)

The value attribute is the primary data payload for the characteristic. This implementation uses internal read/write callbacks by default:

Client read flow:
1. ATT read hits the value attribute and invokes HandleValueRead().
2. OnRead handlers fire first, giving the app a chance to call SetValue() (dynamic only) to refresh data.
3. The current stored value is copied into the ATT response buffer.
Client write flow:
1. ATT write hits the value attribute and invokes HandleValueWrite().
2. The implementation validates permissions and copies the bytes into the value attribute (dynamic storage only).
3. OnWrite handlers are called after the value is stored.
Server-initiated updates:
- Call SetValue() to update the stored value, then call UpdateValue() to send notifications or indications if enabled.
- If both notification and indication bits are set, the implementation sends an indication and ignores notifications.

Important: if the application replaces the value attribute callbacks via SetReadCallback() or SetWriteCallback(), the default HandleValueRead() and HandleValueWrite() are bypassed. In that case, EventHandlers are not invoked automatically and the application is responsible for storage and side effects.

Security Queries (Planning Before Connections)

This class now provides higher-level security query helpers that map directly to the configured SecurityLevel bits on the value attribute:

Authentication queries: ReadRequiresAuthentication(), WriteRequiresAuthentication(), RequiresAuthentication()
Encryption queries: ReadRequiresEncryption(), WriteRequiresEncryption(), RequiresEncryption()
Authorization queries: ReadRequiresAuthorization(), WriteRequiresAuthorization(), RequiresAuthorization()

These helpers are intended to support service- and server-level security planning (for example, deciding whether a SecurityManager must be enabled) before connections are established.

Descriptor Security Enforcement

CCCD/SCCD writes are validated against the characteristic's security requirements in HandleCccdWrite() / HandleSccdWrite(). This ensures that clients cannot enable notifications/indications or broadcasts unless the active link meets the required security level (encryption, authentication, or authorization).

Internal/Reserved APIs (do not call from application code)

The following methods exist to integrate with the BLE stack and platform glue. They are not part of the public application API and should be considered reserved for internal use:

DispatchBleHciPacket() (HCI event dispatch/flow control)
HandleAttributeRead() / HandleAttributeWrite() (ATT read/write handlers)
DispatchEvent() (internal event fan-out)
UpdateValue() (platform transport of notifications/indications)
HandleCccdWrite() / HandleSccdWrite() (descriptor write handling)
HandleValueRead() / HandleValueWrite() (value attribute handlers)
Attribute factories for standard declarations/descriptors

Note: Only one of Notify or Indicate should be set; both require CCCD descriptor.; Read callbacks are required for dynamic read attributes.; Write callbacks are required for write-enabled attributes.

Member Enumeration Documentation

◆ CCCDProperties

enum class c7222::Characteristic::CCCDProperties : uint16_t

strong

Client Characteristic Configuration Descriptor (CCCD) bit values.

CCCD allows clients to configure notifications and indications for a characteristic.

Note: As per Bluetooth Core Spec Vol 3, Part G, Section 3.3.3.3

Enumerator
kNone	Neither notifications nor indications enabled.
kNotifications	Notifications enabled.
kIndications	Indications enabled.

◆ EventId

enum class c7222::Characteristic::EventId : uint8_t

strong

Event IDs for Characteristic-related ATT events.

Enumerator
kHandleValueIndicationComplete	ATT Handle Value Indication Complete (confirmation received or timeout).
kAttEventEnd	Generic ATT event (extensible for future events).

◆ ExtendedProperties

enum class c7222::Characteristic::ExtendedProperties : uint16_t

strong

Characteristic Extended Properties bit values.

Extended Properties descriptor defines additional characteristic properties.

Note: As per Bluetooth Core Spec Vol 3, Part G, Section 3.3.3.1

Enumerator
kNone	No extended properties.
kReliableWrite	Reliable Write enabled.
kWritableAuxiliaries	Writable Auxiliaries enabled.

◆ Properties

enum class c7222::Characteristic::Properties : uint8_t

strong

GATT Characteristic Properties as defined in Bluetooth Core Spec.

These properties appear in the first byte of the Characteristic Declaration. They define which operations are permitted on the characteristic value.

Note: As per Bluetooth Core Specification Vol 3, Part G, Section 3.3.1.1

Enumerator
kNone	No properties set.
kBroadcast	Characteristic supports broadcast.
kRead	Characteristic value can be read.
kWriteWithoutResponse	Characteristic value can be written without response.
kWrite	Characteristic value can be written with response.
kNotify	Characteristic supports notifications.
kIndicate	Characteristic supports indications.
kAuthenticatedSignedWrites	Characteristic supports authenticated signed writes.
kExtendedProperties	Characteristic has extended properties descriptor.

◆ SCCDProperties

enum class c7222::Characteristic::SCCDProperties : uint16_t

strong

Server Characteristic Configuration Descriptor (SCCD) bit values.

SCCD allows clients to configure broadcasts for a characteristic.

Note: As per Bluetooth Core Spec Vol 3, Part G, Section 3.3.3.4

Enumerator
kNone	Broadcasts disabled.
kBroadcasts	Broadcasts enabled.

◆ SecurityLevel

enum class c7222::Characteristic::SecurityLevel : uint8_t

strong

Security level requirements for read/write operations.

These levels define encryption and authentication requirements for accessing the characteristic value. The 2-bit encoding (Bit0 and Bit1) maps to BTstack's ATT_PROPERTY_READ/WRITE_PERMISSION_BIT_0 and BIT_1.

Security levels are enforced by the BLE stack and determine when a client can successfully read or write the characteristic.

Note: As per Bluetooth Core Specification and BTstack att_db.h

Enumerator
kNone	No security required (open access). Anyone can read/write without pairing or encryption. Bit pattern: 00b.
kEncryptionRequired	Unauthenticated pairing with encryption required. Client must pair and establish encrypted link (Just Works or Numeric Comparison). No MITM protection required. Bit pattern: 01b.
kAuthenticationRequired	Authenticated pairing with encryption required. Client must pair using authenticated method with MITM protection (Passkey Entry, Out of Band) and establish encrypted link. Bit pattern: 10b.
kAuthorizationRequired	Authenticated pairing with encryption AND authorization required. Highest security level: authenticated pairing plus application-level authorization check. Application must approve access even after successful authentication and encryption. Bit pattern: 11b.

Constructor & Destructor Documentation

◆ Characteristic() [1/4]

c7222::Characteristic::Characteristic	(	const Uuid &	uuid,
		uint8_t	properties,
		uint16_t	declaration_handle,
		uint16_t	value_handle
	)

explicit

Construct a new Characteristic with declaration data. Creates the characteristic with proper declaration attribute. The value handle is typically declaration_handle + 1.

Parameters

uuid	The UUID identifying this characteristic
properties	Characteristic properties bitfield (combination of Properties enum flags)
declaration_handle	Handle of the Declaration attribute
value_handle	Handle of the Value attribute (typically declaration_handle + 1)

◆ Characteristic() [2/4]

c7222::Characteristic::Characteristic	(	Attribute &&	decl_attribute,
		Attribute &&	value_attr,
		std::list< Attribute > &&	descriptor_attrs
	)

explicit

Construct a Characteristic by moving parsed attributes.

This constructor takes ownership of the declaration/value/descriptor attributes produced during parsing and avoids rebuilding them. Handles are preserved from the moved attributes.

Parameters

decl_attribute	Characteristic Declaration attribute (moved)
value_attr	Value attribute (moved)
descriptor_attrs	Descriptor attributes (moved)

◆ Characteristic() [3/4]

c7222::Characteristic::Characteristic ( Characteristic && other )

noexcept

Move constructor. Transfers ownership of all internal attributes and descriptors.

◆ Characteristic() [4/4]

c7222::Characteristic::Characteristic ( )

delete

Construct a new Characteristic object (deleted). Prevents default construction without parameters.

◆ ~Characteristic()

c7222::Characteristic::~Characteristic ( )

overridedefault

Destructor. Cleans up all managed attributes and descriptors.

Member Function Documentation

◆ AddDescriptor()

Attribute & c7222::Characteristic::AddDescriptor	(	const Uuid &	uuid,
		Attribute::Properties	properties,
		const std::vector< uint8_t > &	value,
		uint16_t	handle = `0`
	)

Add a custom descriptor to this characteristic. Allows extension with application-specific descriptors beyond CCCD and User Description.

Parameters

uuid	UUID of the descriptor
properties	Descriptor properties (typically Read and/or Write)
value	Initial value of the descriptor
handle	Optional handle for the descriptor (used in DB)

Returns: Reference to the newly added Attribute for callback configuration

◆ AddEventHandler()

void c7222::Characteristic::AddEventHandler ( EventHandler & handler )

Register an event handler for this characteristic.

The handler is stored as a pointer; it must outlive the Characteristic instance. Multiple handlers can be registered and will be called in the order they were added.

Parameters

handler Reference to the EventHandlers structure to register

Here is the caller graph for this function:

◆ CanRead()

bool c7222::Characteristic::CanRead ( ) const

inline

Check if characteristic supports read operations.

Returns: true if kRead property is set

◆ CanSignedWrite()

bool c7222::Characteristic::CanSignedWrite ( ) const

inline

Check if characteristic supports authenticated signed writes.

Returns: true if kAuthenticatedSignedWrites property is set

◆ CanWrite()

bool c7222::Characteristic::CanWrite ( ) const

inline

Check if characteristic supports write operations (with response).

Returns: true if kWrite property is set

◆ CanWriteWithoutResponse()

bool c7222::Characteristic::CanWriteWithoutResponse ( ) const

inline

Check if characteristic supports write without response.

Returns: true if kWriteWithoutResponse property is set

◆ ClearEventHandlers()

void c7222::Characteristic::ClearEventHandlers ( )

Clear all registered event handlers for this characteristic.

Note: The handler instances are not deleted by this method. Therefore, the caller must delete the objects if they were dynamically allocated.

◆ DispatchBleHciPacket()

virtual BleError c7222::Characteristic::DispatchBleHciPacket	(	uint8_t	packet_type,
		const uint8_t *	packet_data,
		uint16_t	packet_data_size
	)

virtual

Dispatch BLE HCI packet to the appropriate event handler.

This must be fed HCI events so that indication completion and ATT_EVENT_CAN_SEND_NOW flow control are handled.

Parameters

packet_type	The type of the HCI packet
packet_data	Pointer to the packet data
packet_data_size	Size of the packet data

Returns: BleError indicating success or failure

Note: Internal use only (platform BLE stack dispatch).

◆ DispatchEvent()

BleError c7222::Characteristic::DispatchEvent	(	EventId	event_id,
		const uint8_t *	event_data,
		uint16_t	event_data_size
	)

protected

Dispatch event to registered event handlers.

Parameters

event_id	The event identifier
event_data	Pointer to the event data
event_data_size	Size of the event data

Returns: BleError indicating success or failure

Note: Internal use only (event fan-out from stack dispatch).

◆ EnableCCCD()

Attribute & c7222::Characteristic::EnableCCCD ( )

Enable Client Characteristic Configuration Descriptor (CCCD). Required for characteristics with Notify or Indicate properties. Initializes CCCD with value {0x00, 0x00} (notifications and indications disabled).

Returns: Reference to the CCCD Attribute for further configuration

◆ EnableExtendedProperties()

Attribute & c7222::Characteristic::EnableExtendedProperties ( )

Enable Characteristic Extended Properties Descriptor. Defines additional characteristic properties beyond the standard properties byte. Initializes with value {0x00, 0x00} (no extended properties).

Returns: Reference to the Extended Properties Attribute for further configuration

◆ EnableSCCD()

Attribute & c7222::Characteristic::EnableSCCD ( )

Enable Server Characteristic Configuration Descriptor (SCCD). Required for characteristics with Broadcast property. Initializes SCCD with value {0x00, 0x00} (broadcasts disabled).

Returns: Reference to the SCCD Attribute for further configuration

◆ GetCCCD() [1/2]

Attribute * c7222::Characteristic::GetCCCD ( )

inline

Get the CCCD descriptor.

Returns: Pointer to CCCD Attribute, or nullptr if not enabled

◆ GetCCCD() [2/2]

const Attribute * c7222::Characteristic::GetCCCD ( ) const

inline

Get the CCCD descriptor (const version).

Returns: Const pointer to CCCD Attribute, or nullptr if not enabled

◆ GetConnectionHandle()

uint16_t c7222::Characteristic::GetConnectionHandle ( ) const

inline

Get the current connection handle.

Returns: The connection handle, or 0 if disconnected/invalid

◆ GetDeclarationAttribute() [1/2]

Attribute & c7222::Characteristic::GetDeclarationAttribute ( )

inline

Get the Declaration Attribute. The declaration attribute contains properties, value handle, and UUID.

Returns: Reference to the Declaration Attribute

◆ GetDeclarationAttribute() [2/2]

const Attribute & c7222::Characteristic::GetDeclarationAttribute ( ) const

inline

Get the Declaration Attribute (const version).

Returns: Const reference to the Declaration Attribute

◆ GetDeclarationHandle()

uint16_t c7222::Characteristic::GetDeclarationHandle ( ) const

inline

Get the handle of the Declaration attribute.

Returns: Declaration attribute handle

Here is the call graph for this function:

◆ GetDescriptor() [1/2]

Attribute * c7222::Characteristic::GetDescriptor ( size_t index )

Get a custom descriptor by index.

Parameters

index Index of the descriptor (0 to GetDescriptorCount()-1)

Returns: Pointer to the Attribute, or nullptr if index out of range

◆ GetDescriptor() [2/2]

const Attribute * c7222::Characteristic::GetDescriptor ( size_t index ) const

Get a custom descriptor by index (const version).

Parameters

index Index of the descriptor (0 to GetDescriptorCount()-1)

Returns: Const pointer to the Attribute, or nullptr if index out of range

◆ GetDescriptorCount()

size_t c7222::Characteristic::GetDescriptorCount ( ) const

inline

Get count of custom descriptors (excluding CCCD and User Description).

Returns: Number of additional descriptors

◆ GetEncryptionKeySize()

uint16_t c7222::Characteristic::GetEncryptionKeySize ( ) const

inline

Get the required encryption key size for this characteristic. Returns the encryption key size requirement encoded in bits 12-15.

Returns: Encryption key size (0-16 bytes), or 0 if no requirement

Here is the call graph for this function:

◆ GetEventHandlers()

std::list< EventHandler * > c7222::Characteristic::GetEventHandlers ( ) const

inline

Get the list of registered event handlers.

Returns: List of pointers to registered EventHandlers structures

◆ GetExtendedProperties() [1/2]

Attribute * c7222::Characteristic::GetExtendedProperties ( )

inline

Get the Extended Properties descriptor.

Returns: Pointer to Extended Properties Attribute, or nullptr if not enabled

◆ GetExtendedProperties() [2/2]

const Attribute * c7222::Characteristic::GetExtendedProperties ( ) const

inline

Get the Extended Properties descriptor (const version).

Returns: Const pointer to Extended Properties Attribute, or nullptr if not enabled

◆ GetProperties()

Properties c7222::Characteristic::GetProperties ( ) const

inline

Get the properties of this characteristic.

Returns: Bitmask of characteristic properties (Read, Write, Notify, etc.)

◆ GetReadSecurityLevel()

SecurityLevel c7222::Characteristic::GetReadSecurityLevel ( ) const

Get current read security level.

Returns: SecurityLevel extracted from read permission bits

◆ GetSCCD() [1/2]

Attribute * c7222::Characteristic::GetSCCD ( )

inline

Get the SCCD descriptor.

Returns: Pointer to SCCD Attribute, or nullptr if not enabled

◆ GetSCCD() [2/2]

const Attribute * c7222::Characteristic::GetSCCD ( ) const

inline

Get the SCCD descriptor (const version).

Returns: Const pointer to SCCD Attribute, or nullptr if not enabled

◆ GetUserDescription() [1/2]

Attribute * c7222::Characteristic::GetUserDescription ( )

inline

Get the User Description descriptor.

Returns: Pointer to User Description Attribute, or nullptr if not set

◆ GetUserDescription() [2/2]

const Attribute * c7222::Characteristic::GetUserDescription ( ) const

inline

Get the User Description descriptor (const version).

Returns: Const pointer to User Description Attribute, or nullptr if not set

◆ GetUserDescriptionText()

const std::string & c7222::Characteristic::GetUserDescriptionText ( ) const

inline

Get the user description text.

Returns: Reference to the user description text if set; empty string otherwise

This returns the current user description text. If the User Description descriptor is not present, it returns an empty string reference.

Here is the caller graph for this function:

◆ GetUuid()

const Uuid & c7222::Characteristic::GetUuid ( ) const

inline

Get the UUID of this characteristic.

Returns: Reference to the characteristic's UUID

◆ GetValueAsVector()

std::vector< uint8_t > c7222::Characteristic::GetValueAsVector ( ) const

Get the complete value as a vector.

Returns: Vector copy of the characteristic value

◆ GetValueAttribute() [1/2]

Attribute & c7222::Characteristic::GetValueAttribute ( )

inline

Get the Value Attribute. The value attribute holds the actual characteristic data.

Returns: Reference to the Value Attribute

◆ GetValueAttribute() [2/2]

const Attribute & c7222::Characteristic::GetValueAttribute ( ) const

inline

Get the Value Attribute (const version).

Returns: Const reference to the Value Attribute

◆ GetValueData()

const uint8_t * c7222::Characteristic::GetValueData ( ) const

Get the current value data pointer. For dynamic values, this may change after SetValue() calls.

Returns: Pointer to value data, or nullptr if no value set

◆ GetValueHandle()

uint16_t c7222::Characteristic::GetValueHandle ( ) const

inline

Get the handle of the Value attribute.

Returns: Value attribute handle (typically declaration_handle + 1)

Here is the call graph for this function:

◆ GetValueSize()

size_t c7222::Characteristic::GetValueSize ( ) const

Get the size of the current value.

Returns: Size in bytes of the characteristic value

◆ GetWriteSecurityLevel()

SecurityLevel c7222::Characteristic::GetWriteSecurityLevel ( ) const

Get current write security level.

Returns: SecurityLevel extracted from write permission bits

◆ HandleAttributeRead()

uint16_t c7222::Characteristic::HandleAttributeRead	(	uint16_t	attribute_handle,
		uint16_t	offset,
		uint8_t *	buffer,
		uint16_t	buffer_size
	)

Attribute read handler for BLE stack callbacks.

Note: Internal use only (ATT read handler).

◆ HandleAttributeWrite()

BleError c7222::Characteristic::HandleAttributeWrite	(	uint16_t	attribute_handle,
		uint16_t	offset,
		const uint8_t *	data,
		uint16_t	size
	)

Attribute write handler for BLE stack callbacks.

Note: Internal use only (ATT write handler).

◆ HasBroadcast()

bool c7222::Characteristic::HasBroadcast ( ) const

inline

Check if characteristic supports broadcasts.

Returns: true if kBroadcast property is set

◆ HasCCCD()

bool c7222::Characteristic::HasCCCD ( ) const

inline

Check if CCCD descriptor is present.

Returns: true if CCCD has been enabled

◆ HasExtendedProperties()

bool c7222::Characteristic::HasExtendedProperties ( ) const

inline

Check if Extended Properties descriptor is present.

Returns: true if Extended Properties has been enabled

◆ HasExtendedPropertiesCapability()

bool c7222::Characteristic::HasExtendedPropertiesCapability ( ) const

inline

Check if characteristic properties flag has extended properties capability.

Returns: true if kExtendedProperties property bit is set

◆ HasHandle()

bool c7222::Characteristic::HasHandle ( uint16_t handle ) const

Check if this characteristic owns the given handle.

Parameters

handle Attribute handle (declaration or value)

Returns: true if handle matches declaration, value, or descriptor

◆ HasIndications()

bool c7222::Characteristic::HasIndications ( ) const

inline

Check if characteristic supports indications.

Returns: true if kIndicate property is set

◆ HasNotifications()

bool c7222::Characteristic::HasNotifications ( ) const

inline

Check if characteristic supports notifications.

Returns: true if kNotify property is set

◆ HasSCCD()

bool c7222::Characteristic::HasSCCD ( ) const

inline

Check if SCCD descriptor is present.

Returns: true if SCCD has been enabled

◆ HasUserDescription()

bool c7222::Characteristic::HasUserDescription ( ) const

inline

Check if User Description descriptor is present.

Returns: true if user description has been set

Here is the caller graph for this function:

◆ IsBroadcastEnabled()

bool c7222::Characteristic::IsBroadcastEnabled ( ) const

Check if broadcasts are enabled via SCCD.

Returns: true if SCCD is present and broadcasts bit is set

◆ IsDynamic()

bool c7222::Characteristic::IsDynamic ( ) const

inline

Check if characteristic value is dynamic (can change).

Returns: true if kDynamic property is set

Here is the call graph for this function:

◆ IsIndicationsEnabled()

bool c7222::Characteristic::IsIndicationsEnabled ( ) const

Check if indications are enabled via CCCD.

Returns: true if CCCD is present and indications bit is set

◆ IsNotificationsEnabled()

bool c7222::Characteristic::IsNotificationsEnabled ( ) const

Check if notifications are enabled via CCCD.

Returns: true if CCCD is present and notifications bit is set

◆ IsReadPermitted()

bool c7222::Characteristic::IsReadPermitted	(	bool	authorized,
		bool	authenticated
	)		const

Check if read is permitted given the connection security state.

Evaluates whether a client with the given security state is allowed to read this characteristic based on the configured read security level and Secure Connections requirement.

Parameters

authorized	true if client is authorized (passed app-level authorization)
authenticated	true if client has authenticated pairing

Returns: true if read is permitted, false if security requirements not met

Note: Secure Connections requirement is checked separately and not included in this logic (caller must verify SC separately if needed)

if (characteristic.IsReadPermitted(user_authorized, is_authenticated)) {
    // Allow read operation
}

◆ IsThisCharacteristic() [1/2]

bool c7222::Characteristic::IsThisCharacteristic ( const Uuid & uuid ) const

Check if this characteristic matches the given UUID.

Parameters

uuid	UUID to compare

Returns: true if UUID matches

◆ IsThisCharacteristic() [2/2]

bool c7222::Characteristic::IsThisCharacteristic	(	const Uuid &	uuid,
		uint16_t	handle
	)		const

Check if this characteristic matches the given UUID and handle.

Parameters

uuid	UUID to compare
handle	Attribute handle (declaration or value)

Returns: true if both UUID matches and handle matches declaration or value

◆ IsValid()

bool c7222::Characteristic::IsValid ( ) const

Check if this characteristic is valid.

Returns: true if UUID is valid and handles are non-zero

◆ IsWritePermitted()

bool c7222::Characteristic::IsWritePermitted	(	bool	authorized,
		bool	authenticated
	)		const

Check if write is permitted given the connection security state.

Evaluates whether a client with the given security state is allowed to write this characteristic based on the configured write security level and Secure Connections requirement.

Parameters

authorized	true if client is authorized (passed app-level authorization)
authenticated	true if client has authenticated pairing

Returns: true if write is permitted, false if security requirements not met

Note: Secure Connections requirement is checked separately and not included in this logic (caller must verify SC separately if needed)

if (characteristic.IsWritePermitted(user_authorized, is_authenticated)) {
    // Allow write operation
}

◆ operator=()

Characteristic & c7222::Characteristic::operator= ( Characteristic && other )

noexcept

Move assignment operator. Transfers ownership of all internal attributes and descriptors.

◆ ParseFromAttributes()

static std::optional< Characteristic > c7222::Characteristic::ParseFromAttributes ( std::list< Attribute > & attributes )

static

Parse the first characteristic from a list of attributes.

This function scans the attribute list for the first Characteristic Declaration attribute, then groups the following attributes (value and descriptors) into a single Characteristic.

Implementation details:

Iterates the list in order; the first declaration starts a new characteristic.
Parses declaration value as: properties (1), value handle (2, LE), UUID (2 or 16).
Matches the value attribute by handle within the extracted slice.
Consumes following descriptor attributes until the next declaration or service.
Copies value bytes and descriptor bytes into the new Characteristic; callbacks are not copied.
Recognizes CCCD and User Description explicitly; other descriptors are added as custom.

Assumptions:

Attributes are ordered (Declaration, Value, Descriptors).
Declaration value length is 5 (16-bit UUID) or 19 (128-bit UUID).
Value handle in the declaration refers to the value attribute in the list.
Descriptor attributes follow the value attribute contiguously.
Parsing stops at the next characteristic declaration or service declaration.

Parameters

attributes Attribute list to parse; the extracted attributes are removed

Returns: Parsed Characteristic if a declaration was found; std::nullopt otherwise

Note: Attributes must be in proper order: Declaration, Value, Descriptors; Stops parsing when the next characteristic declaration or service declaration is found; Value/descriptor callbacks are not copied from the source attributes; The parsed attributes are moved into the resulting Characteristic; The extracted attributes are removed even if parsing fails

◆ ReadHasSecurityRequirement()

bool c7222::Characteristic::ReadHasSecurityRequirement ( ) const

inline

Check if characteristic has read permission bits set (requires authorization). Read permission bits 0 and 1 indicate security level requirements.

Returns: true if read permission bits (kReadPermissionBit0/1) are set

Here is the call graph for this function:

◆ ReadRequiresAuthentication()

bool c7222::Characteristic::ReadRequiresAuthentication ( ) const

Check whether reads require authenticated pairing (MITM).

This returns true when the configured read security level is kAuthenticationRequired or kAuthorizationRequired.

◆ ReadRequiresAuthorization()

bool c7222::Characteristic::ReadRequiresAuthorization ( ) const

Check whether reads require application-level authorization.

Authorization is the highest level and implies authentication.

◆ ReadRequiresEncryption()

bool c7222::Characteristic::ReadRequiresEncryption ( ) const

Check whether reads require at least encrypted link security.

Returns true if the read security level is kEncryptionRequired or higher.

◆ ReadRequiresSC()

bool c7222::Characteristic::ReadRequiresSC ( ) const

inline

Check if characteristic read requires Secure Connections (SC).

Returns: true if kReadPermissionSc is set

Here is the call graph for this function:

◆ RemoveEventHandler()

bool c7222::Characteristic::RemoveEventHandler ( const EventHandler & handler )

Unregister an event handler from this characteristic.

Parameters

handler Reference to the EventHandlers structure to unregister

Returns: true if the handler was found and removed, false otherwise

Note: Handlers are compared by pointer address. If multiple identical handlers were added, only the first is removed.; Removing a handler that was not registered has no effect.; Do not remove handlers while iterating through the handler list (e.g. during event dispatch). It is NOT safe to remove handlers from within event callbacks.; The handler instance is not deleted by this method. Therefore, the caller must delete the object if it was dynamically allocated.

◆ RequiresAuthentication()

bool c7222::Characteristic::RequiresAuthentication ( ) const

Check whether any access requires authentication.

Returns true if either read or write requires authentication.

◆ RequiresAuthorization()

bool c7222::Characteristic::RequiresAuthorization ( ) const

Check whether any access requires authorization.

Returns true if either read or write requires authorization.

◆ RequiresEncryption()

bool c7222::Characteristic::RequiresEncryption ( ) const

Check whether any access requires at least encrypted link security.

◆ SetCCCDValue()

Attribute & c7222::Characteristic::SetCCCDValue ( CCCDProperties config )

Set CCCD configuration value. Enables or configures notifications and/or indications. Automatically creates CCCD descriptor if not present.

Parameters

config CCCD configuration flags

Returns: Reference to the CCCD Attribute

◆ SetConnectionHandle()

void c7222::Characteristic::SetConnectionHandle ( uint16_t connection_handle )

inline

Set the connection handle for this characteristic.

The connection handle is set when a device connects and the characteristic's security requirements are satisfied. Used by UpdateValue to send notifications/indications.

Parameters

connection_handle The connection handle (0 is invalid/disconnected)

◆ SetEncryptionKeySize()

void c7222::Characteristic::SetEncryptionKeySize ( uint8_t key_size )

Set minimum encryption key size requirement.

Configures the minimum encryption key size (in bytes) that clients must use. Valid range is 7-16 bytes per Bluetooth specification. Sets bits 12-15 of the attribute properties (ATT_PROPERTY_ENCRYPTION_KEY_SIZE_MASK).

Parameters

key_size Minimum key size in bytes (7-16), or 0 for no requirement

Note: Most implementations use 16 bytes (128-bit) for maximum security

◆ SetExtendedPropertiesValue()

Attribute & c7222::Characteristic::SetExtendedPropertiesValue ( ExtendedProperties config )

Set Extended Properties configuration value. Configures reliable write and writable auxiliaries. Automatically creates Extended Properties descriptor if not present.

Parameters

config Extended properties flags

Returns: Reference to the Extended Properties Attribute

◆ SetReadRequiresSecureConnections()

void c7222::Characteristic::SetReadRequiresSecureConnections ( bool required )

Set Secure Connections requirement for reads.

When enabled, reads require LE Secure Connections pairing (Bluetooth 4.2+). This provides enhanced security with ECDH key agreement. Sets ATT_PROPERTY_READ_PERMISSION_SC flag.

Parameters

required true to require Secure Connections, false to allow legacy pairing

◆ SetReadSecurityLevel()

void c7222::Characteristic::SetReadSecurityLevel ( SecurityLevel level )

Set read security level requirement for this characteristic.

Configures the security level that clients must meet to read this characteristic. This sets the appropriate ATT_PROPERTY_READ_PERMISSION_BIT_0 and BIT_1 flags on the value attribute.

Parameters

level Security level (None, Encryption, Authentication, or Authorization)

// Require authenticated pairing for reads

characteristic.SetReadSecurityLevel(Characteristic::SecurityLevel::kAuthenticationRequired);

c7222::Characteristic::SecurityLevel::kAuthenticationRequired

@ kAuthenticationRequired

Authenticated pairing with encryption required. Client must pair using authenticated method with MITM...

◆ SetSCCDValue()

Attribute & c7222::Characteristic::SetSCCDValue ( SCCDProperties config )

Set SCCD configuration value. Enables or disables broadcasts. Automatically creates SCCD descriptor if not present.

Parameters

config SCCD configuration flags

Returns: Reference to the SCCD Attribute

◆ SetUserDescription()

Attribute & c7222::Characteristic::SetUserDescription ( const std::string & description )

Set the Characteristic User Description. Creates or updates the user-readable description of this characteristic.

Parameters

description Human-readable description string

Returns: Reference to the User Description Attribute for further configuration

Here is the caller graph for this function:

◆ SetUserDescriptionText()

const std::string * c7222::Characteristic::SetUserDescriptionText ( const std::string & description )

Update the user description text if a User Description descriptor exists.

Parameters

description Human-readable description string

Returns: Pointer to the internal description string if the descriptor exists; nullptr otherwise

This does not create the descriptor. It is intended for cases where the 0x2901 descriptor already exists (e.g., parsed from the ATT DB) and the application wants to update the text at runtime. The descriptor is forced read-only and served via the internal read handler.

◆ SetValue() [1/4]

bool c7222::Characteristic::SetValue ( const std::vector< uint8_t > & data )

Set the characteristic value from an lvalue vector (copy semantics). Only allowed for dynamic characteristics.

Parameters

data	Const reference to vector (copied into storage)

Returns: true if value was set, false if rejected (e.g., static characteristic)

◆ SetValue() [2/4]

template<typename T >

bool c7222::Characteristic::SetValue ( const T & value )

inline

Set the characteristic value from a typed value (generic template). Converts any trivial type to bytes and stores as the value. Only allowed for dynamic characteristics.

Template Parameters

T	Must be a trivial type (primitive types, arrays, small structs)

Parameters

value The value to store

Returns: true if value was set, false if rejected (e.g., static characteristic)

Note: Uses binary representation; for endian-sensitive types, ensure consistency

Example: SetValue<uint16_t>(0x1234) stores as bytes {0x34, 0x12} (little-endian).

Here is the call graph for this function:

◆ SetValue() [3/4]

bool c7222::Characteristic::SetValue	(	const uint8_t *	data,
		size_t	size
	)

Set the characteristic value from raw bytes (pointer + size). Only allowed for dynamic characteristics.

Parameters

data	Pointer to value data (copied into storage)
size	Size of the data in bytes

Returns: true if value was set, false if rejected (e.g., static characteristic)

Here is the caller graph for this function:

◆ SetValue() [4/4]

bool c7222::Characteristic::SetValue ( std::vector< uint8_t > && data )

Set the characteristic value from an rvalue vector (move semantics). Only allowed for dynamic characteristics.

Parameters

data	Rvalue reference to vector (moved into storage)

Returns: true if value was set, false if rejected (e.g., static characteristic)

◆ SetWriteRequiresSecureConnections()

void c7222::Characteristic::SetWriteRequiresSecureConnections ( bool required )

Set Secure Connections requirement for writes.

When enabled, writes require LE Secure Connections pairing (Bluetooth 4.2+). This provides enhanced security with ECDH key agreement. Sets ATT_PROPERTY_WRITE_PERMISSION_SC flag.

Parameters

required true to require Secure Connections, false to allow legacy pairing

◆ SetWriteSecurityLevel()

void c7222::Characteristic::SetWriteSecurityLevel ( SecurityLevel level )

Set write security level requirement for this characteristic.

Configures the security level that clients must meet to write this characteristic. This sets the appropriate ATT_PROPERTY_WRITE_PERMISSION_BIT_0 and BIT_1 flags on the value attribute.

Parameters

level Security level (None, Encryption, Authentication, or Authorization)

// Require encryption for writes

characteristic.SetWriteSecurityLevel(Characteristic::SecurityLevel::kEncryptionRequired);

c7222::Characteristic::SecurityLevel::kEncryptionRequired

@ kEncryptionRequired

Unauthenticated pairing with encryption required. Client must pair and establish encrypted link (Just...

◆ UpdateValue()

virtual BleError c7222::Characteristic::UpdateValue ( )

protectedvirtual

Update the characteristic value and send notification/indication if enabled.

This is called internally by SetValue functions to handle platform-specific transmission logic. The function checks CCCD configuration and sends the appropriate update to the connected client based on enabled notifications/indications.

Logic:

If neither notifications nor indications are enabled: no transmission
If only notifications are enabled: sends notification
If only indications are enabled: sends indication
If both are enabled: sends indication and ignores notification

Returns: BleError indicating success or failure

Note: Only executes if connection_handle_ is valid (non-zero); Platform-specific implementation handles actual transmission; Internal use only (called from SetValue() and BLE stack flow control).

◆ Uses128BitUuid()

bool c7222::Characteristic::Uses128BitUuid ( ) const

inline

Check if characteristic has 128-bit UUID.

Returns: true if kUuid128 is set in value attribute

Here is the call graph for this function:

◆ WriteHasSecurityRequirement()

bool c7222::Characteristic::WriteHasSecurityRequirement ( ) const

inline

Check if characteristic has write permission bits set (requires authorization). Write permission bits 0 and 1 indicate security level requirements.

Returns: true if write permission bits (kWritePermissionBit0/1) are set

Here is the call graph for this function:

◆ WriteRequiresAuthentication()

bool c7222::Characteristic::WriteRequiresAuthentication ( ) const

Check whether writes require authenticated pairing (MITM).

This returns true when the configured write security level is kAuthenticationRequired or kAuthorizationRequired.

◆ WriteRequiresAuthorization()

bool c7222::Characteristic::WriteRequiresAuthorization ( ) const

Check whether writes require application-level authorization.

Authorization is the highest level and implies authentication.

◆ WriteRequiresEncryption()

bool c7222::Characteristic::WriteRequiresEncryption ( ) const

Check whether writes require at least encrypted link security.

Returns true if the write security level is kEncryptionRequired or higher.

◆ WriteRequiresSC()

bool c7222::Characteristic::WriteRequiresSC ( ) const

inline

Check if characteristic write requires Secure Connections (SC).

Returns: true if kWritePermissionSc is set

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Characteristic &	characteristic
	)

friend

Stream insertion operator for Characteristic. Outputs the characteristic UUID, properties, security requirements, and descriptors.

Parameters

os	Output stream
characteristic	The characteristic to output

Returns: Reference to the output stream

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

libs/elec_c7222/ble/gatt/include/characteristic.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Friends

Construction and Parsing

Detailed Description

Construction / Parsing

Event Handling Model

User Description Descriptor (0x2901)

Debug Logging

RPi Pico (BTstack) Integration

Descriptor Model (what, when, and storage)

Value Attribute Updates (read/write flow)

Security Queries (Planning Before Connections)

Descriptor Security Enforcement

Internal/Reserved APIs (do not call from application code)

Member Enumeration Documentation

◆ CCCDProperties

◆ EventId

◆ ExtendedProperties

◆ Properties

◆ SCCDProperties

◆ SecurityLevel

Constructor & Destructor Documentation

◆ Characteristic() [1/4]

◆ Characteristic() [2/4]

◆ Characteristic() [3/4]

◆ Characteristic() [4/4]

◆ ~Characteristic()

Member Function Documentation

◆ AddDescriptor()

◆ AddEventHandler()

◆ CanRead()

◆ CanSignedWrite()

◆ CanWrite()

◆ CanWriteWithoutResponse()

◆ ClearEventHandlers()

◆ DispatchBleHciPacket()

◆ DispatchEvent()

◆ EnableCCCD()

◆ EnableExtendedProperties()

◆ EnableSCCD()

◆ GetCCCD() [1/2]

◆ GetCCCD() [2/2]

◆ GetConnectionHandle()

◆ GetDeclarationAttribute() [1/2]

◆ GetDeclarationAttribute() [2/2]

◆ GetDeclarationHandle()

◆ GetDescriptor() [1/2]

◆ GetDescriptor() [2/2]

◆ GetDescriptorCount()

◆ GetEncryptionKeySize()

◆ GetEventHandlers()

◆ GetExtendedProperties() [1/2]

◆ GetExtendedProperties() [2/2]

◆ GetProperties()

◆ GetReadSecurityLevel()

◆ GetSCCD() [1/2]

◆ GetSCCD() [2/2]

◆ GetUserDescription() [1/2]

◆ GetUserDescription() [2/2]

◆ GetUserDescriptionText()

◆ GetUuid()

◆ GetValueAsVector()

◆ GetValueAttribute() [1/2]

◆ GetValueAttribute() [2/2]

◆ GetValueData()

◆ GetValueHandle()

◆ GetValueSize()

◆ GetWriteSecurityLevel()

◆ HandleAttributeRead()

◆ HandleAttributeWrite()

◆ HasBroadcast()

◆ HasCCCD()

◆ HasExtendedProperties()

◆ HasExtendedPropertiesCapability()

◆ HasHandle()

◆ HasIndications()

◆ HasNotifications()