characteristic.hpp

Go to the documentation of this file.

#ifndef ELEC_C7222_BLE_GATT_CHARACTERISTIC_HPP_
#define ELEC_C7222_BLE_GATT_CHARACTERISTIC_HPP_
 
#include <iosfwd>
#include <list>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
#include "attribute.hpp"
#include "ble_error.hpp"
#include "uuid.hpp"
 
namespace c7222 {
 
class Characteristic final : public MovableOnly {
   public:
 
    enum class Properties : uint8_t {
        kNone = 0x00,
        kBroadcast = 0x01,
        kRead = 0x02,
        kWriteWithoutResponse = 0x04,
        kWrite = 0x08,
        kNotify = 0x10,
        kIndicate = 0x20,
        kAuthenticatedSignedWrites = 0x40,
        kExtendedProperties = 0x80
    };
 
    enum class CCCDProperties : uint16_t {
        kNone = 0x0000,
        kNotifications = 0x0001,
        kIndications = 0x0002
    };
 
    enum class SCCDProperties : uint16_t {
        kNone = 0x0000,
        kBroadcasts = 0x0001
    };
 
    enum class ExtendedProperties : uint16_t {
        kNone = 0x0000,
        kReliableWrite = 0x0001,
        kWritableAuxiliaries = 0x0002
    };
 
    enum class SecurityLevel : uint8_t {
        kNone = 0,
 
        kEncryptionRequired = 1,
 
        kAuthenticationRequired = 2,
 
        kAuthorizationRequired = 3
    };
 
    enum class EventId : uint8_t {
        kHandleValueIndicationComplete,
        kAttEventEnd
    };
 
    struct EventHandler {
        virtual void OnUpdatesEnabled(bool is_indication) {
            (void)is_indication;
        }
        virtual void OnUpdatesDisabled() {
        }
 
        virtual void OnIndicationComplete(uint8_t status) {
            (void)status;
        }
 
        virtual void OnBroadcastEnabled() {
        }
 
        virtual void OnBroadcastDisabled() {
        }
 
        virtual void OnRead() {
        }
 
        virtual void OnWrite(const std::vector<uint8_t>& data) {
            (void)data;
        }
        virtual void OnConfirmationReceived(bool status) {
            (void)status;
        }
    protected:
        virtual ~EventHandler() = default;
    };
 
 
    explicit Characteristic(const Uuid& uuid,
                            uint8_t properties,
                            uint16_t declaration_handle,
                            uint16_t value_handle);
 
    explicit Characteristic(Attribute&& decl_attribute,
                            Attribute&& value_attr,
                            std::list<Attribute>&& descriptor_attrs);
 
    Characteristic(Characteristic&& other) noexcept;
 
    Characteristic& operator=(Characteristic&& other) noexcept;
    Characteristic() = delete;
    ~Characteristic() override = default;
 
    static std::optional<Characteristic>
    ParseFromAttributes(std::list<Attribute>& attributes);
 
 
    [[nodiscard]] const Uuid& GetUuid() const {
        return uuid_;
    }
 
    [[nodiscard]] Properties GetProperties() const {
        return properties_;
    }
 
    [[nodiscard]] uint16_t GetValueHandle() const {
        return value_attr_.GetHandle();
    }
 
    [[nodiscard]] uint16_t GetDeclarationHandle() const {
        return declaration_attr_.GetHandle();
    }
 
    [[nodiscard]] bool IsValid() const;
 
    [[nodiscard]] bool IsThisCharacteristic(const Uuid& uuid, uint16_t handle) const;
 
    [[nodiscard]] bool IsThisCharacteristic(const Uuid& uuid) const;
 
    [[nodiscard]] bool HasHandle(uint16_t handle) const;
 
 
    [[nodiscard]] bool HasBroadcast() const {
        return (static_cast<uint8_t>(properties_) & static_cast<uint8_t>(Properties::kBroadcast)) !=
               0;
    }
 
    [[nodiscard]] bool CanRead() const {
        return (static_cast<uint8_t>(properties_) & static_cast<uint8_t>(Properties::kRead)) != 0;
    }
 
    [[nodiscard]] bool CanWriteWithoutResponse() const {
        return (static_cast<uint8_t>(properties_) &
                static_cast<uint8_t>(Properties::kWriteWithoutResponse)) != 0;
    }
 
    [[nodiscard]] bool CanWrite() const {
        return (static_cast<uint8_t>(properties_) & static_cast<uint8_t>(Properties::kWrite)) != 0;
    }
 
    [[nodiscard]] bool HasNotifications() const {
        return (static_cast<uint8_t>(properties_) & static_cast<uint8_t>(Properties::kNotify)) != 0;
    }
 
    [[nodiscard]] bool HasIndications() const {
        return (static_cast<uint8_t>(properties_) & static_cast<uint8_t>(Properties::kIndicate)) !=
               0;
    }
 
    [[nodiscard]] bool CanSignedWrite() const {
        return (static_cast<uint8_t>(properties_) &
                static_cast<uint8_t>(Properties::kAuthenticatedSignedWrites)) != 0;
    }
 
    [[nodiscard]] bool HasExtendedPropertiesCapability() const {
        return (static_cast<uint8_t>(properties_) &
                static_cast<uint8_t>(Properties::kExtendedProperties)) != 0;
    }
 
 
    [[nodiscard]] bool ReadHasSecurityRequirement() const {
        uint16_t props = value_attr_.GetProperties();
        return (props & static_cast<uint16_t>(Attribute::Properties::kReadPermissionBit0)) != 0 ||
               (props & static_cast<uint16_t>(Attribute::Properties::kReadPermissionBit1)) != 0;
    }
 
    [[nodiscard]] bool WriteHasSecurityRequirement() const {
        uint16_t props = value_attr_.GetProperties();
        return (props & static_cast<uint16_t>(Attribute::Properties::kWritePermissionBit0)) != 0 ||
               (props & static_cast<uint16_t>(Attribute::Properties::kWritePermissionBit1)) != 0;
    }
 
    [[nodiscard]] bool ReadRequiresSC() const {
        return (value_attr_.GetProperties() &
                static_cast<uint16_t>(Attribute::Properties::kReadPermissionSc)) != 0;
    }
 
    [[nodiscard]] bool WriteRequiresSC() const {
        return (value_attr_.GetProperties() &
                static_cast<uint16_t>(Attribute::Properties::kWritePermissionSc)) != 0;
    }
 
    [[nodiscard]] uint16_t GetEncryptionKeySize() const {
        return (value_attr_.GetProperties() &
                static_cast<uint16_t>(Attribute::Properties::kEncryptionKeySizeMask)) >>
               12;
    }
 
    [[nodiscard]] bool ReadRequiresAuthentication() const;
 
    [[nodiscard]] bool WriteRequiresAuthentication() const;
 
    [[nodiscard]] bool ReadRequiresAuthorization() const;
 
    [[nodiscard]] bool WriteRequiresAuthorization() const;
 
    [[nodiscard]] bool ReadRequiresEncryption() const;
 
    [[nodiscard]] bool WriteRequiresEncryption() const;
 
    [[nodiscard]] bool RequiresAuthentication() const;
 
    [[nodiscard]] bool RequiresAuthorization() const;
 
    [[nodiscard]] bool RequiresEncryption() const;
 
 
    void SetReadSecurityLevel(SecurityLevel level);
 
    void SetWriteSecurityLevel(SecurityLevel level);
 
    void SetReadRequiresSecureConnections(bool required);
 
    void SetWriteRequiresSecureConnections(bool required);
 
    void SetEncryptionKeySize(uint8_t key_size);
 
    [[nodiscard]] SecurityLevel GetReadSecurityLevel() const;
 
    [[nodiscard]] SecurityLevel GetWriteSecurityLevel() const;
 
 
    [[nodiscard]] bool IsReadPermitted(bool authorized, bool authenticated) const;
 
    [[nodiscard]] bool IsWritePermitted(bool authorized, bool authenticated) const;
 
    [[nodiscard]] bool Uses128BitUuid() const {
        return (value_attr_.GetProperties() &
                static_cast<uint16_t>(Attribute::Properties::kUuid128)) != 0;
    }
 
    [[nodiscard]] bool IsDynamic() const {
        return (value_attr_.GetProperties() &
                static_cast<uint16_t>(Attribute::Properties::kDynamic)) != 0;
    }
 
 
    [[nodiscard]] const uint8_t* GetValueData() const;
 
    [[nodiscard]] size_t GetValueSize() const;
 
    [[nodiscard]] std::vector<uint8_t> GetValueAsVector() const;
 
 
    bool SetValue(const uint8_t* data, size_t size);
 
    bool SetValue(std::vector<uint8_t>&& data);
 
    bool SetValue(const std::vector<uint8_t>& data);
 
    template <typename T>
    bool SetValue(const T& value) {
        static_assert(std::is_trivial<T>::value, "T must be a trivial type for binary conversion");
        return SetValue(reinterpret_cast<const uint8_t*>(&value), sizeof(T));
    }
 
 
    Attribute& EnableCCCD();
 
    [[nodiscard]] bool HasCCCD() const {
        return cccd_ != nullptr;
    }
 
    [[nodiscard]] bool IsNotificationsEnabled() const;
 
    [[nodiscard]] bool IsIndicationsEnabled() const;
 
    Attribute* GetCCCD() {
        return cccd_.get();
    }
 
    [[nodiscard]] const Attribute* GetCCCD() const {
        return cccd_.get();
    }
 
    Attribute& SetCCCDValue(CCCDProperties config);
 
    Attribute& EnableSCCD();
 
    [[nodiscard]] bool HasSCCD() const {
        return sccd_ != nullptr;
    }
 
    [[nodiscard]] bool IsBroadcastEnabled() const;
 
    Attribute* GetSCCD() {
        return sccd_.get();
    }
 
    [[nodiscard]] const Attribute* GetSCCD() const {
        return sccd_.get();
    }
 
    Attribute& SetSCCDValue(SCCDProperties config);
 
    Attribute& EnableExtendedProperties();
 
    [[nodiscard]] bool HasExtendedProperties() const {
        return extended_properties_ != nullptr;
    }
 
    Attribute* GetExtendedProperties() {
        return extended_properties_.get();
    }
 
    [[nodiscard]] const Attribute* GetExtendedProperties() const {
        return extended_properties_.get();
    }
 
    Attribute& SetExtendedPropertiesValue(ExtendedProperties config);
 
    Attribute& SetUserDescription(const std::string& description);
 
    const std::string* SetUserDescriptionText(const std::string& description);
 
    [[nodiscard]] bool HasUserDescription() const {
        return user_description_ != nullptr;
    }
 
    Attribute* GetUserDescription() {
        return user_description_.get();
    }
 
    const std::string& GetUserDescriptionText() const {
        static const std::string empty_string;
        return user_description_ ? user_description_text_ : empty_string;
    }
    [[nodiscard]] const Attribute* GetUserDescription() const {
        return user_description_.get();
    }
 
    Attribute& AddDescriptor(const Uuid& uuid,
                             Attribute::Properties properties,
                             const std::vector<uint8_t>& value,
                             uint16_t handle = 0);
 
    [[nodiscard]] size_t GetDescriptorCount() const {
        return descriptors_.size();
    }
 
    Attribute* GetDescriptor(size_t index);
 
    [[nodiscard]] const Attribute* GetDescriptor(size_t index) const;
 
 
    Attribute& GetDeclarationAttribute() {
        return declaration_attr_;
    }
 
    [[nodiscard]] const Attribute& GetDeclarationAttribute() const {
        return declaration_attr_;
    }
 
    Attribute& GetValueAttribute() {
        return value_attr_;
    }
 
    [[nodiscard]] const Attribute& GetValueAttribute() const {
        return value_attr_;
    }
 
 
    void AddEventHandler(EventHandler& handler);
 
    bool RemoveEventHandler(const EventHandler& handler);
 
    void ClearEventHandlers();
 
    [[nodiscard]] std::list<EventHandler*> GetEventHandlers() const {
        return event_handlers_;
    }
 
 
    void SetConnectionHandle(uint16_t connection_handle) {
        connection_handle_ = connection_handle;
    }
 
    [[nodiscard]] uint16_t GetConnectionHandle() const {
        return connection_handle_;
    }
 
 
    virtual BleError DispatchBleHciPacket(uint8_t packet_type,
                                          const uint8_t* packet_data,
                                          uint16_t packet_data_size);
    uint16_t HandleAttributeRead(uint16_t attribute_handle,
                                 uint16_t offset,
                                 uint8_t* buffer,
                                 uint16_t buffer_size);
    BleError HandleAttributeWrite(uint16_t attribute_handle,
                                  uint16_t offset,
                                  const uint8_t* data,
                                  uint16_t size);
 
   protected:
 
    BleError DispatchEvent(EventId event_id,
                                   const uint8_t* event_data,
                                   uint16_t event_data_size);
 
 
    virtual BleError UpdateValue();
 
   private:
    // Core characteristic data
    Uuid uuid_;                   
    Properties properties_;       
    uint16_t connection_handle_;  
    bool notification_pending_;  
 
    // Required attributes
    Attribute declaration_attr_;  
    Attribute value_attr_;        
 
    // Optional descriptors
    std::unique_ptr<Attribute> cccd_;  
    std::unique_ptr<Attribute> sccd_;  
    std::unique_ptr<Attribute> extended_properties_;  
    std::unique_ptr<Attribute> user_description_;     
    std::string user_description_text_;           
    std::list<Attribute> descriptors_;                
 
    // Internal helpers for descriptor write handling
    BleError HandleCccdWrite(uint16_t offset, const uint8_t* data, uint16_t size) const;
    BleError HandleSccdWrite(uint16_t offset, const uint8_t* data, uint16_t size) const;
    uint16_t HandleUserDescriptionRead(uint16_t offset, uint8_t* buffer, uint16_t buffer_size) const;
    BleError HandleUserDescriptionWrite(uint16_t offset, const uint8_t* data, uint16_t size) const;
 
    // Internal helpers for value attribute read/write handling
    uint16_t HandleValueRead(uint16_t offset, uint8_t* buffer, uint16_t buffer_size) const;
    BleError HandleValueWrite(uint16_t offset, const uint8_t* data, uint16_t size);
 
    // Event handlers
    std::list<EventHandler*> event_handlers_;  
 
    void ConfigureUserDescriptionDescriptor();
    void SyncUserDescriptionTextFromAttribute();
    void RebindInternalCallbacks();
 
    friend std::ostream& operator<<(std::ostream& os, const Characteristic& characteristic);
};
 
// ========== Bitwise operators for Characteristic::Properties ==========
 
constexpr Characteristic::Properties operator|(Characteristic::Properties lhs,
                                               Characteristic::Properties rhs) noexcept {
    return static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) |
                                                   static_cast<uint8_t>(rhs));
}
 
constexpr Characteristic::Properties operator&(Characteristic::Properties lhs,
                                               Characteristic::Properties rhs) noexcept {
    return static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) &
                                                   static_cast<uint8_t>(rhs));
}
 
constexpr Characteristic::Properties operator^(Characteristic::Properties lhs,
                                               Characteristic::Properties rhs) noexcept {
    return static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) ^
                                                   static_cast<uint8_t>(rhs));
}
 
constexpr Characteristic::Properties operator~(Characteristic::Properties prop) noexcept {
    return static_cast<Characteristic::Properties>(~static_cast<uint8_t>(prop));
}
 
constexpr Characteristic::Properties& operator|=(Characteristic::Properties& lhs,
                                                 Characteristic::Properties rhs) noexcept {
    lhs = static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) |
                                                  static_cast<uint8_t>(rhs));
    return lhs;
}
 
constexpr Characteristic::Properties& operator&=(Characteristic::Properties& lhs,
                                                 Characteristic::Properties rhs) noexcept {
    lhs = static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) &
                                                  static_cast<uint8_t>(rhs));
    return lhs;
}
 
constexpr Characteristic::Properties& operator^=(Characteristic::Properties& lhs,
                                                 Characteristic::Properties rhs) noexcept {
    lhs = static_cast<Characteristic::Properties>(static_cast<uint8_t>(lhs) ^
                                                  static_cast<uint8_t>(rhs));
    return lhs;
}
 
std::ostream& operator<<(std::ostream& os, Characteristic::Properties props);
 
std::ostream& operator<<(std::ostream& os, const Characteristic& characteristic);
 
// ========== Bitwise operators for Characteristic::CCCDProperties ==========
 
constexpr Characteristic::CCCDProperties operator|(Characteristic::CCCDProperties lhs,
                                                   Characteristic::CCCDProperties rhs) noexcept {
    return static_cast<Characteristic::CCCDProperties>(static_cast<uint16_t>(lhs) |
                                                       static_cast<uint16_t>(rhs));
}
 
constexpr Characteristic::CCCDProperties operator&(Characteristic::CCCDProperties lhs,
                                                   Characteristic::CCCDProperties rhs) noexcept {
    return static_cast<Characteristic::CCCDProperties>(static_cast<uint16_t>(lhs) &
                                                       static_cast<uint16_t>(rhs));
}
 
// ========== Bitwise operators for Characteristic::SCCDProperties ==========
 
constexpr Characteristic::SCCDProperties operator|(Characteristic::SCCDProperties lhs,
                                                   Characteristic::SCCDProperties rhs) noexcept {
    return static_cast<Characteristic::SCCDProperties>(static_cast<uint16_t>(lhs) |
                                                       static_cast<uint16_t>(rhs));
}
 
constexpr Characteristic::SCCDProperties operator&(Characteristic::SCCDProperties lhs,
                                                   Characteristic::SCCDProperties rhs) noexcept {
    return static_cast<Characteristic::SCCDProperties>(static_cast<uint16_t>(lhs) &
                                                       static_cast<uint16_t>(rhs));
}
 
// ========== Bitwise operators for Characteristic::ExtendedProperties ==========
 
constexpr Characteristic::ExtendedProperties
operator|(Characteristic::ExtendedProperties lhs, Characteristic::ExtendedProperties rhs) noexcept {
    return static_cast<Characteristic::ExtendedProperties>(static_cast<uint16_t>(lhs) |
                                                           static_cast<uint16_t>(rhs));
}
 
constexpr Characteristic::ExtendedProperties
operator&(Characteristic::ExtendedProperties lhs, Characteristic::ExtendedProperties rhs) noexcept {
    return static_cast<Characteristic::ExtendedProperties>(static_cast<uint16_t>(lhs) &
                                                           static_cast<uint16_t>(rhs));
}
 
}  // namespace c7222
 
#endif  // ELEC_C7222_BLE_GATT_CHARACTERISTIC_HPP_