Cefn Hoile / nRF51822

Attempting to publish a tree

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

source/nRF5xCharacteristicDescriptorDiscoverer.h@624:3ef324d9f2df, 2016-06-01 (annotated)

Committer:
cefn
Date:
Wed Jun 01 17:41:42 2016 +0000
Revision:
624:3ef324d9f2df
Parent:
616:a8f9b022d8fd 
Attempting to publish a tree

Who changed what in which revision?

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