Diff: ble/BLE.h

Revision:

855:98b96c377015

Parent:

854:ad4ae73c2b5a

Child:

857:7f578be2d01d

--- a/ble/BLE.h	Mon Nov 02 09:09:06 2015 +0000
+++ b/ble/BLE.h	Mon Nov 02 09:09:06 2015 +0000
@@ -38,8 +38,19 @@
 class BLE
 {
 public:
-    typedef unsigned InstanceID_t;
-    typedef void (*InitializationCompleteCallback_t)(BLE &bleInstance);
+    typedef unsigned InstanceID_t; /** The type returned by BLE::getInstanceID(). */
+
+    /**
+     * The function signature for callbacks for initialization completion.
+     * @param  ble
+     *             A reference to the BLE instance being initialized.
+     * @param  error
+     *             This captures the result of initialization. It is set to
+     *             BLE_ERROR_NONE if initialization completed successfully. Else
+     *             the error value is implementation specific.
+     *
+     */
+    typedef void (*InitializationCompleteCallback_t)(BLE &ble, ble_error_t error);
 
     /**
      * Initialize the BLE controller. This should be called before using
@@ -61,6 +72,12 @@
      * @return  BLE_ERROR_NONE if the initialization procedure was started
      *     successfully.
      *
+     * @note The underlying stack must invoke the initialization completion
+     *     callback in response to init(). In some cases, initialization is
+     *     instantaneous (or blocking); if so, it is acceptable for the stack-
+     *     specific implementation of init() to invoke the completion callback
+     *     directly--i.e. within its own context.
+     *
      * @note Nearly all BLE APIs would return
      *     BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
      *     corresponding transport is initialized.