diff --git a/ble/CharacteristicDescriptorDiscovery.h b/ble/CharacteristicDescriptorDiscovery.h new file mode 100644 index 0000000..4cd0fb2 --- /dev/null +++ b/ble/CharacteristicDescriptorDiscovery.h @@ -0,0 +1,99 @@ +/* mbed Microcontroller Library + * Copyright (c) 2006-2015 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ +#define __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ + +#include "FunctionPointerWithContext.h" + +class DiscoveredCharacteristic; // forward declaration +class DiscoveredCharacteristicDescriptor; // forward declaration + +/** + * @brief Contain all definitions of callbacks and callbacks parameters types + * related to characteristic descriptor discovery. + * + * @details This class act like a namespace for characteristic descriptor discovery + * types. It act like ServiceDiscovery by providing callbacks and callbacks + * parameters types related to the characteristic descriptor discovery process but + * contrary to ServiceDiscovery class, it does not force the porter to use a + * specific interface for the characteristic descriptor discovery process. + */ +class CharacteristicDescriptorDiscovery { +public: + /** + * @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t. + * @detail Every time a characteristic descriptor has been discovered, the callback + * registered for the discovery operation through GattClient::discoverCharacteristicDescriptors + * or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter. + * + */ + struct DiscoveryCallbackParams_t { + /** + * The characteristic owning the DiscoveredCharacteristicDescriptor + */ + const DiscoveredCharacteristic& characteristic; + + /** + * The characteristic descriptor discovered + */ + const DiscoveredCharacteristicDescriptor& descriptor; + }; + + /** + * @brief Parameter type of CharacteristicDescriptorDiscovery::TerminationCallback_t. + * @details Once a characteristic descriptor discovery process terminate, the termination + * callback registered for the discovery operation through + * GattClient::discoverCharacteristicDescriptors or DiscoveredCharacteristic::discoverDescriptors + * will be called with this parameter. + */ + struct TerminationCallbackParams_t { + /** + * The characteristic for which the descriptors has been discovered + */ + const DiscoveredCharacteristic& characteristic; + + /** + * status of the discovery operation + */ + ble_error_t status; + }; + + /** + * @brief Callback type for when a matching characteristic descriptor is found during + * characteristic descriptor discovery. + * + * @param param A pointer to a DiscoveryCallbackParams_t object which will remain + * valid for the lifetime of the callback. Memory for this object is owned by + * the BLE_API eventing framework. The application can safely make a persistent + * shallow-copy of this object in order to work with the service beyond the + * callback. + */ + typedef FunctionPointerWithContext DiscoveryCallback_t; + + /** + * @brief Callback type for when characteristic descriptor discovery terminates. + * + * @param param A pointer to a TerminationCallbackParams_t object which will remain + * valid for the lifetime of the callback. Memory for this object is owned by + * the BLE_API eventing framework. The application can safely make a persistent + * shallow-copy of this object in order to work with the service beyond the + * callback. + */ + typedef FunctionPointerWithContext TerminationCallback_t; +}; + +#endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 85d0e2d..11c35a6 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -21,10 +21,24 @@ #include "Gap.h" #include "GattAttribute.h" #include "GattClient.h" +#include "CharacteristicDescriptorDiscovery.h" +#include "ble/DiscoveredCharacteristicDescriptor.h" /** - * Structure for holding information about the service and the characteristics - * found during the discovery process. + * @brief Representation of a characteristic discovered during a GattClient + * discovery procedure (see GattClient::launchServiceDiscovery ). + * + * @detail Provide detailed informations about a discovered characteristic like: + * - Its UUID (see #getUUID). + * - The most important handles of the characteristic definition + * (see #getDeclHandle, #getValueHandle, #getLastHandle ) + * - Its properties (see #getProperties). + * This class also provide functions to operate on the characteristic: + * - Read the characteristic value (see #read) + * - Writing a characteristic value (see #write or #writeWoResponse) + * - Discover descriptors inside the characteristic definition. These descriptors + * extends the characteristic. More information about descriptor usage is + * available in DiscoveredCharacteristicDescriptor class. */ class DiscoveredCharacteristic { public: @@ -33,7 +47,7 @@ public: uint8_t _read :1; /**< Reading the value permitted. */ uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */ uint8_t _write :1; /**< Writing the value with Write Request permitted. */ - uint8_t _notify :1; /**< Notications of the value permitted. */ + uint8_t _notify :1; /**< Notifications of the value permitted. */ uint8_t _indicate :1; /**< Indications of the value permitted. */ uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */ @@ -46,36 +60,50 @@ public: bool indicate(void) const {return _indicate; } bool authSignedWrite(void) const {return _authSignedWrite;} + /** + * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t + * + * @param lhs[in] The left hand side of the equality expression + * @param rhs[in] The right hand side of the equality expression + * + * @return true if operands are equals, false otherwise. + */ + friend bool operator==(Properties_t lhs, Properties_t rhs) { + return lhs._broadcast == rhs._broadcast && + lhs._read == rhs._read && + lhs._writeWoResp == rhs._writeWoResp && + lhs._write == rhs._write && + lhs._notify == rhs._notify && + lhs._indicate == rhs._indicate && + lhs._authSignedWrite == rhs._authSignedWrite; + } + + /** + * @brief "Not equal to" operator for DiscoveredCharacteristic::Properties_t + * + * @param lhs The right hand side of the expression + * @param rhs The left hand side of the expression + * + * @return true if operands are not equals, false otherwise. + */ + friend bool operator!=(Properties_t lhs, Properties_t rhs) { + return !(lhs == rhs); + } + private: operator uint8_t() const; /* Disallow implicit conversion into an integer. */ operator unsigned() const; /* Disallow implicit conversion into an integer. */ }; - /** - * Structure for holding information about the service and the characteristics - * found during the discovery process. - */ - struct DiscoveredDescriptor { - GattAttribute::Handle_t handle; /**< Descriptor Handle. */ - UUID uuid; /**< Descriptor UUID. */ - }; - - /** - * Callback type for when a characteristic descriptor is found during descriptor- - * discovery. The receiving function is passed in a pointer to a - * DiscoveredDescriptor object which will remain valid for the lifetime - * of the callback. Memory for this object is owned by the BLE_API eventing - * framework. The application can safely make a persistent shallow-copy of - * this object in order to work with the characteristic beyond the callback. - */ - typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *); - /** * Initiate (or continue) a read for the value attribute, optionally at a * given offset. If the characteristic or descriptor to be read is longer * than ATT_MTU - 1, this function must be called multiple times with * appropriate offset to read the complete value. * + * @param offset[in] The position - in the characteristic value bytes stream - where + * the read operation begin. + * * @return BLE_ERROR_NONE if a read has been initiated, or * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or * BLE_STACK_BUSY if some client procedure is already in progress, or @@ -83,14 +111,22 @@ public: */ ble_error_t read(uint16_t offset = 0) const; + /** + * @brief Same as #read(uint16_t) const but allow the user to register a callback + * which will be fired once the read is done. + * + * @param offset[in] The position - in the characteristic value bytes stream - where + * the read operation begin. + * @param onRead[in] Continuation of the read operation + */ ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const; /** * Perform a write without response procedure. * - * @param length + * @param[in] length * The amount of data being written. - * @param value + * @param[in] value * The bytes being written. * * @note It is important to note that a write without response will generate @@ -110,20 +146,20 @@ public: /** * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic. * - * @param callback - * @param matchingUUID - * Filter for descriptors. Defaults to wildcard which will discover all descriptors. + * @param[in] onDescriptorDiscovered This callback will be called every time a descriptor is discovered + * @param[in] onTermination This callback will be called when the discovery process is over. * - * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error. + * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error. */ - ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const; + ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const; /** * Perform a write procedure. * - * @param length + * @param[in] length * The amount of data being written. - * @param value + * @param[in] value * The bytes being written. * * @note It is important to note that a write will generate @@ -138,36 +174,142 @@ public: ble_error_t write(uint16_t length, const uint8_t *value) const; /** - * Same as above but register the callback wich will be called once the data has been written + * Same as #write(uint16_t, const uint8_t *) const but register a callback + * which will be called once the data has been written. + * + * @param[in] length The amount of bytes to write. + * @param[in] value The bytes to write. + * @param[in] onRead Continuation callback for the write operation */ - ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const; + ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const; void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) { uuid.setupLong(longUUID, order); } public: + /** + * @brief Get the UUID of the discovered characteristic + * @return the UUID of this characteristic + */ const UUID& getUUID(void) const { return uuid; } + /** + * @brief Get the properties of this characteristic + * @return the set of properties of this characteristic + */ const Properties_t& getProperties(void) const { return props; } - const GattAttribute::Handle_t& getDeclHandle(void) const { + /** + * @brief Get the declaration handle of this characteristic. + * @detail The declaration handle is the first handle of a characteristic + * definition. The value accessible at this handle contains the following + * informations: + * - The characteristics properties (see Properties_t). This value can + * be accessed by using #getProperties . + * - The characteristic value attribute handle. This field can be accessed + * by using #getValueHandle . + * - The characteristic UUID, this value can be accessed by using the + * function #getUUID . + * @return the declaration handle of this characteristic. + */ + GattAttribute::Handle_t getDeclHandle(void) const { return declHandle; } - const GattAttribute::Handle_t& getValueHandle(void) const { + + /** + * @brief Return the handle used to access the value of this characteristic. + * @details This handle is the one provided in the characteristic declaration + * value. Usually, it is equal to #getDeclHandle() + 1. But it is not always + * the case. Anyway, users are allowed to use #getDeclHandle() + 1 to access + * the value of a characteristic. + * @return The handle to access the value of this characteristic. + */ + GattAttribute::Handle_t getValueHandle(void) const { return valueHandle; } + /** + * @brief Return the last handle of the characteristic definition. + * @details A Characteristic definition can contain a lot of handles: + * - one for the declaration (see #getDeclHandle) + * - one for the value (see #getValueHandle) + * - zero of more for the characteristic descriptors. + * This handle is the last handle of the characteristic definition. + * @return The last handle of this characteristic definition. + */ + GattAttribute::Handle_t getLastHandle(void) const { + return lastHandle; + } + + /** + * @brief Return the GattClient which can operate on this characteristic. + * @return The GattClient which can operate on this characteristic. + */ + GattClient* getGattClient() { + return gattc; + } + + /** + * @brief Return the GattClient which can operate on this characteristic. + * @return The GattClient which can operate on this characteristic. + */ + const GattClient* getGattClient() const { + return gattc; + } + + /** + * @brief Return the connection handle to the GattServer which contain + * this characteristic. + * @return the connection handle to the GattServer which contain + * this characteristic. + */ + Gap::Handle_t getConnectionHandle() const { + return connHandle; + } + + /** + * @brief "Equal to" operator for DiscoveredCharacteristic + * + * @param lhs[in] The left hand side of the equality expression + * @param rhs[in] The right hand side of the equality expression + * + * @return true if operands are equals, false otherwise. + */ + friend bool operator==(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) { + return lhs.gattc == rhs.gattc && + lhs.uuid == rhs.uuid && + lhs.props == rhs.props && + lhs.declHandle == rhs.declHandle && + lhs.valueHandle == rhs.valueHandle && + lhs.lastHandle == rhs.lastHandle && + lhs.connHandle == rhs.connHandle; + } + + /** + * @brief "Not equal to" operator for DiscoveredCharacteristic + * + * @param lhs[in] The right hand side of the expression + * @param rhs[in] The left hand side of the expression + * + * @return true if operands are not equals, false otherwise. + */ + friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) { + return !(lhs == rhs); + } + public: DiscoveredCharacteristic() : gattc(NULL), uuid(UUID::ShortUUIDBytes_t(0)), props(), declHandle(GattAttribute::INVALID_HANDLE), - valueHandle(GattAttribute::INVALID_HANDLE) { + valueHandle(GattAttribute::INVALID_HANDLE), + lastHandle(GattAttribute::INVALID_HANDLE), + connHandle() { /* empty */ } @@ -179,6 +321,7 @@ protected: Properties_t props; GattAttribute::Handle_t declHandle; GattAttribute::Handle_t valueHandle; + GattAttribute::Handle_t lastHandle; Gap::Handle_t connHandle; }; diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h new file mode 100644 index 0000000..86fd6ab --- /dev/null +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -0,0 +1,111 @@ +/* mbed Microcontroller Library + * Copyright (c) 2006-2013 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ +#define __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ + +#include "UUID.h" +#include "Gap.h" +#include "GattAttribute.h" +#include "GattClient.h" +#include "CharacteristicDescriptorDiscovery.h" + +/** + * @brief Representation of a descriptor discovered during a GattClient + * discovery procedure (see GattClient::discoverCharacteristicDescriptors or + * DiscoveredCharacteristic::discoverDescriptors ). + * + * @detail Provide detailed informations about a discovered characteristic descriptor + * like: + * - Its UUID (see #getUUID). + * - Its handle (see #getAttributeHandle) + * Basic read (see GattClient::read) and write (see GattClient::write) procedure from + * GattClient can be used access the value of the descriptor. + * + * @todo read member function + * @todo write member function + * @todo enumeration of standard descriptors + */ +class DiscoveredCharacteristicDescriptor { + +public: + + /** + * @brief construct a new instance of a DiscoveredCharacteristicDescriptor + * + * @param client The client from where the descriptor has been discovered + * @param connectionHandle The connection handle on which the descriptor has + * been discovered + * @param attributeHandle The handle of the attribute containing this descriptor + * @param uuid The UUID of the descriptor + */ + DiscoveredCharacteristicDescriptor( + GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const UUID& uuid) : + _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(attributeHandle) { + + } + + /** + * @brief Return the GattClient which can operate on this descriptor. + * @return The GattClient which can operate on this descriptor. + */ + GattClient* getGattClient() { + return _client; + } + + /** + * @brief Return the GattClient which can operate on this descriptor. + * @return The GattClient which can operate on this descriptor. + */ + const GattClient* getGattClient() const { + return _client; + } + + /** + * @brief Return the connection handle to the GattServer which contain + * this descriptor. + * @return the connection handle to the GattServer which contain + * this descriptor. + */ + Gap::Handle_t getConnectionHandle() const { + return _connectionHandle; + } + + /** + * @brief Return the UUID of this descriptor + * @return the UUID of this descriptor + */ + const UUID& getUUID(void) const { + return _uuid; + } + + /** + * @brief Return the attribute handle to use to access to this descriptor + * on the gatt server. + * @return The attribute handle of the descriptor + */ + GattAttribute::Handle_t getAttributeHandle() const { + return _gattHandle; + } + +private: + GattClient *_client; + Gap::Handle_t _connectionHandle; + UUID _uuid; + GattAttribute::Handle_t _gattHandle; +}; + +#endif /*__DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__*/ diff --git a/ble/GattClient.h b/ble/GattClient.h index c65207f..5313388 100644 --- a/ble/GattClient.h +++ b/ble/GattClient.h @@ -20,6 +20,7 @@ #include "Gap.h" #include "GattAttribute.h" #include "ServiceDiscovery.h" +#include "CharacteristicDescriptorDiscovery.h" #include "GattCallbackParamTypes.h" @@ -219,8 +220,8 @@ public: * Initiate a GATT Client write procedure. * * @param[in] cmd - * Command can be either a write-request (which generates a - * matching response from the peripheral), or a write-command + * Command can be either a write-request (which generates a + * matching response from the peripheral), or a write-command * (which doesn't require the connected peer to respond). * @param[in] connHandle * Connection handle. @@ -249,8 +250,8 @@ public: /* Event callback handlers. */ public: /** - * Set up a callback for read response events. - * It is possible to remove registered callbacks using + * Set up a callback for read response events. + * It is possible to remove registered callbacks using * onDataRead().detach(callbackToRemove) */ void onDataRead(ReadCallback_t callback) { @@ -260,7 +261,7 @@ public: /** * @brief provide access to the callchain of read callbacks * It is possible to register callbacks using onDataRead().add(callback); - * It is possible to unregister callbacks using onDataRead().detach(callback) + * It is possible to unregister callbacks using onDataRead().detach(callback) * @return The read callbacks chain */ ReadCallbackChain_t& onDataRead() { @@ -269,7 +270,7 @@ public: /** * Set up a callback for write response events. - * It is possible to remove registered callbacks using + * It is possible to remove registered callbacks using * onDataWritten().detach(callbackToRemove). * @Note: Write commands (issued using writeWoResponse) don't generate a response. */ @@ -280,10 +281,10 @@ public: /** * @brief provide access to the callchain of data written callbacks * It is possible to register callbacks using onDataWritten().add(callback); - * It is possible to unregister callbacks using onDataWritten().detach(callback) + * It is possible to unregister callbacks using onDataWritten().detach(callback) * @return The data written callbacks chain */ - WriteCallbackChain_t& onDataWritten() { + WriteCallbackChain_t& onDataWritten() { return onDataWriteCallbackChain; } @@ -307,6 +308,59 @@ public: /* Requesting action from porters: override this API if this capability is supported. */ } + /** + * @brief launch discovery of descriptors for a given characteristic + * @details This function will discover all descriptors available for a + * specific characteristic. + * + * @param characteristic[in] The characteristic targeted by this discovery + * procedure + * @param discoveryCallback[in] User function called each time a descriptor + * is found during the procedure. + * @param terminationCallback[in] User provided function which will be called + * once the discovery procedure is terminating. This will get called when all + * the descriptors have been discovered or if an error occur during the discovery + * procedure. + * + * @return + * BLE_ERROR_NONE if characteristic descriptor discovery is launched + * successfully; else an appropriate error. + */ + virtual ble_error_t discoverCharacteristicDescriptors( + const DiscoveredCharacteristic& characteristic, + const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) { + (void) characteristic; + (void) discoveryCallback; + (void) terminationCallback; + /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; + } + + /** + * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic + * or not. + * @param characteristic[in] The characteristic concerned by the descriptors discovery. + * @return true if a descriptors discovery is active for the characteristic in input; otherwise false. + */ + virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const + { + (void) characteristic; + return false; /* Requesting action from porter(s): override this API if this capability is supported. */ + } + + /** + * @brief Terminate an ongoing characteristic descriptor discovery. + * @detail This should result in an invocation of the TerminationCallback if + * the characteristic descriptor discovery is active. + * @param characteristic[in] The characteristic on which the running descriptors + * discovery should be stopped. + */ + virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) { + /* Requesting action from porter(s): override this API if this capability is supported. */ + (void) characteristic; + } + /** * Set up a callback for when the GATT client receives an update event * corresponding to a change in the value of a characteristic on the remote @@ -352,10 +406,10 @@ public: /** * @brief provide access to the callchain of HVX callbacks * It is possible to register callbacks using onHVX().add(callback); - * It is possible to unregister callbacks using onHVX().detach(callback) + * It is possible to unregister callbacks using onHVX().detach(callback) * @return The HVX callbacks chain */ - HVXCallbackChain_t& onHVX() { + HVXCallbackChain_t& onHVX() { return onHVXCallbackChain; } diff --git a/source/DiscoveredCharacteristic.cpp b/source/DiscoveredCharacteristic.cpp index 72214e3..e2a6849 100644 --- a/source/DiscoveredCharacteristic.cpp +++ b/source/DiscoveredCharacteristic.cpp @@ -151,12 +151,17 @@ ble_error_t DiscoveredCharacteristic::write(uint16_t length, const uint8_t *valu return error; } -ble_error_t -DiscoveredCharacteristic::discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID) const -{ - /* Avoid compiler warnings */ - (void) callback; - (void) matchingUUID; +ble_error_t DiscoveredCharacteristic::discoverDescriptors( + const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const { - return BLE_ERROR_NOT_IMPLEMENTED; /* TODO: this needs to be filled in. */ + if(!gattc) { + return BLE_ERROR_INVALID_STATE; + } + + ble_error_t err = gattc->discoverCharacteristicDescriptors( + *this, onCharacteristicDiscovered, onTermination + ); + + return err; }