Marco Ferreira / BLE_API

just a fork

Fork of BLE_API by Bluetooth Low Energy

ble/BLE.h@874:0607a58418ce, 2015-11-03 (annotated)

Committer:
rgrover1
Date:
Tue Nov 03 12:51:24 2015 +0000
Revision:
874:0607a58418ce
Parent:
861:2afa79e3ed0a
Child:
875:25480c83e3cc
Synchronized with git rev aa7e4b2d

Author: Rohit Grover

BLE::init() should also be able to take a <object,member> tuple.

Who changed what in which revision?

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