Bluetooth Low Energy / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.

Supported Services

Supported services can be found in the BLE_API/services folder.

ble/BLEInstanceBase.h@1208:65474dc93927, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:18:00 2016 +0100
Revision:
1208:65474dc93927
Parent:
1201:9b71aac42d14 
Sync with 8d97fced5440d78c9557693b6d1632f1ab5d77b7



2016-09-01 08:21:37+01:00: Vincent Coubard

version v2.7.0

Who changed what in which revision?

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