EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

features/FEATURE_BLE/ble/DiscoveredCharacteristic.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

UserRevisionLine numberNew contents of line
be_bryan 0:b74591d5ab33 1 /* mbed Microcontroller Library
be_bryan 0:b74591d5ab33 2 * Copyright (c) 2006-2013 ARM Limited
be_bryan 0:b74591d5ab33 3 *
be_bryan 0:b74591d5ab33 4 * Licensed under the Apache License, Version 2.0 (the "License");
be_bryan 0:b74591d5ab33 5 * you may not use this file except in compliance with the License.
be_bryan 0:b74591d5ab33 6 * You may obtain a copy of the License at
be_bryan 0:b74591d5ab33 7 *
be_bryan 0:b74591d5ab33 8 * http://www.apache.org/licenses/LICENSE-2.0
be_bryan 0:b74591d5ab33 9 *
be_bryan 0:b74591d5ab33 10 * Unless required by applicable law or agreed to in writing, software
be_bryan 0:b74591d5ab33 11 * distributed under the License is distributed on an "AS IS" BASIS,
be_bryan 0:b74591d5ab33 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
be_bryan 0:b74591d5ab33 13 * See the License for the specific language governing permissions and
be_bryan 0:b74591d5ab33 14 * limitations under the License.
be_bryan 0:b74591d5ab33 15 */
be_bryan 0:b74591d5ab33 16
be_bryan 0:b74591d5ab33 17 #ifndef MBED_DISCOVERED_CHARACTERISTIC_H__
be_bryan 0:b74591d5ab33 18 #define MBED_DISCOVERED_CHARACTERISTIC_H__
be_bryan 0:b74591d5ab33 19
be_bryan 0:b74591d5ab33 20 #include "UUID.h"
be_bryan 0:b74591d5ab33 21 #include "Gap.h"
be_bryan 0:b74591d5ab33 22 #include "GattAttribute.h"
be_bryan 0:b74591d5ab33 23 #include "GattClient.h"
be_bryan 0:b74591d5ab33 24 #include "CharacteristicDescriptorDiscovery.h"
be_bryan 0:b74591d5ab33 25 #include "DiscoveredCharacteristicDescriptor.h"
be_bryan 0:b74591d5ab33 26
be_bryan 0:b74591d5ab33 27 /**
be_bryan 0:b74591d5ab33 28 * @addtogroup ble
be_bryan 0:b74591d5ab33 29 * @{
be_bryan 0:b74591d5ab33 30 * @addtogroup gatt
be_bryan 0:b74591d5ab33 31 * @{
be_bryan 0:b74591d5ab33 32 * @addtogroup client
be_bryan 0:b74591d5ab33 33 * @{
be_bryan 0:b74591d5ab33 34 */
be_bryan 0:b74591d5ab33 35
be_bryan 0:b74591d5ab33 36 /**
be_bryan 0:b74591d5ab33 37 * Representation of a characteristic discovered.
be_bryan 0:b74591d5ab33 38 *
be_bryan 0:b74591d5ab33 39 * The GattClient discovery procedure initiated with
be_bryan 0:b74591d5ab33 40 * GattClient::launchServiceDiscovery() generates instances of this class.
be_bryan 0:b74591d5ab33 41 *
be_bryan 0:b74591d5ab33 42 * It exposes the main attributes of the discovered characteristic:
be_bryan 0:b74591d5ab33 43 * - The UUID of the characteristic, it can be retrieved by a call to the
be_bryan 0:b74591d5ab33 44 * function getUUID(). This UUID is the type of the characteristic.
be_bryan 0:b74591d5ab33 45 * - Attribute Handles of the characteristic are present as the triplet
be_bryan 0:b74591d5ab33 46 * declaration handle, value handle and last handle. The value handle is
be_bryan 0:b74591d5ab33 47 * used to read or write the content of the characteristic.
be_bryan 0:b74591d5ab33 48 * - The properties contain the set of operations the characteristic can
be_bryan 0:b74591d5ab33 49 * handle, for instance being read or written.
be_bryan 0:b74591d5ab33 50 *
be_bryan 0:b74591d5ab33 51 * It important to note that the value of the characteristic - if it is
be_bryan 0:b74591d5ab33 52 * accessible - is not fetched at discovery time.
be_bryan 0:b74591d5ab33 53 *
be_bryan 0:b74591d5ab33 54 * The main operations the class offers are reading, writing and discovering
be_bryan 0:b74591d5ab33 55 * the descriptors of the characteristic discovered.
be_bryan 0:b74591d5ab33 56 *
be_bryan 0:b74591d5ab33 57 * Reading a discovered characteristic can be accomplished in two different
be_bryan 0:b74591d5ab33 58 * fashions:
be_bryan 0:b74591d5ab33 59 *
be_bryan 0:b74591d5ab33 60 * If the user has a callback registered for the data read operation in the
be_bryan 0:b74591d5ab33 61 * GattClient, then a call to the read(uint16_t) function will initiate a read of
be_bryan 0:b74591d5ab33 62 * the characteristic. Results of the operation will be pass on the callback
be_bryan 0:b74591d5ab33 63 * registered by GattClient::onDataRead(), which processes all the responses to
be_bryan 0:b74591d5ab33 64 * read requests. The read request for a given characteristic can be identified
be_bryan 0:b74591d5ab33 65 * by the connection handle and the attribute handle, which are present in
be_bryan 0:b74591d5ab33 66 * GattReadCallbackParams.
be_bryan 0:b74591d5ab33 67 *
be_bryan 0:b74591d5ab33 68 * Another overload (read(uint16_t, const GattClient::ReadCallback_t&)) of the
be_bryan 0:b74591d5ab33 69 * read function accepts a completion callback as a last parameter. That
be_bryan 0:b74591d5ab33 70 * completion callback will be invoked automatically once the response to the
be_bryan 0:b74591d5ab33 71 * read request for that given characteristic has been received. However,
be_bryan 0:b74591d5ab33 72 * convenience came at the expense of dynamic memory usage for the time of the
be_bryan 0:b74591d5ab33 73 * transaction.
be_bryan 0:b74591d5ab33 74 *
be_bryan 0:b74591d5ab33 75 * Similarly, two versions of the write() API are exposed. One where the user
be_bryan 0:b74591d5ab33 76 * has to register a callback handling write response through the function
be_bryan 0:b74591d5ab33 77 * GattClient::onDataWritten() and another one that accepts a completion
be_bryan 0:b74591d5ab33 78 * callback in input.
be_bryan 0:b74591d5ab33 79 *
be_bryan 0:b74591d5ab33 80 * It is also possible to send a write command, which is not acknowledged by the
be_bryan 0:b74591d5ab33 81 * peer server by using the function writeWoResponse().
be_bryan 0:b74591d5ab33 82 *
be_bryan 0:b74591d5ab33 83 * Finally, descriptors of the characteristic can be discovered by invoking the
be_bryan 0:b74591d5ab33 84 * function discoverDescriptors, which is shorthand for calling
be_bryan 0:b74591d5ab33 85 * GattClient::discoverCharacteristicDescriptors. That discovery is necessary to
be_bryan 0:b74591d5ab33 86 * enable or disable characteristic notification or indication that is achieved
be_bryan 0:b74591d5ab33 87 * by writing on the Client Characteristic Configuration Descriptor (CCCD).
be_bryan 0:b74591d5ab33 88 */
be_bryan 0:b74591d5ab33 89 class DiscoveredCharacteristic {
be_bryan 0:b74591d5ab33 90 public:
be_bryan 0:b74591d5ab33 91 /**
be_bryan 0:b74591d5ab33 92 * Properties of a discovered characteristic.
be_bryan 0:b74591d5ab33 93 */
be_bryan 0:b74591d5ab33 94 struct Properties_t {
be_bryan 0:b74591d5ab33 95 /**
be_bryan 0:b74591d5ab33 96 * Permits broadcasts of the characteristic value using the character
be_bryan 0:b74591d5ab33 97 * the Server Characteristic Configuration Descriptor.
be_bryan 0:b74591d5ab33 98 *
be_bryan 0:b74591d5ab33 99 * @note If set, descriptors of the characteristic contain a Server
be_bryan 0:b74591d5ab33 100 * Characteristic Configuration Descriptor.
be_bryan 0:b74591d5ab33 101 */
be_bryan 0:b74591d5ab33 102 uint8_t _broadcast :1;
be_bryan 0:b74591d5ab33 103
be_bryan 0:b74591d5ab33 104 /**
be_bryan 0:b74591d5ab33 105 * If set, the value of the characteristic can be read.
be_bryan 0:b74591d5ab33 106 */
be_bryan 0:b74591d5ab33 107 uint8_t _read :1;
be_bryan 0:b74591d5ab33 108
be_bryan 0:b74591d5ab33 109 /**
be_bryan 0:b74591d5ab33 110 * If set, a write command can write the characteristic value
be_bryan 0:b74591d5ab33 111 * (write without response).
be_bryan 0:b74591d5ab33 112 */
be_bryan 0:b74591d5ab33 113 uint8_t _writeWoResp :1;
be_bryan 0:b74591d5ab33 114
be_bryan 0:b74591d5ab33 115 /**
be_bryan 0:b74591d5ab33 116 * If set, clients can issue requests to write the characteristic.
be_bryan 0:b74591d5ab33 117 */
be_bryan 0:b74591d5ab33 118 uint8_t _write :1;
be_bryan 0:b74591d5ab33 119
be_bryan 0:b74591d5ab33 120 /**
be_bryan 0:b74591d5ab33 121 * If set, the server can emit notifications of the Characteristic Value
be_bryan 0:b74591d5ab33 122 * (without client acknowledgment).
be_bryan 0:b74591d5ab33 123 *
be_bryan 0:b74591d5ab33 124 * @note If set, descriptors of the characteristic contain a Client
be_bryan 0:b74591d5ab33 125 * Characteristic Configuration Descriptor.
be_bryan 0:b74591d5ab33 126 */
be_bryan 0:b74591d5ab33 127 uint8_t _notify :1;
be_bryan 0:b74591d5ab33 128
be_bryan 0:b74591d5ab33 129 /**
be_bryan 0:b74591d5ab33 130 * If set, the server can emit indication of the Characteristic Value
be_bryan 0:b74591d5ab33 131 * (with client acknowledgement).
be_bryan 0:b74591d5ab33 132 *
be_bryan 0:b74591d5ab33 133 * @note If set, descriptors of the characteristic contain a Client
be_bryan 0:b74591d5ab33 134 * Characteristic Configuration Descriptor.
be_bryan 0:b74591d5ab33 135 */
be_bryan 0:b74591d5ab33 136 uint8_t _indicate :1;
be_bryan 0:b74591d5ab33 137
be_bryan 0:b74591d5ab33 138 /**
be_bryan 0:b74591d5ab33 139 * If set, signed write of the Characteristic Value is supported.
be_bryan 0:b74591d5ab33 140 */
be_bryan 0:b74591d5ab33 141 uint8_t _authSignedWrite :1;
be_bryan 0:b74591d5ab33 142
be_bryan 0:b74591d5ab33 143 public:
be_bryan 0:b74591d5ab33 144 /**
be_bryan 0:b74591d5ab33 145 * Return the value of the broadcast propertie.
be_bryan 0:b74591d5ab33 146 *
be_bryan 0:b74591d5ab33 147 * @return true if the Server Characteristic Configuration Descriptor
be_bryan 0:b74591d5ab33 148 * of the characteristic can be configured to broadcast the
be_bryan 0:b74591d5ab33 149 * characteristic value during broadcast procedure.
be_bryan 0:b74591d5ab33 150 *
be_bryan 0:b74591d5ab33 151 * @see _broadcast
be_bryan 0:b74591d5ab33 152 */
be_bryan 0:b74591d5ab33 153 bool broadcast(void) const
be_bryan 0:b74591d5ab33 154 {
be_bryan 0:b74591d5ab33 155 return _broadcast;
be_bryan 0:b74591d5ab33 156 }
be_bryan 0:b74591d5ab33 157
be_bryan 0:b74591d5ab33 158 /**
be_bryan 0:b74591d5ab33 159 * Return the value of the read property
be_bryan 0:b74591d5ab33 160 *
be_bryan 0:b74591d5ab33 161 * @return true if the characteristic value can be read and false
be_bryan 0:b74591d5ab33 162 * otherwise.
be_bryan 0:b74591d5ab33 163 *
be_bryan 0:b74591d5ab33 164 * @see _read
be_bryan 0:b74591d5ab33 165 */
be_bryan 0:b74591d5ab33 166 bool read(void) const
be_bryan 0:b74591d5ab33 167 {
be_bryan 0:b74591d5ab33 168 return _read;
be_bryan 0:b74591d5ab33 169 }
be_bryan 0:b74591d5ab33 170
be_bryan 0:b74591d5ab33 171 /**
be_bryan 0:b74591d5ab33 172 * Return the value of the write without response property.
be_bryan 0:b74591d5ab33 173 *
be_bryan 0:b74591d5ab33 174 * @return true if the characteristic accepts write without response
be_bryan 0:b74591d5ab33 175 * commands and false otherwise.
be_bryan 0:b74591d5ab33 176 *
be_bryan 0:b74591d5ab33 177 * @see _writeWoResp
be_bryan 0:b74591d5ab33 178 */
be_bryan 0:b74591d5ab33 179 bool writeWoResp(void) const
be_bryan 0:b74591d5ab33 180 {
be_bryan 0:b74591d5ab33 181 return _writeWoResp;
be_bryan 0:b74591d5ab33 182 }
be_bryan 0:b74591d5ab33 183
be_bryan 0:b74591d5ab33 184 /**
be_bryan 0:b74591d5ab33 185 * Return the value of the write property.
be_bryan 0:b74591d5ab33 186 *
be_bryan 0:b74591d5ab33 187 * @return true if writing the characteristic accepts write requests and
be_bryan 0:b74591d5ab33 188 * false otherwise.
be_bryan 0:b74591d5ab33 189 *
be_bryan 0:b74591d5ab33 190 * @see _write
be_bryan 0:b74591d5ab33 191 */
be_bryan 0:b74591d5ab33 192 bool write(void) const
be_bryan 0:b74591d5ab33 193 {
be_bryan 0:b74591d5ab33 194 return _write;
be_bryan 0:b74591d5ab33 195 }
be_bryan 0:b74591d5ab33 196
be_bryan 0:b74591d5ab33 197 /**
be_bryan 0:b74591d5ab33 198 * Return the value of the notification property.
be_bryan 0:b74591d5ab33 199 *
be_bryan 0:b74591d5ab33 200 * @return true if the Client Characteristic Configuration Descriptor
be_bryan 0:b74591d5ab33 201 * can be configured to notify the characteristic value to a given
be_bryan 0:b74591d5ab33 202 * client and false otherwise.
be_bryan 0:b74591d5ab33 203 *
be_bryan 0:b74591d5ab33 204 * @note unlike indication, the notification procedure does not require
be_bryan 0:b74591d5ab33 205 * acknowledgement from the client.
be_bryan 0:b74591d5ab33 206 *
be_bryan 0:b74591d5ab33 207 * @see _notify
be_bryan 0:b74591d5ab33 208 */
be_bryan 0:b74591d5ab33 209 bool notify(void) const
be_bryan 0:b74591d5ab33 210 {
be_bryan 0:b74591d5ab33 211 return _notify;
be_bryan 0:b74591d5ab33 212 }
be_bryan 0:b74591d5ab33 213
be_bryan 0:b74591d5ab33 214 /**
be_bryan 0:b74591d5ab33 215 * Return the value of the indicate property.
be_bryan 0:b74591d5ab33 216 *
be_bryan 0:b74591d5ab33 217 * @return true if the Client Characteristic Configuration Descriptor
be_bryan 0:b74591d5ab33 218 * can be configured to indicate the characteristic value to a given
be_bryan 0:b74591d5ab33 219 * client and false otherwise.
be_bryan 0:b74591d5ab33 220 *
be_bryan 0:b74591d5ab33 221 * @note unlike notification the indication procedure does require
be_bryan 0:b74591d5ab33 222 * acknowledgment from the client.
be_bryan 0:b74591d5ab33 223 *
be_bryan 0:b74591d5ab33 224 * @see _indicate
be_bryan 0:b74591d5ab33 225 */
be_bryan 0:b74591d5ab33 226 bool indicate(void) const
be_bryan 0:b74591d5ab33 227 {
be_bryan 0:b74591d5ab33 228 return _indicate;
be_bryan 0:b74591d5ab33 229 }
be_bryan 0:b74591d5ab33 230
be_bryan 0:b74591d5ab33 231 /**
be_bryan 0:b74591d5ab33 232 * Return the value of the authenticated signed writes property.
be_bryan 0:b74591d5ab33 233 *
be_bryan 0:b74591d5ab33 234 * @return true if the characteristic accepts authenticated signed write
be_bryan 0:b74591d5ab33 235 * and false otherwise.
be_bryan 0:b74591d5ab33 236 */
be_bryan 0:b74591d5ab33 237 bool authSignedWrite(void) const
be_bryan 0:b74591d5ab33 238 {
be_bryan 0:b74591d5ab33 239 return _authSignedWrite;
be_bryan 0:b74591d5ab33 240 }
be_bryan 0:b74591d5ab33 241
be_bryan 0:b74591d5ab33 242 /**
be_bryan 0:b74591d5ab33 243 * Equal to operator for DiscoveredCharacteristic::Properties_t.
be_bryan 0:b74591d5ab33 244 *
be_bryan 0:b74591d5ab33 245 * @param[in] lhs The left hand side of the equality expression.
be_bryan 0:b74591d5ab33 246 * @param[in] rhs The right hand side of the equality expression.
be_bryan 0:b74591d5ab33 247 *
be_bryan 0:b74591d5ab33 248 * @return true if operands are equals and false otherwise.
be_bryan 0:b74591d5ab33 249 */
be_bryan 0:b74591d5ab33 250 friend bool operator==(Properties_t lhs, Properties_t rhs)
be_bryan 0:b74591d5ab33 251 {
be_bryan 0:b74591d5ab33 252 return lhs._broadcast == rhs._broadcast &&
be_bryan 0:b74591d5ab33 253 lhs._read == rhs._read &&
be_bryan 0:b74591d5ab33 254 lhs._writeWoResp == rhs._writeWoResp &&
be_bryan 0:b74591d5ab33 255 lhs._write == rhs._write &&
be_bryan 0:b74591d5ab33 256 lhs._notify == rhs._notify &&
be_bryan 0:b74591d5ab33 257 lhs._indicate == rhs._indicate &&
be_bryan 0:b74591d5ab33 258 lhs._authSignedWrite == rhs._authSignedWrite;
be_bryan 0:b74591d5ab33 259 }
be_bryan 0:b74591d5ab33 260
be_bryan 0:b74591d5ab33 261 /**
be_bryan 0:b74591d5ab33 262 * Not equal to operator for DiscoveredCharacteristic::Properties_t.
be_bryan 0:b74591d5ab33 263 *
be_bryan 0:b74591d5ab33 264 * @param lhs The left hand side of the expression.
be_bryan 0:b74591d5ab33 265 * @param rhs The right hand side of the expression.
be_bryan 0:b74591d5ab33 266 *
be_bryan 0:b74591d5ab33 267 * @return true if operands are not equals, false otherwise.
be_bryan 0:b74591d5ab33 268 */
be_bryan 0:b74591d5ab33 269 friend bool operator!=(Properties_t lhs, Properties_t rhs)
be_bryan 0:b74591d5ab33 270 {
be_bryan 0:b74591d5ab33 271 return !(lhs == rhs);
be_bryan 0:b74591d5ab33 272 }
be_bryan 0:b74591d5ab33 273
be_bryan 0:b74591d5ab33 274 private:
be_bryan 0:b74591d5ab33 275 /* Disallow implicit conversion to integer types. */
be_bryan 0:b74591d5ab33 276 operator uint8_t() const;
be_bryan 0:b74591d5ab33 277 operator unsigned() const;
be_bryan 0:b74591d5ab33 278 };
be_bryan 0:b74591d5ab33 279
be_bryan 0:b74591d5ab33 280 /**
be_bryan 0:b74591d5ab33 281 * Initiate a read of the characteristic value.
be_bryan 0:b74591d5ab33 282 *
be_bryan 0:b74591d5ab33 283 * The characteristic value is read in its entirety from the value attribute
be_bryan 0:b74591d5ab33 284 * of the characteristic.
be_bryan 0:b74591d5ab33 285 *
be_bryan 0:b74591d5ab33 286 * Read responses will be passed to the callback registered in
be_bryan 0:b74591d5ab33 287 * GattClient::onDataRead(). Read responses to read requests that this function
be_bryan 0:b74591d5ab33 288 * call initiates will have their GattReadCallbackParams::connHandle
be_bryan 0:b74591d5ab33 289 * field equal to the value returned by getConnectionHandle() and their
be_bryan 0:b74591d5ab33 290 * GattReadCallbackParams::handle field equal to the value returned by
be_bryan 0:b74591d5ab33 291 * getValueHandle().
be_bryan 0:b74591d5ab33 292 *
be_bryan 0:b74591d5ab33 293 * @param[in] offset The position - in the characteristic value bytes stream
be_bryan 0:b74591d5ab33 294 * - where the read operation begin. This parameter is optional.
be_bryan 0:b74591d5ab33 295 *
be_bryan 0:b74591d5ab33 296 * @return BLE_ERROR_NONE if a read has been initiated.
be_bryan 0:b74591d5ab33 297 * @return BLE_ERROR_INVALID_STATE if some internal state about the
be_bryan 0:b74591d5ab33 298 * connection is invalid.
be_bryan 0:b74591d5ab33 299 * @return BLE_STACK_BUSY if some client procedure is already in progress.
be_bryan 0:b74591d5ab33 300 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
be_bryan 0:b74591d5ab33 301 * properties.
be_bryan 0:b74591d5ab33 302 */
be_bryan 0:b74591d5ab33 303 ble_error_t read(uint16_t offset = 0) const;
be_bryan 0:b74591d5ab33 304
be_bryan 0:b74591d5ab33 305 /**
be_bryan 0:b74591d5ab33 306 * Initiate a read of the characteristic value and pass the response to its
be_bryan 0:b74591d5ab33 307 * completion callback.
be_bryan 0:b74591d5ab33 308 *
be_bryan 0:b74591d5ab33 309 * @param[in] offset The position - in the characteristic value bytes stream
be_bryan 0:b74591d5ab33 310 * - where the read operation begin.
be_bryan 0:b74591d5ab33 311 *
be_bryan 0:b74591d5ab33 312 * @param[in] onRead Completion callback which will accept the response of
be_bryan 0:b74591d5ab33 313 * the read request. The callback is copied; it is unnecessary to keep it
be_bryan 0:b74591d5ab33 314 * in memory after the call.
be_bryan 0:b74591d5ab33 315 *
be_bryan 0:b74591d5ab33 316 * @return BLE_ERROR_NONE if a read has been initiated.
be_bryan 0:b74591d5ab33 317 * @return BLE_ERROR_INVALID_STATE if some internal state about the
be_bryan 0:b74591d5ab33 318 * connection is invalid.
be_bryan 0:b74591d5ab33 319 * @return BLE_STACK_BUSY if some client procedure is already in progress.
be_bryan 0:b74591d5ab33 320 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
be_bryan 0:b74591d5ab33 321 * properties.
be_bryan 0:b74591d5ab33 322 *
be_bryan 0:b74591d5ab33 323 * @note This function is similar to read(uint16_t) const; however, it uses
be_bryan 0:b74591d5ab33 324 * dynamic memory to store the use completion callback.
be_bryan 0:b74591d5ab33 325 */
be_bryan 0:b74591d5ab33 326 ble_error_t read(
be_bryan 0:b74591d5ab33 327 uint16_t offset,
be_bryan 0:b74591d5ab33 328 const GattClient::ReadCallback_t &onRead
be_bryan 0:b74591d5ab33 329 ) const;
be_bryan 0:b74591d5ab33 330
be_bryan 0:b74591d5ab33 331 /**
be_bryan 0:b74591d5ab33 332 * Perform a write without response procedure.
be_bryan 0:b74591d5ab33 333 *
be_bryan 0:b74591d5ab33 334 * @note The server does not acknowledge write without responses.
be_bryan 0:b74591d5ab33 335 * Therefore, they won't generate any event on the client side.
be_bryan 0:b74591d5ab33 336 *
be_bryan 0:b74591d5ab33 337 * @param[in] length The amount of data being written.
be_bryan 0:b74591d5ab33 338 * @param[in] value The bytes being written.
be_bryan 0:b74591d5ab33 339 *
be_bryan 0:b74591d5ab33 340 * @return BLE_ERROR_NONE Successfully started the Write procedure.
be_bryan 0:b74591d5ab33 341 * @return BLE_ERROR_INVALID_STATE if some internal state about the
be_bryan 0:b74591d5ab33 342 * connection is invalid.
be_bryan 0:b74591d5ab33 343 * @return BLE_STACK_BUSY if some client procedure is already in progress.
be_bryan 0:b74591d5ab33 344 * @return BLE_ERROR_NO_MEM if there are no available buffers left to
be_bryan 0:b74591d5ab33 345 * process the request.
be_bryan 0:b74591d5ab33 346 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
be_bryan 0:b74591d5ab33 347 * properties.
be_bryan 0:b74591d5ab33 348 */
be_bryan 0:b74591d5ab33 349 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
be_bryan 0:b74591d5ab33 350
be_bryan 0:b74591d5ab33 351 /**
be_bryan 0:b74591d5ab33 352 * Initiate a discovery of the characteristic descriptors.
be_bryan 0:b74591d5ab33 353 *
be_bryan 0:b74591d5ab33 354 * When a descriptor is discovered, the callback onDescriptorDiscovered is
be_bryan 0:b74591d5ab33 355 * invoked with the descriptor discovered as parameter. When the process
be_bryan 0:b74591d5ab33 356 * ends, the callback onTermination is invoked.
be_bryan 0:b74591d5ab33 357 *
be_bryan 0:b74591d5ab33 358 * @param[in] onDescriptorDiscovered Callback is invoked when a descriptor is
be_bryan 0:b74591d5ab33 359 * discovered.
be_bryan 0:b74591d5ab33 360 *
be_bryan 0:b74591d5ab33 361 * @param[in] onTermination Callback is invoked when the discovery process ends.
be_bryan 0:b74591d5ab33 362 *
be_bryan 0:b74591d5ab33 363 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully;
be_bryan 0:b74591d5ab33 364 * else an appropriate error.
be_bryan 0:b74591d5ab33 365 *
be_bryan 0:b74591d5ab33 366 * @note This function is shorthand for
be_bryan 0:b74591d5ab33 367 * GattClient::discoverCharacteristicDescriptors; therefore,
be_bryan 0:b74591d5ab33 368 * GattClient::isCharacteristicDescriptorDiscoveryActive can be used to
be_bryan 0:b74591d5ab33 369 * determine the descriptor discovery and
be_bryan 0:b74591d5ab33 370 * GattClient::terminateCharacteristicDescriptorDiscovery can be used to
be_bryan 0:b74591d5ab33 371 * end the discovery process.
be_bryan 0:b74591d5ab33 372 */
be_bryan 0:b74591d5ab33 373 ble_error_t discoverDescriptors(
be_bryan 0:b74591d5ab33 374 const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered,
be_bryan 0:b74591d5ab33 375 const CharacteristicDescriptorDiscovery::TerminationCallback_t &onTermination
be_bryan 0:b74591d5ab33 376 ) const;
be_bryan 0:b74591d5ab33 377
be_bryan 0:b74591d5ab33 378 /**
be_bryan 0:b74591d5ab33 379 * Initiate a write procedure of the characteristic value.
be_bryan 0:b74591d5ab33 380 *
be_bryan 0:b74591d5ab33 381 * Unlike write without responses (see writeWoResponse()), an acknowledgment
be_bryan 0:b74591d5ab33 382 * is expected for this procedure. The response of the peer GATT server to
be_bryan 0:b74591d5ab33 383 * the write request is passed to callbacks registered in
be_bryan 0:b74591d5ab33 384 * GattClient::onDataWritten().
be_bryan 0:b74591d5ab33 385 *
be_bryan 0:b74591d5ab33 386 * Similarly to read responses, responses to write request of this
be_bryan 0:b74591d5ab33 387 * characteristic can be identified by their connection handle (
be_bryan 0:b74591d5ab33 388 * GattWriteCallbackParams::connHandle), which is equal to the value
be_bryan 0:b74591d5ab33 389 * returned by getConnectionHandle() and their attribute handle (
be_bryan 0:b74591d5ab33 390 * GattWriteCallbackParams::handle), which is equal to the value
be_bryan 0:b74591d5ab33 391 * returned by getValueHandle().
be_bryan 0:b74591d5ab33 392 *
be_bryan 0:b74591d5ab33 393 * @param[in] length The amount of data being written.
be_bryan 0:b74591d5ab33 394 * @param[in] value The bytes being written.
be_bryan 0:b74591d5ab33 395 *
be_bryan 0:b74591d5ab33 396 * @return BLE_ERROR_NONE Successfully started the Write procedure.
be_bryan 0:b74591d5ab33 397 * @return BLE_ERROR_INVALID_STATE If some internal state about the
be_bryan 0:b74591d5ab33 398 * connection is invalid.
be_bryan 0:b74591d5ab33 399 * @return BLE_STACK_BUSY If some client procedure is already in progress.
be_bryan 0:b74591d5ab33 400 * @return BLE_ERROR_NO_MEM If there are no available buffers left to
be_bryan 0:b74591d5ab33 401 * process the request.
be_bryan 0:b74591d5ab33 402 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
be_bryan 0:b74591d5ab33 403 * properties.
be_bryan 0:b74591d5ab33 404 *
be_bryan 0:b74591d5ab33 405 * @note Internally, the API uses the write or long write procedure, depending
be_bryan 0:b74591d5ab33 406 * on the number of bytes to write and the MTU size.
be_bryan 0:b74591d5ab33 407 */
be_bryan 0:b74591d5ab33 408 ble_error_t write(uint16_t length, const uint8_t *value) const;
be_bryan 0:b74591d5ab33 409
be_bryan 0:b74591d5ab33 410 /**
be_bryan 0:b74591d5ab33 411 * Initiate a write procedure of the characteristic value.
be_bryan 0:b74591d5ab33 412 *
be_bryan 0:b74591d5ab33 413 * Same as write(uint16_t, const uint8_t *) const but accepts a completion
be_bryan 0:b74591d5ab33 414 * callback, which is invoked when the server response is received.
be_bryan 0:b74591d5ab33 415 *
be_bryan 0:b74591d5ab33 416 * @param[in] length The amount of bytes to write.
be_bryan 0:b74591d5ab33 417 * @param[in] value The bytes to write.
be_bryan 0:b74591d5ab33 418 * @param[in] onWrite Continuation callback of the write procedure.
be_bryan 0:b74591d5ab33 419 *
be_bryan 0:b74591d5ab33 420 * @return BLE_ERROR_NONE Successfully started the Write procedure.
be_bryan 0:b74591d5ab33 421 * @return BLE_ERROR_INVALID_STATE if some internal state about the
be_bryan 0:b74591d5ab33 422 * connection is invalid.
be_bryan 0:b74591d5ab33 423 * @return BLE_STACK_BUSY if some client procedure is already in progress.
be_bryan 0:b74591d5ab33 424 * @return BLE_ERROR_NO_MEM if there are no available buffers left to
be_bryan 0:b74591d5ab33 425 * process the request.
be_bryan 0:b74591d5ab33 426 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
be_bryan 0:b74591d5ab33 427 * properties.
be_bryan 0:b74591d5ab33 428 */
be_bryan 0:b74591d5ab33 429 ble_error_t write(
be_bryan 0:b74591d5ab33 430 uint16_t length,
be_bryan 0:b74591d5ab33 431 const uint8_t *value,
be_bryan 0:b74591d5ab33 432 const GattClient::WriteCallback_t &onWrite
be_bryan 0:b74591d5ab33 433 ) const;
be_bryan 0:b74591d5ab33 434
be_bryan 0:b74591d5ab33 435 void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
be_bryan 0:b74591d5ab33 436 uuid.setupLong(longUUID, order);
be_bryan 0:b74591d5ab33 437 }
be_bryan 0:b74591d5ab33 438
be_bryan 0:b74591d5ab33 439 public:
be_bryan 0:b74591d5ab33 440 /**
be_bryan 0:b74591d5ab33 441 * Get the UUID of the discovered characteristic.
be_bryan 0:b74591d5ab33 442 *
be_bryan 0:b74591d5ab33 443 * @return The UUID of this characteristic.
be_bryan 0:b74591d5ab33 444 */
be_bryan 0:b74591d5ab33 445 const UUID &getUUID(void) const
be_bryan 0:b74591d5ab33 446 {
be_bryan 0:b74591d5ab33 447 return uuid;
be_bryan 0:b74591d5ab33 448 }
be_bryan 0:b74591d5ab33 449
be_bryan 0:b74591d5ab33 450 /**
be_bryan 0:b74591d5ab33 451 * Get the properties of this characteristic.
be_bryan 0:b74591d5ab33 452 *
be_bryan 0:b74591d5ab33 453 * @return The set of properties of this characteristic.
be_bryan 0:b74591d5ab33 454 */
be_bryan 0:b74591d5ab33 455 const Properties_t &getProperties(void) const
be_bryan 0:b74591d5ab33 456 {
be_bryan 0:b74591d5ab33 457 return props;
be_bryan 0:b74591d5ab33 458 }
be_bryan 0:b74591d5ab33 459
be_bryan 0:b74591d5ab33 460 /**
be_bryan 0:b74591d5ab33 461 * Get the declaration handle of this characteristic.
be_bryan 0:b74591d5ab33 462 *
be_bryan 0:b74591d5ab33 463 * The declaration handle is the first handle of a characteristic
be_bryan 0:b74591d5ab33 464 * definition. The value accessible at this handle contains the following
be_bryan 0:b74591d5ab33 465 * informations:
be_bryan 0:b74591d5ab33 466 * - The characteristics properties (see Properties_t). This value can
be_bryan 0:b74591d5ab33 467 * be accessed by using #getProperties .
be_bryan 0:b74591d5ab33 468 * - The characteristic value attribute handle. This field can be accessed
be_bryan 0:b74591d5ab33 469 * by using #getValueHandle .
be_bryan 0:b74591d5ab33 470 * - The characteristic UUID, this value can be accessed by using the
be_bryan 0:b74591d5ab33 471 * function #getUUID .
be_bryan 0:b74591d5ab33 472 *
be_bryan 0:b74591d5ab33 473 * @return the declaration handle of this characteristic.
be_bryan 0:b74591d5ab33 474 */
be_bryan 0:b74591d5ab33 475 GattAttribute::Handle_t getDeclHandle(void) const
be_bryan 0:b74591d5ab33 476 {
be_bryan 0:b74591d5ab33 477 return declHandle;
be_bryan 0:b74591d5ab33 478 }
be_bryan 0:b74591d5ab33 479
be_bryan 0:b74591d5ab33 480 /**
be_bryan 0:b74591d5ab33 481 * Get the attribute handle of the characteristic value.
be_bryan 0:b74591d5ab33 482 *
be_bryan 0:b74591d5ab33 483 * This handle is used to read or write the value of the characteristic.
be_bryan 0:b74591d5ab33 484 *
be_bryan 0:b74591d5ab33 485 * @return The handle to access the value of this characteristic.
be_bryan 0:b74591d5ab33 486 */
be_bryan 0:b74591d5ab33 487 GattAttribute::Handle_t getValueHandle(void) const
be_bryan 0:b74591d5ab33 488 {
be_bryan 0:b74591d5ab33 489 return valueHandle;
be_bryan 0:b74591d5ab33 490 }
be_bryan 0:b74591d5ab33 491
be_bryan 0:b74591d5ab33 492 /**
be_bryan 0:b74591d5ab33 493 * Return the last attribute handle of the characteristic definition.
be_bryan 0:b74591d5ab33 494 *
be_bryan 0:b74591d5ab33 495 * The attribute layout of a characteristic definition is:
be_bryan 0:b74591d5ab33 496 * - Declaration attribute (see #getDeclHandle).
be_bryan 0:b74591d5ab33 497 * - Value attribute (see #getValueHandle).
be_bryan 0:b74591d5ab33 498 * - Zero or more characteristic descriptors attribute.
be_bryan 0:b74591d5ab33 499 *
be_bryan 0:b74591d5ab33 500 * The last attribute handle is used internally to discover characteristic
be_bryan 0:b74591d5ab33 501 * descriptors. The discovery operates on the range [ValueHandle + 1 :
be_bryan 0:b74591d5ab33 502 * LastHandle].
be_bryan 0:b74591d5ab33 503 *
be_bryan 0:b74591d5ab33 504 * @return The last handle of this characteristic definition.
be_bryan 0:b74591d5ab33 505 *
be_bryan 0:b74591d5ab33 506 * @note This function is public for informative purposes.
be_bryan 0:b74591d5ab33 507 */
be_bryan 0:b74591d5ab33 508 GattAttribute::Handle_t getLastHandle(void) const
be_bryan 0:b74591d5ab33 509 {
be_bryan 0:b74591d5ab33 510 return lastHandle;
be_bryan 0:b74591d5ab33 511 }
be_bryan 0:b74591d5ab33 512
be_bryan 0:b74591d5ab33 513 /**
be_bryan 0:b74591d5ab33 514 * Get the GattClient, which can operate on this characteristic.
be_bryan 0:b74591d5ab33 515 *
be_bryan 0:b74591d5ab33 516 * @return The GattClient, which can operate on this characteristic.
be_bryan 0:b74591d5ab33 517 */
be_bryan 0:b74591d5ab33 518 GattClient* getGattClient()
be_bryan 0:b74591d5ab33 519 {
be_bryan 0:b74591d5ab33 520 return gattc;
be_bryan 0:b74591d5ab33 521 }
be_bryan 0:b74591d5ab33 522
be_bryan 0:b74591d5ab33 523 /**
be_bryan 0:b74591d5ab33 524 * Get the GattClient, which can operate on this characteristic.
be_bryan 0:b74591d5ab33 525 *
be_bryan 0:b74591d5ab33 526 * @return The GattClient, which can operate on this characteristic.
be_bryan 0:b74591d5ab33 527 */
be_bryan 0:b74591d5ab33 528 const GattClient* getGattClient() const
be_bryan 0:b74591d5ab33 529 {
be_bryan 0:b74591d5ab33 530 return gattc;
be_bryan 0:b74591d5ab33 531 }
be_bryan 0:b74591d5ab33 532
be_bryan 0:b74591d5ab33 533 /**
be_bryan 0:b74591d5ab33 534 * @brief Get the connection handle to the GattServer containing this
be_bryan 0:b74591d5ab33 535 * characteristic.
be_bryan 0:b74591d5ab33 536 *
be_bryan 0:b74591d5ab33 537 * @return Connection handle to the GattServer, which contains this
be_bryan 0:b74591d5ab33 538 * characteristic.
be_bryan 0:b74591d5ab33 539 */
be_bryan 0:b74591d5ab33 540 Gap::Handle_t getConnectionHandle() const
be_bryan 0:b74591d5ab33 541 {
be_bryan 0:b74591d5ab33 542 return connHandle;
be_bryan 0:b74591d5ab33 543 }
be_bryan 0:b74591d5ab33 544
be_bryan 0:b74591d5ab33 545 /**
be_bryan 0:b74591d5ab33 546 * "Equal to" operator for DiscoveredCharacteristic.
be_bryan 0:b74591d5ab33 547 *
be_bryan 0:b74591d5ab33 548 * @param[in] lhs The left hand side of the equality expression.
be_bryan 0:b74591d5ab33 549 * @param[in] rhs The right hand side of the equality expression.
be_bryan 0:b74591d5ab33 550 *
be_bryan 0:b74591d5ab33 551 * @return true if operands are equals and false otherwise.
be_bryan 0:b74591d5ab33 552 */
be_bryan 0:b74591d5ab33 553 friend bool operator==(
be_bryan 0:b74591d5ab33 554 const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs
be_bryan 0:b74591d5ab33 555 ) {
be_bryan 0:b74591d5ab33 556 return lhs.gattc == rhs.gattc &&
be_bryan 0:b74591d5ab33 557 lhs.uuid == rhs.uuid &&
be_bryan 0:b74591d5ab33 558 lhs.props == rhs.props &&
be_bryan 0:b74591d5ab33 559 lhs.declHandle == rhs.declHandle &&
be_bryan 0:b74591d5ab33 560 lhs.valueHandle == rhs.valueHandle &&
be_bryan 0:b74591d5ab33 561 lhs.lastHandle == rhs.lastHandle &&
be_bryan 0:b74591d5ab33 562 lhs.connHandle == rhs.connHandle;
be_bryan 0:b74591d5ab33 563 }
be_bryan 0:b74591d5ab33 564
be_bryan 0:b74591d5ab33 565 /**
be_bryan 0:b74591d5ab33 566 * "Not equal to" operator for DiscoveredCharacteristic.
be_bryan 0:b74591d5ab33 567 *
be_bryan 0:b74591d5ab33 568 * @param[in] lhs The right hand side of the expression.
be_bryan 0:b74591d5ab33 569 * @param[in] rhs The left hand side of the expression.
be_bryan 0:b74591d5ab33 570 *
be_bryan 0:b74591d5ab33 571 * @return true if operands are not equal and false otherwise.
be_bryan 0:b74591d5ab33 572 */
be_bryan 0:b74591d5ab33 573 friend bool operator !=(
be_bryan 0:b74591d5ab33 574 const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs
be_bryan 0:b74591d5ab33 575 ) {
be_bryan 0:b74591d5ab33 576 return !(lhs == rhs);
be_bryan 0:b74591d5ab33 577 }
be_bryan 0:b74591d5ab33 578
be_bryan 0:b74591d5ab33 579 public:
be_bryan 0:b74591d5ab33 580 DiscoveredCharacteristic() :
be_bryan 0:b74591d5ab33 581 gattc(NULL),
be_bryan 0:b74591d5ab33 582 uuid(UUID::ShortUUIDBytes_t(0)),
be_bryan 0:b74591d5ab33 583 props(),
be_bryan 0:b74591d5ab33 584 declHandle(GattAttribute::INVALID_HANDLE),
be_bryan 0:b74591d5ab33 585 valueHandle(GattAttribute::INVALID_HANDLE),
be_bryan 0:b74591d5ab33 586 lastHandle(GattAttribute::INVALID_HANDLE),
be_bryan 0:b74591d5ab33 587 connHandle() {
be_bryan 0:b74591d5ab33 588 }
be_bryan 0:b74591d5ab33 589
be_bryan 0:b74591d5ab33 590 protected:
be_bryan 0:b74591d5ab33 591 /**
be_bryan 0:b74591d5ab33 592 * Pointer to the underlying GattClient for this DiscoveredCharacteristic
be_bryan 0:b74591d5ab33 593 * object.
be_bryan 0:b74591d5ab33 594 */
be_bryan 0:b74591d5ab33 595 GattClient *gattc;
be_bryan 0:b74591d5ab33 596
be_bryan 0:b74591d5ab33 597 protected:
be_bryan 0:b74591d5ab33 598 /**
be_bryan 0:b74591d5ab33 599 * Discovered characteristic's UUID.
be_bryan 0:b74591d5ab33 600 */
be_bryan 0:b74591d5ab33 601 UUID uuid;
be_bryan 0:b74591d5ab33 602
be_bryan 0:b74591d5ab33 603 /**
be_bryan 0:b74591d5ab33 604 * Hold the configured properties of the discovered characteristic.
be_bryan 0:b74591d5ab33 605 *
be_bryan 0:b74591d5ab33 606 * @see Properties_t.
be_bryan 0:b74591d5ab33 607 */
be_bryan 0:b74591d5ab33 608 Properties_t props;
be_bryan 0:b74591d5ab33 609
be_bryan 0:b74591d5ab33 610 /**
be_bryan 0:b74591d5ab33 611 * Value handle of the discovered characteristic's declaration attribute.
be_bryan 0:b74591d5ab33 612 */
be_bryan 0:b74591d5ab33 613 GattAttribute::Handle_t declHandle;
be_bryan 0:b74591d5ab33 614
be_bryan 0:b74591d5ab33 615 /**
be_bryan 0:b74591d5ab33 616 * Value handle of the discovered characteristic's value attribute.
be_bryan 0:b74591d5ab33 617 */
be_bryan 0:b74591d5ab33 618 GattAttribute::Handle_t valueHandle;
be_bryan 0:b74591d5ab33 619
be_bryan 0:b74591d5ab33 620 /**
be_bryan 0:b74591d5ab33 621 * Value handle of the discovered characteristic's last attribute.
be_bryan 0:b74591d5ab33 622 */
be_bryan 0:b74591d5ab33 623 GattAttribute::Handle_t lastHandle;
be_bryan 0:b74591d5ab33 624
be_bryan 0:b74591d5ab33 625 /**
be_bryan 0:b74591d5ab33 626 * Handle of the connection where the characteristic was discovered.
be_bryan 0:b74591d5ab33 627 */
be_bryan 0:b74591d5ab33 628 Gap::Handle_t connHandle;
be_bryan 0:b74591d5ab33 629 };
be_bryan 0:b74591d5ab33 630
be_bryan 0:b74591d5ab33 631 /**
be_bryan 0:b74591d5ab33 632 * @}
be_bryan 0:b74591d5ab33 633 * @}
be_bryan 0:b74591d5ab33 634 * @}
be_bryan 0:b74591d5ab33 635 */
be_bryan 0:b74591d5ab33 636
be_bryan 0:b74591d5ab33 637 #endif /*MBED_DISCOVERED_CHARACTERISTIC_H__*/