Michael Galis / nRF51822

No changes

Fork of nRF51822 by Nordic Semiconductor

source/nRF5xCharacteristicDescriptorDiscoverer.h@568:13b23a4b1f58, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:20 2016 +0000
Revision:
568:13b23a4b1f58
Parent:
563:9c4b96f7be8d
Child:
569:9e72aa06ec32
Synchronized with git rev c8d826ff

Author: Vincent Coubard

Documentation of descriptor discoverer class.

Simplify the process

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 563:9c4b96f7be8d 1 /* mbed Microcontroller Library
vcoubard 563:9c4b96f7be8d 2 * Copyright (c) 2006-2015 ARM Limited
vcoubard 563:9c4b96f7be8d 3 *
vcoubard 563:9c4b96f7be8d 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 563:9c4b96f7be8d 5 * you may not use this file except in compliance with the License.
vcoubard 563:9c4b96f7be8d 6 * You may obtain a copy of the License at
vcoubard 563:9c4b96f7be8d 7 *
vcoubard 563:9c4b96f7be8d 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 563:9c4b96f7be8d 9 *
vcoubard 563:9c4b96f7be8d 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 563:9c4b96f7be8d 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 563:9c4b96f7be8d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 563:9c4b96f7be8d 13 * See the License for the specific language governing permissions and
vcoubard 563:9c4b96f7be8d 14 * limitations under the License.
vcoubard 563:9c4b96f7be8d 15 */
vcoubard 563:9c4b96f7be8d 16
vcoubard 563:9c4b96f7be8d 17 #ifndef __NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
vcoubard 563:9c4b96f7be8d 18 #define __NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
vcoubard 563:9c4b96f7be8d 19
vcoubard 563:9c4b96f7be8d 20 #include "ble/Gap.h"
vcoubard 563:9c4b96f7be8d 21 #include "ble/DiscoveredCharacteristic.h"
vcoubard 563:9c4b96f7be8d 22 #include "ble/CharacteristicDescriptorDiscovery.h"
vcoubard 563:9c4b96f7be8d 23 #include "ble/GattClient.h"
vcoubard 563:9c4b96f7be8d 24 #include "ble_gattc.h"
vcoubard 563:9c4b96f7be8d 25
vcoubard 563:9c4b96f7be8d 26 /**
vcoubard 568:13b23a4b1f58 27 * @brief Manage the discovery of Characteristic descriptors
vcoubard 568:13b23a4b1f58 28 * @details is a bridge between BLE API and Nordic stack regarding Characteristic
vcoubard 568:13b23a4b1f58 29 * Descriptor discovery. The BLE API can launch, monitor and ask for termination
vcoubard 568:13b23a4b1f58 30 * of a discovery. The Nordic stack will provide new descriptors and indicate when
vcoubard 568:13b23a4b1f58 31 * the discovery is done.
vcoubard 563:9c4b96f7be8d 32 */
vcoubard 563:9c4b96f7be8d 33 class nRF5xCharacteristicDescriptorDiscoverer
vcoubard 563:9c4b96f7be8d 34 {
vcoubard 563:9c4b96f7be8d 35 typedef CharacteristicDescriptorDiscovery::DiscoveryCallback_t DiscoveryCallback_t;
vcoubard 563:9c4b96f7be8d 36 typedef CharacteristicDescriptorDiscovery::TerminationCallback_t TerminationCallback_t;
vcoubard 563:9c4b96f7be8d 37
vcoubard 563:9c4b96f7be8d 38 public:
vcoubard 568:13b23a4b1f58 39 /**
vcoubard 568:13b23a4b1f58 40 * @brief Construct a new characteristic descriptor discoverer.
vcoubard 568:13b23a4b1f58 41 */
vcoubard 568:13b23a4b1f58 42 nRF5xCharacteristicDescriptorDiscoverer();
vcoubard 563:9c4b96f7be8d 43
vcoubard 568:13b23a4b1f58 44 /**
vcoubard 568:13b23a4b1f58 45 * @brief Destroy a characteristic descriptor discoverer.
vcoubard 568:13b23a4b1f58 46 */
vcoubard 563:9c4b96f7be8d 47 ~nRF5xCharacteristicDescriptorDiscoverer();
vcoubard 563:9c4b96f7be8d 48
vcoubard 563:9c4b96f7be8d 49 /**
vcoubard 568:13b23a4b1f58 50 * Launch a new characteristic descriptor discovery for a given DiscoveredCharacteristic.
vcoubard 568:13b23a4b1f58 51 * @param characteristic The characteristic owning the descriptors to discover.
vcoubard 568:13b23a4b1f58 52 * @param discoveryCallback The callback called when a descriptor is discovered.
vcoubard 568:13b23a4b1f58 53 * @param terminationCallback The callback called when the discovery process end.
vcoubard 568:13b23a4b1f58 54 * @return BLE_ERROR_NONE if characteristic descriptor discovery is launched successfully;
vcoubard 568:13b23a4b1f58 55 * else an appropriate error.
vcoubard 568:13b23a4b1f58 56 * @note: this will be called by BLE API side.
vcoubard 563:9c4b96f7be8d 57 */
vcoubard 563:9c4b96f7be8d 58 ble_error_t launch(
vcoubard 568:13b23a4b1f58 59 const DiscoveredCharacteristic& characteristic,
vcoubard 568:13b23a4b1f58 60 const DiscoveryCallback_t& discoveryCallback,
vcoubard 563:9c4b96f7be8d 61 const TerminationCallback_t& terminationCallback
vcoubard 563:9c4b96f7be8d 62 );
vcoubard 563:9c4b96f7be8d 63
vcoubard 563:9c4b96f7be8d 64 /**
vcoubard 568:13b23a4b1f58 65 * @brief indicate if a characteristic descriptor discovery is active for a
vcoubard 568:13b23a4b1f58 66 * given DiscoveredCharacteristic.
vcoubard 568:13b23a4b1f58 67 * @param characteristic The characteristic for whom the descriptor might be
vcoubard 568:13b23a4b1f58 68 * currently discovered.
vcoubard 568:13b23a4b1f58 69 * @return true if descriptors of characteristic are discovered, false otherwise.
vcoubard 568:13b23a4b1f58 70 * @note: this will be called by BLE API side.
vcoubard 563:9c4b96f7be8d 71 */
vcoubard 563:9c4b96f7be8d 72 bool isActive(const DiscoveredCharacteristic& characteristic) const;
vcoubard 563:9c4b96f7be8d 73
vcoubard 563:9c4b96f7be8d 74 /**
vcoubard 568:13b23a4b1f58 75 * @brief request the termination of characteristic descriptor discovery
vcoubard 563:9c4b96f7be8d 76 * for a give DiscoveredCharacteristic
vcoubard 568:13b23a4b1f58 77 * @param characteristic The characteristic for whom the descriptor discovery
vcoubard 568:13b23a4b1f58 78 * should be stopped.
vcoubard 568:13b23a4b1f58 79 * @note: this will be called by BLE API side.
vcoubard 563:9c4b96f7be8d 80 */
vcoubard 563:9c4b96f7be8d 81 void requestTerminate(const DiscoveredCharacteristic& characteristic);
vcoubard 563:9c4b96f7be8d 82
vcoubard 563:9c4b96f7be8d 83 /**
vcoubard 568:13b23a4b1f58 84 * @brief process descriptors discovered from the Nordic stack.
vcoubard 568:13b23a4b1f58 85 * @param connectionHandle The connection handle upon which descriptors has been
vcoubard 568:13b23a4b1f58 86 * discovered.
vcoubard 568:13b23a4b1f58 87 * @param descriptors Discovered descriptors.
vcoubard 568:13b23a4b1f58 88 * @note This will be called by the Nordic stack.
vcoubard 563:9c4b96f7be8d 89 */
vcoubard 568:13b23a4b1f58 90 void process(uint16_t connectionHandle, const ble_gattc_evt_desc_disc_rsp_t& descriptors);
vcoubard 563:9c4b96f7be8d 91
vcoubard 563:9c4b96f7be8d 92 /**
vcoubard 568:13b23a4b1f58 93 * @brief Called by the Nordic stack when the discovery is over.
vcoubard 568:13b23a4b1f58 94 * @param The connection handle upon which the discovery process is done.
vcoubard 568:13b23a4b1f58 95 * @param err An error if the termination is due to an error.
vcoubard 563:9c4b96f7be8d 96 */
vcoubard 568:13b23a4b1f58 97 void terminate(uint16_t connectionHandle, ble_error_t err);
vcoubard 563:9c4b96f7be8d 98
vcoubard 563:9c4b96f7be8d 99 private:
vcoubard 568:13b23a4b1f58 100 // protection against copy construction and assignment
vcoubard 563:9c4b96f7be8d 101 nRF5xCharacteristicDescriptorDiscoverer(const nRF5xCharacteristicDescriptorDiscoverer&);
vcoubard 563:9c4b96f7be8d 102 nRF5xCharacteristicDescriptorDiscoverer& operator=(const nRF5xCharacteristicDescriptorDiscoverer&);
vcoubard 563:9c4b96f7be8d 103
vcoubard 568:13b23a4b1f58 104 /**
vcoubard 568:13b23a4b1f58 105 * @brief Discovery process, it store the DiscoveredCharacteristic, the
vcoubard 568:13b23a4b1f58 106 * discovery callback and the termination callback.
vcoubard 568:13b23a4b1f58 107 */
vcoubard 563:9c4b96f7be8d 108 struct Discovery {
vcoubard 568:13b23a4b1f58 109 /**
vcoubard 568:13b23a4b1f58 110 * @brief Construct an empty discovery, such can be considerate as a not running discovery.
vcoubard 568:13b23a4b1f58 111 * @note #isEmpty function will return true
vcoubard 568:13b23a4b1f58 112 */
vcoubard 563:9c4b96f7be8d 113 Discovery() : characteristic(), onDiscovery(), onTerminate() { }
vcoubard 563:9c4b96f7be8d 114
vcoubard 568:13b23a4b1f58 115 /**
vcoubard 568:13b23a4b1f58 116 * @brief Construct a valid discovery process.
vcoubard 568:13b23a4b1f58 117 *
vcoubard 568:13b23a4b1f58 118 * @param c the characteristic from whom descriptors will be discovered.
vcoubard 568:13b23a4b1f58 119 * @param dCb The discovery callback called each time a descriptor is discovered.
vcoubard 568:13b23a4b1f58 120 * @param tCb The termination callback called when the discovery terminate.
vcoubard 568:13b23a4b1f58 121 *
vcoubard 568:13b23a4b1f58 122 * @note #isEmpty function will return false
vcoubard 568:13b23a4b1f58 123 */
vcoubard 568:13b23a4b1f58 124 Discovery(const DiscoveredCharacteristic& c, const DiscoveryCallback_t& dCb, const TerminationCallback_t& tCb) :
vcoubard 568:13b23a4b1f58 125 characteristic(c),
vcoubard 568:13b23a4b1f58 126 onDiscovery(dCb),
vcoubard 568:13b23a4b1f58 127 onTerminate(tCb) {
vcoubard 563:9c4b96f7be8d 128 }
vcoubard 563:9c4b96f7be8d 129
vcoubard 563:9c4b96f7be8d 130 DiscoveredCharacteristic characteristic;
vcoubard 563:9c4b96f7be8d 131 DiscoveryCallback_t onDiscovery;
vcoubard 563:9c4b96f7be8d 132 TerminationCallback_t onTerminate;
vcoubard 563:9c4b96f7be8d 133
vcoubard 568:13b23a4b1f58 134 /**
vcoubard 568:13b23a4b1f58 135 * @brief Process the discovery of a descriptor.
vcoubard 568:13b23a4b1f58 136 *
vcoubard 568:13b23a4b1f58 137 * @param handle The attribute handle of the descriptor found
vcoubard 568:13b23a4b1f58 138 * @param uuid The UUID of the descriptor found.
vcoubard 568:13b23a4b1f58 139 */
vcoubard 568:13b23a4b1f58 140 void process(GattAttribute::Handle_t handle, const UUID& uuid) {
vcoubard 568:13b23a4b1f58 141 CharacteristicDescriptorDiscovery::DiscoveryCallbackParams_t params = {
vcoubard 563:9c4b96f7be8d 142 characteristic,
vcoubard 563:9c4b96f7be8d 143 DiscoveredCharacteristicDescriptor(
vcoubard 563:9c4b96f7be8d 144 characteristic.getGattClient(),
vcoubard 563:9c4b96f7be8d 145 characteristic.getConnectionHandle(),
vcoubard 563:9c4b96f7be8d 146 handle,
vcoubard 563:9c4b96f7be8d 147 uuid
vcoubard 563:9c4b96f7be8d 148 )
vcoubard 563:9c4b96f7be8d 149 };
vcoubard 563:9c4b96f7be8d 150 onDiscovery.call(&params);
vcoubard 563:9c4b96f7be8d 151 }
vcoubard 563:9c4b96f7be8d 152
vcoubard 568:13b23a4b1f58 153 /**
vcoubard 568:13b23a4b1f58 154 * @brief Terminate the discovery process.
vcoubard 568:13b23a4b1f58 155 *
vcoubard 568:13b23a4b1f58 156 * @param err Error associate with the termination
vcoubard 568:13b23a4b1f58 157 *
vcoubard 568:13b23a4b1f58 158 * @note after this call #isEmpty function will return true.
vcoubard 568:13b23a4b1f58 159 */
vcoubard 568:13b23a4b1f58 160 void terminate(ble_error_t err) {
vcoubard 563:9c4b96f7be8d 161 CharacteristicDescriptorDiscovery::TerminationCallbackParams_t params = {
vcoubard 563:9c4b96f7be8d 162 characteristic,
vcoubard 563:9c4b96f7be8d 163 err
vcoubard 563:9c4b96f7be8d 164 };
vcoubard 568:13b23a4b1f58 165
vcoubard 563:9c4b96f7be8d 166 onTerminate.call(&params);
vcoubard 563:9c4b96f7be8d 167 }
vcoubard 563:9c4b96f7be8d 168
vcoubard 568:13b23a4b1f58 169 /**
vcoubard 568:13b23a4b1f58 170 * @brief check if the discovery process is empty or not. Empty discovery are
vcoubard 568:13b23a4b1f58 171 * not running.
vcoubard 568:13b23a4b1f58 172 * @detail Discovery are empty after:
vcoubard 568:13b23a4b1f58 173 * - a default construction
vcoubard 568:13b23a4b1f58 174 * - a copy construction form a default constructed
vcoubard 568:13b23a4b1f58 175 * - an assignment from a default constructed Discovery
vcoubard 568:13b23a4b1f58 176 * @return true if the Discovery is empty and false otherwise.
vcoubard 568:13b23a4b1f58 177 */
vcoubard 568:13b23a4b1f58 178 bool isEmpty() const {
vcoubard 568:13b23a4b1f58 179 return *this == Discovery();
vcoubard 568:13b23a4b1f58 180 }
vcoubard 568:13b23a4b1f58 181
vcoubard 568:13b23a4b1f58 182 /**
vcoubard 568:13b23a4b1f58 183 * @brief equal to operator, test if two discovery process are equal
vcoubard 568:13b23a4b1f58 184 * @param lhs left hand side of the expression
vcoubard 568:13b23a4b1f58 185 * @param rhs right hand side of the expression
vcoubard 568:13b23a4b1f58 186 * @return true if lhs == rhs
vcoubard 568:13b23a4b1f58 187 */
vcoubard 563:9c4b96f7be8d 188 friend bool operator==(const Discovery& lhs, const Discovery& rhs) {
vcoubard 563:9c4b96f7be8d 189 return lhs.characteristic == rhs.characteristic &&
vcoubard 563:9c4b96f7be8d 190 lhs.onDiscovery == rhs.onDiscovery &&
vcoubard 563:9c4b96f7be8d 191 lhs.onTerminate == rhs.onTerminate;
vcoubard 563:9c4b96f7be8d 192 }
vcoubard 563:9c4b96f7be8d 193
vcoubard 568:13b23a4b1f58 194 /**
vcoubard 568:13b23a4b1f58 195 * @brief not equal to operator, test if two discovery process are not equal
vcoubard 568:13b23a4b1f58 196 * @param lhs left hand side of the expression
vcoubard 568:13b23a4b1f58 197 * @param rhs right hand side of the expression
vcoubard 568:13b23a4b1f58 198 * @return true if lhs != rhs
vcoubard 568:13b23a4b1f58 199 */
vcoubard 563:9c4b96f7be8d 200 friend bool operator!=(const Discovery& lhs, const Discovery& rhs) {
vcoubard 563:9c4b96f7be8d 201 return !(lhs == rhs);
vcoubard 563:9c4b96f7be8d 202 }
vcoubard 563:9c4b96f7be8d 203 };
vcoubard 563:9c4b96f7be8d 204
vcoubard 568:13b23a4b1f58 205 // find a running discovery process
vcoubard 563:9c4b96f7be8d 206 Discovery* findRunningDiscovery(const DiscoveredCharacteristic& characteristic);
vcoubard 563:9c4b96f7be8d 207 Discovery* findRunningDiscovery(uint16_t handle);
vcoubard 568:13b23a4b1f58 208
vcoubard 568:13b23a4b1f58 209 // Called to terminate a discovery is over.
vcoubard 568:13b23a4b1f58 210 void terminate(Discovery* discovery, ble_error_t err);
vcoubard 568:13b23a4b1f58 211
vcoubard 568:13b23a4b1f58 212 // get one slot for a discovery process
vcoubard 568:13b23a4b1f58 213 Discovery* getAvailableDiscoverySlot();
vcoubard 568:13b23a4b1f58 214
vcoubard 568:13b23a4b1f58 215 // indicate if a connection is already running a discovery
vcoubard 563:9c4b96f7be8d 216 bool isConnectionInUse(uint16_t connHandle);
vcoubard 563:9c4b96f7be8d 217
vcoubard 568:13b23a4b1f58 218 // low level start of a discovery
vcoubard 568:13b23a4b1f58 219 static ble_error_t gattc_descriptors_discover(uint16_t connection_handle, uint16_t start_handle, uint16_t end_handle);
vcoubard 563:9c4b96f7be8d 220
vcoubard 568:13b23a4b1f58 221 // count of concurrent connections which can run a descriptor discovery process
vcoubard 568:13b23a4b1f58 222 static const size_t MAXIMUM_CONCURRENT_CONNECTIONS_COUNT = 3;
vcoubard 568:13b23a4b1f58 223
vcoubard 568:13b23a4b1f58 224 // array of running discoveries
vcoubard 568:13b23a4b1f58 225 Discovery discoveryRunning[MAXIMUM_CONCURRENT_CONNECTIONS_COUNT];
vcoubard 563:9c4b96f7be8d 226 };
vcoubard 563:9c4b96f7be8d 227
vcoubard 563:9c4b96f7be8d 228 #endif /*__NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__*/