From 582789ea91bd2441c7729c81a7aafaad6271c8c5 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 10 Nov 2015 17:07:03 +0000 Subject: [PATCH 01/20] Add function template makeFunctionPointer wich help to create FunctionPointerWithContext instances. --- ble/FunctionPointerWithContext.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/ble/FunctionPointerWithContext.h b/ble/FunctionPointerWithContext.h index 26447aa..41b99fa 100644 --- a/ble/FunctionPointerWithContext.h +++ b/ble/FunctionPointerWithContext.h @@ -152,4 +152,23 @@ private: * 'CallChain' as an alternative. */ }; +/** + * @brief Create a new FunctionPointerWithContext which bind an instance and a + * a member function together. + * @details This little helper is a just here to eliminate the need to write the + * FunctionPointerWithContext type each time you want to create one by kicking + * automatic type deduction of function templates. With this function, it is easy + * to write only one entry point for functions which expect a FunctionPointer + * in parameters. + * + * @param object to bound with member function + * @param member The member function called + * @return a new FunctionPointerWithContext + */ +template +FunctionPointerWithContext makeFunctionPointer(T *object, void (T::*member)(ContextType context)) +{ + return FunctionPointerWithContext(object, member); +} + #endif // ifndef MBED_FUNCTIONPOINTER_WITH_CONTEXT_H From 6dd3376c8656a57c5c2548581d3bf9efedab344f Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 10 Nov 2015 17:09:23 +0000 Subject: [PATCH 02/20] Add characteristic descriptor discovery API. --- ble/CharacteristicDescriptorDiscovery.h | 56 +++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 ble/CharacteristicDescriptorDiscovery.h diff --git a/ble/CharacteristicDescriptorDiscovery.h b/ble/CharacteristicDescriptorDiscovery.h new file mode 100644 index 0000000..67beb8f --- /dev/null +++ b/ble/CharacteristicDescriptorDiscovery.h @@ -0,0 +1,56 @@ +/* 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; +class DiscoveredCharacteristicDescriptor; + +class CharacteristicDescriptorDiscovery { +public: + /* + * Exposed application callback types. + */ + struct DiscoveryCallbackParams_t { + DiscoveredCharacteristic& characteristic; + DiscoveredCharacteristicDescriptor& descriptor; + }; + + struct TerminationCallbackParams_t { + DiscoveredCharacteristic& characteristic; + }; + + /** + * Callback type for when a matching characteristic descriptor is found during + * characteristic descriptor discovery. The receiving function is passed in a + * pointer to a DiscoveredCharacteristicDescriptor 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; + + /** + * Callback type for when characteristic descriptor discovery terminates. + */ + typedef FunctionPointerWithContext TerminationCallback_t; +}; + +#endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ From c9261773ac1f51d804a4d5fd1a73d12fae67a56c Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Fri, 13 Nov 2015 13:01:48 +0000 Subject: [PATCH 03/20] Improve interface for CharacteristicDescriptorDiscovery: CharacteristicDescriptorDiscovery::DiscoveryCallback_t take a DiscoveryCallBackParam instead of just the discovered descriptor DiscoveredCharacteristicDescriptor is now a plain type. DiscoveredCharacteristic support operator== DiscoveredCharacteristic::Properties-t support operator== DiscoveredCharacteristic now include the last Gatt handle of this characteristic FunctionPointer with context call() is now const, in order to mirror std::function and call a const FunctionPointerWithContext FunctionPointerWithContext support operator == GattClient support basic characteristic descriptor discovery operations The implementation of DiscoveredCharacteristic::discoverDescriptors is now fullfiled. --- ble/DiscoveredCharacteristicDescriptor.h | 66 ++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 ble/DiscoveredCharacteristicDescriptor.h diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h new file mode 100644 index 0000000..fd3ddc4 --- /dev/null +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -0,0 +1,66 @@ +/* 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" + + +/** + * + */ +class DiscoveredCharacteristicDescriptor { + +public: + DiscoveredCharacteristicDescriptor( + GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t gattHandle, const UUID& uuid) : + _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(gattHandle) { + + } + + GattClient* client() { + return _client; + } + + const GattClient* client() const { + return _client; + } + + Gap::Handle_t connectionHandle() const { + return _connectionHandle; + } + + const UUID& uuid(void) const { + return _uuid; + } + + GattAttribute::Handle_t gattHandle() const { + return _gattHandle; + } + +private: + GattClient *_client; + Gap::Handle_t _connectionHandle; + UUID _uuid; + GattAttribute::Handle_t _gattHandle; +}; + +#endif /*__DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__*/ From 62a1c4a9cc382bd3c717b13cdb6176e1673af5e5 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 17 Nov 2015 10:15:17 +0000 Subject: [PATCH 04/20] Improve Characteristic descriptor discovery: - all member of CharacteristicDescriptorDiscovery::DiscoveryCallbackParams_t are now const by default - CharacteristicDescriptorDiscovery::TerminationCallbackParams_t now accept a status parameter which indicate if the operation ends properly or not - Remove DiscoveredCharacteristicDescriptor declaration from DiscoveredCharacteristic.h file - Add comparison operation to DiscoveredCharacteristic::Properties_t type - Add lastHandle member to DiscoveredCharacteristic - Add equality operator to DiscoveredCharacteristic - make FunctionPointerWithContext call operation const, so that it mirror std::function and allow to call this kind of objects to be called when they are passed by const reference - Add primitive operations to GattClient for dicovering characteristic descriptors - Fullfil DiscoveredCharacteristic::discoverDescriptors function implementation --- ble/CharacteristicDescriptorDiscovery.h | 11 ++-- ble/DiscoveredCharacteristic.h | 75 ++++++++++++++++--------- ble/FunctionPointerWithContext.h | 20 +++++-- ble/GattClient.h | 47 ++++++++++++++++ source/DiscoveredCharacteristic.cpp | 17 ++++-- 5 files changed, 130 insertions(+), 40 deletions(-) diff --git a/ble/CharacteristicDescriptorDiscovery.h b/ble/CharacteristicDescriptorDiscovery.h index 67beb8f..43aaf39 100644 --- a/ble/CharacteristicDescriptorDiscovery.h +++ b/ble/CharacteristicDescriptorDiscovery.h @@ -28,24 +28,25 @@ public: * Exposed application callback types. */ struct DiscoveryCallbackParams_t { - DiscoveredCharacteristic& characteristic; - DiscoveredCharacteristicDescriptor& descriptor; + const DiscoveredCharacteristic& characteristic; + const DiscoveredCharacteristicDescriptor& descriptor; }; struct TerminationCallbackParams_t { - DiscoveredCharacteristic& characteristic; + const DiscoveredCharacteristic& characteristic; + ble_error_t status; }; /** * Callback type for when a matching characteristic descriptor is found during * characteristic descriptor discovery. The receiving function is passed in a - * pointer to a DiscoveredCharacteristicDescriptor object which will remain + * 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; + typedef FunctionPointerWithContext DiscoveryCallback_t; /** * Callback type for when characteristic descriptor discovery terminates. diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 89e4722..b8a8c12 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -21,6 +21,9 @@ #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 @@ -46,30 +49,21 @@ public: bool indicate(void) const {return _indicate; } bool authSignedWrite(void) const {return _authSignedWrite;} + friend bool operator==(Properties_t rhs, Properties_t lhs) { + return rhs._broadcast == lhs._broadcast && + rhs._read == lhs._read && + rhs._writeWoResp == lhs._writeWoResp && + rhs._write == lhs._write && + rhs._notify == lhs._notify && + rhs._indicate == lhs._indicate && + rhs._authSignedWrite == lhs._authSignedWrite; + } + 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 @@ -108,13 +102,13 @@ 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 onCharacteristicDiscovered This callback will be called every time a descriptor is discovered + * @param 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. */ - ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const; + ble_error_t discoverDescriptors(CharacteristicDescriptorDiscovery::DiscoveryCallback_t onCharacteristicDiscovered, + CharacteristicDescriptorDiscovery::TerminationCallback_t onTermination) const; /** * Perform a write procedure. @@ -148,19 +142,47 @@ public: return props; } - const GattAttribute::Handle_t& getDeclHandle(void) const { + GattAttribute::Handle_t getDeclHandle(void) const { return declHandle; } - const GattAttribute::Handle_t& getValueHandle(void) const { + + GattAttribute::Handle_t getValueHandle(void) const { return valueHandle; } + GattAttribute::Handle_t getLastHandle(void) const { + return lastHandle; + } + + GattClient* getGattClient() { + return gattc; + } + + const GattClient* getGattClient() const { + return gattc; + } + + Gap::Handle_t getConnectionHandle() const { + return connHandle; + } + + friend bool operator==(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) { + return rhs.gattc == rhs.gattc && + rhs.uuid == lhs.uuid && + rhs.props == rhs.props && + rhs.declHandle == lhs.declHandle && + rhs.valueHandle == lhs.valueHandle && + rhs.lastHandle == lhs.lastHandle && + rhs.connHandle == lhs.connHandle; + } + 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) { /* empty */ } @@ -172,6 +194,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/FunctionPointerWithContext.h b/ble/FunctionPointerWithContext.h index 41b99fa..6132c4e 100644 --- a/ble/FunctionPointerWithContext.h +++ b/ble/FunctionPointerWithContext.h @@ -26,6 +26,7 @@ template class FunctionPointerWithContext { public: typedef FunctionPointerWithContext *pFunctionPointerWithContext_t; + typedef const FunctionPointerWithContext *cpFunctionPointerWithContext_t; typedef void (*pvoidfcontext_t)(ContextType context); /** Create a FunctionPointerWithContext, attaching a static function @@ -73,7 +74,7 @@ public: * FunctionPointers their callbacks are invoked as well. * @Note: all chained callbacks stack up; so hopefully there won't be too * many FunctionPointers in a chain. */ - void call(ContextType context) { + void call(ContextType context) const { _caller(this, context); /* Propagate the call to next in the chain. */ @@ -101,9 +102,18 @@ public: return (pvoidfcontext_t)_function; } + friend bool operator==(const FunctionPointerWithContext& lhs, const FunctionPointerWithContext& rhs) { + return rhs._caller == lhs._caller && + memcmp( + &rhs._memberFunctionAndPointer, + &lhs._memberFunctionAndPointer, + sizeof(rhs._memberFunctionAndPointer) + ) == 0; + } + private: template - static void membercaller(pFunctionPointerWithContext_t self, ContextType context) { + static void membercaller(cpFunctionPointerWithContext_t self, ContextType context) { if (self->_memberFunctionAndPointer._object) { T *o = static_cast(self->_memberFunctionAndPointer._object); void (T::*m)(ContextType); @@ -112,7 +122,7 @@ private: } } - static void functioncaller(pFunctionPointerWithContext_t self, ContextType context) { + static void functioncaller(cpFunctionPointerWithContext_t self, ContextType context) { if (self->_function) { self->_function(context); } @@ -141,10 +151,10 @@ private: * object this pointer and pointer to member - * _memberFunctionAndPointer._object will be NULL if none attached */ - MemberFunctionAndPtr _memberFunctionAndPointer; + mutable MemberFunctionAndPtr _memberFunctionAndPointer; }; - void (*_caller)(FunctionPointerWithContext*, ContextType); + void (*_caller)(const FunctionPointerWithContext*, ContextType); pFunctionPointerWithContext_t _next; /**< Optional link to make a chain out of functionPointers; this * allows chaining function pointers without requiring diff --git a/ble/GattClient.h b/ble/GattClient.h index 7a8867e..129e908 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" @@ -275,6 +276,52 @@ public: /* Requesting action from porter(s): 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 The characteristic targeted by this discovery + * @param callback This is the application callback for each descriptors + * found. + * @note service discovery may still be active when the callback is issued; + * calling asynchronous BLE-stack APIs from within this application callback + * might cause the stack to abort the discovery. If this becomes an issue, + * it may be better to make local copy of the DiscoveredCharacteristicDescriptor + * and wait for characteristic descriptor discovery to terminate before + * operating on the descriptor. + * + * @return + * BLE_ERROR_NONE if characteristic descriptor discovery is launched + * successfully; else an appropriate error. + */ + virtual ble_error_t discoverCharacteristicDescriptors( + const DiscoveredCharacteristic& characteristic, + CharacteristicDescriptorDiscovery::DiscoveryCallback_t discoveryCallback, + CharacteristicDescriptorDiscovery::TerminationCallback_t terminationCallback) { + (void) characteristic; + (void) discoveryCallback; + (void) terminationCallback; + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + } + + /** + * Is characteristic descriptor discovery currently active? + */ + virtual bool isCharacteristicDiscoveryActive(const DiscoveredCharacteristic& characteristic) const { + (void) characteristic; + return false; /* Requesting action from porter(s): override this API if this capability is supported. */ + } + + /** + * Terminate an ongoing characteristic descriptor discovery. This should result + * in an invocation of the TerminationCallback if characteristic descriptor discovery is active. + */ + virtual void terminateCharacteristicDiscovery(const DiscoveredCharacteristic& characteristic) { + /* Requesting action from porter(s): override this API if this capability is supported. */ + (void) characteristic; + } + /** * Setup a callback for when GattClient receives an update event * corresponding to a change in value of a characteristic on the remote diff --git a/source/DiscoveredCharacteristic.cpp b/source/DiscoveredCharacteristic.cpp index 5d0133d..ebe1a5b 100644 --- a/source/DiscoveredCharacteristic.cpp +++ b/source/DiscoveredCharacteristic.cpp @@ -59,8 +59,17 @@ DiscoveredCharacteristic::writeWoResponse(uint16_t length, const uint8_t *value) return gattc->write(GattClient::GATT_OP_WRITE_CMD, connHandle, valueHandle, length, value); } -ble_error_t -DiscoveredCharacteristic::discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID) const -{ - return BLE_ERROR_NOT_IMPLEMENTED; /* TODO: this needs to be filled in. */ +ble_error_t DiscoveredCharacteristic::discoverDescriptors( + CharacteristicDescriptorDiscovery::DiscoveryCallback_t onCharacteristicDiscovered, + CharacteristicDescriptorDiscovery::TerminationCallback_t onTermination) const { + + if(!gattc) { + return BLE_ERROR_INVALID_STATE; + } + + ble_error_t err = gattc->discoverCharacteristicDescriptors( + *this, onCharacteristicDiscovered, onTermination + ); + + return err; } From 483cf906dba32b335eacbe97c800ac3b05eeacc0 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 17 Nov 2015 14:17:38 +0000 Subject: [PATCH 05/20] Improve FunctionPointerWithContext value semantic. Fix operator== in DiscoveredCharacteristic. add DiscoveredOperator::operator!= add a function to set the last handle of a DiscoveredCharacteristic on the fly --- ble/DiscoveredCharacteristic.h | 15 ++++++++++++--- ble/FunctionPointerWithContext.h | 13 ++++++++++++- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index b8a8c12..0f54118 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -154,6 +154,10 @@ public: return lastHandle; } + void setLastHandle(GattAttribute::Handle_t last) { + lastHandle = last; + } + GattClient* getGattClient() { return gattc; } @@ -167,22 +171,27 @@ public: } friend bool operator==(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) { - return rhs.gattc == rhs.gattc && + return rhs.gattc == lhs.gattc && rhs.uuid == lhs.uuid && - rhs.props == rhs.props && + rhs.props == lhs.props && rhs.declHandle == lhs.declHandle && rhs.valueHandle == lhs.valueHandle && rhs.lastHandle == lhs.lastHandle && rhs.connHandle == lhs.connHandle; } + friend bool operator !=(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) { + return !(rhs == lhs); + } + public: DiscoveredCharacteristic() : gattc(NULL), uuid(UUID::ShortUUIDBytes_t(0)), props(), declHandle(GattAttribute::INVALID_HANDLE), valueHandle(GattAttribute::INVALID_HANDLE), - lastHandle(GattAttribute::INVALID_HANDLE) { + lastHandle(GattAttribute::INVALID_HANDLE), + connHandle() { /* empty */ } diff --git a/ble/FunctionPointerWithContext.h b/ble/FunctionPointerWithContext.h index 6132c4e..ae44fbb 100644 --- a/ble/FunctionPointerWithContext.h +++ b/ble/FunctionPointerWithContext.h @@ -34,7 +34,7 @@ public: * @param function The void static function to attach (default is none) */ FunctionPointerWithContext(void (*function)(ContextType context) = NULL) : - _function(NULL), _caller(NULL), _next(NULL) { + _memberFunctionAndPointer(), _caller(NULL), _next(NULL) { attach(function); } @@ -49,6 +49,17 @@ public: attach(object, member); } + FunctionPointerWithContext(const FunctionPointerWithContext& that) : + _memberFunctionAndPointer(that._memberFunctionAndPointer), _caller(that._caller), _next(NULL) { + } + + FunctionPointerWithContext& operator=(const FunctionPointerWithContext& that) { + _memberFunctionAndPointer = that._memberFunctionAndPointer; + _caller = that._caller; + _next = NULL; + return *this; + } + /** Attach a static function * * @param function The void static function to attach (default is none) From b8260b5193445491cacf0364952a020febe0f0a9 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 18 Nov 2015 12:44:35 +0000 Subject: [PATCH 06/20] Use const reference instead of value for characteristic discovery callbacks --- ble/DiscoveredCharacteristic.h | 4 ++-- ble/GattClient.h | 4 ++-- source/DiscoveredCharacteristic.cpp | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 0f54118..d06b20a 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -107,8 +107,8 @@ public: * * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error. */ - ble_error_t discoverDescriptors(CharacteristicDescriptorDiscovery::DiscoveryCallback_t onCharacteristicDiscovered, - CharacteristicDescriptorDiscovery::TerminationCallback_t onTermination) const; + ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const; /** * Perform a write procedure. diff --git a/ble/GattClient.h b/ble/GattClient.h index 129e908..408019f 100644 --- a/ble/GattClient.h +++ b/ble/GattClient.h @@ -297,8 +297,8 @@ public: */ virtual ble_error_t discoverCharacteristicDescriptors( const DiscoveredCharacteristic& characteristic, - CharacteristicDescriptorDiscovery::DiscoveryCallback_t discoveryCallback, - CharacteristicDescriptorDiscovery::TerminationCallback_t terminationCallback) { + const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) { (void) characteristic; (void) discoveryCallback; (void) terminationCallback; diff --git a/source/DiscoveredCharacteristic.cpp b/source/DiscoveredCharacteristic.cpp index ebe1a5b..65b63dd 100644 --- a/source/DiscoveredCharacteristic.cpp +++ b/source/DiscoveredCharacteristic.cpp @@ -60,8 +60,8 @@ DiscoveredCharacteristic::writeWoResponse(uint16_t length, const uint8_t *value) } ble_error_t DiscoveredCharacteristic::discoverDescriptors( - CharacteristicDescriptorDiscovery::DiscoveryCallback_t onCharacteristicDiscovered, - CharacteristicDescriptorDiscovery::TerminationCallback_t onTermination) const { + const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered, + const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const { if(!gattc) { return BLE_ERROR_INVALID_STATE; From 4d8829addb257060acd087df4bd5e182633ef947 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 18 Nov 2015 14:24:40 +0000 Subject: [PATCH 07/20] Workaround for mbed os Functionpointer implementation: mbed os FunctionPointer implementation does not allow, yet, to use a const member function This kind of workaround is needed to use FunctionPointerWithContext class in minar --- ble/FunctionPointerWithContext.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/ble/FunctionPointerWithContext.h b/ble/FunctionPointerWithContext.h index 8c4159d..79d5594 100644 --- a/ble/FunctionPointerWithContext.h +++ b/ble/FunctionPointerWithContext.h @@ -94,6 +94,16 @@ public: } } + /** Same as above, workaround for mbed os FunctionPointer implementation. */ + void call(ContextType context) { + _caller(this, context); + + /* Propagate the call to next in the chain. */ + if (_next) { + _next->call(context); + } + } + /** * Set up an external FunctionPointer as a next in the chain of related * callbacks. Invoking call() on the head FunctionPointer will invoke all From 15c69957453ce5a596f2b581b83729133f9a42ff Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 18 Nov 2015 14:36:33 +0000 Subject: [PATCH 08/20] Add operator!= for DiscoveredCharacteristic::Properties_t --- ble/DiscoveredCharacteristic.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index b08471b..db02516 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -59,6 +59,10 @@ public: rhs._authSignedWrite == lhs._authSignedWrite; } + friend bool operator!=(Properties_t rhs, Properties_t lhs) { + return !(rhs == lhs); + } + private: operator uint8_t() const; /* Disallow implicit conversion into an integer. */ operator unsigned() const; /* Disallow implicit conversion into an integer. */ From 16f99ad6ef94c9f16c1c0de9241936b0e215484c Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 18 Nov 2015 15:51:27 +0000 Subject: [PATCH 09/20] Rename characteristic descriptors discovery activity and termination function --- ble/GattClient.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ble/GattClient.h b/ble/GattClient.h index 0b4a3a1..c097c27 100644 --- a/ble/GattClient.h +++ b/ble/GattClient.h @@ -308,7 +308,8 @@ public: /** * Is characteristic descriptor discovery currently active? */ - virtual bool isCharacteristicDiscoveryActive(const DiscoveredCharacteristic& characteristic) const { + virtual bool isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const + { (void) characteristic; return false; /* Requesting action from porter(s): override this API if this capability is supported. */ } @@ -317,7 +318,7 @@ public: * Terminate an ongoing characteristic descriptor discovery. This should result * in an invocation of the TerminationCallback if characteristic descriptor discovery is active. */ - virtual void terminateCharacteristicDiscovery(const DiscoveredCharacteristic& characteristic) { + virtual void terminateCharacteristicDescriptorsDiscovery(const DiscoveredCharacteristic& characteristic) { /* Requesting action from porter(s): override this API if this capability is supported. */ (void) characteristic; } From 933f134872610fe2f87bb0e694f157c7784e1b44 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 12:03:45 +0000 Subject: [PATCH 10/20] Add documentation for CharacteristicDescriptorDiscovery --- ble/CharacteristicDescriptorDiscovery.h | 66 ++++++++++++++++++++----- 1 file changed, 54 insertions(+), 12 deletions(-) diff --git a/ble/CharacteristicDescriptorDiscovery.h b/ble/CharacteristicDescriptorDiscovery.h index 43aaf39..4cd0fb2 100644 --- a/ble/CharacteristicDescriptorDiscovery.h +++ b/ble/CharacteristicDescriptorDiscovery.h @@ -19,37 +19,79 @@ #include "FunctionPointerWithContext.h" -class DiscoveredCharacteristic; -class DiscoveredCharacteristicDescriptor; +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: - /* - * Exposed application callback types. + /** + * @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; }; - struct TerminationCallbackParams_t { + /** + * @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; }; /** - * Callback type for when a matching characteristic descriptor is found during - * characteristic descriptor discovery. The receiving function is passed in 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 + * @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; /** - * Callback type for when characteristic descriptor discovery terminates. + * @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; }; From 325f52c7aaa503fed964acc73ac55ecf3d322d93 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 12:04:04 +0000 Subject: [PATCH 11/20] Add documentation for DiscoveredCharacteristic --- ble/DiscoveredCharacteristic.h | 123 +++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 20 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 35c9390..0c361c0 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -24,7 +24,6 @@ #include "CharacteristicDescriptorDiscovery.h" #include "ble/DiscoveredCharacteristicDescriptor.h" - /** * Structure for holding information about the service and the characteristics * found during the discovery process. @@ -36,7 +35,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. */ @@ -49,7 +48,15 @@ public: bool indicate(void) const {return _indicate; } bool authSignedWrite(void) const {return _authSignedWrite;} - friend bool operator==(Properties_t rhs, Properties_t lhs) { + /** + * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t + * + * @param lhs The left hand side of the equality expression + * @param rhs 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 rhs._broadcast == lhs._broadcast && rhs._read == lhs._read && rhs._writeWoResp == lhs._writeWoResp && @@ -59,7 +66,15 @@ public: rhs._authSignedWrite == lhs._authSignedWrite; } - friend bool operator!=(Properties_t rhs, Properties_t lhs) { + /** + * @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 !(rhs == lhs); } @@ -108,12 +123,12 @@ public: /** * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic. * - * @param onCharacteristicDiscovered This callback will be called every time a descriptor is discovered + * @param onDescriptorDiscovered This callback will be called every time a descriptor is discovered * @param 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(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered, + ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered, const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const; /** @@ -145,54 +160,122 @@ public: } 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; } + /** + * @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 DiscoveredCharacteristic::getProperties . + * - The characteristic value attribute handle. This field can be accessed + * by using DiscoveredCharacteristic::getValueHandle . + * - The characteristic UUID, this value can be accessed by using the + * function DiscoveredCharacteristic::getUUID . + * @return the declaration handle of this characteristic. + */ GattAttribute::Handle_t getDeclHandle(void) const { return declHandle; } + /** + * @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 + 1. But it is not always + * the case. Anyway, users are allowed to use + 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 DiscoveredCharacteristic::getDeclHandle) + * - one for the value (see DiscoveredCharacteristic::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; } - void setLastHandle(GattAttribute::Handle_t last) { + void setLastHandle(GattAttribute::Handle_t last) { lastHandle = last; } - GattClient* getGattClient() { + /** + * @brief Return the GattClient which can operate on this characteristic. + * @return The GattClient which can operate on this characteristic. + */ + GattClient* getGattClient() { return gattc; } - const GattClient* getGattClient() const { + /** + * @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; } - friend bool operator==(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) { - return rhs.gattc == lhs.gattc && - rhs.uuid == lhs.uuid && - rhs.props == lhs.props && - rhs.declHandle == lhs.declHandle && - rhs.valueHandle == lhs.valueHandle && - rhs.lastHandle == lhs.lastHandle && - rhs.connHandle == lhs.connHandle; + /** + * @brief "Equal to" operator for DiscoveredCharacteristic + * + * @param lhs The left hand side of the equality expression + * @param rhs 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; } - friend bool operator !=(const DiscoveredCharacteristic& rhs, const DiscoveredCharacteristic& lhs) { - return !(rhs == lhs); + /** + * @brief "Not equal to" operator for DiscoveredCharacteristic + * + * @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 !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) { + return !(lhs == rhs); } public: From e9d0a85643912c1e28be27b9c4a4d24c26126d8f Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 13:39:28 +0000 Subject: [PATCH 12/20] Improve description of class DiscoveredCharacteristic --- ble/DiscoveredCharacteristic.h | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 0c361c0..88291da 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -25,8 +25,20 @@ #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: From 6b6cf34b1dbb3eb8f4a7279a6cf07e8b38bc3d29 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 13:40:23 +0000 Subject: [PATCH 13/20] Improve description of class DiscoveredCharacteristicDescriptor --- ble/DiscoveredCharacteristicDescriptor.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h index fd3ddc4..f11c5bd 100644 --- a/ble/DiscoveredCharacteristicDescriptor.h +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -25,22 +25,22 @@ /** - * + * */ class DiscoveredCharacteristicDescriptor { public: DiscoveredCharacteristicDescriptor( - GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t gattHandle, const UUID& uuid) : + GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t gattHandle, const UUID& uuid) : _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(gattHandle) { } - GattClient* client() { + GattClient* client() { return _client; } - const GattClient* client() const { + const GattClient* client() const { return _client; } From bb9cb988a2b0ec733a8961f934bb17aa35c23e25 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 13:44:30 +0000 Subject: [PATCH 14/20] Improve consistency of accessor naming --- ble/DiscoveredCharacteristicDescriptor.h | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h index f11c5bd..6258c30 100644 --- a/ble/DiscoveredCharacteristicDescriptor.h +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -23,7 +23,6 @@ #include "GattClient.h" #include "CharacteristicDescriptorDiscovery.h" - /** * */ @@ -36,23 +35,23 @@ public: } - GattClient* client() { + GattClient* getGattClient() { return _client; } - const GattClient* client() const { + const GattClient* getGattClient() const { return _client; } - Gap::Handle_t connectionHandle() const { + Gap::Handle_t getConnectionHandle() const { return _connectionHandle; } - const UUID& uuid(void) const { + const UUID& getUUID(void) const { return _uuid; } - GattAttribute::Handle_t gattHandle() const { + GattAttribute::Handle_t getAttributeHandle() const { return _gattHandle; } From d7700bccb8b40ef4a5e1c0a932e2528671274a1d Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 14:04:05 +0000 Subject: [PATCH 15/20] Improve documentation of DiscoveredCharacteristicDescriptor --- ble/DiscoveredCharacteristicDescriptor.h | 50 +++++++++++++++++++++++- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h index 6258c30..e24bb81 100644 --- a/ble/DiscoveredCharacteristicDescriptor.h +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -24,33 +24,79 @@ #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 gattHandle, const UUID& uuid) : - _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(gattHandle) { + 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; } From e877d0b7c754583d0e64e7be3a2a87071dbd0dd2 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 14:31:08 +0000 Subject: [PATCH 16/20] Improve and correct documentation of DiscoveredCharacteristic --- ble/DiscoveredCharacteristic.h | 84 ++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 34 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 88291da..31d7021 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -29,13 +29,13 @@ * discovery procedure (see GattClient::launchServiceDiscovery ). * * @detail Provide detailed informations about a discovered characteristic like: - * - Its UUID (see getUUID). + * - Its UUID (see #getUUID). * - The most important handles of the characteristic definition - * (see getDeclHandle, getValueHandle, getLastHandle ) - * - Its properties (see getProperties). + * (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) + * - 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. @@ -63,19 +63,19 @@ public: /** * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t * - * @param lhs The left hand side of the equality expression - * @param rhs The right hand side of the equality expression + * @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 rhs._broadcast == lhs._broadcast && - rhs._read == lhs._read && - rhs._writeWoResp == lhs._writeWoResp && - rhs._write == lhs._write && - rhs._notify == lhs._notify && - rhs._indicate == lhs._indicate && - rhs._authSignedWrite == lhs._authSignedWrite; + 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; } /** @@ -87,7 +87,7 @@ public: * @return true if operands are not equals, false otherwise. */ friend bool operator!=(Properties_t lhs, Properties_t rhs) { - return !(rhs == lhs); + return !(lhs == rhs); } private: @@ -101,6 +101,9 @@ public: * 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 @@ -108,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 @@ -135,8 +146,8 @@ public: /** * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic. * - * @param onDescriptorDiscovered This callback will be called every time a descriptor is discovered - * @param onTermination This callback will be called when the discovery process is over. + * @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. */ @@ -146,9 +157,9 @@ public: /** * 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 @@ -163,9 +174,14 @@ 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); @@ -194,11 +210,11 @@ public: * definition. The value accessible at this handle contains the following * informations: * - The characteristics properties (see Properties_t). This value can - * be accessed by using DiscoveredCharacteristic::getProperties . + * be accessed by using #getProperties . * - The characteristic value attribute handle. This field can be accessed - * by using DiscoveredCharacteristic::getValueHandle . + * by using #getValueHandle . * - The characteristic UUID, this value can be accessed by using the - * function DiscoveredCharacteristic::getUUID . + * function #getUUID . * @return the declaration handle of this characteristic. */ GattAttribute::Handle_t getDeclHandle(void) const { @@ -208,8 +224,8 @@ public: /** * @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 + 1. But it is not always - * the case. Anyway, users are allowed to use + 1 to access + * 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. */ @@ -220,8 +236,8 @@ public: /** * @brief Return the last handle of the characteristic definition. * @details A Characteristic definition can contain a lot of handles: - * - one for the declaration (see DiscoveredCharacteristic::getDeclHandle) - * - one for the value (see DiscoveredCharacteristic::getValueHandle) + * - 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. @@ -263,8 +279,8 @@ public: /** * @brief "Equal to" operator for DiscoveredCharacteristic * - * @param lhs The left hand side of the equality expression - * @param rhs The right hand side of the equality expression + * @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. */ @@ -281,8 +297,8 @@ public: /** * @brief "Not equal to" operator for DiscoveredCharacteristic * - * @param lhs The right hand side of the expression - * @param rhs The left hand side of the expression + * @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. */ From a56a875bbc256b37683f4df3c0ca565d14172eea Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 14:33:31 +0000 Subject: [PATCH 17/20] Improve cross references for DiscoveredCharacteristicDescriptor docs --- ble/DiscoveredCharacteristicDescriptor.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ble/DiscoveredCharacteristicDescriptor.h b/ble/DiscoveredCharacteristicDescriptor.h index e24bb81..86fd6ab 100644 --- a/ble/DiscoveredCharacteristicDescriptor.h +++ b/ble/DiscoveredCharacteristicDescriptor.h @@ -30,8 +30,8 @@ * * @detail Provide detailed informations about a discovered characteristic descriptor * like: - * - Its UUID (see getUUID). - * - Its handle (see getAttributeHandle) + * - 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. * From 726a144eeb683331fa571f71d0ef8fed52305843 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 14:48:38 +0000 Subject: [PATCH 18/20] Fix whitespace and improve documentation of Descriptors discovery --- ble/GattClient.h | 66 ++++++++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/ble/GattClient.h b/ble/GattClient.h index 4ae0793..e74eca3 100644 --- a/ble/GattClient.h +++ b/ble/GattClient.h @@ -217,8 +217,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. @@ -247,8 +247,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) { @@ -258,7 +258,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() { @@ -267,7 +267,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. */ @@ -278,10 +278,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,21 +307,20 @@ public: /** * @brief launch discovery of descriptors for a given characteristic - * @details This function will discover all descriptors available for a - * specific characteristic. - * - * @param characteristic The characteristic targeted by this discovery - * @param callback This is the application callback for each descriptors - * found. - * @note service discovery may still be active when the callback is issued; - * calling asynchronous BLE-stack APIs from within this application callback - * might cause the stack to abort the discovery. If this becomes an issue, - * it may be better to make local copy of the DiscoveredCharacteristicDescriptor - * and wait for characteristic descriptor discovery to terminate before - * operating on the descriptor. - * - * @return - * BLE_ERROR_NONE if characteristic descriptor discovery is launched + * @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( @@ -331,21 +330,28 @@ public: (void) characteristic; (void) discoveryCallback; (void) terminationCallback; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Is characteristic descriptor discovery currently active? + * @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 isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const + virtual bool isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const { (void) characteristic; return false; /* Requesting action from porter(s): override this API if this capability is supported. */ } /** - * Terminate an ongoing characteristic descriptor discovery. This should result - * in an invocation of the TerminationCallback if characteristic descriptor discovery is active. + * @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 terminateCharacteristicDescriptorsDiscovery(const DiscoveredCharacteristic& characteristic) { /* Requesting action from porter(s): override this API if this capability is supported. */ @@ -366,10 +372,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; } From 87d8941374203cbee55b37b7ab20064c33d49d7f Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 14 Dec 2015 15:03:40 +0000 Subject: [PATCH 19/20] Remove setLastHandle member function, it does not belong here --- ble/DiscoveredCharacteristic.h | 4 ---- 1 file changed, 4 deletions(-) diff --git a/ble/DiscoveredCharacteristic.h b/ble/DiscoveredCharacteristic.h index 31d7021..11c35a6 100644 --- a/ble/DiscoveredCharacteristic.h +++ b/ble/DiscoveredCharacteristic.h @@ -246,10 +246,6 @@ public: return lastHandle; } - void setLastHandle(GattAttribute::Handle_t last) { - lastHandle = last; - } - /** * @brief Return the GattClient which can operate on this characteristic. * @return The GattClient which can operate on this characteristic. From 4dda9bf1b89650357e67d964975800ac92c834fc Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 15 Dec 2015 07:57:47 +0000 Subject: [PATCH 20/20] Fix function names: - isCharacteristicDescriptorsDiscoveryActive => isCharacteristicDescriptorDiscoveryActive - terminateCharacteristicDescriptorsDiscovery =>terminateCharacteristicDescriptorDiscovery --- ble/GattClient.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ble/GattClient.h b/ble/GattClient.h index e74eca3..9846071 100644 --- a/ble/GattClient.h +++ b/ble/GattClient.h @@ -340,7 +340,7 @@ public: * @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 isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const + virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const { (void) characteristic; return false; /* Requesting action from porter(s): override this API if this capability is supported. */ @@ -353,7 +353,7 @@ public: * @param characteristic[in] The characteristic on which the running descriptors * discovery should be stopped. */ - virtual void terminateCharacteristicDescriptorsDiscovery(const DiscoveredCharacteristic& characteristic) { + virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) { /* Requesting action from porter(s): override this API if this capability is supported. */ (void) characteristic; }