Mbed OS Reference | BLEInstanceBase.h Source File

Go to the documentation of this file.
 /* 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.
  */
 
 /**
  * @file
  */
 
 #ifndef MBED_BLE_DEVICE_INSTANCE_BASE__
 #define MBED_BLE_DEVICE_INSTANCE_BASE__
 
 #include "ble/BLE.h"
 #include "ble/Gap.h"
 #include "ble/SecurityManager.h"
 #include "ble/GattServer.h"
 #include "ble/GattClient.h"
 
 
 
 /**
  * @addtogroup ble
  * @{
  * @addtogroup porting
  * @{
  */
 
 /**
  * Private interface used to implement the BLE class.
  *
  * The BLE class delegates all its abstract operations to an instance of this
  * abstract class, which every vendor port of Mbed BLE shall implement.
  *
  * The vendor port shall also define an implementation of the freestanding function
  * createBLEInstance(). The BLE API uses this singleton function to gain
  * access to a concrete implementation of this class defined in the vendor port.
  *
  * @attention This class is part of the porting API and is not meant to be used
  * by end users of BLE API.
  *
  * @see BLE
  */
 class BLEInstanceBase
 {
 public:
     /**
      * Base constructor.
      */
     BLEInstanceBase() {}
 
     /**
      * Virtual destructor of the interface.
      */
     virtual ~BLEInstanceBase();
 
     /**
      * Process ALL pending events living in the vendor BLE subsystem.
      *
      * Return once all pending events have been consumed.
      *
      * @see BLE::processEvents()
      */
     virtual void processEvents() = 0;
 
     /**
      * Signal to BLE that events needing processing are available.
      *
      * The vendor port shall call this function whenever there are events
      * ready to be processed in the internal stack or BLE subsystem. As a result
      * of this call, the callback registered by the end user via
      * BLE::onEventsToProcess will be invoked.
      *
      * @param[in] id: Identifier of the BLE instance, which does have events to
      * ready to be processed.
      */
     void signalEventsToProcess(BLE::InstanceID_t id);
 
     /**
      * Start the initialization of the vendor BLE subsystem.
      *
      * Calls to this function are initiated by BLE::init, instanceID identify
      * the BLE instance which issue that call while the initCallback is used to
      * signal asynchronously the completion of the initialization process.
      *
      * @param[in] instanceID Identifier of the BLE instance requesting
      * initialization.
      * @param[in] initCallback Callback which the vendor port shall invoke
      * when the initialization completes.
      *
      * This is an optional parameter set to NULL when not supplied.
      *
      * @return BLE_ERROR_NONE if the initialization procedure started
      * successfully.
      *
      * @post initCallback shall be invoked upon completion of the initialization
      * process.
      *
      * @post hasInitialized() shall return false until the initialization is
      * complete, and it shall return true after succesful completion of the
      * initialization process.
      *
      * @see BLE::init()
      */
     virtual ble_error_t init(
         BLE::InstanceID_t instanceID,
         FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext*> initCallback
     ) = 0;
 
     /**
      * Check whether the vendor BLE subsystem has been initialized or not.
      *
      * @return true if the initialization has completed for the vendor BLE
      * subsystem.
      *
      * @note this function is invoked by BLE::hasInitialized()
      *
      * @see BLE::init() BLE::hasInitialized()
      */
     virtual bool hasInitialized(void) const = 0;
 
     /**
      * Shutdown the vendor BLE subsystem.
      *
      * This operation includes purging the stack of GATT and GAP state and
      * clearing all state from other BLE components, such as the SecurityManager.
      * Clearing all states may be realized by a call to Gap::reset(),
      * GattClient::reset(), GattServer::reset() and SecurityManager::reset().
      *
      * BLE::init() must be called afterward to reinstantiate services and GAP
      * state.
      *
      * @return BLE_ERROR_NONE if the underlying stack and all other services of
      * the BLE API were shut down correctly.
      *
      * @post hasInitialized() shall return false.
      *
      * @note This function is invoked by BLE::shutdown().
      *
      * @see BLE::shutdown() BLE::init() BLE::hasInitialized() Gap::reset()
      * GattClient::reset() GattServer::reset() SecurityManager::reset() .
      */
     virtual ble_error_t shutdown(void) = 0;
 
     /**
      * Fetches a NULL terminated string representation of the underlying BLE
      * vendor subsystem.
      *
      * @return A pointer to the NULL terminated string representation of the
      * underlying BLE stack's version.
      *
      * @see BLE::getVersion()
      */
     virtual const char *getVersion(void) = 0;
 
     /**
      * Accessor to the vendor implementation of the Gap interface.
      *
      * @return A reference to a Gap object associated to this BLEInstanceBase
      * instance.
      *
      * @see BLE::gap() Gap
      */
     virtual Gap &getGap(void) = 0;
 
     /**
      * Const alternative to getGap().
      *
      * @return A const reference to a Gap object associated to this
      * BLEInstanceBase instance.
      *
      * @see BLE::gap() Gap
      */
     virtual const Gap &getGap(void) const = 0;
 
 
 #if BLE_FEATURE_GATT_SERVER
     /**
      * Accessor to the vendor implementation of the GattServer interface.
      *
      * @return A reference to a GattServer object associated to this
      * BLEInstanceBase instance.
      *
      * @see BLE::gattServer() GattServer
      */
     virtual GattServer &getGattServer(void) = 0;
 
     /**
      * A const alternative to getGattServer().
      *
      * @return A const reference to a GattServer object associated to this
      * BLEInstanceBase instance.
      *
      * @see BLE::gattServer() GattServer
      */
     virtual const GattServer &getGattServer(void) const = 0;
 #endif // BLE_FEATURE_GATT_SERVER
 
 #if BLE_FEATURE_GATT_CLIENT
     /**
      * Accessor to the vendor implementation of the GattClient interface.
      *
      * @return A reference to a GattClient object associated to this
      * BLEInstanceBase instance.
      *
      * @see BLE::gattClient() GattClient
      */
     virtual GattClient &getGattClient(void) = 0;
 #endif
 
 #if BLE_FEATURE_SECURITY
     /**
      * Accessor to the vendor implementation of the SecurityManager interface.
      *
      * @return A reference to a SecurityManager object associated to this
      * BLEInstanceBase instance.
      *
      * @see BLE::securityManager() SecurityManager
      */
     virtual SecurityManager &getSecurityManager(void) = 0;
 
     /**
      * A const alternative to getSecurityManager().
      *
      * @return A const reference to a SecurityManager object associated to this
      * BLEInstancebase instance.
      *
      * @see BLE::securityManager() SecurityManager
      */
     virtual const SecurityManager &getSecurityManager(void) const = 0;
 #endif // BLE_FEATURE_SECURITY
 
     /**
      * Process pending events present in the vendor subsystem; then, put the MCU
      * to sleep until an external source wakes it up.
      *
      * @attention This function is deprecated in the BLE class. It will be
      * removed from this interface once it is removed from BLE.
      *
      * @see BLE::waitForEvent() BLE::processEvents()
      */
     virtual void waitForEvent(void) = 0;
 
 private:
     // this class is not a value type.
     // prohibit copy construction and copy assignement
     BLEInstanceBase(const BLEInstanceBase&);
     BLEInstanceBase &operator=(const BLEInstanceBase&);
 };
 
 /**
  * Return the instance of the vendor implementation of BLEInstanceBase.
  *
  * @attention Contrary to its name, this function does not return a new instance
  * at each call. It rather acts like an accessor to a singleton.
  *
  * @attention The vendor library must provide an implementation for this function
  * library. Otherwise, there will be a linker error.
  */
 extern BLEInstanceBase *createBLEInstance(void);
 
 /**
  * @}
  * @}
  */
 
 #endif // ifndef MBED_BLE_DEVICE_INSTANCE_BASE__
Important Information for this Arm website
