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 #ifndef __BLE_DEVICE_INSTANCE_BASE__
00018 #define __BLE_DEVICE_INSTANCE_BASE__
00019 
00020 #include "Gap.h"
00021 #include "ble/SecurityManager.h"
00022 #include "ble/BLE.h"
00023 
00024 /* Forward declarations. */
00025 class GattServer;
00026 class GattClient;
00027 
00028 /**
00029  *  The interface for the transport object to be created by the target library's
00030  *  createBLEInstance().
00031  *
00032  * @note This class is part of the interface of BLE API with the implementation;
00033  *       therefore, it is meant to be used only by porters rather than normal
00034  *       BLE API users.
00035  */
00036 class BLEInstanceBase
00037 {
00038 public:
00039     BLEInstanceBase() {}
00040 
00041     /**
00042      * Virtual destructor of the interface.
00043      */
00044     virtual ~BLEInstanceBase();
00045 
00046     /**
00047      * Initialize the underlying BLE stack. This should be called before
00048      * anything else in the BLE API.
00049      *
00050      * @param[in] instanceID
00051      *              The ID of the instance to initialize.
00052      * @param[in] initCallback
00053      *              A callback for when initialization completes for a BLE
00054      *              instance. This is an optional parameter set to NULL when not
00055      *              supplied.
00056      *
00057      * @return BLE_ERROR_NONE if the initialization procedure was started
00058      *         successfully.
00059      */
00060     virtual ble_error_t            init(BLE::InstanceID_t instanceID,
00061                                         FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
00062 
00063     /**
00064      * Check whether the underlying stack has already been initialized,
00065      * possible with a call to init().
00066      *
00067      * @return true if the initialization has completed for the underlying BLE
00068      *         stack.
00069      */
00070     virtual bool                   hasInitialized(void) const = 0;
00071 
00072     /**
00073      * Shutdown the underlying BLE stack. This includes purging the stack of
00074      * GATT and GAP state and clearing all state from other BLE components
00075      * such as the SecurityManager. init() must be called afterwards to
00076      * re-instantiate services and GAP state.
00077      *
00078      * @return BLE_ERROR_NONE if the underlying stack and all other services of
00079      *         the BLE API were shutdown correctly.
00080      */
00081     virtual ble_error_t            shutdown(void)             = 0;
00082 
00083     /**
00084      * Fetches a string representation of the underlying BLE stack's version.
00085      *
00086      * @return A pointer to the string representation of the underlying
00087      *         BLE stack's version.
00088      */
00089     virtual const char *           getVersion(void)           = 0;
00090 
00091     /**
00092      * Accessor to Gap. This function is used by BLE::gap().
00093      *
00094      * @return A reference to a Gap object associated to this BLE instance.
00095      */
00096     virtual Gap&                   getGap()                   = 0;
00097 
00098     /**
00099      * A const alternative to getGap().
00100      *
00101      * @return A const reference to a Gap object associated to this BLE instance.
00102      */
00103     virtual const Gap&             getGap() const             = 0;
00104 
00105     /**
00106      * Accessor to GattServer. This function is used by BLE::gattServer().
00107      *
00108      * @return A reference to a GattServer object associated to this BLE instance.
00109      */
00110     virtual GattServer&            getGattServer()            = 0;
00111 
00112     /**
00113      * A const alternative to getGattServer().
00114      *
00115      * @return A const reference to a GattServer object associated to this BLE instance.
00116      */
00117     virtual const GattServer&      getGattServer() const      = 0;
00118 
00119     /**
00120      * Accessors to GattClient. This function is used by BLE::gattClient().
00121      *
00122      * @return A reference to a GattClient object associated to this BLE instance.
00123      */
00124     virtual GattClient&            getGattClient()            = 0;
00125 
00126     /**
00127      * Accessors to SecurityManager. This function is used by BLE::securityManager().
00128      *
00129      * @return A reference to a SecurityManager object associated to this BLE instance.
00130      */
00131     virtual SecurityManager&       getSecurityManager()       = 0;
00132 
00133     /**
00134      * A const alternative to getSecurityManager().
00135      *
00136      * @return A const reference to a SecurityManager object associated to this BLE instance.
00137      */
00138     virtual const SecurityManager& getSecurityManager() const = 0;
00139 
00140     /**
00141      * Yield control to the BLE stack or to other tasks waiting for events.
00142      * refer to BLE::waitForEvent().
00143      */
00144     virtual void                   waitForEvent(void)         = 0;
00145 
00146     /**
00147      * Process ALL pending events living in the BLE stack .
00148      * Return once all events have been consumed.
00149      */
00150     virtual void processEvents() = 0;
00151 
00152     /**
00153      * This function allow the BLE stack to signal that their is work to do and
00154      * event processing should be done (BLE::processEvent()).
00155      * @param id: The ID of the BLE instance which does have events to process.
00156      */
00157     void signalEventsToProcess(BLE::InstanceID_t id);
00158 
00159 private:
00160     // this class is not a value type.
00161     // prohibit copy construction and copy assignement
00162     BLEInstanceBase(const BLEInstanceBase&);
00163     BLEInstanceBase& operator=(const BLEInstanceBase&);
00164 };
00165 
00166 /**
00167  * BLE uses composition to hide an interface object encapsulating the
00168  * backend transport.
00169  *
00170  * The following API is used to create the singleton interface object. An
00171  * implementation for this function must be provided by the device-specific
00172  * library, otherwise there will be a linker error.
00173  */
00174 extern BLEInstanceBase *createBLEInstance(void);
00175 
00176 #endif // ifndef __BLE_DEVICE_INSTANCE_BASE__