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