Lancaster University / BLE_API

Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API

Dependents:   microbit-dal microbit-dal microbit-ble-open microbit-dal ... more

Fork of BLE_API by Bluetooth Low Energy

ble/DiscoveredCharacteristic.h@1065:473735376f13, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:38 2016 +0000
Revision:
1065:473735376f13
Parent:
1063:187f9929cb60
Child:
1066:980dd95eb920
Synchronized with git rev 325f52c7

Author: Vincent Coubard

Add documentation for DiscoveredCharacteristic

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 716:11b41f651697 1 /* mbed Microcontroller Library
rgrover1 716:11b41f651697 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 716:11b41f651697 3 *
rgrover1 716:11b41f651697 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 716:11b41f651697 5 * you may not use this file except in compliance with the License.
rgrover1 716:11b41f651697 6 * You may obtain a copy of the License at
rgrover1 716:11b41f651697 7 *
rgrover1 716:11b41f651697 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 716:11b41f651697 9 *
rgrover1 716:11b41f651697 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 716:11b41f651697 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 716:11b41f651697 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 716:11b41f651697 13 * See the License for the specific language governing permissions and
rgrover1 716:11b41f651697 14 * limitations under the License.
rgrover1 716:11b41f651697 15 */
rgrover1 716:11b41f651697 16
rgrover1 716:11b41f651697 17 #ifndef __DISCOVERED_CHARACTERISTIC_H__
rgrover1 716:11b41f651697 18 #define __DISCOVERED_CHARACTERISTIC_H__
rgrover1 716:11b41f651697 19
rgrover1 716:11b41f651697 20 #include "UUID.h"
rgrover1 716:11b41f651697 21 #include "Gap.h"
rgrover1 716:11b41f651697 22 #include "GattAttribute.h"
rgrover1 716:11b41f651697 23 #include "GattClient.h"
vcoubard 1063:187f9929cb60 24 #include "CharacteristicDescriptorDiscovery.h"
vcoubard 1063:187f9929cb60 25 #include "ble/DiscoveredCharacteristicDescriptor.h"
vcoubard 1063:187f9929cb60 26
rgrover1 716:11b41f651697 27 /**
rgrover1 716:11b41f651697 28 * Structure for holding information about the service and the characteristics
rgrover1 716:11b41f651697 29 * found during the discovery process.
rgrover1 716:11b41f651697 30 */
rgrover1 716:11b41f651697 31 class DiscoveredCharacteristic {
rgrover1 716:11b41f651697 32 public:
rgrover1 716:11b41f651697 33 struct Properties_t {
vcoubard 1048:efb29faf12fc 34 uint8_t _broadcast :1; /**< Broadcasting the value permitted. */
rgrover1 716:11b41f651697 35 uint8_t _read :1; /**< Reading the value permitted. */
rgrover1 716:11b41f651697 36 uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */
rgrover1 716:11b41f651697 37 uint8_t _write :1; /**< Writing the value with Write Request permitted. */
vcoubard 1065:473735376f13 38 uint8_t _notify :1; /**< Notifications of the value permitted. */
rgrover1 716:11b41f651697 39 uint8_t _indicate :1; /**< Indications of the value permitted. */
rgrover1 716:11b41f651697 40 uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
rgrover1 716:11b41f651697 41
rgrover1 716:11b41f651697 42 public:
rgrover1 716:11b41f651697 43 bool broadcast(void) const {return _broadcast; }
rgrover1 716:11b41f651697 44 bool read(void) const {return _read; }
rgrover1 716:11b41f651697 45 bool writeWoResp(void) const {return _writeWoResp; }
rgrover1 716:11b41f651697 46 bool write(void) const {return _write; }
rgrover1 716:11b41f651697 47 bool notify(void) const {return _notify; }
rgrover1 716:11b41f651697 48 bool indicate(void) const {return _indicate; }
rgrover1 716:11b41f651697 49 bool authSignedWrite(void) const {return _authSignedWrite;}
rgrover1 716:11b41f651697 50
vcoubard 1065:473735376f13 51 /**
vcoubard 1065:473735376f13 52 * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
vcoubard 1065:473735376f13 53 *
vcoubard 1065:473735376f13 54 * @param lhs The left hand side of the equality expression
vcoubard 1065:473735376f13 55 * @param rhs The right hand side of the equality expression
vcoubard 1065:473735376f13 56 *
vcoubard 1065:473735376f13 57 * @return true if operands are equals, false otherwise.
vcoubard 1065:473735376f13 58 */
vcoubard 1065:473735376f13 59 friend bool operator==(Properties_t lhs, Properties_t rhs) {
vcoubard 1063:187f9929cb60 60 return rhs._broadcast == lhs._broadcast &&
vcoubard 1063:187f9929cb60 61 rhs._read == lhs._read &&
vcoubard 1063:187f9929cb60 62 rhs._writeWoResp == lhs._writeWoResp &&
vcoubard 1063:187f9929cb60 63 rhs._write == lhs._write &&
vcoubard 1063:187f9929cb60 64 rhs._notify == lhs._notify &&
vcoubard 1063:187f9929cb60 65 rhs._indicate == lhs._indicate &&
vcoubard 1063:187f9929cb60 66 rhs._authSignedWrite == lhs._authSignedWrite;
vcoubard 1063:187f9929cb60 67 }
vcoubard 1063:187f9929cb60 68
vcoubard 1065:473735376f13 69 /**
vcoubard 1065:473735376f13 70 * @brief "Not equal to" operator for DiscoveredCharacteristic::Properties_t
vcoubard 1065:473735376f13 71 *
vcoubard 1065:473735376f13 72 * @param lhs The right hand side of the expression
vcoubard 1065:473735376f13 73 * @param rhs The left hand side of the expression
vcoubard 1065:473735376f13 74 *
vcoubard 1065:473735376f13 75 * @return true if operands are not equals, false otherwise.
vcoubard 1065:473735376f13 76 */
vcoubard 1065:473735376f13 77 friend bool operator!=(Properties_t lhs, Properties_t rhs) {
vcoubard 1063:187f9929cb60 78 return !(rhs == lhs);
vcoubard 1063:187f9929cb60 79 }
vcoubard 1063:187f9929cb60 80
rgrover1 716:11b41f651697 81 private:
vcoubard 1048:efb29faf12fc 82 operator uint8_t() const; /* Disallow implicit conversion into an integer. */
vcoubard 1048:efb29faf12fc 83 operator unsigned() const; /* Disallow implicit conversion into an integer. */
rgrover1 716:11b41f651697 84 };
rgrover1 716:11b41f651697 85
rgrover1 716:11b41f651697 86 /**
rgrover1 716:11b41f651697 87 * Initiate (or continue) a read for the value attribute, optionally at a
vcoubard 1048:efb29faf12fc 88 * given offset. If the characteristic or descriptor to be read is longer
rgrover1 716:11b41f651697 89 * than ATT_MTU - 1, this function must be called multiple times with
rgrover1 716:11b41f651697 90 * appropriate offset to read the complete value.
rgrover1 716:11b41f651697 91 *
vcoubard 1048:efb29faf12fc 92 * @return BLE_ERROR_NONE if a read has been initiated, or
rgrover1 716:11b41f651697 93 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 94 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 95 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 96 */
rgrover1 716:11b41f651697 97 ble_error_t read(uint16_t offset = 0) const;
rgrover1 716:11b41f651697 98
vcoubard 1052:b55e1ad3e1b3 99 ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 100
rgrover1 716:11b41f651697 101 /**
rgrover1 716:11b41f651697 102 * Perform a write without response procedure.
rgrover1 716:11b41f651697 103 *
rgrover1 716:11b41f651697 104 * @param length
rgrover1 716:11b41f651697 105 * The amount of data being written.
rgrover1 716:11b41f651697 106 * @param value
rgrover1 716:11b41f651697 107 * The bytes being written.
rgrover1 716:11b41f651697 108 *
rgrover1 716:11b41f651697 109 * @note It is important to note that a write without response will generate
rgrover1 716:11b41f651697 110 * an onDataSent() callback when the packet has been transmitted. There
rgrover1 716:11b41f651697 111 * will be a BLE-stack specific limit to the number of pending
rgrover1 716:11b41f651697 112 * writeWoResponse operations; the user may want to use the onDataSent()
rgrover1 716:11b41f651697 113 * callback for flow-control.
rgrover1 716:11b41f651697 114 *
vcoubard 1048:efb29faf12fc 115 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 116 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 117 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 118 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 119 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 120 */
rgrover1 716:11b41f651697 121 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 122
rgrover1 716:11b41f651697 123 /**
rgrover1 716:11b41f651697 124 * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
rgrover1 716:11b41f651697 125 *
vcoubard 1065:473735376f13 126 * @param onDescriptorDiscovered This callback will be called every time a descriptor is discovered
vcoubard 1063:187f9929cb60 127 * @param onTermination This callback will be called when the discovery process is over.
rgrover1 716:11b41f651697 128 *
vcoubard 1065:473735376f13 129 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 716:11b41f651697 130 */
vcoubard 1065:473735376f13 131 ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered,
vcoubard 1063:187f9929cb60 132 const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const;
rgrover1 716:11b41f651697 133
rgrover1 716:11b41f651697 134 /**
rgrover1 716:11b41f651697 135 * Perform a write procedure.
rgrover1 716:11b41f651697 136 *
rgrover1 716:11b41f651697 137 * @param length
rgrover1 716:11b41f651697 138 * The amount of data being written.
rgrover1 716:11b41f651697 139 * @param value
rgrover1 716:11b41f651697 140 * The bytes being written.
rgrover1 716:11b41f651697 141 *
rgrover1 716:11b41f651697 142 * @note It is important to note that a write will generate
rgrover1 716:11b41f651697 143 * an onDataWritten() callback when the peer acknowledges the request.
rgrover1 716:11b41f651697 144 *
vcoubard 1048:efb29faf12fc 145 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 146 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 147 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 148 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 149 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 150 */
rgrover1 716:11b41f651697 151 ble_error_t write(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 152
vcoubard 1056:ce2fb3d09929 153 /**
vcoubard 1052:b55e1ad3e1b3 154 * Same as above but register the callback wich will be called once the data has been written
vcoubard 1052:b55e1ad3e1b3 155 */
vcoubard 1052:b55e1ad3e1b3 156 ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 157
vcoubard 1056:ce2fb3d09929 158 void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
vcoubard 1056:ce2fb3d09929 159 uuid.setupLong(longUUID, order);
rgrover1 716:11b41f651697 160 }
rgrover1 716:11b41f651697 161
rgrover1 716:11b41f651697 162 public:
vcoubard 1065:473735376f13 163 /**
vcoubard 1065:473735376f13 164 * @brief Get the UUID of the discovered characteristic
vcoubard 1065:473735376f13 165 * @return the UUID of this characteristic
vcoubard 1065:473735376f13 166 */
rgrover1 741:d6dceefb844e 167 const UUID& getUUID(void) const {
rgrover1 741:d6dceefb844e 168 return uuid;
rgrover1 716:11b41f651697 169 }
rgrover1 716:11b41f651697 170
vcoubard 1065:473735376f13 171 /**
vcoubard 1065:473735376f13 172 * @brief Get the properties of this characteristic
vcoubard 1065:473735376f13 173 * @return the set of properties of this characteristic
vcoubard 1065:473735376f13 174 */
rgrover1 716:11b41f651697 175 const Properties_t& getProperties(void) const {
rgrover1 716:11b41f651697 176 return props;
rgrover1 716:11b41f651697 177 }
rgrover1 716:11b41f651697 178
vcoubard 1065:473735376f13 179 /**
vcoubard 1065:473735376f13 180 * @brief Get the declaration handle of this characteristic.
vcoubard 1065:473735376f13 181 * @detail The declaration handle is the first handle of a characteristic
vcoubard 1065:473735376f13 182 * definition. The value accessible at this handle contains the following
vcoubard 1065:473735376f13 183 * informations:
vcoubard 1065:473735376f13 184 * - The characteristics properties (see Properties_t). This value can
vcoubard 1065:473735376f13 185 * be accessed by using DiscoveredCharacteristic::getProperties .
vcoubard 1065:473735376f13 186 * - The characteristic value attribute handle. This field can be accessed
vcoubard 1065:473735376f13 187 * by using DiscoveredCharacteristic::getValueHandle .
vcoubard 1065:473735376f13 188 * - The characteristic UUID, this value can be accessed by using the
vcoubard 1065:473735376f13 189 * function DiscoveredCharacteristic::getUUID .
vcoubard 1065:473735376f13 190 * @return the declaration handle of this characteristic.
vcoubard 1065:473735376f13 191 */
vcoubard 1063:187f9929cb60 192 GattAttribute::Handle_t getDeclHandle(void) const {
rgrover1 716:11b41f651697 193 return declHandle;
rgrover1 716:11b41f651697 194 }
vcoubard 1063:187f9929cb60 195
vcoubard 1065:473735376f13 196 /**
vcoubard 1065:473735376f13 197 * @brief Return the handle used to access the value of this characteristic.
vcoubard 1065:473735376f13 198 * @details This handle is the one provided in the characteristic declaration
vcoubard 1065:473735376f13 199 * value. Usually, it is equal to <declaration handle> + 1. But it is not always
vcoubard 1065:473735376f13 200 * the case. Anyway, users are allowed to use <declaration handle> + 1 to access
vcoubard 1065:473735376f13 201 * the value of a characteristic.
vcoubard 1065:473735376f13 202 * @return The handle to access the value of this characteristic.
vcoubard 1065:473735376f13 203 */
vcoubard 1063:187f9929cb60 204 GattAttribute::Handle_t getValueHandle(void) const {
rgrover1 716:11b41f651697 205 return valueHandle;
rgrover1 716:11b41f651697 206 }
rgrover1 716:11b41f651697 207
vcoubard 1065:473735376f13 208 /**
vcoubard 1065:473735376f13 209 * @brief Return the last handle of the characteristic definition.
vcoubard 1065:473735376f13 210 * @details A Characteristic definition can contain a lot of handles:
vcoubard 1065:473735376f13 211 * - one for the declaration (see DiscoveredCharacteristic::getDeclHandle)
vcoubard 1065:473735376f13 212 * - one for the value (see DiscoveredCharacteristic::getValueHandle)
vcoubard 1065:473735376f13 213 * - zero of more for the characteristic descriptors.
vcoubard 1065:473735376f13 214 * This handle is the last handle of the characteristic definition.
vcoubard 1065:473735376f13 215 * @return The last handle of this characteristic definition.
vcoubard 1065:473735376f13 216 */
vcoubard 1063:187f9929cb60 217 GattAttribute::Handle_t getLastHandle(void) const {
vcoubard 1063:187f9929cb60 218 return lastHandle;
vcoubard 1063:187f9929cb60 219 }
vcoubard 1063:187f9929cb60 220
vcoubard 1065:473735376f13 221 void setLastHandle(GattAttribute::Handle_t last) {
vcoubard 1063:187f9929cb60 222 lastHandle = last;
vcoubard 1063:187f9929cb60 223 }
vcoubard 1063:187f9929cb60 224
vcoubard 1065:473735376f13 225 /**
vcoubard 1065:473735376f13 226 * @brief Return the GattClient which can operate on this characteristic.
vcoubard 1065:473735376f13 227 * @return The GattClient which can operate on this characteristic.
vcoubard 1065:473735376f13 228 */
vcoubard 1065:473735376f13 229 GattClient* getGattClient() {
vcoubard 1063:187f9929cb60 230 return gattc;
vcoubard 1063:187f9929cb60 231 }
vcoubard 1063:187f9929cb60 232
vcoubard 1065:473735376f13 233 /**
vcoubard 1065:473735376f13 234 * @brief Return the GattClient which can operate on this characteristic.
vcoubard 1065:473735376f13 235 * @return The GattClient which can operate on this characteristic.
vcoubard 1065:473735376f13 236 */
vcoubard 1065:473735376f13 237 const GattClient* getGattClient() const {
vcoubard 1063:187f9929cb60 238 return gattc;
vcoubard 1063:187f9929cb60 239 }
vcoubard 1063:187f9929cb60 240
vcoubard 1065:473735376f13 241 /**
vcoubard 1065:473735376f13 242 * @brief Return the connection handle to the GattServer which contain
vcoubard 1065:473735376f13 243 * this characteristic.
vcoubard 1065:473735376f13 244 * @return the connection handle to the GattServer which contain
vcoubard 1065:473735376f13 245 * this characteristic.
vcoubard 1065:473735376f13 246 */
vcoubard 1063:187f9929cb60 247 Gap::Handle_t getConnectionHandle() const {
vcoubard 1063:187f9929cb60 248 return connHandle;
vcoubard 1063:187f9929cb60 249 }
vcoubard 1063:187f9929cb60 250
vcoubard 1065:473735376f13 251 /**
vcoubard 1065:473735376f13 252 * @brief "Equal to" operator for DiscoveredCharacteristic
vcoubard 1065:473735376f13 253 *
vcoubard 1065:473735376f13 254 * @param lhs The left hand side of the equality expression
vcoubard 1065:473735376f13 255 * @param rhs The right hand side of the equality expression
vcoubard 1065:473735376f13 256 *
vcoubard 1065:473735376f13 257 * @return true if operands are equals, false otherwise.
vcoubard 1065:473735376f13 258 */
vcoubard 1065:473735376f13 259 friend bool operator==(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
vcoubard 1065:473735376f13 260 return lhs.gattc == rhs.gattc &&
vcoubard 1065:473735376f13 261 lhs.uuid == rhs.uuid &&
vcoubard 1065:473735376f13 262 lhs.props == rhs.props &&
vcoubard 1065:473735376f13 263 lhs.declHandle == rhs.declHandle &&
vcoubard 1065:473735376f13 264 lhs.valueHandle == rhs.valueHandle &&
vcoubard 1065:473735376f13 265 lhs.lastHandle == rhs.lastHandle &&
vcoubard 1065:473735376f13 266 lhs.connHandle == rhs.connHandle;
vcoubard 1063:187f9929cb60 267 }
vcoubard 1063:187f9929cb60 268
vcoubard 1065:473735376f13 269 /**
vcoubard 1065:473735376f13 270 * @brief "Not equal to" operator for DiscoveredCharacteristic
vcoubard 1065:473735376f13 271 *
vcoubard 1065:473735376f13 272 * @param lhs The right hand side of the expression
vcoubard 1065:473735376f13 273 * @param rhs The left hand side of the expression
vcoubard 1065:473735376f13 274 *
vcoubard 1065:473735376f13 275 * @return true if operands are not equals, false otherwise.
vcoubard 1065:473735376f13 276 */
vcoubard 1065:473735376f13 277 friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
vcoubard 1065:473735376f13 278 return !(lhs == rhs);
vcoubard 1063:187f9929cb60 279 }
vcoubard 1063:187f9929cb60 280
rgrover1 716:11b41f651697 281 public:
rgrover1 716:11b41f651697 282 DiscoveredCharacteristic() : gattc(NULL),
rgrover1 716:11b41f651697 283 uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 716:11b41f651697 284 props(),
rgrover1 716:11b41f651697 285 declHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1063:187f9929cb60 286 valueHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1063:187f9929cb60 287 lastHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1063:187f9929cb60 288 connHandle() {
rgrover1 716:11b41f651697 289 /* empty */
rgrover1 716:11b41f651697 290 }
rgrover1 716:11b41f651697 291
rgrover1 716:11b41f651697 292 protected:
rgrover1 716:11b41f651697 293 GattClient *gattc;
rgrover1 716:11b41f651697 294
rgrover1 716:11b41f651697 295 protected:
rgrover1 716:11b41f651697 296 UUID uuid;
rgrover1 716:11b41f651697 297 Properties_t props;
rgrover1 716:11b41f651697 298 GattAttribute::Handle_t declHandle;
rgrover1 716:11b41f651697 299 GattAttribute::Handle_t valueHandle;
vcoubard 1063:187f9929cb60 300 GattAttribute::Handle_t lastHandle;
rgrover1 716:11b41f651697 301
rgrover1 716:11b41f651697 302 Gap::Handle_t connHandle;
rgrover1 716:11b41f651697 303 };
rgrover1 716:11b41f651697 304
rgrover1 716:11b41f651697 305 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/