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