Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

public/BLE.h@539:0b6e82025358, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:08 2015 +0100
Revision:
539:0b6e82025358
Parent:
538:fff02872b62f
Child:
540:1fb1e0b809eb
Synchronized with git rev 5b76b4ae

Author: Rohit Grover

GattServer: readValue()->read(), updateValue()->write()

Who changed what in which revision?

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