Diff: ble/BLEInstanceBase.h

Branch:

2f55eed1fdde06fdabfb66d41ce6cd14e280978f

Revision:

1201:9b71aac42d14

Parent:

1183:1589830dbdb7

--- a/ble/BLEInstanceBase.h	Wed Apr 06 19:16:08 2016 +0100
+++ b/ble/BLEInstanceBase.h	Wed Sep 14 14:17:52 2016 +0100
@@ -1,150 +1,176 @@
-/* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-#ifndef __BLE_DEVICE_INSTANCE_BASE__
-#define __BLE_DEVICE_INSTANCE_BASE__
-
-#include "Gap.h"
-#include "ble/SecurityManager.h"
-#include "ble/BLE.h"
-
-/* Forward declarations. */
-class GattServer;
-class GattClient;
-
-/**
- *  The interface for the transport object to be created by the target library's
- *  createBLEInstance().
- *
- * @note This class is part of the interface of BLE API with the implementation;
- *       therefore, it is meant to be used only by porters rather than normal
- *       BLE API users.
- */
-class BLEInstanceBase
-{
-public:
-    /**
-     * Initialize the underlying BLE stack. This should be called before
-     * anything else in the BLE API.
-     *
-     * @param[in] instanceID
-     *              The ID of the instance to initialize.
-     * @param[in] initCallback
-     *              A callback for when initialization completes for a BLE
-     *              instance. This is an optional parameter set to NULL when not
-     *              supplied.
-     *
-     * @return BLE_ERROR_NONE if the initialization procedure was started
-     *         successfully.
-     */
-    virtual ble_error_t            init(BLE::InstanceID_t instanceID,
-                                        FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
-
-    /**
-     * Check whether the underlying stack has already been initialized,
-     * possible with a call to init().
-     *
-     * @return true if the initialization has completed for the underlying BLE
-     *         stack.
-     */
-    virtual bool                   hasInitialized(void) const = 0;
-
-    /**
-     * Shutdown the underlying BLE stack. This includes purging the stack of
-     * GATT and GAP state and clearing all state from other BLE components
-     * such as the SecurityManager. init() must be called afterwards to
-     * re-instantiate services and GAP state.
-     *
-     * @return BLE_ERROR_NONE if the underlying stack and all other services of
-     *         the BLE API were shutdown correctly.
-     */
-    virtual ble_error_t            shutdown(void)             = 0;
-
-    /**
-     * Fetches a string representation of the underlying BLE stack's version.
-     *
-     * @return A pointer to the string representation of the underlying
-     *         BLE stack's version.
-     */
-    virtual const char *           getVersion(void)           = 0;
-
-    /**
-     * Accessor to Gap. This function is used by BLE::gap().
-     *
-     * @return A reference to a Gap object associated to this BLE instance.
-     */
-    virtual Gap&                   getGap()                   = 0;
-
-    /**
-     * A const alternative to getGap().
-     *
-     * @return A const reference to a Gap object associated to this BLE instance.
-     */
-    virtual const Gap&             getGap() const             = 0;
-
-    /**
-     * Accessor to GattServer. This function is used by BLE::gattServer().
-     *
-     * @return A reference to a GattServer object associated to this BLE instance.
-     */
-    virtual GattServer&            getGattServer()            = 0;
-
-    /**
-     * A const alternative to getGattServer().
-     *
-     * @return A const reference to a GattServer object associated to this BLE instance.
-     */
-    virtual const GattServer&      getGattServer() const      = 0;
-
-    /**
-     * Accessors to GattClient. This function is used by BLE::gattClient().
-     *
-     * @return A reference to a GattClient object associated to this BLE instance.
-     */
-    virtual GattClient&            getGattClient()            = 0;
-
-    /**
-     * Accessors to SecurityManager. This function is used by BLE::securityManager().
-     *
-     * @return A reference to a SecurityManager object associated to this BLE instance.
-     */
-    virtual SecurityManager&       getSecurityManager()       = 0;
-
-    /**
-     * A const alternative to getSecurityManager().
-     *
-     * @return A const reference to a SecurityManager object associated to this BLE instance.
-     */
-    virtual const SecurityManager& getSecurityManager() const = 0;
-
-    /**
-     * Yield control to the BLE stack or to other tasks waiting for events.
-     * refer to BLE::waitForEvent().
-     */
-    virtual void                   waitForEvent(void)         = 0;
-};
-
-/**
- * BLE uses composition to hide an interface object encapsulating the
- * backend transport.
- *
- * The following API is used to create the singleton interface object. An
- * implementation for this function must be provided by the device-specific
- * library, otherwise there will be a linker error.
- */
-extern BLEInstanceBase *createBLEInstance(void);
-
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __BLE_DEVICE_INSTANCE_BASE__
+#define __BLE_DEVICE_INSTANCE_BASE__
+
+#include "Gap.h"
+#include "ble/SecurityManager.h"
+#include "ble/BLE.h"
+
+/* Forward declarations. */
+class GattServer;
+class GattClient;
+
+/**
+ *  The interface for the transport object to be created by the target library's
+ *  createBLEInstance().
+ *
+ * @note This class is part of the interface of BLE API with the implementation;
+ *       therefore, it is meant to be used only by porters rather than normal
+ *       BLE API users.
+ */
+class BLEInstanceBase
+{
+public:
+    BLEInstanceBase() {}
+
+    /**
+     * Virtual destructor of the interface.
+     */
+    virtual ~BLEInstanceBase();
+
+    /**
+     * Initialize the underlying BLE stack. This should be called before
+     * anything else in the BLE API.
+     *
+     * @param[in] instanceID
+     *              The ID of the instance to initialize.
+     * @param[in] initCallback
+     *              A callback for when initialization completes for a BLE
+     *              instance. This is an optional parameter set to NULL when not
+     *              supplied.
+     *
+     * @return BLE_ERROR_NONE if the initialization procedure was started
+     *         successfully.
+     */
+    virtual ble_error_t            init(BLE::InstanceID_t instanceID,
+                                        FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
+
+    /**
+     * Check whether the underlying stack has already been initialized,
+     * possible with a call to init().
+     *
+     * @return true if the initialization has completed for the underlying BLE
+     *         stack.
+     */
+    virtual bool                   hasInitialized(void) const = 0;
+
+    /**
+     * Shutdown the underlying BLE stack. This includes purging the stack of
+     * GATT and GAP state and clearing all state from other BLE components
+     * such as the SecurityManager. init() must be called afterwards to
+     * re-instantiate services and GAP state.
+     *
+     * @return BLE_ERROR_NONE if the underlying stack and all other services of
+     *         the BLE API were shutdown correctly.
+     */
+    virtual ble_error_t            shutdown(void)             = 0;
+
+    /**
+     * Fetches a string representation of the underlying BLE stack's version.
+     *
+     * @return A pointer to the string representation of the underlying
+     *         BLE stack's version.
+     */
+    virtual const char *           getVersion(void)           = 0;
+
+    /**
+     * Accessor to Gap. This function is used by BLE::gap().
+     *
+     * @return A reference to a Gap object associated to this BLE instance.
+     */
+    virtual Gap&                   getGap()                   = 0;
+
+    /**
+     * A const alternative to getGap().
+     *
+     * @return A const reference to a Gap object associated to this BLE instance.
+     */
+    virtual const Gap&             getGap() const             = 0;
+
+    /**
+     * Accessor to GattServer. This function is used by BLE::gattServer().
+     *
+     * @return A reference to a GattServer object associated to this BLE instance.
+     */
+    virtual GattServer&            getGattServer()            = 0;
+
+    /**
+     * A const alternative to getGattServer().
+     *
+     * @return A const reference to a GattServer object associated to this BLE instance.
+     */
+    virtual const GattServer&      getGattServer() const      = 0;
+
+    /**
+     * Accessors to GattClient. This function is used by BLE::gattClient().
+     *
+     * @return A reference to a GattClient object associated to this BLE instance.
+     */
+    virtual GattClient&            getGattClient()            = 0;
+
+    /**
+     * Accessors to SecurityManager. This function is used by BLE::securityManager().
+     *
+     * @return A reference to a SecurityManager object associated to this BLE instance.
+     */
+    virtual SecurityManager&       getSecurityManager()       = 0;
+
+    /**
+     * A const alternative to getSecurityManager().
+     *
+     * @return A const reference to a SecurityManager object associated to this BLE instance.
+     */
+    virtual const SecurityManager& getSecurityManager() const = 0;
+
+    /**
+     * Yield control to the BLE stack or to other tasks waiting for events.
+     * refer to BLE::waitForEvent().
+     */
+    virtual void                   waitForEvent(void)         = 0;
+
+    /**
+     * Process ALL pending events living in the BLE stack .
+     * Return once all events have been consumed.
+     */
+    virtual void processEvents() = 0;
+
+    /**
+     * This function allow the BLE stack to signal that their is work to do and
+     * event processing should be done (BLE::processEvent()).
+     * @param id: The ID of the BLE instance which does have events to process.
+     */
+    void signalEventsToProcess(BLE::InstanceID_t id);
+
+private:
+    // this class is not a value type.
+    // prohibit copy construction and copy assignement
+    BLEInstanceBase(const BLEInstanceBase&);
+    BLEInstanceBase& operator=(const BLEInstanceBase&);
+};
+
+/**
+ * BLE uses composition to hide an interface object encapsulating the
+ * backend transport.
+ *
+ * The following API is used to create the singleton interface object. An
+ * implementation for this function must be provided by the device-specific
+ * library, otherwise there will be a linker error.
+ */
+extern BLEInstanceBase *createBLEInstance(void);
+
 #endif // ifndef __BLE_DEVICE_INSTANCE_BASE__
\ No newline at end of file