Cristi Stoican
jgh
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/GattServer.h
- Revision:
- 1179:4ab722f8dca0
- Parent:
- 1165:0717ca5ed305
- Child:
- 1183:1589830dbdb7
--- a/ble/GattServer.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattServer.h Wed Apr 06 19:15:30 2016 +0100
@@ -26,57 +26,22 @@
class GattServer {
public:
- /**
- * Type for the registered callbacks added to the data sent callchain.
- * Refer to GattServer::onDataSent().
- */
+ /* Event callback handlers. */
typedef FunctionPointerWithContext<unsigned> DataSentCallback_t;
- /**
- * Type for the data sent event callchain. Refer to GattServer::onDataSent().
- */
typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t;
- /**
- * Type for the registered callbacks added to the data written callchain.
- * Refer to GattServer::onDataWritten().
- */
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t;
- /**
- * Type for the data written event callchain. Refer to GattServer::onDataWritten().
- */
typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t;
- /**
- * Type for the registered callbacks added to the data read callchain.
- * Refer to GattServer::onDataRead().
- */
typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t;
- /**
- * Type for the data read event callchain. Refer to GattServer::onDataRead().
- */
typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t;
- /**
- * Type for the registered callbacks added to the shutdown callchain.
- * Refer to GattServer::onShutdown().
- */
typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t;
- /**
- * Type for the shutdown event callchain. Refer to GattServer::onShutdown().
- */
typedef CallChainOfFunctionPointersWithContext<const GattServer *> GattServerShutdownCallbackChain_t;
- /**
- * Type for the registered callback for various events. Refer to
- * GattServer::onUpdatesEnabled(), GattServer::onUpdateDisabled() and
- * GattServer::onConfirmationReceived().
- */
typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t;
protected:
- /**
- * Construct a GattServer instance.
- */
GattServer() :
serviceCount(0),
characteristicCount(0),
@@ -97,11 +62,6 @@
/**
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
- *
- * @param[in] service
- * The service to be added.
- *
- * @return BLE_ERROR_NONE if the service was successfully added.
*/
virtual ble_error_t addService(GattService &service) {
/* Avoid compiler warnings about unused variables. */
@@ -112,12 +72,11 @@
/**
* 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
* A buffer to hold the value being read.
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will hold upon return the total attribute value length
@@ -137,14 +96,13 @@
/**
* Read the value of a characteristic from the local GATT server.
- *
* @param[in] connectionHandle
* Connection handle.
* @param[in] attributeHandle
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will hold upon return the total attribute value length
@@ -231,7 +189,7 @@
/**
* Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD.
*
- * @param[in] characteristic
+ * @param characteristic
* The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
@@ -249,13 +207,14 @@
/**
* Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD.
*
- * @param[in] connectionHandle
+ * @param connectionHandle
* The connection handle.
- * @param[in] characteristic
- * The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
*
+ * @param characteristic
+ * The characteristic.
+ *
* @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) {
@@ -270,8 +229,6 @@
/**
* A virtual function to allow underlying stacks to indicate if they support
* onDataRead(). It should be overridden to return true as applicable.
- *
- * @return true if onDataRead is supported, false otherwise.
*/
virtual bool isOnDataReadAvailable() const {
return false; /* Requesting action from porters: override this API if this capability is supported. */
@@ -285,41 +242,21 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @param[in] callback
- * Event handler being registered.
+ * @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 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 set up a callback into a member function of
- * some object.
+ * @Note: It is also possible to set up a callback into a member function of
+ * some object.
*/
- void onDataSent(const DataSentCallback_t& callback) {
- dataSentCallChain.add(callback);
- }
-
- /**
- * Same as GattServer::onDataSent(), but allows the possibility to add an object
- * reference and member function as handler for DATA_SENT event
- * callbacks.
- *
- * @param[in] objPtr
- * Pointer to the object of a class defining the member callback
- * function (@p memberPtr).
- * @param[in] memberPtr
- * The member callback (within the context of an object) to be
- * invoked.
- */
+ 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);
}
/**
- * @brief Provide access to the callchain of DATA_SENT event callbacks.
- *
- * @return A reference to the DATA_SENT event callback chain.
+ * @brief get the callback chain called when the event DATA_EVENT is triggered.
*/
DataSentCallbackChain_t& onDataSent() {
return dataSentCallChain;
@@ -332,48 +269,27 @@
* For a central, this callback is triggered when a response is received for
* a write request.
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @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
* onDataWritten callbacks behind the scenes to trap interesting events.
*
- * @note It is also possible to set up 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)
+ * @Note It is possible to unregister a callback using onDataWritten().detach(callback)
*/
- void onDataWritten(const DataWrittenCallback_t& callback) {
- dataWrittenCallChain.add(callback);
- }
-
- /**
- * Same as GattServer::onDataWritten(), but allows the possibility to add an object
- * reference and member function as handler for data written event
- * callbacks.
- *
- * @param[in] objPtr
- * Pointer to the object of a class defining the member callback
- * function (@p memberPtr).
- * @param[in] memberPtr
- * The member callback (within the context of an object) to be
- * invoked.
- */
+ 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.
- *
- * @return A reference to the data written event callbacks chain.
- *
- * @note It is possible to register callbacks using onDataWritten().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataWritten().detach(callback).
+ * @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;
@@ -383,25 +299,22 @@
* Setup a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
- * else BLE_ERROR_NONE.
- *
- * @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 set up 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).
+ * @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(const DataReadCallback_t& callback) {
if (!isOnDataReadAvailable()) {
@@ -411,19 +324,6 @@
dataReadCallChain.add(callback);
return BLE_ERROR_NONE;
}
-
- /**
- * Same as GattServer::onDataRead(), but allows the possibility to add an object
- * reference and member function as handler for data read event
- * callbacks.
- *
- * @param[in] objPtr
- * Pointer to the object of a class defining the member callback
- * function (@p memberPtr).
- * @param[in] memberPtr
- * The member callback (within the context of an object) to be
- * invoked.
- */
template <typename T>
ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
if (!isOnDataReadAvailable()) {
@@ -435,13 +335,10 @@
}
/**
- * @brief Provide access to the callchain of data read event callbacks.
- *
- * @return A reference to the data read event callbacks chain.
- *
- * @note It is possible to register callbacks using onDataRead().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataRead().detach(callback).
+ * @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;
@@ -452,47 +349,28 @@
* GattServer instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to chain together multiple onShutdown callbacks
+ * @Note: It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the GattServer is shutdown.
*
- * @note It is also possible to set up 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 onShutdown().detach(callback)
+ * @Note It is possible to unregister a callback using onShutdown().detach(callback)
*/
void onShutdown(const GattServerShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
-
- /**
- * Same as GattServer::onShutdown(), but allows the possibility to add an object
- * reference and member function as handler for shutdown event
- * callbacks.
- *
- * @param[in] objPtr
- * Pointer to the object of a class defining the member callback
- * function (@p memberPtr).
- * @param[in] memberPtr
- * The member callback (within the context of an object) to be
- * invoked.
- */
template <typename T>
void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
shutdownCallChain.add(objPtr, memberPtr);
}
/**
- * @brief Provide access to the callchain of shutdown event callbacks.
- *
- * @return A reference to the shutdown event callbacks chain.
- *
- * @note It is possible to register callbacks using onShutdown().add(callback).
- *
- * @note It is possible to unregister callbacks using onShutdown().detach(callback).
+ * @brief provide access to the callchain of shutdown event callbacks
+ * It is possible to register callbacks using onShutdown().add(callback);
+ * It is possible to unregister callbacks using onShutdown().detach(callback)
+ * @return The shutdown event callbacks chain
*/
GattServerShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -501,75 +379,31 @@
/**
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GATT server.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onUpdatesEnabled(EventCallback_t callback) {
- updatesEnabledCallback = callback;
- }
+ void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
/**
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GATT server.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onUpdatesDisabled(EventCallback_t callback) {
- updatesDisabledCallback = callback;
- }
+ void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
/**
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onConfirmationReceived(EventCallback_t callback) {
- confirmationReceivedCallback = callback;
- }
+ void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
/* Entry points for the underlying stack to report events back to the user. */
protected:
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data written event. This function is meant to be called from the
- * BLE stack specific implementation when a data written event occurs.
- *
- * @param[in] params
- * The data written parameters passed to the registered
- * handlers.
- */
void handleDataWrittenEvent(const GattWriteCallbackParams *params) {
dataWrittenCallChain.call(params);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data read event. This function is meant to be called from the
- * BLE stack specific implementation when a data read event occurs.
- *
- * @param[in] params
- * The data read parameters passed to the registered
- * handlers.
- */
void handleDataReadEvent(const GattReadCallbackParams *params) {
dataReadCallChain.call(params);
}
- /**
- * Helper function that notifies the registered handler of an occurrence
- * of updates enabled, updates disabled and confirmation received events.
- * This function is meant to be called from the BLE stack specific
- * implementation when any of these events occurs.
- *
- * @param[in] type
- * The type of event that occurred.
- * @param[in] attributeHandle
- * The handle of the attribute that was modified.
- */
void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) {
switch (type) {
case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
@@ -592,14 +426,6 @@
}
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data sent event. This function is meant to be called from the
- * BLE stack specific implementation when a data sent event occurs.
- *
- * @param[in] count
- * Number of packets sent.
- */
void handleDataSentEvent(unsigned count) {
dataSentCallChain.call(count);
}
@@ -637,47 +463,16 @@
}
protected:
- /**
- * The total number of services added to the ATT table.
- */
uint8_t serviceCount;
- /**
- * The total number of characteristics added to the ATT table.
- */
uint8_t characteristicCount;
private:
- /**
- * Callchain containing all registered callback handlers for data sent
- * events.
- */
DataSentCallbackChain_t dataSentCallChain;
- /**
- * Callchain containing all registered callback handlers for data written
- * events.
- */
DataWrittenCallbackChain_t dataWrittenCallChain;
- /**
- * Callchain containing all registered callback handlers for data read
- * events.
- */
DataReadCallbackChain_t dataReadCallChain;
- /**
- * Callchain containing all registered callback handlers for shutdown
- * events.
- */
GattServerShutdownCallbackChain_t shutdownCallChain;
- /**
- * The registered callback handler for updates enabled events.
- */
EventCallback_t updatesEnabledCallback;
- /**
- * The registered callback handler for updates disabled events.
- */
EventCallback_t updatesDisabledCallback;
- /**
- * The registered callback handler for confirmation received events.
- */
EventCallback_t confirmationReceivedCallback;
private:
@@ -686,4 +481,4 @@
GattServer& operator=(const GattServer &);
};
-#endif /* ifndef __GATT_SERVER_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_SERVER_H__
\ No newline at end of file