GattCharacteristic.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __GATT_CHARACTERISTIC_H__
00018 #define __GATT_CHARACTERISTIC_H__
00019 
00020 #include "Gap.h"
00021 #include "SecurityManager.h"
00022 #include "GattAttribute.h"
00023 #include "GattCallbackParamTypes.h"
00024 #include "FunctionPointerWithContext.h "
00025 
00026 /**
00027  * @addtogroup ble
00028  * @{
00029  * @addtogroup gatt
00030  * @{
00031  * @addtogroup server
00032  * @{
00033  */
00034 
00035 /**
00036  * Representation of a GattServer characteristic.
00037  *
00038  * A characteristic is a typed value enclosed in a GATT service (GattService).
00039  *
00040  * @par Type
00041  *
00042  * The type of the value defines the purpose of the characteristic, and a
00043  * UUID represents it. Standard characteristic types may be consulted at
00044  * https://www.bluetooth.com/specifications/gatt/characteristics
00045  *
00046  * @par Supported operations
00047  * A set of properties define what client operations the characteristic
00048  * supports. See GattServer::Properties_t
00049  *
00050  * @par Descriptors
00051  *
00052  * Additional information, such as the unit of the characteristic value, a
00053  * description string or a client control point, can be added to the
00054  * characteristic.
00055  *
00056  * See BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part G] - 3.3.1.1
00057  *
00058  * One of the most important types of descriptor is the Client Characteristic
00059  * Configuration Descriptor (CCCD) that must be present if the characteristic
00060  * properties allow a client to subscribe to updates of the characteristic
00061  * value.
00062  *
00063  * @par Characteristic breakdown
00064  *
00065  * A characteristic is composed of several GATT attributes (GattAttribute):
00066  *   - Characteristic declaration: It contains the properties of the
00067  *     characteristic, its type and the handle of its value.
00068  *   - Characteristic value: The value of the characteristic.
00069  *   - Descriptors: A single GATT attribute stores each descriptor.
00070  *
00071  * When the GattService containing the characteristic is registered in the
00072  * GattServer, a unique attribute handle is assigned to the various attributes
00073  * of the characteristic. Clients use this handle to interact with the
00074  * characteristic. This handle is used locally in GattServer APIs.
00075  *
00076  * @par Security requirements
00077  *
00078  * Verification of security requirements happens whenever a client request to
00079  * read the characteristic; write it or even register to its updates. Different
00080  * requirements may be defined for these three type of operation. As an example:
00081  * it is possible to define a characteristic that do not require security to be
00082  * read and require an authenticated link to be written.
00083  *
00084  * By default all security requirements are set to att_security_requirement_t::NONE
00085  * except if the characteristic supports signed write; in such case the security
00086  * requirement for write operations is set to att_security_requirement_t::UNAUTHENTICATED.
00087  *
00088  * @note If a peer uses an operation that is not set in the characteristic
00089  * properties then the request request is discarded regardless of the security
00090  * requirements and current security level. The only exception being signed
00091  * write: signed write are converted into regular write without response if
00092  * the link is encrypted.
00093  */
00094 class GattCharacteristic {
00095 public:
00096 
00097     /*
00098      * Enumeration of characteristic UUID defined by the Bluetooth body.
00099      */
00100     enum {
00101         /**
00102          * Not used in actual BLE service.
00103          */
00104         UUID_BATTERY_LEVEL_STATE_CHAR = 0x2A1B,
00105 
00106         /**
00107          * Not used in actual BLE service.
00108          */
00109         UUID_BATTERY_POWER_STATE_CHAR = 0x2A1A,
00110 
00111         /**
00112          * Not used in actual BLE service.
00113          */
00114         UUID_REMOVABLE_CHAR = 0x2A3A,
00115 
00116         /**
00117          * Not used in actual BLE service.
00118          */
00119         UUID_SERVICE_REQUIRED_CHAR = 0x2A3B,
00120 
00121         /**
00122          * Not used as a characteristic UUID.
00123          */
00124         UUID_ALERT_CATEGORY_ID_CHAR = 0x2A43,
00125 
00126         /**
00127          * Not used as a characteristic UUID.
00128          */
00129         UUID_ALERT_CATEGORY_ID_BIT_MASK_CHAR = 0x2A42,
00130 
00131         /**
00132          * Control point of the Immediate Alert service that allows the client to
00133          * command the server to alert to a given level.
00134          */
00135         UUID_ALERT_LEVEL_CHAR = 0x2A06,
00136 
00137         /**
00138          * Control point of the Alert Notification service that allows the client
00139          * finely tune the notification configuration.
00140          */
00141         UUID_ALERT_NOTIFICATION_CONTROL_POINT_CHAR = 0x2A44,
00142 
00143         /**
00144          * Part of the Alert Notification service, which exposes the count of
00145          * unread alert events existing in the server.
00146          */
00147         UUID_ALERT_STATUS_CHAR = 0x2A3F,
00148 
00149         /**
00150          * Characteristic of the Battery service, which exposes the current
00151          * battery level as a percentage.
00152          */
00153         UUID_BATTERY_LEVEL_CHAR = 0x2A19,
00154 
00155         /**
00156          * Describe the features supported by the blood pressure sensor exposed
00157          * by the Blood Pressure service.
00158          */
00159         UUID_BLOOD_PRESSURE_FEATURE_CHAR = 0x2A49,
00160 
00161         /**
00162          * Characteristic of the Blood Pressure service that exposes the
00163          * measurement of the blood sensor.
00164          */
00165         UUID_BLOOD_PRESSURE_MEASUREMENT_CHAR = 0x2A35,
00166 
00167         /**
00168          * Characteristic of the Heart Rate service that indicate the intended
00169          * location of the heart rate monitor.
00170          */
00171         UUID_BODY_SENSOR_LOCATION_CHAR = 0x2A38,
00172 
00173         /**
00174          * Part of the Human Interface Device service.
00175          */
00176         UUID_BOOT_KEYBOARD_INPUT_REPORT_CHAR = 0x2A22,
00177 
00178         /**
00179          * Part of the Human Interface Device service.
00180          */
00181         UUID_BOOT_KEYBOARD_OUTPUT_REPORT_CHAR = 0x2A32,
00182 
00183         /**
00184          * Part of the Human Interface Device service.
00185          */
00186         UUID_BOOT_MOUSE_INPUT_REPORT_CHAR = 0x2A33,
00187 
00188         /**
00189          * Characteristic of the Current Time service that contains the current
00190          * time.
00191          */
00192         UUID_CURRENT_TIME_CHAR = 0x2A2B,
00193 
00194         /**
00195          * Not used in a service as a characteristic.
00196          */
00197         UUID_DATE_TIME_CHAR = 0x2A08,
00198 
00199         /**
00200          * Not used in a service as a characteristic.
00201          */
00202         UUID_DAY_DATE_TIME_CHAR = 0x2A0A,
00203 
00204         /**
00205          * Not used in a service as a characteristic.
00206          */
00207         UUID_DAY_OF_WEEK_CHAR = 0x2A09,
00208 
00209         /**
00210          * Not used in a service as a characteristic.
00211          */
00212         UUID_DST_OFFSET_CHAR = 0x2A0D,
00213 
00214         /**
00215          * Not used in a service as a characteristic.
00216          */
00217         UUID_EXACT_TIME_256_CHAR = 0x2A0C,
00218 
00219         /**
00220          * Characteristic of the Device Information Service that contains a
00221          * UTF8 string representing the firmware revision for the firmware within
00222          * the device.
00223          */
00224         UUID_FIRMWARE_REVISION_STRING_CHAR = 0x2A26,
00225 
00226         /**
00227          * Characteristic of the Glucose service that exposes features supported
00228          * by the server.
00229          */
00230         UUID_GLUCOSE_FEATURE_CHAR = 0x2A51,
00231 
00232         /**
00233          * Characteristic of the Glucose service that exposes glucose
00234          * measurements.
00235          */
00236         UUID_GLUCOSE_MEASUREMENT_CHAR = 0x2A18,
00237 
00238         /**
00239          * Characteristic of the Glucose service that sends additional
00240          * information related to the glucose measurements.
00241          */
00242         UUID_GLUCOSE_MEASUREMENT_CONTEXT_CHAR = 0x2A34,
00243 
00244         /**
00245          * Characteristic of the Device Information Service that contains a
00246          * UTF8 string representing the hardware revision of the device.
00247          */
00248         UUID_HARDWARE_REVISION_STRING_CHAR = 0x2A27,
00249 
00250         /**
00251          * Characteristic of the Heart Rate service used by the client to control
00252          * the service behavior.
00253          */
00254         UUID_HEART_RATE_CONTROL_POINT_CHAR = 0x2A39,
00255 
00256         /**
00257          * Characteristic of the Heart Rate that sends heart rate measurements to
00258          * registered clients.
00259          */
00260         UUID_HEART_RATE_MEASUREMENT_CHAR = 0x2A37,
00261 
00262         /**
00263          * Part of the Human Interface Device service.
00264          */
00265         UUID_HID_CONTROL_POINT_CHAR = 0x2A4C,
00266 
00267         /**
00268          * Part of the Human Interface Device service.
00269          */
00270         UUID_HID_INFORMATION_CHAR = 0x2A4A,
00271 
00272         /**
00273          * Characteristic of the Environmental Sensing service, which exposes
00274          * humidity measurements.
00275          */
00276         UUID_HUMIDITY_CHAR = 0x2A6F,
00277 
00278         /**
00279          * Characteristic of the Device Information Service, which exposes
00280          * various regulatory or certification compliance items to which the
00281          * device claims adherence.
00282          */
00283         UUID_IEEE_REGULATORY_CERTIFICATION_DATA_LIST_CHAR = 0x2A2A,
00284 
00285         /**
00286          * Characteristic of the Blood Pressure service, which exposes intermediate
00287          * cuff pressure measurements.
00288          */
00289         UUID_INTERMEDIATE_CUFF_PRESSURE_CHAR = 0x2A36,
00290 
00291         /**
00292          * Characteristic of the Health Thermometer service that sends intermediate
00293          * temperature values while the measurement is in progress.
00294          */
00295         UUID_INTERMEDIATE_TEMPERATURE_CHAR = 0x2A1E,
00296 
00297         /**
00298          * Characteristic of the current Time service that exposes information
00299          * about the local time.
00300          */
00301         UUID_LOCAL_TIME_INFORMATION_CHAR = 0x2A0F,
00302 
00303         /**
00304          * Characteristic of the Device Information Service that contains a
00305          * UTF8 string representing the manufacturer name of the device.
00306          */
00307         UUID_MANUFACTURER_NAME_STRING_CHAR = 0x2A29,
00308 
00309         /**
00310          * Characteristic of the Health Thermometer service that exposes the
00311          * interval time between two measurements.
00312          */
00313         UUID_MEASUREMENT_INTERVAL_CHAR = 0x2A21,
00314 
00315         /**
00316          * Characteristic of the Device Information Service that contains a
00317          * UTF8 string representing the model number of the device assigned by
00318          * the vendor.
00319          */
00320         UUID_MODEL_NUMBER_STRING_CHAR = 0x2A24,
00321 
00322         /**
00323          * Characteristic of the Alert Notification Service that shows how many
00324          * numbers of unread alerts exist in the specific category in the device.
00325          */
00326         UUID_UNREAD_ALERT_CHAR = 0x2A45,
00327 
00328         /**
00329          * Characteristic of the Alert Notification Service that defines the
00330          * category of the alert and how many new alerts of that category have
00331          * occurred in the server.
00332          */
00333         UUID_NEW_ALERT_CHAR = 0x2A46,
00334 
00335         /**
00336          * Characteristic of the Device Information Service; it is a set of
00337          * values used to create a device ID that is unique for this device.
00338          */
00339         UUID_PNP_ID_CHAR = 0x2A50,
00340 
00341         /**
00342          * Characteristic of the Environmental Sensing Service that exposes the
00343          * pressure measured.
00344          */
00345         UUID_PRESSURE_CHAR = 0x2A6D,
00346 
00347         /**
00348          * Part of the Human Interface Device service.
00349          */
00350         UUID_PROTOCOL_MODE_CHAR = 0x2A4E,
00351 
00352         /**
00353          * Pulse Oxymeter, Glucose and Continuous Glucose Monitoring services
00354          * use this control point to provide basic management of the patient
00355          * record database.
00356          */
00357         UUID_RECORD_ACCESS_CONTROL_POINT_CHAR = 0x2A52,
00358 
00359         /**
00360          * Characteristic of the Current Time service that exposes information
00361          * related to the current time served (accuracy, source, hours since
00362          * update and so on).
00363          */
00364         UUID_REFERENCE_TIME_INFORMATION_CHAR = 0x2A14,
00365 
00366         /**
00367          * Part of the Human Interface Device service.
00368          */
00369         UUID_REPORT_CHAR = 0x2A4D,
00370 
00371         /**
00372          * Part of the Human Interface Device service.
00373          */
00374         UUID_REPORT_MAP_CHAR = 0x2A4B,
00375 
00376         /**
00377          * Characteristic of the Phone Alert Status service that allows a client
00378          * to configure operating mode.
00379          */
00380         UUID_RINGER_CONTROL_POINT_CHAR = 0x2A40,
00381 
00382         /**
00383          * Characteristic of the Phone Alert Status service that returns the
00384          * ringer setting when read.
00385          */
00386         UUID_RINGER_SETTING_CHAR = 0x2A41,
00387 
00388         /**
00389          * Characteristic of the Scan Parameter service that stores the client's
00390          * scan parameters (scan interval and scan window).
00391          */
00392         UUID_SCAN_INTERVAL_WINDOW_CHAR = 0x2A4F,
00393 
00394         /**
00395          * Characteristic of the Scan Parameter service that sends a notification
00396          * to a client when the server requires its latest scan parameters.
00397          */
00398         UUID_SCAN_REFRESH_CHAR = 0x2A31,
00399 
00400         /**
00401          * Characteristic of the Device Information Service that contains a
00402          * UTF8 string representing the serial number of the device.
00403          */
00404         UUID_SERIAL_NUMBER_STRING_CHAR = 0x2A25,
00405 
00406         /**
00407          * Characteristic of the Device Information Service that contains an
00408          * UTF8 string representing the software revision of the device.
00409          */
00410         UUID_SOFTWARE_REVISION_STRING_CHAR = 0x2A28,
00411 
00412         /**
00413          * Characteristic of the Alert Notification Service that notifies the
00414          * count of new alerts for a given category to a subscribed client.
00415          */
00416         UUID_SUPPORTED_NEW_ALERT_CATEGORY_CHAR = 0x2A47,
00417 
00418         /**
00419          * Characteristic of the Alert Notification service, which exposes
00420          * categories of unread alert supported by the server.
00421          */
00422         UUID_SUPPORTED_UNREAD_ALERT_CATEGORY_CHAR = 0x2A48,
00423 
00424         /**
00425          * Characteristic of the Device Information Service that exposes a
00426          * structure containing an Organizationally Unique Identifier (OUI)
00427          * followed by a manufacturer-defined identifier. The value of the
00428          * structure is unique for each individual instance of the product.
00429          */
00430         UUID_SYSTEM_ID_CHAR = 0x2A23,
00431 
00432         /**
00433          * Characteristic of the Environmental Sensing service that exposes the
00434          * temperature measurement with a resolution of 0.01 degree Celsius.
00435          */
00436         UUID_TEMPERATURE_CHAR = 0x2A6E,
00437 
00438         /**
00439          * Characteristic of the Health Thermometer service that sends temperature
00440          * measurement to clients.
00441          */
00442         UUID_TEMPERATURE_MEASUREMENT_CHAR = 0x2A1C,
00443 
00444         /**
00445          * Characteristic of the Health Thermometer service that describes
00446          * where the measurement takes place.
00447          */
00448         UUID_TEMPERATURE_TYPE_CHAR = 0x2A1D,
00449 
00450         /**
00451          * Not used in a service as a characteristic.
00452          */
00453         UUID_TIME_ACCURACY_CHAR = 0x2A12,
00454 
00455         /**
00456          * Not used in a service as a characteristic.
00457          */
00458         UUID_TIME_SOURCE_CHAR = 0x2A13,
00459 
00460         /**
00461          * Characteristic of the Reference Time service that allows clients to
00462          * control time update.
00463          */
00464         UUID_TIME_UPDATE_CONTROL_POINT_CHAR = 0x2A16,
00465 
00466         /**
00467          * Characteristic of the Reference Time service that informs clients of
00468          * the status of the time update operation.
00469          */
00470         UUID_TIME_UPDATE_STATE_CHAR = 0x2A17,
00471 
00472         /**
00473          * Characteristic of the Next DST Change service that returns to clients
00474          * the time with DST.
00475          */
00476         UUID_TIME_WITH_DST_CHAR = 0x2A11,
00477 
00478         /**
00479          * Not used in a service as a characteristic.
00480          */
00481         UUID_TIME_ZONE_CHAR = 0x2A0E,
00482 
00483         /**
00484          * Characteristic of the TX Power service that exposes the current
00485          * transmission power in dBm.
00486          */
00487         UUID_TX_POWER_LEVEL_CHAR = 0x2A07,
00488 
00489         /**
00490          * Characteristic of the Cycling Speed and Cadence (CSC) service that
00491          * exposes features supported by the server.
00492          */
00493         UUID_CSC_FEATURE_CHAR = 0x2A5C,
00494 
00495         /**
00496          * Characteristic of the Cycling Speed and Cadence (CSC) service that
00497          * exposes measurements made by the server.
00498          */
00499         UUID_CSC_MEASUREMENT_CHAR = 0x2A5B,
00500 
00501         /**
00502          * Characteristic of the Running Speed and Cadence (RSC) service that
00503          * exposes features supported by the server.
00504          */
00505         UUID_RSC_FEATURE_CHAR = 0x2A54,
00506 
00507         /**
00508          * Characteristic of the Running Speed and Cadence (RSC) service that
00509          * exposes measurements made by the server.
00510          */
00511         UUID_RSC_MEASUREMENT_CHAR = 0x2A53
00512     };
00513 
00514     /**
00515      * Unit type of a characteristic value.
00516      *
00517      * These unit types are used to describe what the raw numeric data in a
00518      * characteristic actually represents. A server can expose that information
00519      * to its clients by adding a Characteristic Presentation Format descriptor
00520      * to relevant characteristics.
00521      *
00522      * @note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx
00523      */
00524     enum {
00525 
00526         /**
00527          * No specified unit type.
00528          */
00529         BLE_GATT_UNIT_NONE = 0x2700,
00530 
00531         /**
00532          * Length, meter.
00533          */
00534         BLE_GATT_UNIT_LENGTH_METRE = 0x2701,
00535 
00536         /**
00537          * Mass, kilogram.
00538          */
00539         BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702,
00540 
00541         /**
00542          * Time, second.
00543          */
00544         BLE_GATT_UNIT_TIME_SECOND = 0x2703,
00545 
00546         /**
00547          * Electric current, ampere.
00548          */
00549         BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704,
00550 
00551         /**
00552          * Thermodynamic temperature, kelvin.
00553          */
00554         BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705,
00555 
00556         /** Amount of substance, mole.
00557          *
00558         */
00559         BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706,
00560 
00561         /**
00562          * Luminous intensity, candela.
00563          */
00564         BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707,
00565 
00566         /**
00567          * Area, square meters.
00568          */
00569         BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710,
00570 
00571         /**
00572          * Volume, cubic meters.
00573          */
00574         BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711,
00575 
00576         /**
00577          * Velocity, meters per second.
00578          */
00579         BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712,
00580 
00581         /**
00582          * Acceleration, meters per second squared.
00583          */
00584         BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713,
00585 
00586         /**
00587          * Wave number reciprocal, meter.
00588          */
00589         BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714,
00590 
00591         /**
00592          * Density, kilogram per cubic meter.
00593          */
00594         BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715,
00595 
00596         /**
00597          * Surface density (kilogram per square meter).
00598          */
00599         BLE_GATT_UNIT_SURFACE_DENSITY_KILOGRAM_PER_SQUARE_METRE = 0x2716,
00600 
00601         /**
00602          * Specific volume (cubic meter per kilogram).
00603          */
00604         BLE_GATT_UNIT_SPECIFIC_VOLUME_CUBIC_METRE_PER_KILOGRAM = 0x2717,
00605 
00606         /**
00607          * Current density (ampere per square meter).
00608          */
00609         BLE_GATT_UNIT_CURRENT_DENSITY_AMPERE_PER_SQUARE_METRE = 0x2718,
00610 
00611         /**
00612          * Magnetic field strength, ampere per meter.
00613          */
00614         BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719,
00615 
00616         /**
00617          * Amount concentration (mole per cubic meter).
00618          */
00619         BLE_GATT_UNIT_AMOUNT_CONCENTRATION_MOLE_PER_CUBIC_METRE = 0x271A,
00620 
00621         /**
00622          * Mass concentration (kilogram per cubic meter).
00623          */
00624         BLE_GATT_UNIT_MASS_CONCENTRATION_KILOGRAM_PER_CUBIC_METRE = 0x271B,
00625 
00626         /**
00627          * Luminance (candela per square meter).
00628          */
00629         BLE_GATT_UNIT_LUMINANCE_CANDELA_PER_SQUARE_METRE = 0x271C,
00630 
00631         /**
00632          * Refractive index.
00633          */
00634         BLE_GATT_UNIT_REFRACTIVE_INDEX = 0x271D,
00635 
00636         /**
00637          * Relative permeability.
00638         */
00639         BLE_GATT_UNIT_RELATIVE_PERMEABILITY = 0x271E,
00640 
00641         /**
00642          * Plane angle (radian).
00643          */
00644         BLE_GATT_UNIT_PLANE_ANGLE_RADIAN = 0x2720,
00645 
00646         /**
00647          * Solid angle (steradian).
00648         */
00649         BLE_GATT_UNIT_SOLID_ANGLE_STERADIAN = 0x2721,
00650 
00651         /**
00652          * Frequency, hertz.
00653          */
00654         BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722,
00655 
00656         /**
00657          * Force, newton.
00658          */
00659         BLE_GATT_UNIT_FORCE_NEWTON = 0x2723,
00660 
00661         /**
00662          * Pressure, pascal.
00663          */
00664         BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724,
00665 
00666         /**
00667          * Energy, joule.
00668          */
00669         BLE_GATT_UNIT_ENERGY_JOULE = 0x2725,
00670 
00671         /**
00672          * Power, watt.
00673          */
00674         BLE_GATT_UNIT_POWER_WATT = 0x2726,
00675 
00676         /**
00677          * Electrical charge, coulomb.
00678          */
00679         BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727,
00680 
00681         /**
00682          * Electrical potential difference, voltage.
00683          */
00684         BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728,
00685 
00686         /**
00687          * Capacitance, farad.
00688          */
00689         BLE_GATT_UNIT_CAPACITANCE_FARAD = 0x2729,
00690 
00691         /**
00692          * Electric resistance, ohm.
00693          */
00694         BLE_GATT_UNIT_ELECTRIC_RESISTANCE_OHM = 0x272A,
00695 
00696         /**
00697          * Electric conductance, siemens.
00698          */
00699         BLE_GATT_UNIT_ELECTRIC_CONDUCTANCE_SIEMENS = 0x272B,
00700 
00701         /**
00702          * Magnetic flux, weber.
00703          */
00704         BLE_GATT_UNIT_MAGNETIC_FLEX_WEBER = 0x272C,
00705 
00706         /**
00707          * Magnetic flux density, tesla.
00708          */
00709         BLE_GATT_UNIT_MAGNETIC_FLEX_DENSITY_TESLA = 0x272D,
00710 
00711         /**
00712          * Inductance, henry.
00713          */
00714         BLE_GATT_UNIT_INDUCTANCE_HENRY = 0x272E,
00715 
00716         /**
00717          * Celsius temperature, degree Celsius.
00718          */
00719         BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_CELSIUS = 0x272F,
00720 
00721         /**
00722          * Luminous flux, lumen.
00723          */
00724         BLE_GATT_UNIT_LUMINOUS_FLUX_LUMEN = 0x2730,
00725 
00726         /**
00727          * Illuminance, lux.
00728          */
00729         BLE_GATT_UNIT_ILLUMINANCE_LUX = 0x2731,
00730 
00731         /**
00732          * Activity referred to a radionuclide, becquerel.
00733          */
00734         BLE_GATT_UNIT_ACTIVITY_REFERRED_TO_A_RADIONUCLIDE_BECQUEREL = 0x2732,
00735 
00736         /**
00737          * Absorbed dose, gray.
00738          */
00739         BLE_GATT_UNIT_ABSORBED_DOSE_GRAY = 0x2733,
00740 
00741         /**
00742          * Dose equivalent, sievert.
00743          */
00744         BLE_GATT_UNIT_DOSE_EQUIVALENT_SIEVERT = 0x2734,
00745 
00746         /**
00747          * Catalytic activity, katal.
00748          */
00749         BLE_GATT_UNIT_CATALYTIC_ACTIVITY_KATAL = 0x2735,
00750 
00751         /**
00752          * Dynamic viscosity, pascal second.
00753          */
00754         BLE_GATT_UNIT_DYNAMIC_VISCOSITY_PASCAL_SECOND = 0x2740,
00755 
00756         /**
00757          * Moment of force, newton meter.
00758          */
00759         BLE_GATT_UNIT_MOMENT_OF_FORCE_NEWTON_METRE = 0x2741,
00760 
00761         /**
00762          * Surface tension, newton per meter.
00763          */
00764         BLE_GATT_UNIT_SURFACE_TENSION_NEWTON_PER_METRE = 0x2742,
00765 
00766         /**
00767          * Angular velocity, radian per second.
00768          */
00769         BLE_GATT_UNIT_ANGULAR_VELOCITY_RADIAN_PER_SECOND = 0x2743,
00770 
00771         /**
00772          * Angular acceleration, radian per second squared.
00773          */
00774         BLE_GATT_UNIT_ANGULAR_ACCELERATION_RADIAN_PER_SECOND_SQUARED = 0x2744,
00775 
00776         /**
00777          * Heat flux density, watt per square meter.
00778          */
00779         BLE_GATT_UNIT_HEAT_FLUX_DENSITY_WATT_PER_SQUARE_METRE = 0x2745,
00780 
00781         /**
00782          * Heat capacity, joule per kelvin.
00783          */
00784         BLE_GATT_UNIT_HEAT_CAPACITY_JOULE_PER_KELVIN = 0x2746,
00785 
00786         /**
00787          * Specific heat capacity, joule per kilogram kelvin.
00788          */
00789         BLE_GATT_UNIT_SPECIFIC_HEAT_CAPACITY_JOULE_PER_KILOGRAM_KELVIN = 0x2747,
00790 
00791         /**
00792          * Specific energy, joule per kilogram.
00793          */
00794         BLE_GATT_UNIT_SPECIFIC_ENERGY_JOULE_PER_KILOGRAM = 0x2748,
00795 
00796         /**
00797          * Thermal conductivity, watt per meter kelvin.
00798          */
00799         BLE_GATT_UNIT_THERMAL_CONDUCTIVITY_WATT_PER_METRE_KELVIN = 0x2749,
00800 
00801         /**
00802          * Energy density, joule per cubic meter.
00803          */
00804         BLE_GATT_UNIT_ENERGY_DENSITY_JOULE_PER_CUBIC_METRE = 0x274A,
00805 
00806         /**
00807          * Electric field strength, volt per meter.
00808          */
00809         BLE_GATT_UNIT_ELECTRIC_FIELD_STRENGTH_VOLT_PER_METRE = 0x274B,
00810 
00811         /**
00812          * Electric charge density, coulomb per cubic meter.
00813          */
00814         BLE_GATT_UNIT_ELECTRIC_CHARGE_DENSITY_COULOMB_PER_CUBIC_METRE = 0x274C,
00815 
00816         /**
00817          * Surface charge density, coulomb per square meter.
00818          */
00819         BLE_GATT_UNIT_SURFACE_CHARGE_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274D,
00820 
00821         /**
00822          * Electric flux density, coulomb per square meter.
00823          */
00824         BLE_GATT_UNIT_ELECTRIC_FLUX_DENSITY_COULOMB_PER_SQUARE_METRE = 0x274E,
00825 
00826         /**
00827          * Permittivity, farad per meter.
00828          */
00829         BLE_GATT_UNIT_PERMITTIVITY_FARAD_PER_METRE = 0x274F,
00830 
00831         /**
00832          * Permeability, henry per meter.
00833          */
00834         BLE_GATT_UNIT_PERMEABILITY_HENRY_PER_METRE = 0x2750,
00835 
00836         /**
00837          * Molar energy, joule per mole.
00838          */
00839         BLE_GATT_UNIT_MOLAR_ENERGY_JOULE_PER_MOLE = 0x2751,
00840 
00841         /**
00842          * Molar entropy, joule per mole kelvin.
00843          */
00844         BLE_GATT_UNIT_MOLAR_ENTROPY_JOULE_PER_MOLE_KELVIN = 0x2752,
00845 
00846         /**
00847          * Exposure, coulomb per kilogram.
00848          */
00849         BLE_GATT_UNIT_EXPOSURE_COULOMB_PER_KILOGRAM = 0x2753,
00850 
00851         /**
00852          * Absorbed dose rate, gray per second.
00853          */
00854         BLE_GATT_UNIT_ABSORBED_DOSE_RATE_GRAY_PER_SECOND = 0x2754,
00855 
00856         /**
00857          * Radiant intensity, watt per steradian.
00858          */
00859         BLE_GATT_UNIT_RADIANT_INTENSITY_WATT_PER_STERADIAN = 0x2755,
00860 
00861         /**
00862          * Radiance, watt per square meter steradian.
00863          */
00864         BLE_GATT_UNIT_RADIANCE_WATT_PER_SQUARE_METRE_STERADIAN = 0x2756,
00865 
00866         /**
00867          * Catalytic activity concentration, katal per cubic meter.
00868          */
00869         BLE_GATT_UNIT_CATALYTIC_ACTIVITY_CONCENTRATION_KATAL_PER_CUBIC_METRE = 0x2757,
00870 
00871         /**
00872          * Time, minute.
00873          */
00874         BLE_GATT_UNIT_TIME_MINUTE = 0x2760,
00875 
00876         /**
00877          * Time, hour.
00878          */
00879         BLE_GATT_UNIT_TIME_HOUR = 0x2761,
00880 
00881         /**
00882          * Time, day.
00883          */
00884         BLE_GATT_UNIT_TIME_DAY = 0x2762,
00885 
00886         /**
00887          * Plane angle, degree.
00888          */
00889         BLE_GATT_UNIT_PLANE_ANGLE_DEGREE = 0x2763,
00890 
00891         /**
00892          * Plane angle, minute.
00893          */
00894         BLE_GATT_UNIT_PLANE_ANGLE_MINUTE = 0x2764,
00895 
00896         /**
00897          * Plane angle, seconds.
00898          */
00899         BLE_GATT_UNIT_PLANE_ANGLE_SECOND = 0x2765,
00900 
00901         /**
00902          * Area, hectare.
00903          */
00904         BLE_GATT_UNIT_AREA_HECTARE = 0x2766,
00905 
00906         /**
00907          * Volume, liter.
00908          */
00909         BLE_GATT_UNIT_VOLUME_LITRE = 0x2767,
00910 
00911         /**
00912          * Mass, ton.
00913          */
00914         BLE_GATT_UNIT_MASS_TONNE = 0x2768,
00915 
00916         /**
00917          * Pressure, bar.
00918          */
00919         BLE_GATT_UNIT_PRESSURE_BAR = 0x2780,
00920 
00921         /**
00922          * Pressure, millimeter of mercury.
00923          */
00924         BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781,
00925 
00926         /**
00927          * Length, ngstrm.
00928          */
00929         BLE_GATT_UNIT_LENGTH_ANGSTROM = 0x2782,
00930 
00931         /**
00932          * Length, nautical mile.
00933          */
00934         BLE_GATT_UNIT_LENGTH_NAUTICAL_MILE = 0x2783,
00935 
00936         /**
00937          * Area, barn.
00938          */
00939         BLE_GATT_UNIT_AREA_BARN = 0x2784,
00940 
00941         /**
00942          * Velocity, knot.
00943          */
00944         BLE_GATT_UNIT_VELOCITY_KNOT = 0x2785,
00945 
00946         /**
00947          * Logarithmic radio quantity, neper.
00948          */
00949         BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_NEPER = 0x2786,
00950 
00951         /**
00952          * Logarithmic radio quantity, bel.
00953          */
00954         BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_BEL = 0x2787,
00955 
00956         /**
00957          * Length, yard.
00958          */
00959         BLE_GATT_UNIT_LENGTH_YARD = 0x27A0,
00960 
00961         /**
00962          * Length, parsec.
00963          */
00964         BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1,
00965 
00966         /**
00967          * Length, inch.
00968          */
00969         BLE_GATT_UNIT_LENGTH_INCH = 0x27A2,
00970 
00971         /**
00972          * Length, foot.
00973          */
00974         BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3,
00975 
00976         /**
00977          * Length, mile.
00978          */
00979         BLE_GATT_UNIT_LENGTH_MILE = 0x27A4,
00980 
00981         /**
00982          * Pressure, pound-force per square inch.
00983          */
00984         BLE_GATT_UNIT_PRESSURE_POUND_FORCE_PER_SQUARE_INCH = 0x27A5,
00985 
00986         /**
00987          * Velocity, kilometer per hour.
00988          */
00989         BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6,
00990 
00991         /** Velocity, mile per hour.
00992          *
00993          */
00994         BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7,
00995 
00996         /**
00997          * Angular Velocity, revolution per minute.
00998          */
00999         BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8,
01000 
01001         /**
01002          * Energy, gram calorie.
01003          */
01004         BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9,
01005 
01006         /**
01007          * Energy, kilogram calorie.
01008          */
01009         BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA,
01010 
01011         /**
01012          * Energy, killowatt hour.
01013          */
01014         BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB,
01015 
01016         /**
01017          * Thermodynamic temperature, degree Fahrenheit.
01018          */
01019         BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_FAHRENHEIT = 0x27AC,
01020 
01021         /**
01022          * Percentage.
01023          */
01024         BLE_GATT_UNIT_PERCENTAGE = 0x27AD,
01025 
01026         /**
01027          * Per mille.
01028          */
01029         BLE_GATT_UNIT_PER_MILLE = 0x27AE,
01030 
01031         /**
01032          * Period, beats per minute.
01033          */
01034         BLE_GATT_UNIT_PERIOD_BEATS_PER_MINUTE = 0x27AF,
01035 
01036         /**
01037          * Electric charge, ampere hours.
01038          */
01039         BLE_GATT_UNIT_ELECTRIC_CHARGE_AMPERE_HOURS = 0x27B0,
01040 
01041         /**
01042          * Mass density, milligram per deciliter.
01043          */
01044         BLE_GATT_UNIT_MASS_DENSITY_MILLIGRAM_PER_DECILITRE = 0x27B1,
01045 
01046         /**
01047          * Mass density, millimole per liter.
01048          */
01049         BLE_GATT_UNIT_MASS_DENSITY_MILLIMOLE_PER_LITRE = 0x27B2,
01050 
01051         /**
01052          * Time, year.
01053          */
01054         BLE_GATT_UNIT_TIME_YEAR = 0x27B3,
01055 
01056         /**
01057          * Time, month.
01058          */
01059         BLE_GATT_UNIT_TIME_MONTH = 0x27B4,
01060 
01061         /**
01062          * Concentration, count per cubic meter.
01063          */
01064         BLE_GATT_UNIT_CONCENTRATION_COUNT_PER_CUBIC_METRE = 0x27B5,
01065 
01066         /**
01067          * Irradiance, watt per square meter.
01068          */
01069         BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE = 0x27B6
01070     };
01071 
01072     /**
01073      * Presentation format of a characteristic.
01074      *
01075      * It determines how the value of a characteristic is formatted. A server
01076      * can expose that information to its clients by adding a Characteristic
01077      * Presentation Format descriptor to relevant characteristics.
01078      *
01079      * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2.
01080      */
01081     enum {
01082         /**
01083          * Reserved for future use.
01084          */
01085         BLE_GATT_FORMAT_RFU = 0x00,
01086 
01087         /**
01088          * Boolean.
01089          */
01090         BLE_GATT_FORMAT_BOOLEAN = 0x01,
01091 
01092         /**
01093          * Unsigned 2-bit integer.
01094          */
01095         BLE_GATT_FORMAT_2BIT = 0x02,
01096 
01097         /**
01098          * Unsigned 4-bit integer.
01099          */
01100         BLE_GATT_FORMAT_NIBBLE = 0x03,
01101 
01102         /**
01103          * Unsigned 8-bit integer.
01104          */
01105         BLE_GATT_FORMAT_UINT8 = 0x04,
01106 
01107         /**
01108          * Unsigned 12-bit integer.
01109          */
01110         BLE_GATT_FORMAT_UINT12 = 0x05,
01111 
01112         /**
01113          * Unsigned 16-bit integer.
01114          */
01115         BLE_GATT_FORMAT_UINT16 = 0x06,
01116 
01117         /**
01118          * Unsigned 24-bit integer.
01119          */
01120         BLE_GATT_FORMAT_UINT24 = 0x07,
01121 
01122         /**
01123          * Unsigned 32-bit integer.
01124          */
01125         BLE_GATT_FORMAT_UINT32 = 0x08,
01126 
01127         /**
01128          * Unsigned 48-bit integer.
01129          */
01130         BLE_GATT_FORMAT_UINT48 = 0x09,
01131 
01132         /**
01133          * Unsigned 64-bit integer.
01134          */
01135         BLE_GATT_FORMAT_UINT64 = 0x0A,
01136 
01137         /**
01138          * Unsigned 128-bit integer.
01139          */
01140         BLE_GATT_FORMAT_UINT128 = 0x0B,
01141 
01142         /**
01143          * Signed 8-bit integer.
01144          */
01145         BLE_GATT_FORMAT_SINT8 = 0x0C,
01146 
01147         /**
01148          * Signed 12-bit integer.
01149          */
01150         BLE_GATT_FORMAT_SINT12 = 0x0D,
01151 
01152         /**
01153          * Signed 16-bit integer.
01154          */
01155         BLE_GATT_FORMAT_SINT16 = 0x0E,
01156 
01157         /**
01158          * Signed 24-bit integer.
01159          */
01160         BLE_GATT_FORMAT_SINT24 = 0x0F,
01161 
01162         /**
01163          * Signed 32-bit integer.
01164          */
01165         BLE_GATT_FORMAT_SINT32 = 0x10,
01166 
01167         /**
01168          * Signed 48-bit integer.
01169          */
01170         BLE_GATT_FORMAT_SINT48 = 0x11,
01171 
01172         /**
01173          * Signed 64-bit integer.
01174          */
01175         BLE_GATT_FORMAT_SINT64 = 0x12,
01176 
01177         /**
01178          * Signed 128-bit integer.
01179          */
01180         BLE_GATT_FORMAT_SINT128 = 0x13,
01181 
01182         /**
01183          * IEEE-754 32-bit floating point.
01184          */
01185         BLE_GATT_FORMAT_FLOAT32 = 0x14,
01186 
01187         /**
01188          * IEEE-754 64-bit floating point.
01189          */
01190         BLE_GATT_FORMAT_FLOAT64 = 0x15,
01191 
01192         /**
01193          * IEEE-11073 16-bit SFLOAT.
01194          */
01195         BLE_GATT_FORMAT_SFLOAT = 0x16,
01196 
01197         /**
01198          * IEEE-11073 32-bit FLOAT.
01199          */
01200         BLE_GATT_FORMAT_FLOAT = 0x17,
01201 
01202         /**
01203          * IEEE-20601 format.
01204          */
01205         BLE_GATT_FORMAT_DUINT16 = 0x18,
01206 
01207         /**
01208          * UTF8 string.
01209          */
01210         BLE_GATT_FORMAT_UTF8S = 0x19,
01211 
01212         /**
01213          * UTF16 string.
01214          */
01215         BLE_GATT_FORMAT_UTF16S = 0x1A,
01216 
01217         /**
01218          * Opaque Structure.
01219          */
01220         BLE_GATT_FORMAT_STRUCT = 0x1B
01221     };
01222 
01223     /*!
01224      * Characteristic properties.
01225      *
01226      * It is a bitfield that determines how a characteristic value can be used.
01227      *
01228      * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1
01229      * and Section 3.3.3.1 for Extended Properties.
01230      */
01231     enum Properties_t  {
01232         /**
01233          * No property defined.
01234          */
01235         BLE_GATT_CHAR_PROPERTIES_NONE = 0x00,
01236 
01237         /**
01238          * Permits broadcasts of the characteristic value using the Server
01239          * Characteristic Configuration descriptor.
01240          */
01241         BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01,
01242 
01243         /**
01244          * Permits reads of the characteristic value.
01245          */
01246         BLE_GATT_CHAR_PROPERTIES_READ = 0x02,
01247 
01248         /**
01249          * Permits writes of the characteristic value without response.
01250          */
01251         BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04,
01252 
01253         /**
01254          * Permits writes of the characteristic value with response.
01255          */
01256         BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08,
01257 
01258         /**
01259          * Permits notifications of a characteristic value without acknowledgment.
01260          */
01261         BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10,
01262 
01263         /**
01264          * Permits indications of a characteristic value with acknowledgment.
01265          */
01266         BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20,
01267 
01268         /**
01269          * Permits signed writes to the characteristic value.
01270          */
01271         BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40,
01272 
01273         /**
01274          * The Characteristic Extended Properties descriptor
01275          * defines additional characteristic properties.
01276          */
01277         BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80
01278     };
01279 
01280     /**
01281      * Indicates if the properties has at least one of the writable flags.
01282      *
01283      * @param[in] properties The properties to inspect.
01284      *
01285      * @return True if the properties set at least one of the writable flags and
01286      * false otherwise.
01287      */
01288     static bool isWritable(uint8_t properties)
01289     {
01290         const uint8_t writable =
01291              BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE |
01292              BLE_GATT_CHAR_PROPERTIES_WRITE |
01293              BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES;
01294 
01295         return properties & writable;
01296     }
01297 
01298     /**
01299      * Indicates if the properties is readable.
01300      *
01301      * @param[in] properties The properties to inspect.
01302      *
01303      * @return True if the properties has its readable flag set and false
01304      * otherwise.
01305      */
01306     static bool isReadable(uint8_t properties)
01307     {
01308         const uint8_t readable = BLE_GATT_CHAR_PROPERTIES_READ;
01309         return properties & readable;
01310     }
01311 
01312     /**
01313      * Value of a Characteristic Presentation Format descriptor.
01314      *
01315      * Characteristic Presentation Format descriptor expresses the format of a
01316      * characteristic value.
01317      *
01318      * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.
01319      */
01320     struct PresentationFormat_t {
01321         /**
01322          * Format of the value.
01323          */
01324         uint8_t gatt_format;
01325 
01326         /**
01327          * Exponent for integer data types.
01328          *
01329          * Example: if Exponent = -3 and the char value is 3892, the actual
01330          * value is 3.892
01331          */
01332         int8_t exponent;
01333 
01334         /**
01335          * Unit of the characteristic value.
01336          *
01337          * It is a UUID from Bluetooth Assigned Numbers.
01338          */
01339         uint16_t gatt_unit;
01340 
01341         /**
01342          * Namespace of the description field.
01343          *
01344          * This field identifies the organization that is responsible for
01345          * defining the enumerations for the description field.
01346          *
01347          * The namespace of the Bluetooth Body is 0x01.
01348          */
01349         uint8_t gatt_namespace;
01350 
01351         /**
01352          * Description.
01353          *
01354          * @note The value 0x0000 means unknown in the Bluetooth namespace.
01355          */
01356         uint16_t gatt_nsdesc;
01357 
01358     };
01359 
01360     /**
01361      * Security level applied to GATT operations.
01362      */
01363     typedef ble::att_security_requirement_t SecurityRequirement_t;
01364 
01365     /**
01366      * @brief  Constructs a new GattCharacteristic.
01367      *
01368      * @param[in] uuid The UUID of this characteristic.
01369      * @param[in] valuePtr Memory buffer holding the initial value. The value is
01370      * copied into the Bluetooth subsytem when the enclosing service is added.
01371      * Thereafter, the stack maintains it internally.
01372      * @param[in] len The length in bytes of this characteristic's value.
01373      * @param[in] maxLen The capacity in bytes of the characteristic value
01374      * buffer.
01375      * @param[in] props An 8-bit field that contains the characteristic's
01376      * properties.
01377      * @param[in] descriptors A pointer to an array of descriptors to be included
01378      * within this characteristic. The caller owns the memory for the descriptor
01379      * array, which must remain valid at least until the enclosing service is
01380      * added to the GATT table.
01381      * @param[in] numDescriptors The number of descriptors presents in @p
01382      * descriptors array.
01383      * @param[in] hasVariableLen Flag that indicates if the attribute's value
01384      * length can change throughout time.
01385      *
01386      * @note If valuePtr is NULL, length is equal to 0 and the characteristic
01387      * is readable, then that particular characteristic may be considered
01388      * optional and dropped while instantiating the service with the underlying
01389      * BLE stack.
01390      *
01391      * @note A Client Characteristic Configuration Descriptor (CCCD) should not
01392      * be allocated if either the notify or indicate flag in the @p props bit
01393      * field; the underlying BLE stack handles it.
01394      *
01395      * @attention GattCharacteristic registered in a GattServer must remain
01396      * valid for the lifetime of the GattServer.
01397      */
01398     GattCharacteristic(
01399         const UUID &uuid,
01400         uint8_t *valuePtr = NULL,
01401         uint16_t len = 0,
01402         uint16_t maxLen = 0,
01403         uint8_t props = BLE_GATT_CHAR_PROPERTIES_NONE,
01404         GattAttribute *descriptors[] = NULL,
01405         unsigned numDescriptors = 0,
01406         bool hasVariableLen = true
01407     ) : _valueAttribute(uuid, valuePtr, len, maxLen, hasVariableLen),
01408         _properties(props),
01409         _descriptors(descriptors),
01410         _descriptorCount(numDescriptors),
01411         readAuthorizationCallback(),
01412         writeAuthorizationCallback(),
01413         _update_security(SecurityRequirement_t::NONE) {
01414         _valueAttribute.allowWrite(isWritable(_properties));
01415         _valueAttribute.allowRead(isReadable(_properties));
01416 
01417         // signed writes requires at least an unauthenticated CSRK or an
01418         // unauthenticated ltk if the link is encrypted.
01419         if (_properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES) {
01420             _valueAttribute.setWriteSecurityRequirement(
01421                 SecurityRequirement_t::UNAUTHENTICATED
01422             );
01423         }
01424     }
01425 
01426 public:
01427     /**
01428      * Set up the minimum security (mode and level) requirements for access to
01429      * the characteristic's value attribute.
01430      *
01431      * @param[in] securityMode Can be one of encryption or signing, with or
01432      * without protection for man in the middle attacks (MITM).
01433      *
01434      * @deprecated Fine grained security check has been added to with mbed OS
01435      * 5.9. It is possible to set independently security requirements for read,
01436      * write and update operations. In the meantime SecurityManager::SecurityMode_t
01437      * is not used anymore to represent security requirements as it maps
01438      * incorrectly the Bluetooth standard.
01439      */
01440     MBED_DEPRECATED_SINCE(
01441         "mbed-os-5.9",
01442         "Use setWriteSecurityRequirements, setReadSecurityRequirements and "
01443         "setUpdateSecurityRequirements"
01444     )
01445     void requireSecurity(SecurityManager::SecurityMode_t securityMode)
01446     {
01447         SecurityRequirement_t sec_requirements = SecurityModeToAttSecurity(securityMode);
01448 
01449         _valueAttribute.setReadSecurityRequirement(sec_requirements);
01450         _valueAttribute.setWriteSecurityRequirement(sec_requirements);
01451         _update_security = sec_requirements.value();
01452     }
01453 
01454     /**
01455      * Set all security requirements of the characteristic.
01456      *
01457      * @param read_security The security requirement of the read operations.
01458      * @param write_security The security requirement of write operations.
01459      * @param update_security The security requirement of update operations.
01460      */
01461     void setSecurityRequirements(
01462         SecurityRequirement_t read_security,
01463         SecurityRequirement_t write_security,
01464         SecurityRequirement_t update_security
01465     ) {
01466         setReadSecurityRequirement(read_security);
01467         setWriteSecurityRequirement(write_security);
01468         setUpdateSecurityRequirement(update_security);
01469     }
01470 
01471     /**
01472      * Set the security of the read operation.
01473      *
01474      * @param[in] security The security requirement of the read operation.
01475      */
01476     void setReadSecurityRequirement(SecurityRequirement_t security)
01477     {
01478         _valueAttribute.setReadSecurityRequirement(security);
01479     }
01480 
01481     /**
01482      * Get the security requirement of the read operation.
01483      *
01484      * @return The security requirement of the read operation.
01485      */
01486     SecurityRequirement_t getReadSecurityRequirement() const
01487     {
01488         return _valueAttribute.getReadSecurityRequirement();
01489     }
01490 
01491     /**
01492      * Set the security requirement of the write operations.
01493      *
01494      * @note If the signed write flag is set in the characteristic properties
01495      * then the security requirement applied to write operation must be either
01496      * AUTHENTICATED or UNAUTHENTICATED. Security requirements NONE and
01497      * SC_AUTHENTICATED are not applicable to signing operation.
01498      *
01499      * @param[in] security The security requirement of write operations.
01500      */
01501     void setWriteSecurityRequirement(SecurityRequirement_t security)
01502     {
01503         MBED_ASSERT(
01504             ((_properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES) &&
01505             ((security == SecurityRequirement_t::NONE) ||
01506             (security == SecurityRequirement_t::SC_AUTHENTICATED))) == false
01507         );
01508         _valueAttribute.setWriteSecurityRequirement(security);
01509     }
01510 
01511     /**
01512      * Get the security requirement of write operations.
01513      *
01514      * @return The security requirement of write operations.
01515      */
01516     SecurityRequirement_t getWriteSecurityRequirement() const
01517     {
01518         return _valueAttribute.getWriteSecurityRequirement();
01519     }
01520 
01521     /**
01522      * Set the security requirement of update operations.
01523      *
01524      * @note This security requirement is also applied to the write operation of
01525      * the Client Characteristic Configuration Descriptor.
01526      *
01527      * @param[in] security The security requirement that must be met to send
01528      * updates and accept write of the CCCD.
01529      */
01530     void setUpdateSecurityRequirement(SecurityRequirement_t security)
01531     {
01532         _update_security = security.value();
01533     }
01534 
01535     /**
01536      * Get the security requirement of update operations.
01537      *
01538      * @note This security requirement is also applied to the write operation of
01539      * the Client Characteristic Configuration Descriptor.
01540      *
01541      * @return The security requirement that must be met to send updates and
01542      * accept write of the CCCD.
01543      */
01544     SecurityRequirement_t getUpdateSecurityRequirement() const
01545     {
01546         return static_cast<SecurityRequirement_t::type>(_update_security);
01547     }
01548 
01549 public:
01550     /**
01551      * Register a callback handling client's write requests or commands.
01552      *
01553      * The callback registered is invoked when the client attempts to write the
01554      * characteristic value; the event handler can accept or reject the write
01555      * request with the appropriate error code.
01556      *
01557      * @param[in] callback Event handler being registered.
01558      */
01559     void setWriteAuthorizationCallback(
01560         void (*callback)(GattWriteAuthCallbackParams *)
01561     ) {
01562         writeAuthorizationCallback.attach(callback);
01563     }
01564 
01565     /**
01566      * Register a callback handling client's write requests or commands.
01567      *
01568      * The callback registered is invoked when the client attempts to write the
01569      * characteristic value; the event handler can accept or reject the write
01570      * request with the appropriate error code.
01571      *
01572      * @param[in] object Pointer to the object of a class defining the event
01573      * handler (@p member). It must remain valid for the lifetime of the
01574      * GattCharacteristic.
01575      * @param[in] member The member function that handles the write event.
01576      */
01577     template <typename T>
01578     void setWriteAuthorizationCallback(
01579         T *object,
01580         void (T::*member)(GattWriteAuthCallbackParams *)
01581     ) {
01582         writeAuthorizationCallback.attach(object, member);
01583     }
01584 
01585     /**
01586      * Register the read requests event handler.
01587      *
01588      * The callback registered is invoked when the client attempts to read the
01589      * characteristic value; the event handler can accept or reject the read
01590      * request with the appropriate error code. It can also set specific outgoing
01591      * data.
01592      *
01593      * @param[in] callback Event handler being registered.
01594      */
01595     void setReadAuthorizationCallback(
01596         void (*callback)(GattReadAuthCallbackParams *)
01597     ) {
01598         readAuthorizationCallback.attach(callback);
01599     }
01600 
01601     /**
01602      * Register the read requests event handler.
01603      *
01604      * The callback registered is invoked when the client attempts to read the
01605      * characteristic value; the event handler can accept or reject the read
01606      * request with the appropriate error code. It can also set specific outgoing
01607      * data.
01608      *
01609      * @param[in] object Pointer to the object of a class defining the event
01610      * handler (@p member). It must remain valid for the lifetime of the
01611      * GattCharacteristic.
01612      * @param[in] member The member function that handles the read event.
01613      */
01614     template <typename T>
01615     void setReadAuthorizationCallback(
01616         T *object,
01617         void (T::*member)(GattReadAuthCallbackParams *)
01618     ) {
01619         readAuthorizationCallback.attach(object, member);
01620     }
01621 
01622     /**
01623      * Invoke the write authorization callback.
01624      *
01625      * This function is a helper that calls the registered write handler to
01626      * determine the authorization reply for a write request.
01627      *
01628      * @attention This function is not meant to be called by user code.
01629      *
01630      * @param[in] params Context of the write-auth request; it contains an
01631      * out-parameter used as a reply.
01632      *
01633      * @return A GattAuthCallbackReply_t value indicating whether authorization
01634      * is granted.
01635      */
01636     GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params)
01637     {
01638         if (!isWriteAuthorizationEnabled()) {
01639             return AUTH_CALLBACK_REPLY_SUCCESS;
01640         }
01641 
01642         /* Initialized to no-error by default. */
01643         params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS;
01644         writeAuthorizationCallback.call(params);
01645         return params->authorizationReply;
01646     }
01647 
01648     /**
01649      * Invoke the read authorization callback.
01650      *
01651      * This function is a helper that calls the registered read handler to
01652      * determine the authorization reply for a read request.
01653      *
01654      * @attention This function is not meant to be called by user code.
01655      *
01656      * @param[in] params Context of the read-auth request; it contains an
01657      * out-parameter used as a reply and the handler can fill it with outgoing
01658      * data.
01659      *
01660      * @return A GattAuthCallbackReply_t value indicating whether authorization
01661      * is granted.
01662      *
01663      * @note If the read request is approved and params->data remains NULL, then
01664      * the current characteristic value is used in the read response payload.
01665      *
01666      * @note If the read is approved, the event handler can specify an outgoing
01667      * value directly with the help of the fields
01668      * GattReadAuthCallbackParams::data and GattReadAuthCallbackParams::len.
01669      */
01670     GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params)
01671     {
01672         if (!isReadAuthorizationEnabled()) {
01673             return AUTH_CALLBACK_REPLY_SUCCESS;
01674         }
01675 
01676         /* Initialized to no-error by default. */
01677         params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS;
01678         readAuthorizationCallback.call(params);
01679         return params->authorizationReply;
01680     }
01681 
01682 public:
01683     /**
01684      * Get the characteristic's value attribute.
01685      *
01686      * @return A reference to the characteristic's value attribute.
01687      */
01688     GattAttribute& getValueAttribute()
01689     {
01690         return _valueAttribute;
01691     }
01692 
01693     /**
01694      * Get the characteristic's value attribute.
01695      *
01696      * @return A const reference to the characteristic's value attribute.
01697      */
01698     const GattAttribute& getValueAttribute() const
01699     {
01700         return _valueAttribute;
01701     }
01702 
01703     /**
01704      * Get the characteristic's value attribute handle in the ATT table.
01705      *
01706      * @return The value attribute handle.
01707      *
01708      * @note The underlying BLE stack assigns the attribute handle when the
01709      * enclosing service is added.
01710      */
01711     GattAttribute::Handle_t getValueHandle(void) const
01712     {
01713         return getValueAttribute().getHandle();
01714     }
01715 
01716     /**
01717      * Get the characteristic's properties.
01718      *
01719      * @note Refer to GattCharacteristic::Properties_t.
01720      *
01721      * @return The characteristic's properties.
01722      */
01723     uint8_t getProperties(void) const
01724     {
01725         return _properties;
01726     }
01727 
01728     /**
01729      * Get the characteristic's required security.
01730      *
01731      * @return The characteristic's required security.
01732      *
01733      * @deprecated Fine grained security check has been added to with mbed OS
01734      * 5.9. It is possible to set independently security requirements for read,
01735      * write and update operations. In the meantime SecurityManager::SecurityMode_t
01736      * is not used anymore to represent security requirements as it maps
01737      * incorrectly the Bluetooth standard.
01738      */
01739     MBED_DEPRECATED_SINCE(
01740         "mbed-os-5.9",
01741         "Use getWriteSecurityRequirements, getReadSecurityRequirements and "
01742         "getUpdateSecurityRequirements"
01743     )
01744     SecurityManager::SecurityMode_t getRequiredSecurity() const
01745     {
01746         SecurityRequirement_t max_sec = std::max(
01747             std::max(
01748                 getReadSecurityRequirement(),
01749                 getWriteSecurityRequirement()
01750             ),
01751             getUpdateSecurityRequirement()
01752         );
01753 
01754         bool needs_signing =
01755             _properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES;
01756 
01757         switch(max_sec.value()) {
01758             case SecurityRequirement_t::NONE:
01759                 MBED_ASSERT(needs_signing == false);
01760                 return SecurityManager::SECURITY_MODE_ENCRYPTION_OPEN_LINK;
01761 
01762             case SecurityRequirement_t::UNAUTHENTICATED:
01763                 return (needs_signing) ?
01764                     SecurityManager::SECURITY_MODE_SIGNED_NO_MITM :
01765                     SecurityManager::SECURITY_MODE_ENCRYPTION_NO_MITM;
01766 
01767             case SecurityRequirement_t::AUTHENTICATED:
01768                 return (needs_signing) ?
01769                     SecurityManager::SECURITY_MODE_SIGNED_WITH_MITM :
01770                     SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM;
01771 
01772             case SecurityRequirement_t::SC_AUTHENTICATED:
01773                 MBED_ASSERT(needs_signing == false);
01774                 // fallback to encryption with MITM
01775                 return SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM;
01776             default:
01777                 MBED_ASSERT(false);
01778                 return SecurityManager::SECURITY_MODE_NO_ACCESS;
01779         }
01780     }
01781 
01782     /**
01783      * Get the total number of descriptors within this characteristic.
01784      *
01785      * @return The total number of descriptors.
01786      */
01787     uint8_t getDescriptorCount(void) const
01788     {
01789         return _descriptorCount;
01790     }
01791 
01792     /**
01793      * Check whether read authorization is enabled.
01794      *
01795      * Read authorization is enabled when a read authorization event handler is
01796      * set up.
01797      *
01798      * @return true if read authorization is enabled and false otherwise.
01799      */
01800     bool isReadAuthorizationEnabled() const
01801     {
01802         return readAuthorizationCallback;
01803     }
01804 
01805     /**
01806      * Check whether write authorization is enabled.
01807      *
01808      * Write authorization is enabled when a write authorization event handler is
01809      * set up.
01810      *
01811      * @return true if write authorization is enabled, false otherwise.
01812      */
01813     bool isWriteAuthorizationEnabled() const
01814     {
01815         return writeAuthorizationCallback;
01816     }
01817 
01818     /**
01819      * Get this characteristic's descriptor at a specific index.
01820      *
01821      * @param[in] index The index of the descriptor to get.
01822      *
01823      * @return A pointer the requested descriptor if @p index is within the
01824      * range of the descriptor array or NULL otherwise.
01825      */
01826     GattAttribute *getDescriptor(uint8_t index)
01827     {
01828         if (index >= _descriptorCount) {
01829             return NULL;
01830         }
01831 
01832         return _descriptors[index];
01833     }
01834 
01835 private:
01836 
01837     /**
01838      * Loosely convert a SecurityManager::SecurityMode_t into a
01839      * SecurityRequirement_t.
01840      *
01841      * @param[in] mode The security mode to convert
01842      *
01843      * @return The security requirement equivalent to the security mode in input.
01844      */
01845     SecurityRequirement_t SecurityModeToAttSecurity(
01846         SecurityManager::SecurityMode_t mode
01847     ) {
01848         switch(mode) {
01849             case SecurityManager::SECURITY_MODE_ENCRYPTION_OPEN_LINK:
01850             case SecurityManager::SECURITY_MODE_NO_ACCESS:
01851                 // assuming access is managed by property and orthogonal to
01852                 // security mode ...
01853                 return SecurityRequirement_t::NONE;
01854 
01855             case SecurityManager::SECURITY_MODE_ENCRYPTION_NO_MITM:
01856             case SecurityManager::SECURITY_MODE_SIGNED_NO_MITM:
01857                 return SecurityRequirement_t::UNAUTHENTICATED;
01858 
01859             case SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM:
01860             case SecurityManager::SECURITY_MODE_SIGNED_WITH_MITM:
01861                 return SecurityRequirement_t::AUTHENTICATED;
01862 
01863             default:
01864                 // should not happens; makes the compiler happy.
01865                 return SecurityRequirement_t::NONE;
01866         }
01867     }
01868 
01869     /**
01870      * Attribute that contains the actual value of this characteristic.
01871      */
01872     GattAttribute _valueAttribute;
01873 
01874     /**
01875      * The characteristic's properties. Refer to
01876      * GattCharacteristic::Properties_t.
01877      */
01878     uint8_t _properties;
01879 
01880     /**
01881      * The characteristic's descriptor attributes.
01882      */
01883     GattAttribute **_descriptors;
01884 
01885     /**
01886      * The number of descriptors in this characteristic.
01887      */
01888     uint8_t _descriptorCount;
01889 
01890     /**
01891      * The registered callback handler for read authorization reply.
01892      */
01893     FunctionPointerWithContext<GattReadAuthCallbackParams *> 
01894         readAuthorizationCallback;
01895 
01896     /**
01897      * The registered callback handler for write authorization reply.
01898      */
01899     FunctionPointerWithContext<GattWriteAuthCallbackParams *> 
01900         writeAuthorizationCallback;
01901 
01902     /**
01903      * Security requirements of update operations.
01904      *
01905      * The peer must meet the security requirement to enable, disable and
01906      * receive updates
01907      */
01908     uint8_t _update_security: SecurityRequirement_t::size;
01909 
01910 private:
01911     /* Disallow copy and assignment. */
01912     GattCharacteristic(const GattCharacteristic &);
01913     GattCharacteristic& operator=(const GattCharacteristic &);
01914 };
01915 
01916 /**
01917  * Helper class that represents a read only GattCharacteristic.
01918  */
01919 template <typename T>
01920 class ReadOnlyGattCharacteristic : public GattCharacteristic {
01921 public:
01922     /**
01923      * Construct a ReadOnlyGattCharacteristic.
01924      *
01925      * @param[in] uuid The characteristic's UUID.
01926      * @param[in] valuePtr Pointer to the characteristic's initial value. The
01927      * pointer is reinterpreted as a pointer to an uint8_t buffer.
01928      * @param[in] additionalProperties Additional characteristic properties. By
01929      * default, the properties are set to
01930      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
01931      * @param[in] descriptors An array of pointers to descriptors to be added
01932      * to the new characteristic.
01933      * @param[in] numDescriptors The total number of descriptors in @p
01934      * descriptors.
01935      *
01936      * @note Instances of ReadOnlyGattCharacteristic have a fixed length
01937      * attribute value that equals sizeof(T). For a variable length alternative,
01938      * use GattCharacteristic directly.
01939      */
01940     ReadOnlyGattCharacteristic<T>(
01941         const UUID &uuid,
01942         T *valuePtr,
01943         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
01944         GattAttribute *descriptors[] = NULL,
01945         unsigned numDescriptors = 0
01946     ) : GattCharacteristic(
01947         uuid,
01948         reinterpret_cast<uint8_t *>(valuePtr),
01949         sizeof(T),
01950         sizeof(T),
01951         BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
01952         descriptors,
01953         numDescriptors,
01954         false
01955     ) {
01956     }
01957 };
01958 
01959 /**
01960  * Helper class that represents a write only GattCharacteristic.
01961  */
01962 template <typename T>
01963 class WriteOnlyGattCharacteristic : public GattCharacteristic {
01964 public:
01965     /**
01966      * Construct a WriteOnlyGattCharacteristic.
01967      *
01968      * @param[in] uuid The characteristic's UUID.
01969      * @param[in] valuePtr Pointer to the characteristic's initial value. The
01970      * pointer is reinterpreted as a pointer to an uint8_t buffer.
01971      * @param[in] additionalProperties Additional characteristic properties. By
01972      * default, the properties are set to
01973      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
01974      * @param[in] descriptors An array of pointers to descriptors to be added to
01975      * the new characteristic.
01976      * @param[in] numDescriptors The total number of descriptors in @p
01977      * descriptors.
01978      *
01979      * @note Instances of WriteOnlyGattCharacteristic have variable length
01980      * attribute value with maximum size equal to sizeof(T). For a fixed length
01981      * alternative, use GattCharacteristic directly.
01982      */
01983     WriteOnlyGattCharacteristic<T>(
01984         const UUID &uuid,
01985         T *valuePtr,
01986         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
01987         GattAttribute *descriptors[] = NULL,
01988         unsigned numDescriptors = 0
01989     ) : GattCharacteristic(
01990         uuid,
01991         reinterpret_cast<uint8_t *>(valuePtr),
01992         sizeof(T),
01993         sizeof(T),
01994         BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
01995         descriptors,
01996         numDescriptors
01997     ) {
01998     }
01999 };
02000 
02001 /**
02002  * Helper class that represents a readable and writable GattCharacteristic.
02003  */
02004 template <typename T>
02005 class ReadWriteGattCharacteristic : public GattCharacteristic {
02006 public:
02007     /**
02008      * Construct a ReadWriteGattCharacteristic.
02009      *
02010      * @param[in] uuid The characteristic's UUID.
02011      * @param[in] valuePtr Pointer to the characteristic's initial value. The
02012      * pointer is reinterpreted as a pointer to an uint8_t buffer.
02013      * @param[in] additionalProperties Additional characteristic properties. By
02014      * default, the properties are set to
02015      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE and
02016      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02017      * @param[in] descriptors An array of pointers to descriptors to be added to
02018      * the new characteristic.
02019      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02020      *
02021      * @note Instances of ReadWriteGattCharacteristic have variable length
02022      * attribute value with maximum size equal to sizeof(T). For a fixed length
02023      * alternative, use GattCharacteristic directly.
02024      */
02025     ReadWriteGattCharacteristic<T>(
02026         const UUID &uuid,
02027         T *valuePtr,
02028         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02029         GattAttribute *descriptors[] = NULL,
02030         unsigned numDescriptors = 0
02031     ) : GattCharacteristic(
02032         uuid,
02033         reinterpret_cast<uint8_t *>(valuePtr),
02034         sizeof(T),
02035         sizeof(T),
02036         BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02037         descriptors,
02038         numDescriptors
02039     ) {
02040     }
02041 };
02042 
02043 /**
02044  * Helper class that represents a write-only GattCharacteristic with an array
02045  * value.
02046  */
02047 template <typename T, unsigned NUM_ELEMENTS>
02048 class WriteOnlyArrayGattCharacteristic : public GattCharacteristic {
02049 public:
02050     /**
02051      * Construct a WriteOnlyGattCharacteristic.
02052      *
02053      * @param[in] uuid The characteristic's UUID.
02054      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02055      * the characteristic's initial value. The pointer is reinterpreted as a
02056      * pointer to an uint8_t buffer.
02057      * @param[in] additionalProperties Additional characteristic properties. By
02058      * default, the properties are set to
02059      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
02060      * @param[in] descriptors An array of pointers to descriptors to be added to
02061      * the new characteristic.
02062      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02063      *
02064      * @note Instances of WriteOnlyGattCharacteristic have variable length
02065      * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
02066      * For a fixed length alternative, use GattCharacteristic directly.
02067      */
02068     WriteOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(
02069         const UUID &uuid,
02070         T valuePtr[NUM_ELEMENTS],
02071         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02072         GattAttribute *descriptors[] = NULL,
02073         unsigned numDescriptors = 0
02074     ) : GattCharacteristic(
02075         uuid,
02076         reinterpret_cast<uint8_t *>(valuePtr),
02077         sizeof(T) * NUM_ELEMENTS,
02078         sizeof(T) * NUM_ELEMENTS,
02079         BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02080         descriptors,
02081         numDescriptors
02082     ) {
02083     }
02084 };
02085 
02086 /**
02087  * Helper class that represents a read-only GattCharacteristic with an array
02088  * value.
02089  */
02090 template <typename T, unsigned NUM_ELEMENTS>
02091 class ReadOnlyArrayGattCharacteristic : public GattCharacteristic {
02092 public:
02093     /**
02094      * Construct a ReadOnlyGattCharacteristic.
02095      *
02096      * @param[in] uuid The characteristic's UUID.
02097      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02098      * the characteristic's initial value. The pointer is reinterpreted as a
02099      * pointer to an uint8_t buffer.
02100      * @param[in] additionalProperties Additional characteristic properties. By
02101      * default, the properties are set to
02102      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02103      * @param[in] descriptors An array of pointers to descriptors to be added to
02104      * the new characteristic.
02105      * @param[in] numDescriptors The total number of descriptors in @p
02106      * descriptors.
02107      *
02108      * @note Instances of ReadOnlyGattCharacteristic have fixed length
02109      * attribute value that equals sizeof(T) * NUM_ELEMENTS. For a variable
02110      * length alternative, use GattCharacteristic directly.
02111      */
02112     ReadOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(
02113         const UUID    &uuid,
02114         T valuePtr[NUM_ELEMENTS],
02115         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02116         GattAttribute *descriptors[] = NULL,
02117         unsigned numDescriptors = 0
02118     ) : GattCharacteristic(
02119         uuid,
02120         reinterpret_cast<uint8_t *>(valuePtr),
02121         sizeof(T) * NUM_ELEMENTS,
02122         sizeof(T) * NUM_ELEMENTS,
02123         BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
02124         descriptors,
02125         numDescriptors,
02126         false
02127     ) {
02128     }
02129 };
02130 
02131 /**
02132  * Helper class that represents a readable and writable GattCharacteristic with
02133  * an array value.
02134  */
02135 template <typename T, unsigned NUM_ELEMENTS>
02136 class ReadWriteArrayGattCharacteristic : public GattCharacteristic {
02137 public:
02138     /**
02139      * Construct a ReadWriteGattCharacteristic.
02140      *
02141      * @param[in] uuid The characteristic's UUID.
02142      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02143      * the characteristic's initial value. The pointer is reinterpreted as a
02144      * pointer to an uint8_t buffer.
02145      * @param[in] additionalProperties Additional characteristic properties. By
02146      * default, the properties are set to
02147      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
02148      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02149      * @param[in] descriptors An array of pointers to descriptors to be added to
02150      * the new characteristic.
02151      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02152      *
02153      * @note Instances of ReadWriteGattCharacteristic have variable length
02154      * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
02155      * For a fixed length alternative, use GattCharacteristic directly.
02156      */
02157     ReadWriteArrayGattCharacteristic<T, NUM_ELEMENTS>(
02158         const UUID    &uuid,
02159         T valuePtr[NUM_ELEMENTS],
02160         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02161         GattAttribute *descriptors[] = NULL,
02162         unsigned numDescriptors = 0
02163     ) : GattCharacteristic(
02164         uuid,
02165         reinterpret_cast<uint8_t *>(valuePtr),
02166         sizeof(T) * NUM_ELEMENTS,
02167         sizeof(T) * NUM_ELEMENTS,
02168         BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02169         descriptors,
02170         numDescriptors
02171     ) {
02172     }
02173 };
02174 
02175 /**
02176  * @}
02177  * @}
02178  * @}
02179  */
02180 
02181 #endif /* ifndef __GATT_CHARACTERISTIC_H__ */