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@1047:2d66d38d9ac9, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:27 2016 +0000
Revision:
1047:2d66d38d9ac9
Parent:
1046:87a2ebe45470
Child:
1048:efb29faf12fc
Synchronized with git rev b8260b51

Author: Vincent Coubard

Use const reference instead of value for characteristic discovery

callbacks

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 1045:b9d15970040f 24 #include "CharacteristicDescriptorDiscovery.h"
vcoubard 1045:b9d15970040f 25 #include "ble/DiscoveredCharacteristicDescriptor.h"
vcoubard 1045:b9d15970040f 26
rgrover1 716:11b41f651697 27
rgrover1 716:11b41f651697 28 /**
rgrover1 716:11b41f651697 29 * Structure for holding information about the service and the characteristics
rgrover1 716:11b41f651697 30 * found during the discovery process.
rgrover1 716:11b41f651697 31 */
rgrover1 716:11b41f651697 32 class DiscoveredCharacteristic {
rgrover1 716:11b41f651697 33 public:
rgrover1 716:11b41f651697 34 struct Properties_t {
vcoubard 1042:21a86ac7f5b1 35 uint8_t _broadcast :1; /**< Broadcasting of the value permitted. */
rgrover1 716:11b41f651697 36 uint8_t _read :1; /**< Reading the value permitted. */
rgrover1 716:11b41f651697 37 uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */
rgrover1 716:11b41f651697 38 uint8_t _write :1; /**< Writing the value with Write Request permitted. */
rgrover1 716:11b41f651697 39 uint8_t _notify :1; /**< Notications of the value permitted. */
rgrover1 716:11b41f651697 40 uint8_t _indicate :1; /**< Indications of the value permitted. */
rgrover1 716:11b41f651697 41 uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
rgrover1 716:11b41f651697 42
rgrover1 716:11b41f651697 43 public:
rgrover1 716:11b41f651697 44 bool broadcast(void) const {return _broadcast; }
rgrover1 716:11b41f651697 45 bool read(void) const {return _read; }
rgrover1 716:11b41f651697 46 bool writeWoResp(void) const {return _writeWoResp; }
rgrover1 716:11b41f651697 47 bool write(void) const {return _write; }
rgrover1 716:11b41f651697 48 bool notify(void) const {return _notify; }
rgrover1 716:11b41f651697 49 bool indicate(void) const {return _indicate; }
rgrover1 716:11b41f651697 50 bool authSignedWrite(void) const {return _authSignedWrite;}
rgrover1 716:11b41f651697 51
vcoubard 1045:b9d15970040f 52 friend bool operator==(Properties_t rhs, Properties_t lhs) {
vcoubard 1045:b9d15970040f 53 return rhs._broadcast == lhs._broadcast &&
vcoubard 1045:b9d15970040f 54 rhs._read == lhs._read &&
vcoubard 1045:b9d15970040f 55 rhs._writeWoResp == lhs._writeWoResp &&
vcoubard 1045:b9d15970040f 56 rhs._write == lhs._write &&
vcoubard 1045:b9d15970040f 57 rhs._notify == lhs._notify &&
vcoubard 1045:b9d15970040f 58 rhs._indicate == lhs._indicate &&
vcoubard 1045:b9d15970040f 59 rhs._authSignedWrite == lhs._authSignedWrite;
vcoubard 1045:b9d15970040f 60 }
vcoubard 1045:b9d15970040f 61
rgrover1 716:11b41f651697 62 private:
vcoubard 1042:21a86ac7f5b1 63 operator uint8_t() const; /* disallow implicit conversion into an integer */
vcoubard 1042:21a86ac7f5b1 64 operator unsigned() const; /* disallow implicit conversion into an integer */
rgrover1 716:11b41f651697 65 };
rgrover1 716:11b41f651697 66
rgrover1 716:11b41f651697 67 /**
rgrover1 716:11b41f651697 68 * Initiate (or continue) a read for the value attribute, optionally at a
vcoubard 1042:21a86ac7f5b1 69 * given offset. If the Characteristic or Descriptor to be read is longer
rgrover1 716:11b41f651697 70 * than ATT_MTU - 1, this function must be called multiple times with
rgrover1 716:11b41f651697 71 * appropriate offset to read the complete value.
rgrover1 716:11b41f651697 72 *
vcoubard 1042:21a86ac7f5b1 73 * @return BLE_ERROR_NONE if a read has been initiated, else
rgrover1 716:11b41f651697 74 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1042:21a86ac7f5b1 75 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 716:11b41f651697 76 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 77 */
rgrover1 716:11b41f651697 78 ble_error_t read(uint16_t offset = 0) const;
rgrover1 716:11b41f651697 79
rgrover1 716:11b41f651697 80 /**
rgrover1 716:11b41f651697 81 * Perform a write without response procedure.
rgrover1 716:11b41f651697 82 *
rgrover1 716:11b41f651697 83 * @param length
rgrover1 716:11b41f651697 84 * The amount of data being written.
rgrover1 716:11b41f651697 85 * @param value
rgrover1 716:11b41f651697 86 * The bytes being written.
rgrover1 716:11b41f651697 87 *
rgrover1 716:11b41f651697 88 * @note It is important to note that a write without response will generate
rgrover1 716:11b41f651697 89 * an onDataSent() callback when the packet has been transmitted. There
rgrover1 716:11b41f651697 90 * will be a BLE-stack specific limit to the number of pending
rgrover1 716:11b41f651697 91 * writeWoResponse operations; the user may want to use the onDataSent()
rgrover1 716:11b41f651697 92 * callback for flow-control.
rgrover1 716:11b41f651697 93 *
vcoubard 1042:21a86ac7f5b1 94 * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
rgrover1 716:11b41f651697 95 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1042:21a86ac7f5b1 96 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 716:11b41f651697 97 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 98 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 99 */
rgrover1 716:11b41f651697 100 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 101
rgrover1 716:11b41f651697 102 /**
rgrover1 716:11b41f651697 103 * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
rgrover1 716:11b41f651697 104 *
vcoubard 1045:b9d15970040f 105 * @param onCharacteristicDiscovered This callback will be called every time a descriptor is discovered
vcoubard 1045:b9d15970040f 106 * @param onTermination This callback will be called when the discovery process is over.
rgrover1 716:11b41f651697 107 *
rgrover1 716:11b41f651697 108 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 716:11b41f651697 109 */
vcoubard 1047:2d66d38d9ac9 110 ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered,
vcoubard 1047:2d66d38d9ac9 111 const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const;
rgrover1 716:11b41f651697 112
rgrover1 716:11b41f651697 113 /**
rgrover1 716:11b41f651697 114 * Perform a write procedure.
rgrover1 716:11b41f651697 115 *
rgrover1 716:11b41f651697 116 * @param length
rgrover1 716:11b41f651697 117 * The amount of data being written.
rgrover1 716:11b41f651697 118 * @param value
rgrover1 716:11b41f651697 119 * The bytes being written.
rgrover1 716:11b41f651697 120 *
rgrover1 716:11b41f651697 121 * @note It is important to note that a write will generate
rgrover1 716:11b41f651697 122 * an onDataWritten() callback when the peer acknowledges the request.
rgrover1 716:11b41f651697 123 *
vcoubard 1042:21a86ac7f5b1 124 * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
rgrover1 716:11b41f651697 125 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1042:21a86ac7f5b1 126 * BLE_STACK_BUSY if some client procedure already in progress, or
rgrover1 716:11b41f651697 127 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 128 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 129 */
rgrover1 716:11b41f651697 130 ble_error_t write(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 131
vcoubard 1042:21a86ac7f5b1 132 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
vcoubard 1042:21a86ac7f5b1 133 uuid.setupLong(longUUID);
rgrover1 716:11b41f651697 134 }
rgrover1 716:11b41f651697 135
rgrover1 716:11b41f651697 136 public:
rgrover1 741:d6dceefb844e 137 const UUID& getUUID(void) const {
rgrover1 741:d6dceefb844e 138 return uuid;
rgrover1 716:11b41f651697 139 }
rgrover1 716:11b41f651697 140
rgrover1 716:11b41f651697 141 const Properties_t& getProperties(void) const {
rgrover1 716:11b41f651697 142 return props;
rgrover1 716:11b41f651697 143 }
rgrover1 716:11b41f651697 144
vcoubard 1045:b9d15970040f 145 GattAttribute::Handle_t getDeclHandle(void) const {
rgrover1 716:11b41f651697 146 return declHandle;
rgrover1 716:11b41f651697 147 }
vcoubard 1045:b9d15970040f 148
vcoubard 1045:b9d15970040f 149 GattAttribute::Handle_t getValueHandle(void) const {
rgrover1 716:11b41f651697 150 return valueHandle;
rgrover1 716:11b41f651697 151 }
rgrover1 716:11b41f651697 152
vcoubard 1045:b9d15970040f 153 GattAttribute::Handle_t getLastHandle(void) const {
vcoubard 1045:b9d15970040f 154 return lastHandle;
vcoubard 1045:b9d15970040f 155 }
vcoubard 1045:b9d15970040f 156
vcoubard 1046:87a2ebe45470 157 void setLastHandle(GattAttribute::Handle_t last) {
vcoubard 1046:87a2ebe45470 158 lastHandle = last;
vcoubard 1046:87a2ebe45470 159 }
vcoubard 1046:87a2ebe45470 160
vcoubard 1045:b9d15970040f 161 GattClient* getGattClient() {
vcoubard 1045:b9d15970040f 162 return gattc;
vcoubard 1045:b9d15970040f 163 }
vcoubard 1045:b9d15970040f 164
vcoubard 1045:b9d15970040f 165 const GattClient* getGattClient() const {
vcoubard 1045:b9d15970040f 166 return gattc;
vcoubard 1045:b9d15970040f 167 }
vcoubard 1045:b9d15970040f 168
vcoubard 1045:b9d15970040f 169 Gap::Handle_t getConnectionHandle() const {
vcoubard 1045:b9d15970040f 170 return connHandle;
vcoubard 1045:b9d15970040f 171 }
vcoubard 1045:b9d15970040f 172
vcoubard 1045:b9d15970040f 173 friend bool operator==(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) {
vcoubard 1046:87a2ebe45470 174 return rhs.gattc == lhs.gattc &&
vcoubard 1045:b9d15970040f 175 rhs.uuid == lhs.uuid &&
vcoubard 1046:87a2ebe45470 176 rhs.props == lhs.props &&
vcoubard 1045:b9d15970040f 177 rhs.declHandle == lhs.declHandle &&
vcoubard 1045:b9d15970040f 178 rhs.valueHandle == lhs.valueHandle &&
vcoubard 1045:b9d15970040f 179 rhs.lastHandle == lhs.lastHandle &&
vcoubard 1045:b9d15970040f 180 rhs.connHandle == lhs.connHandle;
vcoubard 1045:b9d15970040f 181 }
vcoubard 1045:b9d15970040f 182
vcoubard 1046:87a2ebe45470 183 friend bool operator !=(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) {
vcoubard 1046:87a2ebe45470 184 return !(rhs == lhs);
vcoubard 1046:87a2ebe45470 185 }
vcoubard 1046:87a2ebe45470 186
rgrover1 716:11b41f651697 187 public:
rgrover1 716:11b41f651697 188 DiscoveredCharacteristic() : gattc(NULL),
rgrover1 716:11b41f651697 189 uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 716:11b41f651697 190 props(),
rgrover1 716:11b41f651697 191 declHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1045:b9d15970040f 192 valueHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1046:87a2ebe45470 193 lastHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1046:87a2ebe45470 194 connHandle() {
rgrover1 716:11b41f651697 195 /* empty */
rgrover1 716:11b41f651697 196 }
rgrover1 716:11b41f651697 197
rgrover1 716:11b41f651697 198 protected:
rgrover1 716:11b41f651697 199 GattClient *gattc;
rgrover1 716:11b41f651697 200
rgrover1 716:11b41f651697 201 protected:
rgrover1 716:11b41f651697 202 UUID uuid;
rgrover1 716:11b41f651697 203 Properties_t props;
rgrover1 716:11b41f651697 204 GattAttribute::Handle_t declHandle;
rgrover1 716:11b41f651697 205 GattAttribute::Handle_t valueHandle;
vcoubard 1045:b9d15970040f 206 GattAttribute::Handle_t lastHandle;
rgrover1 716:11b41f651697 207
rgrover1 716:11b41f651697 208 Gap::Handle_t connHandle;
rgrover1 716:11b41f651697 209 };
rgrover1 716:11b41f651697 210
rgrover1 716:11b41f651697 211 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/