Matthew Lister
BLE_API
Diff: ble/GattServer.h
- Revision:
- 1183:1589830dbdb7
- Parent:
- 1179:4ab722f8dca0
- Child:
- 1192:718787de23b7
--- a/ble/GattServer.h Wed Apr 06 19:15:34 2016 +0100
+++ b/ble/GattServer.h Wed Apr 06 19:15:36 2016 +0100
@@ -26,22 +26,57 @@
class GattServer {
public:
- /* Event callback handlers. */
+ /**
+ * Type for the registered callbacks added to the data sent callchain.
+ * Refer to GattServer::onDataSent().
+ */
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),
@@ -62,6 +97,11 @@
/**
* 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. */
@@ -72,11 +112,12 @@
/**
* 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
@@ -96,13 +137,14 @@
/**
* 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
@@ -189,7 +231,7 @@
/**
* Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD.
*
- * @param characteristic
+ * @param[in] characteristic
* The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
@@ -207,14 +249,13 @@
/**
* Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD.
*
- * @param connectionHandle
+ * @param[in] 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) {
@@ -229,6 +270,8 @@
/**
* 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. */
@@ -242,21 +285,41 @@
* 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
- * (potentially from different modules of an application) to receive updates
- * to characteristics.
+ * @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 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);}
+ 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.
+ */
template <typename T>
void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
dataSentCallChain.add(objPtr, memberPtr);
}
/**
- * @brief get the callback chain called when the event DATA_EVENT is triggered.
+ * @brief Provide access to the callchain of DATA_SENT event callbacks.
+ *
+ * @return A reference to the DATA_SENT event callback chain.
*/
DataSentCallbackChain_t& onDataSent() {
return dataSentCallChain;
@@ -269,27 +332,48 @@
* 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
+ * @param[in] callback
+ * Event handler being registered.
+ *
+ * @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);}
+ 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.
+ */
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
+ * @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).
*/
DataWrittenCallbackChain_t& onDataWritten() {
return dataWrittenCallChain;
@@ -299,22 +383,25 @@
* 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.
+ * @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.
* 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)
- *
- * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
- * else BLE_ERROR_NONE.
+ * @note It is possible to unregister a callback using onDataRead().detach(callback).
*/
ble_error_t onDataRead(const DataReadCallback_t& callback) {
if (!isOnDataReadAvailable()) {
@@ -324,6 +411,19 @@
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()) {
@@ -335,10 +435,13 @@
}
/**
- * @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
+ * @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).
*/
DataReadCallbackChain_t& onDataRead() {
return dataReadCallChain;
@@ -349,28 +452,47 @@
* GattServer instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @Note: It is possible to chain together multiple onShutdown callbacks
+ * @param[in] callback
+ * Event handler being registered.
+ *
+ * @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
- * 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
+ * @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).
*/
GattServerShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -379,31 +501,75 @@
/**
* 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:
@@ -426,6 +592,14 @@
}
}
+ /**
+ * 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);
}
@@ -463,16 +637,47 @@
}
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:
@@ -481,4 +686,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