Varun Bahl / BahlDecrypModified

Updated

Fork of BLE_API by Bluetooth Low Energy

ble/BLE.h@1131:692ddf04fc42, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:13:46 2016 +0100
Revision:
1131:692ddf04fc42
Parent:
1119:7a487d506451
Child:
1135:22aada733dbd
Synchronized with git rev 13bf70b6

Author: Rohit Grover

Release 2.1.5

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



A minor release to separate the concept of minlen and len in

GattCharacteristic. Also contains some improvements to documentation.

Who changed what in which revision?

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