|
ELEC-C7222
Libraries for ELEC C7222 Course Work
|
Represents a GATT Service with its characteristics and included services. More...
#include <service.hpp>


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 Uuid & | GetUuid () 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. | |
| Characteristic & | GetCharacteristic (size_t index) |
| Get a characteristic by index. | |
| const Characteristic & | GetCharacteristic (size_t index) const |
| Get a characteristic by index (const version). | |
| Characteristic * | FindCharacteristicByUuid (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 Characteristic * | FindCharacteristicByUuid (const Uuid &uuid) const |
| Get a characteristic by UUID (const version). | |
| Characteristic * | FindCharacteristicByHandle (uint16_t handle) |
| Get a characteristic that containes the specfied attribute handle. | |
| const Characteristic * | FindCharacteristicByHandle (uint16_t handle) const |
| Get a characteristic that containes the specfied attribute handle (const version). | |
| Attribute * | FindServiceAttributeByHandle (uint16_t handle) |
| Find a service declaration or included service declaration by handle. | |
| const Attribute * | FindServiceAttributeByHandle (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. | |
| Service & | GetIncludedService (size_t index) |
| Get an included service by index. | |
| const Service & | GetIncludedService (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 | |
| Characteristic & | AddCharacteristic (Characteristic &&characteristic) |
| Add a characteristic to this service. | |
| Characteristic & | CreateCharacteristic (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 | |
| 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 |
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. | |
| Service & | operator= (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< Service > | ParseFromAttributes (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 | |
Represents a GATT Service with its characteristics and included services.
A GATT Service consists of:
The Service Declaration contains:
Services are identified by their UUID and organize related characteristics into logical groups. Clients discover services first, then characteristics.
There are two common ways to create a Service:
AddCharacteristic() or CreateCharacteristic().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 services are represented by:
Service objects (included_services_) for higher-level access.included_service_declarations_) for the ATT database representation.When adding an included service with AddIncludedService(), this class creates a declaration attribute that contains:
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.
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.
Services expose security query helpers that aggregate characteristic requirements across the service:
HasCharacteristicsRequiringAuthentication()HasCharacteristicsRequiringEncryption()HasCharacteristicsRequiringAuthorization()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.
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:
Attribute/Service.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:
ParseFromAttributes() (ATT DB parsing)FindServiceAttributeByHandle() (server routing helpers)
|
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. |
|
explicit |
Construct a new Service. Creates the service with the given UUID and type.
| uuid | The UUID identifying this service |
| service_type | Type of service (Primary or Secondary) |
| declaration_handle | Optional handle for the Declaration attribute (used in DB) |
|
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.
|
defaultnoexcept |
Move constructor. Transfers ownership of all internal characteristics and attributes.
|
delete |
Deleted default constructor. A service must have a UUID and type specified.
|
overridedefault |
Destructor. Cleans up all managed characteristics and included services.
| 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.
| characteristic | The characteristic to add (will be moved) |
| 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.
| included_service | Reference to the service to include |
| declaration_handle | Optional handle for the Included Service Declaration |
|
inline |
Get iterator to first characteristic.
|
inline |
Get const iterator to first characteristic.
|
inline |
Get const iterator to first characteristic.
|
inline |
Get const iterator to end of characteristics.
| void c7222::Service::ClearCharacteristics | ( | ) |
Remove all characteristics from this service.
| void c7222::Service::ClearIncludedServices | ( | ) |
Remove all included services.
| 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.
| uuid | UUID for the characteristic |
| properties | Characteristic properties bitfield |
| declaration_handle | Handle of the Declaration attribute |
| value_handle | Handle of the Value attribute |
|
inline |
Get iterator to end of characteristics.
|
inline |
Get const iterator to end of characteristics.
| Characteristic * c7222::Service::FindCharacteristicByHandle | ( | uint16_t | handle | ) |
Get a characteristic that containes the specfied attribute handle.
| handle | Attribute handle to be searched for |
| const Characteristic * c7222::Service::FindCharacteristicByHandle | ( | uint16_t | handle | ) | const |
Get a characteristic that containes the specfied attribute handle (const version).
| handle | Attribute handle to be searched for |
| Characteristic * c7222::Service::FindCharacteristicByUuid | ( | const Uuid & | uuid | ) |
Get a characteristic by UUID.
| uuid | UUID to search for |
| const Characteristic * c7222::Service::FindCharacteristicByUuid | ( | const Uuid & | uuid | ) | const |
Get a characteristic by UUID (const version).
| uuid | UUID to search for |
| std::list< Characteristic * > c7222::Service::FindCharacteristicsByProperties | ( | Characteristic::Properties | properties | ) | const |
Find characteristics that include all specified properties.
| properties | Bitfield of properties to match (logical AND filter) |

| 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.
|
inline |
Find characteristics that can notify or indicate.
Matches characteristics with Notify and/or Indicate properties set.

|
inline |
Find characteristics that are readable.
Matches characteristics advertising the Read property.

|
inline |
Find characteristics that are writable.
Matches characteristics advertising the Write property.

| Attribute * c7222::Service::FindServiceAttributeByHandle | ( | uint16_t | handle | ) |
Find a service declaration or included service declaration by handle.
| handle | Attribute handle to search for |
| const Attribute * c7222::Service::FindServiceAttributeByHandle | ( | uint16_t | handle | ) | const |
Find a service declaration or included service declaration by handle (const version).
| handle | Attribute handle to search for |
| Characteristic & c7222::Service::GetCharacteristic | ( | size_t | index | ) |
Get a characteristic by index.
| index | Index of the characteristic (0 to GetCharacteristicCount()-1) |
| const Characteristic & c7222::Service::GetCharacteristic | ( | size_t | index | ) | const |
Get a characteristic by index (const version).
| index | Index of the characteristic (0 to GetCharacteristicCount()-1) |
|
inline |
Get the number of characteristics in this service.
|
inline |
Get the Characteristics object.
|
inline |
Get the list of characteristics in this service.
|
inline |
Get the current connection handle for this service.
|
inline |
Get the handle of the Declaration attribute.

| Service & c7222::Service::GetIncludedService | ( | size_t | index | ) |
Get an included service by index.
| index | Index of the included service |
| const Service & c7222::Service::GetIncludedService | ( | size_t | index | ) | const |
Get an included service by index (const version).
| index | Index of the included service |
|
inline |
Get the number of included services.
|
inline |
Get the number of included service declaration attributes.
|
inline |
Get the service type (Primary or Secondary).
|
inline |
Get the UUID of this service.
| 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.
| bool c7222::Service::HasCharacteristicsRequiringAuthorization | ( | ) | const |
Check whether any characteristic requires authorization.
Authorization implies authentication and typically requires an application-level decision.
| bool c7222::Service::HasCharacteristicsRequiringEncryption | ( | ) | const |
Check whether any characteristic requires encrypted link security.
| bool c7222::Service::IsValid | ( | ) | const |
Check if this service is valid.
Move assignment operator. Transfers ownership of all internal characteristics and 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.
| attributes | Attribute list to consume (modified in place) |
| bool c7222::Service::RemoveCharacteristic | ( | size_t | index | ) |
Remove a characteristic by index.
| index | Index of the characteristic to remove |
| bool c7222::Service::RemoveIncludedService | ( | size_t | index | ) |
Remove an included service by index.
| index | Index of the included service to remove |
| void c7222::Service::SetConnectionHandle | ( | uint16_t | connection_handle | ) |
Set the connection handle for all characteristics in this service.
| connection_handle | The connection handle (0 is invalid/disconnected) |
|
inline |
Check if this service uses 128-bit UUID.

|
friend |