Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/BLE_API/ble/BLE.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /* mbed Microcontroller Library
MrBedfordVan 0:b9164b348919 2 * Copyright (c) 2006-2013 ARM Limited
MrBedfordVan 0:b9164b348919 3 *
MrBedfordVan 0:b9164b348919 4 * Licensed under the Apache License, Version 2.0 (the "License");
MrBedfordVan 0:b9164b348919 5 * you may not use this file except in compliance with the License.
MrBedfordVan 0:b9164b348919 6 * You may obtain a copy of the License at
MrBedfordVan 0:b9164b348919 7 *
MrBedfordVan 0:b9164b348919 8 * http://www.apache.org/licenses/LICENSE-2.0
MrBedfordVan 0:b9164b348919 9 *
MrBedfordVan 0:b9164b348919 10 * Unless required by applicable law or agreed to in writing, software
MrBedfordVan 0:b9164b348919 11 * distributed under the License is distributed on an "AS IS" BASIS,
MrBedfordVan 0:b9164b348919 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
MrBedfordVan 0:b9164b348919 13 * See the License for the specific language governing permissions and
MrBedfordVan 0:b9164b348919 14 * limitations under the License.
MrBedfordVan 0:b9164b348919 15 */
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 #ifndef __BLE_H__
MrBedfordVan 0:b9164b348919 18 #define __BLE_H__
MrBedfordVan 0:b9164b348919 19
MrBedfordVan 0:b9164b348919 20 #include "blecommon.h"
MrBedfordVan 0:b9164b348919 21 #include "Gap.h"
MrBedfordVan 0:b9164b348919 22 #include "GattServer.h"
MrBedfordVan 0:b9164b348919 23 #include "GattClient.h"
MrBedfordVan 0:b9164b348919 24
MrBedfordVan 0:b9164b348919 25 #include "ble/FunctionPointerWithContext.h"
MrBedfordVan 0:b9164b348919 26
MrBedfordVan 0:b9164b348919 27 #ifdef YOTTA_CFG_MBED_OS
MrBedfordVan 0:b9164b348919 28 #include "mbed-drivers/mbed_error.h"
MrBedfordVan 0:b9164b348919 29 #else
MrBedfordVan 0:b9164b348919 30 #include "mbed_error.h"
MrBedfordVan 0:b9164b348919 31 #endif
MrBedfordVan 0:b9164b348919 32
MrBedfordVan 0:b9164b348919 33 /* Forward declaration for the implementation class */
MrBedfordVan 0:b9164b348919 34 class BLEInstanceBase;
MrBedfordVan 0:b9164b348919 35
MrBedfordVan 0:b9164b348919 36 /**
MrBedfordVan 0:b9164b348919 37 * The base class used to abstract away BLE-capable radio transceivers or SOCs,
MrBedfordVan 0:b9164b348919 38 * so that the BLE API can work with any radio transparently.
MrBedfordVan 0:b9164b348919 39 */
MrBedfordVan 0:b9164b348919 40 class BLE
MrBedfordVan 0:b9164b348919 41 {
MrBedfordVan 0:b9164b348919 42 public:
MrBedfordVan 0:b9164b348919 43 typedef unsigned InstanceID_t; /** The type returned by BLE::getInstanceID(). */
MrBedfordVan 0:b9164b348919 44
MrBedfordVan 0:b9164b348919 45 /**
MrBedfordVan 0:b9164b348919 46 * The context provided to init-completion-callbacks (see init() below).
MrBedfordVan 0:b9164b348919 47 *
MrBedfordVan 0:b9164b348919 48 * @param ble
MrBedfordVan 0:b9164b348919 49 * A reference to the BLE instance being initialized.
MrBedfordVan 0:b9164b348919 50 * @param error
MrBedfordVan 0:b9164b348919 51 * Captures the result of initialization. It is set to
MrBedfordVan 0:b9164b348919 52 * BLE_ERROR_NONE if initialization completed successfully. Else
MrBedfordVan 0:b9164b348919 53 * the error value is implementation specific.
MrBedfordVan 0:b9164b348919 54 */
MrBedfordVan 0:b9164b348919 55 struct InitializationCompleteCallbackContext {
MrBedfordVan 0:b9164b348919 56 BLE& ble; /* Reference to the BLE object that has been initialized */
MrBedfordVan 0:b9164b348919 57 ble_error_t error; /* Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
MrBedfordVan 0:b9164b348919 58 };
MrBedfordVan 0:b9164b348919 59
MrBedfordVan 0:b9164b348919 60 /**
MrBedfordVan 0:b9164b348919 61 * The signature for function-pointer like callbacks for initialization-completion.
MrBedfordVan 0:b9164b348919 62 *
MrBedfordVan 0:b9164b348919 63 * @note There are two versions of init(). In addition to the simple
MrBedfordVan 0:b9164b348919 64 * function-pointer, init() can also take a <Object, member> tuple as its
MrBedfordVan 0:b9164b348919 65 * callback target. In case of the latter, the following declaration doesn't apply.
MrBedfordVan 0:b9164b348919 66 */
MrBedfordVan 0:b9164b348919 67 typedef void (*InitializationCompleteCallback_t)(InitializationCompleteCallbackContext *context);
MrBedfordVan 0:b9164b348919 68
MrBedfordVan 0:b9164b348919 69 /**
MrBedfordVan 0:b9164b348919 70 * Initialize the BLE controller. This should be called before using
MrBedfordVan 0:b9164b348919 71 * anything else in the BLE_API.
MrBedfordVan 0:b9164b348919 72 *
MrBedfordVan 0:b9164b348919 73 * init() hands control to the underlying BLE module to accomplish
MrBedfordVan 0:b9164b348919 74 * initialization. This initialization may tacitly depend on other hardware
MrBedfordVan 0:b9164b348919 75 * setup (such as clocks or power-modes) that happens early on during
MrBedfordVan 0:b9164b348919 76 * system startup. It may not be safe to call init() from a global static
MrBedfordVan 0:b9164b348919 77 * context where ordering is compiler-specific and can't be guaranteed - it
MrBedfordVan 0:b9164b348919 78 * is safe to call BLE::init() from within main().
MrBedfordVan 0:b9164b348919 79 *
MrBedfordVan 0:b9164b348919 80 * @param initCompleteCallback
MrBedfordVan 0:b9164b348919 81 * A callback for when initialization completes for a BLE
MrBedfordVan 0:b9164b348919 82 * instance. This is an optional parameter; if no callback is
MrBedfordVan 0:b9164b348919 83 * set up the application can still determine the status of
MrBedfordVan 0:b9164b348919 84 * initialization using BLE::hasInitialized() (see below).
MrBedfordVan 0:b9164b348919 85 *
MrBedfordVan 0:b9164b348919 86 * @return BLE_ERROR_NONE if the initialization procedure was started
MrBedfordVan 0:b9164b348919 87 * successfully.
MrBedfordVan 0:b9164b348919 88 *
MrBedfordVan 0:b9164b348919 89 * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
MrBedfordVan 0:b9164b348919 90 * the initialization completion callback at some point.
MrBedfordVan 0:b9164b348919 91 *
MrBedfordVan 0:b9164b348919 92 * @note In some cases, initialization is instantaneous (or blocking); if
MrBedfordVan 0:b9164b348919 93 * so, it is acceptable for the stack-specific implementation of init()
MrBedfordVan 0:b9164b348919 94 * to invoke the completion callback directly (within its own
MrBedfordVan 0:b9164b348919 95 * context).
MrBedfordVan 0:b9164b348919 96 *
MrBedfordVan 0:b9164b348919 97 * @note Nearly all BLE APIs would return
MrBedfordVan 0:b9164b348919 98 * BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
MrBedfordVan 0:b9164b348919 99 * corresponding transport is initialized.
MrBedfordVan 0:b9164b348919 100 *
MrBedfordVan 0:b9164b348919 101 * @note There are two versions of init(). In addition to the simple
MrBedfordVan 0:b9164b348919 102 * function-pointer, init() can also take an <Object, member> tuple as its
MrBedfordVan 0:b9164b348919 103 * callback target.
MrBedfordVan 0:b9164b348919 104 */
MrBedfordVan 0:b9164b348919 105 ble_error_t init(InitializationCompleteCallback_t initCompleteCallback = NULL) {
MrBedfordVan 0:b9164b348919 106 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(initCompleteCallback);
MrBedfordVan 0:b9164b348919 107 return initImplementation(callback);
MrBedfordVan 0:b9164b348919 108 }
MrBedfordVan 0:b9164b348919 109
MrBedfordVan 0:b9164b348919 110 /**
MrBedfordVan 0:b9164b348919 111 * An alternate declaration for init(). This one takes an <Object, member> tuple as its
MrBedfordVan 0:b9164b348919 112 * callback target.
MrBedfordVan 0:b9164b348919 113 */
MrBedfordVan 0:b9164b348919 114 template<typename T>
MrBedfordVan 0:b9164b348919 115 ble_error_t init(T *object, void (T::*initCompleteCallback)(InitializationCompleteCallbackContext *context)) {
MrBedfordVan 0:b9164b348919 116 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, initCompleteCallback);
MrBedfordVan 0:b9164b348919 117 return initImplementation(callback);
MrBedfordVan 0:b9164b348919 118 }
MrBedfordVan 0:b9164b348919 119
MrBedfordVan 0:b9164b348919 120 /**
MrBedfordVan 0:b9164b348919 121 * @return true if initialization has completed for the underlying BLE
MrBedfordVan 0:b9164b348919 122 * transport.
MrBedfordVan 0:b9164b348919 123 *
MrBedfordVan 0:b9164b348919 124 * The application can set up a callback to signal completion of
MrBedfordVan 0:b9164b348919 125 * initialization when using init(). Otherwise, this method can be used to
MrBedfordVan 0:b9164b348919 126 * poll the state of initialization.
MrBedfordVan 0:b9164b348919 127 */
MrBedfordVan 0:b9164b348919 128 bool hasInitialized(void) const;
MrBedfordVan 0:b9164b348919 129
MrBedfordVan 0:b9164b348919 130 /**
MrBedfordVan 0:b9164b348919 131 * Purge the BLE stack of GATT and GAP state. init() must be called
MrBedfordVan 0:b9164b348919 132 * afterwards to re-instate services and GAP state. This API offers a way to
MrBedfordVan 0:b9164b348919 133 * repopulate the GATT database with new services and characteristics.
MrBedfordVan 0:b9164b348919 134 */
MrBedfordVan 0:b9164b348919 135 ble_error_t shutdown(void);
MrBedfordVan 0:b9164b348919 136
MrBedfordVan 0:b9164b348919 137 /**
MrBedfordVan 0:b9164b348919 138 * This call allows the application to get the BLE stack version information.
MrBedfordVan 0:b9164b348919 139 *
MrBedfordVan 0:b9164b348919 140 * @return A pointer to a const string representing the version.
MrBedfordVan 0:b9164b348919 141 * Note: The string is owned by BLE_API.
MrBedfordVan 0:b9164b348919 142 */
MrBedfordVan 0:b9164b348919 143 const char *getVersion(void);
MrBedfordVan 0:b9164b348919 144
MrBedfordVan 0:b9164b348919 145 /*
MrBedfordVan 0:b9164b348919 146 * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
MrBedfordVan 0:b9164b348919 147 * going through this accessor.
MrBedfordVan 0:b9164b348919 148 */
MrBedfordVan 0:b9164b348919 149 const Gap &gap() const;
MrBedfordVan 0:b9164b348919 150 Gap &gap();
MrBedfordVan 0:b9164b348919 151
MrBedfordVan 0:b9164b348919 152 /*
MrBedfordVan 0:b9164b348919 153 * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
MrBedfordVan 0:b9164b348919 154 * functionality requires going through this accessor.
MrBedfordVan 0:b9164b348919 155 */
MrBedfordVan 0:b9164b348919 156 const GattServer& gattServer() const;
MrBedfordVan 0:b9164b348919 157 GattServer& gattServer();
MrBedfordVan 0:b9164b348919 158
MrBedfordVan 0:b9164b348919 159 /*
MrBedfordVan 0:b9164b348919 160 * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
MrBedfordVan 0:b9164b348919 161 * functionality requires going through this accessor.
MrBedfordVan 0:b9164b348919 162 */
MrBedfordVan 0:b9164b348919 163 const GattClient& gattClient() const;
MrBedfordVan 0:b9164b348919 164 GattClient& gattClient();
MrBedfordVan 0:b9164b348919 165
MrBedfordVan 0:b9164b348919 166 /*
MrBedfordVan 0:b9164b348919 167 * Accessors to Security Manager. Please refer to SecurityManager.h. All
MrBedfordVan 0:b9164b348919 168 * SecurityManager related functionality requires going through this
MrBedfordVan 0:b9164b348919 169 * accessor.
MrBedfordVan 0:b9164b348919 170 */
MrBedfordVan 0:b9164b348919 171 const SecurityManager& securityManager() const;
MrBedfordVan 0:b9164b348919 172 SecurityManager& securityManager();
MrBedfordVan 0:b9164b348919 173
MrBedfordVan 0:b9164b348919 174 /**
MrBedfordVan 0:b9164b348919 175 * Yield control to the BLE stack or to other tasks waiting for events. This
MrBedfordVan 0:b9164b348919 176 * is a sleep function that will return when there is an application-specific
MrBedfordVan 0:b9164b348919 177 * interrupt, but the MCU might wake up several times before
MrBedfordVan 0:b9164b348919 178 * returning (to service the stack). This is not always interchangeable with
MrBedfordVan 0:b9164b348919 179 * WFE().
MrBedfordVan 0:b9164b348919 180 */
MrBedfordVan 0:b9164b348919 181 void waitForEvent(void);
MrBedfordVan 0:b9164b348919 182
MrBedfordVan 0:b9164b348919 183 public:
MrBedfordVan 0:b9164b348919 184 static const InstanceID_t DEFAULT_INSTANCE = 0;
MrBedfordVan 0:b9164b348919 185 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
MrBedfordVan 0:b9164b348919 186 static const InstanceID_t NUM_INSTANCES = 1;
MrBedfordVan 0:b9164b348919 187 #else
MrBedfordVan 0:b9164b348919 188 static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
MrBedfordVan 0:b9164b348919 189 #endif
MrBedfordVan 0:b9164b348919 190
MrBedfordVan 0:b9164b348919 191 /**
MrBedfordVan 0:b9164b348919 192 * Get a reference to the BLE singleton corresponding to a given interface.
MrBedfordVan 0:b9164b348919 193 * There is a static array of BLE singletons.
MrBedfordVan 0:b9164b348919 194 *
MrBedfordVan 0:b9164b348919 195 * @Note: Calling Instance() is preferred over constructing a BLE object
MrBedfordVan 0:b9164b348919 196 * directly, as it returns references to singletons.
MrBedfordVan 0:b9164b348919 197 *
MrBedfordVan 0:b9164b348919 198 * @param[in] id
MrBedfordVan 0:b9164b348919 199 * Instance-ID. This should be less than NUM_INSTANCES
MrBedfordVan 0:b9164b348919 200 * for the returned BLE singleton to be useful.
MrBedfordVan 0:b9164b348919 201 *
MrBedfordVan 0:b9164b348919 202 * @return a reference to a single object.
MrBedfordVan 0:b9164b348919 203 */
MrBedfordVan 0:b9164b348919 204 static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
MrBedfordVan 0:b9164b348919 205
MrBedfordVan 0:b9164b348919 206 /**
MrBedfordVan 0:b9164b348919 207 * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
MrBedfordVan 0:b9164b348919 208 * are thin wrappers around a transport object (that is, ptr. to
MrBedfordVan 0:b9164b348919 209 * BLEInstanceBase).
MrBedfordVan 0:b9164b348919 210 *
MrBedfordVan 0:b9164b348919 211 * It is better to create BLE objects as singletons accessed through the
MrBedfordVan 0:b9164b348919 212 * Instance() method. If multiple BLE handles are constructed for the same
MrBedfordVan 0:b9164b348919 213 * interface (using this constructor), they will share the same underlying
MrBedfordVan 0:b9164b348919 214 * transport object.
MrBedfordVan 0:b9164b348919 215 */
MrBedfordVan 0:b9164b348919 216 BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
MrBedfordVan 0:b9164b348919 217
MrBedfordVan 0:b9164b348919 218 /**
MrBedfordVan 0:b9164b348919 219 * Fetch the ID of a BLE instance. Typically there would only be the DEFAULT_INSTANCE.
MrBedfordVan 0:b9164b348919 220 */
MrBedfordVan 0:b9164b348919 221 InstanceID_t getInstanceID(void) const {
MrBedfordVan 0:b9164b348919 222 return instanceID;
MrBedfordVan 0:b9164b348919 223 }
MrBedfordVan 0:b9164b348919 224
MrBedfordVan 0:b9164b348919 225 /*
MrBedfordVan 0:b9164b348919 226 * Deprecation alert!
MrBedfordVan 0:b9164b348919 227 * All of the following are deprecated and may be dropped in a future
MrBedfordVan 0:b9164b348919 228 * release. Documentation should refer to alternative APIs.
MrBedfordVan 0:b9164b348919 229 */
MrBedfordVan 0:b9164b348919 230
MrBedfordVan 0:b9164b348919 231 /* GAP specific APIs. */
MrBedfordVan 0:b9164b348919 232 public:
MrBedfordVan 0:b9164b348919 233 /**
MrBedfordVan 0:b9164b348919 234 * Set the BTLE MAC address and type.
MrBedfordVan 0:b9164b348919 235 * @return BLE_ERROR_NONE on success.
MrBedfordVan 0:b9164b348919 236 *
MrBedfordVan 0:b9164b348919 237 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 238 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 239 * ble.setAddress(...) should be replaced with
MrBedfordVan 0:b9164b348919 240 * ble.gap().setAddress(...).
MrBedfordVan 0:b9164b348919 241 */
MrBedfordVan 0:b9164b348919 242 ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
MrBedfordVan 0:b9164b348919 243 return gap().setAddress(type, address);
MrBedfordVan 0:b9164b348919 244 }
MrBedfordVan 0:b9164b348919 245
MrBedfordVan 0:b9164b348919 246 /**
MrBedfordVan 0:b9164b348919 247 * Fetch the BTLE MAC address and type.
MrBedfordVan 0:b9164b348919 248 * @return BLE_ERROR_NONE on success.
MrBedfordVan 0:b9164b348919 249 *
MrBedfordVan 0:b9164b348919 250 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 251 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 252 * ble.getAddress(...) should be replaced with
MrBedfordVan 0:b9164b348919 253 * ble.gap().getAddress(...).
MrBedfordVan 0:b9164b348919 254 */
MrBedfordVan 0:b9164b348919 255 ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
MrBedfordVan 0:b9164b348919 256 return gap().getAddress(typeP, address);
MrBedfordVan 0:b9164b348919 257 }
MrBedfordVan 0:b9164b348919 258
MrBedfordVan 0:b9164b348919 259 /**
MrBedfordVan 0:b9164b348919 260 * Set the GAP advertising mode to use for this device.
MrBedfordVan 0:b9164b348919 261 *
MrBedfordVan 0:b9164b348919 262 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 263 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 264 * ble.setAdvertisingType(...) should be replaced with
MrBedfordVan 0:b9164b348919 265 * ble.gap().setAdvertisingType(...).
MrBedfordVan 0:b9164b348919 266 */
MrBedfordVan 0:b9164b348919 267 void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
MrBedfordVan 0:b9164b348919 268 gap().setAdvertisingType(advType);
MrBedfordVan 0:b9164b348919 269 }
MrBedfordVan 0:b9164b348919 270
MrBedfordVan 0:b9164b348919 271 /**
MrBedfordVan 0:b9164b348919 272 * @param[in] interval
MrBedfordVan 0:b9164b348919 273 * Advertising interval in units of milliseconds. Advertising
MrBedfordVan 0:b9164b348919 274 * is disabled if interval is 0. If interval is smaller than
MrBedfordVan 0:b9164b348919 275 * the minimum supported value, then the minimum supported
MrBedfordVan 0:b9164b348919 276 * value is used instead. This minimum value can be discovered
MrBedfordVan 0:b9164b348919 277 * using getMinAdvertisingInterval().
MrBedfordVan 0:b9164b348919 278 *
MrBedfordVan 0:b9164b348919 279 * This field must be set to 0 if connectionMode is equal
MrBedfordVan 0:b9164b348919 280 * to ADV_CONNECTABLE_DIRECTED.
MrBedfordVan 0:b9164b348919 281 *
MrBedfordVan 0:b9164b348919 282 * @note: Decreasing this value allows central devices to detect a
MrBedfordVan 0:b9164b348919 283 * peripheral faster, at the expense of more power being used by the radio
MrBedfordVan 0:b9164b348919 284 * due to the higher data transmit rate.
MrBedfordVan 0:b9164b348919 285 *
MrBedfordVan 0:b9164b348919 286 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 287 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 288 * ble.setAdvertisingInterval(...) should be replaced with
MrBedfordVan 0:b9164b348919 289 * ble.gap().setAdvertisingInterval(...).
MrBedfordVan 0:b9164b348919 290 *
MrBedfordVan 0:b9164b348919 291 * @note: [WARNING] This API previously used 0.625ms as the unit for its
MrBedfordVan 0:b9164b348919 292 * 'interval' argument. That required an explicit conversion from
MrBedfordVan 0:b9164b348919 293 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
MrBedfordVan 0:b9164b348919 294 * no longer required as the new units are milliseconds. Any application
MrBedfordVan 0:b9164b348919 295 * code depending on the old semantics needs to be updated accordingly.
MrBedfordVan 0:b9164b348919 296 */
MrBedfordVan 0:b9164b348919 297 void setAdvertisingInterval(uint16_t interval) {
MrBedfordVan 0:b9164b348919 298 gap().setAdvertisingInterval(interval);
MrBedfordVan 0:b9164b348919 299 }
MrBedfordVan 0:b9164b348919 300
MrBedfordVan 0:b9164b348919 301 /**
MrBedfordVan 0:b9164b348919 302 * @return Minimum Advertising interval in milliseconds.
MrBedfordVan 0:b9164b348919 303 *
MrBedfordVan 0:b9164b348919 304 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 305 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 306 * ble.getMinAdvertisingInterval(...) should be replaced with
MrBedfordVan 0:b9164b348919 307 * ble.gap().getMinAdvertisingInterval(...).
MrBedfordVan 0:b9164b348919 308 */
MrBedfordVan 0:b9164b348919 309 uint16_t getMinAdvertisingInterval(void) const {
MrBedfordVan 0:b9164b348919 310 return gap().getMinAdvertisingInterval();
MrBedfordVan 0:b9164b348919 311 }
MrBedfordVan 0:b9164b348919 312
MrBedfordVan 0:b9164b348919 313 /**
MrBedfordVan 0:b9164b348919 314 * @return Minimum Advertising interval in milliseconds for non-connectible mode.
MrBedfordVan 0:b9164b348919 315 *
MrBedfordVan 0:b9164b348919 316 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 317 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 318 * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
MrBedfordVan 0:b9164b348919 319 * ble.gap().getMinNonConnectableAdvertisingInterval(...).
MrBedfordVan 0:b9164b348919 320 */
MrBedfordVan 0:b9164b348919 321 uint16_t getMinNonConnectableAdvertisingInterval(void) const {
MrBedfordVan 0:b9164b348919 322 return gap().getMinNonConnectableAdvertisingInterval();
MrBedfordVan 0:b9164b348919 323 }
MrBedfordVan 0:b9164b348919 324
MrBedfordVan 0:b9164b348919 325 /**
MrBedfordVan 0:b9164b348919 326 * @return Maximum Advertising interval in milliseconds.
MrBedfordVan 0:b9164b348919 327 *
MrBedfordVan 0:b9164b348919 328 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 329 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 330 * ble.getMaxAdvertisingInterval(...) should be replaced with
MrBedfordVan 0:b9164b348919 331 * ble.gap().getMaxAdvertisingInterval(...).
MrBedfordVan 0:b9164b348919 332 */
MrBedfordVan 0:b9164b348919 333 uint16_t getMaxAdvertisingInterval(void) const {
MrBedfordVan 0:b9164b348919 334 return gap().getMaxAdvertisingInterval();
MrBedfordVan 0:b9164b348919 335 }
MrBedfordVan 0:b9164b348919 336
MrBedfordVan 0:b9164b348919 337 /**
MrBedfordVan 0:b9164b348919 338 * @param[in] timeout
MrBedfordVan 0:b9164b348919 339 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
MrBedfordVan 0:b9164b348919 340 * and 16383). Use 0 to disable the advertising timeout.
MrBedfordVan 0:b9164b348919 341 *
MrBedfordVan 0:b9164b348919 342 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 343 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 344 * ble.setAdvertisingTimeout(...) should be replaced with
MrBedfordVan 0:b9164b348919 345 * ble.gap().setAdvertisingTimeout(...).
MrBedfordVan 0:b9164b348919 346 */
MrBedfordVan 0:b9164b348919 347 void setAdvertisingTimeout(uint16_t timeout) {
MrBedfordVan 0:b9164b348919 348 gap().setAdvertisingTimeout(timeout);
MrBedfordVan 0:b9164b348919 349 }
MrBedfordVan 0:b9164b348919 350
MrBedfordVan 0:b9164b348919 351 /**
MrBedfordVan 0:b9164b348919 352 * Set up a particular, user-constructed set of advertisement parameters for
MrBedfordVan 0:b9164b348919 353 * the underlying stack. It would be uncommon for this API to be used
MrBedfordVan 0:b9164b348919 354 * directly; there are other APIs to tweak advertisement parameters
MrBedfordVan 0:b9164b348919 355 * individually (see above).
MrBedfordVan 0:b9164b348919 356 *
MrBedfordVan 0:b9164b348919 357 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 358 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 359 * ble.setAdvertisingParams(...) should be replaced with
MrBedfordVan 0:b9164b348919 360 * ble.gap().setAdvertisingParams(...).
MrBedfordVan 0:b9164b348919 361 */
MrBedfordVan 0:b9164b348919 362 void setAdvertisingParams(const GapAdvertisingParams &advParams) {
MrBedfordVan 0:b9164b348919 363 gap().setAdvertisingParams(advParams);
MrBedfordVan 0:b9164b348919 364 }
MrBedfordVan 0:b9164b348919 365
MrBedfordVan 0:b9164b348919 366 /**
MrBedfordVan 0:b9164b348919 367 * @return Read back advertising parameters. Useful for storing and
MrBedfordVan 0:b9164b348919 368 * restoring parameters rapidly.
MrBedfordVan 0:b9164b348919 369 *
MrBedfordVan 0:b9164b348919 370 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 371 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 372 * ble.getAdvertisingParams(...) should be replaced with
MrBedfordVan 0:b9164b348919 373 * ble.gap().getAdvertisingParams(...).
MrBedfordVan 0:b9164b348919 374 */
MrBedfordVan 0:b9164b348919 375 const GapAdvertisingParams &getAdvertisingParams(void) const {
MrBedfordVan 0:b9164b348919 376 return gap().getAdvertisingParams();
MrBedfordVan 0:b9164b348919 377 }
MrBedfordVan 0:b9164b348919 378
MrBedfordVan 0:b9164b348919 379 /**
MrBedfordVan 0:b9164b348919 380 * Accumulate an AD structure in the advertising payload. Please note that
MrBedfordVan 0:b9164b348919 381 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
MrBedfordVan 0:b9164b348919 382 * as an additional 31 bytes if the advertising payload is too
MrBedfordVan 0:b9164b348919 383 * small.
MrBedfordVan 0:b9164b348919 384 *
MrBedfordVan 0:b9164b348919 385 * @param[in] flags
MrBedfordVan 0:b9164b348919 386 * The flags to add. Please refer to
MrBedfordVan 0:b9164b348919 387 * GapAdvertisingData::Flags for valid flags. Multiple
MrBedfordVan 0:b9164b348919 388 * flags may be specified in combination.
MrBedfordVan 0:b9164b348919 389 *
MrBedfordVan 0:b9164b348919 390 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 391 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 392 * ble.accumulateAdvertisingPayload(flags) should be replaced with
MrBedfordVan 0:b9164b348919 393 * ble.gap().accumulateAdvertisingPayload(flags).
MrBedfordVan 0:b9164b348919 394 */
MrBedfordVan 0:b9164b348919 395 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
MrBedfordVan 0:b9164b348919 396 return gap().accumulateAdvertisingPayload(flags);
MrBedfordVan 0:b9164b348919 397 }
MrBedfordVan 0:b9164b348919 398
MrBedfordVan 0:b9164b348919 399 /**
MrBedfordVan 0:b9164b348919 400 * Accumulate an AD structure in the advertising payload. Please note that
MrBedfordVan 0:b9164b348919 401 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
MrBedfordVan 0:b9164b348919 402 * as an additional 31 bytes if the advertising payload is too
MrBedfordVan 0:b9164b348919 403 * small.
MrBedfordVan 0:b9164b348919 404 *
MrBedfordVan 0:b9164b348919 405 * @param[in] app
MrBedfordVan 0:b9164b348919 406 * The appearance of the peripheral.
MrBedfordVan 0:b9164b348919 407 *
MrBedfordVan 0:b9164b348919 408 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 409 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 410 * ble.accumulateAdvertisingPayload(appearance) should be replaced with
MrBedfordVan 0:b9164b348919 411 * ble.gap().accumulateAdvertisingPayload(appearance).
MrBedfordVan 0:b9164b348919 412 */
MrBedfordVan 0:b9164b348919 413 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
MrBedfordVan 0:b9164b348919 414 return gap().accumulateAdvertisingPayload(app);
MrBedfordVan 0:b9164b348919 415 }
MrBedfordVan 0:b9164b348919 416
MrBedfordVan 0:b9164b348919 417 /**
MrBedfordVan 0:b9164b348919 418 * Accumulate an AD structure in the advertising payload. Please note that
MrBedfordVan 0:b9164b348919 419 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
MrBedfordVan 0:b9164b348919 420 * as an additional 31 bytes if the advertising payload is too
MrBedfordVan 0:b9164b348919 421 * small.
MrBedfordVan 0:b9164b348919 422 *
MrBedfordVan 0:b9164b348919 423 * @param[in] app
MrBedfordVan 0:b9164b348919 424 * The max transmit power to be used by the controller. This
MrBedfordVan 0:b9164b348919 425 * is only a hint.
MrBedfordVan 0:b9164b348919 426 *
MrBedfordVan 0:b9164b348919 427 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 428 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 429 * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
MrBedfordVan 0:b9164b348919 430 * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
MrBedfordVan 0:b9164b348919 431 */
MrBedfordVan 0:b9164b348919 432 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
MrBedfordVan 0:b9164b348919 433 return gap().accumulateAdvertisingPayloadTxPower(power);
MrBedfordVan 0:b9164b348919 434 }
MrBedfordVan 0:b9164b348919 435
MrBedfordVan 0:b9164b348919 436 /**
MrBedfordVan 0:b9164b348919 437 * Accumulate a variable length byte-stream as an AD structure in the
MrBedfordVan 0:b9164b348919 438 * advertising payload. Please note that the payload is limited to 31 bytes.
MrBedfordVan 0:b9164b348919 439 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
MrBedfordVan 0:b9164b348919 440 * advertising payload is too small.
MrBedfordVan 0:b9164b348919 441 *
MrBedfordVan 0:b9164b348919 442 * @param type The type that describes the variable length data.
MrBedfordVan 0:b9164b348919 443 * @param data Data bytes.
MrBedfordVan 0:b9164b348919 444 * @param len Data length.
MrBedfordVan 0:b9164b348919 445 *
MrBedfordVan 0:b9164b348919 446 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 447 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 448 * ble.accumulateAdvertisingPayload(...) should be replaced with
MrBedfordVan 0:b9164b348919 449 * ble.gap().accumulateAdvertisingPayload(...).
MrBedfordVan 0:b9164b348919 450 */
MrBedfordVan 0:b9164b348919 451 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
MrBedfordVan 0:b9164b348919 452 return gap().accumulateAdvertisingPayload(type, data, len);
MrBedfordVan 0:b9164b348919 453 }
MrBedfordVan 0:b9164b348919 454
MrBedfordVan 0:b9164b348919 455 /**
MrBedfordVan 0:b9164b348919 456 * Setup a particular, user-constructed advertisement payload for the
MrBedfordVan 0:b9164b348919 457 * underlying stack. It would be uncommon for this API to be used directly;
MrBedfordVan 0:b9164b348919 458 * there are other APIs to build an advertisement payload (see above).
MrBedfordVan 0:b9164b348919 459 *
MrBedfordVan 0:b9164b348919 460 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 461 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 462 * ble.setAdvertisingData(...) should be replaced with
MrBedfordVan 0:b9164b348919 463 * ble.gap().setAdvertisingPayload(...).
MrBedfordVan 0:b9164b348919 464 */
MrBedfordVan 0:b9164b348919 465 ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
MrBedfordVan 0:b9164b348919 466 return gap().setAdvertisingPayload(advData);
MrBedfordVan 0:b9164b348919 467 }
MrBedfordVan 0:b9164b348919 468
MrBedfordVan 0:b9164b348919 469 /**
MrBedfordVan 0:b9164b348919 470 * @return Read back advertising data. Useful for storing and
MrBedfordVan 0:b9164b348919 471 * restoring payload.
MrBedfordVan 0:b9164b348919 472 *
MrBedfordVan 0:b9164b348919 473 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 474 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 475 * ble.getAdvertisingData(...) should be replaced with
MrBedfordVan 0:b9164b348919 476 * ble.gap().getAdvertisingPayload()(...).
MrBedfordVan 0:b9164b348919 477 */
MrBedfordVan 0:b9164b348919 478 const GapAdvertisingData &getAdvertisingData(void) const {
MrBedfordVan 0:b9164b348919 479 return gap().getAdvertisingPayload();
MrBedfordVan 0:b9164b348919 480 }
MrBedfordVan 0:b9164b348919 481
MrBedfordVan 0:b9164b348919 482 /**
MrBedfordVan 0:b9164b348919 483 * Reset any advertising payload prepared from prior calls to
MrBedfordVan 0:b9164b348919 484 * accumulateAdvertisingPayload(). This automatically propagates the re-
MrBedfordVan 0:b9164b348919 485 * initialized advertising payload to the underlying stack.
MrBedfordVan 0:b9164b348919 486 *
MrBedfordVan 0:b9164b348919 487 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 488 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 489 * ble.clearAdvertisingPayload(...) should be replaced with
MrBedfordVan 0:b9164b348919 490 * ble.gap().clearAdvertisingPayload(...).
MrBedfordVan 0:b9164b348919 491 */
MrBedfordVan 0:b9164b348919 492 void clearAdvertisingPayload(void) {
MrBedfordVan 0:b9164b348919 493 gap().clearAdvertisingPayload();
MrBedfordVan 0:b9164b348919 494 }
MrBedfordVan 0:b9164b348919 495
MrBedfordVan 0:b9164b348919 496 /**
MrBedfordVan 0:b9164b348919 497 * This API is *deprecated* and resolves to a no-operation. It is left here
MrBedfordVan 0:b9164b348919 498 * to allow older code to compile. Please avoid using this API in new code.
MrBedfordVan 0:b9164b348919 499 * This API will be dropped in a future release.
MrBedfordVan 0:b9164b348919 500 *
MrBedfordVan 0:b9164b348919 501 * Formerly, it would be used to dynamically reset the accumulated advertising
MrBedfordVan 0:b9164b348919 502 * payload and scanResponse; to do this, the application would clear and re-
MrBedfordVan 0:b9164b348919 503 * accumulate a new advertising payload (and scanResponse) before using this
MrBedfordVan 0:b9164b348919 504 * API. Updates to the underlying advertisement payload now happen
MrBedfordVan 0:b9164b348919 505 * implicitly.
MrBedfordVan 0:b9164b348919 506 */
MrBedfordVan 0:b9164b348919 507 ble_error_t setAdvertisingPayload(void) {
MrBedfordVan 0:b9164b348919 508 return BLE_ERROR_NONE;
MrBedfordVan 0:b9164b348919 509 }
MrBedfordVan 0:b9164b348919 510
MrBedfordVan 0:b9164b348919 511 /**
MrBedfordVan 0:b9164b348919 512 * Accumulate a variable length byte-stream as an AD structure in the
MrBedfordVan 0:b9164b348919 513 * scanResponse payload.
MrBedfordVan 0:b9164b348919 514 *
MrBedfordVan 0:b9164b348919 515 * @param[in] type The type that describes the variable length data.
MrBedfordVan 0:b9164b348919 516 * @param[in] data Data bytes.
MrBedfordVan 0:b9164b348919 517 * @param[in] len Data length.
MrBedfordVan 0:b9164b348919 518 *
MrBedfordVan 0:b9164b348919 519 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 520 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 521 * ble.accumulateScanResponse(...) should be replaced with
MrBedfordVan 0:b9164b348919 522 * ble.gap().accumulateScanResponse(...).
MrBedfordVan 0:b9164b348919 523 */
MrBedfordVan 0:b9164b348919 524 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
MrBedfordVan 0:b9164b348919 525 return gap().accumulateScanResponse(type, data, len);
MrBedfordVan 0:b9164b348919 526 }
MrBedfordVan 0:b9164b348919 527
MrBedfordVan 0:b9164b348919 528 /**
MrBedfordVan 0:b9164b348919 529 * Reset any scan response prepared from prior calls to
MrBedfordVan 0:b9164b348919 530 * accumulateScanResponse().
MrBedfordVan 0:b9164b348919 531 *
MrBedfordVan 0:b9164b348919 532 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 533 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 534 * ble.clearScanResponse(...) should be replaced with
MrBedfordVan 0:b9164b348919 535 * ble.gap().clearScanResponse(...).
MrBedfordVan 0:b9164b348919 536 */
MrBedfordVan 0:b9164b348919 537 void clearScanResponse(void) {
MrBedfordVan 0:b9164b348919 538 gap().clearScanResponse();
MrBedfordVan 0:b9164b348919 539 }
MrBedfordVan 0:b9164b348919 540
MrBedfordVan 0:b9164b348919 541 /**
MrBedfordVan 0:b9164b348919 542 * Start advertising.
MrBedfordVan 0:b9164b348919 543 *
MrBedfordVan 0:b9164b348919 544 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 545 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 546 * ble.startAdvertising(...) should be replaced with
MrBedfordVan 0:b9164b348919 547 * ble.gap().startAdvertising(...).
MrBedfordVan 0:b9164b348919 548 */
MrBedfordVan 0:b9164b348919 549 ble_error_t startAdvertising(void) {
MrBedfordVan 0:b9164b348919 550 return gap().startAdvertising();
MrBedfordVan 0:b9164b348919 551 }
MrBedfordVan 0:b9164b348919 552
MrBedfordVan 0:b9164b348919 553 /**
MrBedfordVan 0:b9164b348919 554 * Stop advertising.
MrBedfordVan 0:b9164b348919 555 *
MrBedfordVan 0:b9164b348919 556 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 557 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 558 * ble.stopAdvertising(...) should be replaced with
MrBedfordVan 0:b9164b348919 559 * ble.gap().stopAdvertising(...).
MrBedfordVan 0:b9164b348919 560 */
MrBedfordVan 0:b9164b348919 561 ble_error_t stopAdvertising(void) {
MrBedfordVan 0:b9164b348919 562 return gap().stopAdvertising();
MrBedfordVan 0:b9164b348919 563 }
MrBedfordVan 0:b9164b348919 564
MrBedfordVan 0:b9164b348919 565 /**
MrBedfordVan 0:b9164b348919 566 * Set up parameters for GAP scanning (observer mode).
MrBedfordVan 0:b9164b348919 567 * @param[in] interval
MrBedfordVan 0:b9164b348919 568 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
MrBedfordVan 0:b9164b348919 569 * @param[in] window
MrBedfordVan 0:b9164b348919 570 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
MrBedfordVan 0:b9164b348919 571 * @param[in] timeout
MrBedfordVan 0:b9164b348919 572 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
MrBedfordVan 0:b9164b348919 573 * @param[in] activeScanning
MrBedfordVan 0:b9164b348919 574 * Set to True if active-scanning is required. This is used to fetch the
MrBedfordVan 0:b9164b348919 575 * scan response from a peer if possible.
MrBedfordVan 0:b9164b348919 576 *
MrBedfordVan 0:b9164b348919 577 * The scanning window divided by the interval determines the duty cycle for
MrBedfordVan 0:b9164b348919 578 * scanning. For example, if the interval is 100ms and the window is 10ms,
MrBedfordVan 0:b9164b348919 579 * then the controller will scan for 10 percent of the time. It is possible
MrBedfordVan 0:b9164b348919 580 * to have the interval and window set to the same value. In this case,
MrBedfordVan 0:b9164b348919 581 * scanning is continuous, with a change of scanning frequency once every
MrBedfordVan 0:b9164b348919 582 * interval.
MrBedfordVan 0:b9164b348919 583 *
MrBedfordVan 0:b9164b348919 584 * Once the scanning parameters have been configured, scanning can be
MrBedfordVan 0:b9164b348919 585 * enabled by using startScan().
MrBedfordVan 0:b9164b348919 586 *
MrBedfordVan 0:b9164b348919 587 * @Note: The scan interval and window are recommendations to the BLE stack.
MrBedfordVan 0:b9164b348919 588 *
MrBedfordVan 0:b9164b348919 589 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 590 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 591 * ble.setScanParams(...) should be replaced with
MrBedfordVan 0:b9164b348919 592 * ble.gap().setScanParams(...).
MrBedfordVan 0:b9164b348919 593 */
MrBedfordVan 0:b9164b348919 594 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
MrBedfordVan 0:b9164b348919 595 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
MrBedfordVan 0:b9164b348919 596 uint16_t timeout = 0,
MrBedfordVan 0:b9164b348919 597 bool activeScanning = false) {
MrBedfordVan 0:b9164b348919 598 return gap().setScanParams(interval, window, timeout, activeScanning);
MrBedfordVan 0:b9164b348919 599 }
MrBedfordVan 0:b9164b348919 600
MrBedfordVan 0:b9164b348919 601 /**
MrBedfordVan 0:b9164b348919 602 * Set up the scanInterval parameter for GAP scanning (observer mode).
MrBedfordVan 0:b9164b348919 603 * @param[in] interval
MrBedfordVan 0:b9164b348919 604 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
MrBedfordVan 0:b9164b348919 605 *
MrBedfordVan 0:b9164b348919 606 * The scanning window divided by the interval determines the duty cycle for
MrBedfordVan 0:b9164b348919 607 * scanning. For example, if the interval is 100ms and the window is 10ms,
MrBedfordVan 0:b9164b348919 608 * then the controller will scan for 10 percent of the time. It is possible
MrBedfordVan 0:b9164b348919 609 * to have the interval and window set to the same value. In this case,
MrBedfordVan 0:b9164b348919 610 * scanning is continuous, with a change of scanning frequency once every
MrBedfordVan 0:b9164b348919 611 * interval.
MrBedfordVan 0:b9164b348919 612 *
MrBedfordVan 0:b9164b348919 613 * Once the scanning parameters have been configured, scanning can be
MrBedfordVan 0:b9164b348919 614 * enabled by using startScan().
MrBedfordVan 0:b9164b348919 615 *
MrBedfordVan 0:b9164b348919 616 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 617 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 618 * ble.setScanInterval(interval) should be replaced with
MrBedfordVan 0:b9164b348919 619 * ble.gap().setScanInterval(interval).
MrBedfordVan 0:b9164b348919 620 */
MrBedfordVan 0:b9164b348919 621 ble_error_t setScanInterval(uint16_t interval) {
MrBedfordVan 0:b9164b348919 622 return gap().setScanInterval(interval);
MrBedfordVan 0:b9164b348919 623 }
MrBedfordVan 0:b9164b348919 624
MrBedfordVan 0:b9164b348919 625 /**
MrBedfordVan 0:b9164b348919 626 * Set up the scanWindow parameter for GAP scanning (observer mode).
MrBedfordVan 0:b9164b348919 627 * @param[in] window
MrBedfordVan 0:b9164b348919 628 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
MrBedfordVan 0:b9164b348919 629 *
MrBedfordVan 0:b9164b348919 630 * The scanning window divided by the interval determines the duty cycle for
MrBedfordVan 0:b9164b348919 631 * scanning. For example, if the interval is 100ms and the window is 10ms,
MrBedfordVan 0:b9164b348919 632 * then the controller will scan for 10 percent of the time. It is possible
MrBedfordVan 0:b9164b348919 633 * to have the interval and window set to the same value. In this case,
MrBedfordVan 0:b9164b348919 634 * scanning is continuous, with a change of scanning frequency once every
MrBedfordVan 0:b9164b348919 635 * interval.
MrBedfordVan 0:b9164b348919 636 *
MrBedfordVan 0:b9164b348919 637 * Once the scanning parameters have been configured, scanning can be
MrBedfordVan 0:b9164b348919 638 * enabled by using startScan().
MrBedfordVan 0:b9164b348919 639 *
MrBedfordVan 0:b9164b348919 640 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 641 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 642 * ble.setScanWindow(window) should be replaced with
MrBedfordVan 0:b9164b348919 643 * ble.gap().setScanWindow(window).
MrBedfordVan 0:b9164b348919 644 */
MrBedfordVan 0:b9164b348919 645 ble_error_t setScanWindow(uint16_t window) {
MrBedfordVan 0:b9164b348919 646 return gap().setScanWindow(window);
MrBedfordVan 0:b9164b348919 647 }
MrBedfordVan 0:b9164b348919 648
MrBedfordVan 0:b9164b348919 649 /**
MrBedfordVan 0:b9164b348919 650 * Set up parameters for GAP scanning (observer mode).
MrBedfordVan 0:b9164b348919 651 * @param[in] timeout
MrBedfordVan 0:b9164b348919 652 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
MrBedfordVan 0:b9164b348919 653 *
MrBedfordVan 0:b9164b348919 654 * The scanning window divided by the interval determines the duty cycle for
MrBedfordVan 0:b9164b348919 655 * scanning. For example, if the interval is 100ms and the window is 10ms,
MrBedfordVan 0:b9164b348919 656 * then the controller will scan for 10 percent of the time. It is possible
MrBedfordVan 0:b9164b348919 657 * to have the interval and window set to the same value. In this case,
MrBedfordVan 0:b9164b348919 658 * scanning is continuous, with a change of scanning frequency once every
MrBedfordVan 0:b9164b348919 659 * interval.
MrBedfordVan 0:b9164b348919 660 *
MrBedfordVan 0:b9164b348919 661 * Once the scanning parameters have been configured, scanning can be
MrBedfordVan 0:b9164b348919 662 * enabled by using startScan().
MrBedfordVan 0:b9164b348919 663 *
MrBedfordVan 0:b9164b348919 664 * @Note: The scan interval and window are recommendations to the BLE stack.
MrBedfordVan 0:b9164b348919 665 *
MrBedfordVan 0:b9164b348919 666 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 667 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 668 * ble.setScanTimeout(...) should be replaced with
MrBedfordVan 0:b9164b348919 669 * ble.gap().setScanTimeout(...).
MrBedfordVan 0:b9164b348919 670 */
MrBedfordVan 0:b9164b348919 671 ble_error_t setScanTimeout(uint16_t timeout) {
MrBedfordVan 0:b9164b348919 672 return gap().setScanTimeout(timeout);
MrBedfordVan 0:b9164b348919 673 }
MrBedfordVan 0:b9164b348919 674
MrBedfordVan 0:b9164b348919 675 /**
MrBedfordVan 0:b9164b348919 676 * Set up parameters for GAP scanning (observer mode).
MrBedfordVan 0:b9164b348919 677 * @param[in] activeScanning
MrBedfordVan 0:b9164b348919 678 * Set to True if active-scanning is required. This is used to fetch the
MrBedfordVan 0:b9164b348919 679 * scan response from a peer if possible.
MrBedfordVan 0:b9164b348919 680 *
MrBedfordVan 0:b9164b348919 681 * Once the scanning parameters have been configured, scanning can be
MrBedfordVan 0:b9164b348919 682 * enabled by using startScan().
MrBedfordVan 0:b9164b348919 683 *
MrBedfordVan 0:b9164b348919 684 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 685 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 686 * ble.setActiveScan(...) should be replaced with
MrBedfordVan 0:b9164b348919 687 * ble.gap().setActiveScanning(...).
MrBedfordVan 0:b9164b348919 688 */
MrBedfordVan 0:b9164b348919 689 void setActiveScan(bool activeScanning) {
MrBedfordVan 0:b9164b348919 690 gap().setActiveScanning(activeScanning);
MrBedfordVan 0:b9164b348919 691 }
MrBedfordVan 0:b9164b348919 692
MrBedfordVan 0:b9164b348919 693 /**
MrBedfordVan 0:b9164b348919 694 * Start scanning (Observer Procedure) based on the parameters currently in
MrBedfordVan 0:b9164b348919 695 * effect.
MrBedfordVan 0:b9164b348919 696 *
MrBedfordVan 0:b9164b348919 697 * @param[in] callback
MrBedfordVan 0:b9164b348919 698 * The application-specific callback to be invoked upon
MrBedfordVan 0:b9164b348919 699 * receiving every advertisement report. This can be passed in
MrBedfordVan 0:b9164b348919 700 * as NULL, in which case scanning may not be enabled at all.
MrBedfordVan 0:b9164b348919 701 *
MrBedfordVan 0:b9164b348919 702 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 703 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 704 * ble.startScan(callback) should be replaced with
MrBedfordVan 0:b9164b348919 705 * ble.gap().startScan(callback).
MrBedfordVan 0:b9164b348919 706 */
MrBedfordVan 0:b9164b348919 707 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
MrBedfordVan 0:b9164b348919 708 return gap().startScan(callback);
MrBedfordVan 0:b9164b348919 709 }
MrBedfordVan 0:b9164b348919 710
MrBedfordVan 0:b9164b348919 711 /**
MrBedfordVan 0:b9164b348919 712 * Same as above, but this takes an (object, method) pair for a callback.
MrBedfordVan 0:b9164b348919 713 *
MrBedfordVan 0:b9164b348919 714 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 715 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 716 * ble.startScan(callback) should be replaced with
MrBedfordVan 0:b9164b348919 717 * ble.gap().startScan(object, callback).
MrBedfordVan 0:b9164b348919 718 */
MrBedfordVan 0:b9164b348919 719 template<typename T>
MrBedfordVan 0:b9164b348919 720 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
MrBedfordVan 0:b9164b348919 721
MrBedfordVan 0:b9164b348919 722 /**
MrBedfordVan 0:b9164b348919 723 * Stop scanning. The current scanning parameters remain in effect.
MrBedfordVan 0:b9164b348919 724 *
MrBedfordVan 0:b9164b348919 725 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
MrBedfordVan 0:b9164b348919 726 *
MrBedfordVan 0:b9164b348919 727 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 728 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 729 * ble.stopScan() should be replaced with
MrBedfordVan 0:b9164b348919 730 * ble.gap().stopScan().
MrBedfordVan 0:b9164b348919 731 */
MrBedfordVan 0:b9164b348919 732 ble_error_t stopScan(void) {
MrBedfordVan 0:b9164b348919 733 return gap().stopScan();
MrBedfordVan 0:b9164b348919 734 }
MrBedfordVan 0:b9164b348919 735
MrBedfordVan 0:b9164b348919 736 /**
MrBedfordVan 0:b9164b348919 737 * Create a connection (GAP Link Establishment).
MrBedfordVan 0:b9164b348919 738 * @param peerAddr
MrBedfordVan 0:b9164b348919 739 * 48-bit address, LSB format.
MrBedfordVan 0:b9164b348919 740 * @param peerAddrType
MrBedfordVan 0:b9164b348919 741 * Address type of the peer.
MrBedfordVan 0:b9164b348919 742 * @param connectionParams
MrBedfordVan 0:b9164b348919 743 * Connection parameters.
MrBedfordVan 0:b9164b348919 744 * @param scanParams
MrBedfordVan 0:b9164b348919 745 * Paramters to use while scanning for the peer.
MrBedfordVan 0:b9164b348919 746 * @return BLE_ERROR_NONE if connection establishment procedure is started
MrBedfordVan 0:b9164b348919 747 * successfully. The onConnection callback (if set) is invoked upon
MrBedfordVan 0:b9164b348919 748 * a connection event.
MrBedfordVan 0:b9164b348919 749 *
MrBedfordVan 0:b9164b348919 750 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 751 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 752 * ble.connect(...) should be replaced with
MrBedfordVan 0:b9164b348919 753 * ble.gap().connect(...).
MrBedfordVan 0:b9164b348919 754 */
MrBedfordVan 0:b9164b348919 755 ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
MrBedfordVan 0:b9164b348919 756 BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
MrBedfordVan 0:b9164b348919 757 const Gap::ConnectionParams_t *connectionParams = NULL,
MrBedfordVan 0:b9164b348919 758 const GapScanningParams *scanParams = NULL) {
MrBedfordVan 0:b9164b348919 759 return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
MrBedfordVan 0:b9164b348919 760 }
MrBedfordVan 0:b9164b348919 761
MrBedfordVan 0:b9164b348919 762 /**
MrBedfordVan 0:b9164b348919 763 * This call initiates the disconnection procedure, and its completion is
MrBedfordVan 0:b9164b348919 764 * communicated to the application with an invocation of the
MrBedfordVan 0:b9164b348919 765 * onDisconnection callback.
MrBedfordVan 0:b9164b348919 766 *
MrBedfordVan 0:b9164b348919 767 * @param[in] connectionHandle
MrBedfordVan 0:b9164b348919 768 * @param[in] reason
MrBedfordVan 0:b9164b348919 769 * The reason for disconnection; sent back to the peer.
MrBedfordVan 0:b9164b348919 770 */
MrBedfordVan 0:b9164b348919 771 ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) {
MrBedfordVan 0:b9164b348919 772 return gap().disconnect(connectionHandle, reason);
MrBedfordVan 0:b9164b348919 773 }
MrBedfordVan 0:b9164b348919 774
MrBedfordVan 0:b9164b348919 775 /**
MrBedfordVan 0:b9164b348919 776 * This call initiates the disconnection procedure, and its completion
MrBedfordVan 0:b9164b348919 777 * is communicated to the application with an invocation of the
MrBedfordVan 0:b9164b348919 778 * onDisconnection callback.
MrBedfordVan 0:b9164b348919 779 *
MrBedfordVan 0:b9164b348919 780 * @param reason
MrBedfordVan 0:b9164b348919 781 * The reason for disconnection; sent back to the peer.
MrBedfordVan 0:b9164b348919 782 *
MrBedfordVan 0:b9164b348919 783 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 784 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 785 * ble.disconnect(reason) should be replaced with
MrBedfordVan 0:b9164b348919 786 * ble.gap().disconnect(reason).
MrBedfordVan 0:b9164b348919 787 *
MrBedfordVan 0:b9164b348919 788 * @note: This version of disconnect() doesn't take a connection handle. It
MrBedfordVan 0:b9164b348919 789 * works reliably only for stacks that are limited to a single
MrBedfordVan 0:b9164b348919 790 * connection. This API should be considered *deprecated* in favour of the
MrBedfordVan 0:b9164b348919 791 * alternative, which takes a connection handle. It will be dropped in the future.
MrBedfordVan 0:b9164b348919 792 */
MrBedfordVan 0:b9164b348919 793 ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
MrBedfordVan 0:b9164b348919 794 return gap().disconnect(reason);
MrBedfordVan 0:b9164b348919 795 }
MrBedfordVan 0:b9164b348919 796
MrBedfordVan 0:b9164b348919 797 /**
MrBedfordVan 0:b9164b348919 798 * Returns the current GAP state of the device using a bitmask that
MrBedfordVan 0:b9164b348919 799 * describes whether the device is advertising or connected.
MrBedfordVan 0:b9164b348919 800 *
MrBedfordVan 0:b9164b348919 801 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 802 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 803 * ble.getGapState() should be replaced with
MrBedfordVan 0:b9164b348919 804 * ble.gap().getState().
MrBedfordVan 0:b9164b348919 805 */
MrBedfordVan 0:b9164b348919 806 Gap::GapState_t getGapState(void) const {
MrBedfordVan 0:b9164b348919 807 return gap().getState();
MrBedfordVan 0:b9164b348919 808 }
MrBedfordVan 0:b9164b348919 809
MrBedfordVan 0:b9164b348919 810 /**
MrBedfordVan 0:b9164b348919 811 * Get the GAP peripheral's preferred connection parameters. These are the
MrBedfordVan 0:b9164b348919 812 * defaults that the peripheral would like to have in a connection. The
MrBedfordVan 0:b9164b348919 813 * choice of the connection parameters is eventually up to the central.
MrBedfordVan 0:b9164b348919 814 *
MrBedfordVan 0:b9164b348919 815 * @param[out] params
MrBedfordVan 0:b9164b348919 816 * The structure where the parameters will be stored. Memory
MrBedfordVan 0:b9164b348919 817 * for this is owned by the caller.
MrBedfordVan 0:b9164b348919 818 *
MrBedfordVan 0:b9164b348919 819 * @return BLE_ERROR_NONE if the parameters were successfully filled into
MrBedfordVan 0:b9164b348919 820 * the given structure pointed to by params.
MrBedfordVan 0:b9164b348919 821 *
MrBedfordVan 0:b9164b348919 822 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 823 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 824 * ble.getPreferredConnectionParams() should be replaced with
MrBedfordVan 0:b9164b348919 825 * ble.gap().getPreferredConnectionParams().
MrBedfordVan 0:b9164b348919 826 */
MrBedfordVan 0:b9164b348919 827 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
MrBedfordVan 0:b9164b348919 828 return gap().getPreferredConnectionParams(params);
MrBedfordVan 0:b9164b348919 829 }
MrBedfordVan 0:b9164b348919 830
MrBedfordVan 0:b9164b348919 831 /**
MrBedfordVan 0:b9164b348919 832 * Set the GAP peripheral's preferred connection parameters. These are the
MrBedfordVan 0:b9164b348919 833 * defaults that the peripheral would like to have in a connection. The
MrBedfordVan 0:b9164b348919 834 * choice of the connection parameters is eventually up to the central.
MrBedfordVan 0:b9164b348919 835 *
MrBedfordVan 0:b9164b348919 836 * @param[in] params
MrBedfordVan 0:b9164b348919 837 * The structure containing the desired parameters.
MrBedfordVan 0:b9164b348919 838 *
MrBedfordVan 0:b9164b348919 839 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 840 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 841 * ble.setPreferredConnectionParams() should be replaced with
MrBedfordVan 0:b9164b348919 842 * ble.gap().setPreferredConnectionParams().
MrBedfordVan 0:b9164b348919 843 */
MrBedfordVan 0:b9164b348919 844 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
MrBedfordVan 0:b9164b348919 845 return gap().setPreferredConnectionParams(params);
MrBedfordVan 0:b9164b348919 846 }
MrBedfordVan 0:b9164b348919 847
MrBedfordVan 0:b9164b348919 848 /**
MrBedfordVan 0:b9164b348919 849 * Update connection parameters while in the peripheral role.
MrBedfordVan 0:b9164b348919 850 * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
MrBedfordVan 0:b9164b348919 851 * the central to perform the procedure.
MrBedfordVan 0:b9164b348919 852 * @param[in] handle
MrBedfordVan 0:b9164b348919 853 * Connection Handle
MrBedfordVan 0:b9164b348919 854 * @param[in] params
MrBedfordVan 0:b9164b348919 855 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
MrBedfordVan 0:b9164b348919 856 * the parameters in the PPCP characteristic of the GAP service will be used instead.
MrBedfordVan 0:b9164b348919 857 *
MrBedfordVan 0:b9164b348919 858 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 859 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 860 * ble.updateConnectionParams() should be replaced with
MrBedfordVan 0:b9164b348919 861 * ble.gap().updateConnectionParams().
MrBedfordVan 0:b9164b348919 862 */
MrBedfordVan 0:b9164b348919 863 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
MrBedfordVan 0:b9164b348919 864 return gap().updateConnectionParams(handle, params);
MrBedfordVan 0:b9164b348919 865 }
MrBedfordVan 0:b9164b348919 866
MrBedfordVan 0:b9164b348919 867 /**
MrBedfordVan 0:b9164b348919 868 * Set the device name characteristic in the GAP service.
MrBedfordVan 0:b9164b348919 869 * @param[in] deviceName
MrBedfordVan 0:b9164b348919 870 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
MrBedfordVan 0:b9164b348919 871 *
MrBedfordVan 0:b9164b348919 872 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 873 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 874 * ble.setDeviceName() should be replaced with
MrBedfordVan 0:b9164b348919 875 * ble.gap().setDeviceName().
MrBedfordVan 0:b9164b348919 876 */
MrBedfordVan 0:b9164b348919 877 ble_error_t setDeviceName(const uint8_t *deviceName) {
MrBedfordVan 0:b9164b348919 878 return gap().setDeviceName(deviceName);
MrBedfordVan 0:b9164b348919 879 }
MrBedfordVan 0:b9164b348919 880
MrBedfordVan 0:b9164b348919 881 /**
MrBedfordVan 0:b9164b348919 882 * Get the value of the device name characteristic in the GAP service.
MrBedfordVan 0:b9164b348919 883 * @param[out] deviceName
MrBedfordVan 0:b9164b348919 884 * Pointer to an empty buffer where the UTF-8 *non NULL-
MrBedfordVan 0:b9164b348919 885 * terminated* string will be placed. Set this
MrBedfordVan 0:b9164b348919 886 * value to NULL in order to obtain the deviceName-length
MrBedfordVan 0:b9164b348919 887 * from the 'length' parameter.
MrBedfordVan 0:b9164b348919 888 *
MrBedfordVan 0:b9164b348919 889 * @param[in/out] lengthP
MrBedfordVan 0:b9164b348919 890 * (on input) Length of the buffer pointed to by deviceName;
MrBedfordVan 0:b9164b348919 891 * (on output) the complete device name length (without the
MrBedfordVan 0:b9164b348919 892 * null terminator).
MrBedfordVan 0:b9164b348919 893 *
MrBedfordVan 0:b9164b348919 894 * @note If the device name is longer than the size of the supplied buffer,
MrBedfordVan 0:b9164b348919 895 * length will return the complete device name length, and not the
MrBedfordVan 0:b9164b348919 896 * number of bytes actually returned in deviceName. The application may
MrBedfordVan 0:b9164b348919 897 * use this information to retry with a suitable buffer size.
MrBedfordVan 0:b9164b348919 898 *
MrBedfordVan 0:b9164b348919 899 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 900 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 901 * ble.getDeviceName() should be replaced with
MrBedfordVan 0:b9164b348919 902 * ble.gap().getDeviceName().
MrBedfordVan 0:b9164b348919 903 */
MrBedfordVan 0:b9164b348919 904 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
MrBedfordVan 0:b9164b348919 905 return gap().getDeviceName(deviceName, lengthP);
MrBedfordVan 0:b9164b348919 906 }
MrBedfordVan 0:b9164b348919 907
MrBedfordVan 0:b9164b348919 908 /**
MrBedfordVan 0:b9164b348919 909 * Set the appearance characteristic in the GAP service.
MrBedfordVan 0:b9164b348919 910 * @param[in] appearance
MrBedfordVan 0:b9164b348919 911 * The new value for the device-appearance.
MrBedfordVan 0:b9164b348919 912 *
MrBedfordVan 0:b9164b348919 913 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 914 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 915 * ble.setAppearance() should be replaced with
MrBedfordVan 0:b9164b348919 916 * ble.gap().setAppearance().
MrBedfordVan 0:b9164b348919 917 */
MrBedfordVan 0:b9164b348919 918 ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
MrBedfordVan 0:b9164b348919 919 return gap().setAppearance(appearance);
MrBedfordVan 0:b9164b348919 920 }
MrBedfordVan 0:b9164b348919 921
MrBedfordVan 0:b9164b348919 922 /**
MrBedfordVan 0:b9164b348919 923 * Get the appearance characteristic in the GAP service.
MrBedfordVan 0:b9164b348919 924 * @param[out] appearance
MrBedfordVan 0:b9164b348919 925 * The new value for the device-appearance.
MrBedfordVan 0:b9164b348919 926 *
MrBedfordVan 0:b9164b348919 927 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 928 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 929 * ble.getAppearance() should be replaced with
MrBedfordVan 0:b9164b348919 930 * ble.gap().getAppearance().
MrBedfordVan 0:b9164b348919 931 */
MrBedfordVan 0:b9164b348919 932 ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
MrBedfordVan 0:b9164b348919 933 return gap().getAppearance(appearanceP);
MrBedfordVan 0:b9164b348919 934 }
MrBedfordVan 0:b9164b348919 935
MrBedfordVan 0:b9164b348919 936 /**
MrBedfordVan 0:b9164b348919 937 * Set the radio's transmit power.
MrBedfordVan 0:b9164b348919 938 * @param[in] txPower Radio transmit power in dBm.
MrBedfordVan 0:b9164b348919 939 *
MrBedfordVan 0:b9164b348919 940 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 941 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 942 * ble.setTxPower() should be replaced with
MrBedfordVan 0:b9164b348919 943 * ble.gap().setTxPower().
MrBedfordVan 0:b9164b348919 944 */
MrBedfordVan 0:b9164b348919 945 ble_error_t setTxPower(int8_t txPower) {
MrBedfordVan 0:b9164b348919 946 return gap().setTxPower(txPower);
MrBedfordVan 0:b9164b348919 947 }
MrBedfordVan 0:b9164b348919 948
MrBedfordVan 0:b9164b348919 949 /**
MrBedfordVan 0:b9164b348919 950 * Query the underlying stack for permitted arguments for setTxPower().
MrBedfordVan 0:b9164b348919 951 *
MrBedfordVan 0:b9164b348919 952 * @param[out] valueArrayPP
MrBedfordVan 0:b9164b348919 953 * Out parameter to receive the immutable array of Tx values.
MrBedfordVan 0:b9164b348919 954 * @param[out] countP
MrBedfordVan 0:b9164b348919 955 * Out parameter to receive the array's size.
MrBedfordVan 0:b9164b348919 956 *
MrBedfordVan 0:b9164b348919 957 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 958 * You should use the parallel API from Gap directly. A former call to
MrBedfordVan 0:b9164b348919 959 * ble.getPermittedTxPowerValues() should be replaced with
MrBedfordVan 0:b9164b348919 960 * ble.gap().getPermittedTxPowerValues().
MrBedfordVan 0:b9164b348919 961 */
MrBedfordVan 0:b9164b348919 962 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
MrBedfordVan 0:b9164b348919 963 gap().getPermittedTxPowerValues(valueArrayPP, countP);
MrBedfordVan 0:b9164b348919 964 }
MrBedfordVan 0:b9164b348919 965
MrBedfordVan 0:b9164b348919 966 /**
MrBedfordVan 0:b9164b348919 967 * Add a service declaration to the local server ATT table. Also add the
MrBedfordVan 0:b9164b348919 968 * characteristics contained within.
MrBedfordVan 0:b9164b348919 969 *
MrBedfordVan 0:b9164b348919 970 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 971 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 972 * to ble.addService() should be replaced with
MrBedfordVan 0:b9164b348919 973 * ble.gattServer().addService().
MrBedfordVan 0:b9164b348919 974 */
MrBedfordVan 0:b9164b348919 975 ble_error_t addService(GattService &service) {
MrBedfordVan 0:b9164b348919 976 return gattServer().addService(service);
MrBedfordVan 0:b9164b348919 977 }
MrBedfordVan 0:b9164b348919 978
MrBedfordVan 0:b9164b348919 979 /**
MrBedfordVan 0:b9164b348919 980 * Read the value of a characteristic from the local GattServer.
MrBedfordVan 0:b9164b348919 981 * @param[in] attributeHandle
MrBedfordVan 0:b9164b348919 982 * Attribute handle for the value attribute of the characteristic.
MrBedfordVan 0:b9164b348919 983 * @param[out] buffer
MrBedfordVan 0:b9164b348919 984 * A buffer to hold the value being read.
MrBedfordVan 0:b9164b348919 985 * @param[in/out] lengthP
MrBedfordVan 0:b9164b348919 986 * Length of the buffer being supplied. If the attribute
MrBedfordVan 0:b9164b348919 987 * value is longer than the size of the supplied buffer,
MrBedfordVan 0:b9164b348919 988 * this variable will return the total attribute value length
MrBedfordVan 0:b9164b348919 989 * (excluding offset). The application may use this
MrBedfordVan 0:b9164b348919 990 * information to allocate a suitable buffer size.
MrBedfordVan 0:b9164b348919 991 *
MrBedfordVan 0:b9164b348919 992 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
MrBedfordVan 0:b9164b348919 993 *
MrBedfordVan 0:b9164b348919 994 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 995 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 996 * to ble.readCharacteristicValue() should be replaced with
MrBedfordVan 0:b9164b348919 997 * ble.gattServer().read().
MrBedfordVan 0:b9164b348919 998 */
MrBedfordVan 0:b9164b348919 999 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
MrBedfordVan 0:b9164b348919 1000 return gattServer().read(attributeHandle, buffer, lengthP);
MrBedfordVan 0:b9164b348919 1001 }
MrBedfordVan 0:b9164b348919 1002
MrBedfordVan 0:b9164b348919 1003 /**
MrBedfordVan 0:b9164b348919 1004 * Read the value of a characteristic from the local GattServer.
MrBedfordVan 0:b9164b348919 1005 * @param[in] connectionHandle
MrBedfordVan 0:b9164b348919 1006 * Connection Handle.
MrBedfordVan 0:b9164b348919 1007 * @param[in] attributeHandle
MrBedfordVan 0:b9164b348919 1008 * Attribute handle for the value attribute of the characteristic.
MrBedfordVan 0:b9164b348919 1009 * @param[out] buffer
MrBedfordVan 0:b9164b348919 1010 * A buffer to hold the value being read.
MrBedfordVan 0:b9164b348919 1011 * @param[in/out] lengthP
MrBedfordVan 0:b9164b348919 1012 * Length of the buffer being supplied. If the attribute
MrBedfordVan 0:b9164b348919 1013 * value is longer than the size of the supplied buffer,
MrBedfordVan 0:b9164b348919 1014 * this variable will return the total attribute value length
MrBedfordVan 0:b9164b348919 1015 * (excluding offset). The application may use this
MrBedfordVan 0:b9164b348919 1016 * information to allocate a suitable buffer size.
MrBedfordVan 0:b9164b348919 1017 *
MrBedfordVan 0:b9164b348919 1018 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
MrBedfordVan 0:b9164b348919 1019 *
MrBedfordVan 0:b9164b348919 1020 * @note This API is a version of the above, with an additional connection handle
MrBedfordVan 0:b9164b348919 1021 * parameter to allow fetches for connection-specific multivalued
MrBedfordVan 0:b9164b348919 1022 * attributes (such as the CCCDs).
MrBedfordVan 0:b9164b348919 1023 *
MrBedfordVan 0:b9164b348919 1024 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1025 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1026 * to ble.readCharacteristicValue() should be replaced with
MrBedfordVan 0:b9164b348919 1027 * ble.gattServer().read().
MrBedfordVan 0:b9164b348919 1028 */
MrBedfordVan 0:b9164b348919 1029 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
MrBedfordVan 0:b9164b348919 1030 return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
MrBedfordVan 0:b9164b348919 1031 }
MrBedfordVan 0:b9164b348919 1032
MrBedfordVan 0:b9164b348919 1033 /**
MrBedfordVan 0:b9164b348919 1034 * Update the value of a characteristic on the local GattServer.
MrBedfordVan 0:b9164b348919 1035 *
MrBedfordVan 0:b9164b348919 1036 * @param[in] attributeHandle
MrBedfordVan 0:b9164b348919 1037 * Handle for the value attribute of the characteristic.
MrBedfordVan 0:b9164b348919 1038 * @param[in] value
MrBedfordVan 0:b9164b348919 1039 * A pointer to a buffer holding the new value.
MrBedfordVan 0:b9164b348919 1040 * @param[in] size
MrBedfordVan 0:b9164b348919 1041 * Size of the new value (in bytes).
MrBedfordVan 0:b9164b348919 1042 * @param[in] localOnly
MrBedfordVan 0:b9164b348919 1043 * Should this update be kept on the local
MrBedfordVan 0:b9164b348919 1044 * GattServer regardless of the state of the
MrBedfordVan 0:b9164b348919 1045 * notify/indicate flag in the CCCD for this
MrBedfordVan 0:b9164b348919 1046 * characteristic? If set to true, no notification
MrBedfordVan 0:b9164b348919 1047 * or indication is generated.
MrBedfordVan 0:b9164b348919 1048 *
MrBedfordVan 0:b9164b348919 1049 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
MrBedfordVan 0:b9164b348919 1050 *
MrBedfordVan 0:b9164b348919 1051 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1052 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1053 * to ble.updateCharacteristicValue() should be replaced with
MrBedfordVan 0:b9164b348919 1054 * ble.gattServer().write().
MrBedfordVan 0:b9164b348919 1055 */
MrBedfordVan 0:b9164b348919 1056 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
MrBedfordVan 0:b9164b348919 1057 const uint8_t *value,
MrBedfordVan 0:b9164b348919 1058 uint16_t size,
MrBedfordVan 0:b9164b348919 1059 bool localOnly = false) {
MrBedfordVan 0:b9164b348919 1060 return gattServer().write(attributeHandle, value, size, localOnly);
MrBedfordVan 0:b9164b348919 1061 }
MrBedfordVan 0:b9164b348919 1062
MrBedfordVan 0:b9164b348919 1063 /**
MrBedfordVan 0:b9164b348919 1064 * Update the value of a characteristic on the local GattServer. A version
MrBedfordVan 0:b9164b348919 1065 * of the above, with a connection handle parameter to allow updates
MrBedfordVan 0:b9164b348919 1066 * for connection-specific multivalued attributes (such as the CCCDs).
MrBedfordVan 0:b9164b348919 1067 *
MrBedfordVan 0:b9164b348919 1068 * @param[in] connectionHandle
MrBedfordVan 0:b9164b348919 1069 * Connection Handle.
MrBedfordVan 0:b9164b348919 1070 * @param[in] attributeHandle
MrBedfordVan 0:b9164b348919 1071 * Handle for the value attribute of the Characteristic.
MrBedfordVan 0:b9164b348919 1072 * @param[in] value
MrBedfordVan 0:b9164b348919 1073 * A pointer to a buffer holding the new value.
MrBedfordVan 0:b9164b348919 1074 * @param[in] size
MrBedfordVan 0:b9164b348919 1075 * Size of the new value (in bytes).
MrBedfordVan 0:b9164b348919 1076 * @param[in] localOnly
MrBedfordVan 0:b9164b348919 1077 * Should this update be kept on the local
MrBedfordVan 0:b9164b348919 1078 * GattServer regardless of the state of the
MrBedfordVan 0:b9164b348919 1079 * notify/indicate flag in the CCCD for this
MrBedfordVan 0:b9164b348919 1080 * Characteristic? If set to true, no notification
MrBedfordVan 0:b9164b348919 1081 * or indication is generated.
MrBedfordVan 0:b9164b348919 1082 *
MrBedfordVan 0:b9164b348919 1083 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
MrBedfordVan 0:b9164b348919 1084 *
MrBedfordVan 0:b9164b348919 1085 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1086 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1087 * to ble.updateCharacteristicValue() should be replaced with
MrBedfordVan 0:b9164b348919 1088 * ble.gattServer().write().
MrBedfordVan 0:b9164b348919 1089 */
MrBedfordVan 0:b9164b348919 1090 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
MrBedfordVan 0:b9164b348919 1091 GattAttribute::Handle_t attributeHandle,
MrBedfordVan 0:b9164b348919 1092 const uint8_t *value,
MrBedfordVan 0:b9164b348919 1093 uint16_t size,
MrBedfordVan 0:b9164b348919 1094 bool localOnly = false) {
MrBedfordVan 0:b9164b348919 1095 return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
MrBedfordVan 0:b9164b348919 1096 }
MrBedfordVan 0:b9164b348919 1097
MrBedfordVan 0:b9164b348919 1098 /**
MrBedfordVan 0:b9164b348919 1099 * Enable the BLE stack's Security Manager. The Security Manager implements
MrBedfordVan 0:b9164b348919 1100 * the cryptographic algorithms and protocol exchanges that allow two
MrBedfordVan 0:b9164b348919 1101 * devices to securely exchange data and privately detect each other.
MrBedfordVan 0:b9164b348919 1102 * Calling this API is a prerequisite for encryption and pairing (bonding).
MrBedfordVan 0:b9164b348919 1103 *
MrBedfordVan 0:b9164b348919 1104 * @param[in] enableBonding Allow for bonding.
MrBedfordVan 0:b9164b348919 1105 * @param[in] requireMITM Require protection against man-in-the-middle attacks.
MrBedfordVan 0:b9164b348919 1106 * @param[in] iocaps To specify the I/O capabilities of this peripheral,
MrBedfordVan 0:b9164b348919 1107 * such as availability of a display or keyboard, to
MrBedfordVan 0:b9164b348919 1108 * support out-of-band exchanges of security data.
MrBedfordVan 0:b9164b348919 1109 * @param[in] passkey To specify a static passkey.
MrBedfordVan 0:b9164b348919 1110 *
MrBedfordVan 0:b9164b348919 1111 * @return BLE_ERROR_NONE on success.
MrBedfordVan 0:b9164b348919 1112 *
MrBedfordVan 0:b9164b348919 1113 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1114 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1115 * call to ble.initializeSecurity(...) should be replaced with
MrBedfordVan 0:b9164b348919 1116 * ble.securityManager().init(...).
MrBedfordVan 0:b9164b348919 1117 */
MrBedfordVan 0:b9164b348919 1118 ble_error_t initializeSecurity(bool enableBonding = true,
MrBedfordVan 0:b9164b348919 1119 bool requireMITM = true,
MrBedfordVan 0:b9164b348919 1120 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
MrBedfordVan 0:b9164b348919 1121 const SecurityManager::Passkey_t passkey = NULL) {
MrBedfordVan 0:b9164b348919 1122 return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
MrBedfordVan 0:b9164b348919 1123 }
MrBedfordVan 0:b9164b348919 1124
MrBedfordVan 0:b9164b348919 1125 /**
MrBedfordVan 0:b9164b348919 1126 * Get the security status of a connection.
MrBedfordVan 0:b9164b348919 1127 *
MrBedfordVan 0:b9164b348919 1128 * @param[in] connectionHandle Handle to identify the connection.
MrBedfordVan 0:b9164b348919 1129 * @param[out] securityStatusP Security status.
MrBedfordVan 0:b9164b348919 1130 *
MrBedfordVan 0:b9164b348919 1131 * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
MrBedfordVan 0:b9164b348919 1132 *
MrBedfordVan 0:b9164b348919 1133 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1134 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1135 * call to ble.getLinkSecurity(...) should be replaced with
MrBedfordVan 0:b9164b348919 1136 * ble.securityManager().getLinkSecurity(...).
MrBedfordVan 0:b9164b348919 1137 */
MrBedfordVan 0:b9164b348919 1138 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
MrBedfordVan 0:b9164b348919 1139 return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
MrBedfordVan 0:b9164b348919 1140 }
MrBedfordVan 0:b9164b348919 1141
MrBedfordVan 0:b9164b348919 1142 /**
MrBedfordVan 0:b9164b348919 1143 * Delete all peer device context and all related bonding information from
MrBedfordVan 0:b9164b348919 1144 * the database within the security manager.
MrBedfordVan 0:b9164b348919 1145 *
MrBedfordVan 0:b9164b348919 1146 * @retval BLE_ERROR_NONE On success; else returns an error code indicating the reason for the failure.
MrBedfordVan 0:b9164b348919 1147 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
MrBedfordVan 0:b9164b348919 1148 * application registration.
MrBedfordVan 0:b9164b348919 1149 *
MrBedfordVan 0:b9164b348919 1150 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1151 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1152 * call to ble.purgeAllBondingState() should be replaced with
MrBedfordVan 0:b9164b348919 1153 * ble.securityManager().purgeAllBondingState().
MrBedfordVan 0:b9164b348919 1154 */
MrBedfordVan 0:b9164b348919 1155 ble_error_t purgeAllBondingState(void) {
MrBedfordVan 0:b9164b348919 1156 return securityManager().purgeAllBondingState();
MrBedfordVan 0:b9164b348919 1157 }
MrBedfordVan 0:b9164b348919 1158
MrBedfordVan 0:b9164b348919 1159 /**
MrBedfordVan 0:b9164b348919 1160 * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
MrBedfordVan 0:b9164b348919 1161 * possible event types.
MrBedfordVan 0:b9164b348919 1162 *
MrBedfordVan 0:b9164b348919 1163 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1164 * You should use the parallel API from Gap directly. A former call
MrBedfordVan 0:b9164b348919 1165 * to ble.onTimeout(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1166 * ble.gap().onTimeout(callback).
MrBedfordVan 0:b9164b348919 1167 */
MrBedfordVan 0:b9164b348919 1168 void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
MrBedfordVan 0:b9164b348919 1169 gap().onTimeout(timeoutCallback);
MrBedfordVan 0:b9164b348919 1170 }
MrBedfordVan 0:b9164b348919 1171
MrBedfordVan 0:b9164b348919 1172 /**
MrBedfordVan 0:b9164b348919 1173 * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
MrBedfordVan 0:b9164b348919 1174 *
MrBedfordVan 0:b9164b348919 1175 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1176 * You should use the parallel API from Gap directly. A former call
MrBedfordVan 0:b9164b348919 1177 * to ble.onConnection(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1178 * ble.gap().onConnection(callback).
MrBedfordVan 0:b9164b348919 1179 */
MrBedfordVan 0:b9164b348919 1180 void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
MrBedfordVan 0:b9164b348919 1181 gap().onConnection(connectionCallback);
MrBedfordVan 0:b9164b348919 1182 }
MrBedfordVan 0:b9164b348919 1183
MrBedfordVan 0:b9164b348919 1184 /**
MrBedfordVan 0:b9164b348919 1185 * Append to a chain of callbacks to be invoked upon GAP disconnection.
MrBedfordVan 0:b9164b348919 1186 *
MrBedfordVan 0:b9164b348919 1187 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1188 * You should use the parallel API from Gap directly. A former call
MrBedfordVan 0:b9164b348919 1189 * to ble.onDisconnection(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1190 * ble.gap().onDisconnection(callback).
MrBedfordVan 0:b9164b348919 1191 */
MrBedfordVan 0:b9164b348919 1192 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
MrBedfordVan 0:b9164b348919 1193 gap().onDisconnection(disconnectionCallback);
MrBedfordVan 0:b9164b348919 1194 }
MrBedfordVan 0:b9164b348919 1195
MrBedfordVan 0:b9164b348919 1196 template<typename T>
MrBedfordVan 0:b9164b348919 1197 void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
MrBedfordVan 0:b9164b348919 1198 gap().onDisconnection(tptr, mptr);
MrBedfordVan 0:b9164b348919 1199 }
MrBedfordVan 0:b9164b348919 1200
MrBedfordVan 0:b9164b348919 1201 /**
MrBedfordVan 0:b9164b348919 1202 * Radio Notification is a feature that enables ACTIVE and INACTIVE
MrBedfordVan 0:b9164b348919 1203 * (nACTIVE) signals from the stack. These notify the application when the
MrBedfordVan 0:b9164b348919 1204 * radio is in use. The signal is sent using software interrupt.
MrBedfordVan 0:b9164b348919 1205 *
MrBedfordVan 0:b9164b348919 1206 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
MrBedfordVan 0:b9164b348919 1207 * signal is sent at the end of the radio event. These signals can be used
MrBedfordVan 0:b9164b348919 1208 * by the application programmer to synchronize application logic with radio
MrBedfordVan 0:b9164b348919 1209 * activity. For example, the ACTIVE signal can be used to shut off external
MrBedfordVan 0:b9164b348919 1210 * devices to manage peak current drawn during periods when the radio is on,
MrBedfordVan 0:b9164b348919 1211 * or to trigger sensor data collection for transmission in the radio event.
MrBedfordVan 0:b9164b348919 1212 *
MrBedfordVan 0:b9164b348919 1213 * @param callback
MrBedfordVan 0:b9164b348919 1214 * The application handler to be invoked in response to a radio
MrBedfordVan 0:b9164b348919 1215 * ACTIVE/INACTIVE event.
MrBedfordVan 0:b9164b348919 1216 *
MrBedfordVan 0:b9164b348919 1217 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1218 * You should use the parallel API from Gap directly. A former call
MrBedfordVan 0:b9164b348919 1219 * to ble.onRadioNotification(...) should be replaced with
MrBedfordVan 0:b9164b348919 1220 * ble.gap().onRadioNotification(...).
MrBedfordVan 0:b9164b348919 1221 */
MrBedfordVan 0:b9164b348919 1222 void onRadioNotification(void (*callback)(bool)) {
MrBedfordVan 0:b9164b348919 1223 gap().onRadioNotification(callback);
MrBedfordVan 0:b9164b348919 1224 }
MrBedfordVan 0:b9164b348919 1225
MrBedfordVan 0:b9164b348919 1226 /**
MrBedfordVan 0:b9164b348919 1227 * Add a callback for the GATT event DATA_SENT (which is triggered when
MrBedfordVan 0:b9164b348919 1228 * updates are sent out by GATT in the form of notifications).
MrBedfordVan 0:b9164b348919 1229 *
MrBedfordVan 0:b9164b348919 1230 * @Note: It is possible to chain together multiple onDataSent callbacks
MrBedfordVan 0:b9164b348919 1231 * (potentially from different modules of an application) to receive updates
MrBedfordVan 0:b9164b348919 1232 * to characteristics.
MrBedfordVan 0:b9164b348919 1233 *
MrBedfordVan 0:b9164b348919 1234 * @Note: It is also possible to set up a callback into a member function of
MrBedfordVan 0:b9164b348919 1235 * some object.
MrBedfordVan 0:b9164b348919 1236 *
MrBedfordVan 0:b9164b348919 1237 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1238 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1239 * to ble.onDataSent(...) should be replaced with
MrBedfordVan 0:b9164b348919 1240 * ble.gattServer().onDataSent(...).
MrBedfordVan 0:b9164b348919 1241 */
MrBedfordVan 0:b9164b348919 1242 void onDataSent(void (*callback)(unsigned count)) {
MrBedfordVan 0:b9164b348919 1243 gattServer().onDataSent(callback);
MrBedfordVan 0:b9164b348919 1244 }
MrBedfordVan 0:b9164b348919 1245 template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
MrBedfordVan 0:b9164b348919 1246 gattServer().onDataSent(objPtr, memberPtr);
MrBedfordVan 0:b9164b348919 1247 }
MrBedfordVan 0:b9164b348919 1248
MrBedfordVan 0:b9164b348919 1249 /**
MrBedfordVan 0:b9164b348919 1250 * Set up a callback for when an attribute has its value updated by or at the
MrBedfordVan 0:b9164b348919 1251 * connected peer. For a peripheral, this callback is triggered when the local
MrBedfordVan 0:b9164b348919 1252 * GATT server has an attribute updated by a write command from the peer.
MrBedfordVan 0:b9164b348919 1253 * For a Central, this callback is triggered when a response is received for
MrBedfordVan 0:b9164b348919 1254 * a write request.
MrBedfordVan 0:b9164b348919 1255 *
MrBedfordVan 0:b9164b348919 1256 * @Note: It is possible to chain together multiple onDataWritten callbacks
MrBedfordVan 0:b9164b348919 1257 * (potentially from different modules of an application) to receive updates
MrBedfordVan 0:b9164b348919 1258 * to characteristics. Many services, such as DFU and UART, add their own
MrBedfordVan 0:b9164b348919 1259 * onDataWritten callbacks behind the scenes to trap interesting events.
MrBedfordVan 0:b9164b348919 1260 *
MrBedfordVan 0:b9164b348919 1261 * @Note: It is also possible to set up a callback into a member function of
MrBedfordVan 0:b9164b348919 1262 * some object.
MrBedfordVan 0:b9164b348919 1263 *
MrBedfordVan 0:b9164b348919 1264 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1265 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1266 * to ble.onDataWritten(...) should be replaced with
MrBedfordVan 0:b9164b348919 1267 * ble.gattServer().onDataWritten(...).
MrBedfordVan 0:b9164b348919 1268 */
MrBedfordVan 0:b9164b348919 1269 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
MrBedfordVan 0:b9164b348919 1270 gattServer().onDataWritten(callback);
MrBedfordVan 0:b9164b348919 1271 }
MrBedfordVan 0:b9164b348919 1272 template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
MrBedfordVan 0:b9164b348919 1273 gattServer().onDataWritten(objPtr, memberPtr);
MrBedfordVan 0:b9164b348919 1274 }
MrBedfordVan 0:b9164b348919 1275
MrBedfordVan 0:b9164b348919 1276 /**
MrBedfordVan 0:b9164b348919 1277 * Set up a callback to be invoked on the peripheral when an attribute is
MrBedfordVan 0:b9164b348919 1278 * being read by a remote client.
MrBedfordVan 0:b9164b348919 1279 *
MrBedfordVan 0:b9164b348919 1280 * @Note: This functionality may not be available on all underlying stacks.
MrBedfordVan 0:b9164b348919 1281 * You could use GattCharacteristic::setReadAuthorizationCallback() as an
MrBedfordVan 0:b9164b348919 1282 * alternative.
MrBedfordVan 0:b9164b348919 1283 *
MrBedfordVan 0:b9164b348919 1284 * @Note: It is possible to chain together multiple onDataRead callbacks
MrBedfordVan 0:b9164b348919 1285 * (potentially from different modules of an application) to receive updates
MrBedfordVan 0:b9164b348919 1286 * to characteristics. Services may add their own onDataRead callbacks
MrBedfordVan 0:b9164b348919 1287 * behind the scenes to trap interesting events.
MrBedfordVan 0:b9164b348919 1288 *
MrBedfordVan 0:b9164b348919 1289 * @Note: It is also possible to set up a callback into a member function of
MrBedfordVan 0:b9164b348919 1290 * some object.
MrBedfordVan 0:b9164b348919 1291 *
MrBedfordVan 0:b9164b348919 1292 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
MrBedfordVan 0:b9164b348919 1293 * else BLE_ERROR_NONE.
MrBedfordVan 0:b9164b348919 1294 *
MrBedfordVan 0:b9164b348919 1295 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1296 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1297 * to ble.onDataRead(...) should be replaced with
MrBedfordVan 0:b9164b348919 1298 * ble.gattServer().onDataRead(...).
MrBedfordVan 0:b9164b348919 1299 */
MrBedfordVan 0:b9164b348919 1300 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
MrBedfordVan 0:b9164b348919 1301 return gattServer().onDataRead(callback);
MrBedfordVan 0:b9164b348919 1302 }
MrBedfordVan 0:b9164b348919 1303 template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
MrBedfordVan 0:b9164b348919 1304 return gattServer().onDataRead(objPtr, memberPtr);
MrBedfordVan 0:b9164b348919 1305 }
MrBedfordVan 0:b9164b348919 1306
MrBedfordVan 0:b9164b348919 1307 /**
MrBedfordVan 0:b9164b348919 1308 * Set up a callback for when notifications or indications are enabled for a
MrBedfordVan 0:b9164b348919 1309 * characteristic on the local GattServer.
MrBedfordVan 0:b9164b348919 1310 *
MrBedfordVan 0:b9164b348919 1311 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1312 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1313 * to ble.onUpdatesEnabled(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1314 * ble.gattServer().onUpdatesEnabled(callback).
MrBedfordVan 0:b9164b348919 1315 */
MrBedfordVan 0:b9164b348919 1316 void onUpdatesEnabled(GattServer::EventCallback_t callback) {
MrBedfordVan 0:b9164b348919 1317 gattServer().onUpdatesEnabled(callback);
MrBedfordVan 0:b9164b348919 1318 }
MrBedfordVan 0:b9164b348919 1319
MrBedfordVan 0:b9164b348919 1320 /**
MrBedfordVan 0:b9164b348919 1321 * Set up a callback for when notifications or indications are disabled for a
MrBedfordVan 0:b9164b348919 1322 * characteristic on the local GattServer.
MrBedfordVan 0:b9164b348919 1323 *
MrBedfordVan 0:b9164b348919 1324 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1325 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1326 * to ble.onUpdatesEnabled(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1327 * ble.gattServer().onUpdatesEnabled(callback).
MrBedfordVan 0:b9164b348919 1328 */
MrBedfordVan 0:b9164b348919 1329 void onUpdatesDisabled(GattServer::EventCallback_t callback) {
MrBedfordVan 0:b9164b348919 1330 gattServer().onUpdatesDisabled(callback);
MrBedfordVan 0:b9164b348919 1331 }
MrBedfordVan 0:b9164b348919 1332
MrBedfordVan 0:b9164b348919 1333 /**
MrBedfordVan 0:b9164b348919 1334 * Set up a callback for when the GATT server receives a response for an
MrBedfordVan 0:b9164b348919 1335 * indication event sent previously.
MrBedfordVan 0:b9164b348919 1336 *
MrBedfordVan 0:b9164b348919 1337 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1338 * You should use the parallel API from GattServer directly. A former call
MrBedfordVan 0:b9164b348919 1339 * to ble.onConfirmationReceived(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1340 * ble.gattServer().onConfirmationReceived(callback).
MrBedfordVan 0:b9164b348919 1341 */
MrBedfordVan 0:b9164b348919 1342 void onConfirmationReceived(GattServer::EventCallback_t callback) {
MrBedfordVan 0:b9164b348919 1343 gattServer().onConfirmationReceived(callback);
MrBedfordVan 0:b9164b348919 1344 }
MrBedfordVan 0:b9164b348919 1345
MrBedfordVan 0:b9164b348919 1346 /**
MrBedfordVan 0:b9164b348919 1347 * Set up a callback for when the security setup procedure (key generation
MrBedfordVan 0:b9164b348919 1348 * and exchange) for a link has started. This will be skipped for bonded
MrBedfordVan 0:b9164b348919 1349 * devices. The callback is passed in parameters received from the peer's
MrBedfordVan 0:b9164b348919 1350 * security request: bool allowBonding, bool requireMITM, and
MrBedfordVan 0:b9164b348919 1351 * SecurityIOCapabilities_t.
MrBedfordVan 0:b9164b348919 1352 *
MrBedfordVan 0:b9164b348919 1353 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1354 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1355 * call to ble.onSecuritySetupInitiated(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1356 * ble.securityManager().onSecuritySetupInitiated(callback).
MrBedfordVan 0:b9164b348919 1357 */
MrBedfordVan 0:b9164b348919 1358 void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
MrBedfordVan 0:b9164b348919 1359 securityManager().onSecuritySetupInitiated(callback);
MrBedfordVan 0:b9164b348919 1360 }
MrBedfordVan 0:b9164b348919 1361
MrBedfordVan 0:b9164b348919 1362 /**
MrBedfordVan 0:b9164b348919 1363 * Set up a callback for when the security setup procedure (key generation
MrBedfordVan 0:b9164b348919 1364 * and exchange) for a link has completed. This will be skipped for bonded
MrBedfordVan 0:b9164b348919 1365 * devices. The callback is passed in the success/failure status of the
MrBedfordVan 0:b9164b348919 1366 * security setup procedure.
MrBedfordVan 0:b9164b348919 1367 *
MrBedfordVan 0:b9164b348919 1368 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1369 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1370 * call to ble.onSecuritySetupCompleted(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1371 * ble.securityManager().onSecuritySetupCompleted(callback).
MrBedfordVan 0:b9164b348919 1372 */
MrBedfordVan 0:b9164b348919 1373 void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
MrBedfordVan 0:b9164b348919 1374 securityManager().onSecuritySetupCompleted(callback);
MrBedfordVan 0:b9164b348919 1375 }
MrBedfordVan 0:b9164b348919 1376
MrBedfordVan 0:b9164b348919 1377 /**
MrBedfordVan 0:b9164b348919 1378 * Set up a callback for when a link with the peer is secured. For bonded
MrBedfordVan 0:b9164b348919 1379 * devices, subsequent reconnections with a bonded peer will result only in
MrBedfordVan 0:b9164b348919 1380 * this callback when the link is secured, and setup procedures will not
MrBedfordVan 0:b9164b348919 1381 * occur unless the bonding information is either lost or deleted on either
MrBedfordVan 0:b9164b348919 1382 * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
MrBedfordVan 0:b9164b348919 1383 * to the level of security in effect for the secured link.
MrBedfordVan 0:b9164b348919 1384 *
MrBedfordVan 0:b9164b348919 1385 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1386 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1387 * call to ble.onLinkSecured(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1388 * ble.securityManager().onLinkSecured(callback).
MrBedfordVan 0:b9164b348919 1389 */
MrBedfordVan 0:b9164b348919 1390 void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
MrBedfordVan 0:b9164b348919 1391 securityManager().onLinkSecured(callback);
MrBedfordVan 0:b9164b348919 1392 }
MrBedfordVan 0:b9164b348919 1393
MrBedfordVan 0:b9164b348919 1394 /**
MrBedfordVan 0:b9164b348919 1395 * Set up a callback for successful bonding, meaning that link-specific security
MrBedfordVan 0:b9164b348919 1396 * context is stored persistently for a peer device.
MrBedfordVan 0:b9164b348919 1397 *
MrBedfordVan 0:b9164b348919 1398 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1399 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1400 * call to ble.onSecurityContextStored(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1401 * ble.securityManager().onSecurityContextStored(callback).
MrBedfordVan 0:b9164b348919 1402 */
MrBedfordVan 0:b9164b348919 1403 void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
MrBedfordVan 0:b9164b348919 1404 securityManager().onSecurityContextStored(callback);
MrBedfordVan 0:b9164b348919 1405 }
MrBedfordVan 0:b9164b348919 1406
MrBedfordVan 0:b9164b348919 1407 /**
MrBedfordVan 0:b9164b348919 1408 * Set up a callback for when the passkey needs to be displayed on a
MrBedfordVan 0:b9164b348919 1409 * peripheral with DISPLAY capability. This happens when security is
MrBedfordVan 0:b9164b348919 1410 * configured to prevent Man-In-The-Middle attacks, and the peers need to exchange
MrBedfordVan 0:b9164b348919 1411 * a passkey (or PIN) to authenticate the connection
MrBedfordVan 0:b9164b348919 1412 * attempt.
MrBedfordVan 0:b9164b348919 1413 *
MrBedfordVan 0:b9164b348919 1414 * @note: This API is now *deprecated* and will be dropped in the future.
MrBedfordVan 0:b9164b348919 1415 * You should use the parallel API from SecurityManager directly. A former
MrBedfordVan 0:b9164b348919 1416 * call to ble.onPasskeyDisplay(callback) should be replaced with
MrBedfordVan 0:b9164b348919 1417 * ble.securityManager().onPasskeyDisplay(callback).
MrBedfordVan 0:b9164b348919 1418 */
MrBedfordVan 0:b9164b348919 1419 void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
MrBedfordVan 0:b9164b348919 1420 return securityManager().onPasskeyDisplay(callback);
MrBedfordVan 0:b9164b348919 1421 }
MrBedfordVan 0:b9164b348919 1422
MrBedfordVan 0:b9164b348919 1423 private:
MrBedfordVan 0:b9164b348919 1424 /**
MrBedfordVan 0:b9164b348919 1425 * Implementation of init() [internal to BLE_API].
MrBedfordVan 0:b9164b348919 1426 *
MrBedfordVan 0:b9164b348919 1427 * The implementation is separated into a private method because it isn't
MrBedfordVan 0:b9164b348919 1428 * suitable to be included in the header.
MrBedfordVan 0:b9164b348919 1429 */
MrBedfordVan 0:b9164b348919 1430 ble_error_t initImplementation(FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback);
MrBedfordVan 0:b9164b348919 1431
MrBedfordVan 0:b9164b348919 1432 private:
MrBedfordVan 0:b9164b348919 1433 BLE(const BLE&);
MrBedfordVan 0:b9164b348919 1434 BLE &operator=(const BLE &);
MrBedfordVan 0:b9164b348919 1435
MrBedfordVan 0:b9164b348919 1436 private:
MrBedfordVan 0:b9164b348919 1437 InstanceID_t instanceID;
MrBedfordVan 0:b9164b348919 1438 BLEInstanceBase *transport; /* The device-specific backend */
MrBedfordVan 0:b9164b348919 1439 };
MrBedfordVan 0:b9164b348919 1440
MrBedfordVan 0:b9164b348919 1441 typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
MrBedfordVan 0:b9164b348919 1442 * code. Will be dropped at some point soon.*/
MrBedfordVan 0:b9164b348919 1443
MrBedfordVan 0:b9164b348919 1444 #endif // ifndef __BLE_H__