ELEC-C7222
Libraries for ELEC C7222 Course Work
Loading...
Searching...
No Matches
c7222::Service Class Reference

Represents a GATT Service with its characteristics and included services. More...

#include <service.hpp>

Inheritance diagram for c7222::Service:
Inheritance graph
Collaboration diagram for c7222::Service:
Collaboration graph

Public Types

Types and Configuration
enum class  ServiceType : uint8_t { kPrimary = 0 , kSecondary = 1 }
 Service type indicators. More...
 

Public Member Functions

Accessors and Lookup
const UuidGetUuid () const
 Get the UUID of this service.
 
ServiceType GetServiceType () const
 Get the service type (Primary or Secondary).
 
uint16_t GetDeclarationHandle () const
 Get the handle of the Declaration attribute.
 
size_t GetCharacteristicCount () const
 Get the number of characteristics in this service.
 
const std::list< Characteristic > & GetCharacteristics () const
 Get the list of characteristics in this service.
 
std::list< Characteristic > & GetCharacteristics ()
 Get the Characteristics object.
 
CharacteristicGetCharacteristic (size_t index)
 Get a characteristic by index.
 
const CharacteristicGetCharacteristic (size_t index) const
 Get a characteristic by index (const version).
 
CharacteristicFindCharacteristicByUuid (const Uuid &uuid)
 Get a characteristic by UUID.
 
std::list< Characteristic * > FindCharacteristicsByProperties (Characteristic::Properties properties) const
 Find characteristics that include all specified properties.
 
std::list< Characteristic * > FindCharacteristicsDynamic () const
 Find characteristics that use dynamically assigned value handles.
 
Security Queries
bool HasCharacteristicsRequiringAuthentication () const
 Check whether any characteristic requires authentication.
 
bool HasCharacteristicsRequiringEncryption () const
 Check whether any characteristic requires encrypted link security.
 
bool HasCharacteristicsRequiringAuthorization () const
 Check whether any characteristic requires authorization.
 
Convenience Queries
std::list< Characteristic * > FindCharacteristicsWritable () const
 Find characteristics that are writable.
 
std::list< Characteristic * > FindCharacteristicsReadable () const
 Find characteristics that are readable.
 
std::list< Characteristic * > FindCharacteristicsNotifiableOrIndicatable () const
 Find characteristics that can notify or indicate.
 
const CharacteristicFindCharacteristicByUuid (const Uuid &uuid) const
 Get a characteristic by UUID (const version).
 
CharacteristicFindCharacteristicByHandle (uint16_t handle)
 Get a characteristic that containes the specfied attribute handle.
 
const CharacteristicFindCharacteristicByHandle (uint16_t handle) const
 Get a characteristic that containes the specfied attribute handle (const version).
 
AttributeFindServiceAttributeByHandle (uint16_t handle)
 Find a service declaration or included service declaration by handle.
 
const AttributeFindServiceAttributeByHandle (uint16_t handle) const
 Find a service declaration or included service declaration by handle (const version).
 
Additional Lookup and State
size_t GetIncludedServiceCount () const
 Get the number of included services.
 
ServiceGetIncludedService (size_t index)
 Get an included service by index.
 
const ServiceGetIncludedService (size_t index) const
 Get an included service by index (const version).
 
size_t GetIncludedServiceDeclarationCount () const
 Get the number of included service declaration attributes.
 
bool IsValid () const
 Check if this service is valid.
 
bool Uses128BitUuid () const
 Check if this service uses 128-bit UUID.
 
void SetConnectionHandle (uint16_t connection_handle)
 Set the connection handle for all characteristics in this service.
 
uint16_t GetConnectionHandle () const
 Get the current connection handle for this service.
 
Characteristic Management
CharacteristicAddCharacteristic (Characteristic &&characteristic)
 Add a characteristic to this service.
 
CharacteristicCreateCharacteristic (const Uuid &uuid, uint8_t properties, uint16_t declaration_handle, uint16_t value_handle)
 Create and add a new characteristic to this service.
 
bool RemoveCharacteristic (size_t index)
 Remove a characteristic by index.
 
void ClearCharacteristics ()
 Remove all characteristics from this service.
 
Included Service Management
void AddIncludedService (const Service &included_service, uint16_t declaration_handle=0)
 Add an included service reference.
 
bool RemoveIncludedService (size_t index)
 Remove an included service by index.
 
void ClearIncludedServices ()
 Remove all included services.
 
Iteration
auto begin ()
 Get iterator to first characteristic.
 
auto end ()
 Get iterator to end of characteristics.
 
auto begin () const
 Get const iterator to first characteristic.
 
auto end () const
 Get const iterator to end of characteristics.
 
auto cbegin () const
 Get const iterator to first characteristic.
 
auto cend () const
 Get const iterator to end of characteristics.
 
- Public Member Functions inherited from c7222::MovableOnly
virtual ~MovableOnly ()=default
 
 MovableOnly (MovableOnly &&)=default
 
MovableOnlyoperator= (MovableOnly &&)=default
 
 MovableOnly ()=default
 
- Public Member Functions inherited from c7222::NonCopyable
 NonCopyable (const NonCopyable &)=delete
 
NonCopyableoperator= (const NonCopyable &)=delete
 
 NonCopyable (NonCopyable &&)=default
 
NonCopyableoperator= (NonCopyable &&)=default
 

Friends

Stream Output
std::ostream & operator<< (std::ostream &os, const Service &service)
 Stream insertion operator for service information.
 

Construction and Parsing

 Service (const Uuid &uuid, ServiceType service_type=ServiceType::kPrimary, uint16_t declaration_handle=0)
 Construct a new Service. Creates the service with the given UUID and type.
 
 Service (Attribute &&declaration_attr, std::vector< Attribute > &&included_service_declarations, std::list< Characteristic > &&characteristics)
 Construct a Service by moving parsed attributes.
 
 Service (Service &&other) noexcept=default
 Move constructor. Transfers ownership of all internal characteristics and attributes.
 
Serviceoperator= (Service &&other) noexcept=default
 Move assignment operator. Transfers ownership of all internal characteristics and attributes.
 
 Service ()=delete
 Deleted default constructor. A service must have a UUID and type specified.
 
 ~Service () override=default
 Destructor. Cleans up all managed characteristics and included services.
 
static std::list< ServiceParseFromAttributes (std::list< Attribute > &attributes)
 Parse Services from an ordered attribute list.
 

Additional Inherited Members

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

Detailed Description

Represents a GATT Service with its characteristics and included services.

A GATT Service consists of:

  1. Service Declaration attribute (mandatory) - defines the service UUID
  2. Characteristics (mandatory) - the main data containers within the service
  3. Included Services (optional) - references to other services

The Service Declaration contains:

  • 2 or 16 bytes: Service UUID (16-bit or 128-bit)

Services are identified by their UUID and organize related characteristics into logical groups. Clients discover services first, then characteristics.


Construction / Parsing

There are two common ways to create a Service:

  1. Manual construction: Use the constructor, then add characteristics via AddCharacteristic() or CreateCharacteristic().
  2. Parse from attributes: Use ParseFromAttributes() to extract services from an ordered attribute list. The extracted attributes are removed from the list and moved into the resulting Service/Characteristic instances. Callbacks are not copied; register callbacks after parsing.

Included Service Model

Included services are represented by:

  • A list of Service objects (included_services_) for higher-level access.
  • A list of Included Service Declaration attributes (included_service_declarations_) for the ATT database representation.

When adding an included service with AddIncludedService(), this class creates a declaration attribute that contains:

  • Start handle (16-bit LE)
  • End handle (16-bit LE)
  • Included service UUID (2 or 16 bytes)

The current implementation estimates the end handle based on the included service's declaration handle and characteristic count. If you require exact handle ranges, ensure handles are assigned consistently in the ATT DB.


Connection Handle Propagation

SetConnectionHandle() stores the connection handle on the service and forwards it to all characteristics and included services. This enables notification/indication delivery via the characteristic update APIs.


Security Queries (Planning Before Connections)

Services expose security query helpers that aggregate characteristic requirements across the service:

These are intended to help higher-level components (e.g., the attribute server or BLE facade) decide whether a SecurityManager must be enabled and how it should be configured before connections are established.


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 and then calls Service::ParseFromAttributes() to build services in discovery order.

Important implications:

  • Parsed static attributes keep pointers into the DB blob; the DB memory must remain valid for the lifetime of the Attribute/Service.
  • Parsing moves the attribute objects; callbacks are not copied. Install callbacks after parsing as needed.

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:


Typical Usage

// Manual construction (server-side)
c7222::Service svc(c7222::Uuid(0x180F)); // Battery Service
auto& level = svc.CreateCharacteristic(c7222::Uuid(0x2A19),
0,
0);
level.SetValue(&initial_level, sizeof(initial_level));
// Parsing from a compiled ATT DB (Pico W)
server->Init(att_db);
c7222::Service* parsed = server->FindServiceByUuid(c7222::Uuid(0x180F));
static AttributeServer * GetInstance()
Get the singleton instance.
Definition attribute_server.hpp:160
@ kRead
Characteristic value can be read.
Represents a GATT Service with its characteristics and included services.
Definition service.hpp:119
UUID storage for 16-bit and 128-bit UUIDs.
Definition uuid.hpp:53
Note
Services can be either Primary or Secondary(defined by UUID type).
A service must contain at least one characteristic to be considered valid.

Member Enumeration Documentation

◆ ServiceType

enum class c7222::Service::ServiceType : uint8_t
strong

Service type indicators.

Services can be Primary (standalone) or Secondary (included in other services). The type is determined by the service declaration UUID type in the ATT DB.

Enumerator
kPrimary 

Primary Service - top-level service discoverable by clients.

kSecondary 

Secondary Service - included in other services, not directly discoverable.

Constructor & Destructor Documentation

◆ Service() [1/4]

c7222::Service::Service ( const Uuid uuid,
ServiceType  service_type = ServiceType::kPrimary,
uint16_t  declaration_handle = 0 
)
explicit

Construct a new Service. Creates the service with the given UUID and type.

Parameters
uuidThe UUID identifying this service
service_typeType of service (Primary or Secondary)
declaration_handleOptional handle for the Declaration attribute (used in DB)

◆ Service() [2/4]

c7222::Service::Service ( Attribute &&  declaration_attr,
std::vector< Attribute > &&  included_service_declarations,
std::list< Characteristic > &&  characteristics 
)
explicit

Construct a Service by moving parsed attributes.

This constructor takes ownership of the ATT DB attributes and avoids rebuilding them. The declaration attribute must be a Primary or Secondary Service Declaration with a 16-bit or 128-bit service UUID value payload. Handles are preserved from the moved attributes.

Parameters
declaration_attrService Declaration attribute (moved)
included_service_declarationsIncluded Service Declaration attributes (moved)
characteristicsCharacteristics parsed from the same attribute block (moved)

◆ Service() [3/4]

c7222::Service::Service ( Service &&  other)
defaultnoexcept

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

◆ Service() [4/4]

c7222::Service::Service ( )
delete

Deleted default constructor. A service must have a UUID and type specified.

◆ ~Service()

c7222::Service::~Service ( )
overridedefault

Destructor. Cleans up all managed characteristics and included services.

Member Function Documentation

◆ AddCharacteristic()

Characteristic & c7222::Service::AddCharacteristic ( Characteristic &&  characteristic)

Add a characteristic to this service.

Adds an existing characteristic to the service. The characteristic is moved into the service, transferring ownership.

Parameters
characteristicThe characteristic to add (will be moved)
Returns
Reference to the added characteristic

◆ AddIncludedService()

void c7222::Service::AddIncludedService ( const Service included_service,
uint16_t  declaration_handle = 0 
)

Add an included service reference.

Adds a reference to another service that is included in this service. This creates an Included Service Declaration attribute in the ATT DB. The declaration stores the included service start/end handles and UUID. The end handle is estimated from the included service metadata unless handles are explicitly assigned in the DB.

Parameters
included_serviceReference to the service to include
declaration_handleOptional handle for the Included Service Declaration

◆ begin() [1/2]

auto c7222::Service::begin ( )
inline

Get iterator to first characteristic.

Returns
Iterator to begin of characteristics list

◆ begin() [2/2]

auto c7222::Service::begin ( ) const
inline

Get const iterator to first characteristic.

Returns
Const iterator to begin of characteristics list

◆ cbegin()

auto c7222::Service::cbegin ( ) const
inline

Get const iterator to first characteristic.

Returns
Const iterator to begin of characteristics list

◆ cend()

auto c7222::Service::cend ( ) const
inline

Get const iterator to end of characteristics.

Returns
Const iterator to end of characteristics list

◆ ClearCharacteristics()

void c7222::Service::ClearCharacteristics ( )

Remove all characteristics from this service.

◆ ClearIncludedServices()

void c7222::Service::ClearIncludedServices ( )

Remove all included services.

◆ CreateCharacteristic()

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

Create and add a new characteristic to this service.

Creates a new characteristic with the given parameters and adds it to the service. The caller is responsible for assigning handles if the ATT DB requires fixed handle values; otherwise handles may remain 0 until assigned by the stack.

Parameters
uuidUUID for the characteristic
propertiesCharacteristic properties bitfield
declaration_handleHandle of the Declaration attribute
value_handleHandle of the Value attribute
Returns
Reference to the newly added characteristic

◆ end() [1/2]

auto c7222::Service::end ( )
inline

Get iterator to end of characteristics.

Returns
Iterator to end of characteristics list

◆ end() [2/2]

auto c7222::Service::end ( ) const
inline

Get const iterator to end of characteristics.

Returns
Const iterator to end of characteristics list

◆ FindCharacteristicByHandle() [1/2]

Characteristic * c7222::Service::FindCharacteristicByHandle ( uint16_t  handle)

Get a characteristic that containes the specfied attribute handle.

Parameters
handleAttribute handle to be searched for
Returns
Pointer to the characteristic if found, nullptr otherwise

◆ FindCharacteristicByHandle() [2/2]

const Characteristic * c7222::Service::FindCharacteristicByHandle ( uint16_t  handle) const

Get a characteristic that containes the specfied attribute handle (const version).

Parameters
handleAttribute handle to be searched for
Returns
Const pointer to the characteristic if found, nullptr otherwise

◆ FindCharacteristicByUuid() [1/2]

Characteristic * c7222::Service::FindCharacteristicByUuid ( const Uuid uuid)

Get a characteristic by UUID.

Parameters
uuidUUID to search for
Returns
Pointer to the characteristic if found, nullptr otherwise

◆ FindCharacteristicByUuid() [2/2]

const Characteristic * c7222::Service::FindCharacteristicByUuid ( const Uuid uuid) const

Get a characteristic by UUID (const version).

Parameters
uuidUUID to search for
Returns
Const pointer to the characteristic if found, nullptr otherwise

◆ FindCharacteristicsByProperties()

std::list< Characteristic * > c7222::Service::FindCharacteristicsByProperties ( Characteristic::Properties  properties) const

Find characteristics that include all specified properties.

Parameters
propertiesBitfield of properties to match (logical AND filter)
Returns
List of matching characteristic pointers (may be empty)
Here is the caller graph for this function:

◆ FindCharacteristicsDynamic()

std::list< Characteristic * > c7222::Service::FindCharacteristicsDynamic ( ) const

Find characteristics that use dynamically assigned value handles.

Dynamic characteristics have a value handle of 0 until the stack assigns one.

Returns
List of characteristics with dynamic handles (may be empty)

◆ FindCharacteristicsNotifiableOrIndicatable()

std::list< Characteristic * > c7222::Service::FindCharacteristicsNotifiableOrIndicatable ( ) const
inline

Find characteristics that can notify or indicate.

Matches characteristics with Notify and/or Indicate properties set.

Returns
List of notifiable or indicatable characteristic pointers (may be empty)
Here is the call graph for this function:

◆ FindCharacteristicsReadable()

std::list< Characteristic * > c7222::Service::FindCharacteristicsReadable ( ) const
inline

Find characteristics that are readable.

Matches characteristics advertising the Read property.

Returns
List of readable characteristic pointers (may be empty)
Here is the call graph for this function:

◆ FindCharacteristicsWritable()

std::list< Characteristic * > c7222::Service::FindCharacteristicsWritable ( ) const
inline

Find characteristics that are writable.

Matches characteristics advertising the Write property.

Returns
List of writable characteristic pointers (may be empty)
Here is the call graph for this function:

◆ FindServiceAttributeByHandle() [1/2]

Attribute * c7222::Service::FindServiceAttributeByHandle ( uint16_t  handle)

Find a service declaration or included service declaration by handle.

Parameters
handleAttribute handle to search for
Returns
Pointer to the attribute if found, nullptr otherwise

◆ FindServiceAttributeByHandle() [2/2]

const Attribute * c7222::Service::FindServiceAttributeByHandle ( uint16_t  handle) const

Find a service declaration or included service declaration by handle (const version).

Parameters
handleAttribute handle to search for
Returns
Const pointer to the attribute if found, nullptr otherwise

◆ GetCharacteristic() [1/2]

Characteristic & c7222::Service::GetCharacteristic ( size_t  index)

Get a characteristic by index.

Parameters
indexIndex of the characteristic (0 to GetCharacteristicCount()-1)
Returns
Reference to the characteristic, throws std::out_of_range if invalid

◆ GetCharacteristic() [2/2]

const Characteristic & c7222::Service::GetCharacteristic ( size_t  index) const

Get a characteristic by index (const version).

Parameters
indexIndex of the characteristic (0 to GetCharacteristicCount()-1)
Returns
Const reference to the characteristic, throws std::out_of_range if invalid

◆ GetCharacteristicCount()

size_t c7222::Service::GetCharacteristicCount ( ) const
inline

Get the number of characteristics in this service.

Returns
Count of characteristics

◆ GetCharacteristics() [1/2]

std::list< Characteristic > & c7222::Service::GetCharacteristics ( )
inline

Get the Characteristics object.

Returns
std::list<Characteristic>&

◆ GetCharacteristics() [2/2]

const std::list< Characteristic > & c7222::Service::GetCharacteristics ( ) const
inline

Get the list of characteristics in this service.

Returns
Reference to the characteristic list

◆ GetConnectionHandle()

uint16_t c7222::Service::GetConnectionHandle ( ) const
inline

Get the current connection handle for this service.

Returns
The connection handle, or 0 if disconnected/invalid

◆ GetDeclarationHandle()

uint16_t c7222::Service::GetDeclarationHandle ( ) const
inline

Get the handle of the Declaration attribute.

Returns
Declaration attribute handle
Here is the call graph for this function:

◆ GetIncludedService() [1/2]

Service & c7222::Service::GetIncludedService ( size_t  index)

Get an included service by index.

Parameters
indexIndex of the included service
Returns
Reference to the included service, throws std::out_of_range if invalid

◆ GetIncludedService() [2/2]

const Service & c7222::Service::GetIncludedService ( size_t  index) const

Get an included service by index (const version).

Parameters
indexIndex of the included service
Returns
Const reference to the included service, throws std::out_of_range if invalid

◆ GetIncludedServiceCount()

size_t c7222::Service::GetIncludedServiceCount ( ) const
inline

Get the number of included services.

Returns
Count of included services

◆ GetIncludedServiceDeclarationCount()

size_t c7222::Service::GetIncludedServiceDeclarationCount ( ) const
inline

Get the number of included service declaration attributes.

Returns
Count of included service declarations

◆ GetServiceType()

ServiceType c7222::Service::GetServiceType ( ) const
inline

Get the service type (Primary or Secondary).

Returns
ServiceType of this service

◆ GetUuid()

const Uuid & c7222::Service::GetUuid ( ) const
inline

Get the UUID of this service.

Returns
Reference to the service's UUID

◆ HasCharacteristicsRequiringAuthentication()

bool c7222::Service::HasCharacteristicsRequiringAuthentication ( ) const

Check whether any characteristic requires authentication.

This is useful during service construction/registration to determine whether the service contains security-sensitive characteristics.

◆ HasCharacteristicsRequiringAuthorization()

bool c7222::Service::HasCharacteristicsRequiringAuthorization ( ) const

Check whether any characteristic requires authorization.

Authorization implies authentication and typically requires an application-level decision.

◆ HasCharacteristicsRequiringEncryption()

bool c7222::Service::HasCharacteristicsRequiringEncryption ( ) const

Check whether any characteristic requires encrypted link security.

◆ IsValid()

bool c7222::Service::IsValid ( ) const

Check if this service is valid.

Returns
true if UUID is valid, handles are non-zero, and has at least one characteristic

◆ operator=()

Service & c7222::Service::operator= ( Service &&  other)
defaultnoexcept

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

◆ ParseFromAttributes()

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

Parse Services from an ordered attribute list.

This function scans for Service Declaration attributes, then consumes each service block until the next declaration (or end of list). It parses characteristics one-by-one using Characteristic::ParseFromAttributes.

Parameters
attributesAttribute list to consume (modified in place)
Returns
Parsed Services in discovery order
Note
Parsed attributes are moved into each Service instance
Expects a well-formed, ordered ATT DB; characteristic parsing is asserted

◆ RemoveCharacteristic()

bool c7222::Service::RemoveCharacteristic ( size_t  index)

Remove a characteristic by index.

Parameters
indexIndex of the characteristic to remove
Returns
true if removed successfully, false if index out of range

◆ RemoveIncludedService()

bool c7222::Service::RemoveIncludedService ( size_t  index)

Remove an included service by index.

Parameters
indexIndex of the included service to remove
Returns
true if removed successfully, false if index out of range

◆ SetConnectionHandle()

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

Set the connection handle for all characteristics in this service.

Parameters
connection_handleThe connection handle (0 is invalid/disconnected)

◆ Uses128BitUuid()

bool c7222::Service::Uses128BitUuid ( ) const
inline

Check if this service uses 128-bit UUID.

Returns
true if service UUID is 128-bit
Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<< ( std::ostream &  os,
const Service service 
)
friend

Stream insertion operator for service information.

Outputs service details including:

  • Service UUID
  • Service type (Primary/Secondary)
  • Declaration handle
  • Count of characteristics and included services
Parameters
osOutput stream
serviceService to output
Returns
Reference to the output stream

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