Michael Galis / nRF51822

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of nRF51822 by Nordic Semiconductor

TARGET_MCU_NRF51822/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 "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 private:
Vincent Coubard 638:c90ae1400bf2 100 // protection against copy construction and assignment
Vincent Coubard 638:c90ae1400bf2 101 nRF5xCharacteristicDescriptorDiscoverer(const nRF5xCharacteristicDescriptorDiscoverer&);
Vincent Coubard 638:c90ae1400bf2 102 nRF5xCharacteristicDescriptorDiscoverer& operator=(const nRF5xCharacteristicDescriptorDiscoverer&);
Vincent Coubard 638:c90ae1400bf2 103
Vincent Coubard 638:c90ae1400bf2 104 /**
Vincent Coubard 638:c90ae1400bf2 105 * @brief Discovery process, it store the DiscoveredCharacteristic, the
Vincent Coubard 638:c90ae1400bf2 106 * discovery callback and the termination callback.
Vincent Coubard 638:c90ae1400bf2 107 */
Vincent Coubard 638:c90ae1400bf2 108 class Discovery {
Vincent Coubard 638:c90ae1400bf2 109 public:
Vincent Coubard 638:c90ae1400bf2 110 /**
Vincent Coubard 638:c90ae1400bf2 111 * @brief Construct an empty discovery, such can be considerate as a not running discovery.
Vincent Coubard 638:c90ae1400bf2 112 * @note #isEmpty function will return true
Vincent Coubard 638:c90ae1400bf2 113 */
Vincent Coubard 638:c90ae1400bf2 114 Discovery();
Vincent Coubard 638:c90ae1400bf2 115
Vincent Coubard 638:c90ae1400bf2 116 /**
Vincent Coubard 638:c90ae1400bf2 117 * @brief Construct a valid discovery process.
Vincent Coubard 638:c90ae1400bf2 118 *
Vincent Coubard 638:c90ae1400bf2 119 * @param c the characteristic from whom descriptors will be discovered.
Vincent Coubard 638:c90ae1400bf2 120 * @param dCb The discovery callback called each time a descriptor is discovered.
Vincent Coubard 638:c90ae1400bf2 121 * @param tCb The termination callback called when the discovery terminate.
Vincent Coubard 638:c90ae1400bf2 122 *
Vincent Coubard 638:c90ae1400bf2 123 * @note #isEmpty function will return false
Vincent Coubard 638:c90ae1400bf2 124 */
Vincent Coubard 638:c90ae1400bf2 125 Discovery(const DiscoveredCharacteristic& c, const DiscoveryCallback_t& dCb, const TerminationCallback_t& tCb);
Vincent Coubard 638:c90ae1400bf2 126
Vincent Coubard 638:c90ae1400bf2 127 /**
Vincent Coubard 638:c90ae1400bf2 128 * @brief Process the discovery of a descriptor.
Vincent Coubard 638:c90ae1400bf2 129 *
Vincent Coubard 638:c90ae1400bf2 130 * @param handle The attribute handle of the descriptor found
Vincent Coubard 638:c90ae1400bf2 131 * @param uuid The UUID of the descriptor found.
Vincent Coubard 638:c90ae1400bf2 132 */
Vincent Coubard 638:c90ae1400bf2 133 void process(GattAttribute::Handle_t handle, const UUID& uuid);
Vincent Coubard 638:c90ae1400bf2 134
Vincent Coubard 638:c90ae1400bf2 135 /**
Vincent Coubard 638:c90ae1400bf2 136 * @brief Terminate the discovery process.
Vincent Coubard 638:c90ae1400bf2 137 *
Vincent Coubard 638:c90ae1400bf2 138 * @param err Error associate with the termination
Vincent Coubard 638:c90ae1400bf2 139 * @note after this call #isEmpty function will return true.
Vincent Coubard 638:c90ae1400bf2 140 */
Vincent Coubard 638:c90ae1400bf2 141 void terminate(ble_error_t err);
Vincent Coubard 638:c90ae1400bf2 142
Vincent Coubard 638:c90ae1400bf2 143 /**
Vincent Coubard 638:c90ae1400bf2 144 * @brief check if the discovery process is empty or not. Empty discovery are
Vincent Coubard 638:c90ae1400bf2 145 * not running.
Vincent Coubard 638:c90ae1400bf2 146 *
Vincent Coubard 638:c90ae1400bf2 147 * @detail Discovery are empty after:
Vincent Coubard 638:c90ae1400bf2 148 * - a default construction
Vincent Coubard 638:c90ae1400bf2 149 * - a copy construction form a default constructed
Vincent Coubard 638:c90ae1400bf2 150 * - an assignment from a default constructed Discovery
Vincent Coubard 638:c90ae1400bf2 151 * @return true if the Discovery is empty and false otherwise.
Vincent Coubard 638:c90ae1400bf2 152 */
Vincent Coubard 638:c90ae1400bf2 153 bool isEmpty() const;
Vincent Coubard 638:c90ae1400bf2 154
Vincent Coubard 638:c90ae1400bf2 155 /**
Vincent Coubard 638:c90ae1400bf2 156 * @brief return the characteristic from whom descriptors are discovered.
Vincent Coubard 638:c90ae1400bf2 157 * @return the characteristic from whom descriptors are discovered.
Vincent Coubard 638:c90ae1400bf2 158 */
Vincent Coubard 638:c90ae1400bf2 159 const DiscoveredCharacteristic& getCharacteristic() const;
Vincent Coubard 638:c90ae1400bf2 160
Vincent Coubard 638:c90ae1400bf2 161 /**
Vincent Coubard 638:c90ae1400bf2 162 * @brief equal to operator, test if two discovery process are equal
Vincent Coubard 638:c90ae1400bf2 163 *
Vincent Coubard 638:c90ae1400bf2 164 * @param lhs left hand side of the expression
Vincent Coubard 638:c90ae1400bf2 165 * @param rhs right hand side of the expression
Vincent Coubard 638:c90ae1400bf2 166 * @return true if lhs == rhs
Vincent Coubard 638:c90ae1400bf2 167 */
Vincent Coubard 638:c90ae1400bf2 168 friend bool operator==(const Discovery& lhs, const Discovery& rhs) {
Vincent Coubard 638:c90ae1400bf2 169 return lhs.characteristic == rhs.characteristic &&
Vincent Coubard 638:c90ae1400bf2 170 lhs.onDiscovery == rhs.onDiscovery &&
Vincent Coubard 638:c90ae1400bf2 171 lhs.onTerminate == rhs.onTerminate;
Vincent Coubard 638:c90ae1400bf2 172 }
Vincent Coubard 638:c90ae1400bf2 173
Vincent Coubard 638:c90ae1400bf2 174 /**
Vincent Coubard 638:c90ae1400bf2 175 * @brief not equal to operator, test if two discovery process are not equal
Vincent Coubard 638:c90ae1400bf2 176 *
Vincent Coubard 638:c90ae1400bf2 177 * @param lhs left hand side of the expression
Vincent Coubard 638:c90ae1400bf2 178 * @param rhs right hand side of the expression
Vincent Coubard 638:c90ae1400bf2 179 * @return true if lhs != rhs
Vincent Coubard 638:c90ae1400bf2 180 */
Vincent Coubard 638:c90ae1400bf2 181 friend bool operator!=(const Discovery& lhs, const Discovery& rhs) {
Vincent Coubard 638:c90ae1400bf2 182 return !(lhs == rhs);
Vincent Coubard 638:c90ae1400bf2 183 }
Vincent Coubard 638:c90ae1400bf2 184
Vincent Coubard 638:c90ae1400bf2 185 private:
Vincent Coubard 638:c90ae1400bf2 186 DiscoveredCharacteristic characteristic;
Vincent Coubard 638:c90ae1400bf2 187 DiscoveryCallback_t onDiscovery;
Vincent Coubard 638:c90ae1400bf2 188 TerminationCallback_t onTerminate;
Vincent Coubard 638:c90ae1400bf2 189 };
Vincent Coubard 638:c90ae1400bf2 190
Vincent Coubard 638:c90ae1400bf2 191 // find a running discovery process
Vincent Coubard 638:c90ae1400bf2 192 Discovery* findRunningDiscovery(const DiscoveredCharacteristic& characteristic);
Vincent Coubard 638:c90ae1400bf2 193 Discovery* findRunningDiscovery(uint16_t handle);
Vincent Coubard 638:c90ae1400bf2 194
Vincent Coubard 638:c90ae1400bf2 195 // Called to terminate a discovery is over.
Vincent Coubard 638:c90ae1400bf2 196 void terminate(Discovery* discovery, ble_error_t err);
Vincent Coubard 638:c90ae1400bf2 197
Vincent Coubard 638:c90ae1400bf2 198 // get one slot for a discovery process
Vincent Coubard 638:c90ae1400bf2 199 Discovery* getAvailableDiscoverySlot();
Vincent Coubard 638:c90ae1400bf2 200
Vincent Coubard 638:c90ae1400bf2 201 // indicate if a connection is already running a discovery
Vincent Coubard 638:c90ae1400bf2 202 bool isConnectionInUse(uint16_t connHandle);
Vincent Coubard 638:c90ae1400bf2 203
Vincent Coubard 638:c90ae1400bf2 204 // low level start of a discovery
Vincent Coubard 638:c90ae1400bf2 205 static ble_error_t gattc_descriptors_discover(uint16_t connection_handle, uint16_t start_handle, uint16_t end_handle);
Vincent Coubard 638:c90ae1400bf2 206
Vincent Coubard 638:c90ae1400bf2 207 // count of concurrent connections which can run a descriptor discovery process
Vincent Coubard 638:c90ae1400bf2 208 static const size_t MAXIMUM_CONCURRENT_CONNECTIONS_COUNT = 3;
Vincent Coubard 638:c90ae1400bf2 209
Vincent Coubard 638:c90ae1400bf2 210 // array of running discoveries
Vincent Coubard 638:c90ae1400bf2 211 Discovery discoveryRunning[MAXIMUM_CONCURRENT_CONNECTIONS_COUNT];
Vincent Coubard 638:c90ae1400bf2 212 };
Vincent Coubard 638:c90ae1400bf2 213
Vincent Coubard 638:c90ae1400bf2 214 #endif /*__NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__*/