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 "ble/Gap.h"
00021 #include "ble/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_FLUX_WEBER = 0x272C,
00705 
00706         /**
00707          * Magnetic flux density, tesla.
00708          */
00709         BLE_GATT_UNIT_MAGNETIC_FLUX_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 #if BLE_FEATURE_SECURITY
01418         // signed writes requires at least an unauthenticated CSRK or an
01419         // unauthenticated ltk if the link is encrypted.
01420         if (_properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES) {
01421             _valueAttribute.setWriteSecurityRequirement(
01422                 SecurityRequirement_t::UNAUTHENTICATED
01423             );
01424         }
01425 #endif // BLE_FEATURE_SECURITY
01426     }
01427 
01428 public:
01429     /**
01430      * Set up the minimum security (mode and level) requirements for access to
01431      * the characteristic's value attribute.
01432      *
01433      * @param[in] securityMode Can be one of encryption or signing, with or
01434      * without protection for man in the middle attacks (MITM).
01435      *
01436      * @deprecated Fine grained security check has been added to with mbed OS
01437      * 5.9. It is possible to set independently security requirements for read,
01438      * write and update operations. In the meantime SecurityManager::SecurityMode_t
01439      * is not used anymore to represent security requirements as it maps
01440      * incorrectly the Bluetooth standard.
01441      */
01442     MBED_DEPRECATED_SINCE(
01443         "mbed-os-5.9",
01444         "Use setWriteSecurityRequirements, setReadSecurityRequirements and "
01445         "setUpdateSecurityRequirements"
01446     )
01447     void requireSecurity(SecurityManager::SecurityMode_t securityMode)
01448     {
01449         SecurityRequirement_t sec_requirements = SecurityModeToAttSecurity(securityMode);
01450 
01451         _valueAttribute.setReadSecurityRequirement(sec_requirements);
01452         _valueAttribute.setWriteSecurityRequirement(sec_requirements);
01453         _update_security = sec_requirements.value();
01454     }
01455 
01456     /**
01457      * Set all security requirements of the characteristic.
01458      *
01459      * @param read_security The security requirement of the read operations.
01460      * @param write_security The security requirement of write operations.
01461      * @param update_security The security requirement of update operations.
01462      */
01463     void setSecurityRequirements(
01464         SecurityRequirement_t read_security,
01465         SecurityRequirement_t write_security,
01466         SecurityRequirement_t update_security
01467     ) {
01468         setReadSecurityRequirement(read_security);
01469         setWriteSecurityRequirement(write_security);
01470         setUpdateSecurityRequirement(update_security);
01471     }
01472 
01473     /**
01474      * Set the security of the read operation.
01475      *
01476      * @param[in] security The security requirement of the read operation.
01477      */
01478     void setReadSecurityRequirement(SecurityRequirement_t security)
01479     {
01480         _valueAttribute.setReadSecurityRequirement(security);
01481     }
01482 
01483     /**
01484      * Get the security requirement of the read operation.
01485      *
01486      * @return The security requirement of the read operation.
01487      */
01488     SecurityRequirement_t getReadSecurityRequirement() const
01489     {
01490         return _valueAttribute.getReadSecurityRequirement();
01491     }
01492 
01493     /**
01494      * Set the security requirement of the write operations.
01495      *
01496      * @note If the signed write flag is set in the characteristic properties
01497      * then the security requirement applied to write operation must be either
01498      * AUTHENTICATED or UNAUTHENTICATED. Security requirements NONE and
01499      * SC_AUTHENTICATED are not applicable to signing operation.
01500      *
01501      * @param[in] security The security requirement of write operations.
01502      */
01503     void setWriteSecurityRequirement(SecurityRequirement_t security)
01504     {
01505 #if BLE_FEATURE_SECURITY
01506         MBED_ASSERT(
01507             ((_properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES) &&
01508             ((security == SecurityRequirement_t::NONE) ||
01509             (security == SecurityRequirement_t::SC_AUTHENTICATED))) == false
01510         );
01511 #endif // BLE_FEATURE_SECURITY
01512         _valueAttribute.setWriteSecurityRequirement(security);
01513     }
01514 
01515     /**
01516      * Get the security requirement of write operations.
01517      *
01518      * @return The security requirement of write operations.
01519      */
01520     SecurityRequirement_t getWriteSecurityRequirement() const
01521     {
01522         return _valueAttribute.getWriteSecurityRequirement();
01523     }
01524 
01525     /**
01526      * Set the security requirement of update operations.
01527      *
01528      * @note This security requirement is also applied to the write operation of
01529      * the Client Characteristic Configuration Descriptor.
01530      *
01531      * @param[in] security The security requirement that must be met to send
01532      * updates and accept write of the CCCD.
01533      */
01534     void setUpdateSecurityRequirement(SecurityRequirement_t security)
01535     {
01536         _update_security = security.value();
01537     }
01538 
01539     /**
01540      * Get the security requirement of update operations.
01541      *
01542      * @note This security requirement is also applied to the write operation of
01543      * the Client Characteristic Configuration Descriptor.
01544      *
01545      * @return The security requirement that must be met to send updates and
01546      * accept write of the CCCD.
01547      */
01548     SecurityRequirement_t getUpdateSecurityRequirement() const
01549     {
01550         return static_cast<SecurityRequirement_t::type>(_update_security);
01551     }
01552 
01553 public:
01554     /**
01555      * Register a callback handling client's write requests or commands.
01556      *
01557      * The callback registered is invoked when the client attempts to write the
01558      * characteristic value; the event handler can accept or reject the write
01559      * request with the appropriate error code.
01560      *
01561      * @param[in] callback Event handler being registered.
01562      */
01563     void setWriteAuthorizationCallback(
01564         void (*callback)(GattWriteAuthCallbackParams *)
01565     ) {
01566         writeAuthorizationCallback.attach(callback);
01567     }
01568 
01569     /**
01570      * Register a callback handling client's write requests or commands.
01571      *
01572      * The callback registered is invoked when the client attempts to write the
01573      * characteristic value; the event handler can accept or reject the write
01574      * request with the appropriate error code.
01575      *
01576      * @param[in] object Pointer to the object of a class defining the event
01577      * handler (@p member). It must remain valid for the lifetime of the
01578      * GattCharacteristic.
01579      * @param[in] member The member function that handles the write event.
01580      */
01581     template <typename T>
01582     void setWriteAuthorizationCallback(
01583         T *object,
01584         void (T::*member)(GattWriteAuthCallbackParams *)
01585     ) {
01586         writeAuthorizationCallback.attach(object, member);
01587     }
01588 
01589     /**
01590      * Register the read requests event handler.
01591      *
01592      * The callback registered is invoked when the client attempts to read the
01593      * characteristic value; the event handler can accept or reject the read
01594      * request with the appropriate error code. It can also set specific outgoing
01595      * data.
01596      *
01597      * @param[in] callback Event handler being registered.
01598      */
01599     void setReadAuthorizationCallback(
01600         void (*callback)(GattReadAuthCallbackParams *)
01601     ) {
01602         readAuthorizationCallback.attach(callback);
01603     }
01604 
01605     /**
01606      * Register the read requests event handler.
01607      *
01608      * The callback registered is invoked when the client attempts to read the
01609      * characteristic value; the event handler can accept or reject the read
01610      * request with the appropriate error code. It can also set specific outgoing
01611      * data.
01612      *
01613      * @param[in] object Pointer to the object of a class defining the event
01614      * handler (@p member). It must remain valid for the lifetime of the
01615      * GattCharacteristic.
01616      * @param[in] member The member function that handles the read event.
01617      */
01618     template <typename T>
01619     void setReadAuthorizationCallback(
01620         T *object,
01621         void (T::*member)(GattReadAuthCallbackParams *)
01622     ) {
01623         readAuthorizationCallback.attach(object, member);
01624     }
01625 
01626     /**
01627      * Invoke the write authorization callback.
01628      *
01629      * This function is a helper that calls the registered write handler to
01630      * determine the authorization reply for a write request.
01631      *
01632      * @attention This function is not meant to be called by user code.
01633      *
01634      * @param[in] params Context of the write-auth request; it contains an
01635      * out-parameter used as a reply.
01636      *
01637      * @return A GattAuthCallbackReply_t value indicating whether authorization
01638      * is granted.
01639      */
01640     GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params)
01641     {
01642         if (!isWriteAuthorizationEnabled()) {
01643             return AUTH_CALLBACK_REPLY_SUCCESS;
01644         }
01645 
01646         /* Initialized to no-error by default. */
01647         params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS;
01648         writeAuthorizationCallback.call(params);
01649         return params->authorizationReply;
01650     }
01651 
01652     /**
01653      * Invoke the read authorization callback.
01654      *
01655      * This function is a helper that calls the registered read handler to
01656      * determine the authorization reply for a read request.
01657      *
01658      * @attention This function is not meant to be called by user code.
01659      *
01660      * @param[in] params Context of the read-auth request; it contains an
01661      * out-parameter used as a reply and the handler can fill it with outgoing
01662      * data.
01663      *
01664      * @return A GattAuthCallbackReply_t value indicating whether authorization
01665      * is granted.
01666      *
01667      * @note If the read request is approved and params->data remains NULL, then
01668      * the current characteristic value is used in the read response payload.
01669      *
01670      * @note If the read is approved, the event handler can specify an outgoing
01671      * value directly with the help of the fields
01672      * GattReadAuthCallbackParams::data and GattReadAuthCallbackParams::len.
01673      */
01674     GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params)
01675     {
01676         if (!isReadAuthorizationEnabled()) {
01677             return AUTH_CALLBACK_REPLY_SUCCESS;
01678         }
01679 
01680         /* Initialized to no-error by default. */
01681         params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS;
01682         readAuthorizationCallback.call(params);
01683         return params->authorizationReply;
01684     }
01685 
01686 public:
01687     /**
01688      * Get the characteristic's value attribute.
01689      *
01690      * @return A reference to the characteristic's value attribute.
01691      */
01692     GattAttribute& getValueAttribute()
01693     {
01694         return _valueAttribute;
01695     }
01696 
01697     /**
01698      * Get the characteristic's value attribute.
01699      *
01700      * @return A const reference to the characteristic's value attribute.
01701      */
01702     const GattAttribute& getValueAttribute() const
01703     {
01704         return _valueAttribute;
01705     }
01706 
01707     /**
01708      * Get the characteristic's value attribute handle in the ATT table.
01709      *
01710      * @return The value attribute handle.
01711      *
01712      * @note The underlying BLE stack assigns the attribute handle when the
01713      * enclosing service is added.
01714      */
01715     GattAttribute::Handle_t getValueHandle(void) const
01716     {
01717         return getValueAttribute().getHandle();
01718     }
01719 
01720     /**
01721      * Get the characteristic's properties.
01722      *
01723      * @note Refer to GattCharacteristic::Properties_t.
01724      *
01725      * @return The characteristic's properties.
01726      */
01727     uint8_t getProperties(void) const
01728     {
01729         return _properties;
01730     }
01731 
01732     /**
01733      * Get the characteristic's required security.
01734      *
01735      * @return The characteristic's required security.
01736      *
01737      * @deprecated Fine grained security check has been added to with mbed OS
01738      * 5.9. It is possible to set independently security requirements for read,
01739      * write and update operations. In the meantime SecurityManager::SecurityMode_t
01740      * is not used anymore to represent security requirements as it maps
01741      * incorrectly the Bluetooth standard.
01742      */
01743     MBED_DEPRECATED_SINCE(
01744         "mbed-os-5.9",
01745         "Use getWriteSecurityRequirements, getReadSecurityRequirements and "
01746         "getUpdateSecurityRequirements"
01747     )
01748     SecurityManager::SecurityMode_t getRequiredSecurity() const
01749     {
01750         SecurityRequirement_t max_sec = std::max(
01751             std::max(
01752                 getReadSecurityRequirement(),
01753                 getWriteSecurityRequirement()
01754             ),
01755             getUpdateSecurityRequirement()
01756         );
01757 
01758         bool needs_signing =
01759             _properties & BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES;
01760 
01761         switch(max_sec.value()) {
01762             case SecurityRequirement_t::NONE:
01763                 MBED_ASSERT(needs_signing == false);
01764                 return SecurityManager::SECURITY_MODE_ENCRYPTION_OPEN_LINK;
01765 #if BLE_FEATURE_SECURITY
01766             case SecurityRequirement_t::UNAUTHENTICATED:
01767                 return (needs_signing) ?
01768                     SecurityManager::SECURITY_MODE_SIGNED_NO_MITM :
01769                     SecurityManager::SECURITY_MODE_ENCRYPTION_NO_MITM;
01770 
01771             case SecurityRequirement_t::AUTHENTICATED:
01772                 return (needs_signing) ?
01773                     SecurityManager::SECURITY_MODE_SIGNED_WITH_MITM :
01774                     SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM;
01775 #if BLE_FEATURE_SECURE_CONNECTIONS
01776             case SecurityRequirement_t::SC_AUTHENTICATED:
01777                 MBED_ASSERT(needs_signing == false);
01778                 // fallback to encryption with MITM
01779                 return SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM;
01780 #endif // BLE_FEATURE_SECURE_CONNECTIONS
01781 #endif // BLE_FEATURE_SECURITY
01782             default:
01783                 MBED_ASSERT(false);
01784                 return SecurityManager::SECURITY_MODE_NO_ACCESS;
01785         }
01786     }
01787 
01788     /**
01789      * Get the total number of descriptors within this characteristic.
01790      *
01791      * @return The total number of descriptors.
01792      */
01793     uint8_t getDescriptorCount(void) const
01794     {
01795         return _descriptorCount;
01796     }
01797 
01798     /**
01799      * Check whether read authorization is enabled.
01800      *
01801      * Read authorization is enabled when a read authorization event handler is
01802      * set up.
01803      *
01804      * @return true if read authorization is enabled and false otherwise.
01805      */
01806     bool isReadAuthorizationEnabled() const
01807     {
01808         return readAuthorizationCallback;
01809     }
01810 
01811     /**
01812      * Check whether write authorization is enabled.
01813      *
01814      * Write authorization is enabled when a write authorization event handler is
01815      * set up.
01816      *
01817      * @return true if write authorization is enabled, false otherwise.
01818      */
01819     bool isWriteAuthorizationEnabled() const
01820     {
01821         return writeAuthorizationCallback;
01822     }
01823 
01824     /**
01825      * Get this characteristic's descriptor at a specific index.
01826      *
01827      * @param[in] index The index of the descriptor to get.
01828      *
01829      * @return A pointer the requested descriptor if @p index is within the
01830      * range of the descriptor array or NULL otherwise.
01831      */
01832     GattAttribute *getDescriptor(uint8_t index)
01833     {
01834         if (index >= _descriptorCount) {
01835             return NULL;
01836         }
01837 
01838         return _descriptors[index];
01839     }
01840 
01841 private:
01842 
01843     /**
01844      * Loosely convert a SecurityManager::SecurityMode_t into a
01845      * SecurityRequirement_t.
01846      *
01847      * @param[in] mode The security mode to convert
01848      *
01849      * @return The security requirement equivalent to the security mode in input.
01850      */
01851     SecurityRequirement_t SecurityModeToAttSecurity(
01852         SecurityManager::SecurityMode_t mode
01853     ) {
01854         switch(mode) {
01855             case SecurityManager::SECURITY_MODE_ENCRYPTION_OPEN_LINK:
01856             case SecurityManager::SECURITY_MODE_NO_ACCESS:
01857                 // assuming access is managed by property and orthogonal to
01858                 // security mode ...
01859                 return SecurityRequirement_t::NONE;
01860 #if BLE_FEATURE_SECURITY
01861             case SecurityManager::SECURITY_MODE_ENCRYPTION_NO_MITM:
01862 #if BLE_FEATURE_SIGNING
01863             case SecurityManager::SECURITY_MODE_SIGNED_NO_MITM:
01864 #endif
01865                 return SecurityRequirement_t::UNAUTHENTICATED;
01866 
01867             case SecurityManager::SECURITY_MODE_ENCRYPTION_WITH_MITM:
01868 #if BLE_FEATURE_SIGNING
01869             case SecurityManager::SECURITY_MODE_SIGNED_WITH_MITM:
01870 #endif
01871                 return SecurityRequirement_t::AUTHENTICATED;
01872 #endif // BLE_FEATURE_SECURITY
01873             default:
01874                 // should not happens; makes the compiler happy.
01875                 return SecurityRequirement_t::NONE;
01876         }
01877     }
01878 
01879     /**
01880      * Attribute that contains the actual value of this characteristic.
01881      */
01882     GattAttribute _valueAttribute;
01883 
01884     /**
01885      * The characteristic's properties. Refer to
01886      * GattCharacteristic::Properties_t.
01887      */
01888     uint8_t _properties;
01889 
01890     /**
01891      * The characteristic's descriptor attributes.
01892      */
01893     GattAttribute **_descriptors;
01894 
01895     /**
01896      * The number of descriptors in this characteristic.
01897      */
01898     uint8_t _descriptorCount;
01899 
01900     /**
01901      * The registered callback handler for read authorization reply.
01902      */
01903     FunctionPointerWithContext<GattReadAuthCallbackParams *> 
01904         readAuthorizationCallback;
01905 
01906     /**
01907      * The registered callback handler for write authorization reply.
01908      */
01909     FunctionPointerWithContext<GattWriteAuthCallbackParams *> 
01910         writeAuthorizationCallback;
01911 
01912     /**
01913      * Security requirements of update operations.
01914      *
01915      * The peer must meet the security requirement to enable, disable and
01916      * receive updates
01917      */
01918     uint8_t _update_security: SecurityRequirement_t::size;
01919 
01920 private:
01921     /* Disallow copy and assignment. */
01922     GattCharacteristic(const GattCharacteristic &);
01923     GattCharacteristic& operator=(const GattCharacteristic &);
01924 };
01925 
01926 /**
01927  * Helper class that represents a read only GattCharacteristic.
01928  */
01929 template <typename T>
01930 class ReadOnlyGattCharacteristic : public GattCharacteristic {
01931 public:
01932     /**
01933      * Construct a ReadOnlyGattCharacteristic.
01934      *
01935      * @param[in] uuid The characteristic's UUID.
01936      * @param[in] valuePtr Pointer to the characteristic's initial value. The
01937      * pointer is reinterpreted as a pointer to an uint8_t buffer.
01938      * @param[in] additionalProperties Additional characteristic properties. By
01939      * default, the properties are set to
01940      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
01941      * @param[in] descriptors An array of pointers to descriptors to be added
01942      * to the new characteristic.
01943      * @param[in] numDescriptors The total number of descriptors in @p
01944      * descriptors.
01945      *
01946      * @note Instances of ReadOnlyGattCharacteristic have a fixed length
01947      * attribute value that equals sizeof(T). For a variable length alternative,
01948      * use GattCharacteristic directly.
01949      */
01950     ReadOnlyGattCharacteristic<T>(
01951         const UUID &uuid,
01952         T *valuePtr,
01953         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
01954         GattAttribute *descriptors[] = NULL,
01955         unsigned numDescriptors = 0
01956     ) : GattCharacteristic(
01957         uuid,
01958         reinterpret_cast<uint8_t *>(valuePtr),
01959         sizeof(T),
01960         sizeof(T),
01961         BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
01962         descriptors,
01963         numDescriptors,
01964         false
01965     ) {
01966     }
01967 };
01968 
01969 /**
01970  * Helper class that represents a write only GattCharacteristic.
01971  */
01972 template <typename T>
01973 class WriteOnlyGattCharacteristic : public GattCharacteristic {
01974 public:
01975     /**
01976      * Construct a WriteOnlyGattCharacteristic.
01977      *
01978      * @param[in] uuid The characteristic's UUID.
01979      * @param[in] valuePtr Pointer to the characteristic's initial value. The
01980      * pointer is reinterpreted as a pointer to an uint8_t buffer.
01981      * @param[in] additionalProperties Additional characteristic properties. By
01982      * default, the properties are set to
01983      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
01984      * @param[in] descriptors An array of pointers to descriptors to be added to
01985      * the new characteristic.
01986      * @param[in] numDescriptors The total number of descriptors in @p
01987      * descriptors.
01988      *
01989      * @note Instances of WriteOnlyGattCharacteristic have variable length
01990      * attribute value with maximum size equal to sizeof(T). For a fixed length
01991      * alternative, use GattCharacteristic directly.
01992      */
01993     WriteOnlyGattCharacteristic<T>(
01994         const UUID &uuid,
01995         T *valuePtr,
01996         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
01997         GattAttribute *descriptors[] = NULL,
01998         unsigned numDescriptors = 0
01999     ) : GattCharacteristic(
02000         uuid,
02001         reinterpret_cast<uint8_t *>(valuePtr),
02002         sizeof(T),
02003         sizeof(T),
02004         BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02005         descriptors,
02006         numDescriptors
02007     ) {
02008     }
02009 };
02010 
02011 /**
02012  * Helper class that represents a readable and writable GattCharacteristic.
02013  */
02014 template <typename T>
02015 class ReadWriteGattCharacteristic : public GattCharacteristic {
02016 public:
02017     /**
02018      * Construct a ReadWriteGattCharacteristic.
02019      *
02020      * @param[in] uuid The characteristic's UUID.
02021      * @param[in] valuePtr Pointer to the characteristic's initial value. The
02022      * pointer is reinterpreted as a pointer to an uint8_t buffer.
02023      * @param[in] additionalProperties Additional characteristic properties. By
02024      * default, the properties are set to
02025      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE and
02026      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02027      * @param[in] descriptors An array of pointers to descriptors to be added to
02028      * the new characteristic.
02029      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02030      *
02031      * @note Instances of ReadWriteGattCharacteristic have variable length
02032      * attribute value with maximum size equal to sizeof(T). For a fixed length
02033      * alternative, use GattCharacteristic directly.
02034      */
02035     ReadWriteGattCharacteristic<T>(
02036         const UUID &uuid,
02037         T *valuePtr,
02038         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02039         GattAttribute *descriptors[] = NULL,
02040         unsigned numDescriptors = 0
02041     ) : GattCharacteristic(
02042         uuid,
02043         reinterpret_cast<uint8_t *>(valuePtr),
02044         sizeof(T),
02045         sizeof(T),
02046         BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02047         descriptors,
02048         numDescriptors
02049     ) {
02050     }
02051 };
02052 
02053 /**
02054  * Helper class that represents a write-only GattCharacteristic with an array
02055  * value.
02056  */
02057 template <typename T, unsigned NUM_ELEMENTS>
02058 class WriteOnlyArrayGattCharacteristic : public GattCharacteristic {
02059 public:
02060     /**
02061      * Construct a WriteOnlyGattCharacteristic.
02062      *
02063      * @param[in] uuid The characteristic's UUID.
02064      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02065      * the characteristic's initial value. The pointer is reinterpreted as a
02066      * pointer to an uint8_t buffer.
02067      * @param[in] additionalProperties Additional characteristic properties. By
02068      * default, the properties are set to
02069      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
02070      * @param[in] descriptors An array of pointers to descriptors to be added to
02071      * the new characteristic.
02072      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02073      *
02074      * @note Instances of WriteOnlyGattCharacteristic have variable length
02075      * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
02076      * For a fixed length alternative, use GattCharacteristic directly.
02077      */
02078     WriteOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(
02079         const UUID &uuid,
02080         T valuePtr[NUM_ELEMENTS],
02081         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02082         GattAttribute *descriptors[] = NULL,
02083         unsigned numDescriptors = 0
02084     ) : GattCharacteristic(
02085         uuid,
02086         reinterpret_cast<uint8_t *>(valuePtr),
02087         sizeof(T) * NUM_ELEMENTS,
02088         sizeof(T) * NUM_ELEMENTS,
02089         BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02090         descriptors,
02091         numDescriptors
02092     ) {
02093     }
02094 };
02095 
02096 /**
02097  * Helper class that represents a read-only GattCharacteristic with an array
02098  * value.
02099  */
02100 template <typename T, unsigned NUM_ELEMENTS>
02101 class ReadOnlyArrayGattCharacteristic : public GattCharacteristic {
02102 public:
02103     /**
02104      * Construct a ReadOnlyGattCharacteristic.
02105      *
02106      * @param[in] uuid The characteristic's UUID.
02107      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02108      * the characteristic's initial value. The pointer is reinterpreted as a
02109      * pointer to an uint8_t buffer.
02110      * @param[in] additionalProperties Additional characteristic properties. By
02111      * default, the properties are set to
02112      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02113      * @param[in] descriptors An array of pointers to descriptors to be added to
02114      * the new characteristic.
02115      * @param[in] numDescriptors The total number of descriptors in @p
02116      * descriptors.
02117      *
02118      * @note Instances of ReadOnlyGattCharacteristic have fixed length
02119      * attribute value that equals sizeof(T) * NUM_ELEMENTS. For a variable
02120      * length alternative, use GattCharacteristic directly.
02121      */
02122     ReadOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(
02123         const UUID    &uuid,
02124         T valuePtr[NUM_ELEMENTS],
02125         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02126         GattAttribute *descriptors[] = NULL,
02127         unsigned numDescriptors = 0
02128     ) : GattCharacteristic(
02129         uuid,
02130         reinterpret_cast<uint8_t *>(valuePtr),
02131         sizeof(T) * NUM_ELEMENTS,
02132         sizeof(T) * NUM_ELEMENTS,
02133         BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties,
02134         descriptors,
02135         numDescriptors,
02136         false
02137     ) {
02138     }
02139 };
02140 
02141 /**
02142  * Helper class that represents a readable and writable GattCharacteristic with
02143  * an array value.
02144  */
02145 template <typename T, unsigned NUM_ELEMENTS>
02146 class ReadWriteArrayGattCharacteristic : public GattCharacteristic {
02147 public:
02148     /**
02149      * Construct a ReadWriteGattCharacteristic.
02150      *
02151      * @param[in] uuid The characteristic's UUID.
02152      * @param[in] valuePtr Pointer to an array of length NUM_ELEMENTS containing
02153      * the characteristic's initial value. The pointer is reinterpreted as a
02154      * pointer to an uint8_t buffer.
02155      * @param[in] additionalProperties Additional characteristic properties. By
02156      * default, the properties are set to
02157      * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
02158      * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
02159      * @param[in] descriptors An array of pointers to descriptors to be added to
02160      * the new characteristic.
02161      * @param[in] numDescriptors The total number of descriptors in @p descriptors.
02162      *
02163      * @note Instances of ReadWriteGattCharacteristic have variable length
02164      * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
02165      * For a fixed length alternative, use GattCharacteristic directly.
02166      */
02167     ReadWriteArrayGattCharacteristic<T, NUM_ELEMENTS>(
02168         const UUID    &uuid,
02169         T valuePtr[NUM_ELEMENTS],
02170         uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
02171         GattAttribute *descriptors[] = NULL,
02172         unsigned numDescriptors = 0
02173     ) : GattCharacteristic(
02174         uuid,
02175         reinterpret_cast<uint8_t *>(valuePtr),
02176         sizeof(T) * NUM_ELEMENTS,
02177         sizeof(T) * NUM_ELEMENTS,
02178         BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties,
02179         descriptors,
02180         numDescriptors
02181     ) {
02182     }
02183 };
02184 
02185 /**
02186  * @}
02187  * @}
02188  * @}
02189  */
02190 
02191 #endif /* ifndef __GATT_CHARACTERISTIC_H__ */