ON Semiconductor / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

features/FEATURE_BLE/ble/BLEInstanceBase.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

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