Lee Kai Xuan / mbed-os

Important changes to repositories hosted on mbed.com

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

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

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

Fork of mbed-os by erkin yucel

features/FEATURE_BLE/ble/BLE.h@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

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