Joshua Slater
/
BLE_API_Changed
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
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 Sat Jul 16 2022 17:07:02 by
1.7.2