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