nRF5xCharacteristicDescriptorDiscoverer.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00018 #define __NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
00019 
00020 #include "ble/Gap.h"
00021 #include "ble/DiscoveredCharacteristic.h"
00022 #include "ble/CharacteristicDescriptorDiscovery.h"
00023 #include "ble/GattClient.h"
00024 #include "ble_gattc.h"
00025 
00026 /**
00027  * @brief Manage the discovery of Characteristic descriptors
00028  * @details is a bridge between BLE API and Nordic stack regarding Characteristic
00029  * Descriptor discovery. The BLE API can launch, monitor and ask for termination
00030  * of a discovery. The Nordic stack will provide new descriptors and indicate when
00031  * the discovery is done.
00032  */
00033 class nRF5xCharacteristicDescriptorDiscoverer
00034 {
00035     typedef CharacteristicDescriptorDiscovery::DiscoveryCallback_t DiscoveryCallback_t;
00036     typedef CharacteristicDescriptorDiscovery::TerminationCallback_t TerminationCallback_t;
00037 
00038 public:
00039     /**
00040      * @brief Construct a new characteristic descriptor discoverer.
00041      */
00042     nRF5xCharacteristicDescriptorDiscoverer();
00043 
00044     /**
00045      * @brief Destroy a characteristic descriptor discoverer.
00046      */
00047     ~nRF5xCharacteristicDescriptorDiscoverer();
00048 
00049     /**
00050      * Launch a new characteristic descriptor discovery for a given DiscoveredCharacteristic.
00051      * @param characteristic The characteristic owning the descriptors to discover.
00052      * @param discoveryCallback The callback called when a descriptor is discovered.
00053      * @param terminationCallback The callback called when the discovery process end.
00054      * @return BLE_ERROR_NONE if characteristic descriptor discovery is launched successfully;
00055      *         else an appropriate error.
00056      * @note: this will be called by BLE API side.
00057      */
00058     ble_error_t launch(
00059         const DiscoveredCharacteristic& characteristic,
00060         const DiscoveryCallback_t& discoveryCallback,
00061         const TerminationCallback_t& terminationCallback
00062     );
00063 
00064     /**
00065      * @brief indicate if a characteristic descriptor discovery is active for a
00066      * given DiscoveredCharacteristic.
00067      * @param characteristic The characteristic for whom the descriptor might be
00068      * currently discovered.
00069      * @return true if descriptors of characteristic are discovered, false otherwise.
00070      * @note: this will be called by BLE API side.
00071      */
00072     bool isActive(const DiscoveredCharacteristic& characteristic) const;
00073 
00074     /**
00075      * @brief request the termination of characteristic descriptor discovery
00076      * for a give DiscoveredCharacteristic
00077      * @param characteristic The characteristic for whom the descriptor discovery
00078      * should be stopped.
00079      * @note: this will be called by BLE API side.
00080      */
00081     void requestTerminate(const DiscoveredCharacteristic& characteristic);
00082 
00083     /**
00084      * @brief process descriptors discovered from the Nordic stack.
00085      * @param connectionHandle The connection handle upon which descriptors has been
00086      * discovered.
00087      * @param descriptors Discovered descriptors.
00088      * @note This will be called by the Nordic stack.
00089      */
00090     void process(uint16_t connectionHandle, const ble_gattc_evt_desc_disc_rsp_t& descriptors);
00091 
00092     /**
00093      * @brief Called by the Nordic stack when the discovery is over.
00094      * @param The connection handle upon which the discovery process is done.
00095      * @param err An error if the termination is due to an error.
00096      */
00097     void terminate(uint16_t connectionHandle, ble_error_t err);
00098 
00099 private:
00100     // protection against copy construction and assignment
00101     nRF5xCharacteristicDescriptorDiscoverer(const nRF5xCharacteristicDescriptorDiscoverer&);
00102     nRF5xCharacteristicDescriptorDiscoverer& operator=(const nRF5xCharacteristicDescriptorDiscoverer&);
00103 
00104     /**
00105      * @brief Discovery process, it store the DiscoveredCharacteristic, the
00106      * discovery callback and the termination callback.
00107      */
00108     class Discovery {
00109     public:
00110         /**
00111          * @brief Construct an empty discovery, such can be considerate as a not running discovery.
00112          * @note #isEmpty function will return true
00113          */
00114         Discovery();
00115 
00116         /**
00117          * @brief Construct a valid discovery process.
00118          *
00119          * @param c the characteristic from whom descriptors will be discovered.
00120          * @param dCb The discovery callback called each time a descriptor is discovered.
00121          * @param tCb The termination callback called when the discovery terminate.
00122          *
00123          * @note #isEmpty function will return false
00124          */
00125         Discovery(const DiscoveredCharacteristic& c, const DiscoveryCallback_t& dCb, const TerminationCallback_t& tCb);
00126 
00127         /**
00128          * @brief Process the discovery of a descriptor.
00129          *
00130          * @param handle The attribute handle of the descriptor found
00131          * @param uuid The UUID of the descriptor found.
00132          */
00133         void process(GattAttribute::Handle_t handle, const UUID& uuid);
00134 
00135         /**
00136          * @brief Terminate the discovery process.
00137          *
00138          * @param err Error associate with the termination
00139          * @note after this call #isEmpty function will return true.
00140          */
00141         void terminate(ble_error_t err);
00142 
00143         /**
00144          * @brief check if the discovery process is empty or not. Empty discovery are
00145          * not running.
00146          *
00147          * @detail Discovery are empty after:
00148          *     - a default construction
00149          *     - a copy construction form a default constructed
00150          *     - an assignment from a default constructed Discovery
00151          * @return true if the Discovery is empty and false otherwise.
00152          */
00153         bool isEmpty() const;
00154 
00155         /**
00156          * @brief return the characteristic from whom descriptors are discovered.
00157          * @return the characteristic from whom descriptors are discovered.
00158          */
00159         const DiscoveredCharacteristic& getCharacteristic() const;
00160 
00161         /**
00162          * @brief equal to operator, test if two discovery process are equal
00163          *
00164          * @param lhs left hand side of the expression
00165          * @param rhs right hand side of the expression
00166          * @return true if lhs == rhs
00167          */
00168         friend bool operator==(const Discovery& lhs, const Discovery& rhs) {
00169             return lhs.characteristic == rhs.characteristic &&
00170                    lhs.onDiscovery == rhs.onDiscovery &&
00171                    lhs.onTerminate == rhs.onTerminate;
00172         }
00173 
00174         /**
00175          * @brief not equal to operator, test if two discovery process are not equal
00176          *
00177          * @param lhs left hand side of the expression
00178          * @param rhs right hand side of the expression
00179          * @return true if lhs != rhs
00180          */
00181         friend bool operator!=(const Discovery& lhs, const Discovery& rhs) {
00182             return !(lhs == rhs);
00183         }
00184 
00185     private:
00186         DiscoveredCharacteristic characteristic;
00187         DiscoveryCallback_t onDiscovery;
00188         TerminationCallback_t onTerminate;
00189     };
00190 
00191     // find a running discovery process
00192     Discovery* findRunningDiscovery(const DiscoveredCharacteristic& characteristic);
00193     Discovery* findRunningDiscovery(uint16_t handle);
00194 
00195     // Called to terminate a discovery is over.
00196     void terminate(Discovery* discovery, ble_error_t err);
00197 
00198     // get one slot for a discovery process
00199     Discovery* getAvailableDiscoverySlot();
00200 
00201     // indicate if a connection is already running a discovery
00202     bool isConnectionInUse(uint16_t connHandle);
00203 
00204     // low level start of a discovery
00205     static ble_error_t gattc_descriptors_discover(uint16_t connection_handle, uint16_t start_handle, uint16_t end_handle);
00206 
00207     // count of concurrent connections which can run a descriptor discovery process
00208     static const size_t MAXIMUM_CONCURRENT_CONNECTIONS_COUNT = 3;
00209 
00210     // array of running discoveries
00211     Discovery discoveryRunning[MAXIMUM_CONCURRENT_CONNECTIONS_COUNT];
00212 };
00213 
00214 #endif /*__NRF_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__*/