Joshua Slater
my version with changed conversion between duration units
Fork of
BLE_API
by 
Bluetooth Low Energy
Embed:
(wiki syntax)
Show/hide line numbers
BLE.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef __BLE_H__ 00018 #define __BLE_H__ 00019 00020 #include "blecommon.h" 00021 #include "Gap.h" 00022 #include "GattServer.h" 00023 #include "GattClient.h" 00024 #include "BLEInstanceBase.h" 00025 00026 /** 00027 * The base class used to abstract away BLE capable radio transceivers or SOCs, 00028 * to enable this BLE API to work with any radio transparently. 00029 */ 00030 class BLE 00031 { 00032 public: 00033 /** 00034 * Initialize the BLE controller. This should be called before using 00035 * anything else in the BLE_API. 00036 * 00037 * init() hands control to the underlying BLE module to accomplish 00038 * initialization. This initialization may tacitly depend on other hardware 00039 * setup (such as clocks or power-modes) which happens early on during 00040 * system startup. It may not be safe to call init() from global static 00041 * context where ordering is compiler specific and can't be guaranteed--it 00042 * is safe to call BLE::init() from within main(). 00043 */ 00044 ble_error_t init(); 00045 00046 /** 00047 * Purge the BLE stack of GATT and GAP state. init() must be called 00048 * afterwards to re-instate services and GAP state. This API offers a way to 00049 * repopulate the GATT database with new services and characteristics. 00050 */ 00051 ble_error_t shutdown(void) { 00052 clearAdvertisingPayload(); 00053 return transport->shutdown(); 00054 } 00055 00056 /** 00057 * This call allows the application to get the BLE stack version information. 00058 * 00059 * @return A pointer to a const string representing the version. 00060 * Note: The string is owned by the BLE_API. 00061 */ 00062 const char *getVersion(void) { 00063 return transport->getVersion(); 00064 } 00065 00066 /* 00067 * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires 00068 * going through this accessor. 00069 */ 00070 const Gap &gap() const { 00071 return transport->getGap(); 00072 } 00073 Gap &gap() { 00074 return transport->getGap(); 00075 } 00076 00077 /* 00078 * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related 00079 * functionality requires going through this accessor. 00080 */ 00081 const GattServer& gattServer() const { 00082 return transport->getGattServer(); 00083 } 00084 GattServer& gattServer() { 00085 return transport->getGattServer(); 00086 } 00087 00088 /* 00089 * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related 00090 * functionality requires going through this accessor. 00091 */ 00092 const GattClient& gattClient() const { 00093 return transport->getGattClient(); 00094 } 00095 GattClient& gattClient() { 00096 return transport->getGattClient(); 00097 } 00098 00099 /* 00100 * Accessors to Security Manager. Please refer to SecurityManager.h. All 00101 * SecurityManager related functionality requires going through this 00102 * accessor. 00103 */ 00104 const SecurityManager& securityManager() const { 00105 return transport->getSecurityManager(); 00106 } 00107 SecurityManager& securityManager() { 00108 return transport->getSecurityManager(); 00109 } 00110 00111 /** 00112 * Yield control to the BLE stack or to other tasks waiting for events. This 00113 * is a sleep function which will return when there is an application 00114 * specific interrupt, but the MCU might wake up several times before 00115 * returning (to service the stack). This is not always interchangeable with 00116 * WFE(). 00117 */ 00118 void waitForEvent(void) { 00119 transport->waitForEvent(); 00120 } 00121 00122 /* 00123 * Deprecation alert! 00124 * All of the following are deprecated and may be dropped in a future 00125 * release. Documentation should refer to alternative APIs. 00126 */ 00127 00128 /* GAP specific APIs. */ 00129 public: 00130 /** 00131 * Set the BTLE MAC address and type. 00132 * @return BLE_ERROR_NONE on success. 00133 * 00134 * @note: This API is now *deprecated* and will be dropped in the future. 00135 * You should use the parallel API from Gap directly. A former call to 00136 * ble.setAddress(...) should be replaced with 00137 * ble.gap().setAddress(...). 00138 */ 00139 ble_error_t setAddress(Gap::AddressType_t type, const Gap::Address_t address) { 00140 return gap().setAddress(type, address); 00141 } 00142 00143 /** 00144 * Fetch the BTLE MAC address and type. 00145 * @return BLE_ERROR_NONE on success. 00146 * 00147 * @note: This API is now *deprecated* and will be dropped in the future. 00148 * You should use the parallel API from Gap directly. A former call to 00149 * ble.getAddress(...) should be replaced with 00150 * ble.gap().getAddress(...). 00151 */ 00152 ble_error_t getAddress(Gap::AddressType_t *typeP, Gap::Address_t address) { 00153 return gap().getAddress(typeP, address); 00154 } 00155 00156 /** 00157 * Set the GAP advertising mode to use for this device. 00158 * 00159 * @note: This API is now *deprecated* and will be dropped in the future. 00160 * You should use the parallel API from Gap directly. A former call to 00161 * ble.setAdvertisingType(...) should be replaced with 00162 * ble.gap().setAdvertisingType(...). 00163 */ 00164 void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) { 00165 gap().setAdvertisingType(advType); 00166 } 00167 00168 /** 00169 * @param[in] interval 00170 * Advertising interval in units of milliseconds. Advertising 00171 * is disabled if interval is 0. If interval is smaller than 00172 * the minimum supported value, then the minimum supported 00173 * value is used instead. This minimum value can be discovered 00174 * using getMinAdvertisingInterval(). 00175 * 00176 * This field must be set to 0 if connectionMode is equal 00177 * to ADV_CONNECTABLE_DIRECTED. 00178 * 00179 * @note: Decreasing this value will allow central devices to detect a 00180 * peripheral faster at the expense of more power being used by the radio 00181 * due to the higher data transmit rate. 00182 * 00183 * @note: This API is now *deprecated* and will be dropped in the future. 00184 * You should use the parallel API from Gap directly. A former call to 00185 * ble.setAdvertisingInterval(...) should be replaced with 00186 * ble.gap().setAdvertisingInterval(...). 00187 * 00188 * @note: [WARNING] This API previously used 0.625ms as the unit for its 00189 * 'interval' argument. That required an explicit conversion from 00190 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is 00191 * no longer required as the new units are milliseconds. Any application 00192 * code depending on the old semantics would need to be updated accordingly. 00193 */ 00194 void setAdvertisingInterval (uint16_t interval) { 00195 gap().setAdvertisingInterval(interval); 00196 } 00197 00198 /** 00199 * @return Minimum Advertising interval in milliseconds. 00200 * 00201 * @note: This API is now *deprecated* and will be dropped in the future. 00202 * You should use the parallel API from Gap directly. A former call to 00203 * ble.getMinAdvertisingInterval(...) should be replaced with 00204 * ble.gap().getMinAdvertisingInterval(...). 00205 */ 00206 uint16_t getMinAdvertisingInterval (void) const { 00207 return gap().getMinAdvertisingInterval(); 00208 } 00209 00210 /** 00211 * @return Minimum Advertising interval in milliseconds for non-connectible mode. 00212 * 00213 * @note: This API is now *deprecated* and will be dropped in the future. 00214 * You should use the parallel API from Gap directly. A former call to 00215 * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with 00216 * ble.gap().getMinNonConnectableAdvertisingInterval(...). 00217 */ 00218 uint16_t getMinNonConnectableAdvertisingInterval (void) const { 00219 return gap().getMinNonConnectableAdvertisingInterval(); 00220 } 00221 00222 /** 00223 * @return Maximum Advertising interval in milliseconds. 00224 * 00225 * @note: This API is now *deprecated* and will be dropped in the future. 00226 * You should use the parallel API from Gap directly. A former call to 00227 * ble.getMaxAdvertisingInterval(...) should be replaced with 00228 * ble.gap().getMaxAdvertisingInterval(...). 00229 */ 00230 uint16_t getMaxAdvertisingInterval (void) const { 00231 return gap().getMaxAdvertisingInterval(); 00232 } 00233 00234 /** 00235 * @param[in] timeout 00236 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1 00237 * and 16383). Use 0 to disable the advertising timeout. 00238 * 00239 * @note: This API is now *deprecated* and will be dropped in the future. 00240 * You should use the parallel API from Gap directly. A former call to 00241 * ble.setAdvertisingTimeout(...) should be replaced with 00242 * ble.gap().setAdvertisingTimeout(...). 00243 */ 00244 void setAdvertisingTimeout (uint16_t timeout) { 00245 gap().setAdvertisingTimeout(timeout); 00246 } 00247 00248 /** 00249 * Setup a particular, user-constructed set of advertisement parameters for 00250 * the underlying stack. It would be uncommon for this API to be used 00251 * directly; there are other APIs to tweak advertisement parameters 00252 * individually (see above). 00253 * 00254 * @note: This API is now *deprecated* and will be dropped in the future. 00255 * You should use the parallel API from Gap directly. A former call to 00256 * ble.setAdvertisingParams(...) should be replaced with 00257 * ble.gap().setAdvertisingParams(...). 00258 */ 00259 void setAdvertisingParams(const GapAdvertisingParams &advParams) { 00260 gap().setAdvertisingParams(advParams); 00261 } 00262 00263 /** 00264 * @return Read back advertising parameters. Useful for storing and 00265 * restoring parameters rapidly. 00266 * 00267 * @note: This API is now *deprecated* and will be dropped in the future. 00268 * You should use the parallel API from Gap directly. A former call to 00269 * ble.getAdvertisingParams(...) should be replaced with 00270 * ble.gap().getAdvertisingParams(...). 00271 */ 00272 const GapAdvertisingParams &getAdvertisingParams (void) const { 00273 return gap().getAdvertisingParams(); 00274 } 00275 00276 /** 00277 * Accumulate an AD structure in the advertising payload. Please note that 00278 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00279 * as an additional 31 bytes if the advertising payload proves to be too 00280 * small. 00281 * 00282 * @param[in] flags 00283 * The flags to be added. Please refer to 00284 * GapAdvertisingData::Flags for valid flags. Multiple 00285 * flags may be specified in combination. 00286 * 00287 * @note: This API is now *deprecated* and will be dropped in the future. 00288 * You should use the parallel API from Gap directly. A former call to 00289 * ble.accumulateAdvertisingPayload(flags) should be replaced with 00290 * ble.gap().accumulateAdvertisingPayload(flags). 00291 */ 00292 ble_error_t accumulateAdvertisingPayload(uint8_t flags) { 00293 return gap().accumulateAdvertisingPayload(flags); 00294 } 00295 00296 /** 00297 * Accumulate an AD structure in the advertising payload. Please note that 00298 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00299 * as an additional 31 bytes if the advertising payload proves to be too 00300 * small. 00301 * 00302 * @param[in] app 00303 * The appearance of the peripheral. 00304 * 00305 * @note: This API is now *deprecated* and will be dropped in the future. 00306 * You should use the parallel API from Gap directly. A former call to 00307 * ble.accumulateAdvertisingPayload(appearance) should be replaced with 00308 * ble.gap().accumulateAdvertisingPayload(appearance). 00309 */ 00310 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) { 00311 return gap().accumulateAdvertisingPayload(app); 00312 } 00313 00314 /** 00315 * Accumulate an AD structure in the advertising payload. Please note that 00316 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used 00317 * as an additional 31 bytes if the advertising payload proves to be too 00318 * small. 00319 * 00320 * @param[in] app 00321 * The max transmit power to be used by the controller. This 00322 * is only a hint. 00323 * 00324 * @note: This API is now *deprecated* and will be dropped in the future. 00325 * You should use the parallel API from Gap directly. A former call to 00326 * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with 00327 * ble.gap().accumulateAdvertisingPayloadTxPower(txPower). 00328 */ 00329 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) { 00330 return gap().accumulateAdvertisingPayloadTxPower(power); 00331 } 00332 00333 /** 00334 * Accumulate a variable length byte-stream as an AD structure in the 00335 * advertising payload. Please note that the payload is limited to 31 bytes. 00336 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the 00337 * advertising payload proves to be too small. 00338 * 00339 * @param type The type which describes the variable length data. 00340 * @param data data bytes. 00341 * @param len length of data. 00342 * 00343 * @note: This API is now *deprecated* and will be dropped in the future. 00344 * You should use the parallel API from Gap directly. A former call to 00345 * ble.accumulateAdvertisingPayload(...) should be replaced with 00346 * ble.gap().accumulateAdvertisingPayload(...). 00347 */ 00348 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { 00349 return gap().accumulateAdvertisingPayload(type, data, len); 00350 } 00351 00352 /** 00353 * Setup a particular, user-constructed advertisement payload for the 00354 * underlying stack. It would be uncommon for this API to be used directly; 00355 * there are other APIs to build an advertisement payload (see above). 00356 * 00357 * @note: This API is now *deprecated* and will be dropped in the future. 00358 * You should use the parallel API from Gap directly. A former call to 00359 * ble.setAdvertisingData(...) should be replaced with 00360 * ble.gap().setAdvertisingPayload(...). 00361 */ 00362 ble_error_t setAdvertisingData(const GapAdvertisingData &advData) { 00363 return gap().setAdvertisingPayload(advData); 00364 } 00365 00366 /** 00367 * @return Read back advertising data. Useful for storing and 00368 * restoring payload. 00369 * 00370 * @note: This API is now *deprecated* and will be dropped in the future. 00371 * You should use the parallel API from Gap directly. A former call to 00372 * ble.getAdvertisingData(...) should be replaced with 00373 * ble.gap().getAdvertisingPayload()(...). 00374 */ 00375 const GapAdvertisingData &getAdvertisingData (void) const { 00376 return gap().getAdvertisingPayload(); 00377 } 00378 00379 /** 00380 * Reset any advertising payload prepared from prior calls to 00381 * accumulateAdvertisingPayload(). This automatically propagates the re- 00382 * initialized adv payload to the underlying stack. 00383 * 00384 * @note: This API is now *deprecated* and will be dropped in the future. 00385 * You should use the parallel API from Gap directly. A former call to 00386 * ble.clearAdvertisingPayload(...) should be replaced with 00387 * ble.gap().clearAdvertisingPayload(...). 00388 */ 00389 void clearAdvertisingPayload(void) { 00390 gap().clearAdvertisingPayload(); 00391 } 00392 00393 /** 00394 * This API is *deprecated* and resolves to a no-operation. It is left here 00395 * to allow older code to compile. Please avoid using this API in new code. 00396 * This API will be dropped in a future release. 00397 * 00398 * Formerly, it would be used to dynamically reset the accumulated advertising 00399 * payload and scanResponse; to do this, the application would clear and re- 00400 * accumulate a new advertising payload (and scanResponse) before using this 00401 * API. Updates to the underlying advertisement payload now happen 00402 * implicitly. 00403 */ 00404 ble_error_t setAdvertisingPayload(void) { 00405 return BLE_ERROR_NONE; 00406 } 00407 00408 /** 00409 * Accumulate a variable length byte-stream as an AD structure in the 00410 * scanResponse payload. 00411 * 00412 * @param[in] type The type which describes the variable length data. 00413 * @param[in] data data bytes. 00414 * @param[in] len length of data. 00415 * 00416 * @note: This API is now *deprecated* and will be dropped in the future. 00417 * You should use the parallel API from Gap directly. A former call to 00418 * ble.accumulateScanResponse(...) should be replaced with 00419 * ble.gap().accumulateScanResponse(...). 00420 */ 00421 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { 00422 return gap().accumulateScanResponse(type, data, len); 00423 } 00424 00425 /** 00426 * Reset any scan response prepared from prior calls to 00427 * accumulateScanResponse(). 00428 * 00429 * @note: This API is now *deprecated* and will be dropped in the future. 00430 * You should use the parallel API from Gap directly. A former call to 00431 * ble.clearScanResponse(...) should be replaced with 00432 * ble.gap().clearScanResponse(...). 00433 */ 00434 void clearScanResponse(void) { 00435 gap().clearScanResponse(); 00436 } 00437 00438 /** 00439 * Start advertising. 00440 * 00441 * @note: This API is now *deprecated* and will be dropped in the future. 00442 * You should use the parallel API from Gap directly. A former call to 00443 * ble.startAdvertising(...) should be replaced with 00444 * ble.gap().startAdvertising(...). 00445 */ 00446 ble_error_t startAdvertising(void) { 00447 return gap().startAdvertising(); 00448 } 00449 00450 /** 00451 * Stop advertising. 00452 * 00453 * @note: This API is now *deprecated* and will be dropped in the future. 00454 * You should use the parallel API from Gap directly. A former call to 00455 * ble.stopAdvertising(...) should be replaced with 00456 * ble.gap().stopAdvertising(...). 00457 */ 00458 ble_error_t stopAdvertising(void) { 00459 return gap().stopAdvertising(); 00460 } 00461 00462 /** 00463 * Setup parameters for GAP scanning--i.e. observer mode. 00464 * @param[in] interval 00465 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00466 * @param[in] window 00467 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00468 * @param[in] timeout 00469 * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout. 00470 * @param[in] activeScanning 00471 * Set to True if active-scanning is required. This is used to fetch the 00472 * scan response from a peer if possible. 00473 * 00474 * The scanning window divided by the interval determines the duty cycle for 00475 * scanning. For example, if the interval is 100ms and the window is 10ms, 00476 * then the controller will scan for 10 percent of the time. It is possible 00477 * to have the interval and window set to the same value. In this case, 00478 * scanning is continuous, with a change of scanning frequency once every 00479 * interval. 00480 * 00481 * Once the scanning parameters have been configured, scanning can be 00482 * enabled by using startScan(). 00483 * 00484 * @Note: The scan interval and window are recommendations to the BLE stack. 00485 * 00486 * @note: This API is now *deprecated* and will be dropped in the future. 00487 * You should use the parallel API from Gap directly. A former call to 00488 * ble.setScanParams(...) should be replaced with 00489 * ble.gap().setScanParams(...). 00490 */ 00491 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX, 00492 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX, 00493 uint16_t timeout = 0, 00494 bool activeScanning = false) { 00495 return gap().setScanParams(interval, window, timeout, activeScanning); 00496 } 00497 00498 /** 00499 * Setup the scanInterval parameter for GAP scanning--i.e. observer mode. 00500 * @param[in] interval 00501 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00502 * 00503 * The scanning window divided by the interval determines the duty cycle for 00504 * scanning. For example, if the interval is 100ms and the window is 10ms, 00505 * then the controller will scan for 10 percent of the time. It is possible 00506 * to have the interval and window set to the same value. In this case, 00507 * scanning is continuous, with a change of scanning frequency once every 00508 * interval. 00509 * 00510 * Once the scanning parameters have been configured, scanning can be 00511 * enabled by using startScan(). 00512 * 00513 * @note: This API is now *deprecated* and will be dropped in the future. 00514 * You should use the parallel API from Gap directly. A former call to 00515 * ble.setScanInterval(interval) should be replaced with 00516 * ble.gap().setScanInterval(interval). 00517 */ 00518 ble_error_t setScanInterval(uint16_t interval) { 00519 return gap().setScanInterval(interval); 00520 } 00521 00522 /** 00523 * Setup the scanWindow parameter for GAP scanning--i.e. observer mode. 00524 * @param[in] window 00525 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. 00526 * 00527 * The scanning window divided by the interval determines the duty cycle for 00528 * scanning. For example, if the interval is 100ms and the window is 10ms, 00529 * then the controller will scan for 10 percent of the time. It is possible 00530 * to have the interval and window set to the same value. In this case, 00531 * scanning is continuous, with a change of scanning frequency once every 00532 * interval. 00533 * 00534 * Once the scanning parameters have been configured, scanning can be 00535 * enabled by using startScan(). 00536 * 00537 * @note: This API is now *deprecated* and will be dropped in the future. 00538 * You should use the parallel API from Gap directly. A former call to 00539 * ble.setScanWindow(window) should be replaced with 00540 * ble.gap().setScanWindow(window). 00541 */ 00542 ble_error_t setScanWindow(uint16_t window) { 00543 return gap().setScanWindow(window); 00544 } 00545 00546 /** 00547 * Setup parameters for GAP scanning--i.e. observer mode. 00548 * @param[in] timeout 00549 * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout. 00550 * 00551 * The scanning window divided by the interval determines the duty cycle for 00552 * scanning. For example, if the interval is 100ms and the window is 10ms, 00553 * then the controller will scan for 10 percent of the time. It is possible 00554 * to have the interval and window set to the same value. In this case, 00555 * scanning is continuous, with a change of scanning frequency once every 00556 * interval. 00557 * 00558 * Once the scanning parameters have been configured, scanning can be 00559 * enabled by using startScan(). 00560 * 00561 * @Note: The scan interval and window are recommendations to the BLE stack. 00562 * 00563 * @note: This API is now *deprecated* and will be dropped in the future. 00564 * You should use the parallel API from Gap directly. A former call to 00565 * ble.setScanTimeout(...) should be replaced with 00566 * ble.gap().setScanTimeout(...). 00567 */ 00568 ble_error_t setScanTimeout(uint16_t timeout) { 00569 return gap().setScanTimeout(timeout); 00570 } 00571 00572 /** 00573 * Setup parameters for GAP scanning--i.e. observer mode. 00574 * @param[in] activeScanning 00575 * Set to True if active-scanning is required. This is used to fetch the 00576 * scan response from a peer if possible. 00577 * 00578 * Once the scanning parameters have been configured, scanning can be 00579 * enabled by using startScan(). 00580 * 00581 * @note: This API is now *deprecated* and will be dropped in the future. 00582 * You should use the parallel API from Gap directly. A former call to 00583 * ble.setActiveScan(...) should be replaced with 00584 * ble.gap().setActiveScanning(...). 00585 */ 00586 void setActiveScan(bool activeScanning) { 00587 gap().setActiveScanning(activeScanning); 00588 } 00589 00590 /** 00591 * Start scanning (Observer Procedure) based on the parameters currently in 00592 * effect. 00593 * 00594 * @param[in] callback 00595 * The application specific callback to be invoked upon 00596 * receiving every advertisement report. This can be passed in 00597 * as NULL, in which case scanning may not be enabled at all. 00598 * 00599 * @note: This API is now *deprecated* and will be dropped in the future. 00600 * You should use the parallel API from Gap directly. A former call to 00601 * ble.startScan(callback) should be replaced with 00602 * ble.gap().startScan(callback). 00603 */ 00604 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) { 00605 return gap().startScan(callback); 00606 } 00607 00608 /** 00609 * Same as above, but this takes an (object, method) pair for a callback. 00610 * 00611 * @note: This API is now *deprecated* and will be dropped in the future. 00612 * You should use the parallel API from Gap directly. A former call to 00613 * ble.startScan(callback) should be replaced with 00614 * ble.gap().startScan(object, callback). 00615 */ 00616 template<typename T> 00617 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params)); 00618 00619 /** 00620 * Stop scanning. The current scanning parameters remain in effect. 00621 * 00622 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure. 00623 * 00624 * @note: This API is now *deprecated* and will be dropped in the future. 00625 * You should use the parallel API from Gap directly. A former call to 00626 * ble.stopScan() should be replaced with 00627 * ble.gap().stopScan(). 00628 */ 00629 ble_error_t stopScan(void) { 00630 return gap().stopScan(); 00631 } 00632 00633 /** 00634 * Create a connection (GAP Link Establishment). 00635 * @param peerAddr 00636 * 48-bit address, LSB format. 00637 * @param peerAddrType 00638 * Address type of the peer. 00639 * @param connectionParams 00640 * Connection parameters. 00641 * @param scanParams 00642 * Paramters to be used while scanning for the peer. 00643 * @return BLE_ERROR_NONE if connection establishment procedure is started 00644 * successfully. The onConnection callback (if set) will be invoked upon 00645 * a connection event. 00646 * 00647 * @note: This API is now *deprecated* and will be dropped in the future. 00648 * You should use the parallel API from Gap directly. A former call to 00649 * ble.connect(...) should be replaced with 00650 * ble.gap().connect(...). 00651 */ 00652 ble_error_t connect(const Gap::Address_t peerAddr, 00653 Gap::AddressType_t peerAddrType = Gap::ADDR_TYPE_RANDOM_STATIC, 00654 const Gap::ConnectionParams_t *connectionParams = NULL, 00655 const GapScanningParams *scanParams = NULL) { 00656 return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams); 00657 } 00658 00659 /** 00660 * This call initiates the disconnection procedure, and its completion will 00661 * be communicated to the application with an invocation of the 00662 * onDisconnection callback. 00663 * 00664 * @param[in] connectionHandle 00665 * @param[in] reason 00666 * The reason for disconnection to be sent back to the peer. 00667 */ 00668 ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) { 00669 return gap().disconnect(connectionHandle, reason); 00670 } 00671 00672 /** 00673 * This call initiates the disconnection procedure, and its completion will 00674 * be communicated to the application with an invocation of the 00675 * onDisconnection callback. 00676 * 00677 * @param reason 00678 * The reason for disconnection to be sent back to the peer. 00679 * 00680 * @note: This API is now *deprecated* and will be dropped in the future. 00681 * You should use the parallel API from Gap directly. A former call to 00682 * ble.disconnect(reason) should be replaced with 00683 * ble.gap().disconnect(reason). 00684 * 00685 * @note: this version of disconnect() doesn't take a connection handle. It 00686 * will work reliably only for stacks which are limited to a single 00687 * connection. This API should be considered *deprecated* in favour of the 00688 * alternative which takes a connection handle. It will be dropped in the future. 00689 */ 00690 ble_error_t disconnect(Gap::DisconnectionReason_t reason) { 00691 return gap().disconnect(reason); 00692 } 00693 00694 /** 00695 * Returns the current GAP state of the device using a bitmask which 00696 * describes whether the device is advertising and/or connected. 00697 * 00698 * @note: This API is now *deprecated* and will be dropped in the future. 00699 * You should use the parallel API from Gap directly. A former call to 00700 * ble.getGapState() should be replaced with 00701 * ble.gap().getState(). 00702 */ 00703 Gap::GapState_t getGapState(void) const { 00704 return gap().getState(); 00705 } 00706 00707 /** 00708 * Get the GAP peripheral preferred connection parameters. These are the 00709 * defaults that the peripheral would like to have in a connection. The 00710 * choice of the connection parameters is eventually up to the central. 00711 * 00712 * @param[out] params 00713 * The structure where the parameters will be stored. Memory 00714 * for this is owned by the caller. 00715 * 00716 * @return BLE_ERROR_NONE if the parameters were successfully filled into 00717 * the given structure pointed to by params. 00718 * 00719 * @note: This API is now *deprecated* and will be dropped in the future. 00720 * You should use the parallel API from Gap directly. A former call to 00721 * ble.getPreferredConnectionParams() should be replaced with 00722 * ble.gap().getPreferredConnectionParams(). 00723 */ 00724 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) { 00725 return gap().getPreferredConnectionParams(params); 00726 } 00727 00728 /** 00729 * Set the GAP peripheral preferred connection parameters. These are the 00730 * defaults that the peripheral would like to have in a connection. The 00731 * choice of the connection parameters is eventually up to the central. 00732 * 00733 * @param[in] params 00734 * The structure containing the desired parameters. 00735 * 00736 * @note: This API is now *deprecated* and will be dropped in the future. 00737 * You should use the parallel API from Gap directly. A former call to 00738 * ble.setPreferredConnectionParams() should be replaced with 00739 * ble.gap().setPreferredConnectionParams(). 00740 */ 00741 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) { 00742 return gap().setPreferredConnectionParams(params); 00743 } 00744 00745 /** 00746 * Update connection parameters while in the peripheral role. 00747 * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for 00748 * the central to perform the procedure. 00749 * @param[in] handle 00750 * Connection Handle 00751 * @param[in] params 00752 * Pointer to desired connection parameters. If NULL is provided on a peripheral role, 00753 * the parameters in the PPCP characteristic of the GAP service will be used instead. 00754 * 00755 * @note: This API is now *deprecated* and will be dropped in the future. 00756 * You should use the parallel API from Gap directly. A former call to 00757 * ble.updateConnectionParams() should be replaced with 00758 * ble.gap().updateConnectionParams(). 00759 */ 00760 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) { 00761 return gap().updateConnectionParams(handle, params); 00762 } 00763 00764 /** 00765 * Set the device name characteristic in the GAP service. 00766 * @param[in] deviceName 00767 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string. 00768 * 00769 * @note: This API is now *deprecated* and will be dropped in the future. 00770 * You should use the parallel API from Gap directly. A former call to 00771 * ble.setDeviceName() should be replaced with 00772 * ble.gap().setDeviceName(). 00773 */ 00774 ble_error_t setDeviceName(const uint8_t *deviceName) { 00775 return gap().setDeviceName(deviceName); 00776 } 00777 00778 /** 00779 * Get the value of the device name characteristic in the GAP service. 00780 * @param[out] deviceName 00781 * Pointer to an empty buffer where the UTF-8 *non NULL- 00782 * terminated* string will be placed. Set this 00783 * value to NULL in order to obtain the deviceName-length 00784 * from the 'length' parameter. 00785 * 00786 * @param[in/out] lengthP 00787 * (on input) Length of the buffer pointed to by deviceName; 00788 * (on output) the complete device name length (without the 00789 * null terminator). 00790 * 00791 * @note If the device name is longer than the size of the supplied buffer, 00792 * length will return the complete device name length, and not the 00793 * number of bytes actually returned in deviceName. The application may 00794 * use this information to retry with a suitable buffer size. 00795 * 00796 * @note: This API is now *deprecated* and will be dropped in the future. 00797 * You should use the parallel API from Gap directly. A former call to 00798 * ble.getDeviceName() should be replaced with 00799 * ble.gap().getDeviceName(). 00800 */ 00801 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) { 00802 return gap().getDeviceName(deviceName, lengthP); 00803 } 00804 00805 /** 00806 * Set the appearance characteristic in the GAP service. 00807 * @param[in] appearance 00808 * The new value for the device-appearance. 00809 * 00810 * @note: This API is now *deprecated* and will be dropped in the future. 00811 * You should use the parallel API from Gap directly. A former call to 00812 * ble.setAppearance() should be replaced with 00813 * ble.gap().setAppearance(). 00814 */ 00815 ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) { 00816 return gap().setAppearance(appearance); 00817 } 00818 00819 /** 00820 * Get the appearance characteristic in the GAP service. 00821 * @param[out] appearance 00822 * The new value for the device-appearance. 00823 * 00824 * @note: This API is now *deprecated* and will be dropped in the future. 00825 * You should use the parallel API from Gap directly. A former call to 00826 * ble.getAppearance() should be replaced with 00827 * ble.gap().getAppearance(). 00828 */ 00829 ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) { 00830 return gap().getAppearance(appearanceP); 00831 } 00832 00833 /** 00834 * Set the radio's transmit power. 00835 * @param[in] txPower Radio transmit power in dBm. 00836 * 00837 * @note: This API is now *deprecated* and will be dropped in the future. 00838 * You should use the parallel API from Gap directly. A former call to 00839 * ble.setTxPower() should be replaced with 00840 * ble.gap().setTxPower(). 00841 */ 00842 ble_error_t setTxPower(int8_t txPower) { 00843 return gap().setTxPower(txPower); 00844 } 00845 00846 /** 00847 * Query the underlying stack for permitted arguments for setTxPower(). 00848 * 00849 * @param[out] valueArrayPP 00850 * Out parameter to receive the immutable array of Tx values. 00851 * @param[out] countP 00852 * Out parameter to receive the array's size. 00853 * 00854 * @note: This API is now *deprecated* and will be dropped in the future. 00855 * You should use the parallel API from Gap directly. A former call to 00856 * ble.getPermittedTxPowerValues() should be replaced with 00857 * ble.gap().getPermittedTxPowerValues(). 00858 */ 00859 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) { 00860 gap().getPermittedTxPowerValues(valueArrayPP, countP); 00861 } 00862 00863 /** 00864 * Add a service declaration to the local server ATT table. Also add the 00865 * characteristics contained within. 00866 * 00867 * @note: This API is now *deprecated* and will be dropped in the future. 00868 * You should use the parallel API from GattServer directly. A former call 00869 * to ble.addService() should be replaced with 00870 * ble.gattServer().addService(). 00871 */ 00872 ble_error_t addService(GattService &service) { 00873 return gattServer().addService(service); 00874 } 00875 00876 /** 00877 * Read the value of a characteristic from the local GattServer 00878 * @param[in] attributeHandle 00879 * Attribute handle for the value attribute of the characteristic. 00880 * @param[out] buffer 00881 * A buffer to hold the value being read. 00882 * @param[in/out] lengthP 00883 * Length of the buffer being supplied. If the attribute 00884 * value is longer than the size of the supplied buffer, 00885 * this variable will hold upon return the total attribute value length 00886 * (excluding offset). The application may use this 00887 * information to allocate a suitable buffer size. 00888 * 00889 * @return BLE_ERROR_NONE if a value was read successfully into the buffer. 00890 * 00891 * @note: This API is now *deprecated* and will be dropped in the future. 00892 * You should use the parallel API from GattServer directly. A former call 00893 * to ble.readCharacteristicValue() should be replaced with 00894 * ble.gattServer().read(). 00895 */ 00896 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { 00897 return gattServer().read(attributeHandle, buffer, lengthP); 00898 } 00899 00900 /** 00901 * Read the value of a characteristic from the local GattServer 00902 * @param[in] connectionHandle 00903 * Connection Handle. 00904 * @param[in] attributeHandle 00905 * Attribute handle for the value attribute of the characteristic. 00906 * @param[out] buffer 00907 * A buffer to hold the value being read. 00908 * @param[in/out] lengthP 00909 * Length of the buffer being supplied. If the attribute 00910 * value is longer than the size of the supplied buffer, 00911 * this variable will hold upon return the total attribute value length 00912 * (excluding offset). The application may use this 00913 * information to allocate a suitable buffer size. 00914 * 00915 * @return BLE_ERROR_NONE if a value was read successfully into the buffer. 00916 * 00917 * @note This API is a version of above with an additional connection handle 00918 * parameter to allow fetches for connection-specific multivalued 00919 * attributes (such as the CCCDs). 00920 * 00921 * @note: This API is now *deprecated* and will be dropped in the future. 00922 * You should use the parallel API from GattServer directly. A former call 00923 * to ble.readCharacteristicValue() should be replaced with 00924 * ble.gattServer().read(). 00925 */ 00926 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { 00927 return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP); 00928 } 00929 00930 /** 00931 * Update the value of a characteristic on the local GattServer. 00932 * 00933 * @param[in] attributeHandle 00934 * Handle for the value attribute of the Characteristic. 00935 * @param[in] value 00936 * A pointer to a buffer holding the new value 00937 * @param[in] size 00938 * Size of the new value (in bytes). 00939 * @param[in] localOnly 00940 * Should this update be kept on the local 00941 * GattServer regardless of the state of the 00942 * notify/indicate flag in the CCCD for this 00943 * Characteristic? If set to true, no notification 00944 * or indication is generated. 00945 * 00946 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. 00947 * 00948 * @note: This API is now *deprecated* and will be dropped in the future. 00949 * You should use the parallel API from GattServer directly. A former call 00950 * to ble.updateCharacteristicValue() should be replaced with 00951 * ble.gattServer().write(). 00952 */ 00953 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, 00954 const uint8_t *value, 00955 uint16_t size, 00956 bool localOnly = false) { 00957 return gattServer().write(attributeHandle, value, size, localOnly); 00958 } 00959 00960 /** 00961 * Update the value of a characteristic on the local GattServer. A version 00962 * of the same as above with connection handle parameter to allow updates 00963 * for connection-specific multivalued attributes (such as the CCCDs). 00964 * 00965 * @param[in] connectionHandle 00966 * Connection Handle. 00967 * @param[in] attributeHandle 00968 * Handle for the value attribute of the Characteristic. 00969 * @param[in] value 00970 * A pointer to a buffer holding the new value 00971 * @param[in] size 00972 * Size of the new value (in bytes). 00973 * @param[in] localOnly 00974 * Should this update be kept on the local 00975 * GattServer regardless of the state of the 00976 * notify/indicate flag in the CCCD for this 00977 * Characteristic? If set to true, no notification 00978 * or indication is generated. 00979 * 00980 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. 00981 * 00982 * @note: This API is now *deprecated* and will be dropped in the future. 00983 * You should use the parallel API from GattServer directly. A former call 00984 * to ble.updateCharacteristicValue() should be replaced with 00985 * ble.gattServer().write(). 00986 */ 00987 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle, 00988 GattAttribute::Handle_t attributeHandle, 00989 const uint8_t *value, 00990 uint16_t size, 00991 bool localOnly = false) { 00992 return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly); 00993 } 00994 00995 /** 00996 * Enable the BLE stack's Security Manager. The Security Manager implements 00997 * the actual cryptographic algorithms and protocol exchanges that allow two 00998 * devices to securely exchange data and privately detect each other. 00999 * Calling this API is a prerequisite for encryption and pairing (bonding). 01000 * 01001 * @param[in] enableBonding Allow for bonding. 01002 * @param[in] requireMITM Require protection for man-in-the-middle attacks. 01003 * @param[in] iocaps To specify IO capabilities of this peripheral, 01004 * such as availability of a display or keyboard to 01005 * support out-of-band exchanges of security data. 01006 * @param[in] passkey To specify a static passkey. 01007 * 01008 * @return BLE_ERROR_NONE on success. 01009 * 01010 * @note: This API is now *deprecated* and will be dropped in the future. 01011 * You should use the parallel API from SecurityManager directly. A former 01012 * call to ble.initializeSecurity(...) should be replaced with 01013 * ble.securityManager().init(...). 01014 */ 01015 ble_error_t initializeSecurity(bool enableBonding = true, 01016 bool requireMITM = true, 01017 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE, 01018 const SecurityManager::Passkey_t passkey = NULL) { 01019 return securityManager().init(enableBonding, requireMITM, iocaps, passkey); 01020 } 01021 01022 /** 01023 * Get the security status of a connection. 01024 * 01025 * @param[in] connectionHandle Handle to identify the connection. 01026 * @param[out] securityStatusP security status. 01027 * 01028 * @return BLE_SUCCESS Or appropriate error code indicating reason for failure. 01029 * 01030 * @note: This API is now *deprecated* and will be dropped in the future. 01031 * You should use the parallel API from SecurityManager directly. A former 01032 * call to ble.getLinkSecurity(...) should be replaced with 01033 * ble.securityManager().getLinkSecurity(...). 01034 */ 01035 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) { 01036 return securityManager().getLinkSecurity(connectionHandle, securityStatusP); 01037 } 01038 01039 /** 01040 * Delete all peer device context and all related bonding information from 01041 * the database within the security manager. 01042 * 01043 * @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure. 01044 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or 01045 * application registration. 01046 * 01047 * @note: This API is now *deprecated* and will be dropped in the future. 01048 * You should use the parallel API from SecurityManager directly. A former 01049 * call to ble.purgeAllBondingState() should be replaced with 01050 * ble.securityManager().purgeAllBondingState(). 01051 */ 01052 ble_error_t purgeAllBondingState(void) { 01053 return securityManager().purgeAllBondingState(); 01054 } 01055 01056 /** 01057 * Setup a callback for timeout events. Refer to Gap::TimeoutSource_t for 01058 * possible event types. 01059 * 01060 * @note: This API is now *deprecated* and will be dropped in the future. 01061 * You should use the parallel API from Gap directly. A former call 01062 * to ble.onTimeout(callback) should be replaced with 01063 * ble.gap().onTimeout(callback). 01064 */ 01065 void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) { 01066 gap().onTimeout(timeoutCallback); 01067 } 01068 01069 /** 01070 * Setup a callback for connection events. Refer to Gap::ConnectionEventCallback_t. 01071 * 01072 * @note: This API is now *deprecated* and will be dropped in the future. 01073 * You should use the parallel API from Gap directly. A former call 01074 * to ble.onConnection(callback) should be replaced with 01075 * ble.gap().onConnection(callback). 01076 */ 01077 void onConnection(Gap::ConnectionEventCallback_t connectionCallback) { 01078 gap().onConnection(connectionCallback); 01079 } 01080 01081 /** 01082 * Used to setup a callback for GAP disconnection. 01083 * 01084 * @note: This API is now *deprecated* and will be dropped in the future. 01085 * You should use the parallel API from Gap directly. A former call 01086 * to ble.onDisconnection(callback) should be replaced with 01087 * ble.gap().onDisconnection(callback). 01088 */ 01089 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) { 01090 gap().onDisconnection(disconnectionCallback); 01091 } 01092 01093 /** 01094 * Append to a chain of callbacks to be invoked upon disconnection; these 01095 * callbacks receive no context and are therefore different from the 01096 * onDisconnection callback. 01097 * 01098 * @note: This API is now *deprecated* and will be dropped in the future. 01099 * You should use the parallel API from Gap directly. A former call 01100 * to ble.addToDisconnectionCallchain(...) should be replaced with 01101 * ble.gap().addToDisconnectionCallchain(...). 01102 */ 01103 template<typename T> 01104 void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) { 01105 gap().addToDisconnectionCallChain(tptr, mptr); 01106 } 01107 01108 /** 01109 * Radio Notification is a feature that enables ACTIVE and INACTIVE 01110 * (nACTIVE) signals from the stack that notify the application when the 01111 * radio is in use. The signal is sent using software interrupt. 01112 * 01113 * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE 01114 * signal is sent at the end of the Radio Event. These signals can be used 01115 * by the application programmer to synchronize application logic with radio 01116 * activity. For example, the ACTIVE signal can be used to shut off external 01117 * devices to manage peak current drawn during periods when the radio is on, 01118 * or to trigger sensor data collection for transmission in the Radio Event. 01119 * 01120 * @param callback 01121 * The application handler to be invoked in response to a radio 01122 * ACTIVE/INACTIVE event. 01123 * 01124 * @note: This API is now *deprecated* and will be dropped in the future. 01125 * You should use the parallel API from Gap directly. A former call 01126 * to ble.onRadioNotification(...) should be replaced with 01127 * ble.gap().onRadioNotification(...). 01128 */ 01129 void onRadioNotification(void (*callback)(bool)) { 01130 gap().onRadioNotification(callback); 01131 } 01132 01133 /** 01134 * Add a callback for the GATT event DATA_SENT (which is triggered when 01135 * updates are sent out by GATT in the form of notifications). 01136 * 01137 * @Note: it is possible to chain together multiple onDataSent callbacks 01138 * (potentially from different modules of an application) to receive updates 01139 * to characteristics. 01140 * 01141 * @Note: it is also possible to setup a callback into a member function of 01142 * some object. 01143 * 01144 * @note: This API is now *deprecated* and will be dropped in the future. 01145 * You should use the parallel API from GattServer directly. A former call 01146 * to ble.onDataSent(...) should be replaced with 01147 * ble.gattServer().onDataSent(...). 01148 */ 01149 void onDataSent(void (*callback)(unsigned count)) { 01150 gattServer().onDataSent(callback); 01151 } 01152 template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) { 01153 gattServer().onDataSent(objPtr, memberPtr); 01154 } 01155 01156 /** 01157 * Setup a callback for when an attribute has its value updated by or at the 01158 * connected peer. For a peripheral, this callback triggered when the local 01159 * GATT server has an attribute updated by a write command from the peer. 01160 * For a Central, this callback is triggered when a response is received for 01161 * a write request. 01162 * 01163 * @Note: it is possible to chain together multiple onDataWritten callbacks 01164 * (potentially from different modules of an application) to receive updates 01165 * to characteristics. Many services, such as DFU and UART add their own 01166 * onDataWritten callbacks behind the scenes to trap interesting events. 01167 * 01168 * @Note: it is also possible to setup a callback into a member function of 01169 * some object. 01170 * 01171 * @note: This API is now *deprecated* and will be dropped in the future. 01172 * You should use the parallel API from GattServer directly. A former call 01173 * to ble.onDataWritten(...) should be replaced with 01174 * ble.gattServer().onDataWritten(...). 01175 */ 01176 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) { 01177 gattServer().onDataWritten(callback); 01178 } 01179 template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { 01180 gattServer().onDataWritten(objPtr, memberPtr); 01181 } 01182 01183 /** 01184 * Setup a callback to be invoked on the peripheral when an attribute is 01185 * being read by a remote client. 01186 * 01187 * @Note: this functionality may not be available on all underlying stacks. 01188 * You could use GattCharacteristic::setReadAuthorizationCallback() as an 01189 * alternative. 01190 * 01191 * @Note: it is possible to chain together multiple onDataRead callbacks 01192 * (potentially from different modules of an application) to receive updates 01193 * to characteristics. Services may add their own onDataRead callbacks 01194 * behind the scenes to trap interesting events. 01195 * 01196 * @Note: it is also possible to setup a callback into a member function of 01197 * some object. 01198 * 01199 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; 01200 * else BLE_ERROR_NONE. 01201 * 01202 * @note: This API is now *deprecated* and will be dropped in the future. 01203 * You should use the parallel API from GattServer directly. A former call 01204 * to ble.onDataRead(...) should be replaced with 01205 * ble.gattServer().onDataRead(...). 01206 */ 01207 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) { 01208 return gattServer().onDataRead(callback); 01209 } 01210 template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) { 01211 return gattServer().onDataRead(objPtr, memberPtr); 01212 } 01213 01214 /** 01215 * Setup a callback for when notifications/indications are enabled for a 01216 * characteristic on the local GattServer. 01217 * 01218 * @note: This API is now *deprecated* and will be dropped in the future. 01219 * You should use the parallel API from GattServer directly. A former call 01220 * to ble.onUpdatesEnabled(callback) should be replaced with 01221 * ble.gattServer().onUpdatesEnabled(callback). 01222 */ 01223 void onUpdatesEnabled(GattServer::EventCallback_t callback) { 01224 gattServer().onUpdatesEnabled(callback); 01225 } 01226 01227 /** 01228 * Setup a callback for when notifications/indications are disabled for a 01229 * characteristic on the local GattServer. 01230 * 01231 * @note: This API is now *deprecated* and will be dropped in the future. 01232 * You should use the parallel API from GattServer directly. A former call 01233 * to ble.onUpdatesEnabled(callback) should be replaced with 01234 * ble.gattServer().onUpdatesEnabled(callback). 01235 */ 01236 void onUpdatesDisabled(GattServer::EventCallback_t callback) { 01237 gattServer().onUpdatesDisabled(callback); 01238 } 01239 01240 /** 01241 * Setup a callback for when the GATT server receives a response for an 01242 * indication event sent previously. 01243 * 01244 * @note: This API is now *deprecated* and will be dropped in the future. 01245 * You should use the parallel API from GattServer directly. A former call 01246 * to ble.onConfirmationReceived(callback) should be replaced with 01247 * ble.gattServer().onConfirmationReceived(callback). 01248 */ 01249 void onConfirmationReceived(GattServer::EventCallback_t callback) { 01250 gattServer().onConfirmationReceived(callback); 01251 } 01252 01253 /** 01254 * Setup a callback for when the security setup procedure (key generation 01255 * and exchange) for a link has started. This will be skipped for bonded 01256 * devices. The callback is passed in parameters received from the peer's 01257 * security request: bool allowBonding, bool requireMITM, and 01258 * SecurityIOCapabilities_t. 01259 * 01260 * @note: This API is now *deprecated* and will be dropped in the future. 01261 * You should use the parallel API from SecurityManager directly. A former 01262 * call to ble.onSecuritySetupInitiated(callback) should be replaced with 01263 * ble.securityManager().onSecuritySetupInitiated(callback). 01264 */ 01265 void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) { 01266 securityManager().onSecuritySetupInitiated(callback); 01267 } 01268 01269 /** 01270 * Setup a callback for when the security setup procedure (key generation 01271 * and exchange) for a link has completed. This will be skipped for bonded 01272 * devices. The callback is passed in the success/failure status of the 01273 * security setup procedure. 01274 * 01275 * @note: This API is now *deprecated* and will be dropped in the future. 01276 * You should use the parallel API from SecurityManager directly. A former 01277 * call to ble.onSecuritySetupCompleted(callback) should be replaced with 01278 * ble.securityManager().onSecuritySetupCompleted(callback). 01279 */ 01280 void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) { 01281 securityManager().onSecuritySetupCompleted(callback); 01282 } 01283 01284 /** 01285 * Setup a callback for when a link with the peer is secured. For bonded 01286 * devices, subsequent reconnections with bonded peer will result only in 01287 * this callback when the link is secured and setup procedures will not 01288 * occur unless the bonding information is either lost or deleted on either 01289 * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according 01290 * to the level of security in effect for the secured link. 01291 * 01292 * @note: This API is now *deprecated* and will be dropped in the future. 01293 * You should use the parallel API from SecurityManager directly. A former 01294 * call to ble.onLinkSecured(callback) should be replaced with 01295 * ble.securityManager().onLinkSecured(callback). 01296 */ 01297 void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) { 01298 securityManager().onLinkSecured(callback); 01299 } 01300 01301 /** 01302 * Setup a callback for successful bonding; i.e. that link-specific security 01303 * context is stored persistently for a peer device. 01304 * 01305 * @note: This API is now *deprecated* and will be dropped in the future. 01306 * You should use the parallel API from SecurityManager directly. A former 01307 * call to ble.onSecurityContextStored(callback) should be replaced with 01308 * ble.securityManager().onSecurityContextStored(callback). 01309 */ 01310 void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) { 01311 securityManager().onSecurityContextStored(callback); 01312 } 01313 01314 /** 01315 * Setup a callback for when the passkey needs to be displayed on a 01316 * peripheral with DISPLAY capability. This happens when security is 01317 * configured to prevent Man-In-The-Middle attacks, and a PIN (or passkey) 01318 * needs to be exchanged between the peers to authenticate the connection 01319 * attempt. 01320 * 01321 * @note: This API is now *deprecated* and will be dropped in the future. 01322 * You should use the parallel API from SecurityManager directly. A former 01323 * call to ble.onPasskeyDisplay(callback) should be replaced with 01324 * ble.securityManager().onPasskeyDisplay(callback). 01325 */ 01326 void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) { 01327 return securityManager().onPasskeyDisplay(callback); 01328 } 01329 01330 public: 01331 BLE() : transport(createBLEInstance()) { 01332 /* empty */ 01333 } 01334 01335 private: 01336 BLEInstanceBase *const transport; /* the device specific backend */ 01337 }; 01338 01339 typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older 01340 * code. Will be dropped at some point soon.*/ 01341 01342 #endif // ifndef __BLE_H__
Generated on Wed Jul 13 2022 18:08:30 by
1.7.2