Greg Steiert / maxim_dev

Dependents:   sensomed

features/FEATURE_BLE/ble/BLE.h@0:0e018d759a2a, 2016-11-08 (annotated)

Committer:
switches
Date:
Tue Nov 08 18:27:11 2016 +0000
Revision:
0:0e018d759a2a
Initial commit

Who changed what in which revision?

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