Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Types | Public Member Functions | Static Public Member Functions
GattCharacteristic Class Reference

Representation of a GattServer characteristic. More...

#include <GattCharacteristic.h>

Inheritance diagram for GattCharacteristic:
ReadOnlyArrayGattCharacteristic< T, NUM_ELEMENTS > ReadOnlyGattCharacteristic< T > ReadOnlyGattCharacteristic< HumidityType_t > ReadOnlyGattCharacteristic< PressureType_t > ReadOnlyGattCharacteristic< TemperatureType_t > ReadOnlyGattCharacteristic< TemperatureValueBytes > ReadOnlyGattCharacteristic< uint8_t > ReadWriteArrayGattCharacteristic< T, NUM_ELEMENTS > ReadWriteGattCharacteristic< T > ReadWriteGattCharacteristic< uint8_t > WriteOnlyArrayGattCharacteristic< T, NUM_ELEMENTS > WriteOnlyGattCharacteristic< T >

Data Structures

struct  PresentationFormat_t
 Value of a Characteristic Presentation Format descriptor. More...
 

Public Types

typedef ble::att_security_requirement_t SecurityRequirement_t
 Security level applied to GATT operations. More...
 

Public Member Functions

 GattCharacteristic (const UUID &uuid, uint8_t *valuePtr=nullptr, uint16_t len=0, uint16_t maxLen=0, uint8_t props=BLE_GATT_CHAR_PROPERTIES_NONE, GattAttribute *descriptors[]=nullptr, unsigned numDescriptors=0, bool hasVariableLen=true)
 Constructs a new GattCharacteristic. More...
 
void setSecurityRequirements (SecurityRequirement_t read_security, SecurityRequirement_t write_security, SecurityRequirement_t update_security)
 Set all security requirements of the characteristic. More...
 
void setReadSecurityRequirement (SecurityRequirement_t security)
 Set the security of the read operation. More...
 
SecurityRequirement_t getReadSecurityRequirement () const
 Get the security requirement of the read operation. More...
 
void setWriteSecurityRequirement (SecurityRequirement_t security)
 Set the security requirement of the write operations. More...
 
SecurityRequirement_t getWriteSecurityRequirement () const
 Get the security requirement of write operations. More...
 
void setUpdateSecurityRequirement (SecurityRequirement_t security)
 Set the security requirement of update operations. More...
 
SecurityRequirement_t getUpdateSecurityRequirement () const
 Get the security requirement of update operations. More...
 
void setWriteAuthorizationCallback (void(*callback)(GattWriteAuthCallbackParams *))
 Register a callback handling client's write requests or commands. More...
 
template<typename T >
void setWriteAuthorizationCallback (T *object, void(T::*member)(GattWriteAuthCallbackParams *))
 Register a callback handling client's write requests or commands. More...
 
const FunctionPointerWithContext< GattWriteAuthCallbackParams * > & getWriteAuthorizationCallback () const
 Return the callback registered to handle client's write. More...
 
void setReadAuthorizationCallback (void(*callback)(GattReadAuthCallbackParams *))
 Register the read requests event handler. More...
 
template<typename T >
void setReadAuthorizationCallback (T *object, void(T::*member)(GattReadAuthCallbackParams *))
 Register the read requests event handler. More...
 
const FunctionPointerWithContext< GattReadAuthCallbackParams * > & getReadAuthorizationCallback () const
 Return the callback registered to handle client's read. More...
 
GattAuthCallbackReply_t authorizeWrite (GattWriteAuthCallbackParams *params)
 Invoke the write authorization callback. More...
 
GattAuthCallbackReply_t authorizeRead (GattReadAuthCallbackParams *params)
 Invoke the read authorization callback. More...
 
GattAttributegetValueAttribute ()
 Get the characteristic's value attribute. More...
 
const GattAttributegetValueAttribute () const
 Get the characteristic's value attribute. More...
 
GattAttribute::Handle_t getValueHandle () const
 Get the characteristic's value attribute handle in the ATT table. More...
 
uint8_t getProperties () const
 Get the characteristic's properties. More...
 
uint8_t getDescriptorCount () const
 Get the total number of descriptors within this characteristic. More...
 
bool isReadAuthorizationEnabled () const
 Check whether read authorization is enabled. More...
 
bool isWriteAuthorizationEnabled () const
 Check whether write authorization is enabled. More...
 
GattAttributegetDescriptor (uint8_t index)
 Get this characteristic's descriptor at a specific index. More...
 

Static Public Member Functions

static bool isWritable (uint8_t properties)
 Indicates if the properties has at least one of the writable flags. More...
 
static bool isReadable (uint8_t properties)
 Indicates if the properties is readable. More...
 

Detailed Description

Representation of a GattServer characteristic.

A characteristic is a typed value enclosed in a GATT service (GattService).

Type

The type of the value defines the purpose of the characteristic, and a UUID represents it. Standard characteristic types may be consulted at https://www.bluetooth.com/specifications/gatt/characteristics

Supported operations
A set of properties define what client operations the characteristic supports. See GattServer::Properties_t
Descriptors

Additional information, such as the unit of the characteristic value, a description string or a client control point, can be added to the characteristic.

See BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part G] - 3.3.1.1

One of the most important types of descriptor is the Client Characteristic Configuration Descriptor (CCCD) that must be present if the characteristic properties allow a client to subscribe to updates of the characteristic value.

Characteristic breakdown

A characteristic is composed of several GATT attributes (GattAttribute):

When the GattService containing the characteristic is registered in the GattServer, a unique attribute handle is assigned to the various attributes of the characteristic. Clients use this handle to interact with the characteristic. This handle is used locally in GattServer APIs.

Security requirements

Verification of security requirements happens whenever a client request to read the characteristic; write it or even register to its updates. Different requirements may be defined for these three type of operation. As an example: it is possible to define a characteristic that do not require security to be read and require an authenticated link to be written.

By default all security requirements are set to att_security_requirement_t::NONE except if the characteristic supports signed write; in such case the security requirement for write operations is set to att_security_requirement_t::UNAUTHENTICATED.

Note
If a peer uses an operation that is not set in the characteristic properties then the request request is discarded regardless of the security requirements and current security level. The only exception being signed write: signed write are converted into regular write without response if the link is encrypted.

Definition at line 105 of file gatt/GattCharacteristic.h.

Member Typedef Documentation

Security level applied to GATT operations.

Definition at line 1374 of file gatt/GattCharacteristic.h.

Member Enumeration Documentation

anonymous enum
Enumerator
UUID_BATTERY_LEVEL_STATE_CHAR 

Not used in actual BLE service.

UUID_BATTERY_POWER_STATE_CHAR 

Not used in actual BLE service.

UUID_REMOVABLE_CHAR 

Not used in actual BLE service.

UUID_SERVICE_REQUIRED_CHAR 

Not used in actual BLE service.

UUID_ALERT_CATEGORY_ID_CHAR 

Not used as a characteristic UUID.

UUID_ALERT_CATEGORY_ID_BIT_MASK_CHAR 

Not used as a characteristic UUID.

UUID_ALERT_LEVEL_CHAR 

Control point of the Immediate Alert service that allows the client to command the server to alert to a given level.

UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR 

Control point of the Alert Notification service that allows the client finely tune the notification configuration.

UUID_ALERT_STATUS_CHAR 

Part of the Alert Notification service, which exposes the count of unread alert events existing in the server.

UUID_BATTERY_LEVEL_CHAR 

Characteristic of the Battery service, which exposes the current battery level as a percentage.

UUID_BLOOD_PRESSURE_FEATURE_CHAR 

Describe the features supported by the blood pressure sensor exposed by the Blood Pressure service.

UUID_BLOOD_PRESSURE_MEASUREMENT_CHAR 

Characteristic of the Blood Pressure service that exposes the measurement of the blood sensor.

UUID_BODY_SENSOR_LOCATION_CHAR 

Characteristic of the Heart Rate service that indicate the intended location of the heart rate monitor.

UUID_BOOT_KEYBOARD_INPUT_REPORT_CHAR 

Part of the Human Interface Device service.

UUID_BOOT_KEYBOARD_OUTPUT_REPORT_CHAR 

Part of the Human Interface Device service.

UUID_BOOT_MOUSE_INPUT_REPORT_CHAR 

Part of the Human Interface Device service.

UUID_CURRENT_TIME_CHAR 

Characteristic of the Current Time service that contains the current time.

UUID_DATE_TIME_CHAR 

Not used in a service as a characteristic.

UUID_DAY_DATE_TIME_CHAR 

Not used in a service as a characteristic.

UUID_DAY_OF_WEEK_CHAR 

Not used in a service as a characteristic.

UUID_DST_OFFSET_CHAR 

Not used in a service as a characteristic.

UUID_EXACT_TIME_256_CHAR 

Not used in a service as a characteristic.

UUID_FIRMWARE_REVISION_STRING_CHAR 

Characteristic of the Device Information Service that contains a UTF8 string representing the firmware revision for the firmware within the device.

UUID_GLUCOSE_FEATURE_CHAR 

Characteristic of the Glucose service that exposes features supported by the server.

UUID_GLUCOSE_MEASUREMENT_CHAR 

Characteristic of the Glucose service that exposes glucose measurements.

UUID_GLUCOSE_MEASUREMENT_CONTEXT_CHAR 

Characteristic of the Glucose service that sends additional information related to the glucose measurements.

UUID_HARDWARE_REVISION_STRING_CHAR 

Characteristic of the Device Information Service that contains a UTF8 string representing the hardware revision of the device.

UUID_HEART_RATE_CONTROL_POINT_CHAR 

Characteristic of the Heart Rate service used by the client to control the service behavior.

UUID_HEART_RATE_MEASUREMENT_CHAR 

Characteristic of the Heart Rate that sends heart rate measurements to registered clients.

UUID_HID_CONTROL_POINT_CHAR 

Part of the Human Interface Device service.

UUID_HID_INFORMATION_CHAR 

Part of the Human Interface Device service.

UUID_HUMIDITY_CHAR 

Characteristic of the Environmental Sensing service, which exposes humidity measurements.

UUID_IEEE_REGULATORY_CERTIFICATION_DATA_LIST_CHAR 

Characteristic of the Device Information Service, which exposes various regulatory or certification compliance items to which the device claims adherence.

UUID_INTERMEDIATE_CUFF_PRESSURE_CHAR 

Characteristic of the Blood Pressure service, which exposes intermediate cuff pressure measurements.

UUID_INTERMEDIATE_TEMPERATURE_CHAR 

Characteristic of the Health Thermometer service that sends intermediate temperature values while the measurement is in progress.

UUID_LOCAL_TIME_INFORMATION_CHAR 

Characteristic of the current Time service that exposes information about the local time.

UUID_MANUFACTURER_NAME_STRING_CHAR 

Characteristic of the Device Information Service that contains a UTF8 string representing the manufacturer name of the device.

UUID_MEASUREMENT_INTERVAL_CHAR 

Characteristic of the Health Thermometer service that exposes the interval time between two measurements.

UUID_MODEL_NUMBER_STRING_CHAR 

Characteristic of the Device Information Service that contains a UTF8 string representing the model number of the device assigned by the vendor.

UUID_UNREAD_ALERT_CHAR 

Characteristic of the Alert Notification Service that shows how many numbers of unread alerts exist in the specific category in the device.

UUID_NEW_ALERT_CHAR 

Characteristic of the Alert Notification Service that defines the category of the alert and how many new alerts of that category have occurred in the server.

UUID_PNP_ID_CHAR 

Characteristic of the Device Information Service; it is a set of values used to create a device ID that is unique for this device.

UUID_PRESSURE_CHAR 

Characteristic of the Environmental Sensing Service that exposes the pressure measured.

UUID_PROTOCOL_MODE_CHAR 

Part of the Human Interface Device service.

UUID_RECORD_ACCESS_CONTROL_POINT_CHAR 

Pulse Oxymeter, Glucose and Continuous Glucose Monitoring services use this control point to provide basic management of the patient record database.

UUID_REFERENCE_TIME_INFORMATION_CHAR 

Characteristic of the Current Time service that exposes information related to the current time served (accuracy, source, hours since update and so on).

UUID_REPORT_CHAR 

Part of the Human Interface Device service.

UUID_REPORT_MAP_CHAR 

Part of the Human Interface Device service.

UUID_RINGER_CONTROL_POINT_CHAR 

Characteristic of the Phone Alert Status service that allows a client to configure operating mode.

UUID_RINGER_SETTING_CHAR 

Characteristic of the Phone Alert Status service that returns the ringer setting when read.

UUID_SCAN_INTERVAL_WINDOW_CHAR 

Characteristic of the Scan Parameter service that stores the client's scan parameters (scan interval and scan window).

UUID_SCAN_REFRESH_CHAR 

Characteristic of the Scan Parameter service that sends a notification to a client when the server requires its latest scan parameters.

UUID_SERIAL_NUMBER_STRING_CHAR 

Characteristic of the Device Information Service that contains a UTF8 string representing the serial number of the device.

UUID_SOFTWARE_REVISION_STRING_CHAR 

Characteristic of the Device Information Service that contains an UTF8 string representing the software revision of the device.

UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR 

Characteristic of the Alert Notification Service that notifies the count of new alerts for a given category to a subscribed client.

UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR 

Characteristic of the Alert Notification service, which exposes categories of unread alert supported by the server.

UUID_SYSTEM_ID_CHAR 

Characteristic of the Device Information Service that exposes a structure containing an Organizationally Unique Identifier (OUI) followed by a manufacturer-defined identifier.

The value of the structure is unique for each individual instance of the product.

UUID_TEMPERATURE_CHAR 

Characteristic of the Environmental Sensing service that exposes the temperature measurement with a resolution of 0.01 degree Celsius.

UUID_TEMPERATURE_MEASUREMENT_CHAR 

Characteristic of the Health Thermometer service that sends temperature measurement to clients.

UUID_TEMPERATURE_TYPE_CHAR 

Characteristic of the Health Thermometer service that describes where the measurement takes place.

UUID_TIME_ACCURACY_CHAR 

Not used in a service as a characteristic.

UUID_TIME_SOURCE_CHAR 

Not used in a service as a characteristic.

UUID_TIME_UPDATE_CONTROL_POINT_CHAR 

Characteristic of the Reference Time service that allows clients to control time update.

UUID_TIME_UPDATE_STATE_CHAR 

Characteristic of the Reference Time service that informs clients of the status of the time update operation.

UUID_TIME_WITH_DST_CHAR 

Characteristic of the Next DST Change service that returns to clients the time with DST.

UUID_TIME_ZONE_CHAR 

Not used in a service as a characteristic.

UUID_TX_POWER_LEVEL_CHAR 

Characteristic of the TX Power service that exposes the current transmission power in dBm.

UUID_CSC_FEATURE_CHAR 

Characteristic of the Cycling Speed and Cadence (CSC) service that exposes features supported by the server.

UUID_CSC_MEASUREMENT_CHAR 

Characteristic of the Cycling Speed and Cadence (CSC) service that exposes measurements made by the server.

UUID_RSC_FEATURE_CHAR 

Characteristic of the Running Speed and Cadence (RSC) service that exposes features supported by the server.

UUID_RSC_MEASUREMENT_CHAR 

Characteristic of the Running Speed and Cadence (RSC) service that exposes measurements made by the server.

Definition at line 111 of file gatt/GattCharacteristic.h.

anonymous enum

Unit type of a characteristic value.

These unit types are used to describe what the raw numeric data in a characteristic actually represents. A server can expose that information to its clients by adding a Characteristic Presentation Format descriptor to relevant characteristics.

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

No specified unit type.

BLE_GATT_UNIT_LENGTH_METRE 

Length, meter.

BLE_GATT_UNIT_MASS_KILOGRAM 

Mass, kilogram.

BLE_GATT_UNIT_TIME_SECOND 

Time, second.

BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE 

Electric current, ampere.

BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN 

Thermodynamic temperature, kelvin.

BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE 

Amount of substance, mole.

BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA 

Luminous intensity, candela.

BLE_GATT_UNIT_AREA_SQUARE_METRES 

Area, square meters.

BLE_GATT_UNIT_VOLUME_CUBIC_METRES 

Volume, cubic meters.

BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND 

Velocity, meters per second.

BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED 

Acceleration, meters per second squared.

BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE 

Wave number reciprocal, meter.

BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE 

Density, kilogram per cubic meter.

BLE_GATT_UNIT_SURFACE_DENSITY_KILOGRAM_PER_SQUARE_METRE 

Surface density (kilogram per square meter).

BLE_GATT_UNIT_SPECIFIC_VOLUME_CUBIC_METRE_PER_KILOGRAM 

Specific volume (cubic meter per kilogram).

BLE_GATT_UNIT_CURRENT_DENSITY_AMPERE_PER_SQUARE_METRE 

Current density (ampere per square meter).

BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE 

Magnetic field strength, ampere per meter.

BLE_GATT_UNIT_AMOUNT_CONCENTRATION_MOLE_PER_CUBIC_METRE 

Amount concentration (mole per cubic meter).

BLE_GATT_UNIT_MASS_CONCENTRATION_KILOGRAM_PER_CUBIC_METRE 

Mass concentration (kilogram per cubic meter).

BLE_GATT_UNIT_LUMINANCE_CANDELA_PER_SQUARE_METRE 

Luminance (candela per square meter).

BLE_GATT_UNIT_REFRACTIVE_INDEX 

Refractive index.

BLE_GATT_UNIT_RELATIVE_PERMEABILITY 

Relative permeability.

BLE_GATT_UNIT_PLANE_ANGLE_RADIAN 

Plane angle (radian).

BLE_GATT_UNIT_SOLID_ANGLE_STERADIAN 

Solid angle (steradian).

BLE_GATT_UNIT_FREQUENCY_HERTZ 

Frequency, hertz.

BLE_GATT_UNIT_FORCE_NEWTON 

Force, newton.

BLE_GATT_UNIT_PRESSURE_PASCAL 

Pressure, pascal.

BLE_GATT_UNIT_ENERGY_JOULE 

Energy, joule.

BLE_GATT_UNIT_POWER_WATT 

Power, watt.

BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB 

Electrical charge, coulomb.

BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT 

Electrical potential difference, voltage.

BLE_GATT_UNIT_CAPACITANCE_FARAD 

Capacitance, farad.

BLE_GATT_UNIT_ELECTRIC_RESISTANCE_OHM 

Electric resistance, ohm.

BLE_GATT_UNIT_ELECTRIC_CONDUCTANCE_SIEMENS 

Electric conductance, siemens.

BLE_GATT_UNIT_MAGNETIC_FLUX_WEBER 

Magnetic flux, weber.

BLE_GATT_UNIT_MAGNETIC_FLUX_DENSITY_TESLA 

Magnetic flux density, tesla.

BLE_GATT_UNIT_INDUCTANCE_HENRY 

Inductance, henry.

BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_CELSIUS 

Celsius temperature, degree Celsius.

BLE_GATT_UNIT_LUMINOUS_FLUX_LUMEN 

Luminous flux, lumen.

BLE_GATT_UNIT_ILLUMINANCE_LUX 

Illuminance, lux.

BLE_GATT_UNIT_ACTIVITY_REFERRED_TO_A_RADIONUCLIDE_BECQUEREL 

Activity referred to a radionuclide, becquerel.

BLE_GATT_UNIT_ABSORBED_DOSE_GRAY 

Absorbed dose, gray.

BLE_GATT_UNIT_DOSE_EQUIVALENT_SIEVERT 

Dose equivalent, sievert.

BLE_GATT_UNIT_CATALYTIC_ACTIVITY_KATAL 

Catalytic activity, katal.

BLE_GATT_UNIT_DYNAMIC_VISCOSITY_PASCAL_SECOND 

Dynamic viscosity, pascal second.

BLE_GATT_UNIT_MOMENT_OF_FORCE_NEWTON_METRE 

Moment of force, newton meter.

BLE_GATT_UNIT_SURFACE_TENSION_NEWTON_PER_METRE 

Surface tension, newton per meter.

BLE_GATT_UNIT_ANGULAR_VELOCITY_RADIAN_PER_SECOND 

Angular velocity, radian per second.

BLE_GATT_UNIT_ANGULAR_ACCELERATION_RADIAN_PER_SECOND_SQUARED 

Angular acceleration, radian per second squared.

BLE_GATT_UNIT_HEAT_FLUX_DENSITY_WATT_PER_SQUARE_METRE 

Heat flux density, watt per square meter.

BLE_GATT_UNIT_HEAT_CAPACITY_JOULE_PER_KELVIN 

Heat capacity, joule per kelvin.

BLE_GATT_UNIT_SPECIFIC_HEAT_CAPACITY_JOULE_PER_KILOGRAM_KELVIN 

Specific heat capacity, joule per kilogram kelvin.

BLE_GATT_UNIT_SPECIFIC_ENERGY_JOULE_PER_KILOGRAM 

Specific energy, joule per kilogram.

BLE_GATT_UNIT_THERMAL_CONDUCTIVITY_WATT_PER_METRE_KELVIN 

Thermal conductivity, watt per meter kelvin.

BLE_GATT_UNIT_ENERGY_DENSITY_JOULE_PER_CUBIC_METRE 

Energy density, joule per cubic meter.

BLE_GATT_UNIT_ELECTRIC_FIELD_STRENGTH_VOLT_PER_METRE 

Electric field strength, volt per meter.

BLE_GATT_UNIT_ELECTRIC_CHARGE_DENSITY_COULOMB_PER_CUBIC_METRE 

Electric charge density, coulomb per cubic meter.

BLE_GATT_UNIT_SURFACE_CHARGE_DENSITY_COULOMB_PER_SQUARE_METRE 

Surface charge density, coulomb per square meter.

BLE_GATT_UNIT_ELECTRIC_FLUX_DENSITY_COULOMB_PER_SQUARE_METRE 

Electric flux density, coulomb per square meter.

BLE_GATT_UNIT_PERMITTIVITY_FARAD_PER_METRE 

Permittivity, farad per meter.

BLE_GATT_UNIT_PERMEABILITY_HENRY_PER_METRE 

Permeability, henry per meter.

BLE_GATT_UNIT_MOLAR_ENERGY_JOULE_PER_MOLE 

Molar energy, joule per mole.

BLE_GATT_UNIT_MOLAR_ENTROPY_JOULE_PER_MOLE_KELVIN 

Molar entropy, joule per mole kelvin.

BLE_GATT_UNIT_EXPOSURE_COULOMB_PER_KILOGRAM 

Exposure, coulomb per kilogram.

BLE_GATT_UNIT_ABSORBED_DOSE_RATE_GRAY_PER_SECOND 

Absorbed dose rate, gray per second.

BLE_GATT_UNIT_RADIANT_INTENSITY_WATT_PER_STERADIAN 

Radiant intensity, watt per steradian.

BLE_GATT_UNIT_RADIANCE_WATT_PER_SQUARE_METRE_STERADIAN 

Radiance, watt per square meter steradian.

BLE_GATT_UNIT_CATALYTIC_ACTIVITY_CONCENTRATION_KATAL_PER_CUBIC_METRE 

Catalytic activity concentration, katal per cubic meter.

BLE_GATT_UNIT_TIME_MINUTE 

Time, minute.

BLE_GATT_UNIT_TIME_HOUR 

Time, hour.

BLE_GATT_UNIT_TIME_DAY 

Time, day.

BLE_GATT_UNIT_PLANE_ANGLE_DEGREE 

Plane angle, degree.

BLE_GATT_UNIT_PLANE_ANGLE_MINUTE 

Plane angle, minute.

BLE_GATT_UNIT_PLANE_ANGLE_SECOND 

Plane angle, seconds.

BLE_GATT_UNIT_AREA_HECTARE 

Area, hectare.

BLE_GATT_UNIT_VOLUME_LITRE 

Volume, liter.

BLE_GATT_UNIT_MASS_TONNE 

Mass, ton.

BLE_GATT_UNIT_PRESSURE_BAR 

Pressure, bar.

BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY 

Pressure, millimeter of mercury.

BLE_GATT_UNIT_LENGTH_ANGSTROM 

Length, ngstrm.

BLE_GATT_UNIT_LENGTH_NAUTICAL_MILE 

Length, nautical mile.

BLE_GATT_UNIT_AREA_BARN 

Area, barn.

BLE_GATT_UNIT_VELOCITY_KNOT 

Velocity, knot.

BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_NEPER 

Logarithmic radio quantity, neper.

BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_BEL 

Logarithmic radio quantity, bel.

BLE_GATT_UNIT_LENGTH_YARD 

Length, yard.

BLE_GATT_UNIT_LENGTH_PARSEC 

Length, parsec.

BLE_GATT_UNIT_LENGTH_INCH 

Length, inch.

BLE_GATT_UNIT_LENGTH_FOOT 

Length, foot.

BLE_GATT_UNIT_LENGTH_MILE 

Length, mile.

BLE_GATT_UNIT_PRESSURE_POUND_FORCE_PER_SQUARE_INCH 

Pressure, pound-force per square inch.

BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR 

Velocity, kilometer per hour.

BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR 

Velocity, mile per hour.

BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE 

Angular Velocity, revolution per minute.

BLE_GATT_UNIT_ENERGY_GRAM_CALORIE 

Energy, gram calorie.

BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE 

Energy, kilogram calorie.

BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR 

Energy, killowatt hour.

BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_FAHRENHEIT 

Thermodynamic temperature, degree Fahrenheit.

BLE_GATT_UNIT_PERCENTAGE 

Percentage.

BLE_GATT_UNIT_PER_MILLE 

Per mille.

BLE_GATT_UNIT_PERIOD_BEATS_PER_MINUTE 

Period, beats per minute.

BLE_GATT_UNIT_ELECTRIC_CHARGE_AMPERE_HOURS 

Electric charge, ampere hours.

BLE_GATT_UNIT_MASS_DENSITY_MILLIGRAM_PER_DECILITRE 

Mass density, milligram per deciliter.

BLE_GATT_UNIT_MASS_DENSITY_MILLIMOLE_PER_LITRE 

Mass density, millimole per liter.

BLE_GATT_UNIT_TIME_YEAR 

Time, year.

BLE_GATT_UNIT_TIME_MONTH 

Time, month.

BLE_GATT_UNIT_CONCENTRATION_COUNT_PER_CUBIC_METRE 

Concentration, count per cubic meter.

BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE 

Irradiance, watt per square meter.

Definition at line 535 of file gatt/GattCharacteristic.h.

anonymous enum

Presentation format of a characteristic.

It determines how the value of a characteristic is formatted. A server can expose that information to its clients by adding a Characteristic Presentation Format descriptor to relevant characteristics.

Note
See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2.
Enumerator
BLE_GATT_FORMAT_RFU 

Reserved for future use.

BLE_GATT_FORMAT_BOOLEAN 

Boolean.

BLE_GATT_FORMAT_2BIT 

Unsigned 2-bit integer.

BLE_GATT_FORMAT_NIBBLE 

Unsigned 4-bit integer.

BLE_GATT_FORMAT_UINT8 

Unsigned 8-bit integer.

BLE_GATT_FORMAT_UINT12 

Unsigned 12-bit integer.

BLE_GATT_FORMAT_UINT16 

Unsigned 16-bit integer.

BLE_GATT_FORMAT_UINT24 

Unsigned 24-bit integer.

BLE_GATT_FORMAT_UINT32 

Unsigned 32-bit integer.

BLE_GATT_FORMAT_UINT48 

Unsigned 48-bit integer.

BLE_GATT_FORMAT_UINT64 

Unsigned 64-bit integer.

BLE_GATT_FORMAT_UINT128 

Unsigned 128-bit integer.

BLE_GATT_FORMAT_SINT8 

Signed 8-bit integer.

BLE_GATT_FORMAT_SINT12 

Signed 12-bit integer.

BLE_GATT_FORMAT_SINT16 

Signed 16-bit integer.

BLE_GATT_FORMAT_SINT24 

Signed 24-bit integer.

BLE_GATT_FORMAT_SINT32 

Signed 32-bit integer.

BLE_GATT_FORMAT_SINT48 

Signed 48-bit integer.

BLE_GATT_FORMAT_SINT64 

Signed 64-bit integer.

BLE_GATT_FORMAT_SINT128 

Signed 128-bit integer.

BLE_GATT_FORMAT_FLOAT32 

IEEE-754 32-bit floating point.

BLE_GATT_FORMAT_FLOAT64 

IEEE-754 64-bit floating point.

BLE_GATT_FORMAT_SFLOAT 

IEEE-11073 16-bit SFLOAT.

BLE_GATT_FORMAT_FLOAT 

IEEE-11073 32-bit FLOAT.

BLE_GATT_FORMAT_DUINT16 

IEEE-20601 format.

BLE_GATT_FORMAT_UTF8S 

UTF8 string.

BLE_GATT_FORMAT_UTF16S 

UTF16 string.

BLE_GATT_FORMAT_STRUCT 

Opaque Structure.

Definition at line 1092 of file gatt/GattCharacteristic.h.

Characteristic properties.

It is a bitfield that determines how a characteristic value can be used.

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

No property defined.

BLE_GATT_CHAR_PROPERTIES_BROADCAST 

Permits broadcasts of the characteristic value using the Server Characteristic Configuration descriptor.

BLE_GATT_CHAR_PROPERTIES_READ 

Permits reads of the characteristic value.

BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE 

Permits writes of the characteristic value without response.

BLE_GATT_CHAR_PROPERTIES_WRITE 

Permits writes of the characteristic value with response.

BLE_GATT_CHAR_PROPERTIES_NOTIFY 

Permits notifications of a characteristic value without acknowledgment.

BLE_GATT_CHAR_PROPERTIES_INDICATE 

Permits indications of a characteristic value with acknowledgment.

BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES 

Permits signed writes to the characteristic value.

BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES 

The Characteristic Extended Properties descriptor defines additional characteristic properties.

Definition at line 1242 of file gatt/GattCharacteristic.h.

Constructor & Destructor Documentation

GattCharacteristic ( const UUID uuid,
uint8_t *  valuePtr = nullptr,
uint16_t  len = 0,
uint16_t  maxLen = 0,
uint8_t  props = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute descriptors[] = nullptr,
unsigned  numDescriptors = 0,
bool  hasVariableLen = true 
)

Constructs a new GattCharacteristic.

Parameters
[in]uuidThe UUID of this characteristic.
[in]valuePtrMemory buffer holding the initial value. The value is copied into the Bluetooth subsytem when the enclosing service is added. Thereafter, the stack maintains it internally.
[in]lenThe length in bytes of this characteristic's value.
[in]maxLenThe capacity in bytes of the characteristic value buffer.
[in]propsAn 8-bit field that contains the characteristic's properties.
[in]descriptorsA pointer to an array of descriptors to be included within this characteristic. The caller owns the memory for the descriptor array, which must remain valid at least until the enclosing service is added to the GATT table.
[in]numDescriptorsThe number of descriptors presents in descriptors array.
[in]hasVariableLenFlag that indicates if the attribute's value length can change throughout time.
Note
If valuePtr is nullptr, length is equal to 0 and the characteristic is readable, then that particular characteristic may be considered optional and dropped while instantiating the service with the underlying BLE stack.
A Client Characteristic Configuration Descriptor (CCCD) should not be allocated if either the notify or indicate flag in the props bit field; the underlying BLE stack handles it.
Attention
GattCharacteristic registered in a GattServer must remain valid for the lifetime of the GattServer.

Definition at line 1409 of file gatt/GattCharacteristic.h.

Member Function Documentation

Invoke the read authorization callback.

This function is a helper that calls the registered read handler to determine the authorization reply for a read request.

Attention
This function is not meant to be called by user code.
Parameters
[in,out]paramsContext of the read-auth request; it contains an out-parameter used as a reply and the handler can fill it with outgoing data. The params->data provides a pointer to the data and params->len provides the length of this data. params->len is also used to pass the maximum size of data that the params->data can contain. If you set the params->len to a value larger than the passed in value the read operation will fail.
Returns
A GattAuthCallbackReply_t value indicating whether authorization is granted.
Note
If the read is approved, the event handler can specify an outgoing value directly with the help of the fields params->data and params->len.
If the read request is approved and params->data remains nullptr, then the current characteristic value is used in the read response payload.
The params->len parameter initially contains the maximum length of data that can be returned. Set it to the length of your data but it must not be larger than the original value.
You must also take into account the offset provided in params->offset. The params->len you provide must be larger then the offset as the read operation will attempt to read at that offset.

Definition at line 1700 of file gatt/GattCharacteristic.h.

Invoke the write authorization callback.

This function is a helper that calls the registered write handler to determine the authorization reply for a write request.

Attention
This function is not meant to be called by user code.
Parameters
[in]paramsContext of the write-auth request; it contains an out-parameter used as a reply.
Returns
A GattAuthCallbackReply_t value indicating whether authorization is granted.

Definition at line 1655 of file gatt/GattCharacteristic.h.

GattAttribute* getDescriptor ( uint8_t  index)

Get this characteristic's descriptor at a specific index.

Parameters
[in]indexThe index of the descriptor to get.
Returns
A pointer the requested descriptor if index is within the range of the descriptor array or nullptr otherwise.
Note
if this characteristic has an implicitly-created CCCD this descriptor will be available at the highest index (ie: return of getDescriptorCount() - 1)

Definition at line 1806 of file gatt/GattCharacteristic.h.

uint8_t getDescriptorCount ( ) const

Get the total number of descriptors within this characteristic.

Returns
The total number of descriptors.

Definition at line 1763 of file gatt/GattCharacteristic.h.

uint8_t getProperties ( ) const

Get the characteristic's properties.

Note
Refer to GattCharacteristic::Properties_t.
Returns
The characteristic's properties.

Definition at line 1753 of file gatt/GattCharacteristic.h.

const FunctionPointerWithContext<GattReadAuthCallbackParams *>& getReadAuthorizationCallback ( ) const

Return the callback registered to handle client's read.

Returns
the callback that handles client's read requests.

Definition at line 1636 of file gatt/GattCharacteristic.h.

SecurityRequirement_t getReadSecurityRequirement ( ) const

Get the security requirement of the read operation.

Returns
The security requirement of the read operation.

Definition at line 1481 of file gatt/GattCharacteristic.h.

SecurityRequirement_t getUpdateSecurityRequirement ( ) const

Get the security requirement of update operations.

Note
This security requirement is also applied to the write operation of the Client Characteristic Configuration Descriptor.
Returns
The security requirement that must be met to send updates and accept write of the CCCD.

Definition at line 1541 of file gatt/GattCharacteristic.h.

GattAttribute& getValueAttribute ( )

Get the characteristic's value attribute.

Returns
A reference to the characteristic's value attribute.

Definition at line 1718 of file gatt/GattCharacteristic.h.

const GattAttribute& getValueAttribute ( ) const

Get the characteristic's value attribute.

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

Definition at line 1728 of file gatt/GattCharacteristic.h.

GattAttribute::Handle_t getValueHandle ( ) const

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

Returns
The value attribute handle.
Note
The underlying BLE stack assigns the attribute handle when the enclosing service is added.

Definition at line 1741 of file gatt/GattCharacteristic.h.

const FunctionPointerWithContext<GattWriteAuthCallbackParams *>& getWriteAuthorizationCallback ( ) const

Return the callback registered to handle client's write.

Returns
the callback that handles client's write requests.

Definition at line 1588 of file gatt/GattCharacteristic.h.

SecurityRequirement_t getWriteSecurityRequirement ( ) const

Get the security requirement of write operations.

Returns
The security requirement of write operations.

Definition at line 1513 of file gatt/GattCharacteristic.h.

static bool isReadable ( uint8_t  properties)
static

Indicates if the properties is readable.

Parameters
[in]propertiesThe properties to inspect.
Returns
True if the properties has its readable flag set and false otherwise.

Definition at line 1317 of file gatt/GattCharacteristic.h.

bool isReadAuthorizationEnabled ( ) const

Check whether read authorization is enabled.

Read authorization is enabled when a read authorization event handler is set up.

Returns
true if read authorization is enabled and false otherwise.

Definition at line 1776 of file gatt/GattCharacteristic.h.

static bool isWritable ( uint8_t  properties)
static

Indicates if the properties has at least one of the writable flags.

Parameters
[in]propertiesThe properties to inspect.
Returns
True if the properties set at least one of the writable flags and false otherwise.

Definition at line 1299 of file gatt/GattCharacteristic.h.

bool isWriteAuthorizationEnabled ( ) const

Check whether write authorization is enabled.

Write authorization is enabled when a write authorization event handler is set up.

Returns
true if write authorization is enabled, false otherwise.

Definition at line 1789 of file gatt/GattCharacteristic.h.

void setReadAuthorizationCallback ( void(*)(GattReadAuthCallbackParams *)  callback)

Register the read requests event handler.

The callback registered is invoked when the client attempts to read the characteristic value; the event handler can accept or reject the read request with the appropriate error code. It can also set specific outgoing data.

Parameters
[in]callbackEvent handler being registered.

Definition at line 1603 of file gatt/GattCharacteristic.h.

void setReadAuthorizationCallback ( T *  object,
void(T::*)(GattReadAuthCallbackParams *)  member 
)

Register the read requests event handler.

The callback registered is invoked when the client attempts to read the characteristic value; the event handler can accept or reject the read request with the appropriate error code. It can also set specific outgoing data.

Parameters
[in]objectPointer to the object of a class defining the event handler (member). It must remain valid for the lifetime of the GattCharacteristic.
[in]memberThe member function that handles the read event.

Definition at line 1623 of file gatt/GattCharacteristic.h.

void setReadSecurityRequirement ( SecurityRequirement_t  security)

Set the security of the read operation.

Parameters
[in]securityThe security requirement of the read operation.

Definition at line 1471 of file gatt/GattCharacteristic.h.

void setSecurityRequirements ( SecurityRequirement_t  read_security,
SecurityRequirement_t  write_security,
SecurityRequirement_t  update_security 
)

Set all security requirements of the characteristic.

Parameters
read_securityThe security requirement of the read operations.
write_securityThe security requirement of write operations.
update_securityThe security requirement of update operations.

Definition at line 1456 of file gatt/GattCharacteristic.h.

void setUpdateSecurityRequirement ( SecurityRequirement_t  security)

Set the security requirement of update operations.

Note
This security requirement is also applied to the write operation of the Client Characteristic Configuration Descriptor.
Parameters
[in]securityThe security requirement that must be met to send updates and accept write of the CCCD.

Definition at line 1527 of file gatt/GattCharacteristic.h.

void setWriteAuthorizationCallback ( void(*)(GattWriteAuthCallbackParams *)  callback)

Register a callback handling client's write requests or commands.

The callback registered is invoked when the client attempts to write the characteristic value; the event handler can accept or reject the write request with the appropriate error code.

Parameters
[in]callbackEvent handler being registered.

Definition at line 1556 of file gatt/GattCharacteristic.h.

void setWriteAuthorizationCallback ( T *  object,
void(T::*)(GattWriteAuthCallbackParams *)  member 
)

Register a callback handling client's write requests or commands.

The callback registered is invoked when the client attempts to write the characteristic value; the event handler can accept or reject the write request with the appropriate error code.

Parameters
[in]objectPointer to the object of a class defining the event handler (member). It must remain valid for the lifetime of the GattCharacteristic.
[in]memberThe member function that handles the write event.

Definition at line 1575 of file gatt/GattCharacteristic.h.

void setWriteSecurityRequirement ( SecurityRequirement_t  security)

Set the security requirement of the write operations.

Note
If the signed write flag is set in the characteristic properties then the security requirement applied to write operation must be either AUTHENTICATED or UNAUTHENTICATED. Security requirements NONE and SC_AUTHENTICATED are not applicable to signing operation.
Parameters
[in]securityThe security requirement of write operations.

Definition at line 1496 of file gatt/GattCharacteristic.h.

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.