Andrew Fox / BLE_API

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 BLE_API by Bluetooth Low Energy

ble/BLE.h@1006:76ae9bbf173f, 2015-12-02 (annotated)

Committer:
rgrover1
Date:
Wed Dec 02 12:57:28 2015 +0000
Revision:
1006:76ae9bbf173f
Parent:
888:e43584ccdf03
Child:
1042:21a86ac7f5b1
Synchronized with git rev 12e27cd4

Author: Rohit Grover

Release 2.1.3

=============



* Improvements to CallChainOfFunctionPointerswithContext:

  - add a `detach` function to be able to remove callbacks.

  - detach function now return true if a function has been detached and

    false otherwise.

  - add a function call operator.

  - use safe-bool idiom. see : http://www.artima.com/cppsource/safebool.html



* Add SafeBool class which allow to easily declare a safe bool operator in

  c++03.



* Improvements to FunctionPointerWithContext:

  - fix call propagation

  - use safe bool idiom



* Add config file for generating Doxygen.



* Setup for onRadioNotification callback does not call initRadioNotification

  anymore.



* GapAdvertisementData now handles replacement and appending of data fields

  based on type. Some fields can be replaced with new values, and others

  require the payload to be appended.

Who changed what in which revision?

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