Simon Cooksey / mbed-os

Pinned to some recent date

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

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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