Representation of a GattServer characteristic. More...

#include <GattCharacteristic.h>

Inheritance diagram for GattCharacteristic:

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...

GattAttribute &	getValueAttribute ()
	Get the characteristic's value attribute. More...

const GattAttribute &	getValueAttribute () 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...

GattAttribute *	getDescriptor (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):

Characteristic declaration: It contains the properties of the characteristic, its type and the handle of its value.
Characteristic value: The value of the characteristic.
Descriptors: A single GATT attribute stores each descriptor.

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

typedef ble::att_security_requirement_t SecurityRequirement_t

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.

enum Properties_t

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]	uuid	The UUID of this characteristic.
[in]	valuePtr	Memory 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]	len	The length in bytes of this characteristic's value.
[in]	maxLen	The capacity in bytes of the characteristic value buffer.
[in]	props	An 8-bit field that contains the characteristic's properties.
[in]	descriptors	A 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]	numDescriptors	The number of descriptors presents in `descriptors` array.
[in]	hasVariableLen	Flag 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

GattAuthCallbackReply_t authorizeRead ( GattReadAuthCallbackParams * params )

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] params Context 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.

GattAuthCallbackReply_t authorizeWrite ( GattWriteAuthCallbackParams * params )

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] params Context 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] index The 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] properties The 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] properties The 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] callback Event 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]	object	Pointer to the object of a class defining the event handler (`member`). It must remain valid for the lifetime of the GattCharacteristic.
[in]	member	The 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] security The 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_security	The security requirement of the read operations.
write_security	The security requirement of write operations.
update_security	The 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] security The 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] callback Event 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]	object	Pointer to the object of a class defining the event handler (`member`). It must remain valid for the lifetime of the GattCharacteristic.
[in]	member	The 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] security The security requirement of write operations.

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

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Important Information for this Arm website