Nordic Semiconductor / nRF51822

Nordic stack and drivers for the mbed BLE API

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate writable_gatt ... more

TARGET_NRF5/source/nRF5xCharacteristicDescriptorDiscoverer.h@638:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

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