Diff: ble/Gap.h

Revision:

913:690bea02c431

Parent:

912:f728aa46e7df

Child:

919:c5b9fac295f5

--- a/ble/Gap.h	Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/Gap.h	Thu Nov 26 12:52:03 2015 +0000
@@ -24,7 +24,7 @@
 #include "CallChainOfFunctionPointersWithContext.h"
 #include "FunctionPointerWithContext.h"
 
-/* Forward declarations for classes which will only be used for pointers or references in the following. */
+/* Forward declarations for classes that 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 which is not
-     * covered by this enumeration, then 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 that is not
+     * covered by this enumeration, 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. */
@@ -152,7 +152,7 @@
 public:
     /**
      * Set the BTLE MAC address and type. Please note that the address format is
-     * LSB (least significant byte first). Please refer to Address_t.
+     * least significant byte first (LSB). Please refer to Address_t.
      *
      * @return BLE_ERROR_NONE on success.
      */
@@ -170,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;
 
@@ -230,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;
@@ -245,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 */
@@ -261,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
-     * will work reliably only for stacks which are limited to a single
+     * @note: This version of disconnect() doesn't take a connection handle. It
+     * works reliably only for stacks that are limited to a single
      * connection. This API should be considered *deprecated* in favour of the
-     * altertive which takes a connection handle. It will be dropped in the future.
+     * alternative, 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. */
@@ -288,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. */
@@ -303,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. */
@@ -311,12 +311,12 @@
 
     /**
      * Update connection parameters.
-     * 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
+     * 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
      * 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.
@@ -335,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. */
@@ -373,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. */
@@ -385,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. */
@@ -396,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. */
@@ -411,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;
 
@@ -430,8 +430,8 @@
      */
 public:
     /**
-     * Returns the current GAP state of the device using a bitmask which
-     * describes whether the device is advertising and/or connected.
+     * Returns the current GAP state of the device using a bitmask that
+     * describes whether the device is advertising or connected.
      */
     GapState_t getState(void) const {
         return state;
@@ -456,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.
@@ -468,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 would need to be updated accordingly.
+     * code depending on the old semantics needs to be updated accordingly.
      */
     void setAdvertisingInterval(uint16_t interval) {
         if (interval == 0) {
@@ -492,14 +492,14 @@
      * 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 adv payload to the underlying stack.
+     * initialized advertising payload to the underlying stack.
      */
     void clearAdvertisingPayload(void) {
         _advPayload.clear();
@@ -509,7 +509,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 proves to be too
+     * as an additional 31 bytes if the advertising payload is too
      * small.
      *
      * @param[in] flags
@@ -529,7 +529,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 proves to be too
+     * as an additional 31 bytes if the advertising payload is too
      * small.
      *
      * @param  app
@@ -549,7 +549,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 proves to be too
+     * as an additional 31 bytes if the advertising payload is too
      * small.
      *
      * @param  power
@@ -568,11 +568,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 proves to be too small.
+     * advertising payload is too small.
      *
-     * @param  type The type which describes the variable length data.
-     * @param  data data bytes.
-     * @param  len  length of data.
+     * @param  type The type describing 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) {
@@ -592,14 +592,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 which describes the variable length data.
-     * @param[in] data  data bytes.
-     * @param[in] len   length of data.
+     * @param[in] type  The ADV type field describing 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; else an appropriate error.
+     *         a <type, len> match; otherwise, an appropriate error.
      */
     ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -615,7 +615,7 @@
     }
 
     /**
-     * Setup a particular, user-constructed advertisement payload for the
+     * Set up 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).
      */
@@ -636,9 +636,9 @@
      * Accumulate a variable length byte-stream as an AD structure in the
      * scanResponse payload.
      *
-     * @param[in] type The type which describes the variable length data.
-     * @param[in] data data bytes.
-     * @param[in] len  length of data.
+     * @param[in] type The type describing 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;
@@ -662,13 +662,13 @@
     }
 
     /**
-     * Setup parameters for GAP scanning--i.e. observer mode.
+     * Set up parameters for GAP scanning (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 timeout.
+     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the 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.
@@ -701,7 +701,7 @@
     }
 
     /**
-     * Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
+     * Set up the scanInterval parameter for GAP scanning (observer mode).
      * @param[in] interval
      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
@@ -720,7 +720,7 @@
     }
 
     /**
-     * Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
+     * Set up the scanWindow parameter for GAP scanning (observer mode).
      * @param[in] window
      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
@@ -752,9 +752,9 @@
     }
 
     /**
-     * Setup parameters for GAP scanning--i.e. observer mode.
+     * Set up parameters for GAP scanning (observer mode).
      * @param[in] timeout
-     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
+     *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
      *
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
@@ -777,7 +777,7 @@
     }
 
     /**
-     * Setup parameters for GAP scanning--i.e. observer mode.
+     * Set up parameters for GAP scanning (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.
@@ -804,7 +804,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.
      */
@@ -838,17 +838,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.
@@ -878,7 +878,7 @@
     }
 
     /**
-     * Setup a particular, user-constructed set of advertisement parameters for
+     * Set up 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.
@@ -890,7 +890,7 @@
     /* Event callback handlers. */
 public:
     /**
-     * Setup a callback for timeout events. Refer to TimeoutSource_t for
+     * Set up a callback for timeout events. Refer to TimeoutSource_t for
      * possible event types.
      */
     void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
@@ -918,18 +918,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
@@ -1024,7 +1024,7 @@
     CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
 
 private:
-    /* disallow copy and assignment */
+    /* Disallow copy and assignment. */
     Gap(const Gap &);
     Gap& operator=(const Gap &);
 };