BLEInstanceBase.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * @file
00019  */
00020 
00021 #ifndef MBED_BLE_DEVICE_INSTANCE_BASE__
00022 #define MBED_BLE_DEVICE_INSTANCE_BASE__
00023 
00024 #include "ble/BLE.h"
00025 #include "ble/Gap.h"
00026 #include "ble/SecurityManager.h"
00027 #include "ble/GattServer.h"
00028 #include "ble/GattClient.h"
00029 
00030 
00031 
00032 /**
00033  * @addtogroup ble
00034  * @{
00035  * @addtogroup porting
00036  * @{
00037  */
00038 
00039 /**
00040  * Private interface used to implement the BLE class.
00041  *
00042  * The BLE class delegates all its abstract operations to an instance of this
00043  * abstract class, which every vendor port of Mbed BLE shall implement.
00044  *
00045  * The vendor port shall also define an implementation of the freestanding function
00046  * createBLEInstance(). The BLE API uses this singleton function to gain
00047  * access to a concrete implementation of this class defined in the vendor port.
00048  *
00049  * @attention This class is part of the porting API and is not meant to be used
00050  * by end users of BLE API.
00051  *
00052  * @see BLE
00053  */
00054 class BLEInstanceBase
00055 {
00056 public:
00057     /**
00058      * Base constructor.
00059      */
00060     BLEInstanceBase() {}
00061 
00062     /**
00063      * Virtual destructor of the interface.
00064      */
00065     virtual ~BLEInstanceBase();
00066 
00067     /**
00068      * Process ALL pending events living in the vendor BLE subsystem.
00069      *
00070      * Return once all pending events have been consumed.
00071      *
00072      * @see BLE::processEvents()
00073      */
00074     virtual void processEvents() = 0;
00075 
00076     /**
00077      * Signal to BLE that events needing processing are available.
00078      *
00079      * The vendor port shall call this function whenever there are events
00080      * ready to be processed in the internal stack or BLE subsystem. As a result
00081      * of this call, the callback registered by the end user via
00082      * BLE::onEventsToProcess will be invoked.
00083      *
00084      * @param[in] id: Identifier of the BLE instance, which does have events to
00085      * ready to be processed.
00086      */
00087     void signalEventsToProcess(BLE::InstanceID_t id);
00088 
00089     /**
00090      * Start the initialization of the vendor BLE subsystem.
00091      *
00092      * Calls to this function are initiated by BLE::init, instanceID identify
00093      * the BLE instance which issue that call while the initCallback is used to
00094      * signal asynchronously the completion of the initialization process.
00095      *
00096      * @param[in] instanceID Identifier of the BLE instance requesting
00097      * initialization.
00098      * @param[in] initCallback Callback which the vendor port shall invoke
00099      * when the initialization completes.
00100      *
00101      * This is an optional parameter set to NULL when not supplied.
00102      *
00103      * @return BLE_ERROR_NONE if the initialization procedure started
00104      * successfully.
00105      *
00106      * @post initCallback shall be invoked upon completion of the initialization
00107      * process.
00108      *
00109      * @post hasInitialized() shall return false until the initialization is
00110      * complete, and it shall return true after succesful completion of the
00111      * initialization process.
00112      *
00113      * @see BLE::init()
00114      */
00115     virtual ble_error_t init(
00116         BLE::InstanceID_t instanceID,
00117         FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext*> initCallback
00118     ) = 0;
00119 
00120     /**
00121      * Check whether the vendor BLE subsystem has been initialized or not.
00122      *
00123      * @return true if the initialization has completed for the vendor BLE
00124      * subsystem.
00125      *
00126      * @note this function is invoked by BLE::hasInitialized()
00127      *
00128      * @see BLE::init() BLE::hasInitialized()
00129      */
00130     virtual bool hasInitialized(void) const = 0;
00131 
00132     /**
00133      * Shutdown the vendor BLE subsystem.
00134      *
00135      * This operation includes purging the stack of GATT and GAP state and
00136      * clearing all state from other BLE components, such as the SecurityManager.
00137      * Clearing all states may be realized by a call to Gap::reset(),
00138      * GattClient::reset(), GattServer::reset() and SecurityManager::reset().
00139      *
00140      * BLE::init() must be called afterward to reinstantiate services and GAP
00141      * state.
00142      *
00143      * @return BLE_ERROR_NONE if the underlying stack and all other services of
00144      * the BLE API were shut down correctly.
00145      *
00146      * @post hasInitialized() shall return false.
00147      *
00148      * @note This function is invoked by BLE::shutdown().
00149      *
00150      * @see BLE::shutdown() BLE::init() BLE::hasInitialized() Gap::reset()
00151      * GattClient::reset() GattServer::reset() SecurityManager::reset() .
00152      */
00153     virtual ble_error_t shutdown(void) = 0;
00154 
00155     /**
00156      * Fetches a NULL terminated string representation of the underlying BLE
00157      * vendor subsystem.
00158      *
00159      * @return A pointer to the NULL terminated string representation of the
00160      * underlying BLE stack's version.
00161      *
00162      * @see BLE::getVersion()
00163      */
00164     virtual const char *getVersion(void) = 0;
00165 
00166     /**
00167      * Accessor to the vendor implementation of the Gap interface.
00168      *
00169      * @return A reference to a Gap object associated to this BLEInstanceBase
00170      * instance.
00171      *
00172      * @see BLE::gap() Gap
00173      */
00174     virtual Gap &getGap(void) = 0;
00175 
00176     /**
00177      * Const alternative to getGap().
00178      *
00179      * @return A const reference to a Gap object associated to this
00180      * BLEInstanceBase instance.
00181      *
00182      * @see BLE::gap() Gap
00183      */
00184     virtual const Gap &getGap(void) const = 0;
00185 
00186 
00187 #if BLE_FEATURE_GATT_SERVER
00188     /**
00189      * Accessor to the vendor implementation of the GattServer interface.
00190      *
00191      * @return A reference to a GattServer object associated to this
00192      * BLEInstanceBase instance.
00193      *
00194      * @see BLE::gattServer() GattServer
00195      */
00196     virtual GattServer &getGattServer(void) = 0;
00197 
00198     /**
00199      * A const alternative to getGattServer().
00200      *
00201      * @return A const reference to a GattServer object associated to this
00202      * BLEInstanceBase instance.
00203      *
00204      * @see BLE::gattServer() GattServer
00205      */
00206     virtual const GattServer &getGattServer(void) const = 0;
00207 #endif // BLE_FEATURE_GATT_SERVER
00208 
00209 #if BLE_FEATURE_GATT_CLIENT
00210     /**
00211      * Accessor to the vendor implementation of the GattClient interface.
00212      *
00213      * @return A reference to a GattClient object associated to this
00214      * BLEInstanceBase instance.
00215      *
00216      * @see BLE::gattClient() GattClient
00217      */
00218     virtual GattClient &getGattClient(void) = 0;
00219 #endif
00220 
00221 #if BLE_FEATURE_SECURITY
00222     /**
00223      * Accessor to the vendor implementation of the SecurityManager interface.
00224      *
00225      * @return A reference to a SecurityManager object associated to this
00226      * BLEInstanceBase instance.
00227      *
00228      * @see BLE::securityManager() SecurityManager
00229      */
00230     virtual SecurityManager &getSecurityManager(void) = 0;
00231 
00232     /**
00233      * A const alternative to getSecurityManager().
00234      *
00235      * @return A const reference to a SecurityManager object associated to this
00236      * BLEInstancebase instance.
00237      *
00238      * @see BLE::securityManager() SecurityManager
00239      */
00240     virtual const SecurityManager &getSecurityManager(void) const = 0;
00241 #endif // BLE_FEATURE_SECURITY
00242 
00243     /**
00244      * Process pending events present in the vendor subsystem; then, put the MCU
00245      * to sleep until an external source wakes it up.
00246      *
00247      * @attention This function is deprecated in the BLE class. It will be
00248      * removed from this interface once it is removed from BLE.
00249      *
00250      * @see BLE::waitForEvent() BLE::processEvents()
00251      */
00252     virtual void waitForEvent(void) = 0;
00253 
00254 private:
00255     // this class is not a value type.
00256     // prohibit copy construction and copy assignement
00257     BLEInstanceBase(const BLEInstanceBase&);
00258     BLEInstanceBase &operator=(const BLEInstanceBase&);
00259 };
00260 
00261 /**
00262  * Return the instance of the vendor implementation of BLEInstanceBase.
00263  *
00264  * @attention Contrary to its name, this function does not return a new instance
00265  * at each call. It rather acts like an accessor to a singleton.
00266  *
00267  * @attention The vendor library must provide an implementation for this function
00268  * library. Otherwise, there will be a linker error.
00269  */
00270 extern BLEInstanceBase *createBLEInstance(void);
00271 
00272 /**
00273  * @}
00274  * @}
00275  */
00276 
00277 #endif // ifndef MBED_BLE_DEVICE_INSTANCE_BASE__