Add missing documentation to btle_security for whitelisting

source/btle/btle_security.h

@@ -20,6 +20,15 @@
 #include "ble/Gap.h"
 #include "ble/SecurityManager.h"
 
+/**
+ * Function to test whether the SecurityManager has been initialized.
+ * Possible by a call to @ref btle_initializeSecurity().
+ *
+ * @return True if the SecurityManager was previously initialized, false
+ *         otherwise.
+ */
+bool btle_hasInitializedSecurity(void);
+
 /**
  * Enable Nordic's Device Manager, which brings in functionality from the
  * stack's Security Manager. The Security Manager implements the actual
@@ -40,8 +49,6 @@ ble_error_t btle_initializeSecurity(bool                                      en
                                     SecurityManager::SecurityIOCapabilities_t iocaps        = SecurityManager::IO_CAPS_NONE,
                                     const SecurityManager::Passkey_t          passkey       = NULL);
 
-ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist);
-
 /**
  * Get the security status of a link.
  *
@@ -78,13 +85,19 @@ ble_error_t btle_setLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager
 ble_error_t btle_purgeAllBondingState(void);
 
 /**
- * Function to test whether the SecurityManager has been initialized.
- * Possible by a call to @ref btle_initializeSecurity().
+ * Query the SoftDevice bond table to extract a whitelist containing the BLE
+ * addresses and IRKs of bonded devices.
  *
- * @return True if the SecurityManager was previously initialized, false
- *         otherwise.
+ * @param[in/out]  p_whitelist
+ *                  (on input) p_whitelist->addr_count and
+ *                  p_whitelist->irk_count specify the maximum number of
+ *                  addresses and IRKs added to the whitelist structure.
+ *                  (on output) *p_whitelist is a whitelist containing the
+ *                  addresses and IRKs of the bonded devices.
+ *
+ * @return BLE_ERROR_NONE Or appropriate error code indicating reason for failure.
  */
-bool btle_hasInitializedSecurity(void);
+ble_error_t btle_createWhitelistFromBondTable(ble_gap_whitelist_t *p_whitelist);
 
 /**
  * Function to test whether a BLE address is generated using an IRK.

source/nRF5xGap.cpp

@@ -642,6 +642,48 @@ Gap::InitiatorPolicyMode_t nRF5xGap::getInitiatorPolicyMode(void) const
     return Gap::INIT_POLICY_IGNORE_WHITELIST;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Helper function used to populate the ble_gap_whitelist_t that
+            will be used by the SoftDevice for filtering requests.
+
+    @param[in]  params
+                Basic advertising details, including the advertising
+                delay, timeout and how the device should be advertised
+    @params[in] advData
+                The primary advertising data payload
+    @params[in] scanResponse
+                The optional Scan Response payload if the advertising
+                type is set to \ref GapAdvertisingParams::ADV_SCANNABLE_UNDIRECTED
+                in \ref GapAdveritinngParams
+
+    @returns    \ref ble_error_t
+
+    @retval     BLE_ERROR_NONE
+                Everything executed properly
+
+    @retval     BLE_ERROR_BUFFER_OVERFLOW
+                The proposed action would cause a buffer overflow.  All
+                advertising payloads must be <= 31 bytes, for example.
+
+    @retval     BLE_ERROR_NOT_IMPLEMENTED
+                A feature was requested that is not yet supported in the
+                nRF51 firmware or hardware.
+
+    @retval     BLE_ERROR_PARAM_OUT_OF_RANGE
+                One of the proposed values is outside the valid range.
+
+    @note  This function is needed because for the BLE API the whitelist
+           is just a collection of keys, but for the stack it also includes
+           the IRK table.
+
+    @section EXAMPLE
+
+    @code
+
+    @endcode
+*/
+/**************************************************************************/
 ble_error_t nRF5xGap::generateStackWhitelist(void)
 {
     ble_gap_whitelist_t  whitelistFromBondTable;

source/nRF5xGap.h

@@ -92,6 +92,10 @@ public:
 
     virtual ble_error_t reset(void);
 
+    /*
+     * The following functions are part of the whitelisting experimental API.
+     * Therefore, this functionality can change in the near future.
+     */
     virtual uint8_t getMaxWhitelistSize(void) const;
     virtual ble_error_t getWhitelist(Gap::Whitelist_t &whitelistOut) const;
     virtual ble_error_t setWhitelist(const Gap::Whitelist_t &whitelistIn);
@@ -118,6 +122,10 @@ public:
 #endif
 
 private:
+    /*
+     * Whitelisting API related structures and helper functions.
+     */
+
     /* Policy modes set by the user. By default these are set to ignore the whitelist */
     Gap::AdvertisingPolicyMode_t advertisingPolicyMode;
     Gap::ScanningPolicyMode_t    scanningPolicyMode;
@@ -139,6 +147,7 @@ private:
      */
     ble_error_t generateStackWhitelist(void);
 
+private:
     bool    radioNotificationCallbackParam; /* parameter to be passed into the Timeout-generated radio notification callback. */
     Timeout radioNotificationTimeout;