Michael Galis / nRF51822

No changes

Fork of nRF51822 by Nordic Semiconductor

source/nRF5xCharacteristicDescriptorDiscoverer.h@590:3bdd5346ded1, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:31 2016 +0000
Revision:
590:3bdd5346ded1
Synchronized with git rev 19d1c406

Author: Vincent Coubard

Merge branch 'develop' of https://github.com/ARMmbed/ble-nrf51822 into characteristicDescriptorDiscovery

Who changed what in which revision?

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