Greg Steiert / maxim_dev

Dependents:   sensomed

features/FEATURE_BLE/ble/BLEInstanceBase.h@0:0e018d759a2a, 2016-11-08 (annotated)

Committer:
switches
Date:
Tue Nov 08 18:27:11 2016 +0000
Revision:
0:0e018d759a2a
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
switches 0:0e018d759a2a 1 /* mbed Microcontroller Library
switches 0:0e018d759a2a 2 * Copyright (c) 2006-2013 ARM Limited
switches 0:0e018d759a2a 3 *
switches 0:0e018d759a2a 4 * Licensed under the Apache License, Version 2.0 (the "License");
switches 0:0e018d759a2a 5 * you may not use this file except in compliance with the License.
switches 0:0e018d759a2a 6 * You may obtain a copy of the License at
switches 0:0e018d759a2a 7 *
switches 0:0e018d759a2a 8 * http://www.apache.org/licenses/LICENSE-2.0
switches 0:0e018d759a2a 9 *
switches 0:0e018d759a2a 10 * Unless required by applicable law or agreed to in writing, software
switches 0:0e018d759a2a 11 * distributed under the License is distributed on an "AS IS" BASIS,
switches 0:0e018d759a2a 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
switches 0:0e018d759a2a 13 * See the License for the specific language governing permissions and
switches 0:0e018d759a2a 14 * limitations under the License.
switches 0:0e018d759a2a 15 */
switches 0:0e018d759a2a 16
switches 0:0e018d759a2a 17 #ifndef __BLE_DEVICE_INSTANCE_BASE__
switches 0:0e018d759a2a 18 #define __BLE_DEVICE_INSTANCE_BASE__
switches 0:0e018d759a2a 19
switches 0:0e018d759a2a 20 #include "Gap.h"
switches 0:0e018d759a2a 21 #include "ble/SecurityManager.h"
switches 0:0e018d759a2a 22 #include "ble/BLE.h"
switches 0:0e018d759a2a 23
switches 0:0e018d759a2a 24 /* Forward declarations. */
switches 0:0e018d759a2a 25 class GattServer;
switches 0:0e018d759a2a 26 class GattClient;
switches 0:0e018d759a2a 27
switches 0:0e018d759a2a 28 /**
switches 0:0e018d759a2a 29 * The interface for the transport object to be created by the target library's
switches 0:0e018d759a2a 30 * createBLEInstance().
switches 0:0e018d759a2a 31 *
switches 0:0e018d759a2a 32 * @note This class is part of the interface of BLE API with the implementation;
switches 0:0e018d759a2a 33 * therefore, it is meant to be used only by porters rather than normal
switches 0:0e018d759a2a 34 * BLE API users.
switches 0:0e018d759a2a 35 */
switches 0:0e018d759a2a 36 class BLEInstanceBase
switches 0:0e018d759a2a 37 {
switches 0:0e018d759a2a 38 public:
switches 0:0e018d759a2a 39 BLEInstanceBase() {}
switches 0:0e018d759a2a 40
switches 0:0e018d759a2a 41 /**
switches 0:0e018d759a2a 42 * Virtual destructor of the interface.
switches 0:0e018d759a2a 43 */
switches 0:0e018d759a2a 44 virtual ~BLEInstanceBase();
switches 0:0e018d759a2a 45
switches 0:0e018d759a2a 46 /**
switches 0:0e018d759a2a 47 * Initialize the underlying BLE stack. This should be called before
switches 0:0e018d759a2a 48 * anything else in the BLE API.
switches 0:0e018d759a2a 49 *
switches 0:0e018d759a2a 50 * @param[in] instanceID
switches 0:0e018d759a2a 51 * The ID of the instance to initialize.
switches 0:0e018d759a2a 52 * @param[in] initCallback
switches 0:0e018d759a2a 53 * A callback for when initialization completes for a BLE
switches 0:0e018d759a2a 54 * instance. This is an optional parameter set to NULL when not
switches 0:0e018d759a2a 55 * supplied.
switches 0:0e018d759a2a 56 *
switches 0:0e018d759a2a 57 * @return BLE_ERROR_NONE if the initialization procedure was started
switches 0:0e018d759a2a 58 * successfully.
switches 0:0e018d759a2a 59 */
switches 0:0e018d759a2a 60 virtual ble_error_t init(BLE::InstanceID_t instanceID,
switches 0:0e018d759a2a 61 FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
switches 0:0e018d759a2a 62
switches 0:0e018d759a2a 63 /**
switches 0:0e018d759a2a 64 * Check whether the underlying stack has already been initialized,
switches 0:0e018d759a2a 65 * possible with a call to init().
switches 0:0e018d759a2a 66 *
switches 0:0e018d759a2a 67 * @return true if the initialization has completed for the underlying BLE
switches 0:0e018d759a2a 68 * stack.
switches 0:0e018d759a2a 69 */
switches 0:0e018d759a2a 70 virtual bool hasInitialized(void) const = 0;
switches 0:0e018d759a2a 71
switches 0:0e018d759a2a 72 /**
switches 0:0e018d759a2a 73 * Shutdown the underlying BLE stack. This includes purging the stack of
switches 0:0e018d759a2a 74 * GATT and GAP state and clearing all state from other BLE components
switches 0:0e018d759a2a 75 * such as the SecurityManager. init() must be called afterwards to
switches 0:0e018d759a2a 76 * re-instantiate services and GAP state.
switches 0:0e018d759a2a 77 *
switches 0:0e018d759a2a 78 * @return BLE_ERROR_NONE if the underlying stack and all other services of
switches 0:0e018d759a2a 79 * the BLE API were shutdown correctly.
switches 0:0e018d759a2a 80 */
switches 0:0e018d759a2a 81 virtual ble_error_t shutdown(void) = 0;
switches 0:0e018d759a2a 82
switches 0:0e018d759a2a 83 /**
switches 0:0e018d759a2a 84 * Fetches a string representation of the underlying BLE stack's version.
switches 0:0e018d759a2a 85 *
switches 0:0e018d759a2a 86 * @return A pointer to the string representation of the underlying
switches 0:0e018d759a2a 87 * BLE stack's version.
switches 0:0e018d759a2a 88 */
switches 0:0e018d759a2a 89 virtual const char * getVersion(void) = 0;
switches 0:0e018d759a2a 90
switches 0:0e018d759a2a 91 /**
switches 0:0e018d759a2a 92 * Accessor to Gap. This function is used by BLE::gap().
switches 0:0e018d759a2a 93 *
switches 0:0e018d759a2a 94 * @return A reference to a Gap object associated to this BLE instance.
switches 0:0e018d759a2a 95 */
switches 0:0e018d759a2a 96 virtual Gap& getGap() = 0;
switches 0:0e018d759a2a 97
switches 0:0e018d759a2a 98 /**
switches 0:0e018d759a2a 99 * A const alternative to getGap().
switches 0:0e018d759a2a 100 *
switches 0:0e018d759a2a 101 * @return A const reference to a Gap object associated to this BLE instance.
switches 0:0e018d759a2a 102 */
switches 0:0e018d759a2a 103 virtual const Gap& getGap() const = 0;
switches 0:0e018d759a2a 104
switches 0:0e018d759a2a 105 /**
switches 0:0e018d759a2a 106 * Accessor to GattServer. This function is used by BLE::gattServer().
switches 0:0e018d759a2a 107 *
switches 0:0e018d759a2a 108 * @return A reference to a GattServer object associated to this BLE instance.
switches 0:0e018d759a2a 109 */
switches 0:0e018d759a2a 110 virtual GattServer& getGattServer() = 0;
switches 0:0e018d759a2a 111
switches 0:0e018d759a2a 112 /**
switches 0:0e018d759a2a 113 * A const alternative to getGattServer().
switches 0:0e018d759a2a 114 *
switches 0:0e018d759a2a 115 * @return A const reference to a GattServer object associated to this BLE instance.
switches 0:0e018d759a2a 116 */
switches 0:0e018d759a2a 117 virtual const GattServer& getGattServer() const = 0;
switches 0:0e018d759a2a 118
switches 0:0e018d759a2a 119 /**
switches 0:0e018d759a2a 120 * Accessors to GattClient. This function is used by BLE::gattClient().
switches 0:0e018d759a2a 121 *
switches 0:0e018d759a2a 122 * @return A reference to a GattClient object associated to this BLE instance.
switches 0:0e018d759a2a 123 */
switches 0:0e018d759a2a 124 virtual GattClient& getGattClient() = 0;
switches 0:0e018d759a2a 125
switches 0:0e018d759a2a 126 /**
switches 0:0e018d759a2a 127 * Accessors to SecurityManager. This function is used by BLE::securityManager().
switches 0:0e018d759a2a 128 *
switches 0:0e018d759a2a 129 * @return A reference to a SecurityManager object associated to this BLE instance.
switches 0:0e018d759a2a 130 */
switches 0:0e018d759a2a 131 virtual SecurityManager& getSecurityManager() = 0;
switches 0:0e018d759a2a 132
switches 0:0e018d759a2a 133 /**
switches 0:0e018d759a2a 134 * A const alternative to getSecurityManager().
switches 0:0e018d759a2a 135 *
switches 0:0e018d759a2a 136 * @return A const reference to a SecurityManager object associated to this BLE instance.
switches 0:0e018d759a2a 137 */
switches 0:0e018d759a2a 138 virtual const SecurityManager& getSecurityManager() const = 0;
switches 0:0e018d759a2a 139
switches 0:0e018d759a2a 140 /**
switches 0:0e018d759a2a 141 * Yield control to the BLE stack or to other tasks waiting for events.
switches 0:0e018d759a2a 142 * refer to BLE::waitForEvent().
switches 0:0e018d759a2a 143 */
switches 0:0e018d759a2a 144 virtual void waitForEvent(void) = 0;
switches 0:0e018d759a2a 145
switches 0:0e018d759a2a 146 /**
switches 0:0e018d759a2a 147 * Process ALL pending events living in the BLE stack .
switches 0:0e018d759a2a 148 * Return once all events have been consumed.
switches 0:0e018d759a2a 149 */
switches 0:0e018d759a2a 150 virtual void processEvents() = 0;
switches 0:0e018d759a2a 151
switches 0:0e018d759a2a 152 /**
switches 0:0e018d759a2a 153 * This function allow the BLE stack to signal that their is work to do and
switches 0:0e018d759a2a 154 * event processing should be done (BLE::processEvent()).
switches 0:0e018d759a2a 155 * @param id: The ID of the BLE instance which does have events to process.
switches 0:0e018d759a2a 156 */
switches 0:0e018d759a2a 157 void signalEventsToProcess(BLE::InstanceID_t id);
switches 0:0e018d759a2a 158
switches 0:0e018d759a2a 159 private:
switches 0:0e018d759a2a 160 // this class is not a value type.
switches 0:0e018d759a2a 161 // prohibit copy construction and copy assignement
switches 0:0e018d759a2a 162 BLEInstanceBase(const BLEInstanceBase&);
switches 0:0e018d759a2a 163 BLEInstanceBase& operator=(const BLEInstanceBase&);
switches 0:0e018d759a2a 164 };
switches 0:0e018d759a2a 165
switches 0:0e018d759a2a 166 /**
switches 0:0e018d759a2a 167 * BLE uses composition to hide an interface object encapsulating the
switches 0:0e018d759a2a 168 * backend transport.
switches 0:0e018d759a2a 169 *
switches 0:0e018d759a2a 170 * The following API is used to create the singleton interface object. An
switches 0:0e018d759a2a 171 * implementation for this function must be provided by the device-specific
switches 0:0e018d759a2a 172 * library, otherwise there will be a linker error.
switches 0:0e018d759a2a 173 */
switches 0:0e018d759a2a 174 extern BLEInstanceBase *createBLEInstance(void);
switches 0:0e018d759a2a 175
switches 0:0e018d759a2a 176 #endif // ifndef __BLE_DEVICE_INSTANCE_BASE__