Bkap / BLE_API

adaptation for book and plug demo

Dependents:   BookAndPlug

Fork of BLE_API by Bluetooth Low Energy

Embed: (wiki syntax)

« Back to documentation index

ReadOnlyGattCharacteristic< T > Class Template Reference
Public Types | Public Member Functions

ReadOnlyGattCharacteristic< T > Class Template Reference

Helper class to construct a read-only GattCharacteristic. More...

#include <GattCharacteristic.h>

Inherits GattCharacteristic.

Public Types

enum  {
  BLE_GATT_UNIT_NONE = 0x2700, BLE_GATT_UNIT_LENGTH_METRE = 0x2701, BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702, BLE_GATT_UNIT_TIME_SECOND = 0x2703,
  BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704, BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705, BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706, BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707,
  BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710, BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711, BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712, BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713,
  BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714, BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715 , BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719 , BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722,
  BLE_GATT_UNIT_FORCE_NEWTON = 0x2723, BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724, BLE_GATT_UNIT_ENERGY_JOULE = 0x2725, BLE_GATT_UNIT_POWER_WATT = 0x2726,
  BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727, BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728 , BLE_GATT_UNIT_TIME_MINUTE = 0x2760, BLE_GATT_UNIT_TIME_HOUR = 0x2761,
  BLE_GATT_UNIT_TIME_DAY = 0x2762 , BLE_GATT_UNIT_PRESSURE_BAR = 0x2780, BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781 , BLE_GATT_UNIT_LENGTH_YARD = 0x27A0,
  BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1, BLE_GATT_UNIT_LENGTH_INCH = 0x27A2, BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3, BLE_GATT_UNIT_LENGTH_MILE = 0x27A4 ,
  BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6, BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7, BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8, BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9,
  BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA, BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB , BLE_GATT_UNIT_PERCENTAGE = 0x27AD , BLE_GATT_UNIT_TIME_YEAR = 0x27B3,
  BLE_GATT_UNIT_TIME_MONTH = 0x27B4
}
 

Standard GATT characteristic presentation format unit types.

More...
enum  {
  BLE_GATT_FORMAT_RFU = 0x00, BLE_GATT_FORMAT_BOOLEAN = 0x01, BLE_GATT_FORMAT_2BIT = 0x02, BLE_GATT_FORMAT_NIBBLE = 0x03,
  BLE_GATT_FORMAT_UINT8 = 0x04, BLE_GATT_FORMAT_UINT12 = 0x05, BLE_GATT_FORMAT_UINT16 = 0x06, BLE_GATT_FORMAT_UINT24 = 0x07,
  BLE_GATT_FORMAT_UINT32 = 0x08, BLE_GATT_FORMAT_UINT48 = 0x09, BLE_GATT_FORMAT_UINT64 = 0x0A, BLE_GATT_FORMAT_UINT128 = 0x0B,
  BLE_GATT_FORMAT_SINT8 = 0x0C, BLE_GATT_FORMAT_SINT12 = 0x0D, BLE_GATT_FORMAT_SINT16 = 0x0E, BLE_GATT_FORMAT_SINT24 = 0x0F,
  BLE_GATT_FORMAT_SINT32 = 0x10, BLE_GATT_FORMAT_SINT48 = 0x11, BLE_GATT_FORMAT_SINT64 = 0x12, BLE_GATT_FORMAT_SINT128 = 0x13,
  BLE_GATT_FORMAT_FLOAT32 = 0x14, BLE_GATT_FORMAT_FLOAT64 = 0x15, BLE_GATT_FORMAT_SFLOAT = 0x16, BLE_GATT_FORMAT_FLOAT = 0x17,
  BLE_GATT_FORMAT_DUINT16 = 0x18, BLE_GATT_FORMAT_UTF8S = 0x19, BLE_GATT_FORMAT_UTF16S = 0x1A, BLE_GATT_FORMAT_STRUCT = 0x1B
}
 

Standard GATT number types.

More...
enum  Properties_t { ,
  BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, BLE_GATT_CHAR_PROPERTIES_READ = 0x02, BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04, BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08,
  BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10, BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20, BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40, BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80
}
 

Standard GATT characteristic properties.

More...

Public Member Functions

 ReadOnlyGattCharacteristic (const UUID &uuid, T *valuePtr, uint8_t additionalProperties=BLE_GATT_CHAR_PROPERTIES_NONE, GattAttribute *descriptors[]=NULL, unsigned numDescriptors=0)
 Construct a ReadOnlyGattCharacteristic.
void requireSecurity (SecurityManager::SecurityMode_t securityMode)
 Set up the minimum security (mode and level) requirements for access to the characteristic's value attribute.
void setWriteAuthorizationCallback (void(*callback)(GattWriteAuthCallbackParams *))
 Set up callback that will be triggered before the GATT Client is allowed to write this characteristic.
template<typename T >
void setWriteAuthorizationCallback (T *object, void(T::*member)(GattWriteAuthCallbackParams *))
 Same as GattCharacrteristic::setWriteAuthorizationCallback(), but allows the possibility to add an object reference and member function as handler for connection event callbacks.
void setReadAuthorizationCallback (void(*callback)(GattReadAuthCallbackParams *))
 Set up callback that will be triggered before the GATT Client is allowed to read this characteristic.
template<typename T >
void setReadAuthorizationCallback (T *object, void(T::*member)(GattReadAuthCallbackParams *))
 Same as GattCharacrteristic::setReadAuthorizationCallback(), but allows the possibility to add an object reference and member function as handler for connection event callbacks.
GattAuthCallbackReply_t authorizeWrite (GattWriteAuthCallbackParams *params)
 Helper that calls the registered handler to determine the authorization reply for a write request.
GattAuthCallbackReply_t authorizeRead (GattReadAuthCallbackParams *params)
 Helper that calls the registered handler to determine the authorization reply for a read request.
GattAttribute & getValueAttribute ()
 Get the characteristic's value attribute.
const GattAttribute & getValueAttribute () const
 A const alternative to GattCharacteristic::getValueAttribute().
GattAttribute::Handle_t getValueHandle (void) const
 Get the characteristic's value attribute handle in the ATT table.
uint8_t getProperties (void) const
 Get the characteristic's propertied.
SecurityManager::SecurityMode_t getRequiredSecurity () const
 Get the characteristic's required security.
uint8_t getDescriptorCount (void) const
 Get the total number of descriptors within this characteristic.
bool isReadAuthorizationEnabled () const
 Check whether read authorization is enabled i.e.
bool isWriteAuthorizationEnabled () const
 Check whether write authorization is enabled i.e.
GattAttribute * getDescriptor (uint8_t index)
 Get this characteristic's descriptor at a specific index.

Detailed Description

template<typename T>
class ReadOnlyGattCharacteristic< T >

Helper class to construct a read-only GattCharacteristic.

Definition at line 623 of file GattCharacteristic.h.

Member Enumeration Documentation

anonymous enum [inherited]

Standard GATT characteristic presentation format unit types.

These unit types are used to describe what the raw numeric data in a characteristic actually represents.

Note:
See https://developer.bluetooth.org/gatt/units/Pages/default.aspx

Definition at line 109 of file GattCharacteristic.h.

anonymous enum [inherited]

Standard GATT number types.

Note:
See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2.
See http://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml

Definition at line 228 of file GattCharacteristic.h.

enum Properties_t [inherited]

Standard GATT characteristic properties.

Note:
See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1 and Section 3.3.3.1 for Extended Properties.

Definition at line 265 of file GattCharacteristic.h.

Constructor & Destructor Documentation

ReadOnlyGattCharacteristic ( const UUID &  uuid,
T *  valuePtr,
uint8_t  additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *  descriptors[] = NULL,
unsigned  numDescriptors = 0 
)

Construct a ReadOnlyGattCharacteristic.

Parameters:
[in]uuidThe characteristic's UUID.
[in]valuePtrPointer to the characterisitic's initial value.
[in]additionalPropertiesAdditional characterisitic properties. By default, the properties are set to Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
[in]descriptorsAn array of pointers to descriptors to be added to the new characteristic.
[in]numDescriptorsThe total number of descriptors in descriptors.
Note:
Instances of ReadOnlyGattCharacteristic have a fixed length attribute value that equals sizeof(T). For a variable length alternative use GattCharacteristic directly.

Definition at line 646 of file GattCharacteristic.h.

Member Function Documentation

GattAuthCallbackReply_t authorizeRead ( GattReadAuthCallbackParams *  params ) [inherited]

Helper that calls the registered handler to determine the authorization reply for a read request.

This function is meant to be called from the BLE stack specific implementation.

Parameters:
[in]paramsTo capture the context of the read-auth request.
Returns:
A GattAuthCallbackReply_t value indicating whether authorization is granted.
Note:
To authorize or deny the read the params->authorizationReply field should be set to true (authorize) or false (deny).
If the read is approved and params->data is unchanged (NULL), the current characteristic value will be used.
If the read is approved, a new value can be provided by setting the params->data pointer and params->len fields.

Definition at line 463 of file GattCharacteristic.h.

GattAuthCallbackReply_t authorizeWrite ( GattWriteAuthCallbackParams *  params ) [inherited]

Helper that calls the registered handler to determine the authorization reply for a write request.

This function is meant to be called from the BLE stack specific implementation.

Parameters:
[in]paramsTo capture the context of the write-auth request. Also contains an out-parameter for reply.
Returns:
A GattAuthCallbackReply_t value indicating whether authorization is granted.

Definition at line 433 of file GattCharacteristic.h.

GattAttribute* getDescriptor ( uint8_t  index ) [inherited]

Get this characteristic's descriptor at a specific index.

Parameters:
[in]indexThe descriptor's index.
Returns:
A pointer the requested descriptor if index contains a valid descriptor, or NULL otherwise.

Definition at line 563 of file GattCharacteristic.h.

uint8_t getDescriptorCount ( void   ) const [inherited]

Get the total number of descriptors within this characteristic.

Returns:
The total number of descriptors.

Definition at line 528 of file GattCharacteristic.h.

uint8_t getProperties ( void   ) const [inherited]

Get the characteristic's propertied.

Refer to GattCharacteristic::Properties_t.

Returns:
The characteristic's properties.

Definition at line 510 of file GattCharacteristic.h.

SecurityManager::SecurityMode_t getRequiredSecurity (  ) const [inherited]

Get the characteristic's required security.

Returns:
The characteristic's required security.

Definition at line 519 of file GattCharacteristic.h.

const GattAttribute& getValueAttribute (  ) const [inherited]

A const alternative to GattCharacteristic::getValueAttribute().

Returns:
A const reference to the characteristic's value attribute.

Definition at line 488 of file GattCharacteristic.h.

GattAttribute& getValueAttribute (  ) [inherited]

Get the characteristic's value attribute.

Returns:
A reference to the characteristic's value attribute.

Definition at line 479 of file GattCharacteristic.h.

GattAttribute::Handle_t getValueHandle ( void   ) const [inherited]

Get the characteristic's value attribute handle in the ATT table.

Returns:
The value attribute handle.
Note:
The attribute handle is typically assigned by the underlying BLE stack.

Definition at line 500 of file GattCharacteristic.h.

bool isReadAuthorizationEnabled (  ) const [inherited]

Check whether read authorization is enabled i.e.

check whether a read authorization callback was previously registered. Refer to GattCharacteristic::setReadAuthorizationCallback().

Returns:
true if read authorization is enabled, false otherwise.

Definition at line 539 of file GattCharacteristic.h.

bool isWriteAuthorizationEnabled (  ) const [inherited]

Check whether write authorization is enabled i.e.

check whether a write authorization callback was previously registered. Refer to GattCharacteristic::setReadAuthorizationCallback().

Returns:
true if write authorization is enabled, false otherwise.

Definition at line 550 of file GattCharacteristic.h.

void requireSecurity ( SecurityManager::SecurityMode_t  securityMode ) [inherited]

Set up the minimum security (mode and level) requirements for access to the characteristic's value attribute.

Parameters:
[in]securityModeCan be one of encryption or signing, with or without protection for man in the middle attacks (MITM).

Definition at line 354 of file GattCharacteristic.h.

void setReadAuthorizationCallback ( T *  object,
void(T::*)(GattReadAuthCallbackParams *)  member 
) [inherited]

Same as GattCharacrteristic::setReadAuthorizationCallback(), but allows the possibility to add an object reference and member function as handler for connection event callbacks.

Parameters:
[in]objectPointer to the object of a class defining the member callback function (member).
[in]memberThe member callback (within the context of an object) to be invoked.

Definition at line 416 of file GattCharacteristic.h.

void setReadAuthorizationCallback ( void(*)(GattReadAuthCallbackParams *)  callback ) [inherited]

Set up callback that will be triggered before the GATT Client is allowed to read this characteristic.

The handler will determine the authorizaion reply for the read.

Parameters:
[in]callbackEvent handler being registered.

Definition at line 398 of file GattCharacteristic.h.

void setWriteAuthorizationCallback ( void(*)(GattWriteAuthCallbackParams *)  callback ) [inherited]

Set up callback that will be triggered before the GATT Client is allowed to write this characteristic.

The handler will determine the authorization reply for the write.

Parameters:
[in]callbackEvent handler being registered.

Definition at line 367 of file GattCharacteristic.h.

void setWriteAuthorizationCallback ( T *  object,
void(T::*)(GattWriteAuthCallbackParams *)  member 
) [inherited]

Same as GattCharacrteristic::setWriteAuthorizationCallback(), but allows the possibility to add an object reference and member function as handler for connection event callbacks.

Parameters:
[in]objectPointer to the object of a class defining the member callback function (member).
[in]memberThe member callback (within the context of an object) to be invoked.

Definition at line 385 of file GattCharacteristic.h.

Generated on Wed Jul 13 2022 09:31:10 by  doxygen 1.7.2