Diff: ble/Gap.h

Revision:

933:3ec277a0d780

Parent:

923:ca1964e56ddf

Child:

934:5e3acddfcd82

diff -r 68a113707ba5 -r 3ec277a0d780 ble/Gap.h
--- a/ble/Gap.h	Thu Nov 26 12:52:05 2015 +0000
+++ b/ble/Gap.h	Thu Nov 26 12:52:06 2015 +0000
@@ -24,7 +24,7 @@
 #include "CallChainOfFunctionPointersWithContext.h"
 #include "FunctionPointerWithContext.h"
 
-/* Forward declarations for classes that will only be used for pointers or references in the following. */
+/* Forward declarations for classes which will only be used for pointers or references in the following. */
 class GapAdvertisingParams;
 class GapScanningParams;
 class GapAdvertisingData;
@@ -37,11 +37,11 @@
         ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
         ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
     };
-    typedef enum AddressType_t addr_type_t; /* @Note: Deprecated. Use AddressType_t instead. */
+    typedef enum AddressType_t addr_type_t; /* @Note: deprecated. Use AddressType_t instead. */
 
     static const unsigned ADDR_LEN = 6;
     typedef uint8_t Address_t[ADDR_LEN]; /* 48-bit address, LSB format. */
-    typedef Address_t address_t;         /* @Note: Deprecated. Use Address_t instead. */
+    typedef Address_t address_t;         /* @Note: deprecated. Use Address_t instead. */
 
     enum TimeoutSource_t {
         TIMEOUT_SRC_ADVERTISING      = 0x00, /**< Advertising timeout. */
@@ -52,24 +52,24 @@
 
     /**
      * Enumeration for disconnection reasons. The values for these reasons are
-     * derived from Nordic's implementation, but the reasons are meant to be
-     * independent of the transport. If you are returned a reason that is not
-     * covered by this enumeration, please refer to the underlying
+     * derived from Nordic's implementation; but the reasons are meant to be
+     * independent of the transport. If you are returned a reason which is not
+     * covered by this enumeration, then please refer to the underlying
      * transport library.
      */
     enum DisconnectionReason_t {
         CONNECTION_TIMEOUT                          = 0x08,
         REMOTE_USER_TERMINATED_CONNECTION           = 0x13,
-        REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14,  /**< Remote device terminated connection due to low resources.*/
-        REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF     = 0x15,  /**< Remote device terminated connection due to power off. */
+        REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14,  /**< Remote Device Terminated Connection due to low resources.*/
+        REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF     = 0x15,  /**< Remote Device Terminated Connection due to power off. */
         LOCAL_HOST_TERMINATED_CONNECTION            = 0x16,
         CONN_INTERVAL_UNACCEPTABLE                  = 0x3B,
     };
 
-    /* Describes the current state of the device (more than one bit can be set). */
+    /* Describes the current state of the device (more than one bit can be set) */
     struct GapState_t {
-        unsigned advertising : 1; /**< Peripheral is currently advertising. */
-        unsigned connected   : 1; /**< Peripheral is connected to a central. */
+        unsigned advertising : 1; /**< peripheral is currently advertising */
+        unsigned connected   : 1; /**< peripheral is connected to a central */
     };
 
     typedef uint16_t Handle_t; /* Type for connection handle. */
@@ -140,15 +140,10 @@
         return (durationInMillis * 1000) / UNIT_1_25_MS;
     }
 
-    typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
-    typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
 
-    typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
-    typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
-
-    typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
-    typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;    
-
+    typedef void (*TimeoutEventCallback_t)(TimeoutSource_t source);
+    typedef void (*ConnectionEventCallback_t)(const ConnectionCallbackParams_t *params);
+    typedef void (*DisconnectionEventCallback_t)(const DisconnectionCallbackParams_t *params);
     typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
 
     /*
@@ -157,7 +152,7 @@
 public:
     /**
      * Set the BTLE MAC address and type. Please note that the address format is
-     * least significant byte first (LSB). Please refer to Address_t.
+     * LSB (least significant byte first). Please refer to Address_t.
      *
      * @return BLE_ERROR_NONE on success.
      */
@@ -175,7 +170,7 @@
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)typeP;
         (void)address;
 
@@ -235,7 +230,7 @@
                                 Gap::AddressType_t        peerAddrType,
                                 const ConnectionParams_t *connectionParams,
                                 const GapScanningParams  *scanParams) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)peerAddr;
         (void)peerAddrType;
         (void)connectionParams;
@@ -250,7 +245,7 @@
      * disconnectionCallback.
      *
      * @param  reason
-     *           The reason for disconnection; to be sent back to the peer.
+     *           The reason for disconnection to be sent back to the peer.
      */
     virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
         /* avoid compiler warnings about unused variables */
@@ -266,15 +261,15 @@
      * disconnectionCallback.
      *
      * @param  reason
-     *           The reason for disconnection; to be sent back to the peer.
+     *           The reason for disconnection to be sent back to the peer.
      *
-     * @note: This version of disconnect() doesn't take a connection handle. It
-     * works reliably only for stacks that are limited to a single
+     * @note: this version of disconnect() doesn't take a connection handle. It
+     * will work reliably only for stacks which are limited to a single
      * connection. This API should be considered *deprecated* in favour of the
-     * alternative, which takes a connection handle. It will be dropped in the future.
+     * altertive which takes a connection handle. It will be dropped in the future.
      */
     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)reason;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -293,7 +288,7 @@
      * the given structure pointed to by params.
      */
     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)params;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -308,7 +303,7 @@
      *               The structure containing the desired parameters.
      */
     virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)params;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -316,12 +311,12 @@
 
     /**
      * Update connection parameters.
-     * In the central role this will initiate a Link Layer connection parameter update procedure.
-     * In the peripheral role, this will send the corresponding L2CAP request and wait for
+     * In the central role this will initiate a Link Layer connection parameter update procedure,
+     * otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
      * the central to perform the procedure.
      *
      * @param[in] handle
-     *              Connection Handle.
+     *              Connection Handle
      * @param[in] params
      *              Pointer to desired connection parameters. If NULL is provided on a peripheral role,
      *              the parameters in the PPCP characteristic of the GAP service will be used instead.
@@ -340,7 +335,7 @@
      *              The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
      */
     virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)deviceName;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -378,7 +373,7 @@
      *              The new value for the device-appearance.
      */
     virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)appearance;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -390,7 +385,7 @@
      *               The new value for the device-appearance.
      */
     virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)appearanceP;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -401,7 +396,7 @@
      * @param[in] txPower Radio transmit power in dBm.
      */
     virtual ble_error_t setTxPower(int8_t txPower) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)txPower;
 
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -416,7 +411,7 @@
      *                 Out parameter to receive the array's size.
      */
     virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
-        /* Avoid compiler warnings about unused variables. */
+        /* avoid compiler warnings about unused variables */
         (void)valueArrayPP;
         (void)countP;
 
@@ -435,8 +430,8 @@
      */
 public:
     /**
-     * Returns the current GAP state of the device using a bitmask that
-     * describes whether the device is advertising or connected.
+     * Returns the current GAP state of the device using a bitmask which
+     * describes whether the device is advertising and/or connected.
      */
     GapState_t getState(void) const {
         return state;
@@ -461,7 +456,7 @@
      *              to ADV_CONNECTABLE_DIRECTED.
      *
      * @note: Decreasing this value will allow central devices to detect a
-     * peripheral faster, at the expense of more power being used by the radio
+     * peripheral faster at the expense of more power being used by the radio
      * due to the higher data transmit rate.
      *
      * @note: This API is now *deprecated* and will be dropped in the future.
@@ -473,7 +468,7 @@
      * 'interval' argument. That required an explicit conversion from
      * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
      * no longer required as the new units are milliseconds. Any application
-     * code depending on the old semantics needs to be updated accordingly.
+     * code depending on the old semantics would need to be updated accordingly.
      */
     void setAdvertisingInterval(uint16_t interval) {
         if (interval == 0) {
@@ -497,14 +492,17 @@
      * Start advertising.
      */
     ble_error_t startAdvertising(void) {
-        setAdvertisingData(); /* Update the underlying stack. */
+        setAdvertisingData(); /* update the underlying stack */
         return startAdvertising(_advParams);
     }
 
     /**
      * Reset any advertising payload prepared from prior calls to
      * accumulateAdvertisingPayload(). This automatically propagates the re-
-     * initialized advertising payload to the underlying stack.
+     * initialized adv payload to the underlying stack.
+     *
+     * Note: This should be followed by a call to setAdvertisingPayload() or
+     * startAdvertising() before the update takes effect.
      */
     void clearAdvertisingPayload(void) {
         _advPayload.clear();
@@ -514,7 +512,7 @@
     /**
      * Accumulate an AD structure in the advertising payload. Please note that
      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
-     * as an additional 31 bytes if the advertising payload is too
+     * as an additional 31 bytes if the advertising payload proves to be too
      * small.
      *
      * @param[in] flags
@@ -534,7 +532,7 @@
     /**
      * Accumulate an AD structure in the advertising payload. Please note that
      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
-     * as an additional 31 bytes if the advertising payload is too
+     * as an additional 31 bytes if the advertising payload proves to be too
      * small.
      *
      * @param  app
@@ -554,11 +552,12 @@
     /**
      * Accumulate an AD structure in the advertising payload. Please note that
      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
-     * as an additional 31 bytes if the advertising payload is too
+     * as an additional 31 bytes if the advertising payload proves to be too
      * small.
      *
-     * @param  power
+     * @param  app
      *         The max transmit power to be used by the controller (in dBm).
+     *         This is only a hint.
      */
     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
         ble_error_t rc;
@@ -573,11 +572,11 @@
      * Accumulate a variable length byte-stream as an AD structure in the
      * advertising payload. Please note that the payload is limited to 31 bytes.
      * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
-     * advertising payload is too small.
+     * advertising payload proves to be too small.
      *
-     * @param  type The type describing the variable length data.
-     * @param  data Data bytes.
-     * @param  len  Length of data.
+     * @param  type The type which describes the variable length data.
+     * @param  data data bytes.
+     * @param  len  length of data.
      */
     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -597,14 +596,14 @@
      * matching type and length). Note: the length of the new data must be the
      * same as the old one.
      *
-     * @param[in] type  The ADV type field describing the variable length data.
-     * @param[in] data  Data bytes.
-     * @param[in] len   Length of data.
+     * @param[in] type  The ADV type field which describes the variable length data.
+     * @param[in] data  data bytes.
+     * @param[in] len   length of data.
      *
      * @note: If advertisements are enabled, then the update will take effect immediately.
      *
      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
-     *         a <type, len> match; otherwise, an appropriate error.
+     *         a <type, len> match; else an appropriate error.
      */
     ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -620,7 +619,7 @@
     }
 
     /**
-     * Set up a particular, user-constructed advertisement payload for the
+     * Setup a particular, user-constructed advertisement payload for the
      * underlying stack. It would be uncommon for this API to be used directly;
      * there are other APIs to build an advertisement payload (see above).
      */
@@ -641,9 +640,9 @@
      * Accumulate a variable length byte-stream as an AD structure in the
      * scanResponse payload.
      *
-     * @param[in] type The type describing the variable length data.
-     * @param[in] data Data bytes.
-     * @param[in] len  Length of data.
+     * @param[in] type The type which describes the variable length data.
+     * @param[in] data data bytes.
+     * @param[in] len  length of data.
      */
     ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         ble_error_t rc;
@@ -667,13 +666,13 @@
     }
 
     /**
-     * Set up parameters for GAP scanning (observer mode).
+     * Setup parameters for GAP scanning--i.e. observer mode.
      * @param[in] interval
      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      * @param[in] window
      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      * @param[in] timeout
-     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
+     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
      * @param[in] activeScanning
      *              Set to True if active-scanning is required. This is used to fetch the
      *              scan response from a peer if possible.
@@ -706,7 +705,7 @@
     }
 
     /**
-     * Set up the scanInterval parameter for GAP scanning (observer mode).
+     * Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
      * @param[in] interval
      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
@@ -725,7 +724,7 @@
     }
 
     /**
-     * Set up the scanWindow parameter for GAP scanning (observer mode).
+     * Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
      * @param[in] window
      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
@@ -757,9 +756,9 @@
     }
 
     /**
-     * Set up parameters for GAP scanning (observer mode).
+     * Setup parameters for GAP scanning--i.e. observer mode.
      * @param[in] timeout
-     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
+     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
      *
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
@@ -782,7 +781,7 @@
     }
 
     /**
-     * Set up parameters for GAP scanning (observer mode).
+     * Setup parameters for GAP scanning--i.e. observer mode.
      * @param[in] activeScanning
      *              Set to True if active-scanning is required. This is used to fetch the
      *              scan response from a peer if possible.
@@ -809,7 +808,7 @@
      * effect.
      *
      * @param[in] callback
-     *              The application-specific callback to be invoked upon
+     *              The application specific callback to be invoked upon
      *              receiving every advertisement report. This can be passed in
      *              as NULL, in which case scanning may not be enabled at all.
      */
@@ -843,17 +842,17 @@
 
     /**
      * Initialize radio-notification events to be generated from the stack.
-     * This API doesn't need to be called directly.
+     * This API doesn't need to be called directly;
      *
      * Radio Notification is a feature that enables ACTIVE and INACTIVE
      * (nACTIVE) signals from the stack that notify the application when the
      * radio is in use.
      *
-     * The ACTIVE signal is sent before the radio event starts. The nACTIVE
-     * signal is sent at the end of the radio event. These signals can be used
+     * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
+     * signal is sent at the end of the Radio Event. These signals can be used
      * by the application programmer to synchronize application logic with radio
      * activity. For example, the ACTIVE signal can be used to shut off external
-     * devices, to manage peak current drawn during periods when the radio is on,
+     * devices to manage peak current drawn during periods when the radio is on,
      * or to trigger sensor data collection for transmission in the Radio Event.
      *
      * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
@@ -883,7 +882,7 @@
     }
 
     /**
-     * Set up a particular, user-constructed set of advertisement parameters for
+     * Setup a particular, user-constructed set of advertisement parameters for
      * the underlying stack. It would be uncommon for this API to be used
      * directly; there are other APIs to tweak advertisement parameters
      * individually.
@@ -895,16 +894,10 @@
     /* Event callback handlers. */
 public:
     /**
-     * Set up a callback for timeout events. Refer to TimeoutSource_t for
+     * Setup a callback for timeout events. Refer to TimeoutSource_t for
      * possible event types.
      */
-    void onTimeout(TimeoutEventCallback_t callback) {
-        timeoutCallbackChain.add(callback);
-    }
-
-    TimeoutEventCallbackChain_t& onTimeout() {
-        return timeoutCallbackChain;
-    }
+    void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
 
     /**
      * Append to a chain of callbacks to be invoked upon GAP connection.
@@ -914,10 +907,6 @@
     template<typename T>
     void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
 
-    ConnectionEventCallbackChain_t& onconnection() { 
-        return connectionCallChain;
-    }
-
     /**
      * Append to a chain of callbacks to be invoked upon GAP disconnection.
      */
@@ -926,10 +915,6 @@
     template<typename T>
     void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
 
-    DisconnectionEventCallbackChain_t& onDisconnection() {
-        return disconnectionCallChain;
-    }
-
     /**
      * Set the application callback for radio-notification events.
      *
@@ -937,18 +922,18 @@
      * (nACTIVE) signals from the stack that notify the application when the
      * radio is in use.
      *
-     * The ACTIVE signal is sent before the radio event starts. The nACTIVE
-     * signal is sent at the end of the radio event. These signals can be used
+     * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
+     * signal is sent at the end of the Radio Event. These signals can be used
      * by the application programmer to synchronize application logic with radio
      * activity. For example, the ACTIVE signal can be used to shut off external
-     * devices, to manage peak current drawn during periods when the radio is on,
+     * devices to manage peak current drawn during periods when the radio is on,
      * or to trigger sensor data collection for transmission in the Radio Event.
      *
      * @param callback
      *          The application handler to be invoked in response to a radio
      *          ACTIVE/INACTIVE event.
      *
-     * Or in the other version:
+     * or in the other version:
      *
      * @param tptr
      *          Pointer to the object of a class defining the member callback
@@ -959,14 +944,11 @@
      */
     void onRadioNotification(void (*callback)(bool param)) {
         radioNotificationCallback.attach(callback);
-        // why does it start radio notification ? It is not even indicated in the 
-        // doc that it start the listening process
         initRadioNotification();
     }
     template <typename T>
     void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
         radioNotificationCallback.attach(tptr, mptr);
-        // why does it start radio notification ?
         initRadioNotification();
     }
 
@@ -978,7 +960,7 @@
         _scanResponse(),
         state(),
         scanningActive(false),
-        timeoutCallbackChain(),
+        timeoutCallback(NULL),
         radioNotificationCallback(),
         onAdvertisementReport(),
         connectionCallChain(),
@@ -1024,8 +1006,8 @@
     }
 
     void processTimeoutEvent(TimeoutSource_t source) {
-        if (timeoutCallbackChain) {
-            timeoutCallbackChain(source);
+        if (timeoutCallback) {
+            timeoutCallback(source);
         }
     }
 
@@ -1039,14 +1021,14 @@
     bool                             scanningActive;
 
 protected:
-    TimeoutEventCallbackChain_t       timeoutCallbackChain;
-    RadioNotificationEventCallback_t  radioNotificationCallback;
-    AdvertisementReportCallback_t     onAdvertisementReport;
-    ConnectionEventCallbackChain_t    connectionCallChain;
-    DisconnectionEventCallbackChain_t disconnectionCallChain;
+    TimeoutEventCallback_t           timeoutCallback;
+    RadioNotificationEventCallback_t radioNotificationCallback;
+    AdvertisementReportCallback_t    onAdvertisementReport;
+    CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t*>    connectionCallChain;
+    CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
 
 private:
-    /* Disallow copy and assignment. */
+    /* disallow copy and assignment */
     Gap(const Gap &);
     Gap& operator=(const Gap &);
 };