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@1052:b55e1ad3e1b3, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:31 2016 +0000
Revision:
1052:b55e1ad3e1b3
Parent:
1050:37101a458dfb
Child:
1053:ec4a5b9b254e
Synchronized with git rev 9f31f380

Author: Vincent Coubard

Merge remote-tracking branch 'origin/develop' into descriptorDiscovery

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 1048:efb29faf12fc 35 uint8_t _broadcast :1; /**< Broadcasting 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
vcoubard 1050:37101a458dfb 62 friend bool operator!=(Properties_t rhs, Properties_t lhs) {
vcoubard 1050:37101a458dfb 63 return !(rhs == lhs);
vcoubard 1050:37101a458dfb 64 }
vcoubard 1050:37101a458dfb 65
rgrover1 716:11b41f651697 66 private:
vcoubard 1048:efb29faf12fc 67 operator uint8_t() const; /* Disallow implicit conversion into an integer. */
vcoubard 1048:efb29faf12fc 68 operator unsigned() const; /* Disallow implicit conversion into an integer. */
rgrover1 716:11b41f651697 69 };
rgrover1 716:11b41f651697 70
rgrover1 716:11b41f651697 71 /**
rgrover1 716:11b41f651697 72 * Initiate (or continue) a read for the value attribute, optionally at a
vcoubard 1048:efb29faf12fc 73 * given offset. If the characteristic or descriptor to be read is longer
rgrover1 716:11b41f651697 74 * than ATT_MTU - 1, this function must be called multiple times with
rgrover1 716:11b41f651697 75 * appropriate offset to read the complete value.
rgrover1 716:11b41f651697 76 *
vcoubard 1048:efb29faf12fc 77 * @return BLE_ERROR_NONE if a read has been initiated, or
rgrover1 716:11b41f651697 78 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 79 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 80 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 81 */
rgrover1 716:11b41f651697 82 ble_error_t read(uint16_t offset = 0) const;
rgrover1 716:11b41f651697 83
vcoubard 1052:b55e1ad3e1b3 84 ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 85
rgrover1 716:11b41f651697 86 /**
rgrover1 716:11b41f651697 87 * Perform a write without response procedure.
rgrover1 716:11b41f651697 88 *
rgrover1 716:11b41f651697 89 * @param length
rgrover1 716:11b41f651697 90 * The amount of data being written.
rgrover1 716:11b41f651697 91 * @param value
rgrover1 716:11b41f651697 92 * The bytes being written.
rgrover1 716:11b41f651697 93 *
rgrover1 716:11b41f651697 94 * @note It is important to note that a write without response will generate
rgrover1 716:11b41f651697 95 * an onDataSent() callback when the packet has been transmitted. There
rgrover1 716:11b41f651697 96 * will be a BLE-stack specific limit to the number of pending
rgrover1 716:11b41f651697 97 * writeWoResponse operations; the user may want to use the onDataSent()
rgrover1 716:11b41f651697 98 * callback for flow-control.
rgrover1 716:11b41f651697 99 *
vcoubard 1048:efb29faf12fc 100 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 101 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 102 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 103 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 104 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 105 */
rgrover1 716:11b41f651697 106 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 107
rgrover1 716:11b41f651697 108 /**
rgrover1 716:11b41f651697 109 * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
rgrover1 716:11b41f651697 110 *
vcoubard 1045:b9d15970040f 111 * @param onCharacteristicDiscovered This callback will be called every time a descriptor is discovered
vcoubard 1045:b9d15970040f 112 * @param onTermination This callback will be called when the discovery process is over.
rgrover1 716:11b41f651697 113 *
rgrover1 716:11b41f651697 114 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 716:11b41f651697 115 */
vcoubard 1047:2d66d38d9ac9 116 ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered,
vcoubard 1047:2d66d38d9ac9 117 const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const;
rgrover1 716:11b41f651697 118
rgrover1 716:11b41f651697 119 /**
rgrover1 716:11b41f651697 120 * Perform a write procedure.
rgrover1 716:11b41f651697 121 *
rgrover1 716:11b41f651697 122 * @param length
rgrover1 716:11b41f651697 123 * The amount of data being written.
rgrover1 716:11b41f651697 124 * @param value
rgrover1 716:11b41f651697 125 * The bytes being written.
rgrover1 716:11b41f651697 126 *
rgrover1 716:11b41f651697 127 * @note It is important to note that a write will generate
rgrover1 716:11b41f651697 128 * an onDataWritten() callback when the peer acknowledges the request.
rgrover1 716:11b41f651697 129 *
vcoubard 1048:efb29faf12fc 130 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 131 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
vcoubard 1048:efb29faf12fc 132 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 133 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 134 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 135 */
rgrover1 716:11b41f651697 136 ble_error_t write(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 137
vcoubard 1052:b55e1ad3e1b3 138 /**
vcoubard 1052:b55e1ad3e1b3 139 * Same as above but register the callback wich will be called once the data has been written
vcoubard 1052:b55e1ad3e1b3 140 */
vcoubard 1052:b55e1ad3e1b3 141 ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 142
vcoubard 1042:21a86ac7f5b1 143 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
vcoubard 1042:21a86ac7f5b1 144 uuid.setupLong(longUUID);
rgrover1 716:11b41f651697 145 }
rgrover1 716:11b41f651697 146
rgrover1 716:11b41f651697 147 public:
rgrover1 741:d6dceefb844e 148 const UUID& getUUID(void) const {
rgrover1 741:d6dceefb844e 149 return uuid;
rgrover1 716:11b41f651697 150 }
rgrover1 716:11b41f651697 151
rgrover1 716:11b41f651697 152 const Properties_t& getProperties(void) const {
rgrover1 716:11b41f651697 153 return props;
rgrover1 716:11b41f651697 154 }
rgrover1 716:11b41f651697 155
vcoubard 1045:b9d15970040f 156 GattAttribute::Handle_t getDeclHandle(void) const {
rgrover1 716:11b41f651697 157 return declHandle;
rgrover1 716:11b41f651697 158 }
vcoubard 1045:b9d15970040f 159
vcoubard 1045:b9d15970040f 160 GattAttribute::Handle_t getValueHandle(void) const {
rgrover1 716:11b41f651697 161 return valueHandle;
rgrover1 716:11b41f651697 162 }
rgrover1 716:11b41f651697 163
vcoubard 1045:b9d15970040f 164 GattAttribute::Handle_t getLastHandle(void) const {
vcoubard 1045:b9d15970040f 165 return lastHandle;
vcoubard 1045:b9d15970040f 166 }
vcoubard 1045:b9d15970040f 167
vcoubard 1046:87a2ebe45470 168 void setLastHandle(GattAttribute::Handle_t last) {
vcoubard 1046:87a2ebe45470 169 lastHandle = last;
vcoubard 1046:87a2ebe45470 170 }
vcoubard 1046:87a2ebe45470 171
vcoubard 1045:b9d15970040f 172 GattClient* getGattClient() {
vcoubard 1045:b9d15970040f 173 return gattc;
vcoubard 1045:b9d15970040f 174 }
vcoubard 1045:b9d15970040f 175
vcoubard 1045:b9d15970040f 176 const GattClient* getGattClient() const {
vcoubard 1045:b9d15970040f 177 return gattc;
vcoubard 1045:b9d15970040f 178 }
vcoubard 1045:b9d15970040f 179
vcoubard 1045:b9d15970040f 180 Gap::Handle_t getConnectionHandle() const {
vcoubard 1045:b9d15970040f 181 return connHandle;
vcoubard 1045:b9d15970040f 182 }
vcoubard 1045:b9d15970040f 183
vcoubard 1045:b9d15970040f 184 friend bool operator==(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) {
vcoubard 1046:87a2ebe45470 185 return rhs.gattc == lhs.gattc &&
vcoubard 1045:b9d15970040f 186 rhs.uuid == lhs.uuid &&
vcoubard 1046:87a2ebe45470 187 rhs.props == lhs.props &&
vcoubard 1045:b9d15970040f 188 rhs.declHandle == lhs.declHandle &&
vcoubard 1045:b9d15970040f 189 rhs.valueHandle == lhs.valueHandle &&
vcoubard 1045:b9d15970040f 190 rhs.lastHandle == lhs.lastHandle &&
vcoubard 1045:b9d15970040f 191 rhs.connHandle == lhs.connHandle;
vcoubard 1045:b9d15970040f 192 }
vcoubard 1045:b9d15970040f 193
vcoubard 1046:87a2ebe45470 194 friend bool operator !=(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) {
vcoubard 1046:87a2ebe45470 195 return !(rhs == lhs);
vcoubard 1046:87a2ebe45470 196 }
vcoubard 1046:87a2ebe45470 197
rgrover1 716:11b41f651697 198 public:
rgrover1 716:11b41f651697 199 DiscoveredCharacteristic() : gattc(NULL),
rgrover1 716:11b41f651697 200 uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 716:11b41f651697 201 props(),
rgrover1 716:11b41f651697 202 declHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1045:b9d15970040f 203 valueHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1046:87a2ebe45470 204 lastHandle(GattAttribute::INVALID_HANDLE),
vcoubard 1046:87a2ebe45470 205 connHandle() {
rgrover1 716:11b41f651697 206 /* empty */
rgrover1 716:11b41f651697 207 }
rgrover1 716:11b41f651697 208
rgrover1 716:11b41f651697 209 protected:
rgrover1 716:11b41f651697 210 GattClient *gattc;
rgrover1 716:11b41f651697 211
rgrover1 716:11b41f651697 212 protected:
rgrover1 716:11b41f651697 213 UUID uuid;
rgrover1 716:11b41f651697 214 Properties_t props;
rgrover1 716:11b41f651697 215 GattAttribute::Handle_t declHandle;
rgrover1 716:11b41f651697 216 GattAttribute::Handle_t valueHandle;
vcoubard 1045:b9d15970040f 217 GattAttribute::Handle_t lastHandle;
rgrover1 716:11b41f651697 218
rgrover1 716:11b41f651697 219 Gap::Handle_t connHandle;
rgrover1 716:11b41f651697 220 };
rgrover1 716:11b41f651697 221
rgrover1 716:11b41f651697 222 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/