Rtos API example
GattCharacteristic Class Reference
[Server]
Representation of a GattServer characteristic. More...
#include <GattCharacteristic.h>
Inherited by 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< PowerLevels_t >, ReadWriteGattCharacteristic< uint16_t >, ReadWriteGattCharacteristic< uint8_t >, WriteOnlyArrayGattCharacteristic< T, NUM_ELEMENTS >, WriteOnlyArrayGattCharacteristic< uint8_t, SIZEOF_CONTROL_BYTES >, WriteOnlyGattCharacteristic< T >, WriteOnlyGattCharacteristic< Lock_t >, and WriteOnlyGattCharacteristic< uint8_t >.
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.
Representation of a GattServer characteristic.
A characteristic is a typed value used in a service. It contains a set of properties that define client operations supported by the characteristic. A characteristic may also include descriptors; a descriptor exposes metainformation associated to a characteristic, such as the unit of its value, its human readable name or a control point attribute that allows the client to subscribe to the characteristic notifications.
The GattCharacteristic class allows application code to construct and monitor characteristics presents in a GattServer.
Definition at line 95 of file 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 101 of file 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.
- Enumerator:
Definition at line 525 of file 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:
Definition at line 1082 of file 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:
Definition at line 1232 of file GattCharacteristic.h.
Constructor & Destructor Documentation
GattCharacteristic | ( | const UUID & | uuid, |
uint8_t * | valuePtr = NULL , |
||
uint16_t | len = 0 , |
||
uint16_t | maxLen = 0 , |
||
uint8_t | props = BLE_GATT_CHAR_PROPERTIES_NONE , |
||
GattAttribute * | descriptors[] = NULL , |
||
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 NULL, 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.
GattCharacteristic registered in a GattServer must remain valid for the lifetime of the GattServer.
Definition at line 1363 of file 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.
This function is not meant to be called by user code.
- Parameters:
-
[in] 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.
- Returns:
- A GattAuthCallbackReply_t value indicating whether authorization is granted.
- Note:
- If the read request is approved and params->data remains NULL, then the current characteristic value is used in the read response payload.
- If the read is approved, the event handler can specify an outgoing value directly with the help of the fields GattReadAuthCallbackParams::data and GattReadAuthCallbackParams::len.
Definition at line 1521 of file 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.
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 1487 of file 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 NULL otherwise.
Definition at line 1633 of file GattCharacteristic.h.
uint8_t getDescriptorCount | ( | void | ) | const |
Get the total number of descriptors within this characteristic.
- Returns:
- The total number of descriptors.
Definition at line 1594 of file GattCharacteristic.h.
uint8_t getProperties | ( | void | ) | const |
Get the characteristic's properties.
- Note:
- Refer to GattCharacteristic::Properties_t.
- Returns:
- The characteristic's properties.
Definition at line 1574 of file GattCharacteristic.h.
SecurityManager::SecurityMode_t getRequiredSecurity | ( | ) | const |
Get the characteristic's required security.
- Returns:
- The characteristic's required security.
Definition at line 1584 of file 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 1549 of file GattCharacteristic.h.
GattAttribute& getValueAttribute | ( | ) |
Get the characteristic's value attribute.
- Returns:
- A reference to the characteristic's value attribute.
Definition at line 1539 of file GattCharacteristic.h.
GattAttribute::Handle_t getValueHandle | ( | void | ) | 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 1562 of file 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 1607 of file 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 1620 of file GattCharacteristic.h.
void requireSecurity | ( | SecurityManager::SecurityMode_t | securityMode ) |
Set up the minimum security (mode and level) requirements for access to the characteristic's value attribute.
- Parameters:
-
[in] securityMode Can be one of encryption or signing, with or without protection for man in the middle attacks (MITM).
Definition at line 1391 of file 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 1465 of file 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 1444 of file 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 1406 of file 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 1426 of file GattCharacteristic.h.
Generated on Sun Jul 17 2022 08:25:40 by 1.7.2