add "LE Device Address" 0x1B to advertising data types
Fork of BLE_API by
Diff: ble/GattServer.h
- Revision:
- 993:4d62b7967c11
- Parent:
- 992:ca834f7ae8ed
- Child:
- 1042:21a86ac7f5b1
diff -r ca834f7ae8ed -r 4d62b7967c11 ble/GattServer.h --- a/ble/GattServer.h Wed Dec 02 10:29:44 2015 +0000 +++ b/ble/GattServer.h Wed Dec 02 10:29:44 2015 +0000 @@ -26,9 +26,18 @@ class GattServer { public: + /* Event callback handlers. */ - typedef void (*EventCallback_t)(GattAttribute::Handle_t attributeHandle); - typedef void (*ServerEventCallback_t)(void); /**< independent of any particular attribute */ + typedef FunctionPointerWithContext<unsigned> DataSentCallback_t; + typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t; + + typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t; + typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t; + + typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t; + typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t; + + typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t; protected: GattServer() : @@ -53,14 +62,14 @@ * characteristics contained within. */ virtual ble_error_t addService(GattService &service) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)service; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Read the value of a characteristic from the local GattServer + * Read the value of a characteristic from the local GATT server. * @param[in] attributeHandle * Attribute handle for the value attribute of the characteristic. * @param[out] buffer @@ -75,18 +84,18 @@ * @return BLE_ERROR_NONE if a value was read successfully into the buffer. */ virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)attributeHandle; (void)buffer; (void)lengthP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Read the value of a characteristic from the local GattServer + * Read the value of a characteristic from the local GATT server. * @param[in] connectionHandle - * Connection Handle. + * Connection handle. * @param[in] attributeHandle * Attribute handle for the value attribute of the characteristic. * @param[out] buffer @@ -100,32 +109,32 @@ * * @return BLE_ERROR_NONE if a value was read successfully into the buffer. * - * @note This API is a version of above with an additional connection handle + * @note This API is a version of the above, with an additional connection handle * parameter to allow fetches for connection-specific multivalued * attributes (such as the CCCDs). */ virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)attributeHandle; (void)buffer; (void)lengthP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Update the value of a characteristic on the local GattServer. + * Update the value of a characteristic on the local GATT server. * * @param[in] attributeHandle - * Handle for the value attribute of the Characteristic. + * Handle for the value attribute of the characteristic. * @param[in] value - * A pointer to a buffer holding the new value + * A pointer to a buffer holding the new value. * @param[in] size * Size of the new value (in bytes). * @param[in] localOnly * Should this update be kept on the local - * GattServer regardless of the state of the + * GATT server regardless of the state of the * notify/indicate flag in the CCCD for this * Characteristic? If set to true, no notification * or indication is generated. @@ -133,26 +142,26 @@ * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. */ virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)attributeHandle; (void)value; (void)size; (void)localOnly; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Update the value of a characteristic on the local GattServer. A version - * of the same as above with connection handle parameter to allow updates + * Update the value of a characteristic on the local GATT server. A version + * of the same as the above, with a connection handle parameter to allow updates * for connection-specific multivalued attributes (such as the CCCDs). * * @param[in] connectionHandle - * Connection Handle. + * Connection handle. * @param[in] attributeHandle - * Handle for the value attribute of the Characteristic. + * Handle for the value attribute of the characteristic. * @param[in] value - * A pointer to a buffer holding the new value + * A pointer to a buffer holding the new value. * @param[in] size * Size of the new value (in bytes). * @param[in] localOnly @@ -165,54 +174,54 @@ * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. */ virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)attributeHandle; (void)value; (void)size; (void)localOnly; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Determine the updates-enabled status (notification/indication) for the current connection from a characteristic's CCCD. + * Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD. * * @param characteristic - * The characteristic + * The characteristic. * @param[out] enabledP * Upon return, *enabledP is true if updates are enabled, else false. * - * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise. + * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise. */ virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)characteristic; (void)enabledP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** - * Determine the connection-specific updates-enabled status (notification/indication) from a characteristic's CCCD. + * Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD. * * @param connectionHandle - * The connection handle + * The connection handle. * @param[out] enabledP * Upon return, *enabledP is true if updates are enabled, else false. * * @param characteristic - * The characteristic + * The characteristic. * - * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise. + * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise. */ virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) { - /* avoid compiler warnings about unused variables */ + /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)characteristic; (void)enabledP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ } /** @@ -220,7 +229,7 @@ * onDataRead(). It should be overridden to return true as applicable. */ virtual bool isOnDataReadAvailable() const { - return false; /* Requesting action from porter(s): override this API if this capability is supported. */ + return false; /* Requesting action from porters: override this API if this capability is supported. */ } /* @@ -231,60 +240,81 @@ * Add a callback for the GATT event DATA_SENT (which is triggered when * updates are sent out by GATT in the form of notifications). * - * @Note: it is possible to chain together multiple onDataSent callbacks + * @Note: It is possible to chain together multiple onDataSent callbacks * (potentially from different modules of an application) to receive updates * to characteristics. * - * @Note: it is also possible to setup a callback into a member function of + * @Note: It is also possible to set up a callback into a member function of * some object. */ - void onDataSent(void (*callback)(unsigned count)) {dataSentCallChain.add(callback);} + void onDataSent(const DataSentCallback_t& callback) {dataSentCallChain.add(callback);} template <typename T> void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) { dataSentCallChain.add(objPtr, memberPtr); } /** - * Setup a callback for when an attribute has its value updated by or at the - * connected peer. For a peripheral, this callback triggered when the local + * @brief get the callback chain called when the event DATA_EVENT is triggered. + */ + DataSentCallbackChain_t& onDataSent() { + return dataSentCallChain; + } + + /** + * Set up a callback for when an attribute has its value updated by or at the + * connected peer. For a peripheral, this callback is triggered when the local * GATT server has an attribute updated by a write command from the peer. - * For a Central, this callback is triggered when a response is received for + * For a central, this callback is triggered when a response is received for * a write request. * - * @Note: it is possible to chain together multiple onDataWritten callbacks + * @Note: It is possible to chain together multiple onDataWritten callbacks * (potentially from different modules of an application) to receive updates - * to characteristics. Many services, such as DFU and UART add their own + * to characteristics. Many services, such as DFU and UART, add their own * onDataWritten callbacks behind the scenes to trap interesting events. * - * @Note: it is also possible to setup a callback into a member function of + * @Note: It is also possible to set up a callback into a member function of * some object. + * + * @Note It is possible to unregister a callback using onDataWritten().detach(callback) */ - void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {dataWrittenCallChain.add(callback);} + void onDataWritten(const DataWrittenCallback_t& callback) {dataWrittenCallChain.add(callback);} template <typename T> void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { dataWrittenCallChain.add(objPtr, memberPtr); } /** + * @brief provide access to the callchain of data written event callbacks + * It is possible to register callbacks using onDataWritten().add(callback); + * It is possible to unregister callbacks using onDataWritten().detach(callback) + * @return The data written event callbacks chain + */ + DataWrittenCallbackChain_t& onDataWritten() { + return dataWrittenCallChain; + } + + /** * Setup a callback to be invoked on the peripheral when an attribute is * being read by a remote client. * - * @Note: this functionality may not be available on all underlying stacks. + * @Note: This functionality may not be available on all underlying stacks. * You could use GattCharacteristic::setReadAuthorizationCallback() as an * alternative. Refer to isOnDataReadAvailable(). * - * @Note: it is possible to chain together multiple onDataRead callbacks + * @Note: It is possible to chain together multiple onDataRead callbacks * (potentially from different modules of an application) to receive updates * to characteristics. Services may add their own onDataRead callbacks * behind the scenes to trap interesting events. * - * @Note: it is also possible to setup a callback into a member function of + * @Note: It is also possible to set up a callback into a member function of * some object. * + * @Note It is possible to unregister a callback using onDataRead().detach(callback) + * * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; * else BLE_ERROR_NONE. */ - ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) { + ble_error_t onDataRead(const DataReadCallback_t& callback) { if (!isOnDataReadAvailable()) { return BLE_ERROR_NOT_IMPLEMENTED; } @@ -303,19 +333,29 @@ } /** - * Setup a callback for when notifications/indications are enabled for a - * characteristic on the local GattServer. + * @brief provide access to the callchain of data read event callbacks + * It is possible to register callbacks using onDataRead().add(callback); + * It is possible to unregister callbacks using onDataRead().detach(callback) + * @return The data read event callbacks chain + */ + DataReadCallbackChain_t& onDataRead() { + return dataReadCallChain; + } + + /** + * Set up a callback for when notifications or indications are enabled for a + * characteristic on the local GATT server. */ void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;} /** - * Setup a callback for when notifications/indications are disabled for a - * characteristic on the local GattServer. + * Set up a callback for when notifications or indications are disabled for a + * characteristic on the local GATT server. */ void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;} /** - * Setup a callback for when the GATT server receives a response for an + * Set up a callback for when the GATT server receives a response for an * indication event sent previously. */ void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;} @@ -323,15 +363,11 @@ /* Entry points for the underlying stack to report events back to the user. */ protected: void handleDataWrittenEvent(const GattWriteCallbackParams *params) { - if (dataWrittenCallChain.hasCallbacksAttached()) { - dataWrittenCallChain.call(params); - } + dataWrittenCallChain.call(params); } void handleDataReadEvent(const GattReadCallbackParams *params) { - if (dataReadCallChain.hasCallbacksAttached()) { - dataReadCallChain.call(params); - } + dataReadCallChain.call(params); } void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) { @@ -357,9 +393,7 @@ } void handleDataSentEvent(unsigned count) { - if (dataSentCallChain.hasCallbacksAttached()) { - dataSentCallChain.call(count); - } + dataSentCallChain.call(count); } protected: @@ -367,15 +401,15 @@ uint8_t characteristicCount; private: - CallChainOfFunctionPointersWithContext<unsigned> dataSentCallChain; - CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams *> dataWrittenCallChain; - CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> dataReadCallChain; - EventCallback_t updatesEnabledCallback; - EventCallback_t updatesDisabledCallback; - EventCallback_t confirmationReceivedCallback; + DataSentCallbackChain_t dataSentCallChain; + DataWrittenCallbackChain_t dataWrittenCallChain; + DataReadCallbackChain_t dataReadCallChain; + EventCallback_t updatesEnabledCallback; + EventCallback_t updatesDisabledCallback; + EventCallback_t confirmationReceivedCallback; private: - /* disallow copy and assignment */ + /* Disallow copy and assignment. */ GattServer(const GattServer &); GattServer& operator=(const GattServer &); };